{ "schema_version": 2, "meta": { "build_id": "CODEX-INSTALL-CHATGPT-CODEX", "slug": "install-chatgpt-codex", "title": "Install ChatGPT Codex", "subtitle": "Install, sign in, make one bounded change, and prove it works.", "description": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "one_sentence_description": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "target_user": "A motivated beginner with permission to work in a private practice folder.", "skill_level": "beginner", "estimated_time": "90–150 minutes", "category": "Guided Build", "tags": [ "install-chatgpt-codex", "verified practice", "chatgpt_codex" ], "prerequisites": [ "Permission to use a dedicated workspace", "A browser and terminal", "Read each platform-specific prerequisite before installation" ], "required_accounts": [ "An eligible account for the selected tool; sign in personally." ], "required_software": [ "Modern browser", "Python 3.10+ for downloadable drills" ], "required_hardware": [ "A computer with space for the practice files", "Second drive for the disaster-recovery checkpoint" ], "expected_cost": "Free practice; existing tool accounts may have plan limits.", "final_outcome": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "platforms": [ "windows", "macos", "linux" ], "version": 13, "author": "chatgpt_codex", "source_checked": "2026-10-16", "verification_status": "Created; automated browser and project checks recorded separately. Live account/OS verification is never inferred from browser completion." }, "user_outcome": { "before": "The learner has no reproducible, checked workflow for install chatgpt codex.", "after": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "finished_product": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path." }, "learning_objectives": [ "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "The required runtime and shell are available; the directory is the extracted practice workspace.", "The codex version command exits successfully and prints a version.", "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "The effective configuration and permission mode are recorded; unexpected writes need review." ], "lessons": [ { "lesson_id": "L01", "title": "Choose the right product and account", "purpose": "On Windows use the supported native installation or WSL consistently; files and sign-ins differ between the two environments. The npm route requires a supported Node.js runtime; use current Node.js LTS and verify package engines.", "estimated_time": "6 min", "learning_objective": "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "lessons_before_this": [], "lessons_after_this": [ "L02" ] }, { "lesson_id": "L02", "title": "Prepare a clean workspace", "purpose": "A dedicated folder makes mistakes easy to diagnose and keeps real project files separate.", "estimated_time": "12 min", "learning_objective": "The required runtime and shell are available; the directory is the extracted practice workspace.", "lessons_before_this": [ "L01" ], "lessons_after_this": [ "L03" ] }, { "lesson_id": "L03", "title": "Install and locate the command", "purpose": "The codex version command exits successfully and prints a version.", "estimated_time": "6 min", "learning_objective": "The codex version command exits successfully and prints a version.", "lessons_before_this": [ "L02" ], "lessons_after_this": [ "L04" ] }, { "lesson_id": "L04", "title": "Sign in personally", "purpose": "The user performs identity verification. A version command proves installation only, not account eligibility.", "estimated_time": "6 min", "learning_objective": "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "lessons_before_this": [ "L03" ], "lessons_after_this": [ "L05" ] }, { "lesson_id": "L05", "title": "Give the agent rules and context", "purpose": "Rules are discoverable context, not an enforced deletion boundary. Inspect the tool’s effective permissions separately.", "estimated_time": "6 min", "learning_objective": "The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "lessons_before_this": [ "L04" ], "lessons_after_this": [ "L06" ] }, { "lesson_id": "L06", "title": "Make the first verified change", "purpose": "Independent verification gives you evidence beyond the agent’s report.", "estimated_time": "12 min", "learning_objective": "The effective configuration and permission mode are recorded; unexpected writes need review.", "lessons_before_this": [ "L05" ], "lessons_after_this": [ "L07" ] }, { "lesson_id": "L07", "title": "Use headless mode without surprise writes", "purpose": "Interactive sessions and scripted sessions share tool/account capabilities. A read-only task is a small first automation test.", "estimated_time": "6 min", "learning_objective": "The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "lessons_before_this": [ "L06" ], "lessons_after_this": [ "L08" ] }, { "lesson_id": "L08", "title": "Connect tools deliberately", "purpose": "MCP is a protocol for exposing tools. An extra directory or server can expand what the agent can access; start with the smallest scope.", "estimated_time": "6 min", "learning_objective": "One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "lessons_before_this": [ "L07" ], "lessons_after_this": [ "L09" ] }, { "lesson_id": "L09", "title": "Diagnose failure with evidence", "purpose": "If the tool times out, collect the provider status, CLI version and a bounded reproducer. Do not raise heap/memory limits or disable proxies without evidence.", "estimated_time": "6 min", "learning_objective": "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "lessons_before_this": [ "L08" ], "lessons_after_this": [ "L10" ] }, { "lesson_id": "L10", "title": "Build Bot Better — protect and recover", "purpose": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "estimated_time": "30 min", "learning_objective": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "lessons_before_this": [ "L09" ], "lessons_after_this": [ "L11" ] }, { "lesson_id": "L11", "title": "Run it later — everyday launch", "purpose": "A repeatable launch keeps everyday work tied to the intended folder, account and rules. Authentication/configuration live in ~/.codex (Windows: %USERPROFILE%\\.codex). Do not copy credentials into the project.", "estimated_time": "6 min", "learning_objective": "The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "lessons_before_this": [ "L10" ], "lessons_after_this": [] } ], "steps": [ { "title": "Confirm the product and access", "purpose": "This step helps you confirm the product and access. The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "user_action": "Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing.", "explanation": "This step helps you confirm the product and access. The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "resources": [], "checkpoint": { "what_is_being_checked": "Confirm the product and access", "success_condition": "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "how_to_verify": "Record the observed result for Confirm the product and access. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Confirm the product and access?", "fix": "For Confirm the product and access: Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing. Compare the actual output to The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": { "question": "What is the role of the installed CLI?", "answer_type": "single_choice", "choices": [ "It is an agent harness that uses a model through an authenticated provider.", "It is automatically a free local model download." ], "correct_answer": 0, "explanation": "Installing an agent and having provider/model access are separate checks." }, "coach": { "intro": "We are going to confirm the product and access. The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "demo": "Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Confirm the product and access, compare your own result with: The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.. Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing." }, "video": { "purpose": "Demonstrate confirm the product and access", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing. The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course.", "on_screen_text": [ "Confirm the product and access", "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course." ], "screen_recording_instructions": [ "Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing.", "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Open the linked official source. Verify the product name Codex, your OS/architecture, and the account option available to you. Record the path you will use before installing.", "The product, platform and eligible sign-in route are recorded; no plan upgrade is required by this course." ] }, "step_id": "L01-S01", "lesson_id": "L01" }, { "title": "Set up the practice folder", "purpose": "This step helps you set up the practice folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "user_action": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "explanation": "This step helps you set up the practice folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "python --version\nGet-Location\nGet-ChildItem", "macos": "python3 --version\npwd\nls", "linux": "python3 --version\npwd\nls" }, "command_type": "shell", "required_inputs": [], "expected_result": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "resources": [], "checkpoint": { "what_is_being_checked": "Set up the practice folder", "success_condition": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "how_to_verify": "Record the observed result for Set up the practice folder. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "Python is 3.10 or newer.", "The listed files match the downloaded resources." ], "tokens": [], "user_visible_success_message": "Evidence saved. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "Python or a file is not found", "likely_cause": "The terminal may be outside the extracted ZIP or Python may not be on PATH.", "diagnostic_question": "What exact result did you observe during Set up the practice folder?", "fix": "For Set up the practice folder: Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder. Compare the actual output to Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "alternative_fix": "Use py -3 on Windows if the Python launcher is installed. macOS/Linux commands use python3.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Install Python from python.org with the PATH option; reopen the terminal and change into the extracted folder." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": null, "coach": { "intro": "We are going to set up the practice folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "demo": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Install Python from python.org with the PATH option; reopen the terminal and change into the extracted folder.", "help": "For Set up the practice folder, compare your own result with: Python reports version 3.10 or newer and the terminal is in the extracted resource folder.. Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder." }, "video": { "purpose": "Demonstrate set up the practice folder", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder. Python reports version 3.10 or newer and the terminal is in the extracted resource folder.", "on_screen_text": [ "Set up the practice folder", "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ], "screen_recording_instructions": [ "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Download the resource ZIP at the top of this Build. Extract it into a new folder you own (for example C:\\BBBPractice on Windows, or ~/bbb-practice on macOS/Linux). Open a terminal in the extracted folder. Run the version command for your platform. All subsequent commands assume this folder.", "Python reports version 3.10 or newer and the terminal is in the extracted resource folder." ] }, "step_id": "L02-S01", "lesson_id": "L02" }, { "title": "Check installation prerequisites", "purpose": "This step helps you check installation prerequisites. The required runtime and shell are available; the directory is the extracted practice workspace.", "user_action": "For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm installation route needs Node.js; use the native installer below when you do not have Node. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell.", "explanation": "This step helps you check installation prerequisites. The required runtime and shell are available; the directory is the extracted practice workspace. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "node --version\nnpm.cmd --version\nGet-Location", "macos": "node --version\nnpm --version\npwd\ncommand -v curl", "linux": "node --version\nnpm --version\npwd\ncommand -v curl" }, "command_type": "shell", "required_inputs": [], "expected_result": "The required runtime and shell are available; the directory is the extracted practice workspace.", "resources": [], "checkpoint": { "what_is_being_checked": "Check installation prerequisites", "success_condition": "The required runtime and shell are available; the directory is the extracted practice workspace.", "how_to_verify": "Record the observed result for Check installation prerequisites. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The required runtime and shell are available; the directory is the extracted practice workspace.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The required runtime and shell are available; the directory is the extracted practice workspace.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "Runtime or curl is missing", "likely_cause": "A clean machine may not include Node.js or curl.", "diagnostic_question": "What exact result did you observe during Check installation prerequisites?", "fix": "For Check installation prerequisites: For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm route needs Node.js; the native installer has separate platform prerequisites. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell. Compare the actual output to The required runtime and shell are available; the directory is the extracted practice workspace.", "alternative_fix": "Use the officially supported native/standalone distribution when available; reopen the terminal after installation.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Install Node.js LTS from its official distribution for npm. On Ubuntu for a shell installer, run sudo apt update then sudo apt install curl ca-certificates." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The required runtime and shell are available; the directory is the extracted practice workspace." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": null, "coach": { "intro": "We are going to check installation prerequisites. The required runtime and shell are available; the directory is the extracted practice workspace.", "demo": "For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm route needs Node.js; the native installer has separate platform prerequisites. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Install Node.js LTS from its official distribution for npm. On Ubuntu for a shell installer, run sudo apt update then sudo apt install curl ca-certificates.", "help": "For Check installation prerequisites, compare your own result with: The required runtime and shell are available; the directory is the extracted practice workspace.. For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm route needs Node.js; the native installer has separate platform prerequisites. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell." }, "video": { "purpose": "Demonstrate check installation prerequisites", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm route needs Node.js; the native installer has separate platform prerequisites. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell. The required runtime and shell are available; the directory is the extracted practice workspace.", "on_screen_text": [ "Check installation prerequisites", "The required runtime and shell are available; the directory is the extracted practice workspace." ], "screen_recording_instructions": [ "For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm installation route needs Node.js; use the native installer below when you do not have Node. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell.", "The required runtime and shell are available; the directory is the extracted practice workspace." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The required runtime and shell are available; the directory is the extracted practice workspace." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "For an npm route, install a current Node.js LTS from nodejs.org first. Run node --version and npm --version. The optional npm route needs Node.js; the native installer has separate platform prerequisites. For a native installer, verify the shell and curl (macOS/Linux), and check the official platform prerequisites. Do not run a macOS/Linux script directly in native PowerShell.", "The required runtime and shell are available; the directory is the extracted practice workspace." ] }, "step_id": "L02-S02", "lesson_id": "L02" }, { "title": "Install Codex", "purpose": "This step helps you install Codex. The codex version command exits successfully and prints a version.", "user_action": "Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it.", "explanation": "This step helps you install Codex. The codex version command exits successfully and prints a version. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "# Official native installer; inspect the downloaded script before running it.\npowershell -ExecutionPolicy ByPass -c \"irm https://chatgpt.com/codex/install.ps1 | iex\"\ncodex --version", "macos": "npm install -g @openai/codex@latest\ncodex --version", "linux": "npm install -g @openai/codex@latest\ncodex --version" }, "command_type": "shell", "required_inputs": [ "AGENTS.md" ], "expected_result": "The codex version command exits successfully and prints a version.", "resources": [ "AGENTS.md" ], "checkpoint": { "what_is_being_checked": "Install Codex", "success_condition": "The codex version command exits successfully and prints a version.", "how_to_verify": "Record the observed result for Install Codex. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The codex version command exits successfully and prints a version.", "I can repeat this action from the saved input." ], "tokens": [ "codex-cli" ], "user_visible_success_message": "Evidence saved. The codex version command exits successfully and prints a version.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true, "version_output": true }, "troubleshooting": [ { "problem": "The command is not recognized or PowerShell blocks npm.ps1", "likely_cause": "The new binary directory may not be on PATH, or the npm PowerShell shim is restricted.", "diagnostic_question": "What exact result did you observe during Install Codex?", "fix": "For Install Codex: Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it. Compare the actual output to The codex version command exits successfully and prints a version.", "alternative_fix": "Use the official native installer; ask the administrator to fix a managed machine policy rather than disabling it globally.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Reopen the terminal. For npm on Windows, use npm.cmd and codex.cmd to avoid the PowerShell script shim; inspect npm prefix -g." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The codex version command exits successfully and prints a version." }, { "question": "Which files support this action?", "answer": "Use AGENTS.md." } ], "quiz": null, "coach": { "intro": "We are going to install Codex. The codex version command exits successfully and prints a version.", "demo": "Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Reopen the terminal. For npm on Windows, use npm.cmd and codex.cmd to avoid the PowerShell script shim; inspect npm prefix -g.", "help": "For Install Codex, compare your own result with: The codex version command exits successfully and prints a version.. Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it." }, "video": { "purpose": "Demonstrate install codex", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it. The codex version command exits successfully and prints a version.", "on_screen_text": [ "Install Codex", "The codex version command exits successfully and prints a version." ], "screen_recording_instructions": [ "Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it.", "The codex version command exits successfully and prints a version." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The codex version command exits successfully and prints a version." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Inspect the installer source or package publisher on the official page, then execute the command card for your platform. Reopen the terminal if PATH changed. Save the version output; do not run elevated npm unless the official package specifically requires it.", "The codex version command exits successfully and prints a version." ] }, "step_id": "L03-S01", "lesson_id": "L03" }, { "title": "Complete the account sign-in", "purpose": "This step helps you complete the account sign-in. The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "user_action": "Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project.", "explanation": "This step helps you complete the account sign-in. The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "codex.cmd", "macos": "codex", "linux": "codex" }, "command_type": "shell", "required_inputs": [], "expected_result": "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "resources": [], "checkpoint": { "what_is_being_checked": "Complete the account sign-in", "success_condition": "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "how_to_verify": "Record the observed result for Complete the account sign-in. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The CLI identifies the intended account/session.", "A read-only prompt is accepted.", "Evidence contains no authorization codes, tokens or passwords." ], "tokens": [], "user_visible_success_message": "Evidence saved. The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "Sign-in or eligibility fails", "likely_cause": "The account, browser redirect or organization policy may not permit this tool.", "diagnostic_question": "What exact result did you observe during Complete the account sign-in?", "fix": "For Complete the account sign-in: Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project. Compare the actual output to The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "alternative_fix": "Continue the offline resource exercises while account access is resolved; do not represent them as authenticated agent execution.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Complete the login in the correct account/browser profile and retry once. Stop if organization access or eligibility needs a human decision." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": null, "coach": { "intro": "We are going to complete the account sign-in. The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "demo": "Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Complete the login in the correct account/browser profile and retry once. Stop if organization access or eligibility needs a human decision.", "help": "For Complete the account sign-in, compare your own result with: The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.. Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project." }, "video": { "purpose": "Demonstrate complete the account sign-in", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project. The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files.", "on_screen_text": [ "Complete the account sign-in", "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files." ], "screen_recording_instructions": [ "Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project.", "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run codex in the practice folder. Choose Sign in with ChatGPT and finish the browser flow yourself. Confirm the account and available model in /status. Do not paste tokens into a project.", "The CLI is authenticated to your own account and accepts an interactive prompt; no credential is stored in the practice files." ] }, "step_id": "L04-S01", "lesson_id": "L04" }, { "title": "Verify the rules are read", "purpose": "This step helps you verify the rules are read. The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "user_action": "Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify.", "explanation": "This step helps you verify the rules are read. The agent names AGENTS.md, the practice path, the bounded scope and the verification command. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "create", "commands": { "all": "Read AGENTS.md and app.py. Summarize your permitted workspace, prohibited actions and the verification command. Do not change anything." }, "command_type": "prompt", "required_inputs": [ "AGENTS.md", "app.py", "verify.py" ], "expected_result": "The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "resources": [ "AGENTS.md", "app.py", "verify.py" ], "checkpoint": { "what_is_being_checked": "Verify the rules are read", "success_condition": "The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "how_to_verify": "Record the observed result for Verify the rules are read. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Verify the rules are read?", "fix": "For Verify the rules are read: Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify. Compare the actual output to The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The agent names AGENTS.md, the practice path, the bounded scope and the verification command." }, { "question": "Which files support this action?", "answer": "Use AGENTS.md, app.py, verify.py." } ], "quiz": null, "coach": { "intro": "We are going to verify the rules are read. The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "demo": "Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Verify the rules are read, compare your own result with: The agent names AGENTS.md, the practice path, the bounded scope and the verification command.. Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify." }, "video": { "purpose": "Demonstrate verify the rules are read", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify. The agent names AGENTS.md, the practice path, the bounded scope and the verification command.", "on_screen_text": [ "Verify the rules are read", "The agent names AGENTS.md, the practice path, the bounded scope and the verification command." ], "screen_recording_instructions": [ "Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify.", "The agent names AGENTS.md, the practice path, the bounded scope and the verification command." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The agent names AGENTS.md, the practice path, the bounded scope and the verification command." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Open AGENTS.md in the resource folder and replace the workspace sentence with your real path. Start codex there. Ask the agent to list its rules, summarize app.py and say which files it may modify.", "The agent names AGENTS.md, the practice path, the bounded scope and the verification command." ] }, "step_id": "L05-S01", "lesson_id": "L05" }, { "title": "Delegate one small change", "purpose": "This step helps you delegate one small change. VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "user_action": "Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently.", "explanation": "This step helps you delegate one small change. VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "python verify.py", "macos": "python3 verify.py", "linux": "python3 verify.py" }, "command_type": "shell", "required_inputs": [ "app.py", "verify.py", "delegation.md" ], "expected_result": "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "resources": [ "app.py", "verify.py", "delegation.md" ], "checkpoint": { "what_is_being_checked": "Delegate one small change", "success_condition": "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "how_to_verify": "Record the observed result for Delegate one small change. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Delegate one small change?", "fix": "For Delegate one small change: Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently. Compare the actual output to VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed." }, { "question": "Which files support this action?", "answer": "Use app.py, verify.py, delegation.md." } ], "quiz": null, "coach": { "intro": "We are going to delegate one small change. VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "demo": "Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Delegate one small change, compare your own result with: VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.. Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently." }, "video": { "purpose": "Demonstrate delegate one small change", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently. VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed.", "on_screen_text": [ "Delegate one small change", "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed." ], "screen_recording_instructions": [ "Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently.", "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Ask Codex to add a docstring to total in app.py, keeping behavior unchanged. Require the agent to run verify.py and show the minimal diff. Review that only app.py changed, then run the command independently.", "VERIFY PASS covers empty, ordinary, signed and repeated inputs; only the requested docstring changed." ] }, "step_id": "L06-S01", "lesson_id": "L06" }, { "title": "Inspect configuration and approval modes", "purpose": "This step helps you inspect configuration and approval modes. The effective configuration and permission mode are recorded; unexpected writes need review.", "user_action": "Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply.", "explanation": "This step helps you inspect configuration and approval modes. The effective configuration and permission mode are recorded; unexpected writes need review. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "codex.cmd doctor\ncodex.cmd --help", "macos": "codex doctor\ncodex --help", "linux": "codex doctor\ncodex --help" }, "command_type": "shell", "required_inputs": [], "expected_result": "The effective configuration and permission mode are recorded; unexpected writes need review.", "resources": [], "checkpoint": { "what_is_being_checked": "Inspect configuration and approval modes", "success_condition": "The effective configuration and permission mode are recorded; unexpected writes need review.", "how_to_verify": "Record the observed result for Inspect configuration and approval modes. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The effective configuration and permission mode are recorded; unexpected writes need review.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The effective configuration and permission mode are recorded; unexpected writes need review.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Inspect configuration and approval modes?", "fix": "For Inspect configuration and approval modes: Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply. Compare the actual output to The effective configuration and permission mode are recorded; unexpected writes need review.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The effective configuration and permission mode are recorded; unexpected writes need review." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": { "question": "A prompt says “do not delete profiles.” What does that establish?", "answer_type": "single_choice", "choices": [ "An instruction; verify a real active boundary separately.", "A guaranteed filesystem protection." ], "correct_answer": 0, "explanation": "Instructions can be ignored or misinterpreted; active enforcement and recovery are separate." }, "coach": { "intro": "We are going to inspect configuration and approval modes. The effective configuration and permission mode are recorded; unexpected writes need review.", "demo": "Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Inspect configuration and approval modes, compare your own result with: The effective configuration and permission mode are recorded; unexpected writes need review.. Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply." }, "video": { "purpose": "Demonstrate inspect configuration and approval modes", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply. The effective configuration and permission mode are recorded; unexpected writes need review.", "on_screen_text": [ "Inspect configuration and approval modes", "The effective configuration and permission mode are recorded; unexpected writes need review." ], "screen_recording_instructions": [ "Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply.", "The effective configuration and permission mode are recorded; unexpected writes need review." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The effective configuration and permission mode are recorded; unexpected writes need review." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run the diagnostic command, then the CLI’s --help. Record the rules/settings locations and approval mode available in this installed version. Keep the ordinary permission prompts. For Codex, inspect --sandbox and --ask-for-approval in the installed help; do not assume another tool’s flags apply.", "The effective configuration and permission mode are recorded; unexpected writes need review." ] }, "step_id": "L06-S02", "lesson_id": "L06" }, { "title": "Run a read-only scripted task", "purpose": "This step helps you run a read-only scripted task. The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "user_action": "Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox.", "explanation": "This step helps you run a read-only scripted task. The output accurately describes sum(items), the process exits 0, and app.py is unchanged. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "codex exec \"Read app.py and explain total. Do not edit files or run commands.\"", "macos": "codex exec \"Read app.py and explain total. Do not edit files or run commands.\"", "linux": "codex exec \"Read app.py and explain total. Do not edit files or run commands.\"" }, "command_type": "shell", "required_inputs": [ "app.py" ], "expected_result": "The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "resources": [ "app.py" ], "checkpoint": { "what_is_being_checked": "Run a read-only scripted task", "success_condition": "The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "how_to_verify": "Record the observed result for Run a read-only scripted task. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Run a read-only scripted task?", "fix": "For Run a read-only scripted task: Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox. Compare the actual output to The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The output accurately describes sum(items), the process exits 0, and app.py is unchanged." }, { "question": "Which files support this action?", "answer": "Use app.py." } ], "quiz": null, "coach": { "intro": "We are going to run a read-only scripted task. The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "demo": "Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Run a read-only scripted task, compare your own result with: The output accurately describes sum(items), the process exits 0, and app.py is unchanged.. Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox." }, "video": { "purpose": "Demonstrate run a read-only scripted task", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox. The output accurately describes sum(items), the process exits 0, and app.py is unchanged.", "on_screen_text": [ "Run a read-only scripted task", "The output accurately describes sum(items), the process exits 0, and app.py is unchanged." ], "screen_recording_instructions": [ "Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox.", "The output accurately describes sum(items), the process exits 0, and app.py is unchanged." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The output accurately describes sum(items), the process exits 0, and app.py is unchanged." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Inspect --help for the headless command. Use the card to request only an explanation of app.py. Save stdout and the exit code. Headless mode still consumes provider usage and must not be treated as a free sandbox.", "The output accurately describes sum(items), the process exits 0, and app.py is unchanged." ] }, "step_id": "L07-S01", "lesson_id": "L07" }, { "title": "Plan one connector without granting access", "purpose": "This step helps you plan one connector without granting access. One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "user_action": "Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist.", "explanation": "This step helps you plan one connector without granting access. One connector plan contains purpose, scoped data, permissions, verification and a removal plan. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "resources": [], "checkpoint": { "what_is_being_checked": "Plan one connector without granting access", "success_condition": "One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "how_to_verify": "Record the observed result for Plan one connector without granting access. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Plan one connector without granting access?", "fix": "For Plan one connector without granting access: Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist. Compare the actual output to One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "One connector plan contains purpose, scoped data, permissions, verification and a removal plan." }, { "question": "Which files support this action?", "answer": "No file is required; record your specific observation." } ], "quiz": null, "coach": { "intro": "We are going to plan one connector without granting access. One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "demo": "Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Plan one connector without granting access, compare your own result with: One connector plan contains purpose, scoped data, permissions, verification and a removal plan.. Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist." }, "video": { "purpose": "Demonstrate plan one connector without granting access", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist. One connector plan contains purpose, scoped data, permissions, verification and a removal plan.", "on_screen_text": [ "Plan one connector without granting access", "One connector plan contains purpose, scoped data, permissions, verification and a removal plan." ], "screen_recording_instructions": [ "Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist.", "One connector plan contains purpose, scoped data, permissions, verification and a removal plan." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "One connector plan contains purpose, scoped data, permissions, verification and a removal plan." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Inspect the CLI’s help/configuration for MCP or tool extensions. Write the name of one needed tool, the exact directory/data it would expose, and the permission needed. Add no server until you review that scope. Codex users inspect current MCP/multi-directory help instead of assuming older --mcp-config flags still exist.", "One connector plan contains purpose, scoped data, permissions, verification and a removal plan." ] }, "step_id": "L08-S01", "lesson_id": "L08" }, { "title": "Record a reproducible incident", "purpose": "This step helps you record a reproducible incident. The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "user_action": "Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification.", "explanation": "This step helps you record a reproducible incident. The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "python verify.py", "macos": "python3 verify.py", "linux": "python3 verify.py" }, "command_type": "shell", "required_inputs": [ "incident-template.md", "verify.py" ], "expected_result": "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "resources": [ "incident-template.md", "verify.py" ], "checkpoint": { "what_is_being_checked": "Record a reproducible incident", "success_condition": "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "how_to_verify": "Record the observed result for Record a reproducible incident. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Record a reproducible incident?", "fix": "For Record a reproducible incident: Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification. Compare the actual output to The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery." }, { "question": "Which files support this action?", "answer": "Use incident-template.md, verify.py." } ], "quiz": null, "coach": { "intro": "We are going to record a reproducible incident. The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "demo": "Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Record a reproducible incident, compare your own result with: The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.. Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification." }, "video": { "purpose": "Demonstrate record a reproducible incident", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification. The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery.", "on_screen_text": [ "Record a reproducible incident", "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery." ], "screen_recording_instructions": [ "Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification.", "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Use incident-template.md to document one real or deliberately introduced missing-file error in the practice project. Ask the agent to diagnose from the exact command, path and error, then repair only the practice input and rerun verification.", "The incident contains the failure, one supported diagnosis, smallest fix and VERIFY PASS after recovery." ] }, "step_id": "L09-S01", "lesson_id": "L09" }, { "title": "Write a repeatable onboarding checklist", "purpose": "This step helps you write a repeatable onboarding checklist. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "user_action": "Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked.", "explanation": "This step helps you write a repeatable onboarding checklist. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "15–25 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "onboarding-checklist.md" ], "expected_result": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "resources": [ "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Write a repeatable onboarding checklist", "success_condition": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "how_to_verify": "Record the observed result for Write a repeatable onboarding checklist. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "I can repeat this action from the saved input.", "I recorded the active sandbox/approval mode, actual guard and recovery path; historical Schannel behavior is not claimed as a current test." ], "tokens": [], "user_visible_success_message": "Evidence saved. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Write a repeatable onboarding checklist?", "fix": "For Write a repeatable onboarding checklist: Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked. Compare the actual output to The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." }, { "question": "Which files support this action?", "answer": "Use onboarding-checklist.md." } ], "quiz": null, "coach": { "intro": "We are going to write a repeatable onboarding checklist. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "demo": "Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Write a repeatable onboarding checklist, compare your own result with: The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.. Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked." }, "video": { "purpose": "Demonstrate write a repeatable onboarding checklist", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked. The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "on_screen_text": [ "Write a repeatable onboarding checklist", "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ], "screen_recording_instructions": [ "Fill onboarding-checklist.md for Codex. Rules: AGENTS.md. Memory/settings: ~/.codex (Windows: %USERPROFILE%\\.codex). Guard: ~/.codex/hooks.json; review/trust changes in /hooks when supported by the installed version. Record permissions, backup schedule, restore and final verification. Record the active sandbox and approval settings separately. read-only restricts writes; workspace-write permits scoped project writes; danger-full-access removes that sandbox boundary. This BBB fleet uses danger-full-access by explicit user decision, one active user-folder PreToolUse guard, and independent backups. This is fleet policy, not an installer default. A prompt rule alone cannot enforce protection. The September 29 fleet incident found Windows Schannel TLS failures in sandboxed ODBC/sqlcmd/curl.exe while Python/OpenSSL HTTPS worked; do not assume your current version reproduces that historical failure. Diagnose the exact command, runtime, mode and redacted error before changing access. Optional execpolicy allow rules must pin the interpreter, script and identity, never a blanket python prefix. Do not enable unsupervised full-access jobs until the real workflow, active guard and recovery path are checked.", "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Fill in onboarding-checklist.md for your agent. Record AGENTS.md, the tool’s user settings and memory folder, the assigned workspace, permissions, guard location, backup schedule, and a final proof task. Keep the checklist in your project.", "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification." ] }, "step_id": "L10-S01", "lesson_id": "L10" }, { "title": "Demonstrate the variable-path limit safely", "purpose": "This step helps you demonstrate the variable-path limit safely. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "user_action": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "explanation": "This step helps you demonstrate the variable-path limit safely. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "python workspace_guard.py --self-test", "macos": "python3 workspace_guard.py --self-test", "linux": "python3 workspace_guard.py --self-test" }, "command_type": "shell", "required_inputs": [ "workspace_guard.py" ], "expected_result": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "resources": [ "workspace_guard.py" ], "checkpoint": { "what_is_being_checked": "Demonstrate the variable-path limit safely", "success_condition": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "how_to_verify": "Record the observed result for Demonstrate the variable-path limit safely. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "I can repeat this action from the saved input." ], "tokens": [ "GUARD PASS" ], "user_visible_success_message": "Evidence saved. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Demonstrate the variable-path limit safely?", "fix": "For Demonstrate the variable-path limit safely: Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text. Compare the actual output to GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." }, { "question": "Which files support this action?", "answer": "Use workspace_guard.py." } ], "quiz": { "question": "Does a command-text hook guarantee safety for a path computed inside a script?", "answer_type": "single_choice", "choices": [ "No; add enforcement at the resolved operation boundary and independent recovery.", "Yes, because the command looks harmless." ], "correct_answer": 0, "explanation": "The profile-wipe failure can involve a runtime variable whose value the text hook cannot see." }, "coach": { "intro": "We are going to demonstrate the variable-path limit safely. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "demo": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Demonstrate the variable-path limit safely, compare your own result with: GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.. Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text." }, "video": { "purpose": "Demonstrate demonstrate the variable-path limit safely", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text. GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "on_screen_text": [ "Demonstrate the variable-path limit safely", "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ], "screen_recording_instructions": [ "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run workspace_guard.py --self-test. Read the source: the target is resolved before deciding. The variable_target case points at the home folder but performs no filesystem operation. Compare this with a hook that sees only command text.", "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed." ] }, "step_id": "L10-S02", "lesson_id": "L10" }, { "title": "Verify the actual protection in your tool", "purpose": "This step helps you verify the actual protection in your tool. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "user_action": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; inspect workspace_guard.py from the resource pack; it is a demonstration, not an installed CLI hook. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. If you use a hosted agent, do not assume a local shell hook protects its remote computer: use project-only tasks and reviewed actions, with backups. If no agent is used in this course, record the demonstration only. A hook is active only after a real tool-specific refusal test; otherwise record NOT INSTALLED with the reason.", "explanation": "This step helps you verify the actual protection in your tool. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "inspect", "commands": { "all": "", "windows": "python workspace_guard.py --self-test\npython workspace_guard.py --target \"$env:USERPROFILE\"", "macos": "python3 workspace_guard.py --self-test\npython3 workspace_guard.py --target \"$HOME\"", "linux": "python3 workspace_guard.py --self-test\npython3 workspace_guard.py --target \"$HOME\"" }, "command_type": "shell", "required_inputs": [ "workspace_guard.py", "onboarding-checklist.md" ], "expected_result": "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "resources": [ "workspace_guard.py", "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Verify the actual protection in your tool", "success_condition": "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "how_to_verify": "Record the observed result for Verify the actual protection in your tool. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The harmless command succeeds.", "The boundary dry-run denies a profile target.", "I recorded the tool’s active hook state, or explicitly recorded that this tool has no working local guard." ], "tokens": [], "user_visible_success_message": "Evidence saved. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true, "tokens_any": [ [ "DENY" ], [ "NOT INSTALLED" ] ] }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Verify the actual protection in your tool?", "fix": "For Verify the actual protection in your tool: For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups. Compare the actual output to A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." }, { "question": "Which files support this action?", "answer": "Use workspace_guard.py, onboarding-checklist.md." } ], "quiz": null, "coach": { "intro": "We are going to verify the actual protection in your tool. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "demo": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Verify the actual protection in your tool, compare your own result with: A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.. For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups." }, "video": { "purpose": "Demonstrate verify the actual protection in your tool", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups. A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation.", "on_screen_text": [ "Verify the actual protection in your tool", "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ], "screen_recording_instructions": [ "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; inspect workspace_guard.py from the resource pack; it is a demonstration, not an installed CLI hook. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. If you use a hosted agent, do not assume a local shell hook protects its remote computer: use project-only tasks and reviewed actions, with backups. If no agent is used in this course, record the demonstration only. A hook is active only after a real tool-specific refusal test; otherwise record NOT INSTALLED with the reason.", "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "For CLI tools, open the hook/permissions screen and confirm the configured guard is active. Use your tool’s documented pre-command hook protocol; the BBB working reference is linked in Sources. Run a harmless directory listing, then a guard dry-run targeting the profile. Do not execute a destructive profile probe. Grok Bot has no proven local shell guard here: use project-only tasks and reviewed actions, with backups.", "A harmless command runs, the guard dry-run returns DENY, and the checklist records the actual hook protocol and active state or the Grok Bot limitation." ] }, "step_id": "L10-S03", "lesson_id": "L10" }, { "title": "Enable a real backup of memory and project files", "purpose": "This step helps you enable a real backup of memory and project files. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "user_action": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials. On Windows, review the script, unblock only that downloaded file, then run it with the shown process-only RemoteSigned policy. Group Policy can still refuse it; report that limitation without changing machine policy.", "explanation": "This step helps you enable a real backup of memory and project files. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "15–25 min", "action_type": "command", "commands": { "windows": "# Read the extracted script before unblocking this single file.\nGet-Content .\\profile-backup.ps1\nUnblock-File -LiteralPath .\\profile-backup.ps1\npowershell.exe -NoProfile -ExecutionPolicy RemoteSigned -File .\\profile-backup.ps1 -Destination D:\\Backups\\llm-profiles", "macos": "bash profile-backup.sh /Volumes/YourBackup/llm-profiles", "linux": "bash profile-backup.sh /media/YourBackup/llm-profiles" }, "command_type": "shell", "required_inputs": [ "profile-backup.ps1", "profile-backup.sh", "onboarding-checklist.md" ], "expected_result": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "resources": [ "profile-backup.ps1", "profile-backup.sh", "onboarding-checklist.md" ], "checkpoint": { "what_is_being_checked": "Enable a real backup of memory and project files", "success_condition": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "how_to_verify": "Record the observed result for Enable a real backup of memory and project files. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The destination is a mounted second drive.", "The hidden memory/settings folders and project files are included.", "An automated backup is enabled and its latest successful run is recorded." ], "tokens": [ "PROFILE BACKUP PASS" ], "user_visible_success_message": "Evidence saved. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The backup drive is missing or the script reports a failure", "likely_cause": "The destination may be on the same volume, unmounted, or unwritable.", "diagnostic_question": "What exact result did you observe during Enable a real backup of memory and project files?", "fix": "For Enable a real backup of memory and project files: Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials. Compare the actual output to A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "alternative_fix": "Use the operating system backup application and verify the same folder coverage and successful run.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." }, { "question": "Which files support this action?", "answer": "Use profile-backup.ps1, profile-backup.sh, onboarding-checklist.md." } ], "quiz": null, "coach": { "intro": "We are going to enable a real backup of memory and project files. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "demo": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures.", "help": "For Enable a real backup of memory and project files, compare your own result with: A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.. Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials." }, "video": { "purpose": "Demonstrate enable a real backup of memory and project files", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials. A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded.", "on_screen_text": [ "Enable a real backup of memory and project files", "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ], "screen_recording_instructions": [ "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials. On Windows, review the script, unblock only that downloaded file, then run it with the shown process-only RemoteSigned policy. Group Policy can still refuse it; report that limitation without changing machine policy.", "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Connect a second backup drive. Windows: configure System Protection as additional recovery and use a scheduled copy/File History that explicitly includes hidden agent folders. macOS: configure Time Machine and verify dot folders are included. Linux: use a home backup such as restic/Deja Dup; Timeshift omits /home by default. Download the copy-only profile backup script for your platform, inspect it, and adapt the folder list to your tool. Record the last successful scheduled run; protect backup access because it may contain credentials.", "A backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded." ] }, "step_id": "L10-S04", "lesson_id": "L10" }, { "title": "Practice a hash-verified restore", "purpose": "This step helps you practice a hash-verified restore. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "user_action": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "explanation": "This step helps you practice a hash-verified restore. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "python restore_drill.py --backup-root D:\\Backups\\bbb-practice --work-root practice", "macos": "python3 restore_drill.py --backup-root /Volumes/YourBackup/bbb-practice --work-root practice", "linux": "python3 restore_drill.py --backup-root /media/YourBackup/bbb-practice --work-root practice" }, "command_type": "shell", "required_inputs": [ "restore_drill.py" ], "expected_result": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "resources": [ "restore_drill.py" ], "checkpoint": { "what_is_being_checked": "Practice a hash-verified restore", "success_condition": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "how_to_verify": "Record the observed result for Practice a hash-verified restore. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The proof file SHA256 hashes match.", "I restored and opened a non-secret memory/settings file from my real backup.", "The restored file is in scratch; the live profile was not overwritten." ], "tokens": [ "RESTORE PASS" ], "user_visible_success_message": "Evidence saved. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Practice a hash-verified restore?", "fix": "For Practice a hash-verified restore: Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile. Compare the actual output to RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." }, { "question": "Which files support this action?", "answer": "Use restore_drill.py." } ], "quiz": null, "coach": { "intro": "We are going to practice a hash-verified restore. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "demo": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Practice a hash-verified restore, compare your own result with: RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.. Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile." }, "video": { "purpose": "Demonstrate practice a hash-verified restore", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile. RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "on_screen_text": [ "Practice a hash-verified restore", "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ], "screen_recording_instructions": [ "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Run restore_drill.py with a separate backup directory. The script creates a new proof file, copies it, restores a second copy, and compares SHA256 hashes. Then restore one non-secret file from your actual agent memory backup into a separate scratch directory and open it; do not overwrite the live profile.", "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch." ] }, "step_id": "L10-S05", "lesson_id": "L10" }, { "title": "Restart from the right directory", "purpose": "This step helps you restart from the right directory. The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "user_action": "Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again.", "explanation": "This step helps you restart from the right directory. The correct workspace/rules are active after restart and VERIFY PASS is reproducible. Treat this as local practice until you have actual source and execution evidence.", "estimated_time": "5–10 min", "action_type": "command", "commands": { "windows": "codex resume\n# After returning to your terminal:\npython verify.py", "macos": "codex resume\n# After returning to your terminal:\npython3 verify.py", "linux": "codex resume\n# After returning to your terminal:\npython3 verify.py" }, "command_type": "shell", "required_inputs": [ "AGENTS.md", "verify.py" ], "expected_result": "The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "resources": [ "AGENTS.md", "verify.py" ], "checkpoint": { "what_is_being_checked": "Restart from the right directory", "success_condition": "The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "how_to_verify": "Record the observed result for Restart from the right directory. Use three lines: Result: (what happened); Evidence: (actual output or file and specific observation); Limit: (what you did not verify). Include required output tokens. The page checks structure only, not truth.", "criteria": [ "The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "I can repeat this action from the saved input." ], "tokens": [ "VERIFY PASS" ], "user_visible_success_message": "Evidence saved. The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step.", "structured": true }, "troubleshooting": [ { "problem": "The result differs from the checkpoint", "likely_cause": "You may be in a different folder or using a different input/version.", "diagnostic_question": "What exact result did you observe during Restart from the right directory?", "fix": "For Restart from the right directory: Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again. Compare the actual output to The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "alternative_fix": "Open the supplied resource and inspect the input manually; use the expected-result example to narrow the difference.", "when_to_escalate": "Stop after two explained attempts if the problem needs account access, permissions or changes outside this workspace. Share redacted evidence.", "bot_coach_response": "Compare the input filename and working directory with this step. Rerun only after correcting that difference." } ], "faqs": [ { "question": "What result should I verify for this step?", "answer": "The correct workspace/rules are active after restart and VERIFY PASS is reproducible." }, { "question": "Which files support this action?", "answer": "Use AGENTS.md, verify.py." } ], "quiz": null, "coach": { "intro": "We are going to restart from the right directory. The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "demo": "Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again.", "handoff": "Try this in your own practice workspace, then compare the result.", "success": "Keep that result with your evidence.", "failure": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "help": "For Restart from the right directory, compare your own result with: The correct workspace/rules are active after restart and VERIFY PASS is reproducible.. Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again." }, "video": { "purpose": "Demonstrate restart from the right directory", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again. The correct workspace/rules are active after restart and VERIFY PASS is reproducible.", "on_screen_text": [ "Restart from the right directory", "The correct workspace/rules are active after restart and VERIFY PASS is reproducible." ], "screen_recording_instructions": [ "Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again.", "The correct workspace/rules are active after restart and VERIFY PASS is reproducible." ], "animation_instructions": "Highlight the action, then the corresponding result; avoid motion during command copying.", "cursor_instructions": "Point to the exact input and checkpoint; do not hide errors.", "important_visuals": [ "The correct workspace/rules are active after restart and VERIFY PASS is reproducible." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Close the CLI normally. Reopen a terminal in this extracted folder. Run codex resume (or start a new session if the installed help lists a different continuation option). Ask it to reread AGENTS.md and summarize the last verification. Run verify.py independently again.", "The correct workspace/rules are active after restart and VERIFY PASS is reproducible." ] }, "step_id": "L11-S01", "lesson_id": "L11" } ], "resources": [ { "resource_id": "R001", "name": "workspace_guard.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\n\"\"\"Dry-run resolved-path boundary demonstration. This script never deletes anything.\"\"\"\nimport argparse\nfrom pathlib import Path\n\ndef permitted(target, workspace):\n root = Path(workspace).resolve()\n candidate = Path(target).resolve()\n home = Path.home().resolve()\n if root == home or root == root.anchor or root in home.parents:\n return False\n return candidate != root and root in candidate.parents and candidate != home and candidate not in home.parents\n\ndef main():\n p=argparse.ArgumentParser(description=__doc__)\n p.add_argument('--workspace',default='practice')\n p.add_argument('--target')\n p.add_argument('--self-test',action='store_true')\n a=p.parse_args()\n root=Path(a.workspace).resolve()\n if a.self_test:\n assert permitted(root/'proof.txt',root)\n assert not permitted(Path.home(),root)\n assert not permitted(root.parent/'outside.txt',root)\n assert not permitted(root,root)\n variable_target=Path.home()\n assert not permitted(variable_target,root)\n print('GUARD PASS: inside allowed; profile, variable-derived profile, outside, workspace root denied; no deletion executed')\n else:\n if not a.target:p.error('--target required')\n allowed=permitted(a.target,a.workspace)\n print(('ALLOW' if allowed else 'DENY')+': resolved boundary; dry-run only')\n raise SystemExit(0 if allowed else 2)\nif __name__=='__main__':main()\n", "filename": "workspace_guard.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R002", "name": "restore_drill.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\n\"\"\"Backup and restore a new proof file only; never edits an existing file or profile.\"\"\"\nimport argparse,hashlib,json,logging\nfrom datetime import datetime,timezone\nfrom pathlib import Path\nimport shutil\ndef digest(p):return hashlib.sha256(p.read_bytes()).hexdigest()\ndef main():\n a=argparse.ArgumentParser(description=__doc__)\n a.add_argument('--backup-root',required=True)\n a.add_argument('--work-root',default='practice')\n x=a.parse_args()\n run=datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%S%fZ')\n work=Path(x.work_root).resolve()/('restore-'+run)\n backup=Path(x.backup_root).resolve()/('restore-'+run)\n if work==backup or work in backup.parents or backup in work.parents:raise SystemExit('Use separate, non-overlapping work and backup roots')\n work.mkdir(parents=True,exist_ok=False);backup.mkdir(parents=True,exist_ok=False)\n logging.basicConfig(filename=work/'drill.log',encoding='utf-8',level=logging.INFO)\n source=work/'proof.txt';source.write_text('BuildBotsBetter restore proof '+run,encoding='utf-8')\n shutil.copy2(source,backup/'proof.txt')\n restored=work/'restored.txt';shutil.copy2(backup/'proof.txt',restored)\n assert digest(source)==digest(restored)\n receipt={'result':'RESTORE PASS','source_sha256':digest(source),'restored_sha256':digest(restored),'backup_root':str(backup),'off_volume':work.anchor.lower()!=backup.anchor.lower(),'scope':'new proof file only; does not establish a scheduled profile backup'}\n (work/'receipt.json').write_text(json.dumps(receipt,indent=2),encoding='utf-8')\n logging.info('Proof backup and hash-verified restore completed')\n print(json.dumps(receipt,indent=2))\n if not receipt['off_volume']:print('SAME VOLUME: practice passed; configure a second drive for disaster recovery')\nif __name__=='__main__':main()\n", "filename": "restore_drill.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R003", "name": "onboarding-checklist.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Repeatable agent onboarding\nagent:\ntool version:\nrules file:\nmemory/settings location:\nassigned workspace:\npermissions / actions needing approval:\nhook location and protocol:\nguard active (harmless command + denied dry-run):\nvariable-derived path limit understood:\nbackup destination (second drive):\nbackup schedule / last successful run:\nrestored memory file / matching SHA256:\nfinal task / evidence / reviewer:\n\nProtect memory/settings and project files. A prompt rule is not an operating-system boundary.\nA command-text hook can miss a path computed in a script or variable. Resolve paths at the\noperation boundary and fail closed; keep independent backups and monitoring.\nWindows System Restore reverts system components, not a reliable personal-file backup.\nOneDrive folder backup does not automatically include hidden agent folders.\nmacOS: check Time Machine includes hidden agent folders. Linux: Timeshift excludes /home by\ndefault; use a separate home backup or explicitly include it.\n", "filename": "onboarding-checklist.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R004", "name": "profile-backup.ps1", "type": "ps1", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: copy-only explicit profile backup.\nparam([Parameter(Mandatory=$true)][string]$Destination,[string]$ProjectPath=(Get-Location).Path)\n$ErrorActionPreference='Stop'\n$destRoot=[IO.Path]::GetFullPath($Destination)\n$profileRoot=[IO.Path]::GetFullPath($env:USERPROFILE)\nif ([IO.Path]::GetPathRoot($destRoot) -eq [IO.Path]::GetPathRoot($profileRoot)) { throw 'Choose a backup destination on a second drive.' }\nif (-not (Test-Path -LiteralPath ([IO.Path]::GetPathRoot($destRoot)))) { throw 'Backup drive is unavailable.' }\n$runDir=Join-Path $destRoot (Get-Date -Format 'yyyyMMdd-HHmmss-fff')\nNew-Item -ItemType Directory -Path $runDir -ErrorAction Stop | Out-Null\nforeach ($folderName in @('.codex','.claude','.grok','.qwen','.gemini')) {\n $sourceDir=Join-Path $profileRoot $folderName\n if (Test-Path -LiteralPath $sourceDir) {\n $copyDir=Join-Path $runDir $folderName\n & robocopy $sourceDir $copyDir /E /XJ /R:1 /W:1 /COPY:DAT /DCOPY:DAT /NP\n if ($LASTEXITCODE -ge 8) { throw \"Backup failed for $folderName (robocopy $LASTEXITCODE).\" }\n }\n}\n$projectSource=[IO.Path]::GetFullPath($ProjectPath)\nif (-not (Test-Path -LiteralPath $projectSource -PathType Container)) { throw 'Project directory is unavailable.' }\n& robocopy $projectSource (Join-Path $runDir 'project') /E /XJ /R:1 /W:1 /COPY:DAT /DCOPY:DAT /NP\nif ($LASTEXITCODE -ge 8) { throw \"Project backup failed (robocopy $LASTEXITCODE).\" }\n\"PROFILE BACKUP PASS: $runDir\"\n# Copy-only: no /MIR, /PURGE or deletion. Backup may contain credentials; protect the drive.\n# Add the Grok Bot profile and project path explicitly after finding them in your own installation.\n", "filename": "profile-backup.ps1", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R005", "name": "profile-backup.sh", "type": "sh", "purpose": "Working resource used by this Build; inspect before running.", "contents": "#!/usr/bin/env bash\n# VERSION HISTORY\n# 2026-10-16 EDT | chatgpt_codex / Codex | peer finding repairs\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: copy-only explicit profile backup.\nset -euo pipefail\ndest=${1:?Pass a mounted external-drive backup directory}\nproject=${2:-$PWD}\nif [ ! -d \"$dest\" ]; then echo \"Destination must already exist on a mounted external filesystem.\" >&2; exit 2; fi\nif [ \"$(df -P \"$HOME\" | tail -1 | awk '{print $1}')\" = \"$(df -P \"$dest\" | tail -1 | awk '{print $1}')\" ]; then\n echo 'Choose a destination on another mounted filesystem.' >&2; exit 2\nfi\nrun=\"$dest/$(date -u +%Y%m%dT%H%M%SZ)-$$\"\nmkdir \"$run\"\nfor name in .codex .claude .grok .qwen .gemini; do\n if [ -d \"$HOME/$name\" ]; then cp -pR \"$HOME/$name\" \"$run/$name\"; fi\ndone\nif [ ! -d \"$project\" ]; then echo 'Project directory is unavailable.' >&2; exit 2; fi\ncp -pR \"$project\" \"$run/project\"\necho \"PROFILE BACKUP PASS: $run\"\n# This backup can contain credentials; protect access to the backup drive.\n", "filename": "profile-backup.sh", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R006", "name": "app.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\ndef total(items):\n return sum(items)\nif __name__ == '__main__':\n print('APP PASS: total=' + str(total([2, 3, 5])))\n", "filename": "app.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R007", "name": "verify.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\nfrom app import total\nassert total([])==0\nassert total([2,3,5])==10\nassert total([-2,2])==0\nassert total([2,2])==4\nprint('VERIFY PASS: empty, ordinary, signed, repeated inputs')\n", "filename": "verify.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R008", "name": "broken_app.py", "type": "py", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# VERSION HISTORY\n# 2026-10-05 EDT | chatgpt_codex | overnight-catalog | v1: learner resource.\ndef total(items):\n return sum(set(items))\n", "filename": "broken_app.py", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R009", "name": "delegation.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Bounded delegation\nObjective: make the supplied total function preserve repeated inputs.\nScope: app.py only; inspect verify.py, do not weaken it.\nConstraints: no network, no dependencies, no external writes, no profile cleanup.\nVerification: run python verify.py; include exit code and complete output.\nEvidence: failing case before, diagnosis, minimal diff, passing case after.\nStop: ask if the fix needs files outside this practice directory.\nReview: human checks the diff and reruns verification independently.\n", "filename": "delegation.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R010", "name": "incident-template.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Incident evidence\nWhat I tried:\nExpected result:\nObserved result / complete error:\nReproduce command and exit code:\nRelevant environment versions:\nWorking directory:\nOne hypothesis:\nSmallest diagnostic:\nCorrective action:\nIndependent verification:\nRecovery point:\n", "filename": "incident-template.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "resource_id": "R011", "name": "AGENTS.md", "type": "md", "purpose": "Working resource used by this Build; inspect before running.", "contents": "# Practice rules\nWork only in this extracted folder. Read app.py and verify.py. Explain before changing files. Do not weaken verification. Do not send messages, change accounts, expose secrets, delete profiles or enable background tasks. Require evidence: command, exit code, output and minimal diff.\n", "filename": "AGENTS.md", "generated_from": "BUILD_SPEC.json.resources", "version": "2.0" }, { "filename": "source-README.md", "contents": "# bots/safety: the one restriction every agent keeps\n\nUser decision, 2026-09-29: \"lift all restrictions except for removing user folders.\" No agent runs in a sandbox or with\nallow lists any more. `protect_user_folders.py` is what remains. It blocks:\n\n- deleting or moving `C:\\Users`, a profile root, or a top-level profile folder (Desktop, Documents, .codex, AppData, ...)\n- recursive deletes anywhere inside a profile, except `AppData\\Local\\Temp`\n\nEverything else is allowed.\n\n| Agent | Where the guard is registered |\n|---|---|\n| Claude Code (claude_cli) | `~/.claude/settings.json` hooks.PreToolUse, matcher `Bash\\|PowerShell` |\n| Grok Build (grok_build) | `~/.grok/hooks/protect_user_folders.json` (it also reads Claude's settings) |\n| ChatGPT Codex (chatgpt_codex) | `~/.codex/hooks.json`; headless runs pass `--dangerously-bypass-hook-trust`, interactive: trust once in `/hooks` |\n| Qwen Code (qwen_code) | `~/.qwen/settings.json` hooks.PreToolUse, matcher `run_shell_command` |\n| Antigravity CLI (antigravity_cli) | `~/.gemini/config/hooks.json` (its own JSON protocol: `toolCall.args.CommandLine` in, `{\"decision\": \"deny\"}` out). Regex `permissions.deny` in settings.json did NOT hold in the 2026-09-29 probe, so it is not used |\n\nAntigravity splits the hook `command` on spaces and keeps the quotes, so a quoted `\"C:/My Projects/...\"` path fails on\nEVERY call and blocks every tool (the 2026-09-29 preflight passed for that wrong reason). Every tool's hook therefore uses the\nspace-free 8.3 path: `python C:/MYPROJ~1/BUILDB~1/bots/safety/protect_user_folders.py` (Antigravity fixed 2026-09-29; Qwen Code hit the same bug on 2026-09-30 (\"Tool run_shell_command was not run\"\n47 minutes long), so Qwen, Codex and Grok were switched too; Claude Code runs hooks through a shell and keeps the quoted path;\nthe preflight now shows the real BLOCKED message and the agent can run other commands). A preflight PASS alone does not\nprove the guard ran: also check that the agent can run a harmless command.\n\nHook TRUST (2026-09-30): Codex stores a trusted hash per hook ([hooks.state] in ~/.codex/config.toml). Changing a hook's\ncommand (as the 8.3 switch above did) makes it \"new or changed\": interactive Codex then runs WITHOUT the guard until it is\nre-trusted (/hooks: PreToolUse Installed 1, Active 0). review_loop.py passes --dangerously-bypass-hook-trust, so the\nheadless preflight still PASSES and hides this. After every hook edit: open each tool interactively, review the hook,\ntrust it, and confirm Active 1 (educational/ONBOARDING.txt checklist step 7b).\n\n`python test_hook_protocols.py` feeds the guard every stdin protocol (including Cursor-style\n`beforeShellExecution`) and checks the answers.\n\nGrok Bot (desktop app) has NO working guard (live test 2026-09-29, `grok_bot_probe.py`, two runs with a restart between).\nIt runs shell commands on this PC and ran a recursive delete of the `.bbb_probe` test folder without asking. Its engine\ncontains Cursor's hook code, but hook files in `~/.cursor/hooks.json`, `~/.grokbot/hooks.json` and the project's\n`.cursor/hooks.json` were never called; the test files were removed afterwards. Treat Grok Bot as unguarded: project\nfolders only, no profile clean-up tasks, backups. Re-run the probe after Grok Bot updates (it needs the app started with\n`--remote-debugging-port=9333`; relaunch without the port afterwards).\n\nChecks:\n\n python protect_user_folders.py --self-test # built-in cases\n python protect_user_folders.py --check \"rm -rf ~/Documents\" # one command\n python ../conversation_hub/review_loop.py --preflight # the real agent tries to delete ~/.bbb_probe; must survive\n python check_agent_env.py --all # the hook runs inside every LIVE agent window (exit 0)\n\n`check_agent_env.py` (2026-10-02, hub #1071) exists because preflight runs headless and inherits the caller's PATH. On\n2026-10-02 the windows launched from the All Builds page had a Store \"Python Install Manager\" python first on PATH, so\nevery hook failed with \"Access is denied.\" (exit 1). See `educational/AGENT_LAUNCH_ENVIRONMENT.txt`.\n\nBackstops: the profile guard in review_loop.py and hub_watch.py kills an agent's process tree if key profile folders\ndisappear, and the twice-daily profile backups go to `D:\\Backups\\llm-profiles`. Blocks are logged to\n`logs/protect_user_folders.log`.\n\nFalse blocks (user decision 2026-09-29: keep them, do not add exceptions). The guard judges text, so a command that only\nMENTIONS a protected delete is blocked too, e.g. a heredoc writing a hub message that quotes the probe command. 3 of the\nfirst 25 blocks were like that; nothing ran and nothing was lost. Fix on your side: write the text with your editor/file\ntool (Write/Edit), then pass the file (hub.py post --file). Do not look for a way around the guard.\n\nKnown limit: the hook sees the command text. A script that computes a profile path at run time (for example\n`python cleanup.py`) is not visible to it, and neither is a variable (`Remove-Item -Recurse $tmp`, `rm -rf \"$WORKDIR/\"`,\n`$env:GROK_HOME`): all allowed (checked 2026-09-29). The #30 wipe was most likely that shape (a temp-folder delete whose\nvariable held C:\\Users\\aidat; GROK_HOME was the profile), so this guard would probably NOT have stopped #30. The\nprocess-tree kill and the backups cover that case; courses must say so.\n", "description": "BuildBotsBetter working guard protocols and limits", "type": "text" } ], "bot_coach": { "bot_name": "Buzz", "bot_role": "Offline reviewed step coach", "personality": "patient and concrete", "tone": "plain", "teaching_style": "hint, diagnostic, action, checkpoint", "introduction": "Ask about the current step. I use reviewed local answers and queue unknown questions for review.", "encouragement_style": "Focus on observed results.", "troubleshooting_style": "Ask for the smallest reproducible evidence.", "limits": "This offline coach does not call an LLM or inspect your computer. Unknown questions enter a local exportable review queue, not a shared SQL FAQ." }, "coach_interaction_model": { "stuck": "current diagnostic and first repair", "meaning": "current explanation", "error": "current troubleshooting", "why": "purpose", "skip": "require equivalent evidence", "alternative": "documented alternative", "finished": "record actual output", "start_over": "export then reset only this Build", "progressive_assistance": [ "hint", "diagnostic", "walkthrough", "resource solution" ] }, "website_specification": { "layout": "Lesson outline, actionable step, current-context coach", "features": [ "platform selectors", "command copy with selection fallback", "evidence checklist", "practical quiz", "downloadable resource ZIP", "local progress", "evidence export", "unknown-question review queue" ], "checkpoint_model": "Learner supplies observations/output; tokens check expected shape only, not host truth.", "navigation": "Browse freely; checked next-button progression retains evidence.", "video": "spec-driven walkthrough and optional speech; full rendered media is a downstream production task." }, "final_test": { "test_name": "Repeat the core workflow and restore its evidence", "instructions": "Repeat the last product-specific checkpoint from a fresh practice input, preserve actual output, then complete the Build Bot Better guard and restore checks. Export the evidence.", "required_inputs": [ "workspace_guard.py", "restore_drill.py", "onboarding-checklist.md", "app.py", "verify.py", "broken_app.py", "delegation.md", "incident-template.md", "AGENTS.md" ], "success_conditions": [ "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "Core output can be reproduced", "Guard limit explained", "Backup and restoration evidence retained" ], "automated_tests": "catalog_check.py records browser behavior and executable resources, with explicit scope.", "manual_tests": [ "Review actual account sign-in where needed", "Check source/data assumptions", "Restore one real non-secret memory file" ], "expected_output": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "failure_paths": "Use the specific step diagnostic, retain failure evidence and stop when access is required." }, "extensions": [ { "title": "Use your own input", "action": "Replace the sample with one permitted real input and rerun the same checks." }, { "title": "Add one failure case", "action": "Create a malformed or missing input; prove the workflow fails visibly and recovers." }, { "title": "Automate after review", "action": "Write a bounded schedule with logging and a stop condition; obtain approval for external actions separately." } ], "metadata": { "SEO_title": "Install ChatGPT Codex | BuildBotsBetter", "SEO_description": "An installed, authenticated Codex workspace with rules, a verified Python change, a headless read-only check, and a practiced recovery path.", "SEO_keywords": [ "install-chatgpt-codex", "guided build", "verified outcome" ], "difficulty": "beginner", "related_builds": [ "dogfooding", "buildbotsbetter-onboarding" ], "next_recommended_build": "dogfooding" }, "automation_map": [ { "output": "website", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "walkthrough", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "bot dialogue", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "resources", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "quiz", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "captions", "generated_from": "BUILD_SPEC.json", "human_review_required": true }, { "output": "metadata", "generated_from": "BUILD_SPEC.json", "human_review_required": true } ], "quality_assurance_report": { "scope": "Original instructional content, reviewed against shared brief; execution and browser receipts are stored under logs/catalog-acceptance.", "known_limits": [ "Native installers and Linux/npm prerequisite paths need clean-machine verification; see test receipts.", "macOS commands have not been run on a real Mac.", "Human sign-in and paid-plan eligibility cannot be certified without the learner’s account.", "Do not assign an A/fully verified setup grade until a real clean install and sign-in walk is complete." ] }, "sources": [ { "title": "Official Codex installation and usage", "url": "https://developers.openai.com/codex/cli/" }, { "title": "Node.js official downloads", "url": "https://nodejs.org/en/download" }, { "title": "BuildBotsBetter working guard protocols and limits", "url": "resources/source-README.md" }, { "title": "Official Codex configuration and permissions", "url": "https://developers.openai.com/codex/config-basic/" } ], "known_uncertainties": [ "Native installers and Linux/npm prerequisite paths need clean-machine verification; see test receipts.", "macOS commands have not been run on a real Mac.", "Human sign-in and paid-plan eligibility cannot be certified without the learner’s account.", "Do not assign an A/fully verified setup grade until a real clean install and sign-in walk is complete." ], "checkpoint_revision": "r13-20261017", "version_history": [ "2026-10-16 EDT | chatgpt_codex / Codex | peer finding repairs" ] }