{ "schema_version": 2, "meta": { "build_id": "CODEX-SETUP-GROK-BOT", "slug": "setup-grok-bot", "title": "Set Up Grok Bot", "subtitle": "Create one persistent teammate and verify a useful task.", "description": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "one_sentence_description": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "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": [ "setup-grok-bot", "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": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "platforms": [ "windows", "macos", "linux" ], "version": "2.0", "author": "chatgpt_codex", "source_checked": "2026-10-05", "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 set up grok bot.", "after": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "finished_product": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist." }, "learning_objectives": [ "The chosen product and eligible account path are recorded without a forced plan upgrade.", "The official app opens on the chosen OS/architecture and its version is recorded.", "The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "The bot description has one job, a voice, a source rule and explicit approval rules.", "The task uses only its required data and the connection’s access/removal plan is recorded.", "The bot rejects the false draft and cites the supplied statement about repeated values." ], "lessons": [ { "lesson_id": "L01", "title": "Check the product and eligibility", "purpose": "Product names, plans and privacy settings can change. Verify them in the official account UI rather than assuming any paid plan works.", "estimated_time": "6 min", "learning_objective": "The chosen product and eligible account path are recorded without a forced plan upgrade.", "lessons_before_this": [], "lessons_after_this": [ "L02" ] }, { "lesson_id": "L02", "title": "Install the desktop app", "purpose": "Avoid unofficial download mirrors and similarly named apps. No shell CLI command is required to install the teammate app.", "estimated_time": "6 min", "learning_objective": "The official app opens on the chosen OS/architecture and its version is recorded.", "lessons_before_this": [ "L01" ], "lessons_after_this": [ "L03" ] }, { "lesson_id": "L03", "title": "Sign in and create the teammate", "purpose": "The app can reopen its last chat. A task in Rental Manager is not a task in BuildBotsBetter; select and verify the title every time.", "estimated_time": "6 min", "learning_objective": "The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "lessons_before_this": [ "L02" ], "lessons_after_this": [ "L04" ] }, { "lesson_id": "L04", "title": "Write an operating description", "purpose": "A persistent teammate benefits from an operating manual. Instructions improve behavior but are not a proven local filesystem guard.", "estimated_time": "6 min", "learning_objective": "The bot description has one job, a voice, a source rule and explicit approval rules.", "lessons_before_this": [ "L03" ], "lessons_after_this": [ "L05" ] }, { "lesson_id": "L05", "title": "Grant the smallest tool access", "purpose": "Connected accounts may expose broader data than the current task. Review scopes before granting access.", "estimated_time": "6 min", "learning_objective": "The task uses only its required data and the connection’s access/removal plan is recorded.", "lessons_before_this": [ "L04" ], "lessons_after_this": [ "L06" ] }, { "lesson_id": "L06", "title": "Run a useful first task", "purpose": "The task is small enough to check independently. A confident unsourced answer is a failure, not a successful first run.", "estimated_time": "6 min", "learning_objective": "The bot rejects the false draft and cites the supplied statement about repeated values.", "lessons_before_this": [ "L05" ], "lessons_after_this": [ "L07" ] }, { "lesson_id": "L07", "title": "Test uncertainty and memory", "purpose": "Memory should help continuity without turning absent facts into invented knowledge.", "estimated_time": "6 min", "learning_objective": "The unsupported fact remains unknown and the selected bot retains the intended job/context.", "lessons_before_this": [ "L06" ], "lessons_after_this": [ "L08" ] }, { "lesson_id": "L08", "title": "Plan a bounded routine", "purpose": "Frequent routines can consume usage and produce noise. Use an event or daily check rather than a needlessly frequent polling loop.", "estimated_time": "6 min", "learning_objective": "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "lessons_before_this": [ "L07" ], "lessons_after_this": [ "L09" ] }, { "lesson_id": "L09", "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": [ "L08" ], "lessons_after_this": [ "L10" ] }, { "lesson_id": "L10", "title": "Run it later — select the right teammate", "purpose": "Never assume the app opens the same chat you intended. The desktop profile path depends on the installer/build; locate it through your installation and include it in the backup checklist.", "estimated_time": "6 min", "learning_objective": "The selected teammate, job, source boundary and routine state are verified after reopening.", "lessons_before_this": [ "L09" ], "lessons_after_this": [] } ], "steps": [ { "title": "Choose Grok Bot, not Grok Build", "purpose": "Product names, plans and privacy settings can change. Verify them in the official account UI rather than assuming any paid plan works.", "user_action": "Open the official Grok Bot get-started page. Check current account eligibility, cloud data requirements and your company policy before downloading. Grok Bot is the long-lived teammate app; Grok Build is the terminal coding agent.", "explanation": "Product names, plans and privacy settings can change. Verify them in the official account UI rather than assuming any paid plan works.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The chosen product and eligible account path are recorded without a forced plan upgrade.", "resources": [], "checkpoint": { "what_is_being_checked": "Choose Grok Bot, not Grok Build", "success_condition": "The chosen product and eligible account path are recorded without a forced plan upgrade.", "how_to_verify": "Record the chosen product and eligible account path are recorded without a forced plan upgrade. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The chosen product and eligible account path are recorded without a forced plan upgrade.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The chosen product and eligible account path are recorded without a forced plan upgrade.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify choose grok bot, not grok build?", "answer": "The chosen product and eligible account path are recorded without a forced plan upgrade. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to choose Grok Bot, not Grok Build. The chosen product and eligible account path are recorded without a forced plan upgrade.", "demo": "Open the official Grok Bot get-started page. Check current account eligibility, cloud data requirements and your company policy before downloading. Grok Bot is the long-lived teammate app; Grok Build is the terminal coding agent.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate choose grok bot, not grok build", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Open the official Grok Bot get-started page. Check current account eligibility, cloud data requirements and your company policy before downloading. Grok Bot is the long-lived teammate app; Grok Build is the terminal coding agent. The chosen product and eligible account path are recorded without a forced plan upgrade.", "on_screen_text": [ "Choose Grok Bot, not Grok Build", "The chosen product and eligible account path are recorded without a forced plan upgrade." ], "screen_recording_instructions": [ "Open the official Grok Bot get-started page. Check current account eligibility, cloud data requirements and your company policy before downloading. Grok Bot is the long-lived teammate app; Grok Build is the terminal coding agent.", "Inspect the result: The chosen product and eligible account path are recorded without a forced plan upgrade.", "Record the evidence and check each criterion." ], "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 chosen product and eligible account path are recorded without a forced plan upgrade." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Open the official Grok Bot get-started page. Check current account eligibility, cloud data requirements and your company policy before downloading. Grok Bot is the long-lived teammate app; Grok Build is the terminal coding agent.", "The chosen product and eligible account path are recorded without a forced plan upgrade." ] }, "step_id": "L01-S01", "lesson_id": "L01" }, { "title": "Select the correct installer", "purpose": "Avoid unofficial download mirrors and similarly named apps. No shell CLI command is required to install the teammate app.", "user_action": "Open x.ai/bot downloads. Windows: choose x64/Arm64 from Settings → System → About, run the official installer and launch from Start. macOS: check chip in About This Mac, open the DMG and drag into Applications. Linux: select the official package for your architecture/distribution and install through its supported package route.", "explanation": "Avoid unofficial download mirrors and similarly named apps. No shell CLI command is required to install the teammate app.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The official app opens on the chosen OS/architecture and its version is recorded.", "resources": [], "checkpoint": { "what_is_being_checked": "Select the correct installer", "success_condition": "The official app opens on the chosen OS/architecture and its version is recorded.", "how_to_verify": "Record the official app opens on the chosen OS/architecture and its version is recorded. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The official app opens on the chosen OS/architecture and its version is recorded.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The official app opens on the chosen OS/architecture and its version is recorded.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify select the correct installer?", "answer": "The official app opens on the chosen OS/architecture and its version is recorded. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to select the correct installer. The official app opens on the chosen OS/architecture and its version is recorded.", "demo": "Open x.ai/bot downloads. Windows: choose x64/Arm64 from Settings → System → About, run the official installer and launch from Start. macOS: check chip in About This Mac, open the DMG and drag into Applications. Linux: select the official package for your architecture/distribution and install through its supported package route.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate select the correct installer", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Open x.ai/bot downloads. Windows: choose x64/Arm64 from Settings → System → About, run the official installer and launch from Start. macOS: check chip in About This Mac, open the DMG and drag into Applications. Linux: select the official package for your architecture/distribution and install through its supported package route. The official app opens on the chosen OS/architecture and its version is recorded.", "on_screen_text": [ "Select the correct installer", "The official app opens on the chosen OS/architecture and its version is recorded." ], "screen_recording_instructions": [ "Open x.ai/bot downloads. Windows: choose x64/Arm64 from Settings → System → About, run the official installer and launch from Start. macOS: check chip in About This Mac, open the DMG and drag into Applications. Linux: select the official package for your architecture/distribution and install through its supported package route.", "Inspect the result: The official app opens on the chosen OS/architecture and its version is recorded.", "Record the evidence and check each criterion." ], "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 official app opens on the chosen OS/architecture and its version is recorded." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Open x.ai/bot downloads. Windows: choose x64/Arm64 from Settings → System → About, run the official installer and launch from Start. macOS: check chip in About This Mac, open the DMG and drag into Applications. Linux: select the official package for your architecture/distribution and install through its supported package route.", "The official app opens on the chosen OS/architecture and its version is recorded." ] }, "step_id": "L02-S01", "lesson_id": "L02" }, { "title": "Complete account sign-in and name the bot", "purpose": "The app can reopen its last chat. A task in Rental Manager is not a task in BuildBotsBetter; select and verify the title every time.", "user_action": "Sign in personally using the eligible linked account. Create one bot named Practice Reviewer with the job “review one supplied document and draft sourced corrections.” Confirm the visible chat title before sending any task.", "explanation": "The app can reopen its last chat. A task in Rental Manager is not a task in BuildBotsBetter; select and verify the title every time.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "resources": [], "checkpoint": { "what_is_being_checked": "Complete account sign-in and name the bot", "success_condition": "The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "how_to_verify": "Record the app shows Practice Reviewer and the intended account; the bot has one concrete job. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify complete account sign-in and name the bot?", "answer": "The app shows Practice Reviewer and the intended account; the bot has one concrete job. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to complete account sign-in and name the bot. The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "demo": "Sign in personally using the eligible linked account. Create one bot named Practice Reviewer with the job “review one supplied document and draft sourced corrections.” Confirm the visible chat title before sending any task.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate complete account sign-in and name the bot", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Sign in personally using the eligible linked account. Create one bot named Practice Reviewer with the job “review one supplied document and draft sourced corrections.” Confirm the visible chat title before sending any task. The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "on_screen_text": [ "Complete account sign-in and name the bot", "The app shows Practice Reviewer and the intended account; the bot has one concrete job." ], "screen_recording_instructions": [ "Sign in personally using the eligible linked account. Create one bot named Practice Reviewer with the job “review one supplied document and draft sourced corrections.” Confirm the visible chat title before sending any task.", "Inspect the result: The app shows Practice Reviewer and the intended account; the bot has one concrete job.", "Record the evidence and check each criterion." ], "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 app shows Practice Reviewer and the intended account; the bot has one concrete job." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Sign in personally using the eligible linked account. Create one bot named Practice Reviewer with the job “review one supplied document and draft sourced corrections.” Confirm the visible chat title before sending any task.", "The app shows Practice Reviewer and the intended account; the bot has one concrete job." ] }, "step_id": "L03-S01", "lesson_id": "L03" }, { "title": "Set rules, voice and approvals", "purpose": "A persistent teammate benefits from an operating manual. Instructions improve behavior but are not a proven local filesystem guard.", "user_action": "Write a description with the job, supplied source boundary, concise voice and rules: cite the provided source, say unknown when absent, ask before sending messages or editing shared files. Keep secrets and real customer data out of the practice task.", "explanation": "A persistent teammate benefits from an operating manual. Instructions improve behavior but are not a proven local filesystem guard.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [ "delegation.md" ], "expected_result": "The bot description has one job, a voice, a source rule and explicit approval rules.", "resources": [ "delegation.md" ], "checkpoint": { "what_is_being_checked": "Set rules, voice and approvals", "success_condition": "The bot description has one job, a voice, a source rule and explicit approval rules.", "how_to_verify": "Record the bot description has one job, a voice, a source rule and explicit approval rules. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The bot description has one job, a voice, a source rule and explicit approval rules.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The bot description has one job, a voice, a source rule and explicit approval rules.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify set rules, voice and approvals?", "answer": "The bot description has one job, a voice, a source rule and explicit approval rules. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use delegation.md. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to set rules, voice and approvals. The bot description has one job, a voice, a source rule and explicit approval rules.", "demo": "Write a description with the job, supplied source boundary, concise voice and rules: cite the provided source, say unknown when absent, ask before sending messages or editing shared files. Keep secrets and real customer data out of the practice task.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate set rules, voice and approvals", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write a description with the job, supplied source boundary, concise voice and rules: cite the provided source, say unknown when absent, ask before sending messages or editing shared files. Keep secrets and real customer data out of the practice task. The bot description has one job, a voice, a source rule and explicit approval rules.", "on_screen_text": [ "Set rules, voice and approvals", "The bot description has one job, a voice, a source rule and explicit approval rules." ], "screen_recording_instructions": [ "Write a description with the job, supplied source boundary, concise voice and rules: cite the provided source, say unknown when absent, ask before sending messages or editing shared files. Keep secrets and real customer data out of the practice task.", "Inspect the result: The bot description has one job, a voice, a source rule and explicit approval rules.", "Record the evidence and check each criterion." ], "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 bot description has one job, a voice, a source rule and explicit approval rules." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write a description with the job, supplied source boundary, concise voice and rules: cite the provided source, say unknown when absent, ask before sending messages or editing shared files. Keep secrets and real customer data out of the practice task.", "The bot description has one job, a voice, a source rule and explicit approval rules." ] }, "step_id": "L04-S01", "lesson_id": "L04" }, { "title": "Review one tool connection", "purpose": "Connected accounts may expose broader data than the current task. Review scopes before granting access.", "user_action": "Use the app’s connector/tool screen to review the scope of one needed service. Prefer a private test document or supplied text. Approve only the minimum access and record how to revoke it. If no connection is needed, paste the public practice text directly.", "explanation": "Connected accounts may expose broader data than the current task. Review scopes before granting access.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The task uses only its required data and the connection’s access/removal plan is recorded.", "resources": [], "checkpoint": { "what_is_being_checked": "Review one tool connection", "success_condition": "The task uses only its required data and the connection’s access/removal plan is recorded.", "how_to_verify": "Record the task uses only its required data and the connection’s access/removal plan is recorded. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The task uses only its required data and the connection’s access/removal plan is recorded.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The task uses only its required data and the connection’s access/removal plan is recorded.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify review one tool connection?", "answer": "The task uses only its required data and the connection’s access/removal plan is recorded. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to review one tool connection. The task uses only its required data and the connection’s access/removal plan is recorded.", "demo": "Use the app’s connector/tool screen to review the scope of one needed service. Prefer a private test document or supplied text. Approve only the minimum access and record how to revoke it. If no connection is needed, paste the public practice text directly.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate review one tool connection", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Use the app’s connector/tool screen to review the scope of one needed service. Prefer a private test document or supplied text. Approve only the minimum access and record how to revoke it. If no connection is needed, paste the public practice text directly. The task uses only its required data and the connection’s access/removal plan is recorded.", "on_screen_text": [ "Review one tool connection", "The task uses only its required data and the connection’s access/removal plan is recorded." ], "screen_recording_instructions": [ "Use the app’s connector/tool screen to review the scope of one needed service. Prefer a private test document or supplied text. Approve only the minimum access and record how to revoke it. If no connection is needed, paste the public practice text directly.", "Inspect the result: The task uses only its required data and the connection’s access/removal plan is recorded.", "Record the evidence and check each criterion." ], "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 task uses only its required data and the connection’s access/removal plan is recorded." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Use the app’s connector/tool screen to review the scope of one needed service. Prefer a private test document or supplied text. Approve only the minimum access and record how to revoke it. If no connection is needed, paste the public practice text directly.", "The task uses only its required data and the connection’s access/removal plan is recorded." ] }, "step_id": "L05-S01", "lesson_id": "L05" }, { "title": "Verify the document review", "purpose": "The task is small enough to check independently. A confident unsourced answer is a failure, not a successful first run.", "user_action": "Supply this source sentence: “The practice total function sums every item, including repeated values.” Ask the bot to review the false draft “Repeated values should be removed.” Require a sourced correction and forbid external sending.", "explanation": "The task is small enough to check independently. A confident unsourced answer is a failure, not a successful first run.", "estimated_time": "6 min", "action_type": "create", "commands": { "all": "Read this source: The practice total function sums every item, including repeated values. Review this draft: Repeated values should be removed. Return a correction, source evidence and what remains unknown. Do not send, publish or edit anything." }, "command_type": "prompt", "required_inputs": [], "expected_result": "The bot rejects the false draft and cites the supplied statement about repeated values.", "resources": [], "checkpoint": { "what_is_being_checked": "Verify the document review", "success_condition": "The bot rejects the false draft and cites the supplied statement about repeated values.", "how_to_verify": "Record the bot rejects the false draft and cites the supplied statement about repeated values. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The bot rejects the false draft and cites the supplied statement about repeated values.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The bot rejects the false draft and cites the supplied statement about repeated values.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify verify the document review?", "answer": "The bot rejects the false draft and cites the supplied statement about repeated values. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to verify the document review. The bot rejects the false draft and cites the supplied statement about repeated values.", "demo": "Supply this source sentence: “The practice total function sums every item, including repeated values.” Ask the bot to review the false draft “Repeated values should be removed.” Require a sourced correction and forbid external sending.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate verify the document review", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Supply this source sentence: “The practice total function sums every item, including repeated values.” Ask the bot to review the false draft “Repeated values should be removed.” Require a sourced correction and forbid external sending. The bot rejects the false draft and cites the supplied statement about repeated values.", "on_screen_text": [ "Verify the document review", "The bot rejects the false draft and cites the supplied statement about repeated values." ], "screen_recording_instructions": [ "Supply this source sentence: “The practice total function sums every item, including repeated values.” Ask the bot to review the false draft “Repeated values should be removed.” Require a sourced correction and forbid external sending.", "Inspect the result: The bot rejects the false draft and cites the supplied statement about repeated values.", "Record the evidence and check each criterion." ], "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 bot rejects the false draft and cites the supplied statement about repeated values." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Supply this source sentence: “The practice total function sums every item, including repeated values.” Ask the bot to review the false draft “Repeated values should be removed.” Require a sourced correction and forbid external sending.", "The bot rejects the false draft and cites the supplied statement about repeated values." ] }, "step_id": "L06-S01", "lesson_id": "L06" }, { "title": "Ask an unsupported question and reopen the chat", "purpose": "Memory should help continuity without turning absent facts into invented knowledge.", "user_action": "Ask what currency the practice source uses (it does not say). Verify the bot says unknown. Close/reopen the app and select Practice Reviewer explicitly; ask it to summarize its job and source boundary.", "explanation": "Memory should help continuity without turning absent facts into invented knowledge.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The unsupported fact remains unknown and the selected bot retains the intended job/context.", "resources": [], "checkpoint": { "what_is_being_checked": "Ask an unsupported question and reopen the chat", "success_condition": "The unsupported fact remains unknown and the selected bot retains the intended job/context.", "how_to_verify": "Record the unsupported fact remains unknown and the selected bot retains the intended job/context. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The unsupported fact remains unknown and the selected bot retains the intended job/context.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The unsupported fact remains unknown and the selected bot retains the intended job/context.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify ask an unsupported question and reopen the chat?", "answer": "The unsupported fact remains unknown and the selected bot retains the intended job/context. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to ask an unsupported question and reopen the chat. The unsupported fact remains unknown and the selected bot retains the intended job/context.", "demo": "Ask what currency the practice source uses (it does not say). Verify the bot says unknown. Close/reopen the app and select Practice Reviewer explicitly; ask it to summarize its job and source boundary.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate ask an unsupported question and reopen the chat", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Ask what currency the practice source uses (it does not say). Verify the bot says unknown. Close/reopen the app and select Practice Reviewer explicitly; ask it to summarize its job and source boundary. The unsupported fact remains unknown and the selected bot retains the intended job/context.", "on_screen_text": [ "Ask an unsupported question and reopen the chat", "The unsupported fact remains unknown and the selected bot retains the intended job/context." ], "screen_recording_instructions": [ "Ask what currency the practice source uses (it does not say). Verify the bot says unknown. Close/reopen the app and select Practice Reviewer explicitly; ask it to summarize its job and source boundary.", "Inspect the result: The unsupported fact remains unknown and the selected bot retains the intended job/context.", "Record the evidence and check each criterion." ], "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 unsupported fact remains unknown and the selected bot retains the intended job/context." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Ask what currency the practice source uses (it does not say). Verify the bot says unknown. Close/reopen the app and select Practice Reviewer explicitly; ask it to summarize its job and source boundary.", "The unsupported fact remains unknown and the selected bot retains the intended job/context." ] }, "step_id": "L07-S01", "lesson_id": "L07" }, { "title": "Draft the check-in routine", "purpose": "Frequent routines can consume usage and produce noise. Use an event or daily check rather than a needlessly frequent polling loop.", "user_action": "Write a numbered daily routine: read supplied review queue, cite sources, flag blockers, draft summary, request approval before sending. Set an explicit frequency and stop condition. Do not enable an external-action routine during this practice task.", "explanation": "Frequent routines can consume usage and produce noise. Use an event or daily check rather than a needlessly frequent polling loop.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "resources": [], "checkpoint": { "what_is_being_checked": "Draft the check-in routine", "success_condition": "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "how_to_verify": "Record the routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify draft the check-in routine?", "answer": "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to draft the check-in routine. The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "demo": "Write a numbered daily routine: read supplied review queue, cite sources, flag blockers, draft summary, request approval before sending. Set an explicit frequency and stop condition. Do not enable an external-action routine during this practice task.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate draft the check-in routine", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Write a numbered daily routine: read supplied review queue, cite sources, flag blockers, draft summary, request approval before sending. Set an explicit frequency and stop condition. Do not enable an external-action routine during this practice task. The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "on_screen_text": [ "Draft the check-in routine", "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule." ], "screen_recording_instructions": [ "Write a numbered daily routine: read supplied review queue, cite sources, flag blockers, draft summary, request approval before sending. Set an explicit frequency and stop condition. Do not enable an external-action routine during this practice task.", "Inspect the result: The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule.", "Record the evidence and check each criterion." ], "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 routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Write a numbered daily routine: read supplied review queue, cite sources, flag blockers, draft summary, request approval before sending. Set an explicit frequency and stop condition. Do not enable an external-action routine during this practice task.", "The routine plan has numbered actions, frequency, cost limit, approval boundary and stop rule." ] }, "step_id": "L08-S01", "lesson_id": "L08" }, { "title": "Write a repeatable onboarding checklist", "purpose": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "user_action": "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.", "explanation": "The September 23 BuildBotsBetter profile wipe removed Desktop, Documents and hidden agent memory together. Repeatable onboarding protects the knowledge needed to recover.", "estimated_time": "6 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 checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification. Include the actual result or a specific observation; do not paste credentials.", "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." ], "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." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify write a repeatable onboarding checklist?", "answer": "The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use onboarding-checklist.md. Work in the same practice folder." } ], "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 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.", "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": "What is the current directory, exact command, exit code and complete output?" }, "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 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.", "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 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.", "Inspect the result: The checklist contains a concrete path and owner for rules, memory, permissions, guard, backup, restore and final verification.", "Record the evidence and check each criterion." ], "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": "L09-S01", "lesson_id": "L09" }, { "title": "Demonstrate the variable-path limit safely", "purpose": "A command-text hook can miss a target computed inside a script or variable. This demonstrator checks resolved paths but is not an operating-system sandbox. For a real operation, enforce the resolved boundary at the operation itself; symlinks and races still require care.", "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": "A command-text hook can miss a target computed inside a script or variable. This demonstrator checks resolved paths but is not an operating-system sandbox. For a real operation, enforce the resolved boundary at the operation itself; symlinks and races still require care.", "estimated_time": "6 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 gUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed. Include the actual result or a specific observation; do not paste credentials.", "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." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify demonstrate the variable-path limit safely?", "answer": "GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use workspace_guard.py. Work in the same practice folder." } ], "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": "What is the current directory, exact command, exit code and complete output?" }, "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.", "Inspect the result: GUARD PASS reports inside allowed and profile, outside, variable-derived profile and workspace root denied; no deletion was executed.", "Record the evidence and check each criterion." ], "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": "L09-S02", "lesson_id": "L09" }, { "title": "Verify the actual protection in your tool", "purpose": "A broken hook that blocks everything can look like protection. Some tools fail open when hooks fail. Codex hook changes need review/trust; Grok Build needs its own deny protocol; Antigravity uses a different JSON protocol. Never treat a prompt rule or an inactive hook as enforcement.", "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; 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.", "explanation": "A broken hook that blocks everything can look like protection. Some tools fail open when hooks fail. Codex hook changes need review/trust; Grok Build needs its own deny protocol; Antigravity uses a different JSON protocol. Never treat a prompt rule or an inactive hook as enforcement.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "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 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. Include the actual result or a specific observation; do not paste credentials.", "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." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I install a guard for this tool?", "answer": "Use the linked BBB safety reference for the exact tool/version protocol. Merge into the existing hooks instead of overwriting settings. Review/trust the hook if required, then verify a harmless call and a denied dry-run. The workspace_guard.py file is a teaching demonstration, not a universal hook adapter." }, { "question": "Does Grok Bot have a working local delete guard?", "answer": "The project’s live September 29 tests found no working shell hook. Restrict the tasks and workspace you hand it, keep independent backups, and do not claim local deletion is guarded." } ], "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": "What is the current directory, exact command, exit code and complete output?" }, "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; 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.", "Inspect the 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.", "Record the evidence and check each criterion." ], "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": "L09-S03", "lesson_id": "L09" }, { "title": "Enable a real backup of memory and project files", "purpose": "System Restore alone is not a personal-file backup. Previous Versions can disappear as shadow storage fills; OneDrive’s common-folder backup omits hidden agent folders.", "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.", "explanation": "System Restore alone is not a personal-file backup. Previous Versions can disappear as shadow storage fills; OneDrive’s common-folder backup omits hidden agent folders.", "estimated_time": "6 min", "action_type": "command", "commands": { "windows": ".\\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 a backup on another drive includes the tool’s user settings and memory folder and this project, and a successful schedule/time is recorded. Include the actual result or a specific observation; do not paste credentials.", "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": [], "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." }, "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": "Can you create a scratch file on the actual second drive?", "fix": "Mount the drive and choose an accessible backup directory. Inspect every error; robocopy codes 8 and higher are failures.", "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": "How do I verify enable a real backup of memory and project files?", "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. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use profile-backup.ps1, profile-backup.sh, onboarding-checklist.md. Work in the same practice folder." } ], "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": "Can you create a scratch file on the actual second drive?" }, "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.", "Inspect the 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.", "Record the evidence and check each criterion." ], "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": "L09-S04", "lesson_id": "L09" }, { "title": "Practice a hash-verified restore", "purpose": "A backup becomes useful only when restoration has been practiced. A same-volume practice copy proves the procedure but not protection against disk failure.", "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": "A backup becomes useful only when restoration has been practiced. A same-volume practice copy proves the procedure but not protection against disk failure.", "estimated_time": "6 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 rESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch. Include the actual result or a specific observation; do not paste credentials.", "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." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify practice a hash-verified restore?", "answer": "RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use restore_drill.py. Work in the same practice folder." } ], "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": "What is the current directory, exact command, exit code and complete output?" }, "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.", "Inspect the result: RESTORE PASS contains matching hashes; the actual memory file is readable after restoration into scratch.", "Record the evidence and check each criterion." ], "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": "L09-S05", "lesson_id": "L09" }, { "title": "Reopen the intended bot", "purpose": "Never assume the app opens the same chat you intended. The desktop profile path depends on the installer/build; locate it through your installation and include it in the backup checklist.", "user_action": "Launch the app, select Practice Reviewer, verify the visible title and account, then ask for the current source boundary and next reviewed task. Inspect the routine state before relying on a scheduled run.", "explanation": "Never assume the app opens the same chat you intended. The desktop profile path depends on the installer/build; locate it through your installation and include it in the backup checklist.", "estimated_time": "6 min", "action_type": "inspect", "commands": { "all": "" }, "command_type": "shell", "required_inputs": [], "expected_result": "The selected teammate, job, source boundary and routine state are verified after reopening.", "resources": [], "checkpoint": { "what_is_being_checked": "Reopen the intended bot", "success_condition": "The selected teammate, job, source boundary and routine state are verified after reopening.", "how_to_verify": "Record the selected teammate, job, source boundary and routine state are verified after reopening. Include the actual result or a specific observation; do not paste credentials.", "criteria": [ "The selected teammate, job, source boundary and routine state are verified after reopening.", "I can repeat this action from the saved input." ], "tokens": [], "user_visible_success_message": "Evidence saved. The selected teammate, job, source boundary and routine state are verified after reopening.", "failure_message": "Compare the observed output with the required result before continuing.", "troubleshooting_path": "Open the help for this step." }, "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 is the current directory, exact command, exit code and complete output?", "fix": "Compare the input filename and working directory with this step. Rerun only after correcting that difference.", "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": "How do I verify reopen the intended bot?", "answer": "The selected teammate, job, source boundary and routine state are verified after reopening. Keep the command or observation with your evidence." }, { "question": "Which files do I need for this step?", "answer": "Use your saved work from the previous step. Work in the same practice folder." } ], "quiz": null, "coach": { "intro": "We are going to reopen the intended bot. The selected teammate, job, source boundary and routine state are verified after reopening.", "demo": "Launch the app, select Practice Reviewer, verify the visible title and account, then ask for the current source boundary and next reviewed task. Inspect the routine state before relying on a scheduled run.", "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": "What is the current directory, exact command, exit code and complete output?" }, "video": { "purpose": "Demonstrate reopen the intended bot", "duration_target": "45–75 seconds", "visual_type": "step walkthrough with optional browser narration; no rendered video is claimed", "narration_script": "Launch the app, select Practice Reviewer, verify the visible title and account, then ask for the current source boundary and next reviewed task. Inspect the routine state before relying on a scheduled run. The selected teammate, job, source boundary and routine state are verified after reopening.", "on_screen_text": [ "Reopen the intended bot", "The selected teammate, job, source boundary and routine state are verified after reopening." ], "screen_recording_instructions": [ "Launch the app, select Practice Reviewer, verify the visible title and account, then ask for the current source boundary and next reviewed task. Inspect the routine state before relying on a scheduled run.", "Inspect the result: The selected teammate, job, source boundary and routine state are verified after reopening.", "Record the evidence and check each criterion." ], "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 selected teammate, job, source boundary and routine state are verified after reopening." ], "bot_position": "right sidebar", "bot_expression": "calm", "transition": "Continue after checkpoint", "captions": [ "Launch the app, select Practice Reviewer, verify the visible title and account, then ask for the current source boundary and next reviewed task. Inspect the routine state before relying on a scheduled run.", "The selected teammate, job, source boundary and routine state are verified after reopening." ] }, "step_id": "L10-S01", "lesson_id": "L10" } ], "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-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}\nmkdir -p \"$dest\"\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" } ], "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" ], "success_conditions": [ "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "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": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "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": "Set Up Grok Bot | BuildBotsBetter", "SEO_description": "A correctly selected Grok Bot teammate with a written job, reviewed tool access, a verified private task, a bounded routine plan and a recovery checklist.", "SEO_keywords": [ "setup-grok-bot", "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": [ "A real desktop installation, eligible sign-in and private task must be exercised before this setup receives a verified A.", "BBB tests found no working local shell guard for Grok Bot; local prompt rules do not establish deletion protection." ] }, "sources": [ { "title": "Official Grok Bot get started", "url": "https://docs.x.ai/grok-bot/get-started" }, { "title": "Grok Bot official downloads", "url": "https://x.ai/bot" }, { "title": "BBB live guard tests and limitation", "url": "../../../../bots/safety/README.md" } ], "known_uncertainties": [ "A real desktop installation, eligible sign-in and private task must be exercised before this setup receives a verified A.", "BBB tests found no working local shell guard for Grok Bot; local prompt rules do not establish deletion protection." ] }