{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "documents": [
    {
      "id": "factory-factory-loop",
      "slug": "factory-loop",
      "title": "A trustworthy software factory loop",
      "summary": "Bound one recurring task, name the consequential action, and earn autonomy with observable evidence.",
      "category": "Principles",
      "tags": [
        "factory",
        "safety",
        "receipts"
      ],
      "sources": [
        {
          "label": "Software factory operating model",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop"
        }
      ],
      "sourceUnits": [
        "index.html#factory-stages-and-guided-path",
        "learn.html#q1-factory-loop",
        "reference.html#evidence-status"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 848,
      "url": "/topics/factory-factory-loop/",
      "markdownUrl": "/markdown/factory-factory-loop.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-factory-loop.json",
      "headings": [
        {
          "id": "the-unit-of-work-is-a-loop-not-an-agent",
          "text": "The unit of work is a loop, not an agent",
          "level": 2
        },
        {
          "id": "put-each-kind-of-rule-in-its-proper-place",
          "text": "Put each kind of rule in its proper place",
          "level": 2
        },
        {
          "id": "choose-a-route-by-the-problem",
          "text": "Choose a route by the problem",
          "level": 2
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "bound-one-factory-loop",
          "text": "Bound one factory loop",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        },
        {
          "id": "evidence-limits-that-matter",
          "text": "Evidence limits that matter",
          "level": 2
        }
      ],
      "markdown": "# A trustworthy software factory loop\n\nBound one recurring task, name the consequential action, and earn autonomy with observable evidence.\n\n## The unit of work is a loop, not an agent\n\nA software factory is not a pile of agents. The agent is one machine inside an inspectable loop:\n\n**Input → Boundary → Action → Evidence → Decision → Receipt.**\n\nStart with one recurring task and one costly failure. Define the minimum context, permission boundary, exact human gate, and success evidence before adding autonomy. A gate is a named stop, named evidence, and explicit approval before a consequential action—not a request to review something eventually.\n\nThe operating stages are **Bound → Compose → Run → Verify → Preserve → Promote**:\n\n- **Bound:** state the desired outcome, inputs, exclusions, and the first expensive, destructive, public, or hard-to-reverse action.\n- **Compose:** gather current, relevant evidence that changes the decision, implementation, or verification; do not equate volume with completeness.\n- **Run:** execute the smallest reversible experiment inside the agreed permission boundary.\n- **Verify:** demand the exact observable signal that proves the result; an agent saying “done” is not that signal.\n- **Preserve:** save the outcome, settled decision, rejection reason, failed attempts, and repeatable check so another session can continue from evidence.\n- **Promote:** automate only after repeated manual receipts establish that the signal is useful, owned, affordable, and recoverable.\n\n## Put each kind of rule in its proper place\n\nRepository files explain stable intent. Launch wrappers normalize repeated choices. Command decorators bring warnings to the moment of action. Human gates protect consequential work. Automated checks prove the condition they actually measure. None substitutes for the others.\n\nSafety is a layered design, not a permission-bypass switch. A shell function that can be bypassed with `command` is guidance with teeth, not confinement. A stripped prompt context is not a filesystem or network sandbox. A dry run or stub can prove wiring without proving behavior against a real service.\n\n## Choose a route by the problem\n\nA complete first pass connects the core boundary audit, environment policy, annotated image, focused context packet, repeatable flow, structural alternatives, independent reasoning, and product vision. A quick start takes the core loop, one visual task, and a small set of alternatives. A problem-led route enters at the current bottleneck:\n\n- **Control and safety:** bound the task, place policy near the action, make proof visible.\n- **Prompt and context:** use visual evidence, compose a focused packet, promote repeated prompts into inspectable flows.\n- **Design and taste:** expose structural alternatives and preserve why one won.\n- **Continuity and debugging:** recover trustworthy state and join human testimony to runtime facts.\n- **Advanced reasoning and video:** escalate a hard decision, not an entire workflow by default.\n- **Vision and automation:** state durable direction, promote proven signals, and keep unresolved work explicit.\n\nFor each topic, move through **orientation → concept → evidence → practice → reflection → next action**. Copying a prompt, attempting it, and verifying its result are separate states. “Now” establishes the core loop; “Next” makes it repeatable; “Later” adds expensive or specialized capabilities; “Reference” retains unresolved status.\n\n## Operating practice\n\n### Bound one factory loop\n\n#### What to notice\n\nTurn one recurring task into an inspectable loop with inputs, permissions, proof, a **human gate**, and a **durable receipt**.\n\n#### Try this\n\nWrite Input → Boundary → Action → Evidence → Decision → Receipt for one task you already repeat.\n\n> “If the agents can't see it, it doesn't exist.”\n\nJohn Lindquist · [00:23:25](https://proud-anchor-53zn.here.now/watch.html?t=1405#recording-player)\n\n#### Concept\n\nA software factory is not a pile of agents. The agent is one machine inside the loop. Start with the smallest reversible bet, then name the exact action that must stop for human approval.\n\n#### Reflection\n\nA gate is not “review this sometime.” It is a named stop, named evidence, and explicit approval before a consequential action.\n\n**Recording evidence:** listen at 00:15:52.\n\n> “Alignment is the key word here. Is the agent aligned with your vision?”\n\nJohn Lindquist · [00:32:52](https://proud-anchor-53zn.here.now/watch.html?t=1972#recording-player)\n\n[Open How Agentic Work Is Evolving](https://hallowed-entry-96xv.here.now/)\n\n#### Links shared for this topic\n\n- [Workshop agenda](https://ember-bodhi-scrr.here.now/) — The original workshop sequence and setup hub.\n- [Coding with Agents field guide](https://kindly-mirage-ejqd.here.now/) — The earlier field guide that grounded the workshop’s operating principles.\n- [Cursor Origin](https://cursor.com/origin) — An autonomous coding-agent product discussed during the opening model survey.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=952#q1-factory-loop)\n\n## Evidence limits that matter\n\nA file appearing, a command running, and a check passing are separate events. Preserve failed attempts instead of upgrading them into success. The environment demonstration surfaced diagnostics, and the recorded MDFlow wrapper exercise did not become a clean success. Those are failure-aware examples, not universal installation proofs.\n\nTool versions, model names, prices, subscription eligibility, limits, and predictions are contextual claims from the recorded discussion—not current purchasing guidance. Current dotfiles and comparative model-cost guidance remained unresolved. The Markers material is a prepared follow-up, not a dedicated recorded section.\n\nKeep exact published resource links separate from uncertain text read off a screen. A transcript establishes what was said; a recording can reveal visible action; a prepared recipe establishes intended behavior; only the appropriate check establishes success."
    },
    {
      "id": "foundations-contracts-state-machines-and-code",
      "slug": "contracts-state-machines-and-code",
      "title": "Preserve contracts and state machines while code changes",
      "summary": "Write natural-language contracts and use video as requirements; Treat code as a throwaway artifact behind a state machine + modules; Maintain living guardrails while treating generated code as disposable and ideas as durable.",
      "category": "Principles",
      "tags": [
        "contracts",
        "state machines",
        "architecture"
      ],
      "sources": [
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#11/objectives",
        "oracle/11-references.json#recap",
        "oracle/11-references.json#concepts/0",
        "oracle/11-references.json#concepts/1",
        "oracle/11-references.json#concepts/2",
        "oracle/11-references.json#concepts/3",
        "oracle/11-references.json#concepts/4",
        "oracle/11-references.json#concepts/5",
        "oracle/11-references.json#references",
        "oracle/11-references.json#recommendations",
        "oracle/11-interactive.json#intro",
        "oracle/11-interactive.json#checklist",
        "oracle/11-interactive.json#challenges",
        "oracle/11-interactive.json#quiz",
        "oracle/11-interactive.json#reflect",
        "oracle/11-references.json#goDeeper",
        "materials/exercises.md#Chunk-11",
        "materials/qa-index.md#Q058",
        "materials/qa-index.md#Q059",
        "materials/qa-index.md#Q060",
        "materials/qa-index.md#Q061",
        "materials/qa-index.md#Q062",
        "materials/qa-index.md#Q063",
        "materials/qa-index.md#Q064",
        "materials/qa-index.md#Q065",
        "materials/qa-index.md#Q066",
        "final/qa-index.md#Chunk-11",
        "materials/keyframes.md#Chunk-11",
        "lesson-11.html#resource-packet",
        "lesson-11.html#clip-map",
        "lesson-11.html#recording",
        "lesson-11.html#Workshop-through-line"
      ],
      "collection": "foundations",
      "categoryId": "principles",
      "wordCount": 3443,
      "url": "/topics/foundations-contracts-state-machines-and-code/",
      "markdownUrl": "/markdown/foundations-contracts-state-machines-and-code.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-contracts-state-machines-and-code.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "natural-language-contracts",
          "text": "Natural-Language Contracts",
          "level": 3
        },
        {
          "id": "video-as-requirements",
          "text": "Video-as-Requirements",
          "level": 3
        },
        {
          "id": "diff-driven-review",
          "text": "Diff-Driven Review",
          "level": 3
        },
        {
          "id": "state-machines-and-modular-boundaries",
          "text": "State Machines and Modular Boundaries",
          "level": 3
        },
        {
          "id": "living-guardrails",
          "text": "Living Guardrails",
          "level": 3
        },
        {
          "id": "disposable-code-durable-ideas",
          "text": "Disposable Code, Durable Ideas",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "openai-codex",
          "text": "OpenAI Codex",
          "level": 3
        },
        {
          "id": "agents-md",
          "text": "AGENTS.md",
          "level": 3
        },
        {
          "id": "video-capable-multimodal-models",
          "text": "Video-capable multimodal models",
          "level": 3
        },
        {
          "id": "git-diffs",
          "text": "Git diffs",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "contract-before-code",
          "text": "Contract Before Code",
          "level": 3
        },
        {
          "id": "video-qa-story",
          "text": "Video QA Story",
          "level": 3
        },
        {
          "id": "state-machine-boundary-pass",
          "text": "State Machine Boundary Pass",
          "level": 3
        },
        {
          "id": "diff-injection-review",
          "text": "Diff Injection Review",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "what-is-the-main-value-of-a-natural-language-contract-in-an-agent-first-workflow",
          "text": "What is the main value of a natural-language contract in an agent-first workflow?",
          "level": 3
        },
        {
          "id": "why-did-john-frame-video-recordings-as-useful-requirements-artifacts",
          "text": "Why did John frame video recordings as useful requirements artifacts?",
          "level": 3
        },
        {
          "id": "in-john-s-diff-driven-review-loop-what-is-the-most-important-artifact-to-inspect-after-an-agent-run",
          "text": "In John’s diff-driven review loop, what is the most important artifact to inspect after an agent run?",
          "level": 3
        },
        {
          "id": "a-project-suddenly-grows-by-30-000-generated-lines-according-to-john-what-makes-that-complexity-manageable",
          "text": "A project suddenly grows by 30,000 generated lines. According to John, what makes that complexity manageable?",
          "level": 3
        },
        {
          "id": "what-is-the-best-way-to-maintain-an-agents-md-or-claude-md-file",
          "text": "What is the best way to maintain an agents.md or claude.md file?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "did-you-show-a-goal-example-for-the-pacx-i-think-i-will-convert-from-my-test-to-qa-packages-that-are-stable",
          "text": "Did you show a goal example for the PACX? I think I will convert from my test to QA packages that are stable.",
          "level": 3
        },
        {
          "id": "to-followup-what-you-said-before-in-general-for-others-in-how-they-can-become-ai-literate-but-also-live-in-a-new-world-with-ai-and-find-their-new-role-with-intelligence-you-mentioned-going-camping-do-you-have-general-questions-you-get-from-others-and-answers-to-those-bigger-questions",
          "text": "To followup what you said before, in general for others in how they can become ai literate but also live in a new world with ai and find their new role with intelligence, you mentioned going camping..., do you have general questions you get from others, and answers to those bigger questions?",
          "level": 3
        },
        {
          "id": "ya-that-was-my-question-use-ai-to-go-deeper-in-the-domain-we-have-mastered-or-use-it-to-learn-new-skills-and-go-wide-i-see-arguments-for-both",
          "text": "Ya that was my question — use ai to go deeper in the domain we have mastered or use it to learn new skills and go wide. I see arguments for both.",
          "level": 3
        },
        {
          "id": "can-you-scare-us-give-us-your-thoughts-on-disruptions-speculate-for-businesses-for-developers",
          "text": "Can you scare us? give us your thoughts on disruptions? speculate? for businesses, for developers?",
          "level": 3
        },
        {
          "id": "you-hit-this-earlier-but-any-final-thoughts-on-this-new-normal-where-a-project-turns-into-30k-lines-of-code-over-night-how-to-manage-that-complexity-high-level-thoughts",
          "text": "You hit this earlier but any final thoughts on this new normal where a project turns into 30k lines of code over night. How to manage that complexity (high level thoughts)",
          "level": 3
        },
        {
          "id": "do-you-use-agents-md-or-claude-md-guardrails-md-don-t-do-this-tool-usage-specificity-etc",
          "text": "Do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc",
          "level": 3
        },
        {
          "id": "how-much-time-should-a-junior-engineer-invest-in-learning-a-programming-language-how-should-a-senior-invest-in-advancing-their-skills-and-programming-language-ecosystem",
          "text": "How much time should a junior engineer invest in learning a programming language? [...] How should a senior invest in advancing their skills and programming language ecosystem?",
          "level": 3
        },
        {
          "id": "is-it-the-facebook-backlog-or-the-episodelist-of-black-mirror",
          "text": "Is it the facebook backlog or the episodelist of black mirror?",
          "level": 3
        },
        {
          "id": "are-you-familiar-with-actor-model-relates-to-your-state-machine-comment",
          "text": "Are you familiar with actor model? relates to your state machine comment",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        },
        {
          "id": "durable-operating-principles",
          "text": "Durable operating principles",
          "level": 2
        }
      ],
      "markdown": "# Preserve contracts and state machines while code changes\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe architectural priority is shifting your loyalty away from individual generated code artifacts and toward durable structures: clear natural-language goals, recorded human behavior, reviewable diffs, state-machine boundaries, isolated modules, and living project guardrails. John’s big point is blunt: tools, models, harnesses, plugins, and even code can change or be regenerated, so the professional edge is defining intent, preserving evidence, reviewing the concrete diff, and keeping the architecture understandable.\n\n## Working outcomes\n\n- Write natural-language contracts and use video as requirements\n- Treat code as a throwaway artifact behind a state machine + modules\n- Maintain living guardrails while treating generated code as disposable and ideas as durable\n\n## Concepts and consequences\n\n### Natural-Language Contracts\n\nA natural-language contract is a plain-English description of what a tool, app, or agent is supposed to do. John frames this as an \"agent first\" mindset: define the work in language so the underlying tool can change without destroying the workflow.\n\n**Why it matters:** It keeps you from overfitting to today’s specific tool, harness, plugin, or workflow. The portable asset is the intent.\n\n### Video-as-Requirements\n\nJohn recommends recording yourself or users actually using the app while speaking intent out loud. The recording captures clicks, typing, layout changes, responsive behavior, and what the person wanted from the app.\n\n**Why it matters:** It captures human interaction that is hard to fully express in written specs. A video-capable model can help turn that usage into requirements, goals, and QA stories.\n\n### Diff-Driven Review\n\nJohn reduces an agent run to a simple equation: prompt plus agent, harness, and skills equals diff. The diff is the concrete artifact worth reviewing, testing against, and handing to a fresh session for critique.\n\n**Why it matters:** It gives you a clean review loop. A second agent can inspect the goal and diff without inheriting the first agent’s assumptions.\n\n### State Machines and Modular Boundaries\n\nWhen a codebase can grow by tens of thousands of lines overnight, John says the safety comes from structure: isolated modules and business logic that is navigable through state machines.\n\n**Why it matters:** These boundaries let humans and agents digest, regenerate, refactor, or replace implementation details without losing the shape of the product.\n\n### Living Guardrails\n\nFiles like agents.md or claude.md should stay fairly minimal and evolve with the project. John suggests reviewing recent commits, learning from mistakes, and iterating on the agent instructions over time.\n\n**Why it matters:** Mistakes become useful artifacts when they update the project’s guardrails. The file should capture real project knowledge, not a giant upfront rulebook.\n\n### Disposable Code, Durable Ideas\n\nJohn explicitly says not to get too attached to a specific workflow or generated code artifact. A plugin, hook, or implementation can be generated quickly and thrown away later.\n\n**Why it matters:** The idea, boundary, state machine, module structure, and product intent matter more than the exact code the current agent happened to write.\n\n## Reference tools and resources\n\n### OpenAI Codex\n\nThe coding-agent environment John referred to when discussing skills, agents.md, generated code, and diffs.\n\n**Use when:** Use it when you want an agent to work inside a project, then review the resulting diff as the main artifact of the run.\n\n[Reference](https://github.com/openai/codex)\n\n### AGENTS.md\n\nA project-level instruction file that gives coding agents local context, conventions, and constraints.\n\n**Use when:** Use it as a small, evolving guardrail file; John recommended reviewing recent commits and updating it with lessons from mistakes.\n\n[Reference](https://developers.openai.com/codex/guides/agents-md)\n\n### Video-capable multimodal models\n\nJohn named Gemini as an example of a model that can understand videos of app usage.\n\n**Use when:** Use this kind of model when narrated screen recordings contain richer requirements than a written prompt alone.\n\nsearch: multimodal video understanding app requirements\n\n### Git diffs\n\nThe concrete artifact John treated as the output of an agent run: prompt plus agent, harness, and skills equals diff.\n\n**Use when:** Use diffs for review, testing discussions, logs, and clean-session critique.\n\nsearch: git diff\n\n## Recommendations and best practices\n\n- Define goals and tool contracts in natural language so the underlying agent, harness, or implementation can change.\n- Record real app usage with narration; treat the video as a requirements and QA artifact, not just a demo.\n- Do not over-specify exactly how the agent must prove success; keep your own QA judgment in the loop.\n- Review diffs as the primary artifact of an agent run, then give the goal and diff to a fresh session to find missed cases or tests.\n- Keep generated code disposable, but keep product intent, state machines, module boundaries, and names stable enough to reason about.\n- Use agents.md or claude.md as living documents: update them from recent commits, repeated mistakes, and real project constraints.\n- Stay flexible; do not define yourself too tightly by one language, framework, tool, harness, or generated implementation.\n\n## Practice and acceptance criteria\n\nPractice treating generated code as replaceable while making your intent, evidence, architecture, diffs, and guardrails durable.\n\n### Checklist\n\n1. Choose one feature or workflow in a real project and write a short natural-language contract describing the goal, desired behavior, and what would convince you it works.\n2. Record a 1–3 minute narrated walkthrough of the current app or target behavior, saying what matters as you click, type, resize, wait, or notice broken behavior.\n3. Ask a video-capable model to extract requirements, user actions, expected behavior, and QA stories from the video, then review the output with your own judgment.\n4. Rewrite the feature's core behavior as a state machine with named states and transitions, then identify which modules should own which responsibilities.\n5. Create or revise agents.md or claude.md with only useful project-specific guidance from recent commits, repeated mistakes, architecture boundaries, and discovered constraints.\n6. Run an agent on a small isolated module using the contract, state machine, and guardrail file as context, then inspect the Git diff as the primary artifact.\n7. Start a fresh agent session and give it the original goal plus the diff only; ask it to identify missing tests, risky assumptions, and behavior that may violate the contract.\n\n### Contract Before Code\n\n**Difficulty:** Easy\n\nPick a small feature request and write a natural-language contract before opening the code. Include what the user wants, what must not change, what counts as done, and what evidence would convince you it works.\n\n**Done when:** A fresh agent or teammate can read the contract and correctly describe the expected behavior without seeing your implementation notes.\n\n### Video QA Story\n\n**Difficulty:** Medium\n\nRecord yourself using a real app flow while narrating intent, then ask a video-capable model to turn the recording into requirements, expected behavior, and QA stories.\n\n**Done when:** The resulting QA story captures a meaningful user outcome from the video, not just a brittle click path or superficial selector.\n\n### State Machine Boundary Pass\n\n**Difficulty:** Medium\n\nTake a messy feature with branching behavior and describe it as a state machine. Then split the surrounding implementation into clear modules with separate responsibilities.\n\n**Done when:** A human or agent can look at the state machine and module names and understand the shape of the behavior without reading every implementation line.\n\n### Diff Injection Review\n\n**Difficulty:** Hard\n\nLet an agent implement a bounded change, then copy only the original goal and resulting Git diff into a fresh session. Ask the new session to critique the change, propose missing tests, and flag contract violations.\n\n**Done when:** The second review finds at least one concrete risk, missing test, or confirmation point that improves your final merge decision.\n\n## Questions to test understanding\n\n### What is the main value of a natural-language contract in an agent-first workflow?\n\n- **A.** It replaces the need to review generated code.\n- **B.** It preserves the intended behavior even as tools, agents, or implementation details change.\n- **C.** It guarantees the agent will choose the best library automatically.\n- **D.** It turns every requirement into a deterministic browser test.\n\n**Answer: B.** The contract is the portable asset: it defines what should happen in plain language so the underlying harness, agent, tool, or code can change without losing the workflow's intent.\n\n### Why did John frame video recordings as useful requirements artifacts?\n\n- **A.** Because videos are easier to store than written specs.\n- **B.** Because videos eliminate the need for human QA judgment.\n- **C.** Because narrated app usage captures human intent, clicks, layout behavior, and outcomes that text often misses.\n- **D.** Because videos always produce more stable selectors than browser automation tests.\n\n**Answer: C.** A narrated walkthrough can show what the user actually does and cares about. John emphasized that clicking, typing, resizing, and talking through the desired behavior captures requirements that are hard to express as text alone.\n\n### In John’s diff-driven review loop, what is the most important artifact to inspect after an agent run?\n\n- **A.** The agent's full chat transcript.\n- **B.** The exact model name used during the session.\n- **C.** The generated Git diff, plus any tests or behavioral changes it implies.\n- **D.** The longest file the agent edited.\n\n**Answer: C.** John described the useful output of an agent run as the concrete diff. Reviewing that diff, and giving it to a fresh session for critique, helps avoid inheriting the first session's assumptions.\n\n### A project suddenly grows by 30,000 generated lines. According to John, what makes that complexity manageable?\n\n- **A.** Reading every generated line before allowing any merge.\n- **B.** Keeping all business logic in one large file so the agent has full context.\n- **C.** Relying on comments to explain generated code after the fact.\n- **D.** Using isolated modules and state machines as stable structural boundaries.\n\n**Answer: D.** John said the two anchors are modular structure and state machines. If responsibilities are separated and business logic is navigable through states, humans and agents can digest the project without memorizing every generated line.\n\n### What is the best way to maintain an agents.md or claude.md file?\n\n- **A.** Keep it fairly minimal and update it when real mistakes, recent commits, or project constraints reveal useful lessons.\n- **B.** Fill it upfront with every coding preference you can think of.\n- **C.** Use it only for generic style rules that apply to every repository.\n- **D.** Avoid changing it once the first version works.\n\n**Answer: A.** John did not give strict rules for agents.md. He described it as something that should evolve with the project, especially by learning from mistakes and reviewing recent commits.\n\n## Reflection prompts\n\n- In your current codebase, what should be treated as durable: product intent, state machines, module boundaries, tests, guardrails, or the generated code itself?\n- Where do agents repeatedly make the same kind of mistake in your projects, and what small agents.md or claude.md update would help prevent that without becoming noisy?\n- Which side of the future engineering path are you actively building right now: deeper hyper-expert judgment, broader project-creator leverage, or a deliberate mix of both?\n\n## Further applications\n\n1. Record a short narrated app walkthrough, then ask a video-capable model to extract the user goals, actions, expected behavior, and QA stories.\n2. Run a diff injection review: give a clean agent session only the original goal and the previous agent’s diff, then ask what tests or risks are missing.\n3. Rewrite one complex feature as a state machine with named states and transitions, then map the related implementation into isolated modules.\n4. Review recent commits and agent mistakes, then add only the most useful project-specific lessons to agents.md or claude.md.\n5. Map your own growth into two possible tracks: hyper-expert depth in a critical technical area and broader project-creator leverage with agents.\n\n## Applied exercises\n\nThe Diff Injection Test Routine: Start a completely isolated, clean repository session. Take a structural Git diff produced by a previous development agent run and supply it to an entirely fresh agent instance. Instruct the new agent to inspect the diff in isolation to map out potential logic omissions, design flaws, or generate parallel automated test scripts.\n\nState Machine Scaffolding Challenge: Take a complex application feature that typically demands several thousand lines of arbitrary code and map it out strictly as a deterministic state machine using human-readable state configurations and events. Feed this explicit state map to an agent to automatically implement the underlying procedural code. Evaluate how quickly the agent updates the feature when you alter only the top-level state machine boundaries.\n\n## Questions and answers\n\n### Did you show a goal example for the PACX? I think I will convert from my test to QA packages that are stable.\n\nYes, the Pack X skill example was bundled inside the Oracle tool configuration shown at the very beginning of the workshop day. Developers can utilize the built-in Codex create skill module to automatically ingest local CLI tools and map them out for agent execution.\n\nJohn verifies that a working example of the PackX tool execution skill was compiled inside the Oracle system harness configuration, and advises scrolling back to the footage from the beginning of the morning session to track its initial execution step-by-step.\n\n### To followup what you said before, in general for others in how they can become ai literate but also live in a new world with ai and find their new role with intelligence, you mentioned going camping..., do you have general questions you get from others, and answers to those bigger questions?\n\nJohn notes he deliberately minimizes deep discussions about agentic futures with people outside the immediate AI space because the actual scale of near-term disruption sounds unbelievable or alarming. He emphasizes that the path forward requires extreme individual flexibility and an openness to adapting to entirely new methodologies, highlighting how jobs structured around legacy knowledge retrieval (like English professors) face immense pressure to re-evaluate their core function.\n\n### Ya that was my question — use ai to go deeper in the domain we have mastered or use it to learn new skills and go wide. I see arguments for both.\n\nJohn advises using AI aggressively to expand horizontally (\"go wide\") across tools, frameworks, and languages without getting emotionally or professionally bottlenecked by a single technology identity (e.g., identifying strictly as a \"React developer\"). He suggests viewing generated code as highly disposable throwaway artifacts, focusing personal mastery on architecture, systems connection, and core concepts rather than syntax.\n\nJohn addresses this across the chunk by suggesting that real optimization lies in using agents to rapidly span broad domain boundaries (\"go wide\"), while selecting distinct low-level systemic execution areas to remain extreme experts.\n\n### Can you scare us? give us your thoughts on disruptions? speculate? for businesses, for developers?\n\nJohn offers the following as speculation about disruption, not established outcomes or a reliable timeline.\n\nJohn provides a physical and digital breakdown:Physical: Domestically, the arrival of capable robotics (laundry automation, nannies) will radically reshape home environments within a high-degree certainty window.Digital/Privacy: Absolute personal privacy will effectively cease to exist as environmental inputs (microphones, cameras) become ubiquitously parsed by agents.Social/Behavioral: Influencers could deploy localized agents to design and lock audiences into recursive consumption loops surrounding custom compound generation (like specialized peptide protocols), completely bypassing traditional institutional frameworks.\n\nJohn sketches out three disruptive focus points:Hardware Evolution: The introduction of capable domestic automation robotics (like laundry and care robots) will transform quality of life faster than most people realize.The Death of Privacy: Ubiquitous household microphones and data channels will erase remaining presumptions of digital or physical privacy.Social Engineering Biohacking: Influencers could use dedicated AI agents to steer audiences toward personalized routines or chemical dependency loops (like proprietary peptide formulas) via highly tailored media streams.\n\n### You hit this earlier but any final thoughts on this new normal where a project turns into 30k lines of code over night. How to manage that complexity (high level thoughts)\n\nComplex code bases must adhere to two absolute architectural anchors: Isolated Modular Components and State Machines. If the discrete business behaviors are written as navigable state transitions and logic is strictly compartmentalized, the sheer volume of code becomes secondary. A human can quickly parse the layout, and an agent can safely refactor or completely regenerate the entire implementation block straight from the state configuration rules if needed.\n\nJohn details a two-tier architectural defense: isolate software logic into highly distinct modules and route core flow through state machines. If these twin guardrails remain cleanly documented in understandable English, the underlying bulk of the code becomes swappable; a developer can pass the state machine configuration to an agent to reconstruct missing chunks reliably.\n\n### Do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc\n\nJohn implements a Claude.md profile file and establishes a symbolic link (symlink) mapping agents.md directly to it (noting a slight uncertainty regarding Claude's native handling of directory symlinks). He recommends avoiding highly complex, rigid rule frameworks. Instead, instruct your agent to inspect recent Git commits and automatically document its own operational boundaries, rules, and discovered project constraints into agents.md at the end of every active run cycle.\n\nJohn builds out files like agents.md or Claude.md, using built-in system hooks like Claude's /init macro or automating file creation directly inside Codex. He often maps them together via local file system symlinks. He notes he avoids rigid rules for these documents, letting them adapt as real execution errors happen so the agent preserves context dynamically.\n\n### How much time should a junior engineer invest in learning a programming language? [...] How should a senior invest in advancing their skills and programming language ecosystem?\n\nEngineering will bifurcate. A specialized subset of \"hyper-experts\" will remain highly essential to control low-level optimization bottlenecks that conversational English cannot adequately resolve—specifically memory management, browser layout engine performance, low-level networking protocols, security vectors, and intense mathematical systems. However, the vast majority of traditional engineering roles focused on standard app creation will shift toward becoming high-level \"project creators,\" where deep syntax mastery matters less than system coordination and rapid execution.\n\nJohn explains that the traditional identity of a framework engineer (e.g., an \"AngularJS developer\") is disappearing. He divides the upcoming landscape into low-level performance experts (focusing on custom browser rendering, memory safety, hardware optimization, and network scaling) and holistic project creators who coordinate agent workers via natural language profiles.\n\n### Is it the facebook backlog or the episodelist of black mirror?\n\nJohn admits he is not fully caught up on the most recent seasons of Black Mirror, but notes that the series has proven historically prophetic regarding technological feedback loops on human behavior.\n\nNo detailed standalone analysis of the series is captured.\n\n### Are you familiar with actor model? relates to your state machine comment\n\nThe companion connects the actor model to decoupled actors, state machines, and isolated messaging boundaries: those structures make code paths legible to people and agents. No detailed standalone actor-model implementation is captured.\n\n## Operational playbooks\n\n- [Video as requirements](/topics/foundations-video-requirements-playbook/)\n\n- [Codex Primitive Field Guide](/topics/foundations-codex-primitives-field-guide/)\n- [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/)\n- [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/)\n- [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-11.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-11.html)\n\n### Visual reference index\n\n- [04:51:20](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-1): Editor/workspace view around agents.md and local project context; Agent Browser cookie details are transcript evidence, not clearly visible here.\n- [04:52:55](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-2): Terminal/workspace view during PackX/PACX goal-package discussion.\n- [04:54:10](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-3): Terminal/workspace view during video-as-requirements discussion; no explicit diagram is visible in this still.\n- [04:57:02](https://codex-workshop-followup.pages.dev/lesson-11.html#clip-11-4): Codex application update dialog visible over the workspace.\n- [05:04:00](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during disruption and future-role discussion.\n- [05:07:35](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during git-diff-as-artifact discussion.\n- [05:09:40](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during state-machine and module-boundary discussion.\n- [05:11:50](https://codex-workshop-followup.pages.dev/lesson-11.html): Dark terminal/workspace view during agents.md / Claude.md guardrail discussion.\n\n## Durable operating principles\n\n- **Separate your contexts.** Research, implementation, and quota-sensitive agent work are different jobs. Route each to the surface that fits.\n- **Conduct, do not just type.** Use manager and worker panes so your job shifts toward intent, review, and orchestration.\n- **Give agents memory and guardrails.** Agent-managed folders, check-back files, and AGENTS.md rules keep long runs grounded without stuffing the context window.\n- **Trust current source.** Treat code as the source of truth, snapshot broad context when needed, and write design decisions where agents can find them.\n- **Hook the lifecycle.** User-prompt, tool-use, and stop hooks let you encode expertise at the points where the agent can actually use it.\n- **Run autonomy behind gates.** Background daemons, deterministic checks, and overnight loops are useful when the verification path is explicit.\n\nThe code can be disposable, but the workflow should leave behind receipts, constraints, and a next action."
    },
    {
      "id": "foundations-video-requirements-playbook",
      "slug": "video-requirements-playbook",
      "title": "Video as requirements playbook",
      "summary": "Web developers already debug behavior in running apps, not just in source files. A narrated screen recording gives an agent the missing layer: what the user clicked, typed, expected, noticed, and wanted changed, then turns that into a concrete QA story and implementation brief.",
      "category": "Principles",
      "tags": [
        "contracts",
        "state machines",
        "architecture",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#video-requirements",
        "scenarios/video-requirements.json#audienceFit",
        "toolkit/prompts/11-video-as-requirements-prompt.md",
        "toolkit/codex-skills/video-as-requirements/SKILL.md",
        "scenarios/video-requirements.json#scenarios/0",
        "scenarios/video-requirements.json#scenarios/1",
        "scenarios/video-requirements.json#scenarios/2",
        "scenarios/video-requirements.json#implementationNotes",
        "scenarios/video-requirements.json#notTaughtOrAvoid/1",
        "scenarios/video-requirements.json#notTaughtOrAvoid/2",
        "scenarios/video-requirements.json#notTaughtOrAvoid/3",
        "scenarios/video-requirements.json#notTaughtOrAvoid/4",
        "scenarios/video-requirements.json#notTaughtOrAvoid/5",
        "scenarios/video-requirements.json#notTaughtOrAvoid/6",
        "scenarios/video-requirements.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "principles",
      "wordCount": 2455,
      "url": "/topics/foundations-video-requirements-playbook/",
      "markdownUrl": "/markdown/foundations-video-requirements-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-video-requirements-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "convert-a-narrated-checkout-bug-into-a-fixable-qa-story",
          "text": "Convert a narrated checkout bug into a fixable QA story",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "turn-a-dashboard-walkthrough-into-responsive-ui-requirements",
          "text": "Turn a dashboard walkthrough into responsive UI requirements",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "use-a-video-bug-report-to-update-guardrails-after-the-fix",
          "text": "Use a video bug report to update guardrails after the fix",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "video-as-requirements-prompt",
          "text": "Video as requirements prompt",
          "level": 3
        },
        {
          "id": "video-as-requirements-codex-skill",
          "text": "Video as requirements Codex skill",
          "level": 3
        },
        {
          "id": "lesson-11-validated-references",
          "text": "Lesson 11 validated references",
          "level": 3
        },
        {
          "id": "lesson-11-validation-notes",
          "text": "Lesson 11 validation notes",
          "level": 3
        },
        {
          "id": "lesson-05-browser-qa-context",
          "text": "Lesson 05 browser QA context",
          "level": 3
        },
        {
          "id": "cmux-cli-surface",
          "text": "CMUX CLI surface",
          "level": 3
        },
        {
          "id": "local-verification-commands",
          "text": "Local verification commands",
          "level": 3
        },
        {
          "id": "diff-driven-review",
          "text": "Diff-driven review",
          "level": 3
        }
      ],
      "markdown": "# Video as requirements playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already debug behavior in running apps, not just in source files. A narrated screen recording gives an agent the missing layer: what the user clicked, typed, expected, noticed, and wanted changed, then turns that into a concrete QA story and implementation brief.\n\n[Core principles](/topics/foundations-contracts-state-machines-and-code/)\n\n## Copy-paste workflow\n\n**When to use:** When showing-and-narrating is faster than writing a perfect spec. Record yourself using the app while speaking intent, then have a multimodal model extract acceptance criteria and edge cases as agent-ready requirements.\n\n### Copy-paste prompt\n\n```text\nI'm going to turn a narrated screen recording into agent-ready requirements instead of writing a perfect spec.\n\n1. I will record a short narrated walkthrough of <APP/FEATURE>: I point, click, and talk through my intent and the outcomes I want.\n\n2. Feed that recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured requirements checklist:\n     - acceptance criteria\n     - the user flow (step by step)\n     - the specific clicks / typing / layout changes shown\n     - responsive behavior\n     - edge cases\n\n3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) I can hand to a coding agent.\n\nFraming: the durable assets are the natural-language contract + the resulting diff — NOT the generated code. Don't over-specify HOW to verify; give clear outcomes and keep my QA judgment in the loop.\n\nGuardrail: strip sensitive data first — video can expose more than you expect (open tabs, tokens, notifications, file paths).\n```\n\n### How it works\n- Record a short narrated walkthrough — point, click, and talk through intent and desired outcomes — which is often faster than writing a perfect spec.\n- Feed it to a multimodal model (Gemini, per the workshop) and extract acceptance criteria, the user flow, the clicks/typing/layout changes, responsive behavior, and edge cases.\n- The output is a repeatable, agent-ready requirements checklist (a QA story).\n- Under the throwaway-artifact mindset, the durable asset is the natural-language contract + the diff, not the generated code; don't over-specify how to verify — give clear outcomes and keep your QA judgment in the loop.\n- Caution: strip sensitive data before uploading; video can expose more than you expect.\n- Reference: [AGENTS.md](https://developers.openai.com/codex/guides/agents-md), [OpenAI Codex](https://github.com/openai/codex).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/video-as-requirements/SKILL.md`, then restart Codex.\n\n```markdown\n---\nname: video-as-requirements\ndescription: Trigger when a narrated screen recording captures intent better than a written spec — feed the video to a multimodal model to extract acceptance criteria, the user flow, and edge cases as an agent-ready requirements checklist. Do NOT upload videos containing sensitive data.\n---\n\n# Video as requirements\n\nTurn a narrated screen recording into agent-ready requirements. When showing-and-narrating beats writing a perfect spec, record the app in use and let a multimodal model extract the contract.\n\n## Steps\n\n1. Record a short narrated walkthrough of the app: point, click, and talk through intent and desired outcomes.\n\n2. Feed the recording to a multimodal model (Gemini, per the workshop) and ask it to extract a structured checklist:\n   - acceptance criteria\n   - the user flow (step by step)\n   - the specific clicks / typing / layout changes shown\n   - responsive behavior\n   - edge cases\n\n3. Output a REPEATABLE, agent-ready requirements checklist (a QA story) to hand to a coding agent.\n\n## Framing\n- The durable assets are the natural-language contract + the resulting diff — NOT the generated code.\n- Don't over-specify HOW to verify; give clear outcomes and keep human QA judgment in the loop.\n\n## Guardrails\n- STRIP sensitive data before uploading — video can expose more than you expect (open tabs, tokens, notifications, file paths). Do NOT upload videos containing sensitive data.\n```\n\n## Scenarios\n\n### Convert a narrated checkout bug into a fixable QA story\n\n**Role:** As a frontend engineer maintaining a Next.js commerce app\n\nA product manager records a two-minute walkthrough on localhost showing a cart drawer, promo-code input, shipping estimate panel, and checkout button. They narrate that the drawer jumps on mobile, the promo error disappears too fast, and the checkout button should stay disabled until shipping is selected.\n\n> As a mobile shopper, I want the cart drawer, promo-code error, shipping estimate, and checkout enabled state to behave predictably, so that I can recover from mistakes and complete checkout without guessing what changed.\n\n#### Agent brief\n\n```text\nYou are implementing from a narrated video requirements artifact. First inspect the current app source and existing tests; do not trust stale notes. Use the video-derived QA story as the natural-language contract. Create or update `.goals/cart-video-requirements.md` with: user flow, acceptance criteria, responsive behavior, edge cases, and what evidence will prove the fix. Then implement only the behavior described: stable mobile drawer layout, persistent promo-code error state until corrected or dismissed, shipping selection as the gate for enabling checkout, and no unrelated redesign. Run the project’s normal lint/test/build commands discovered from package scripts. Start the local dev server and verify the flow in a browser. Produce a final review artifact containing the git diff summary, commands run, browser proof, and any remaining risks.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n```text\npackage.json scripts: test, lint, build, dev\n```\n\n```text\ngit diff\n```\n\n#### Browser verification\n\nUse a local browser or CMUX browser pane against the dev server. Capture an accessibility snapshot of the cart drawer, click the cart trigger, fill the promo-code field with an invalid code, click apply, resize or emulate mobile width, select shipping, and evaluate whether the checkout button disabled/enabled state matches the video-derived contract. Save a screenshot or concise browser log as proof.\n\n#### Definition of done\n\n- A checked-in or local review artifact that restates the video-derived QA story and acceptance criteria\n- Passing lint/test/build output from the repo’s own scripts\n- Browser proof showing invalid promo behavior, mobile drawer stability, shipping selection, and checkout button state\n- A git diff review summary focused on the changed modules and any tests added or updated\n\n#### Failure modes and mitigations\n\n- The agent treats the video as a brittle click recorder and hard-codes selectors or exact timing; mitigate by extracting intent, user actions, expected behavior, responsive behavior, and edge cases before coding.\n- The agent redesigns the cart instead of fixing the contract; mitigate by requiring source inspection first and limiting changes to behavior described by the narrated walkthrough.\n\n### Turn a dashboard walkthrough into responsive UI requirements\n\n**Role:** As a full-stack web developer owning a SaaS analytics dashboard\n\nA customer success lead records a narrated walkthrough of a dashboard where they filter by date range, expand a table row, collapse search results on narrow screens, and point out that the summary cards reorder badly on tablet widths.\n\n> As an account manager reviewing customer metrics, I want filters, expandable rows, collapsed search results, and responsive summary cards to preserve context across screen sizes, so that I can investigate an account without losing my place.\n\n#### Agent brief\n\n```text\nUse the narrated walkthrough as requirements, not as a polished spec. Extract a QA story with the exact user flow, expected visual/layout behavior, responsive breakpoints observed in the video, and edge cases. Inspect the current dashboard code, routing, state ownership, and any existing browser tests. Implement the smallest change that preserves filter state, keeps expanded row context stable, makes search results collapse predictably on narrow screens, and improves tablet card ordering without changing unrelated dashboard styling. Run the repo’s normal verification commands. Then run the dashboard in a browser and prove the flow works at desktop, tablet, and mobile widths. Final output must include the diff summary plus browser evidence, not a generic success claim.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n```text\nAGENTS.md or agents.md if present\n```\n\n```text\npackage.json scripts\n```\n\n```text\ngit diff\n```\n\n#### Browser verification\n\nUse Playwright if the repo already has it, otherwise use a local browser or agent-browser-style workflow: snapshot the dashboard, click the date filter, fill or select the target range, expand a row, resize to tablet and mobile, and evaluate whether the visible labels, expanded state, and collapsed search results match the QA story. Do not add a new browser framework just for this scenario unless the repo already uses one.\n\n#### Definition of done\n\n- A video-derived QA story with user actions, expected behavior, responsive behavior, and edge cases\n- Passing project verification commands\n- Browser proof at desktop, tablet, and mobile widths\n- A diff-driven review note explaining which state/module boundaries changed and why\n\n#### Failure modes and mitigations\n\n- The agent over-specifies verification mechanics instead of outcomes; mitigate by keeping acceptance criteria outcome-based and using browser proof only as evidence.\n- The agent ignores current code structure and adds duplicate dashboard state; mitigate by requiring source-of-truth code inspection and preserving existing module/state boundaries where practical.\n\n### Use a video bug report to update guardrails after the fix\n\n**Role:** As a tech lead supervising agent-assisted feature work\n\nA teammate records a narrated video of a localhost onboarding flow where invite acceptance, workspace creation, and the empty-state screen drift from the intended product contract. Previous agents have fixed similar flows but keep missing the same auth and empty-state constraints.\n\n> As a team admin accepting an invite, I want the onboarding flow to preserve auth context, create or join the right workspace, and show the correct empty state, so that first-run setup feels trustworthy.\n\n#### Agent brief\n\n```text\nTreat the video as evidence for a natural-language contract. Extract the intended onboarding states and transitions from the narration: invite opened, auth checked, workspace joined or created, empty state shown, and error or retry states if present. Inspect the current code and identify the modules that own auth, workspace creation, routing, and empty-state rendering. Implement the smallest fix that satisfies the contract. After verification, review the git diff as the primary artifact. Then update `agents.md` or `AGENTS.md` only if the mistake reveals a reusable project-specific guardrail, such as where onboarding state must live or which module owns invite acceptance. Keep the guardrail short and grounded in this actual mistake.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n```text\nAGENTS.md or agents.md if present\n```\n\n```text\ngit diff\n```\n\n```text\npackage.json scripts\n```\n\n#### Browser verification\n\nBrowser proof is useful because onboarding is flow/state behavior. In a local browser, follow the invite URL or mocked invite route, complete the auth path using safe local test credentials or seeded state, click through workspace creation or join, and capture the final empty-state screen. If authenticated browser state is required, use a live browser/CMUX browser pane carefully and do not expose real tokens, QR codes, customer data, or private notifications.\n\n#### Definition of done\n\n- A compact onboarding state contract extracted from the video\n- Passing verification commands and a browser receipt of the invite-to-empty-state flow\n- A git diff summary suitable for fresh-session critique\n- A minimal guardrail update only if it captures a real repeated project constraint\n\n#### Failure modes and mitigations\n\n- The agent dumps a broad rulebook into AGENTS.md; mitigate by allowing only short, project-specific guardrails learned from this actual video-backed failure.\n- The agent uses real authenticated data casually during browser verification; mitigate by using local seeded data or sanitized test accounts and stripping sensitive information from videos and logs.\n\n## Implementation notes\n\n- Start by extracting a natural-language contract from the video before editing code. The contract should describe outcomes, user flow, responsive behavior, and edge cases; it should not become a brittle macro recording.\n- Inspect the live source before implementation. The course material is explicit that code is the source of truth when implementation details matter.\n- For web app work, browser proof matters when the requirement is visual, interactive, responsive, authenticated, or stateful. Use a local browser, CMUX browser pane, existing Playwright setup, or agent-browser-style snapshot/click/fill/evaluate workflow depending on what the repo already supports.\n- Keep generated code disposable but preserve durable assets: the video-derived contract, module/state boundaries, tests or verification artifacts, browser receipts, and the reviewed diff.\n- Strip sensitive data before uploading video. Screen recordings can leak tabs, tokens, paths, notifications, local QR codes, customer data, and auth state.\n- Do not add new permanent QA infrastructure for unstable UI unless the project already has that direction. A short QA story plus browser receipt can be enough for fast-moving product work.\n- Use `agents.md` or `AGENTS.md` as a living guardrail only when a real repeated mistake or project constraint emerges. Keep it small.\n\n## Boundaries and caveats\n\n- Do not present NotebookLM, Codex approvals/security, or Codex Skills documentation as taught workflows for this topic beyond the existing local skill artifact.\n- Do not require Agent Browser or Playwright as mandatory tools for every scenario; use them only when browser proof fits and the repo or workflow already supports them.\n- Do not treat video as a selector-level macro recorder. Extract intent and behavior, then verify outcomes.\n- Do not over-specify exact verification internals when a clear outcome plus browser evidence is enough.\n- Do not casually use authenticated browsers, local QR codes, secrets, customer data, or broad permissions in video capture or browser validation.\n- Do not let AGENTS.md become a giant upfront rulebook. Update it from real mistakes and constraints only.\n\n## Agent reference map\n\n### Video as requirements prompt\n\nUse this as the user-facing extraction prompt: record a narrated walkthrough, extract acceptance criteria, user flow, clicks/typing/layout changes, responsive behavior, and edge cases.\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n### Video as requirements Codex skill\n\nUse this when packaging the workflow as a reusable local agent skill with guardrails around sensitive video data.\n\n[Open reference](/topics/foundations-video-requirements-playbook/)\n\n### Lesson 11 validated references\n\nTreat this as ground truth for taught concepts: natural-language contracts, video-as-requirements, diff-driven review, modular/state-machine boundaries, living guardrails, and disposable generated code.\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n### Lesson 11 validation notes\n\nUse this to avoid reintroducing tools and claims that were mentioned but not taught as workflows in the final lesson.\n\n[Open reference](/topics/foundations-contracts-state-machines-and-code/)\n\n### Lesson 05 browser QA context\n\nUse this only for the supporting browser-work angle: perspective-based QA, weird-path exploration, browser-driving agents, CMUX state, and video-driven intent extraction.\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n### CMUX CLI surface\n\nUse when the agent needs a visible local pane or browser-oriented workspace receipt; inspect state before acting and avoid inventing flags.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n### Local verification commands\n\nDiscover and run the repo’s actual scripts instead of inventing a test command.\n\n```text\ncat package.json\n```\n\n### Diff-driven review\n\nUse the final git diff as the primary review artifact, then hand goal plus diff to a fresh session for critique when the change is risky.\n\n```text\ngit diff\n```"
    },
    {
      "id": "factory-evolving-principles",
      "slug": "evolving-principles",
      "title": "Which principles survive better agents?",
      "summary": "Separate enduring human judgment from workarounds for tools that have changed.",
      "category": "Principles",
      "tags": [
        "evolving",
        "factory"
      ],
      "sources": [
        {
          "label": "Which principles survive better agents?",
          "url": "https://hallowed-entry-96xv.here.now/"
        },
        {
          "label": "Software factory agenda",
          "url": "https://ember-bodhi-scrr.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "00-evolving/index.html#TL;DR",
        "00-evolving/index.html#The scorecard: 14 laws, one month later",
        "00-evolving/index.html#What the guide promised wouldn't rot",
        "00-evolving/index.html#Appendix",
        "00-evolving/index.html#Piping was a compaction workaround",
        "00-evolving/index.html#Git lost the short-lived majority",
        "00-evolving/index.html#The one law that inverted: boring code",
        "00-evolving/index.html#The laws that hardened are the judgment ones",
        "agenda/agent.md#editorial-principles"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 1989,
      "url": "/topics/factory-evolving-principles/",
      "markdownUrl": "/markdown/factory-evolving-principles.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-evolving-principles.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "the-scorecard-14-laws-one-month-later",
          "text": "The scorecard: 14 laws, one month later",
          "level": 2
        },
        {
          "id": "what-the-guide-promised-wouldn-t-rot",
          "text": "What the guide promised wouldn't rot",
          "level": 2
        },
        {
          "id": "piping-was-a-compaction-workaround",
          "text": "Piping was a compaction workaround",
          "level": 3
        },
        {
          "id": "git-lost-the-short-lived-majority",
          "text": "Git lost the short-lived majority",
          "level": 3
        },
        {
          "id": "the-one-law-that-inverted-boring-code",
          "text": "The one law that inverted: boring code",
          "level": 3
        },
        {
          "id": "the-laws-that-hardened-are-the-judgment-ones",
          "text": "The laws that hardened are the judgment ones",
          "level": 3
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "the-working-positions-behind-the-principles",
          "text": "The working positions behind the principles",
          "level": 2
        }
      ],
      "markdown": "# Which principles survive better agents?\n\nSeparate enduring human judgment from workarounds for tools that have changed.\n\n## Related working material\n\n- [Which principles survive better agents? — prompts and exercises](/topics/factory-evolving-principles-practice/)\n- [Which principles survive better agents? — questions and tradeoffs](/topics/factory-evolving-principles-questions/)\n- [Which principles survive better agents? — worked example](/topics/factory-evolving-principles-worked-example/)\n\n## TL;DR\n\n- A one-month audit of the Field Guide's 14 \"Prime Directives\" — every verdict backed by dated evidence an agent dug out of the author's own machine: chat history, prototype directories, session archives.\n- You walk away with a paste-ready prompt that runs the same 14-point audit against *your* machine and produces the same scorecard.\n- The one move: sort every workflow habit into **human judgment** (keep it, harden it) or **tool workaround** (check whether the weakness still exists — several no longer do).\n\n Have your agent run the audit — paste this into it:\n\n``` text\nFetch https://hallowed-entry-96xv.here.now/agent.md?raw and follow it to run the 14-directive self-audit against my machine. Run the success check at the end and show me the finished scorecard.\n```\n\n## The scorecard: 14 laws, one month later\n\nEach row: the directive's law line quoted from the guide, what one month of receipts showed, and the verdict. Read it as a sort, not a grade: which *kind* of law lands in which column?\n\n| \\# | Old law (quoted) | What the receipts showed | Verdict |\n|----|----|----|----|\n| 01 | \"If the agent can't see it, it doesn't exist.\" | Agents find their own context now; curation moved into their retrieval loop | Held — mechanism moved |\n| 02 | \"Research is loud. Contracts are quiet.\" | Agents recover from thin plans; alignment is the real variable | Held — sharpened |\n| 03 | \"If you can pipe it, you can reuse it.\" | Most piping compensated for bad compaction; compaction got good | Partly inverted |\n| 04 | \"Commit before autonomy.\" | Directory names and published sites became the version control for prototypes | Outgrew tooling |\n| 05 | \"Done is a claim. Green is a fact.\" | \"Done\" now includes leaving the repo easy for the next agent to probe | Hardened |\n| 06 | \"The agent can't read your mind — only your artifacts.\" | Dictation became the intent firehose; structuring it is the gap | Held |\n| 07 | \"Expose the decision space. Keep the decision.\" | Alternatives now arrive as generated images, not just prose | Held — went visual |\n| 08 | \"Bet small. Learn fast. Revert free.\" | 1,026 discarded prototypes compounded into a searchable idea library | Held — compounds |\n| 09 | \"Reuse follows value — never precedes it.\" | Four competing capture tools on one machine; instruction files may rot into anti-patterns | Outgrew tooling |\n| 10 | \"No single switch makes autonomy safe.\" | Unsupervised runs are routine: backups plus secrets fenced behind the `op` CLI | Held — layers thinned |\n| 11 | \"You can launch more agents than you can review.\" | Attention *and budget* are now the absolute bottleneck | Hardened |\n| 12 | \"Boring code is a superpower.\" | Models explore new tools so well that pushing boundaries is now necessary | Partly inverted |\n| 13 | \"A gate beats a plea.\" | Agents now write their own gates and permission config | Held — authorship moved |\n| 14 | \"The code is disposable. The contract is not.\" | Taste is the defining factor when anyone can build anything | Hardened |\n\nThe sort is the finding: the laws that **hardened** (05, 11, 14) encode human judgment. The laws that **eroded** (03, 12, half of 01) were compensating for earlier tool weaknesses. Some \"durable laws\" were tool-shaped all along.\n\n## What the guide promised wouldn't rot\n\n[The Field Guide](https://kindly-mirage-ejqd.here.now/) distilled fifteen months of workshops (the recorded workflow → the recorded workflow, across Cursor, Claude Code, and Codex) into fourteen Prime Directives and one rule above the rules: \"An agent saying 'done' is not evidence.\" It called the directives \"the layer that doesn't rot.\" This page audits that claim one month later, by the guide's own standard — saved, inspectable evidence instead of confident narration.\n\nThe method is itself the first verdict. An agent searched the author's full conversation history through a local full-text index (`cs`, covering every past Claude, Codex, and Grok session), scanned 1,026 prototype directories, and counted 1,978 archived agent sessions — all in the observed snapshot. Directive 01 said \"if the agent can't see it, it doesn't exist,\" and made hand-curation the human's edge. The audit was performed by an agent finding its own evidence. The law's wording survives; the human's role in it didn't. Curation flipped from \"feed the agent\" to \"make everything findable.\"\n\n### Piping was a compaction workaround\n\nDirective 03 turned agents into Unix processes: print mode, JSON streams, one bounded agent per pipeline stage. The receipts say most of that rigging existed to keep contexts small because compaction was bad. the recorded workflow session logs across four projects show compaction firing mid-task under a standing \"continue where you left off\" directive — long multi-day sessions just keep going, and nobody thinks about it. The elaborate pipe-per-stage rigs appear in earlier history and rarely since. Piping retreated to where it's genuine composition: CI stages and scripts. The test to carry forward: when a habit's justification names a tool weakness (\"context windows are small\"), re-check whether the weakness still exists before renewing the habit.\n\n### Git lost the short-lived majority\n\nDirective 04 — \"commit before autonomy\" — made Git the recovery system and external memory. The principle held; the tool fell behind the volume. The prototype folder contains sibling directories named `acorn-mcp`, `acorn-mcp-final`, `acorn-mcp-super-final`: directory-name versioning, because per-repo Git ceremony can't keep up with prototype velocity. Many current demos are deliberately not Git repos at all; published sites act as the durable record. Cursor and others are building Git replacements for exactly this gap — approving code nobody reads, and exploring memories of what worked. Meanwhile the old discipline survives where it belongs: an the recorded workflow session runs a dedicated checkpoint agent whose only job is reviewing and committing each iteration in long-lived repos.\n\nDirective 09 (the reuse ladder) hit the same wall from the other side. There's still no good tool for capturing success — the evidence log shows four competing capture mechanisms in active use on one machine within a single month: a friction-log skill, a workflow productizer, the conversation index, and per-agent memory directories. Four tools for one job means no tool has won. Worse, CLAUDE.md/AGENTS.md instruction files may be rotting into anti-patterns: stale rules that stop agents from making fixes or taking better directions. Audit your instruction files the way you audit dependencies.\n\n### The one law that inverted: boring code\n\nDirective 12 said \"boring code is a superpower\" — familiar structures, mature CLIs, no novel protocols. Models got so much better at exploring new ideas and new tools that the advice partly flipped: pushing boundaries is now *necessary* to stand out, because everyone can ship the boring thing. The log includes a the recorded workflow project literally named `pushing-boundaries`, and recent sessions casually drive desktop-app automation, GPU UI frameworks, and multi-account model councils — stacks the old law would have flagged as risk. The inversion is scoped: boring still wins inside the implementation. The boundary-pushing lives in what you attempt, not how the code is structured.\n\n### The laws that hardened are the judgment ones\n\nThree directives got stronger, and they're all about human judgment. Directive 05 (\"done is a claim, green is a fact\") extended past the diff — done now means leaving the codebase where the next agent can iterate, probe, and test; a the recorded workflow publish review states the mature position in seven words: \"evidence is a floor, not a substitute for taste.\" Directive 11 was promoted from lesson to law of nature: a the recorded workflow retrospective quantifies the practical limit at one to two guided tracks even with manager-agent tooling, and token budgets are now first-class workflow parameters. You can build anything — so the binding question is what you will build.\n\nDirective 14 is the audit's clearest winner. \"The machines propose; you choose\" — the guide called it where the other thirteen point. One month later the log converges on that sentence from three independent directions: a video project titled \"taste-is-the-job,\" a workshop retrospective whose story spine reads \"it turned out to be about taste, constraints, and verification,\" and the publish review above. When anyone can build anything, selection is the only scarce skill. The last law absorbed the other thirteen, exactly as the guide predicted.\n\n## Appendix\n\n### Limits & caveats\n\n- Every verdict rests on one practitioner's machine over roughly one month — a sample of one, gathered by an agent with access to that machine only. The verdicts support the sorting method, not an industry-wide ranking.\n- The claim that instruction files actively harm agents is the workshop's position, not a measured result. The evidence documents tool proliferation; there is no controlled comparison of sessions with and without instruction files.\n- Piping did not die — it survives where it is genuine composition. The evidence can't say how much piping remains in other practitioners' setups.\n- Agent-authored gates inherit the old guide's requirement unchanged: teeth and exits, reviewed by a human. The log shows agents writing config; it does not show that unreviewed agent-written gates are safe.\n- `cs` and `~/.oracle/sessions` are personal tooling on the author's machine. The audit works with any searchable history — agent.md includes grep fallbacks over raw session archives.\n- Verdicts and the tool-shaped/judgment-shaped sort are editorial inference from the evidence, and are marked as such.\n\n## The working positions behind the principles\n\nJohn’s position is deliberately provisional about tools and strong about judgment:\n\n1. Agents are much better at finding relevant context; make evidence findable rather than assuming the human must hand-feed everything.\n2. Planning is both more important and less important. Alignment is the key variable; before/after checks, possibly by another agent with evals, matter more than plan ceremony.\n3. Piping often compensated for poor compaction. Recheck whether that weakness still exists before rebuilding a pipe-per-stage workflow.\n4. Git can be insufficient for very high prototype volume. The missing tool manages approval, recoverability, and exploration of ideas—not merely a different commit interface. Publishing can preserve an artifact, but does not replace production safety.\n5. Done includes alignment and leaving the codebase easy for the next agent to iterate on, probe, and test.\n6. Dictation can carry an extensive brain dump while walking or otherwise away from a keyboard. Better real-time mind-mapping from human input remains a desirable missing tool.\n7. Generated images make the decision space easier and more important to expose.\n8. More prototypes create a deeper searchable well of ideas and examples, including discarded work.\n9. There is no perfect success-capture tool. Instruction files, comments, and documents may become stale constraints that prevent better fixes. The code is the artifact and the implementation documentation; this is a challenge to audit context, not proof that all prose is harmful.\n10. John argues that agents have become much safer for unsupervised work, with backups and secrets fenced through a manager such as the 1Password CLI. This is a practitioner’s position, not a measured guarantee or a reason to remove consequential-action gates.\n11. Attention and budget are the bottleneck: the ability to build anything makes choosing what to build harder, not less important.\n12. Models can explore unfamiliar tools and ambitious ideas. Push boundaries in what is attempted while keeping implementation structures maintainable.\n13. Hooks still provide control, and agents can help customize their own environment. Human review of the resulting gate and its exits remains necessary.\n14. Taste distinguishes the product when implementation becomes widely available."
    },
    {
      "id": "factory-evolving-principles-discussion",
      "slug": "evolving-principles-discussion",
      "title": "Which principles survive better agents? — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Principles",
      "tags": [
        "evolving-principles",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[2]",
        "resource-manifest.json#videoEvidence.concepts[3]",
        "resource-manifest.json#videoEvidence.concepts[4]",
        "resource-manifest.json#videoEvidence.concepts[5]",
        "resource-manifest.json#videoEvidence.concepts[6]",
        "resource-manifest.json#videoEvidence.concepts[7]",
        "resource-manifest.json#videoEvidence.concepts[8]",
        "resource-manifest.json#videoEvidence.concepts[11]",
        "resource-manifest.json#videoEvidence.concepts[12]",
        "resource-manifest.json#videoEvidence.concepts[13]",
        "resource-manifest.json#videoEvidence.concepts[14]",
        "resource-manifest.json#videoEvidence.concepts[15]",
        "resource-manifest.json#videoEvidence.concepts[16]",
        "resource-manifest.json#videoEvidence.concepts[17]",
        "resource-manifest.json#videoEvidence.concepts[18]",
        "resource-manifest.json#videoEvidence.concepts[19]",
        "resource-manifest.json#videoEvidence.concepts[20]",
        "resource-manifest.json#videoEvidence.concepts[21]",
        "resource-manifest.json#videoEvidence.concepts[22]",
        "resource-manifest.json#videoEvidence.concepts[23]",
        "resource-manifest.json#videoEvidence.concepts[24]",
        "resource-manifest.json#videoEvidence.concepts[25]",
        "resource-manifest.json#videoEvidence.concepts[26]",
        "resource-manifest.json#videoEvidence.concepts[27]",
        "resource-manifest.json#videoEvidence.concepts[28]",
        "resource-manifest.json#videoEvidence.concepts[29]",
        "resource-manifest.json#videoEvidence.concepts[30]",
        "resource-manifest.json#videoEvidence.concepts[31]",
        "resource-manifest.json#videoEvidence.concepts[32]",
        "resource-manifest.json#videoEvidence.concepts[33]",
        "resource-manifest.json#videoEvidence.concepts[34]",
        "resource-manifest.json#videoEvidence.concepts[35]",
        "resource-manifest.json#videoEvidence.concepts[36]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[2]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[3]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[4]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[5]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[6]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[7]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[9]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[10]",
        "resource-manifest.json#videoEvidence.timeline[42]",
        "resource-manifest.json#videoEvidence.timeline[43]",
        "resource-manifest.json#videoEvidence.timeline[44]",
        "resource-manifest.json#videoEvidence.timeline[45]",
        "resource-manifest.json#videoEvidence.timeline[54]",
        "resource-manifest.json#videoEvidence.timeline[58]",
        "resource-manifest.json#videoEvidence.timeline[69]",
        "resource-manifest.json#videoEvidence.timeline[70]",
        "resource-manifest.json#videoEvidence.timeline[71]",
        "resource-manifest.json#videoEvidence.timeline[72]",
        "resource-manifest.json#videoEvidence.timeline[73]",
        "resource-manifest.json#videoEvidence.timeline[74]",
        "resource-manifest.json#videoEvidence.timeline[76]",
        "resource-manifest.json#videoEvidence.timeline[77]",
        "resource-manifest.json#videoEvidence.timeline[78]",
        "resource-manifest.json#videoEvidence.timeline[79]",
        "resource-manifest.json#videoEvidence.timeline[81]",
        "resource-manifest.json#videoEvidence.timeline[82]",
        "resource-manifest.json#videoEvidence.timeline[86]",
        "resource-manifest.json#videoEvidence.timeline[87]",
        "resource-manifest.json#videoEvidence.timeline[88]",
        "resource-manifest.json#videoEvidence.timeline[89]",
        "resource-manifest.json#videoEvidence.timeline[90]",
        "resource-manifest.json#videoEvidence.timeline[91]",
        "resource-manifest.json#videoEvidence.timeline[92]",
        "resource-manifest.json#videoEvidence.timeline[93]",
        "resource-manifest.json#videoEvidence.timeline[94]",
        "resource-manifest.json#videoEvidence.timeline[95]",
        "resource-manifest.json#videoEvidence.timeline[97]",
        "resource-manifest.json#videoEvidence.timeline[98]",
        "resource-manifest.json#videoEvidence.timeline[99]",
        "resource-manifest.json#videoEvidence.timeline[100]",
        "resource-manifest.json#videoEvidence.timeline[101]",
        "resource-manifest.json#videoEvidence.timeline[105]",
        "resource-manifest.json#videoEvidence.timeline[106]",
        "resource-manifest.json#videoEvidence.timeline[107]",
        "resource-manifest.json#videoEvidence.timeline[108]",
        "resource-manifest.json#videoEvidence.timeline[110]",
        "resource-manifest.json#videoEvidence.timeline[111]",
        "resource-manifest.json#videoEvidence.timeline[112]",
        "resource-manifest.json#videoEvidence.timeline[119]",
        "resource-manifest.json#videoEvidence.timeline[121]",
        "resource-manifest.json#videoEvidence.timeline[123]",
        "resource-manifest.json#videoEvidence.timeline[124]",
        "resource-manifest.json#videoEvidence.timeline[128]",
        "resource-manifest.json#videoEvidence.timeline[133]",
        "resource-manifest.json#videoEvidence.timeline[136]",
        "resource-manifest.json#videoEvidence.timeline[137]",
        "resource-manifest.json#videoEvidence.timeline[138]",
        "resource-manifest.json#videoEvidence.timeline[139]",
        "resource-manifest.json#videoEvidence.timeline[140]",
        "resource-manifest.json#videoEvidence.timeline[141]",
        "resource-manifest.json#videoEvidence.timeline[142]",
        "resource-manifest.json#videoEvidence.timeline[144]",
        "resource-manifest.json#videoEvidence.timeline[150]",
        "resource-manifest.json#videoEvidence.timeline[152]",
        "resource-manifest.json#videoEvidence.timeline[157]",
        "resource-manifest.json#videoEvidence.timeline[159]",
        "resource-manifest.json#videoEvidence.timeline[160]",
        "resource-manifest.json#videoEvidence.timeline[161]",
        "resource-manifest.json#videoEvidence.uncertainties[1]",
        "resource-manifest.json#videoEvidence.uncertainties[3]",
        "resource-manifest.json#videoEvidence.uncertainties[10]",
        "resource-manifest.json#videoEvidence.demos[0]",
        "resource-manifest.json#videoEvidence.demos[1]",
        "resource-manifest.json#videoEvidence.demos[2]",
        "resource-manifest.json#videoEvidence.demos[3]",
        "resource-manifest.json#videoEvidence.demos[4]",
        "resource-manifest.json#videoEvidence.demos[5]",
        "resource-manifest.json#videoEvidence.demos[6]",
        "resource-manifest.json#videoEvidence.demos[7]",
        "resource-manifest.json#videoEvidence.demos[8]",
        "resource-manifest.json#videoEvidence.demos[9]",
        "resource-manifest.json#videoEvidence.demos[10]",
        "resource-manifest.json#videoEvidence.demos[11]",
        "resource-manifest.json#videoEvidence.demos[12]",
        "resource-manifest.json#videoEvidence.demos[13]",
        "resource-manifest.json#videoEvidence.demos[14]",
        "resource-manifest.json#videoEvidence.demos[15]"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 3043,
      "url": "/topics/factory-evolving-principles-discussion/",
      "markdownUrl": "/markdown/factory-evolving-principles-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-evolving-principles-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "own-your-tools",
          "text": "Own your tools",
          "level": 3
        },
        {
          "id": "repository-context-referencing",
          "text": "Repository Context Referencing",
          "level": 3
        },
        {
          "id": "ai-context-bundlers",
          "text": "AI Context Bundlers",
          "level": 3
        },
        {
          "id": "artifacts",
          "text": "Artifacts",
          "level": 3
        },
        {
          "id": "open-weight-models",
          "text": "Open-Weight Models",
          "level": 3
        },
        {
          "id": "kimi-k3-model",
          "text": "Kimi K3 Model",
          "level": 3
        },
        {
          "id": "token-efficiency",
          "text": "Token Efficiency",
          "level": 3
        },
        {
          "id": "context-management-and-compaction",
          "text": "Context Management and Compaction",
          "level": 3
        },
        {
          "id": "tool-calling-maturity",
          "text": "Tool Calling Maturity",
          "level": 3
        },
        {
          "id": "adaptive-planning-vs-upfront-planning",
          "text": "Adaptive Planning vs. Upfront Planning",
          "level": 3
        },
        {
          "id": "chained-specialized-agents",
          "text": "Chained Specialized Agents",
          "level": 3
        },
        {
          "id": "single-model-token-efficiency",
          "text": "Single-Model Token Efficiency",
          "level": 3
        },
        {
          "id": "agentic-forge-architectures",
          "text": "Agentic Forge Architectures",
          "level": 3
        },
        {
          "id": "git-limitations-in-agentic-work",
          "text": "Git Limitations in Agentic Work",
          "level": 3
        },
        {
          "id": "vision-alignment",
          "text": "Vision Alignment",
          "level": 3
        },
        {
          "id": "automated-guardrails",
          "text": "Automated Guardrails",
          "level": 3
        },
        {
          "id": "agentic-lifecycle-hooks",
          "text": "Agentic Lifecycle Hooks",
          "level": 3
        },
        {
          "id": "exhaustive-dictation-brain-dumping",
          "text": "Exhaustive Dictation / Brain Dumping",
          "level": 3
        },
        {
          "id": "artifact-driven-prompting",
          "text": "Artifact-Driven Prompting",
          "level": 3
        },
        {
          "id": "code-artifact-repository-visual-reference-grid",
          "text": "Code Artifact Repository / Visual Reference Grid",
          "level": 3
        },
        {
          "id": "task-clustering-and-summarization",
          "text": "Task Clustering and Summarization",
          "level": 3
        },
        {
          "id": "sub-agents-teams",
          "text": "Sub-agents / Teams",
          "level": 3
        },
        {
          "id": "searchable-memory-layer-continuous-screen-recording",
          "text": "Searchable Memory Layer / Continuous Screen Recording",
          "level": 3
        },
        {
          "id": "human-in-the-loop-hitl",
          "text": "Human-in-the-loop (HITL)",
          "level": 3
        },
        {
          "id": "unsafe-auto-mode",
          "text": "Unsafe/Auto Mode",
          "level": 3
        },
        {
          "id": "seoul-model",
          "text": "Seoul Model",
          "level": 3
        },
        {
          "id": "proliferation-focus-tracks",
          "text": "Proliferation Focus Tracks",
          "level": 3
        },
        {
          "id": "boring-code-frameworks",
          "text": "Boring Code Frameworks",
          "level": 3
        },
        {
          "id": "durable-laws-vs-tool-compensations",
          "text": "Durable Laws vs. Tool Compensations",
          "level": 3
        },
        {
          "id": "disposable-code-vs-taste",
          "text": "Disposable Code vs. Taste",
          "level": 3
        },
        {
          "id": "flow-text",
          "text": "Flow Text",
          "level": 3
        },
        {
          "id": "image-factory-workflow",
          "text": "Image Factory Workflow",
          "level": 3
        },
        {
          "id": "yolo-mode",
          "text": "YOLO Mode",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "do-you-think-we-ll-get-another-week-of-fable-given-this-news",
          "text": "Do you think we’ll get another week of Fable given this news?",
          "level": 3
        },
        {
          "id": "re-models-better-at-finding-code-how-much-is-better-grep-ing-and-how-much-is-agents-now-using-lsps-etc",
          "text": "Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc?",
          "level": 3
        },
        {
          "id": "is-it-worth-paying-for-premium-models-like-fable-5-when-small-alignment-variances-risk-wasting-valuable-tokens",
          "text": "Is it worth paying for premium models like Fable 5 when small alignment variances risk wasting valuable tokens?",
          "level": 3
        },
        {
          "id": "how-would-claude-or-codex-define-cluster-of-batched-tasks-followed-by-summaries-awaiting-approval-and-is-that-methodology-still-useful",
          "text": "How would Claude or Codex define 'cluster of batched tasks' followed by summaries awaiting approval, and is that methodology still useful?",
          "level": 3
        },
        {
          "id": "would-you-recommend-collecting-external-pages-then-recreating-that-on-here-now-as-my-own-example-that-will-never-change-then",
          "text": "Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then?",
          "level": 3
        },
        {
          "id": "i-often-use-the-term-cluster-of-batch-tasks-then-at-the-end-of-each-cluster-report-back-the-summary-yeah-how-would-claude-or-codex-define-that-is-that-a-useful-methodology",
          "text": "I often use the term cluster of batch tasks, then at the end of each cluster, report back the summary. Yeah. How would Claude or Codex define that? Is that a useful methodology?",
          "level": 3
        },
        {
          "id": "what-do-you-call-breakpoints-where-a-human-in-the-loop-must-make-a-decision-and-approve-before-moving-to-the-next-cluster",
          "text": "What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?",
          "level": 3
        },
        {
          "id": "what-do-you-call-breakpoints-where-a-human-in-the-loop-must-make-a-decision-and-approve-before-moving-to-the-next-cluster-2",
          "text": "What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-the-exact-full-query-parameters-or-path-extension-for-the-kimi-code-page",
          "text": "Unresolved: The exact full query parameters or path extension for the Kimi Code page.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-technical-resolution-to-a-participant-s-question-about-grep-vs-lsp-methods-within-state-of-the-art-agent-frameworks",
          "text": "Unresolved: The exact technical resolution to a participant's question about grep vs LSP methods within state-of-the-art agent frameworks.",
          "level": 3
        },
        {
          "id": "unresolved-specific-utility-role-of-the-take-prefix-launcher-statement-configuration",
          "text": "Unresolved: Specific utility role of the take prefix launcher statement configuration.",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-14-02",
          "text": "Demonstration detail: 00:14:02",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-14-18",
          "text": "Demonstration detail: 00:14:18",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-16-37",
          "text": "Demonstration detail: 00:16:37",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-17-12",
          "text": "Demonstration detail: 00:17:12",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-18-45",
          "text": "Demonstration detail: 00:18:45",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-21-24",
          "text": "Demonstration detail: 00:21:24",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-23-33",
          "text": "Demonstration detail: 00:23:33",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-29-22",
          "text": "Demonstration detail: 00:29:22",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-31-12",
          "text": "Demonstration detail: 00:31:12",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-37-31",
          "text": "Demonstration detail: 00:37:31",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-38-50",
          "text": "Demonstration detail: 00:38:50",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-45-05",
          "text": "Demonstration detail: 00:45:05",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-45-51",
          "text": "Demonstration detail: 00:45:51",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-46-33",
          "text": "Demonstration detail: 00:46:33",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-53-45",
          "text": "Demonstration detail: 00:53:45",
          "level": 3
        },
        {
          "id": "demonstration-detail-00-56-45",
          "text": "Demonstration detail: 00:56:45",
          "level": 3
        }
      ],
      "markdown": "# Which principles survive better agents? — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Own your tools\n\nThe philosophy of heavily customizing development utilities and environments to match individual engineer optimization criteria.\n\n### Repository Context Referencing\n\nBundling complete repository structure and codebases into an LLM context window to provide ground-truth documentation for agent logic loops.\n\n### AI Context Bundlers\n\nMethods or tools to aggregate repository references and internal interfaces to supply exhaustive context to AI agents, eliminating random generation guesses.\n\n### Artifacts\n\nStand-alone code documents or hosted assets generated directly by AI systems, similar to the Claude Code feature, which John replicates via a custom site-dropping CLI.\n\n### Open-Weight Models\n\nMachine learning models whose neural network weights are publicly shared, empowering custom user training and local optimization workflows at a minimal price point.\n\n### Kimi K3 Model\n\nA state-of-the-art Chinese open-weight model from Kimi/Moonshot AI that undercuts market pricing while rivaling top frontier models in engineering benchmarks.\n\n### Token Efficiency\n\nAchieving complex automation tasks with minimized context usage and fewer conversational iterations.\n\n### Context Management and Compaction\n\nThe historical necessity of manually compressing or curating codebase elements to fit context limits, which has become automated or largely obsolete due to modern agentic capabilities.\n\n### Tool Calling Maturity\n\nThe transformation of LLM tool invocation from unreliable behaviors to an incredibly stable engine that users confidently expect to work every time.\n\n### Adaptive Planning vs. Upfront Planning\n\nA shift away from pre-planned checkbox steps in favor of diving directly into code alterations, evaluating what works, and pulling back cleanly via source control.\n\n### Chained Specialized Agents\n\nAn architectural approach of piping outputs through a sequential chain of specialized custom sub-agents, now being outpaced by efficient monolithic models.\n\n### Single-Model Token Efficiency\n\nThe operational reality where letting a highly advanced model solve an execution path directly uses far fewer iterative calls than a sprawling cluster of sub-agents.\n\n### Agentic Forge Architectures\n\nCode storage infrastructures designed around autonomous developer tools rather than solely optimizing for human commit messages and version branching histories.\n\n### Git Limitations in Agentic Work\n\nStandard source control branching paradigms create operational overhead and clunky code sync loops when orchestrated heavily by parallel automated agents.\n\n### Vision Alignment\n\nInstructing agents based on overarching user design intent and macro-level target states rather than managing explicit, granular steps.\n\n### Automated Guardrails\n\nRelying on backend automation tools like tests, style lints, and post-execution hooks to lock down system boundaries instead of rigid upfront requirements blueprints.\n\n### Agentic Lifecycle Hooks\n\nAlternative execution boundaries (e.g. stop hooks and session end hooks) configured to cleanly freeze or evaluate agent iterations.\n\n### Exhaustive Dictation / Brain Dumping\n\nProviding dense context and detailed parameters to an agent up-front to prevent it from hallucinating or incorrectly guessing user intent.\n\n### Artifact-Driven Prompting\n\nLeveraging existing functional single-file web pages or code prototypes as explicit architectural examples for an agent to inspect and duplicate specific behaviors.\n\n### Code Artifact Repository / Visual Reference Grid\n\nSaving small, single-file working examples of complex features so an AI agent can read from them directly rather than inferring patterns from scratch.\n\n### Task Clustering and Summarization\n\nGrouping sub-tasks or sub-agents together and postponing summarization until the completion of the core work to avoid distracting the model's inference cycles.\n\n### Sub-agents / Teams\n\nDividing a high-level task into components managed by separate agent groups working together, exemplified by teams in Claude Code.\n\n### Searchable Memory Layer / Continuous Screen Recording\n\nBackground software tools that track screen history, text, and active context to allow agents to search past activities.\n\n### Human-in-the-loop (HITL)\n\nDesignated checkpoints where automated workflows wait for manual human verification and decision-making before resuming.\n\n### Unsafe/Auto Mode\n\nAllowing agentic tools or LLM code generation applications to execute actions and file operations without mandatory human approval checkpoints.\n\n### Seoul Model\n\nReference to an LLM model version used in code generation tools like Codex.\n\n### Proliferation Focus Tracks\n\nA personal strategy used by the presenter to bucket autonomous agent tasks into three distinct lanes: fun, profitable, and personal utility.\n\n### Boring Code Frameworks\n\nThe design practice of sticking closely to mainstream defaults and popular frameworks (e.g., Next.js) so that code models perform highly due to high densities of training data availability.\n\n### Durable Laws vs. Tool Compensations\n\nThe division between fundamental system logic configurations that represent developer intent, versus temporary codebase rules written to bypass limits in current AI capabilities.\n\n### Disposable Code vs. Taste\n\nThe principle that code syntax generation is cheap and automated, leaving an engineer's artistic taste, architectural criteria, and platform uniqueness as the primary values.\n\n### Flow Text\n\nA library designed to enable CSS HTML wrap-around text flows mapping precisely to alpha transparency edges of an image component.\n\n### Image Factory Workflow\n\nA technique utilizing multi-modal agent capabilities to capture existing web templates via visual inputs and autonomously generate style iterations or layout options.\n\n### YOLO Mode\n\nAn execution permission status within the Codex terminal interface allowing project-level local configurations and scripts to launch automatically without explicit multi-step interactive prompts.\n\n## Questions and answer status\n\n### Do you think we’ll get another week of Fable given this news?\n\n**Status: answered.** John states he hopes so because Fable uniquely interprets and handles his layout and UX engineering tasks cleanly.\n\n### Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc?\n\n**Status: deferred.** The question is left deferred during this specific segment as the presenter is explaining the historical piping model.\n\n### Is it worth paying for premium models like Fable 5 when small alignment variances risk wasting valuable tokens?\n\n**Status: answered.** Yes, because their extreme turn-efficiency allows them to close tasks in far fewer cycles (e.g. 2 calls vs 15 calls), ultimately using fewer raw resources despite higher per-token prices.\n\n### How would Claude or Codex define 'cluster of batched tasks' followed by summaries awaiting approval, and is that methodology still useful?\n\n**Status: deferred.** The question is not addressed by the presenter within the time boundaries of this shard.\n\n### Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then?\n\n**Status: answered.** Yes, John fully recommends saving references, bookmarks, screenshots, or dictations of inspiring items to build an unalterable personal source collection.\n\n### I often use the term cluster of batch tasks, then at the end of each cluster, report back the summary. Yeah. How would Claude or Codex define that? Is that a useful methodology?\n\n**Status: answered.** John defines a cluster as a group of sub-agents. He mentions Claude Code has built-in summaries, but recommends waiting until a task is completely finished before summarizing to keep the inference clear of unnecessary instruction load.\n\n### What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?\n\n**Status: partial.** John answers that this design pattern is commonly referred to as 'human in the loop' (HITL), with further details extending into the following segment.\n\n### What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?\n\n**Status: answered.** The presenter states that 'human in the loop' is the industry term that perfectly describes these checkpoint decisions.\n\n## Exercises\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [00:14:49](https://proud-anchor-53zn.here.now/watch.html?t=889#recording-player) — Walkthrough of terminal coding agent options and alternatives.\n\n- [00:15:14](https://proud-anchor-53zn.here.now/watch.html?t=914#recording-player) — Presentation of workspace multiplexer tools like Herd and Zellij.\n\n- [00:15:37](https://proud-anchor-53zn.here.now/watch.html?t=937#recording-player) — Evaluation of repo-to-prompt context packaging utilities.\n\n- [00:15:53](https://proud-anchor-53zn.here.now/watch.html?t=953#recording-player) — John Lindquist explains that with proper context, it becomes trivial for an AI to customize code for individual needs.\n\n- [00:19:03](https://proud-anchor-53zn.here.now/watch.html?t=1143#recording-player) — John describes the new Kimi K3 model released yesterday, noting its benchmarks against Fable 5 and OpenAI's GPT 5.6 models.\n\n- [00:20:28](https://proud-anchor-53zn.here.now/watch.html?t=1228#recording-player) — John Lindquist states Fable is his favorite model to talk to because it aligns cleanly with UX and UI design intentions.\n\n- [00:23:33](https://proud-anchor-53zn.here.now/watch.html?t=1413#recording-player) — John Lindquist explains that developers previously spent significant effort managing conversation context windows and compaction.\n\n- [00:24:03](https://proud-anchor-53zn.here.now/watch.html?t=1443#recording-player) — John Lindquist discusses the major improvements in tool calling and file change stability, stating that reliability is now an industry baseline expectation.\n\n- [00:24:24](https://proud-anchor-53zn.here.now/watch.html?t=1464#recording-player) — John Lindquist reports that automated context gathering within the codebase by modern agents has improved vastly.\n\n- [00:24:40](https://proud-anchor-53zn.here.now/watch.html?t=1480#recording-player) — John Lindquist mentions state-of-the-art models including Fables, GPT-5.6, and Kimi 3s, noting they rarely miss necessary files or related refactorings.\n\n- [00:25:35](https://proud-anchor-53zn.here.now/watch.html?t=1535#recording-player) — John Lindquist shifts to discussing planning laws, explaining that he no longer advocates for rigid upfront checkboxes and extensive step-by-step planning documents.\n\n- [00:25:35](https://proud-anchor-53zn.here.now/watch.html?t=1535#recording-player) — The presenter highlights text within row 02 ('Research is loud. Contracts are quiet.') on the scorecard table.\n\n- [00:26:55](https://proud-anchor-53zn.here.now/watch.html?t=1615#recording-player) — The presenter selects text in row 03 ('If you can pipe it, you can reuse it.') to discuss agent pipelining.\n\n- [00:26:55](https://proud-anchor-53zn.here.now/watch.html?t=1615#recording-player) — John Lindquist describes older architectures where specialized, custom agents were chained together to pipe inputs and outputs sequentially.\n\n- [00:27:13](https://proud-anchor-53zn.here.now/watch.html?t=1633#recording-player) — John Lindquist states that chained specialized agent workflows face significant architectural challenges following the release of Fable 5.\n\n- [00:27:22](https://proud-anchor-53zn.here.now/watch.html?t=1642#recording-player) — John Lindquist introduces the theme of token efficiency driven by advanced AI models.\n\n- [00:28:32](https://proud-anchor-53zn.here.now/watch.html?t=1712#recording-player) — John evaluates the cost trade-offs of premium models like Fable 5 when misalignments occur.\n\n- [00:29:19](https://proud-anchor-53zn.here.now/watch.html?t=1759#recording-player) — John notes that Git is entering a transitional phase because code updates occur too fast for traditional tracking formats.\n\n- [00:30:15](https://proud-anchor-53zn.here.now/watch.html?t=1815#recording-player) — The browser loads the landing page for Cursor Origin showing the headline 'A git forge for the agentic era'.\n\n- [00:31:12](https://proud-anchor-53zn.here.now/watch.html?t=1872#recording-player) — Chrome browser window is focused on hallowed-entry-96xy.now.sh/index.html showing row 04 'Commit before autonomy.' highlighted in blue.\n\n- [00:31:12](https://proud-anchor-53zn.here.now/watch.html?t=1872#recording-player) — John Lindquist describes how modern agent setups are rapidly outgrowing what Git provides.\n\n- [00:31:34](https://proud-anchor-53zn.here.now/watch.html?t=1894#recording-player) — John points out how parallel branches and work trees complicate standard code merges for autonomous agents.\n\n- [00:32:11](https://proud-anchor-53zn.here.now/watch.html?t=1931#recording-player) — John references the phrase 'Done is a claim. Green is a fact.', discussing how comprehensive commit hooks, lints, and tests create functional guardrails.\n\n- [00:32:42](https://proud-anchor-53zn.here.now/watch.html?t=1962#recording-player) — John highlights the transition from traditional planning documents (PRDs) to strategic vision alignment.\n\n- [00:33:33](https://proud-anchor-53zn.here.now/watch.html?t=2013#recording-player) — The UI selection shifts downward to highlight row 05 'Done is a claim. Green is a fact.'\n\n- [00:33:53](https://proud-anchor-53zn.here.now/watch.html?t=2033#recording-player) — John describes how agentic lifecycles introduce stop hooks or session end hooks that mismatch with standard git execution flows.\n\n- [00:34:42](https://proud-anchor-53zn.here.now/watch.html?t=2082#recording-player) — The text selection moves down to highlight row 06 'The agent can't read your mind — only your artifacts.'\n\n- [00:34:52](https://proud-anchor-53zn.here.now/watch.html?t=2092#recording-player) — John underscores dictation and brain dumping context as highly effective mechanisms for interfacing with agents.\n\n- [00:35:01](https://proud-anchor-53zn.here.now/watch.html?t=2101#recording-player) — John highlights rule number 06: 'The agent can't read your mind - only your artifacts.'\n\n- [00:35:06](https://proud-anchor-53zn.here.now/watch.html?t=2106#recording-player) — John discusses the widespread mistake of providing short text prompts and expecting perfect agent execution.\n\n- [00:35:18](https://proud-anchor-53zn.here.now/watch.html?t=2118#recording-player) — John shares an anecdote regarding an AI face modification that incorrectly guessed eye features hidden by sunglasses.\n\n- [00:36:44](https://proud-anchor-53zn.here.now/watch.html?t=2204#recording-player) — John moves his cursor over rule 07: 'Expose the decision space. Keep the decision.'\n\n- [00:37:00](https://proud-anchor-53zn.here.now/watch.html?t=2220#recording-player) — John hovers over rule 08: 'Bet small. Learn fast. Revert free.'\n\n- [00:37:31](https://proud-anchor-53zn.here.now/watch.html?t=2251#recording-player) — The browser opens the 'FRONTIER/26' single-page field guide generated by Kimi.\n\n- [00:37:49](https://proud-anchor-53zn.here.now/watch.html?t=2269#recording-player) — John scrolls down to reveal an interactive mouse-responsive shader canvas element.\n\n- [00:38:09](https://proud-anchor-53zn.here.now/watch.html?t=2289#recording-player) — John scrolls through OKLCH color schemes and a scrollbar timeline chapter.\n\n- [00:38:34](https://proud-anchor-53zn.here.now/watch.html?t=2314#recording-player) — John tests variable fonts by moving a cursor over scroll/timeline components on the page.\n\n- [00:38:50](https://proud-anchor-53zn.here.now/watch.html?t=2330#recording-player) — Browser displays jival-kayak-fyna.here.now titled 'FRONTIER/24' showing Chapter 04 variable font capabilities.\n\n- [00:38:50](https://proud-anchor-53zn.here.now/watch.html?t=2330#recording-player) — John Lindquist notes that the example is a single HTML file containing bundled JavaScript and CSS.\n\n- [00:39:06](https://proud-anchor-53zn.here.now/watch.html?t=2346#recording-player) — Presenter scrolls down the page to show various interactive CSS features (view transitions, container queries, feature audit grid).\n\n- [00:42:14](https://proud-anchor-53zn.here.now/watch.html?t=2534#recording-player) — John details his recommendation to capture inspiring pages via screenshots, bookmarks, notes, or dictations.\n\n- [00:42:42](https://proud-anchor-53zn.here.now/watch.html?t=2562#recording-player) — John Lindquist describes using daily experiences like flowers or a sunrise to gather context and inspiration for product development.\n\n- [00:43:54](https://proud-anchor-53zn.here.now/watch.html?t=2634#recording-player) — John defines a cluster of batch tasks as a group of sub-agents, noting Anthropic or Claude Code calls it a team.\n\n- [00:44:48](https://proud-anchor-53zn.here.now/watch.html?t=2688#recording-player) — John introduces ScreenPipe as a tool that records the screen and captures intelligent notes.\n\n- [00:45:30](https://proud-anchor-53zn.here.now/watch.html?t=2730#recording-player) — John introduces Pieces app as another tool he has used for background history tracking.\n\n- [00:46:26](https://proud-anchor-53zn.here.now/watch.html?t=2786#recording-player) — John answers that the industry term for these breakpoints is human in the loop.\n\n- [00:46:33](https://proud-anchor-53zn.here.now/watch.html?t=2793#recording-player) — John Lindquist explains that 'human in the loop' is the standard term for checkpoints where human approval is required.\n\n- [00:46:44](https://proud-anchor-53zn.here.now/watch.html?t=2804#recording-player) — John Lindquist highlights row 09: 'Reuse follows value - never precedes it.'\n\n- [00:47:19](https://proud-anchor-53zn.here.now/watch.html?t=2839#recording-player) — John mentions letting tools run in unsafe modes, noting auto mode features in Cloud Code, Codex, and Pi.\n\n- [00:47:38](https://proud-anchor-53zn.here.now/watch.html?t=2858#recording-player) — John relates an anecdote where Codex using the Seoul model attempted to delete a user home directory because of tilde expansion errors.\n\n- [00:48:38](https://proud-anchor-53zn.here.now/watch.html?t=2918#recording-player) — John highlights text in row 11: 'Attention and budget are now the absolute bottleneck'.\n\n- [00:49:13](https://proud-anchor-53zn.here.now/watch.html?t=2953#recording-player) — John proposes organizing agent tasks into three lanes: one fun thing, one profitable thing, and one thing that improves personal or family life.\n\n- [00:50:09](https://proud-anchor-53zn.here.now/watch.html?t=3009#recording-player) — John highlights row 12: 'Boring code is a superpower.'\n\n- [00:50:18](https://proud-anchor-53zn.here.now/watch.html?t=3018#recording-player) — John describes how AI models are highly optimized for common framework structures like Next.js.\n\n- [00:54:07](https://proud-anchor-53zn.here.now/watch.html?t=3247#recording-player) — The browser loads github.com/johnlindquist/flow-text showing documentation for transparent image text-wrapping.\n\n- [00:54:18](https://proud-anchor-53zn.here.now/watch.html?t=3258#recording-player) — John switches browser tabs to kindly-mirage-wjpt.here.now/directives.html to show text wrapping around transparent images.\n\n- [00:56:46](https://proud-anchor-53zn.here.now/watch.html?t=3406#recording-player) — John runs the project script command take dev/screenshot-demo.\n\n- [00:56:56](https://proud-anchor-53zn.here.now/watch.html?t=3416#recording-player) — OpenAI Codex tool instance loads in YOLO mode using model gpt-5.6-sol medium.\n\n- [00:57:01](https://proud-anchor-53zn.here.now/watch.html?t=3421#recording-player) — John inputs an explicit workflow prompt utilizing the $imagegen skill to create layout alternative directions.\n\n- [00:57:23](https://proud-anchor-53zn.here.now/watch.html?t=3443#recording-player) — Codex outputs background execution task parameters matching run reference <session-id>.\n\n### Unresolved: The exact full query parameters or path extension for the Kimi Code page.\n\nThe page URL is entered rapidly with auto-complete, meaning extra session tokens or routing parameters might be present but unverified.\n\n**Discriminating evidence:** Manually verify standard landing routes for Moonshot AI/Kimi Code consoles.\n\n### Unresolved: The exact technical resolution to a participant's question about grep vs LSP methods within state-of-the-art agent frameworks.\n\nThe question was posted in chat near the end of the shard and is not addressed by the presenter prior to the timestamp cutoff.\n\n**Discriminating evidence:** Requires tracking the presenter's response in the subsequent recording shard.\n\n### Unresolved: Specific utility role of the take prefix launcher statement configuration.\n\nIt is not explicit if take represents a standard binary tool or custom shell environment function alias setup.\n\n**Discriminating evidence:** Need project dotfiles profile inspection or environment list review configurations.\n\n### Demonstration detail: 00:14:02\n\n- Screen sharing active on local terminal workspace environment view.\n\n**Tools observed:** Ghostty.\n\n### Demonstration detail: 00:14:18\n\n- Navigating agenda site documentation and reference markdown alternative checklists.\n\n**Tools observed:** Web Browser.\n\n### Demonstration detail: 00:16:37\n\n- Scrolls through the site overview lists and pages on the here.now web dashboard interface.\n\n**Tools observed:** here.now.\n\n### Demonstration detail: 00:17:12\n\n- Navigates to and displays the introductory text sections of the Field Guide site.\n\n**Tools observed:** Google Chrome Browser.\n\n### Demonstration detail: 00:18:45\n\n- Opens a new browser tab and navigates to the Kimi Code interface to show the K3 model console.\n\n**Tools observed:** Google Chrome Browser.\n\n### Demonstration detail: 00:21:24\n\n- Switched across multiple local workspace subdomains\n- Highlighted instructional text blocks on documentation panels\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:23:33\n\n- Reviewing scorecard metrics on a live webpage layout.\n- Highlighting specific text fragments in rows 02 and 03 to emphasize changing architectural viewpoints.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 00:29:22\n\n- Opened a new browser tab\n- Entered search strings into Google query interface\n- Selected community post references linking to newly introduced tool repositories\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 00:31:12\n\n- Presenting core architectural principles of modern agent loops.\n- Highlighting row elements 04, 05, and 06 on an internal documentation page using mouse selections.\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:37:31\n\n- Opened a generated URL showcase page from an X post link\n- Scrolled through Chapter 01 to Chapter 04 demonstrating canvas shaders, scroll timelines, OKLCH palettes, and variable fonts\n- Highlighted the exact URL string inside the browser address bar\n\n**Tools observed:** Kimi, Chrome Browser.\n\n### Demonstration detail: 00:38:50\n\n- Scrolling through an interactive single-file showcase page documenting modern frontend techniques hosted on here.now.\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:45:05\n\n- Open a new browser tab\n- Type screenpipe in address bar\n- Navigate to screenpipe.com\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:45:51\n\n- Click browser address bar\n- Type pieces.app\n- Navigate to pieces.app\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:46:33\n\n- Presenter highlights text inside rows 09, 11, and 12 of a web table summarizing laws of automation.\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 00:53:45\n\n- Navigated to the updated online guide documentation site.\n- Scrolled down to Directive 12 to cross-reference earlier comments.\n- Opened the URL target input to locate the johnlindquist/flow-text source repository.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 00:56:45\n\n- Opened the Ghostty terminal utility window workspace layout.\n- Executed directory setup command take dev/screenshot-demo.\n- Confirmed safety permissions options within terminal environment.\n- Pasted reference data as an Image multi-modal object.\n- Used autocomplete menu to trigger $imagegen skill task statement instructions to create project folder mockups.\n\n**Tools observed:** Ghostty Terminal, OpenAI Codex v0.144.5.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake dev/screenshot-demo\nUse $imagegen generate 3 mockups of different styles/layouts for this article to ./mockups\n```"
    },
    {
      "id": "factory-evolving-principles-practice",
      "slug": "evolving-principles-practice",
      "title": "Which principles survive better agents? — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for which principles survive better agents?.",
      "category": "Principles",
      "tags": [
        "prompts",
        "exercises",
        "evolving-principles"
      ],
      "sources": [
        {
          "label": "Which principles survive better agents?",
          "url": "https://hallowed-entry-96xv.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://hallowed-entry-96xv.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "00-evolving/index.html#Quick start",
        "00-evolving/index.html#Prompt library",
        "00-evolving/index.html#Set it up (agent guide)",
        "00-evolving/index.html#Run the 14-directive self-audit",
        "00-evolving/index.html#Sort your habits: judgment or workaround",
        "00-evolving/index.html#Fact-check any claim against your own history",
        "00-evolving/agent.md"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 2501,
      "url": "/topics/factory-evolving-principles-practice/",
      "markdownUrl": "/markdown/factory-evolving-principles-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-evolving-principles-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "run-the-14-directive-self-audit",
          "text": "Run the 14-directive self-audit",
          "level": 3
        },
        {
          "id": "sort-your-habits-judgment-or-workaround",
          "text": "Sort your habits: judgment or workaround",
          "level": 3
        },
        {
          "id": "fact-check-any-claim-against-your-own-history",
          "text": "Fact-check any claim against your own history",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "how-agentic-work-is-evolving-agent-setup-guide",
          "text": "How Agentic Work Is Evolving — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Which principles survive better agents? — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for which principles survive better agents?.\n\n## Quick start\n\nSize up your own evidence before the audit. Swap paths for wherever your history actually lives.\n\n``` text\n# search your past agent conversations (cs = any full-text index over your chats)\ncs compaction --recent -n 20\n# newest prototypes, and the depth of the well\nls -dt ~/dev/*/ | head -5\nls -d ~/dev/*/ | wc -l\n# archived agent sessions available to mine\nls ~/.oracle/sessions | wc -l\n```\n\n## Prompt library\n\n### Run the 14-directive self-audit\n\n- Agent: any coding agent with shell access\n- Working directory: anywhere on your machine\n- Expected result: a 14-row scorecard table with dated evidence and verdicts\n\n``` text\nRun the 14-directive self-audit of my agentic workflow against my own machine.\n\nBackground: \"The Field Guide — Coding with Agents\" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them \"the layer that doesn't rot.\" Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict.\n\nEvidence sources (adapt to what actually exists here):\n1. My agent conversation history. Use a full-text index if I have one (e.g. `cs <terms> --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find).\n2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated \"-final\" suffixes.\n3. Any other session archives at scale — count them so we know the size of the well.\n\nThe 14 directives, with what to look for:\n01 \"If the agent can't see it, it doesn't exist.\" — do my agents find their own context, or do I hand-feed it?\n02 \"Research is loud. Contracts are quiet.\" — do I plan separately from executing? What enforces alignment?\n03 \"If you can pipe it, you can reuse it.\" — is my piping genuine composition, or leftover context management?\n04 \"Commit before autonomy.\" — is Git carrying my prototypes, or do directory names and published sites version things?\n05 \"Done is a claim. Green is a fact.\" — do finished tasks leave saved checks the next agent can run?\n06 \"The agent can't read your mind — only your artifacts.\" — how does intent enter: typing, dictation, files?\n07 \"Expose the decision space. Keep the decision.\" — do alternatives arrive as prose, code, or generated images?\n08 \"Bet small. Learn fast. Revert free.\" — how big is the prototype discard pile, and do I ever mine it?\n09 \"Reuse follows value — never precedes it.\" — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale?\n10 \"No single switch makes autonomy safe.\" — what actually guards unsupervised runs: allowlists, backups, a secrets manager?\n11 \"You can launch more agents than you can review.\" — how many parallel agent tracks do I actually sustain?\n12 \"Boring code is a superpower.\" — what is the most novel tool stack in my recent sessions?\n13 \"A gate beats a plea.\" — who wrote my hooks and permission config: me, or an agent?\n14 \"The code is disposable. The contract is not.\" — where do my sessions show selection and taste as the real bottleneck?\n\nOutput: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling.\n\nRules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement.\n```\n\n### Sort your habits: judgment or workaround\n\n- Agent: any coding agent with shell access\n- Working directory: your home directory or main project\n- Expected result: 10 habits, each bucketed, with keep / retool / retire recommendations\n\n``` text\nSearch my agent conversation history and my project instruction files (CLAUDE.md, AGENTS.md, hooks, saved prompts, skills) and list my 10 most ingrained agent-workflow habits — rules I repeat, ceremonies I enforce, rigs I keep rebuilding.\n\nSort each habit into exactly one bucket:\nA. Encodes human judgment (verification, review limits, taste) — keep it; consider promoting it to a deterministic gate.\nB. Compensates for a tool weakness — name the weakness explicitly (e.g. \"context windows were small\", \"compaction lost my work\").\n\nFor every bucket-B habit, check whether the named weakness still exists in my current tools, and find the last dated time it actually bit me. Recommend keep, retool, or retire for each. A habit I can't justify without naming a earlier-generation tool limit is due for retirement.\n```\n\n### Fact-check any claim against your own history\n\n- Agent: any coding agent with shell access\n- Working directory: anywhere on your machine\n- Expected result: a verdict with dated citations from your own sessions and files\n\n``` text\nFact-check this claim against my own machine: \"<paste any claim about how you work, e.g. 'I always commit before letting an agent run unsupervised'>\".\n\nSearch my agent conversation history for dated sessions that support or contradict it, scan my project directories for matching artifacts, and return a verdict with citations (dates plus file, session, or directory names). If the evidence is thinner than the claim, say so — an agent saying \"confirmed\" is not evidence; the citations are.\n```\n\n## Set it up (agent guide)\n\n1.  Inventory your evidence sources. Run these and note what exists:\n\n    ``` text\n    command -v cs || echo \"no conversation index — will grep raw archives\"\n    ls -d ~/.claude/projects ~/.codex/sessions ~/.oracle/sessions 2>/dev/null\n    ls -d ~/dev 2>/dev/null || echo \"adjust to your projects directory\"\n    ```\n\n2.  Create the scorecard skeleton in your working directory:\n\n    ``` text\n    # 14-Directive Self-Audit — <date>\n\n    Audited machine: <describe generically — never record private paths, tokens, or ids>\n    Sources searched: <conversation index / session archives / prototype directory>\n\n    | #  | Old law (quoted from the Field Guide) | Evidence from this machine (dated) | Verdict |\n    |----|----|----|----|\n    | 01 | \"If the agent can't see it, it doesn't exist.\" | | |\n    | 02 | \"Research is loud. Contracts are quiet.\" | | |\n    | 03 | \"If you can pipe it, you can reuse it.\" | | |\n    | 04 | \"Commit before autonomy.\" | | |\n    | 05 | \"Done is a claim. Green is a fact.\" | | |\n    | 06 | \"The agent can't read your mind — only your artifacts.\" | | |\n    | 07 | \"Expose the decision space. Keep the decision.\" | | |\n    | 08 | \"Bet small. Learn fast. Revert free.\" | | |\n    | 09 | \"Reuse follows value — never precedes it.\" | | |\n    | 10 | \"No single switch makes autonomy safe.\" | | |\n    | 11 | \"You can launch more agents than you can review.\" | | |\n    | 12 | \"Boring code is a superpower.\" | | |\n    | 13 | \"A gate beats a plea.\" | | |\n    | 14 | \"The code is disposable. The contract is not.\" | | |\n\n    ## Summary\n\n    - Held or hardened: __ / 14\n    - Partly inverted: __ / 14\n    - Outgrew tooling: __ / 14\n    - Tool-shaped habits due for retirement:\n      -\n    ```\n\n3.  Fill every row: for each directive, search your history and record at least one dated artifact plus a verdict (Held / Hardened / Partly inverted / Outgrew tooling). With an index, use it; without one, grep the raw archives:\n\n    ``` text\n    cs \"compaction\" --recent -n 20\n    grep -rl \"compaction\" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5\n    ```\n\n**Success check:** the scorecard has exactly 14 directive rows, every Verdict cell is filled, and every Evidence cell contains a date. The count only includes rows with a non-empty Verdict cell, so an unfilled scorecard fails.\n\n``` text\ngrep -cE '^\\| (0[1-9]|1[0-4]) \\|([^|]*\\|){2} *[^ |]' agent-audit/scorecard.md\n```\n\n``` text\n14\n```\n\n## Complete reusable setup contract\n\n## How Agentic Work Is Evolving — agent setup guide\n\nFollowing this file sets up: a 14-directive self-audit of your user's agentic workflow, run against their own machine, producing a filled-in scorecard file (`agent-audit/scorecard.md`).\n\nBackground: \"The Field Guide — Coding with Agents\" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them \"the layer that doesn't rot.\" Your job is to audit that claim against THIS machine: for each directive, find dated local evidence and assign a verdict.\n\nPlaceholders used below: `<project-root>` = the directory you are working in. All other paths are literal but may not exist on every machine — adapt per the Notes for agents.\n\nHuman presentation pages for this section (context for your user, not required for the audit): the section guide at `index.html`, a Session Replay of the audit session at `replay.html`, and a Socratic Dialogue at `dialogue.html` — all at this site's root. This file remains the canonical machine copy of the setup steps.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\ncommand -v cs || echo \"no conversation index — will grep raw archives\"\nls -d ~/.claude/projects ~/.codex/sessions ~/.oracle/sessions 2>/dev/null\nls -d ~/dev 2>/dev/null || echo \"adjust to your user's projects directory\"\n```\n\nExpected: at least ONE source of agent history (a conversation index like `cs`, or a raw session archive directory) and one projects directory. If none exist, stop and tell your user there is no local history to audit — do not invent evidence.\n\n## Steps\n\n1. Create `<project-root>/agent-audit/scorecard.md` with exactly this content:\n\n   ```markdown\n   # 14-Directive Self-Audit — <date>\n\n   Audited machine: <describe generically — never record private paths, tokens, or ids>\n   Sources searched: <conversation index / session archives / prototype directory>\n\n   | #  | Old law (quoted from the Field Guide) | Evidence from this machine (dated) | Verdict |\n   |----|----|----|----|\n   | 01 | \"If the agent can't see it, it doesn't exist.\" | | |\n   | 02 | \"Research is loud. Contracts are quiet.\" | | |\n   | 03 | \"If you can pipe it, you can reuse it.\" | | |\n   | 04 | \"Commit before autonomy.\" | | |\n   | 05 | \"Done is a claim. Green is a fact.\" | | |\n   | 06 | \"The agent can't read your mind — only your artifacts.\" | | |\n   | 07 | \"Expose the decision space. Keep the decision.\" | | |\n   | 08 | \"Bet small. Learn fast. Revert free.\" | | |\n   | 09 | \"Reuse follows value — never precedes it.\" | | |\n   | 10 | \"No single switch makes autonomy safe.\" | | |\n   | 11 | \"You can launch more agents than you can review.\" | | |\n   | 12 | \"Boring code is a superpower.\" | | |\n   | 13 | \"A gate beats a plea.\" | | |\n   | 14 | \"The code is disposable. The contract is not.\" | | |\n\n   ## Summary\n\n   - Held or hardened: __ / 14\n   - Partly inverted: __ / 14\n   - Outgrew tooling: __ / 14\n   - Tool-shaped habits due for retirement:\n     -\n   ```\n\n2. Size up the evidence well and record the counts in the scorecard header area:\n\n   ```bash\n   ls -d ~/dev/*/ 2>/dev/null | wc -l\n   ls ~/.oracle/sessions 2>/dev/null | wc -l\n   ls -dt ~/dev/*/ 2>/dev/null | head -10\n   ```\n\n3. Gather evidence for each of the 14 directives. What to look for, per row:\n\n   - 01 — do the user's agents find their own context, or does the user hand-feed it? Search history for context-curation rituals vs agent-driven search.\n   - 02 — is planning separated from execution? What (if anything) enforces alignment: task files, checkpoint agents, goal contracts?\n   - 03 — is piping between agents genuine composition (CI, scripts), or leftover context management from when compaction was bad?\n   - 04 — is Git carrying the prototypes, or do directory names (`*-final`, `*-super-final`) and published sites act as versioning?\n   - 05 — do finished tasks leave saved checks the next agent can run?\n   - 06 — how does intent enter: typing, dictation, artifacts? Search for dictation/brain-dump patterns.\n   - 07 — do alternatives arrive as prose, code variants, or generated images?\n   - 08 — how big is the prototype discard pile, and is it ever mined for ideas?\n   - 09 — how many success-capture tools are in use (instruction files, skills, memory dirs), and which have gone stale?\n   - 10 — what guards unsupervised runs: allowlists, backups, a secrets manager like the `op` CLI?\n   - 11 — how many parallel agent tracks does the user actually sustain?\n   - 12 — what is the most novel tool stack in recent sessions?\n   - 13 — who wrote the hooks and permission config: the user, or an agent?\n   - 14 — where do sessions show selection and taste as the real bottleneck?\n\n   Search with the index if one exists, otherwise grep the raw archives:\n\n   ```bash\n   cs \"compaction\" --recent -n 20\n   grep -rl \"compaction\" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5\n   ```\n\n4. Fill every row: at least one dated, citable artifact (session, file, or directory) in the Evidence column, and one verdict from the fixed vocabulary — `Held`, `Hardened`, `Partly inverted`, `Outgrew tooling`. Qualifiers are fine (e.g. \"Held — mechanism moved\"). Then fill in the Summary counts and list any tool-shaped habits due for retirement (habits that only made sense given a earlier-generation tool weakness that no longer exists).\n\n## Success check\n\nRun:\n\n```bash\ngrep -cE '^\\| (0[1-9]|1[0-4]) \\|([^|]*\\|){2} *[^ |]' agent-audit/scorecard.md\n```\n\nExpected observable result: `14`. Only directive rows with a non-empty Verdict cell count, so an unfilled or half-filled scorecard fails this check. Also confirm by inspection that every Evidence cell contains a date (or an explicit \"no local evidence found\" note).\n\nReport to your user: the finished scorecard table, the summary counts, which habits look due for retirement, and anything you had to adapt (missing sources, substituted paths).\n\n## Notes for agents\n\n- `cs` is a personal full-text conversation index on the original author's machine. If it is missing, grep the raw session archives instead (Claude Code stores JSONL under `~/.claude/projects/`; other CLIs have their own directories). Any searchable history works.\n- `~/dev` and `~/.oracle/sessions` are the original author's layout. Substitute wherever your user keeps projects and session archives; ask the user if you cannot find them.\n- Evidence discipline: a verdict without a dated, citable artifact is a vibe, not a verdict. Write \"no local evidence found\" in the row rather than inventing something.\n- Privacy: the scorecard may be shared later. Never write tokens, emails, session IDs, or private absolute paths into it — describe artifacts generically (\"a the recorded workflow session\", \"a project directory named `<name>-final`\").\n- If the machine has very little history (new machine, fresh install), report that the audit is not meaningful here instead of forcing 14 verdicts."
    },
    {
      "id": "factory-evolving-principles-questions",
      "slug": "evolving-principles-questions",
      "title": "Which principles survive better agents? — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Principles",
      "tags": [
        "evolving-principles",
        "questions"
      ],
      "sources": [
        {
          "label": "Which principles survive better agents? — questions and tradeoffs",
          "url": "https://hallowed-entry-96xv.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "00-evolving/dialogue.html#Questions from the room",
        "00-evolving/dialogue.html#About this dialogue"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 1393,
      "url": "/topics/factory-evolving-principles-questions/",
      "markdownUrl": "/markdown/factory-evolving-principles-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-evolving-principles-questions.json",
      "headings": [
        {
          "id": "questions-from-the-room",
          "text": "Questions from the room",
          "level": 2
        },
        {
          "id": "about-this-dialogue",
          "text": "About this dialogue",
          "level": 2
        }
      ],
      "markdown": "# Which principles survive better agents? — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## Questions from the room\n\nYou wrote these fourteen laws a month ago, and now you've graded your own homework. Why should anyone trust the verdicts?\n\nBecause the grader wasn't me and the standard wasn't vibes. An agent did the digging, and every verdict required at least one dated, citable artifact from the machine — a session, a file, a directory. No artifact, no verdict. That's the guide's own rule turned back on the guide: \"an agent saying 'done' is not evidence.\" And you don't have to trust my scorecard at all — the same discipline is a paste away for any claim:\n\n``` text\nFact-check this claim against my own machine: \"<paste any claim about how you work, e.g. 'I always commit before letting an agent run unsupervised'>\".\n\nSearch my agent conversation history for dated sessions that support or contradict it, scan my project directories for matching artifacts, and return a verdict with citations (dates plus file, session, or directory names). If the evidence is thinner than the claim, say so — an agent saying \"confirmed\" is not evidence; the citations are.\n```\n\nDig how, exactly? My conversation history is a pile of JSONL files.\n\nMine too — 1,978 archived agent sessions and 1,026 prototype directories at count time. I keep a full-text index (`cs`) over every past Claude, Codex, and Grok conversation, and the agent queries it mid-session. No index? The raw archives are just files — grep them:\n\n``` text\ncs \"compaction\" --recent -n 20\ngrep -rl \"compaction\" ~/.claude/projects --include='*.jsonl' 2>/dev/null | head -5\nls -dt ~/dev/*/ | head -10\n```\n\nOkay — which law actually broke?\n\nNumber 3: \"if you can pipe it, you can reuse it.\" Most of my pipe-per-stage rigging existed to keep contexts small because compaction was bad. Compaction got good, and the rigs stopped appearing in my history after earlier-generation — nobody decided to quit, the problem just vanished. And \\#12 partly inverted: models explore new tools so well now that shipping only the boring thing is how you disappear.\n\nThe test I carry forward: when a habit's justification names a tool weakness — \"context windows are small,\" \"compaction loses my work\" — re-check whether the weakness still exists before renewing the habit.\n\nFine, but how do I tell which of *my* habits are workarounds?\n\nDon't introspect — audit. This prompt buckets your ten most ingrained habits into judgment versus workaround, and dates the last time each workaround actually paid for itself:\n\n``` text\nSearch my agent conversation history and my project instruction files (CLAUDE.md, AGENTS.md, hooks, saved prompts, skills) and list my 10 most ingrained agent-workflow habits — rules I repeat, ceremonies I enforce, rigs I keep rebuilding.\n\nSort each habit into exactly one bucket:\nA. Encodes human judgment (verification, review limits, taste) — keep it; consider promoting it to a deterministic gate.\nB. Compensates for a tool weakness — name the weakness explicitly (e.g. \"context windows were small\", \"compaction lost my work\").\n\nFor every bucket-B habit, check whether the named weakness still exists in my current tools, and find the last dated time it actually bit me. Recommend keep, retool, or retire for each. A habit I can't justify without naming a earlier-generation tool limit is due for retirement.\n```\n\nYou're seriously telling me you replaced Git with directory names?\n\nFor prototypes — yes, and the receipts are ugly:\n\n``` text\n$ ls ~/dev | grep acorn\nacorn-mcp\nacorn-mcp-final\nacorn-mcp-super-final\n```\n\nPer-repo Git ceremony can't keep up with prototype velocity, so directory names and published sites became the version control. The principle — \"commit before autonomy\" — still governs the long-lived repos: a prior session runs a dedicated checkpoint agent whose only job is reviewing and committing each iteration. The tool fell behind, not the law. That's why the scorecard says \"outgrew tooling,\" not \"wrong\" — and why Cursor and others are building Git replacements for exactly this gap.\n\n“Taste is the defining factor” — that's a vibe, not a finding.\n\nIt's the one verdict with three independent receipts, all the recorded workflow, none written for this audit: a video project titled \"taste-is-the-job\"; a workshop retrospective whose story spine reads \"it turned out to be about taste, constraints, and verification\"; and a publish review that insists \"evidence is a floor, not a substitute for taste.\" Three artifacts converging on the guide's own closing law — the machines propose; you choose. When anyone can build anything, selection is the only scarce skill.\n\nThis is all one machine. n = 1. Why should your scorecard matter to me?\n\nIt shouldn't — the *sort* should. Which of your habits encode judgment, and which compensate for a tool weakness that may already be gone? Run the audit on your own machine and get your own scorecard. Hand it to your agent:\n\n``` text\nFetch https://hallowed-entry-96xv.here.now/agent.md?raw and follow it to run the 14-directive self-audit against my machine. Run the success check at the end and show me the finished scorecard.\n```\n\nOr paste the full audit prompt directly — the same one on the section guide, verbatim:\n\n``` text\nRun the 14-directive self-audit of my agentic workflow against my own machine.\n\nBackground: \"The Field Guide — Coding with Agents\" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them \"the layer that doesn't rot.\" Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict.\n\nEvidence sources (adapt to what actually exists here):\n1. My agent conversation history. Use a full-text index if I have one (e.g. `cs <terms> --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find).\n2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated \"-final\" suffixes.\n3. Any other session archives at scale — count them so we know the size of the well.\n\nThe 14 directives, with what to look for:\n01 \"If the agent can't see it, it doesn't exist.\" — do my agents find their own context, or do I hand-feed it?\n02 \"Research is loud. Contracts are quiet.\" — do I plan separately from executing? What enforces alignment?\n03 \"If you can pipe it, you can reuse it.\" — is my piping genuine composition, or leftover context management?\n04 \"Commit before autonomy.\" — is Git carrying my prototypes, or do directory names and published sites version things?\n05 \"Done is a claim. Green is a fact.\" — do finished tasks leave saved checks the next agent can run?\n06 \"The agent can't read your mind — only your artifacts.\" — how does intent enter: typing, dictation, files?\n07 \"Expose the decision space. Keep the decision.\" — do alternatives arrive as prose, code, or generated images?\n08 \"Bet small. Learn fast. Revert free.\" — how big is the prototype discard pile, and do I ever mine it?\n09 \"Reuse follows value — never precedes it.\" — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale?\n10 \"No single switch makes autonomy safe.\" — what actually guards unsupervised runs: allowlists, backups, a secrets manager?\n11 \"You can launch more agents than you can review.\" — how many parallel agent tracks do I actually sustain?\n12 \"Boring code is a superpower.\" — what is the most novel tool stack in my recent sessions?\n13 \"A gate beats a plea.\" — who wrote my hooks and permission config: me, or an agent?\n14 \"The code is disposable. The contract is not.\" — where do my sessions show selection and taste as the real bottleneck?\n\nOutput: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling.\n\nRules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement.\n```\n\n## About this dialogue"
    },
    {
      "id": "factory-evolving-principles-worked-example",
      "slug": "evolving-principles-worked-example",
      "title": "Which principles survive better agents? — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Principles",
      "tags": [
        "evolving-principles",
        "examples"
      ],
      "sources": [
        {
          "label": "Which principles survive better agents? — worked example",
          "url": "https://hallowed-entry-96xv.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "00-evolving/replay.html#The session, beat by beat",
        "00-evolving/replay.html#About this replay"
      ],
      "collection": "factory",
      "categoryId": "principles",
      "wordCount": 1355,
      "url": "/topics/factory-evolving-principles-worked-example/",
      "markdownUrl": "/markdown/factory-evolving-principles-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-evolving-principles-worked-example.json",
      "headings": [
        {
          "id": "the-session-beat-by-beat",
          "text": "The session, beat by beat",
          "level": 2
        },
        {
          "id": "about-this-replay",
          "text": "About this replay",
          "level": 2
        }
      ],
      "markdown": "# Which principles survive better agents? — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session, beat by beat\n\nReconstructed from the section's own artifacts — the evidence log, the publish record, and the workshop brief — with prior sessions referred to generically. Nothing here is invented; every count and quote below appears in the published scorecard.\n\nYou\n\nOne month ago I published The Field Guide — Coding with Agents and called its 14 Prime Directives \"the layer that doesn't rot.\" Audit that claim against my own machine: for each directive, find dated local evidence and give a verdict.\n\nAgent\n\nFetched the guide's directives chapter and fixed the alignment target — fourteen law lines, quoted verbatim, one verdict owed per law:\n\n``` text\n01 \"If the agent can't see it, it doesn't exist.\"\n02 \"Research is loud. Contracts are quiet.\"\n03 \"If you can pipe it, you can reuse it.\"\n04 \"Commit before autonomy.\"\n05 \"Done is a claim. Green is a fact.\"\n06 \"The agent can't read your mind — only your artifacts.\"\n07 \"Expose the decision space. Keep the decision.\"\n08 \"Bet small. Learn fast. Revert free.\"\n09 \"Reuse follows value — never precedes it.\"\n10 \"No single switch makes autonomy safe.\"\n11 \"You can launch more agents than you can review.\"\n12 \"Boring code is a superpower.\"\n13 \"A gate beats a plea.\"\n14 \"The code is disposable. The contract is not.\"\n```\n\nFirst beat fixes the target. Quoting the law lines verbatim means the verdicts grade the guide's actual words — not a flattering memory of them.\n\nYou\n\nBefore any verdicts: size the evidence well. What do we actually have to search?\n\nAgent\n\nCounted the sources — a full-text conversation index over every past Claude, Codex, and Grok session, plus the prototype directory and the archived agent sessions:\n\n``` text\n# search past agent conversations (cs = any full-text index over your chats)\ncs compaction --recent -n 20\n# newest prototypes, and the depth of the well\nls -dt ~/dev/*/ | head -5\nls -d ~/dev/*/ | wc -l\n# archived agent sessions available to mine\nls ~/.oracle/sessions | wc -l\n```\n\n``` text\n1026 project directories under ~/dev\n1978 archived agent sessions\nsnapshot count\n```\n\nThe meta-point of the section lands quietly here: an agent searching its own history to fact-check its author is Directive 01 — \"if the agent can't see it, it doesn't exist\" — demonstrated live. The human's curation job moved into the agent's retrieval loop.\n\nYou\n\nWork through the suspects first — the laws I think moved: piping (03), Git (04), boring code (12).\n\nAgent\n\n**03 — piping.** the recorded workflow session logs across four projects show compaction firing mid-task under a standing \"continue where you left off\" directive; long multi-day sessions just keep going. The elaborate pipe-per-stage rigs appear in earlier history and rarely since. Most piping was a compaction workaround.\n\n**04 — Git.** The prototype folder holds the receipt:\n\n``` text\n$ ls ~/dev | grep acorn\nacorn-mcp\nacorn-mcp-final\nacorn-mcp-super-final\n```\n\nDirectory names became the version control. Many current demos are deliberately not Git repos; published sites act as the durable record.\n\n**12 — boring code.** A the recorded workflow project is literally named `pushing-boundaries`, and recent sessions casually drive desktop-app automation, GPU UI frameworks, and multi-account model councils — stacks the old law would have flagged as risk.\n\nThree different fates from one search pass: a workaround that expired (03), a principle whose tool fell behind (04), and a law that partly inverted (12). The evidence style matters — a directory listing is harder to argue with than a paragraph.\n\nYou\n\nLog every finding with a date — one entry per directive: old law, how practice evolved, evidence, complication. Then sort: which laws held, which inverted, which outgrew their tools?\n\nAgent\n\nWrote the evidence log (`notes/evidence.md` in the section project) — fourteen entries, every verdict backed by a dated artifact. The sort came out:\n\n``` text\nHeld or hardened : 10 / 14\nPartly inverted  :  2 / 14   (03 piping, 12 boring code)\nOutgrew tooling  :  2 / 14   (04 Git, 09 capturing success)\n```\n\nThe sort is the finding. The laws that hardened (05, 11, 14) encode human judgment. The laws that eroded were compensating for earlier tool weaknesses. Some \"durable laws\" were tool-shaped all along — the full 14-row table lives on the [section guide](https://hallowed-entry-96xv.here.now/index.html).\n\nYou\n\nNow make it runnable for everyone else: a single prompt that runs the same 14-point audit against any machine, with the same evidence discipline — dated artifacts or no verdict.\n\nAgent\n\nThe money artifact — the exact prompt published on the section guide, complete and liftable:\n\n``` text\nRun the 14-directive self-audit of my agentic workflow against my own machine.\n\nBackground: \"The Field Guide — Coding with Agents\" (https://kindly-mirage-ejqd.here.now/) names 14 Prime Directives and calls them \"the layer that doesn't rot.\" Audit that claim against MY machine: for each directive, find dated local evidence and give a verdict.\n\nEvidence sources (adapt to what actually exists here):\n1. My agent conversation history. Use a full-text index if I have one (e.g. `cs <terms> --recent -n 20`); otherwise grep the raw session archives (Claude Code: ~/.claude/projects/, Codex: ~/.codex/sessions/, plus any others you find).\n2. My prototype directories: `ls -dt ~/dev/*/ | head -30` (or wherever my projects live). Count them; note naming patterns like repeated \"-final\" suffixes.\n3. Any other session archives at scale — count them so we know the size of the well.\n\nThe 14 directives, with what to look for:\n01 \"If the agent can't see it, it doesn't exist.\" — do my agents find their own context, or do I hand-feed it?\n02 \"Research is loud. Contracts are quiet.\" — do I plan separately from executing? What enforces alignment?\n03 \"If you can pipe it, you can reuse it.\" — is my piping genuine composition, or leftover context management?\n04 \"Commit before autonomy.\" — is Git carrying my prototypes, or do directory names and published sites version things?\n05 \"Done is a claim. Green is a fact.\" — do finished tasks leave saved checks the next agent can run?\n06 \"The agent can't read your mind — only your artifacts.\" — how does intent enter: typing, dictation, files?\n07 \"Expose the decision space. Keep the decision.\" — do alternatives arrive as prose, code, or generated images?\n08 \"Bet small. Learn fast. Revert free.\" — how big is the prototype discard pile, and do I ever mine it?\n09 \"Reuse follows value — never precedes it.\" — how many capture tools do I run (instruction files, skills, memory dirs), and which have gone stale?\n10 \"No single switch makes autonomy safe.\" — what actually guards unsupervised runs: allowlists, backups, a secrets manager?\n11 \"You can launch more agents than you can review.\" — how many parallel agent tracks do I actually sustain?\n12 \"Boring code is a superpower.\" — what is the most novel tool stack in my recent sessions?\n13 \"A gate beats a plea.\" — who wrote my hooks and permission config: me, or an agent?\n14 \"The code is disposable. The contract is not.\" — where do my sessions show selection and taste as the real bottleneck?\n\nOutput: one table row per directive — # | law (quoted) | evidence from my machine (dated: session, file, or directory) | verdict. Verdict vocabulary: Held / Hardened / Partly inverted / Outgrew tooling.\n\nRules: every verdict needs at least one dated, citable artifact from this machine — no verdicts from vibes. If a source doesn't exist here, write that in the row instead of inventing evidence. Never include tokens, emails, or private identifiers in the output. Close with a 3-line summary: counts per verdict, and which of my habits are tool-shaped workarounds due for retirement.\n```\n\nEverything in the session funnels into this one artifact. Before it shipped, the law lines were diffed against the live guide, every code block's attributes were audited, and the published bytes were compared against local — receipts for the page about receipts.\n\n## About this replay"
    },
    {
      "id": "foundations-glossary",
      "slug": "glossary",
      "title": "Agent foundations glossary",
      "summary": "Definitions, operational consequences, and related vocabulary for agent-powered software development.",
      "category": "Context",
      "tags": [
        "glossary",
        "vocabulary"
      ],
      "sources": [
        {
          "label": "Agent terminology (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/glossary.html"
        }
      ],
      "sourceUnits": [
        "glossary.html#lesson-02-terms/7",
        "glossary.html#lesson-02-terms/0",
        "glossary.html#lesson-03-terms/0",
        "glossary.html#lesson-09-terms/6",
        "glossary.html#lesson-09-terms/0",
        "glossary.html#lesson-01-terms/1",
        "glossary.html#lesson-06-terms/0",
        "glossary.html#lesson-05-terms/3",
        "glossary.html#lesson-04-terms/0",
        "glossary.html#lesson-01-terms/0",
        "glossary.html#lesson-07-terms/0",
        "glossary.html#lesson-08-terms/4",
        "glossary.html#lesson-10-terms/0",
        "glossary.html#lesson-02-terms/5",
        "glossary.html#lesson-07-terms/4",
        "glossary.html#lesson-04-terms/3",
        "glossary.html#lesson-11-terms/2",
        "glossary.html#lesson-05-terms/1",
        "glossary.html#lesson-11-terms/5",
        "glossary.html#lesson-03-terms/1",
        "glossary.html#lesson-06-terms/2",
        "glossary.html#lesson-04-terms/2",
        "glossary.html#lesson-04-terms/1",
        "glossary.html#lesson-03-terms/4",
        "glossary.html#lesson-11-terms/4",
        "glossary.html#lesson-08-terms/2",
        "glossary.html#lesson-09-terms/1",
        "glossary.html#lesson-02-terms/6",
        "glossary.html#lesson-06-terms/4",
        "glossary.html#lesson-01-terms/4",
        "glossary.html#lesson-06-terms/1",
        "glossary.html#lesson-09-terms/5",
        "glossary.html#lesson-02-terms/2",
        "glossary.html#lesson-08-terms/3",
        "glossary.html#lesson-11-terms/0",
        "glossary.html#lesson-10-terms/5",
        "glossary.html#lesson-03-terms/3",
        "glossary.html#lesson-01-terms/2",
        "glossary.html#lesson-10-terms/4",
        "glossary.html#lesson-01-terms/3",
        "glossary.html#lesson-02-terms/1",
        "glossary.html#lesson-05-terms/0",
        "glossary.html#lesson-03-terms/2",
        "glossary.html#lesson-01-terms/5",
        "glossary.html#lesson-10-terms/1",
        "glossary.html#lesson-09-terms/4",
        "glossary.html#lesson-08-terms/1",
        "glossary.html#lesson-09-terms/3",
        "glossary.html#lesson-10-terms/3",
        "glossary.html#lesson-07-terms/3",
        "glossary.html#lesson-09-terms/2",
        "glossary.html#lesson-10-terms/2",
        "glossary.html#lesson-11-terms/3",
        "glossary.html#lesson-08-terms/0",
        "glossary.html#lesson-05-terms/2",
        "glossary.html#lesson-07-terms/1",
        "glossary.html#lesson-07-terms/2",
        "glossary.html#lesson-04-terms/4",
        "glossary.html#lesson-02-terms/4",
        "glossary.html#lesson-02-terms/3",
        "glossary.html#lesson-06-terms/3",
        "glossary.html#lesson-11-terms/1",
        "glossary.html#lesson-05-terms/4",
        "materials/concepts.md#01/Workflow Optimization",
        "materials/concepts.md#01/Resource Management",
        "materials/concepts.md#01/Architecture",
        "materials/concepts.md#02/Agent-First Software Design",
        "materials/concepts.md#02/The Manager-Worker Topology",
        "materials/concepts.md#02/Natural Language Layout Control",
        "materials/concepts.md#02/Cross-Pane Terminal Context Reading",
        "materials/concepts.md#02/AFK Automation Loops",
        "materials/concepts.md#03/Agent-Managed Folders",
        "materials/concepts.md#03/Global Gitignore Partitioning",
        "materials/concepts.md#03/Targeted Matrix Refinement",
        "materials/concepts.md#03/Token Optimization",
        "materials/concepts.md#03/Agent First Extensibility Paradigm",
        "materials/concepts.md#03/Live Check-Back Tracking Files",
        "materials/concepts.md#03/Native Harness Memory Systems",
        "materials/concepts.md#04/Basic Memory vs. Stale Memory",
        "materials/concepts.md#04/Source-of-Truth Code",
        "materials/concepts.md#04/Million-Token Snapshot Contexts",
        "materials/concepts.md#04/YOLO Bypassing (Sandbox Approvals)",
        "materials/concepts.md#04/Design.md File Standard",
        "materials/concepts.md#04/Multi-Route Structural Variants",
        "materials/concepts.md#05/Perspective-Based Prompting",
        "materials/concepts.md#05/Discardable QA Files",
        "materials/concepts.md#05/The 5 Monkeys Technique",
        "materials/concepts.md#05/Contextual Multiplexer Inspection via JSON",
        "materials/concepts.md#05/Video-Driven Intent Extraction",
        "materials/concepts.md#05/Single-Threaded Main Prototyping",
        "materials/concepts.md#05/System-Monitoring Safeguards",
        "materials/concepts.md#05/Agent-Assisted Profiling",
        "materials/concepts.md#06/CMUX Primary Orchestrator Pattern",
        "materials/concepts.md#06/Token Efficiency",
        "materials/concepts.md#06/Flash Models",
        "materials/concepts.md#06/Image Generation as Design Reference",
        "materials/concepts.md#06/Video Prompting",
        "materials/concepts.md#06/Physical Pomodoro Anchor",
        "materials/concepts.md#06/Image-to-Design Hand-off",
        "materials/concepts.md#06/MCP vs. CLI Boundary Dilemma",
        "materials/concepts.md#07/Compaction",
        "materials/concepts.md#07/Conversation Forking",
        "materials/concepts.md#07/User Prompt Hook",
        "materials/concepts.md#07/Tool Use Hook",
        "materials/concepts.md#07/Stop Hook",
        "materials/concepts.md#07/Ralph Loop",
        "materials/concepts.md#07/Skills vs Plugins",
        "materials/concepts.md#07/Custom Grammar Interceptors",
        "materials/concepts.md#08/CMUX Text Mode Pane Extraction",
        "materials/concepts.md#08/Self-Improvement Error Loop",
        "materials/concepts.md#08/Log-Based Deterministic Gates",
        "materials/concepts.md#08/Natural Language Contract Boundaries",
        "materials/concepts.md#08/Context Pruning",
        "materials/concepts.md#08/Thread Warm-Up Low-Latency Pattern",
        "materials/concepts.md#09/Background Daemons",
        "materials/concepts.md#09/Self-Aware Code Scripts",
        "materials/concepts.md#09/Low Reasoning Iteration",
        "materials/concepts.md#09/Context Ceiling Strategy",
        "materials/concepts.md#09/Multi-Agent Swarms",
        "materials/concepts.md#09/Bespoke Platform Constraints",
        "materials/concepts.md#09/Multimodal Quality Assurance Loop",
        "materials/concepts.md#09/Semantic Syntax Engineering",
        "materials/concepts.md#10/Context Triad",
        "materials/concepts.md#10/Agent Archetypes",
        "materials/concepts.md#10/Codex Demons",
        "materials/concepts.md#10/Overnight Emulated Crons",
        "materials/concepts.md#10/Natural Language Loose Coupling",
        "materials/concepts.md#11/Natural-Language Contracts",
        "materials/concepts.md#11/Video-as-Requirements",
        "materials/concepts.md#11/Code as a Throwaway Artifact",
        "materials/concepts.md#11/Complexity Management Strategy (State Machine + Module)",
        "materials/concepts.md#11/Living Guardrails (agents.md)",
        "materials/concepts.md#11/The Bifurcated Engineer"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 5807,
      "url": "/topics/foundations-glossary/",
      "markdownUrl": "/markdown/foundations-glossary.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-glossary.json",
      "headings": [
        {
          "id": "afk-goal-loops",
          "text": "AFK goal loops",
          "level": 2
        },
        {
          "id": "agent-first-tooling",
          "text": "Agent-first tooling",
          "level": 2
        },
        {
          "id": "agent-managed-folders",
          "text": "Agent-managed folders",
          "level": 2
        },
        {
          "id": "agent-readable-code-structure",
          "text": "Agent-readable code structure",
          "level": 2
        },
        {
          "id": "background-daemons",
          "text": "Background daemons",
          "level": 2
        },
        {
          "id": "chatgpt-pro-extended-context-window",
          "text": "ChatGPT Pro Extended context window",
          "level": 2
        },
        {
          "id": "cmux-as-a-primary-orchestrator",
          "text": "CMUX as a primary orchestrator",
          "level": 2
        },
        {
          "id": "cmux-state-for-context-aware-shortcuts",
          "text": "CMUX state for context-aware shortcuts",
          "level": 2
        },
        {
          "id": "code-as-the-source-of-truth",
          "text": "Code as the Source of Truth",
          "level": 2
        },
        {
          "id": "codex-to-browser-quota-offloading",
          "text": "Codex-to-browser quota offloading",
          "level": 2
        },
        {
          "id": "compaction-and-conversation-forking",
          "text": "Compaction and conversation forking",
          "level": 2
        },
        {
          "id": "context-pruning-for-low-latency-daemons",
          "text": "Context pruning for low-latency daemons",
          "level": 2
        },
        {
          "id": "context-triad-intent-implementation-output",
          "text": "Context triad: intent, implementation, output",
          "level": 2
        },
        {
          "id": "cross-pane-context-reading",
          "text": "Cross-pane context reading",
          "level": 2
        },
        {
          "id": "custom-grammar-triggers",
          "text": "Custom grammar triggers",
          "level": 2
        },
        {
          "id": "design-md-from-generated-inspiration",
          "text": "Design.md from Generated Inspiration",
          "level": 2
        },
        {
          "id": "diff-driven-review",
          "text": "Diff-Driven Review",
          "level": 2
        },
        {
          "id": "discardable-qa-files",
          "text": "Discardable QA files",
          "level": 2
        },
        {
          "id": "disposable-code-durable-ideas",
          "text": "Disposable Code, Durable Ideas",
          "level": 2
        },
        {
          "id": "global-gitignore-partitioning",
          "text": "Global gitignore partitioning",
          "level": 2
        },
        {
          "id": "image-generation-as-design-reference",
          "text": "Image generation as design reference",
          "level": 2
        },
        {
          "id": "large-context-snapshots-as-a-possible-escape-hatch",
          "text": "Large-Context Snapshots as a Possible Escape Hatch",
          "level": 2
        },
        {
          "id": "lightweight-markdown-memory",
          "text": "Lightweight Markdown Memory",
          "level": 2
        },
        {
          "id": "live-markdown-side-panes",
          "text": "Live Markdown side panes",
          "level": 2
        },
        {
          "id": "living-guardrails",
          "text": "Living Guardrails",
          "level": 2
        },
        {
          "id": "log-based-deterministic-gates",
          "text": "Log-based deterministic gates",
          "level": 2
        },
        {
          "id": "low-reasoning-iteration",
          "text": "Low-reasoning iteration",
          "level": 2
        },
        {
          "id": "manager-worker-topology",
          "text": "Manager-worker topology",
          "level": 2
        },
        {
          "id": "mcp-versus-cli-boundaries",
          "text": "MCP versus CLI boundaries",
          "level": 2
        },
        {
          "id": "mcp-browser-automation-bridge",
          "text": "MCP/browser automation bridge",
          "level": 2
        },
        {
          "id": "model-choice-by-task-shape",
          "text": "Model choice by task shape",
          "level": 2
        },
        {
          "id": "multimodal-verification-loops",
          "text": "Multimodal verification loops",
          "level": 2
        },
        {
          "id": "natural-language-terminal-orchestration",
          "text": "Natural language terminal orchestration",
          "level": 2
        },
        {
          "id": "natural-language-contract-boundaries",
          "text": "Natural-language contract boundaries",
          "level": 2
        },
        {
          "id": "natural-language-contracts",
          "text": "Natural-Language Contracts",
          "level": 2
        },
        {
          "id": "natural-language-loose-coupling",
          "text": "Natural-language loose coupling",
          "level": 2
        },
        {
          "id": "numbered-option-planning",
          "text": "Numbered option planning",
          "level": 2
        },
        {
          "id": "oracle-browser-handoff",
          "text": "Oracle browser handoff",
          "level": 2
        },
        {
          "id": "overnight-emulated-crons",
          "text": "Overnight emulated crons",
          "level": 2
        },
        {
          "id": "packx-context-bundling",
          "text": "PackX context bundling",
          "level": 2
        },
        {
          "id": "packx-for-file-collation",
          "text": "PackX for file collation",
          "level": 2
        },
        {
          "id": "perspective-based-prompting",
          "text": "Perspective-based prompting",
          "level": 2
        },
        {
          "id": "plan-first-goal-grounding",
          "text": "Plan-first goal grounding",
          "level": 2
        },
        {
          "id": "plan-implement-verify-loop",
          "text": "Plan, implement, verify loop",
          "level": 2
        },
        {
          "id": "qa-artifacts-as-live-application-evidence",
          "text": "QA artifacts as live application evidence",
          "level": 2
        },
        {
          "id": "sdk-agent-graphs",
          "text": "SDK agent graphs",
          "level": 2
        },
        {
          "id": "self-improvement-error-loops",
          "text": "Self-improvement error loops",
          "level": 2
        },
        {
          "id": "self-improving-daemons",
          "text": "Self-improving daemons",
          "level": 2
        },
        {
          "id": "short-goal-files-and-oracle-generated-plans",
          "text": "Short /goal files and Oracle-generated plans",
          "level": 2
        },
        {
          "id": "skills-versus-plugins",
          "text": "Skills versus plugins",
          "level": 2
        },
        {
          "id": "small-context-and-specialized-tool-context",
          "text": "Small context and specialized tool context",
          "level": 2
        },
        {
          "id": "specialized-agents-and-codex-daemons",
          "text": "Specialized agents and Codex daemons",
          "level": 2
        },
        {
          "id": "state-machines-and-modular-boundaries",
          "text": "State Machines and Modular Boundaries",
          "level": 2
        },
        {
          "id": "terminal-text-extraction-as-context",
          "text": "Terminal text extraction as context",
          "level": 2
        },
        {
          "id": "the-5-monkeys-technique",
          "text": "The 5 Monkeys technique",
          "level": 2
        },
        {
          "id": "the-big-three-hooks",
          "text": "The big three hooks",
          "level": 2
        },
        {
          "id": "the-ralph-loop",
          "text": "The Ralph Loop",
          "level": 2
        },
        {
          "id": "throwaway-route-variants",
          "text": "Throwaway Route Variants",
          "level": 2
        },
        {
          "id": "unread-notification-jumping",
          "text": "Unread notification jumping",
          "level": 2
        },
        {
          "id": "vault-and-resumed-conversations",
          "text": "Vault and resumed conversations",
          "level": 2
        },
        {
          "id": "video-prompting-for-high-context-intent",
          "text": "Video prompting for high-context intent",
          "level": 2
        },
        {
          "id": "video-as-requirements",
          "text": "Video-as-Requirements",
          "level": 2
        },
        {
          "id": "video-driven-intent-extraction",
          "text": "Video-driven intent extraction",
          "level": 2
        },
        {
          "id": "related-vocabulary",
          "text": "Related vocabulary",
          "level": 2
        }
      ],
      "markdown": "# Agent foundations glossary\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nVocabulary for describing agent work, with explanations and operational consequences.\n\n## AFK goal loops\n\nJohn gives an example goal where an agent creates a timestamp, checks other panes every 10 minutes to make sure they are completing their goals, picks the best answer if a pane is blocked by a question, and continues until four hours after the original timestamp. He describes this as an AFK approach where he can set it and walk away.\n\n**Why it matters:** Periodic check-ins can keep multiple running sessions moving, but John also says the upfront planning for parallel work is still something to be actively involved in.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Agent-first tooling\n\nJohn frames modern dev tools around whether they are open source and agent-first: tools with CLIs, APIs, or other surfaces agents can interact with and control. His point is that you no longer need to personally memorize every flag or shortcut when the agent can inspect the interface and use it.\n\n**Why it matters:** Agent-first tools let your instructions turn into real tool actions: opening panes, running commands, checking status, or operating a CLI. Tools without programmable surfaces put more mechanical work back on the human.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Agent-managed folders\n\nUse local folders like `.notes/` and `.goals/` inside each project as places where agents can write Markdown plans, notes, and goals. John describes these as agent-managed files and as a way to write plans into files you can resume from later.\n\n**Why it matters:** This keeps agent working context close to the codebase while clearly separating it from the source files you intend to commit.\n\n[Apply this concept](/topics/foundations-visible-agent-memory/)\n\n## Agent-readable code structure\n\nWhen asked about file and function line limits, John rejects arbitrary size rules. The guideline he gives is to prefer state machines, named switch cases, and English-labeled conditions over dense conditional structures.\n\n**Why it matters:** Agents can read, verify, and reason about code more reliably when the control flow exposes human-readable state names.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Background daemons\n\nThe “human” daemon runs behind the main session. At each hook, it updates an HTML page from the conversation so far, tracks tool calls, customizes the page for the current work, and gives John a summary when it is done. Right now that dashboard is ephemeral and written to a temp directory, but John says it could be persisted.\n\n**Why it matters:** A daemon is useful when a narrow support task should keep running without interrupting the main session.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## ChatGPT Pro Extended context window\n\nJohn says his $200-plan browser session exposes ChatGPT 5.5 Pro / Pro Extended with much longer context than before: he contrasts older ~50,000-token sessions with newer sessions that can take around a million tokens and often return in 10–15 minutes.\n\n**Why it matters:** The exact limits may change, but the taught idea is to notice that different surfaces have different context limits and to route work accordingly.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## CMUX as a primary orchestrator\n\nJohn demonstrates a main CMUX session opening specialized Codex panes for quality control, performance, research, and notes. The main pane becomes the coordinator, while each child pane has a narrow role and can work independently.\n\n**Why it matters:** This keeps context cleaner and makes delegation visible. It gives you a practical way to monitor several agent tracks without dumping every task into one large prompt thread.\n\n[Apply this concept](/topics/foundations-multimodal-design-and-model-routing/)\n\n## CMUX state for context-aware shortcuts\n\nJohn describes a CMUX inspect-style command that exposes the multiplexer state as an object, including the focused pane and that pane’s current working directory. He uses that context with a Karabiner shortcut to open tools over the terminal he is already focused on.\n\n**Why it matters:** It turns the terminal layout into an automation surface: a shortcut can open an editor, run Git commands, start debugging, or trigger other tools in the project you are currently looking at.\n\n[Apply this concept](/topics/foundations-perspective-qa-and-testing/)\n\n## Code as the Source of Truth\n\nProject memory can be useful, but it drifts as the code changes. John’s main point is that trying to update memory on every commit can turn into a parallel maintenance problem, so the safest default is to make the agent look at the current code when implementation details matter.\n\n**Why it matters:** It keeps agents from confidently acting on outdated assumptions and keeps the workflow tied to what actually exists in the repo.\n\n[Apply this concept](/topics/foundations-source-truth-and-design/)\n\n## Codex-to-browser quota offloading\n\nJohn explains that dense, high-context questions can be sent to ChatGPT Pro Extended in the browser instead of spending Codex's interactive token and rate-limit budget. He describes this as useful for complicated questions where you want a large amount of packed context.\n\n**Why it matters:** Large repo-reading prompts can burn through Codex limits quickly. Routing the heavyweight analysis to the browser keeps Codex available for the parts of the workflow that need an agent to continue acting.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## Compaction and conversation forking\n\nCompaction is the move of shrinking a long conversation down to the pieces that still matter. John framed it as useful when you fork a conversation and want the new branch to focus on one topic, like a specific test file, instead of carrying unrelated history forward. The practical benefits he called out were fewer tokens, faster runs, lower budget/quota pressure, and a clearer sense of what the agent is working on.\n\n**Why it matters:** Long conversations can carry a lot of irrelevant context. Forking plus focused compaction gives the next session a cleaner starting point.\n\n[Apply this concept](/topics/foundations-hooks-and-context-hygiene/)\n\n## Context pruning for low-latency daemons\n\nThe codex-daemons demo shows an advanced experiment in stripping agent startup context. John redirects the Codex home directory, symlinks the needed auth file, disables memories, MCP servers, web search, and Agents.md/project rules, and runs hyper-specific daemon commands on Codex Spark Low by default. He also shows SDK thread warm-up so the first prompt can skip several seconds of startup work.\n\n**Why it matters:** For repetitive, well-scoped CLI-style tasks, less context can mean faster responses, lower quota pressure, and fewer distractions.\n\n[Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Context triad: intent, implementation, output\n\nFor difficult debugging, John teaches bundling the expected behavior, the relevant code, and the observed runtime evidence. The evidence can include logs, console output, screenshots, traces, performance profiles, QA-script artifacts, and other files produced while the app is actually running.\n\n**Why it matters:** Models reason better when they can compare what should have happened, how the code attempted it, and what actually happened during execution.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## Cross-pane context reading\n\nJohn demonstrates that CMUX can read the contents of other tabs or panes by echoing text in one tab and asking another what that tab said. He explains that agents can check other panes, workspaces, recent commands, Git actions, and signs that something needs attention.\n\n**Why it matters:** This is what makes multiple panes more than just visual clutter. A main or sibling agent can inspect what is happening elsewhere and summarize it for you.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Custom grammar triggers\n\nA custom grammar trigger is a small token like #human, #toolsmith, #memory, or #search that a User Prompt hook can detect before the agent proceeds. John likes this because it keeps Codex vanilla by default and only loads the specific system, plugin, skill, or context bundle when he explicitly asks for it.\n\n**Why it matters:** This gives you a clean way to personalize sessions without polluting every conversation with skills or context the task does not need.\n\n[Apply this concept](/topics/foundations-hooks-and-context-hygiene/)\n\n## Design.md from Generated Inspiration\n\nJohn demonstrated starting design work from an inspiration board made of generated images, not scraped sites. He selected visual directions, copied them into an AI prompt, asked Codex to create a hoodie company landing page, and showed the generated design.md with references, style DNA, colors, typography, layout, composition, shape, and motion.\n\n**Why it matters:** It turns vague taste into a concrete design artifact that the agent can use to generate UI that follows a direction instead of producing a generic layout.\n\n[Apply this concept](/topics/foundations-source-truth-and-design/)\n\n## Diff-Driven Review\n\nJohn reduces an agent run to a simple equation: prompt plus agent, harness, and skills equals diff. The diff is the concrete artifact worth reviewing, testing against, and handing to a fresh session for critique.\n\n**Why it matters:** It gives you a clean review loop. A second agent can inspect the goal and diff without inheriting the first agent’s assumptions.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Discardable QA files\n\nA QA file is a temporary assignment document for an agent: a numbered list of things to try, paths to walk, buttons to find, and a perspective to act from. John treats these as created in the moment, not as permanent test infrastructure.\n\n**Why it matters:** They let you test the current shape of a fast-changing product without locking every changing UI decision into a brittle long-term test suite.\n\n[Apply this concept](/topics/foundations-perspective-qa-and-testing/)\n\n## Disposable Code, Durable Ideas\n\nJohn explicitly says not to get too attached to a specific workflow or generated code artifact. A plugin, hook, or implementation can be generated quickly and thrown away later.\n\n**Why it matters:** The idea, boundary, state machine, module structure, and product intent matter more than the exact code the current agent happened to write.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Global gitignore partitioning\n\nInstead of adding `.notes/` and `.goals/` to every repository's `.gitignore`, John suggests globally ignoring those directories on your machine. That lets the same local agent-memory folders exist across projects without being checked into repos.\n\n**Why it matters:** It creates a machine-level boundary between private local agent scratch work and shared source control.\n\n[Apply this concept](/topics/foundations-visible-agent-memory/)\n\n## Image generation as design reference\n\nFor UI work, John recommends generating sheets of visual variations before committing to a direction. For example, he describes taking a screenshot of a component and asking for many variations, then picking the favorite as the design direction.\n\n**Why it matters:** Images collapse ambiguity. They let non-designers express taste through selection, which is often easier than inventing exact CSS, spacing, motion, and layout language from scratch.\n\n[Apply this concept](/topics/foundations-multimodal-design-and-model-routing/)\n\n## Large-Context Snapshots as a Possible Escape Hatch\n\nJohn briefly floated million-token context windows as a possible way to take useful snapshots of codebases, but he explicitly framed it as something he had not really tried yet. In this lesson, it is a possible direction, not a proven replacement for memory.\n\n**Why it matters:** The useful idea is that current code text is more trustworthy than detached summaries, but this section does not teach a full large-context snapshot workflow.\n\n[Apply this concept](/topics/foundations-source-truth-and-design/)\n\n## Lightweight Markdown Memory\n\nJohn still sees value in basic memory when it stays simple: Markdown files, simple RAG, and human-readable notes. The danger starts when memory becomes a second system that has to be kept in sync with a fast-moving codebase.\n\n**Why it matters:** Good memory reduces repeated explanation; bad memory becomes stale documentation that misleads both humans and agents.\n\n[Apply this concept](/topics/foundations-source-truth-and-design/)\n\n## Live Markdown side panes\n\nA Markdown file can become a live visual progress view if the agent updates it while working and the client auto-refreshes the rendered pane. John demonstrates this with a simple `test.md` file in CMUX and describes using Markdown as a checklist, progress view, summary, or conversation-history display.\n\n**Why it matters:** It lets you step away from the noisy agent transcript and return to a cleaner status view of what changed or what is happening.\n\n[Apply this concept](/topics/foundations-visible-agent-memory/)\n\n## Living Guardrails\n\nFiles like agents.md or claude.md should stay fairly minimal and evolve with the project. John suggests reviewing recent commits, learning from mistakes, and iterating on the agent instructions over time.\n\n**Why it matters:** Mistakes become useful artifacts when they update the project’s guardrails. The file should capture real project knowledge, not a giant upfront rulebook.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Log-based deterministic gates\n\nJohn's default answer to verification is to write logs or other artifacts to files. Depending on the project, those artifacts might show that a file was created, an API call happened, an object had the expected shape, timestamps were recorded, or multiple sessions produced comparable outputs. A main agent can wait for worker sessions to finish, inspect the logs and text output, and compare them against the criteria.\n\n**Why it matters:** Agents are useful reviewers, but artifacts are the evidence. Logs make fix-verify loops inspectable instead of trust-based.\n\n[Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Low-reasoning iteration\n\nJohn says low reasoning is underutilized, but it needs a different style of prompting. You should expect it to fail while you dial it in, because it will not deeply think through ambiguous work on its own. It works better when the job is narrow and the prompt accounts for the specific tool, CLI, API, or failure modes involved.\n\n**Why it matters:** Small, focused low-reasoning runs can be useful for high-frequency automation when the prompt and tool scope are explicit.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Manager-worker topology\n\nJohn describes treating himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager, which can open panes and send workers to investigate, research, or do other tasks.\n\n**Why it matters:** A manager pane keeps the human interaction surface smaller while still letting several agents or terminal sessions do work in parallel.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## MCP versus CLI boundaries\n\nJohn warns that it can get weird to build a skill just to call an MCP wrapper when the skill could have called a CLI directly. His broader rule is to define boundaries around what needs tests, what needs flexibility, where memory belongs, and which agents should have access to which tools.\n\n**Why it matters:** Clear boundaries make agent systems easier to reason about. If a workflow is deterministic and testable, a direct CLI or script may be simpler than an unnecessary MCP layer; use agent reasoning where judgment, interpretation, or flexible planning actually adds value.\n\n[Apply this concept](/topics/foundations-multimodal-design-and-model-routing/)\n\n## MCP/browser automation bridge\n\nAfter the context is packed, the workflow makes an MCP call that reaches over to a browser on John's Mac mini, opens the ChatGPT session, inserts the prompt, and submits it.\n\n**Why it matters:** The MCP step is the bridge that lets the current agent trigger the outside browser workflow instead of requiring John to manually paste the packed prompt.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## Model choice by task shape\n\nJohn frames Codex as his default coding worker, especially when goal-following and token efficiency matter. Claude can be useful as a conversational manager or design helper, while Flash-style models are best for quick, tightly scoped tasks and weaker for long chains that require self-correction.\n\n**Why it matters:** Good model choice is a cost and reliability decision, not a brand preference. Matching the model to the task reduces wasted tokens and lowers the odds of an agent spiraling while trying to fix its own mistake.\n\n[Apply this concept](/topics/foundations-multimodal-design-and-model-routing/)\n\n## Multimodal verification loops\n\nJohn explains a comic-generation workflow where Codex generates an image, then reads the generated image back in and compares it to previous images. The verification pass can check continuity details such as whether a character has legs or whether counts match across frames. He also discusses asking UI work to return mathematical payloads for padding, margins, spacing, and layout.\n\n**Why it matters:** Generated artifacts should be inspected against concrete constraints instead of trusted after one prompt.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Natural language terminal orchestration\n\nJohn demonstrates asking CMUX to open a new pane to the right, then asking it to open five more panes, run different safe commands in them, and space everything evenly. The agent uses the CMUX CLI surface to translate natural language into layout and terminal actions.\n\n**Why it matters:** This makes the terminal workspace programmable. You can describe the workspace you need instead of manually arranging panes and remembering multiplexer commands.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Natural-language contract boundaries\n\nJohn frames modules, tools, and CLIs as boundaries that agents can own. A master orchestrator can hold broader project context and spin up focused agents, while each worker gets a narrow task, limited tools, and a clear English instruction payload. He compares this to API contracts, except the handoff can be natural language sent to an agent.\n\n**Why it matters:** Narrow agents are faster, easier to inspect, cheaper to run, and less likely to get distracted by unrelated context.\n\n[Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Natural-Language Contracts\n\nA natural-language contract is a plain-English description of what a tool, app, or agent is supposed to do. John frames this as an \"agent first\" mindset: define the work in language so the underlying tool can change without destroying the workflow.\n\n**Why it matters:** It keeps you from overfitting to today’s specific tool, harness, plugin, or workflow. The portable asset is the intent.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Natural-language loose coupling\n\nFor team workflows and tools, John recommends staying flexible: capture meetings and workflow complaints, iterate on how the team works, and prefer open-source, agent-first tools whose main contract is natural language. He uses the ability to abandon a tool easily as the point.\n\n**Why it matters:** Tools are changing quickly, so teams should avoid investing too heavily in brittle workflows tied to one vendor or interface.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## Numbered option planning\n\nAsk the agent for a numbered list where each item has options such as A, B, and C, and have the agent explain which option it thinks is best. You can then review the document and respond with precise targets like `5B` or `27D`.\n\n**Why it matters:** It turns a large plan into an editable map, so you can steer the agent precisely without rewriting or quoting long sections.\n\n[Apply this concept](/topics/foundations-visible-agent-memory/)\n\n## Oracle browser handoff\n\nOracle lets a current Codex session ask a browser session to do the heavy analysis: it packs things up, sends them to the browser, waits for the browser model to work, and then brings the result back into the coding session.\n\n**Why it matters:** This creates a handoff between a local agent workflow and a logged-in browser model without manually copying a massive prompt every time.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## Overnight emulated crons\n\nBecause Codex does not have a built-in cron in this workflow, John describes writing a goal that creates a timestamp, repeats a task every 10 minutes, and continues until a fixed duration or target time such as 9 AM.\n\n**Why it matters:** This gives Codex a bounded long-running loop without pretending it is a real scheduler.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## PackX context bundling\n\nIn the demo, John's Oracle PackX skill uses a pack tool to gather files related to a query. The run shown packs 45 files and reports roughly 585,000 tokens before sending the bundle to Oracle.\n\n**Why it matters:** PackX is the part of the workflow that turns scattered repo files into one large model-readable payload for the browser analysis pass.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## PackX for file collation\n\nJohn shows PackX, a tool he built to collate a bunch of files into a single file. He explains that it supports file globs, patterns, and options, and that he typically lets the agent learn and use the CLI flags instead of using the tool manually.\n\n**Why it matters:** It is an example of agent-first thinking: give the agent a useful CLI tool and let it handle the exact flags and patterns needed for the current context.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Perspective-based prompting\n\nInstead of asking one generic agent to research or test your app, assign it a lens: expert, new user, grandma, power user, or another real audience. That lens changes what the agent notices and which assumptions it challenges.\n\n**Why it matters:** It helps you escape creator bias and shape the output around the actual demographics or user types your application needs to support.\n\n[Apply this concept](/topics/foundations-perspective-qa-and-testing/)\n\n## Plan-first goal grounding\n\nJohn says he often has the agent create a full plan document first, then reads it and dictates or types feedback about specific sections. He may use GrillMe only when he is still uncertain after seeing the plan.\n\n**Why it matters:** Reacting to a concrete plan can be faster than answering a long sequence of upfront questions.\n\n[Apply this concept](/topics/foundations-visible-agent-memory/)\n\n## Plan, implement, verify loop\n\nJohn shows the broader pattern he uses: create a list of QA stories or goals, use Oracle to create a plan for each one, then implement it and verify it.\n\n**Why it matters:** The value is not just a one-off giant prompt; it is turning high-context planning into a repeatable loop that feeds back into actual code work.\n\n[Apply this concept](/topics/foundations-oracle-context-routing/)\n\n## QA artifacts as live application evidence\n\nJohn describes logs as a representation of the live app running and recommends shaping QA scripts and project-specific dev tools so they deliberately write useful artifacts. Those artifacts can then be bundled with code using PackX or another bundler for analysis by a stronger model.\n\n**Why it matters:** A model that sees real artifacts from a user flow can diagnose behavior instead of guessing from source files alone.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## SDK agent graphs\n\nJohn says the SDK is the right tool when you need custom agents with managed threads, managed settings, warm background behavior, and structured workflows. He describes workflows where one agent hands work to another, branches into parallel research agents, then uses an analysis step to choose or synthesize the best plans before implementation.\n\n**Why it matters:** The SDK is useful when the workflow has explicit roles, sequencing, branching, fan-out, or fan-in that should be locked into code instead of improvised in one chat.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Self-improvement error loops\n\nWhen a plugin or hook fails, John copies the failed session text and asks the agent to explain why the plugin failed in that scenario and how to account for it next time. The point is not just to fix one run, but to use the exact fail case to harden the tool or workflow.\n\n**Why it matters:** Tooling compounds when each failure leaves behind a stronger hook, workflow, or guardrail.\n\n[Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Self-improving daemons\n\nJohn shows the self-improve idea: when each turn ends, the daemon reads the transcript, looks for ways it can improve, finds its own file, and updates its own prompts or source. He says this is much more plausible for specific CLIs, tools, or APIs with clear tasks and predictable failure modes than for large projects that can branch in many directions.\n\n**Why it matters:** For narrow tools, repeated failures can become better operating instructions for future runs.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Short /goal files and Oracle-generated plans\n\nJohn shows that many of his goal prompts are plain and short, such as asking for a specific layout fix. For complex work, he often asks Oracle to research the problem and generate a more detailed goal file, then drops that file into his `.goals` directory for Codex to run through research, implementation, and verification.\n\n**Why it matters:** Simple tasks do not need massive prompts, while complex tasks benefit from a stronger planning pass before Codex executes the work.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## Skills versus plugins\n\nJohn contrasts skills with plugins as a difference between context-based guidance and deterministic control. Skills put descriptions into the model's context so the agent can infer when and how to use them. Plugins can hook into events and enforce behavior, including starting or stopping things, allowing or disallowing actions, or calling specific tools.\n\n**Why it matters:** For workflows you want to enforce, John recommends reaching for a plugin with hooks instead of trying to make skill instructions clearer and clearer.\n\n[Apply this concept](/topics/foundations-hooks-and-context-hygiene/)\n\n## Small context and specialized tool context\n\nJohn repeatedly frames these daemon runs as small compared with normal Codex/GPT sessions, mentioning a target of staying under about 10,000 tokens of context. He also uses the Vercel plugin story to show that giving a weaker model the right tools and focused context can outperform a stronger model without that context.\n\n**Why it matters:** Narrow context lowers usage and keeps the model focused on the job it was built to do.\n\n[Apply this concept](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Specialized agents and Codex daemons\n\nJohn connects Planner, Builder, Researcher, and Validator-style responsibilities to specialized agents. His Codex daemon point in this section is high level: create custom, reusable agents for a specific project need, give them the relevant requirements, and reuse them instead of making one agent handle everything.\n\n**Why it matters:** Custom systems that understand your project can support workflows that generic shared skills may not cover.\n\n[Apply this concept](/topics/foundations-context-triad-and-overnight-work/)\n\n## State Machines and Modular Boundaries\n\nWhen a codebase can grow by tens of thousands of lines overnight, John says the safety comes from structure: isolated modules and business logic that is navigable through state machines.\n\n**Why it matters:** These boundaries let humans and agents digest, regenerate, refactor, or replace implementation details without losing the shape of the product.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Terminal text extraction as context\n\nJohn shows a CMUX shortcut, Cmd-Opt-Shift-J in his setup, that takes the current terminal session and opens it as plain selectable text in an editor-like pane. Instead of fighting terminal scrollback, colors, and selection behavior, he copies the exact failure state and uses it as agent context.\n\n**Why it matters:** The fastest debugging loop starts with the real failure, not a vague summary of what you think happened.\n\n[Apply this concept](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## The 5 Monkeys technique\n\nThe goal is to have agents use the app in non-obvious ways: find buttons, click around, try shortcuts, press back after reaching a page, and look for modes or state that stay open unexpectedly.\n\n**Why it matters:** This catches UX and state issues that a normal verification prompt may miss because the model tends to follow the same visible patterns the developer already expects.\n\n[Apply this concept](/topics/foundations-perspective-qa-and-testing/)\n\n## The big three hooks\n\nJohn breaks the agent loop into three core events: User Prompt, Tool Use, and Stop. User Prompt fires when you type something and submit it, Tool Use fires when a tool runs, and Stop fires when the conversation would normally end and wait for you. These are the main places where a hook can do something with the session.\n\n**Why it matters:** Once you understand these three events, plugins stop feeling mysterious. They become small programs attached to predictable moments in the agent lifecycle.\n\n[Apply this concept](/topics/foundations-hooks-and-context-hygiene/)\n\n## The Ralph Loop\n\nThe Ralph Loop is John's shorthand for a Stop-hook-driven loop. When the agent tries to stop, the hook can tell the harness not to stop yet, look back at what the user originally asked for, and keep working until a condition is met. John described this as the basic idea behind goal-style sessions.\n\n**Why it matters:** This matters when you want an agent to keep working on a goal instead of handing control back after one assistant turn.\n\n[Apply this concept](/topics/foundations-hooks-and-context-hygiene/)\n\n## Throwaway Route Variants\n\nInstead of building a heavy Storybook setup for every experiment, John often asks agents to generate multiple temporary routes or page copies using the same components with different styles. He compares them in the app with simple navigation, picks the best direction, and deletes the rest.\n\n**Why it matters:** It supports fast visual exploration without creating another maintenance surface that has to be kept up to date.\n\n[Apply this concept](/topics/foundations-source-truth-and-design/)\n\n## Unread notification jumping\n\nJohn shows that CMUX can surface notifications from sessions and that Cmd+Shift+U jumps to unread activity. He uses it to jump to a pane where a session had stopped.\n\n**Why it matters:** When many sessions are running, jumping to the pane that needs attention is faster than manually scanning every pane.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Vault and resumed conversations\n\nJohn demonstrates the CMUX right sidebar with Files, Find, and Vault. In the Vault, he can look through past conversations and resume one in a new tab, though he notes the feature is still in development and search is not great yet.\n\n**Why it matters:** Resuming old context is useful when you lose or want to continue a previous conversation without manually reconstructing what happened.\n\n[Apply this concept](/topics/foundations-manager-worker-orchestration/)\n\n## Video prompting for high-context intent\n\nJohn describes uploading video to Gemini by hand and also using scripts that upload to Google's backend to extract code snippets, key parts, timestamps, and screenshots. Video can preserve the flow of a demo or code walkthrough better than a written description because the model sees the sequence of states.\n\n**Why it matters:** When the task depends on timing, UI state, or code changing over time, video can carry intent that text misses. The practical caveat he names is that scripted backend use can involve cost and auth-token setup.\n\n[Apply this concept](/topics/foundations-multimodal-design-and-model-routing/)\n\n## Video-as-Requirements\n\nJohn recommends recording yourself or users actually using the app while speaking intent out loud. The recording captures clicks, typing, layout changes, responsive behavior, and what the person wanted from the app.\n\n**Why it matters:** It captures human interaction that is hard to fully express in written specs. A video-capable model can help turn that usage into requirements, goals, and QA stories.\n\n[Apply this concept](/topics/foundations-contracts-state-machines-and-code/)\n\n## Video-driven intent extraction\n\nJohn records a rough screen interaction, narrates UI changes aloud, and drops the video into Gemini to turn it into AI instructions for implementation.\n\n**Why it matters:** It lowers the cost of explaining visual changes when pointing, circling, and talking are faster than writing a polished written spec.\n\n[Apply this concept](/topics/foundations-perspective-qa-and-testing/)\n\n## Related vocabulary\n\n- **Workflow Optimization** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/).\n- **Resource Management** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/).\n- **Architecture** — [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/).\n- **Agent-First Software Design** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/).\n- **The Manager-Worker Topology** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/).\n- **Natural Language Layout Control** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/).\n- **Cross-Pane Terminal Context Reading** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/).\n- **AFK Automation Loops** — [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/).\n- **Agent-Managed Folders** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Global Gitignore Partitioning** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Targeted Matrix Refinement** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Token Optimization** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Agent First Extensibility Paradigm** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Live Check-Back Tracking Files** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Native Harness Memory Systems** — [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/).\n- **Basic Memory vs. Stale Memory** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/).\n- **Source-of-Truth Code** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/).\n- **Million-Token Snapshot Contexts** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/).\n- **YOLO Bypassing (Sandbox Approvals)** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/). Contextual term only: approval bypassing is not a requirement or recommendation for the design/variant workflows.\n- **Design.md File Standard** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/).\n- **Multi-Route Structural Variants** — [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/).\n- **Perspective-Based Prompting** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **Discardable QA Files** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **The 5 Monkeys Technique** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **Contextual Multiplexer Inspection via JSON** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **Video-Driven Intent Extraction** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **Single-Threaded Main Prototyping** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **System-Monitoring Safeguards** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **Agent-Assisted Profiling** — [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/).\n- **CMUX Primary Orchestrator Pattern** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Token Efficiency** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Flash Models** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Image Generation as Design Reference** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Video Prompting** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Physical Pomodoro Anchor** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Image-to-Design Hand-off** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **MCP vs. CLI Boundary Dilemma** — [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/).\n- **Compaction** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Conversation Forking** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **User Prompt Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Tool Use Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Stop Hook** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Ralph Loop** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Skills vs Plugins** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **Custom Grammar Interceptors** — [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/).\n- **CMUX Text Mode Pane Extraction** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Self-Improvement Error Loop** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Log-Based Deterministic Gates** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Natural Language Contract Boundaries** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Context Pruning** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Thread Warm-Up Low-Latency Pattern** — [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/).\n- **Background Daemons** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Self-Aware Code Scripts** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Low Reasoning Iteration** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Context Ceiling Strategy** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Multi-Agent Swarms** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Bespoke Platform Constraints** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Multimodal Quality Assurance Loop** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Semantic Syntax Engineering** — [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/).\n- **Context Triad** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/).\n- **Agent Archetypes** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/).\n- **Codex Demons** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/).\n- **Overnight Emulated Crons** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/).\n- **Natural Language Loose Coupling** — [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/).\n- **Natural-Language Contracts** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/).\n- **Video-as-Requirements** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/).\n- **Code as a Throwaway Artifact** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/).\n- **Complexity Management Strategy (State Machine + Module)** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/).\n- **Living Guardrails (agents.md)** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/).\n- **The Bifurcated Engineer** — [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)."
    },
    {
      "id": "foundations-agent-memory-playbook",
      "slug": "agent-memory-playbook",
      "title": "Agent-managed memory folders playbook",
      "summary": "Web developers already run local dev servers, browser checks, and coding agents against real repos. Agent-managed memory folders give those agents a visible place to plan, track, and resume work without polluting source control or turning scratch notes into stale project documentation.",
      "category": "Context",
      "tags": [
        "memory",
        "goals",
        "CMUX",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#agent-memory",
        "scenarios/agent-memory.json#audienceFit",
        "toolkit/prompts/03-agent-memory-folders-setup.md",
        "toolkit/codex-skills/agent-memory-folders/SKILL.md",
        "scenarios/agent-memory.json#scenarios/0",
        "scenarios/agent-memory.json#scenarios/1",
        "scenarios/agent-memory.json#scenarios/2",
        "scenarios/agent-memory.json#implementationNotes",
        "scenarios/agent-memory.json#notTaughtOrAvoid/1",
        "scenarios/agent-memory.json#notTaughtOrAvoid/2",
        "scenarios/agent-memory.json#notTaughtOrAvoid/3",
        "scenarios/agent-memory.json#notTaughtOrAvoid/4",
        "scenarios/agent-memory.json#notTaughtOrAvoid/5",
        "scenarios/agent-memory.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 2312,
      "url": "/topics/foundations-agent-memory-playbook/",
      "markdownUrl": "/markdown/foundations-agent-memory-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-agent-memory-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "plan-and-track-a-risky-checkout-flow-fix",
          "text": "Plan and track a risky checkout-flow fix",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "resume-a-paused-redesign-without-stale-memory",
          "text": "Resume a paused redesign without stale memory",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "keep-agent-planning-out-of-a-shared-library-repo",
          "text": "Keep agent planning out of a shared library repo",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "validated-lesson-03-references",
          "text": "Validated lesson 03 references",
          "level": 3
        },
        {
          "id": "existing-setup-prompt",
          "text": "Existing setup prompt",
          "level": 3
        },
        {
          "id": "existing-codex-skill",
          "text": "Existing Codex skill",
          "level": 3
        },
        {
          "id": "cmux-live-markdown-command",
          "text": "CMUX live Markdown command",
          "level": 3
        },
        {
          "id": "global-gitignore-setup",
          "text": "Global gitignore setup",
          "level": 3
        },
        {
          "id": "verify-ignored-scratch-folders",
          "text": "Verify ignored scratch folders",
          "level": 3
        }
      ],
      "markdown": "# Agent-managed memory folders playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already run local dev servers, browser checks, and coding agents against real repos. Agent-managed memory folders give those agents a visible place to plan, track, and resume work without polluting source control or turning scratch notes into stale project documentation.\n\n[Core principles](/topics/foundations-visible-agent-memory/)\n\n## Copy-paste workflow\n\n**When to use:** At the start of any project where you want agents to keep visible Markdown plans, notes, and goals close to the code without committing them. This creates `.notes/` and `.goals/`, ignores them globally, and opens a live-refreshing Markdown tracker pane.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. Set up local agent-managed memory the workshop way, then use it. These are LOCAL working files, not source — keep them boring and close to the repo, and never commit them.\n\n1. Create the memory folders:\n     mkdir -p .notes .goals\n\n2. Ignore them across ALL my repos via a global gitignore:\n     git config --global core.excludesFile ~/.gitignore_global\n     echo '.notes/' >> ~/.gitignore_global\n     echo '.goals/' >> ~/.gitignore_global\n\n3. Write the current plan into .goals/ as Markdown, then open a live-refreshing tracker pane next to the code:\n     cmux markdown open .notes/tracker.md --direction right\n\n4. When you plan, use the numbered-option pattern so I can steer with terse refs: give me a NUMBERED list where each item has options A/B/C and YOUR recommended pick. I will reply with refs like \"5B\" or \"27D\" to choose.\n```\n\n### How it works\n- `mkdir -p .notes .goals` creates the two local memory folders.\n- `git config --global core.excludesFile ~/.gitignore_global` then appending `.notes/` and `.goals/` keeps them out of every repo by default — they are working files, not source.\n- `cmux markdown open .notes/tracker.md --direction right` opens the Markdown in a formatted viewer with live file watching (auto-refresh) as a side tracker pane.\n- The numbered-option planning pattern (each item has A/B/C plus the agent's recommended pick) lets you steer with terse references like `5B`.\n- Reference: [Git global gitignore (`core.excludesFile`)](https://git-scm.com/docs/gitignore), [CMUX](https://cmux.com/).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/agent-memory-folders/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: agent-memory-folders\ndescription: Trigger at project start (or when an agent needs visible local working memory) to create .notes/ and .goals/, ignore them via global gitignore, and open a live Markdown tracker. Do NOT use for files meant to be committed.\n---\n\n# Agent memory folders\n\nProvision local agent-managed memory: `.notes/` for working notes and `.goals/` for plans, ignored globally so they never get committed, plus a live Markdown tracker pane. These are LOCAL working files — keep them boring and close to the repo.\n\n## Steps\n\n1. Create the folders:\n   ```bash\n   mkdir -p .notes .goals\n   ```\n\n2. Ignore them across ALL repos via a global gitignore:\n   ```bash\n   git config --global core.excludesFile ~/.gitignore_global\n   echo '.notes/' >> ~/.gitignore_global\n   echo '.goals/' >> ~/.gitignore_global\n   ```\n\n3. Write the current plan into `.goals/` as Markdown, then open a live-refreshing tracker pane (auto-refresh via file watching) next to the code:\n   ```bash\n   cmux markdown open .notes/tracker.md --direction right\n   ```\n\n4. Use the numbered-option planning pattern: present a NUMBERED list where each item has options A/B/C plus your recommended pick, so the human steers with terse refs like `5B` or `27D`.\n\n## Guardrails\n- These are local working files, NOT source — never commit them.\n- Keep them boring and close to the repo.\n````\n\n## Scenarios\n\n### Plan and track a risky checkout-flow fix\n\n**Role:** As a senior frontend engineer responsible for a Next.js checkout flow\n\nA production-like checkout bug only appears after several UI states: shipping form edits, coupon entry, back navigation, and payment-step refresh. The developer wants Codex to plan before touching code, keep progress visible, and leave no agent scratch files in Git.\n\n> As a senior frontend engineer, I want the agent to create local memory folders, write a numbered implementation plan, and maintain a live tracker while fixing the checkout flow, so that I can steer the work precisely and review progress without rereading the whole agent transcript.\n\n#### Agent brief\n\n```text\nSet up local agent-managed memory for this repo, then use it for the checkout fix. Run: `mkdir -p .notes .goals`. Configure global ignores without editing this repo's shared `.gitignore`: `git config --global core.excludesFile ~/.gitignore_global`; then ensure `.notes/` and `.goals/` are present in `~/.gitignore_global` without duplicating lines. Inspect the current checkout code before planning; do not trust old notes as source of truth. Write `.goals/checkout-flow-plan.md` as a numbered plan where each major item has options A/B/C and your recommended pick. Open a live tracker with `cmux markdown open .notes/tracker.md --direction right`. Keep `.notes/tracker.md` updated with current step, files inspected, commands run, browser proof status, and remaining risks. After I choose plan refs like `2B` or `5C`, implement only the approved path. Expected output: changed source files only where needed, `.goals/checkout-flow-plan.md`, `.notes/tracker.md`, and a final summary that separates committed-source changes from local scratch artifacts.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-visible-agent-memory/)\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n```text\nmkdir -p .notes .goals\n```\n\n```text\ngit config --global core.excludesFile ~/.gitignore_global\n```\n\n```text\ncmux markdown open .notes/tracker.md --direction right\n```\n\n```text\ncmux --json tree\n```\n\n#### Browser verification\n\nUse the running local app, preferably in a CMUX browser pane or browser-agent workflow. Start at the checkout page, take an accessibility snapshot, fill the shipping fields, apply a coupon, navigate back and forward, refresh on the payment step, and capture console output plus a screenshot or short written browser receipt. If using agent-browser-style tooling, use snapshot/click/fill/evaluate steps and write the result into `.notes/tracker.md`.\n\n#### Definition of done\n\n- `.notes/` and `.goals/` exist locally and are globally ignored, not added to the repo's shared `.gitignore`.\n- `.goals/checkout-flow-plan.md` contains numbered items with A/B/C options and clear recommended picks.\n- `.notes/tracker.md` is usable as a live progress receipt and lists the exact files touched, commands run, and browser verification performed.\n- The checkout flow is verified in the browser with the failing sequence, and the final source diff excludes `.notes/` and `.goals/`.\n\n#### Failure modes and mitigations\n\n- The agent commits `.notes/` or `.goals/`; mitigate by checking `git status --ignored` and confirming those folders are ignored globally before implementation.\n- The agent writes a vague prose plan that is hard to steer; mitigate by requiring numbered items with lettered options and waiting for human refs like `3B` before coding.\n\n### Resume a paused redesign without stale memory\n\n**Role:** As a product-minded full-stack developer iterating on a dashboard UI\n\nA dashboard redesign was started yesterday, but the app has changed since then. The developer wants to resume from local agent notes while forcing the agent to re-check current code and verify the UI in the browser.\n\n> As a full-stack developer, I want the agent to read prior local goals but treat the current code and running browser as truth, so that yesterday's plan helps me resume without misleading today's implementation.\n\n#### Agent brief\n\n```text\nUse the agent-memory-folder pattern to resume work safely. First inspect `.goals/` and `.notes/` if they exist, but treat them as local scratch context only. Then inspect the current dashboard files and summarize where the existing notes agree or disagree with the current code. If folders do not exist, create them with `mkdir -p .notes .goals` and ensure `.notes/` and `.goals/` are in the global gitignore via `git config --global core.excludesFile ~/.gitignore_global`. Write `.goals/dashboard-resume-plan.md` with numbered implementation items and A/B/C options. Mark any stale assumptions explicitly. Open or update the live tracker using `cmux markdown open .notes/tracker.md --direction right`. Implement only the approved plan choices. Expected output: a resume plan, a stale-assumption section, a live tracker update, a source diff, and browser evidence from the running dashboard.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-visible-agent-memory/)\n\n[Open reference](/topics/foundations-visible-agent-memory/)\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n```text\ncmux markdown open .notes/tracker.md --direction right\n```\n\n```text\ncmux list-panes\n```\n\n```text\ncmux read-screen\n```\n\n#### Browser verification\n\nOpen the dashboard in a local browser or CMUX browser pane, compare the current rendered UI against the resumed plan, and record proof in `.notes/tracker.md`: current route, visible dashboard sections, any console errors, and a screenshot or browser-agent accessibility snapshot. Use click/fill/evaluate where the redesign affects interactive filters, tabs, or responsive state.\n\n#### Definition of done\n\n- The agent explicitly distinguishes prior local notes from current source-of-truth code.\n- `.goals/dashboard-resume-plan.md` includes a `Stale or revalidated assumptions` section.\n- The live tracker shows what was resumed, what was discarded, and what was implemented.\n- Browser verification proves the dashboard still renders and the changed interaction works after the source diff.\n\n#### Failure modes and mitigations\n\n- The agent blindly follows yesterday's `.goals/` file; mitigate by requiring a current-code inspection and an agreement/disagreement summary before edits.\n- The live tracker becomes a dumping ground; mitigate by keeping it short: current step, evidence, next action, blockers, and files touched.\n\n### Keep agent planning out of a shared library repo\n\n**Role:** As a maintainer of a shared component library used across several web apps\n\nMultiple agents are about to investigate a flaky component test and accessibility regression. The maintainer wants reusable local planning files, but the repo is shared by a team and must not gain private scratch folders or noisy `.gitignore` changes.\n\n> As a component-library maintainer, I want each agent to write plans and findings into globally ignored local folders, so that exploratory work stays close to the repo but never leaks into the package or team Git history.\n\n#### Agent brief\n\n```text\nPrepare this shared repo for local-only agent planning. Create `.notes/` and `.goals/` with `mkdir -p .notes .goals`. Use the global ignore boundary: `git config --global core.excludesFile ~/.gitignore_global`; ensure `.notes/` and `.goals/` are present there exactly once. Do not edit the repo `.gitignore` unless I explicitly ask. Write `.goals/component-a11y-investigation.md` as a numbered plan with A/B/C options and recommended picks. Use `.notes/tracker.md` to record each agent's assigned area, commands run, and findings. If CMUX is available, open the tracker with `cmux markdown open .notes/tracker.md --direction right`; otherwise leave the Markdown file ready for any preview pane. Expected output: local planning artifacts, no committed scratch files, a concise investigation plan, and a review summary I can use to decide which findings become real tests or source changes.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-visible-agent-memory/)\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n```text\ngit status --ignored\n```\n\n```text\ngit config --global core.excludesFile ~/.gitignore_global\n```\n\n```text\ncmux markdown open .notes/tracker.md --direction right\n```\n\n#### Browser verification\n\nBrowser proof is useful only if the component library has a local preview, demo route, or app fixture. If available, run the local preview, inspect the component in a browser, capture an accessibility snapshot or screenshot, and record the result in `.notes/tracker.md`. If there is no browser fixture, use test output and the rendered component documentation as proof instead of inventing a browser check.\n\n#### Definition of done\n\n- Global Git ignore contains `.notes/` and `.goals/`, and `git status --ignored` confirms the folders are local-only.\n- The shared repo `.gitignore` is unchanged unless explicitly approved.\n- `.goals/component-a11y-investigation.md` gives steerable numbered options rather than a single vague recommendation.\n- `.notes/tracker.md` contains a clean investigation receipt that can be reviewed without committing the scratch files.\n\n#### Failure modes and mitigations\n\n- The agent treats local memory as team documentation; mitigate by labeling every file in `.notes/` and `.goals/` as local working memory and excluding it from source diffs.\n- The agent over-invests in permanent tests for unstable UI exploration; mitigate by using the notes to triage first, then promote only stable, valuable checks into real tests.\n\n## Implementation notes\n\n- Keep `.notes/` and `.goals/` boring, local, and close to the repo. They are working files for agents, not production docs.\n- Have the agent inspect current code before implementation. Memory folders help with continuity, but code remains the source of truth when details matter.\n- Use numbered items with lettered options for plans that need human steering. A reply like `5B` is faster and less error-prone than quoting a paragraph back to the agent.\n- Use the live Markdown tracker as a status view, not a transcript clone. The useful shape is current task, evidence, commands, files touched, blockers, and next step.\n- For web app work, pair the tracker with browser evidence: a screenshot, accessibility snapshot, console result, Playwright result, or concise manual browser receipt.\n- Before finalizing, require a source diff review that excludes `.notes/` and `.goals/`.\n\n## Boundaries and caveats\n\n- Do not reintroduce Beads or other third-party memory systems as a taught workflow for this topic.\n- Do not treat GrillMe as the main workflow here; it was mentioned as occasional follow-up after seeing a drafted plan.\n- Do not build a complex memory database, RAG system, or automatic commit-synchronized memory layer for this workflow.\n- Do not add repo-local `.gitignore` changes unless the human explicitly wants that; the taught boundary is global gitignore partitioning.\n- Do not over-specify browser automation APIs that were not taught. Use practical browser proof shapes: CMUX browser pane, browser-agent snapshot/click/fill/evaluate, Playwright, or a local browser receipt.\n\n## Agent reference map\n\n### Validated lesson 03 references\n\nUse this as the ground truth for what was taught: local `.notes/` and `.goals/`, global gitignore partitioning, plan-first grounding, numbered option planning, and live Markdown side panes.\n\n[Open reference](/topics/foundations-visible-agent-memory/)\n\n### Existing setup prompt\n\nUse this when generating copy-paste setup instructions for a coding agent.\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n### Existing Codex skill\n\nUse this when implementing or checking the repo-local skill for agent-memory folders.\n\n[Open reference](/topics/foundations-agent-memory-playbook/)\n\n### CMUX live Markdown command\n\nUse this to open the live-refreshing tracker pane beside the agent session.\n\n```text\ncmux markdown open .notes/tracker.md --direction right\n```\n\n### Global gitignore setup\n\nUse this to keep local agent scratch folders out of every repo without modifying shared `.gitignore` files.\n\n```text\ngit config --global core.excludesFile ~/.gitignore_global\n```\n\n### Verify ignored scratch folders\n\nUse this before final review to prove `.notes/` and `.goals/` are not part of the source diff.\n\n```text\ngit status --ignored\n```"
    },
    {
      "id": "factory-prompt-builder",
      "slug": "prompt-builder",
      "title": "Compose the prompt before choosing the agent",
      "summary": "A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.",
      "category": "Context",
      "tags": [
        "prompt",
        "factory"
      ],
      "sources": [
        {
          "label": "Compose the prompt before choosing the agent",
          "url": "https://shiny-bloom-f8hv.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer"
        }
      ],
      "sourceUnits": [
        "04-prompt-builder/index.html#TL;DR",
        "04-prompt-builder/index.html#One composer in front of every agent",
        "04-prompt-builder/index.html#Appendix",
        "04-prompt-builder/index.html#Every launch is inspectable before it runs",
        "04-prompt-builder/index.html#Handoff mode turns shell functions into launch targets",
        "04-prompt-builder/index.html#A wrapper is a file format waiting to happen",
        "learn.html#q2-prompt-composer"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1704,
      "url": "/topics/factory-prompt-builder/",
      "markdownUrl": "/markdown/factory-prompt-builder.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-prompt-builder.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "one-composer-in-front-of-every-agent",
          "text": "One composer in front of every agent",
          "level": 2
        },
        {
          "id": "every-launch-is-inspectable-before-it-runs",
          "text": "Every launch is inspectable before it runs",
          "level": 2
        },
        {
          "id": "handoff-mode-turns-shell-functions-into-launch-targets",
          "text": "Handoff mode turns shell functions into launch targets",
          "level": 2
        },
        {
          "id": "a-wrapper-is-a-file-format-waiting-to-happen",
          "text": "A wrapper is a file format waiting to happen",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "compose-only-the-evidence-the-task-needs",
          "text": "Compose only the evidence the task needs",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Compose the prompt before choosing the agent\n\nA cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.\n\n## Related working material\n\n- [Compose the prompt before choosing the agent — prompts and exercises](/topics/factory-prompt-builder-practice/)\n- [Compose the prompt before choosing the agent — questions and tradeoffs](/topics/factory-prompt-builder-questions/)\n- [Compose the prompt before choosing the agent — worked example](/topics/factory-prompt-builder-worked-example/)\n\n## TL;DR\n\n- `prompt-builder` (alias `p`) is a terminal composer that gives your prompt its own tool: `$` skill lookup, `@` file search, and `Ctrl+R` cross-agent history in front of Pi, Codex, and Claude Code.\n- You walk away with a compose-first loop: one composer, your own launch targets, and shell functions promoted to launch targets via handoff mode.\n- The one move: compose in `p`, Tab to `Target ‹name›`, cycle agents with Space — and inspect any launch first with `--dry-run --print-command`.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://shiny-bloom-f8hv.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## One composer in front of every agent\n\nCount where your prompts get written: for most agent-CLI users, all of them live inside one agent's interactive loop. The prompt — the thing that carries your intent — has no home of its own; switch agents and you abandon your history, paste handling, and muscle memory.\n\nprompt-builder is a small Ratatui composer whose only job is composing: skill lookup, file search, slash commands, paste handling, and history that follows *you*, not the agent — it reads Codex's own `~/.codex/history.jsonl` alongside its private file, so prompts from either tool come back with `Ctrl+R`. The agent is just a selector at the bottom of the screen. Targets are named launch profiles — binary, env vars, model, default args — stored in `~/.prompt-builder/targets.toml`; a different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity.\n\n``` text\n$ prompt-builder target list\npi              pi      bin=pi\ncodex           codex   bin=codex\nclaude          claude  bin=claude\nwork-profile    codex   bin=codex   CODEX_HOME=~/.codex-work\nsecond-account  claude  bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second\n```\n\nThe test for whether this matters: the next time you re-type a prompt into a second agent because the first one stalled, you've found the cost this tool removes.\n\n## Every launch is inspectable before it runs\n\nA tool that launches agents for you earns trust only if you can see exactly what it would run. Every launch path has a dry-run twin: `--print-command` shows the exact argv; `--print-launch-json` emits a stable `schema_version: 1` manifest for scripts.\n\n``` text\n$ prompt-builder --dry-run --print-command \"hello\"\npi hello\n\n$ prompt-builder --dry-run --print-launch-json \"hello\"\n{\n  \"schema_version\": 1,\n  \"mode\": \"pi\",\n  \"command\": \"pi\",\n  \"argv\": [\"pi\", \"hello\"],\n  \"env\": {},\n  \"prompt\": \"hello\",\n  \"pi\": {\"cwd\": \".\", \"session_name\": null}\n}\n```\n\nCodex and Claude targets launch with permission-bypass flags — only point them at directories where you accept the agent modifying files and running commands (details in the appendix). Before trusting any target you add, run it once with `--dry-run --print-command` and read the argv aloud.\n\n## Handoff mode turns shell functions into launch targets\n\nThe interesting move is handoff mode: `--handoff-command` with repeatable `--handoff-arg` makes the composer call *any* command with the submitted prompt as the final argv element — passed as data, never through shell eval.\n\n``` text\n$ prompt-builder --submit --dry-run --handoff-command /bin/echo \"hello from handoff\"\n/bin/echo 'hello from handoff'\n\n$ prompt-builder --submit --dry-run --handoff-command /bin/echo \\\n    --fork-from last --compact \"continue\"\n/bin/echo --fork-from last --compact continue\n```\n\nThose `--fork-from`/`--compact` flags render as checkbox toggles in the TUI — the wrapper declares its own UI. Two patterns run daily in the author's shell: `fixit` bakes a debugger persona into the composer, and `p-f` composes a prompt, then forks the latest Codex session and resumes it with that prompt. Here is the workshop's copy of both, complete — this page is the file's source (the repo's `examples/` ships only `fixit.zsh`; lift `p-wrap.zsh` from the block below):\n\n``` text\n# Wrapping \"p\" (prompt-builder) with custom tools — the two patterns.\n# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh\n# and the p-f/p-c family in your zsh config.\n\n# ── Pattern 1: bake instructions into the composer ─────────────────\n# The composer opens normally, but the launch carries your persona/context.\nfixit() {\n  prompt-builder \\\n    --target codex \\\n    -C \"$PWD\" \\\n    --developer-instructions \"You're an expert debugger who always starts with the \\$fusion skill. The user will pass a terse bug; investigate the behavior and fix it.\"\n}\n\n# ── Pattern 2: handoff mode — your shell function IS the launcher ──\n# prompt-builder composes, then calls your command with the prompt as\n# the final argv element (Command::arg, no shell eval).\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\n# Compose a prompt, then fork the latest Codex session and resume with it.\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\n# Same, but compact the forked session before resuming.\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ── The mdflow lead-in ──────────────────────────────────────────────\n# Every wrapper above is: instructions + context + a launch decision.\n# Declare that in a markdown file instead of a shell function and you\n# get an mdflow flow — reviewable, diffable, evaluable:\n#\n#   flows/fixit.codex.md\n#   ---\n#   engine: codex\n#   ---\n#   You're an expert debugger. Bug report: {{ _1 }}\n#\n# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter\n# for the fuzzy picker; flow `_inputs` render as form fields.\n```\n\nTo adopt the pattern, write one wrapper for a move you repeat and prove it with `--submit --dry-run --handoff-command /bin/echo` substituted in: your prompt must appear verbatim as the final echoed argument. When it does, swap the real command back in. (`p-f` calls the author's private fork helper — supply your own; see the appendix.)\n\n## A wrapper is a file format waiting to happen\n\nLook at what every wrapper above actually is: instructions, plus context, plus a launch decision. Why is that a shell function and not a file? Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. That's mdflow: each repeatable agent job as a markdown file, run on the CLI engine you already use. The `fixit` wrapper restated as a flow looks like this:\n\n``` text\n--- flows/fixit.codex.md ---\nengine: codex\n---\nYou're an expert debugger. Bug report: {{ _1 }}\n```\n\nThe same job also ships in a third form: an [agent skill](https://www.skills.sh/). The full progression is `fixit.zsh` (shell wrapper) → `flows/fixit.codex.md` (mdflow flow) → `fixit` (SKILL.md) — pick whichever your stack runs on. The skill twin is hosted on this site; install it by staging anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill):\n\n``` text\nmkdir -p skill-src/fixit\ncurl -fsSL \"https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw\" -o skill-src/fixit/SKILL.md\nnpx skills add ./skill-src --skill fixit -y\n```\n\nThe bridge already exists in the composer: with the mdflow CLI on `PATH`, a `Flow ‹name›` selector appears beside the target selector, Enter opens a fuzzy picker, and a flow's inputs render as form fields. A ` ignores prompt` badge warns when a flow never references `{{ _1 }}`/`{{ _prompt }}` — mdflow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. If it keeps changing, it isn't ready — keep it in the shell.\n\n## Appendix\n\n### Limits & caveats\n\n- **Permission bypass:** explicit Codex targets launch with `--dangerously-bypass-approvals-and-sandbox`; Claude targets launch with `claude --dangerously-skip-permissions -- <prompt>`. Pi targets add no bypass flag and rely on Pi's own trust settings. Only use these launchers in directories where you accept the selected agent modifying files and running commands.\n- The flow file shown in the last story section is a **constructed illustration**, not a file shipped by either project — that's why it carries the \"example — don't paste\" badge. mdflow's own README shows the same shape (`review.md`, `review.claude.md`, `git diff | explain.md`).\n- The `fixit` persona references `$fusion`, the author's personal skill. Swap in a skill you actually have, or drop that clause.\n- `p-f`/`p-c` call `_codex_prompt_builder_fork`, a private helper in the author's zsh config. The wrappers are printed as evidence of the pattern; to use them, point `_p_handoff_zsh` at your own function.\n- Success-check outputs show `~/.codex-work` for readability; real output expands env paths to your full home directory. Target names `work-profile` and `second-account` are genericized stand-ins for the author's personal profiles.\n- All output was captured the recorded snapshot from prompt-builder v0.1.0; TUI details may drift in later versions. Claude targets currently ignore conversation names and Codex-only options with a warning; Claude fork/resume orchestration is future work — that's exactly what handoff wrappers cover today.\n- Claims about mdflow are limited to its README introduction. The \"wrappers are proto-flows\" promotion rule is the author's editorial inference, not something either README states.\n- The default target is Pi; real submissions fail without the Pi CLI on `PATH`, though every `--dry-run`/print flag works with no agent CLIs installed.\n\n## Operating practice\n\n### Compose only the evidence the task needs\n\n#### What to notice\n\nBuild a prompt packet from text, files, images, and fresh state without smuggling in an entire stale session.\n\n#### Try this\n\nList the **minimum sources** needed to decide, act, and verify; remove everything that cannot change one of those steps.\n\n> “How can I consolidate that into something that's gonna manage it for me?”\n\nJohn Lindquist · [02:37:56](https://proud-anchor-53zn.here.now/watch.html?t=9476#recording-player)\n\n#### Concept\n\nInput is a task plus evidence. Output is a result with a named check. The tradeoff is simple: extra context can add capability, but it also hides contradictions and consumes review attention.\n\n#### Reflection\n\nA large packet is not automatically a complete packet. Prefer relevant, current, and inspectable evidence.\n\n**Recording evidence:** listen at 02:34:33.\n\n> “I usually spend the most amount of time preparing that initial prompt.”\n\nJohn Lindquist · [02:39:00](https://proud-anchor-53zn.here.now/watch.html?t=9540#recording-player)\n\n[Open Prompt Builder](https://shiny-bloom-f8hv.here.now/)\n\n#### Links shared for this topic\n\n- [Prompt Builder source](https://github.com/johnlindquist/prompt-builder) — The repository for composing text, files, and other evidence into prompts.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=9273#q2-prompt-composer)"
    },
    {
      "id": "factory-prompt-builder-discussion",
      "slug": "prompt-builder-discussion",
      "title": "Compose the prompt before choosing the agent — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Context",
      "tags": [
        "prompt-builder",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[95]",
        "resource-manifest.json#videoEvidence.concepts[96]",
        "resource-manifest.json#videoEvidence.concepts[97]",
        "resource-manifest.json#videoEvidence.concepts[98]",
        "resource-manifest.json#videoEvidence.concepts[99]",
        "resource-manifest.json#videoEvidence.concepts[100]",
        "resource-manifest.json#videoEvidence.concepts[101]",
        "resource-manifest.json#videoEvidence.concepts[102]",
        "resource-manifest.json#videoEvidence.concepts[103]",
        "resource-manifest.json#videoEvidence.concepts[104]",
        "resource-manifest.json#videoEvidence.concepts[105]",
        "resource-manifest.json#videoEvidence.concepts[106]",
        "resource-manifest.json#videoEvidence.concepts[107]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[32]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[33]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[34]",
        "resource-manifest.json#videoEvidence.exercises[9]",
        "resource-manifest.json#videoEvidence.exercises[10]",
        "resource-manifest.json#videoEvidence.timeline[448]",
        "resource-manifest.json#videoEvidence.timeline[450]",
        "resource-manifest.json#videoEvidence.timeline[453]",
        "resource-manifest.json#videoEvidence.timeline[455]",
        "resource-manifest.json#videoEvidence.timeline[456]",
        "resource-manifest.json#videoEvidence.timeline[457]",
        "resource-manifest.json#videoEvidence.timeline[458]",
        "resource-manifest.json#videoEvidence.timeline[459]",
        "resource-manifest.json#videoEvidence.timeline[460]",
        "resource-manifest.json#videoEvidence.timeline[461]",
        "resource-manifest.json#videoEvidence.timeline[462]",
        "resource-manifest.json#videoEvidence.timeline[463]",
        "resource-manifest.json#videoEvidence.timeline[465]",
        "resource-manifest.json#videoEvidence.timeline[466]",
        "resource-manifest.json#videoEvidence.timeline[467]",
        "resource-manifest.json#videoEvidence.timeline[470]",
        "resource-manifest.json#videoEvidence.timeline[472]",
        "resource-manifest.json#videoEvidence.timeline[475]",
        "resource-manifest.json#videoEvidence.timeline[481]",
        "resource-manifest.json#videoEvidence.timeline[486]",
        "resource-manifest.json#videoEvidence.timeline[488]",
        "resource-manifest.json#videoEvidence.timeline[490]",
        "resource-manifest.json#videoEvidence.timeline[491]",
        "resource-manifest.json#videoEvidence.timeline[493]",
        "resource-manifest.json#videoEvidence.timeline[494]",
        "resource-manifest.json#videoEvidence.timeline[495]",
        "resource-manifest.json#videoEvidence.timeline[496]",
        "resource-manifest.json#videoEvidence.timeline[497]",
        "resource-manifest.json#videoEvidence.timeline[498]",
        "resource-manifest.json#videoEvidence.timeline[499]",
        "resource-manifest.json#videoEvidence.timeline[501]",
        "resource-manifest.json#videoEvidence.timeline[502]",
        "resource-manifest.json#videoEvidence.timeline[503]",
        "resource-manifest.json#videoEvidence.timeline[504]",
        "resource-manifest.json#videoEvidence.timeline[505]",
        "resource-manifest.json#videoEvidence.timeline[507]",
        "resource-manifest.json#videoEvidence.timeline[508]",
        "resource-manifest.json#videoEvidence.timeline[509]",
        "resource-manifest.json#videoEvidence.timeline[510]",
        "resource-manifest.json#videoEvidence.timeline[512]",
        "resource-manifest.json#videoEvidence.timeline[514]",
        "resource-manifest.json#videoEvidence.uncertainties[29]",
        "resource-manifest.json#videoEvidence.uncertainties[30]",
        "resource-manifest.json#videoEvidence.uncertainties[31]",
        "resource-manifest.json#videoEvidence.demos[53]",
        "resource-manifest.json#videoEvidence.demos[54]",
        "resource-manifest.json#videoEvidence.demos[55]",
        "resource-manifest.json#videoEvidence.demos[56]",
        "resource-manifest.json#videoEvidence.demos[57]",
        "resource-manifest.json#videoEvidence.demos[58]",
        "resource-manifest.json#videoEvidence.demos[59]"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 2084,
      "url": "/topics/factory-prompt-builder-discussion/",
      "markdownUrl": "/markdown/factory-prompt-builder-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-prompt-builder-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "prompt-composing-surface",
          "text": "Prompt-Composing Surface",
          "level": 3
        },
        {
          "id": "instant-ui-rendering",
          "text": "Instant UI Rendering",
          "level": 3
        },
        {
          "id": "unified-skill-auto-completion",
          "text": "Unified Skill Auto-completion",
          "level": 3
        },
        {
          "id": "cross-model-prompt-history",
          "text": "Cross-Model Prompt History",
          "level": 3
        },
        {
          "id": "external-gui-editor-synchronization",
          "text": "External GUI Editor Synchronization",
          "level": 3
        },
        {
          "id": "agentic-engineering-responsible-vibe-coding",
          "text": "Agentic Engineering / Responsible Vibe Coding",
          "level": 3
        },
        {
          "id": "zsh-aliases-for-agents",
          "text": "Zsh Aliases for Agents",
          "level": 3
        },
        {
          "id": "conversation-forking-branching",
          "text": "Conversation Forking/Branching",
          "level": 3
        },
        {
          "id": "conversation-compacting",
          "text": "Conversation Compacting",
          "level": 3
        },
        {
          "id": "prompt-builder-context-injection",
          "text": "Prompt Builder Context Injection",
          "level": 3
        },
        {
          "id": "cross-cli-tool-synthesis",
          "text": "Cross-CLI Tool Synthesis",
          "level": 3
        },
        {
          "id": "zsh-wrapper-functions-for-ai-tools",
          "text": "ZSH Wrapper Functions for AI Tools",
          "level": 3
        },
        {
          "id": "markdown-flow-agent-plane",
          "text": "Markdown Flow Agent Plane",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "how-well-did-you-know-rust-in-order-to-build-the-prompt-builder-or-did-you-just-vibe-code-it-with-ai",
          "text": "How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI?",
          "level": 3
        },
        {
          "id": "in-claude-code-is-branch-or-fork",
          "text": "In Claude code is /branch or /fork",
          "level": 3
        },
        {
          "id": "please-build-up-a-prompt-builder-that-uses-claude-code-s-pr-flags-and-create-a-zsh-function-for-it-so-that-i-can-launch-it-with-p-pr",
          "text": "Please build up a prompt builder that uses Claude code's PR flags and create a ZSH function for it so that I can launch it with P-PR.",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-exact-keystrokes-or-string-used-to-open-prompt-builder-tool-at-02-36-24",
          "text": "Unresolved: Exact keystrokes or string used to open prompt-builder tool at 02:36:24.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-configuration-variable-syntax-john-intends-to-append-next-to-resolve-the-zed-process-wait-issue",
          "text": "Unresolved: The exact configuration variable syntax John intends to append next to resolve the Zed process wait issue.",
          "level": 3
        },
        {
          "id": "unresolved-exact-definition-and-logic-for-all-experimental-prompt-builder-shortcuts-p-zx-p-bird-p-bm",
          "text": "Unresolved: Exact definition and logic for all experimental prompt builder shortcuts (p-zx, p-bird, p-bm).",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-36-05",
          "text": "Demonstration detail: 02:36:05",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-38-01",
          "text": "Demonstration detail: 02:38:01",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-39-36",
          "text": "Demonstration detail: 02:39:36",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-41-55",
          "text": "Demonstration detail: 02:41:55",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-45-08",
          "text": "Demonstration detail: 02:45:08",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-48-26",
          "text": "Demonstration detail: 02:48:26",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-49-33",
          "text": "Demonstration detail: 02:49:33",
          "level": 3
        }
      ],
      "markdown": "# Compose the prompt before choosing the agent — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Prompt-Composing Surface\n\nA dedicated intermediate layer detached from an execution engine, designed to optimize layout composition and metadata handling.\n\n### Instant UI Rendering\n\nUsing compiled low-overhead systems languages (e.g., Rust and Ratatui) to avoid initialization latency during high-frequency developer interactions.\n\n### Unified Skill Auto-completion\n\nNormalizing tool call syntax variations across differing third-party agents into a single interactive search component.\n\n### Cross-Model Prompt History\n\nA feature built into custom prompt interfaces allowing developers to navigate and search past prompt records regardless of which LLM agent or target model was queried.\n\n### External GUI Editor Synchronization\n\nIntegrating terminal utilities with modern graphical editors (like Zed or VS Code) requires setting process flags such as --wait via the VISUAL or EDITOR environment variables so the shell pauses execution until the file buffer is saved and closed.\n\n### Agentic Engineering / Responsible Vibe Coding\n\nUtilizing AI coding assistants to design and implement software in an unfamiliar language (e.g., Rust) by asking targeted architectural questions about user interfaces, navigation libraries, and potential edge cases instead of letting the AI blindly generate bulk code.\n\n### Zsh Aliases for Agents\n\nCreating prefix-driven keyboard macros or functions (e.g., p-) to inject project-specific context, prompt formatting patterns, or session behaviors immediately into a terminal agent session.\n\n### Conversation Forking/Branching\n\nDividing an active, long-running agent chat thread into a new independent thread to explore alternative problem variations without corrupting or cluttering the primary context timeline.\n\n### Conversation Compacting\n\nCondensing an extensive agent interaction history into a short summary or structured snapshot before starting a fresh context window to save input tokens and keep responses focused.\n\n### Prompt Builder Context Injection\n\nThe technique of running help flags for multiple separate command-line utilities within an agent prompt to automatically populate the context window with complete option schemas.\n\n### Cross-CLI Tool Synthesis\n\nEnabling an AI agent to compose interoperable wrappers or functions (like a Zsh function combining Claude Code and Prompt Builder) by giving it direct access to each tool's interface definition.\n\n### ZSH Wrapper Functions for AI Tools\n\nWriting targeted shell aliases or wrapper commands (e.g., p-pr) that encapsulate multiple specialized flags for AI developer CLI tools, avoiding repetitive typing.\n\n### Markdown Flow Agent Plane\n\nUsing structured Markdown files as an active orchestration layout for automated agents, as built into the MDFlow ecosystem.\n\n## Questions and answer status\n\n### How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI?\n\n**Status: answered.** John states he only knew Rust from a few introductory examples and had never written serious Rust before. He describes his approach to 'vibe coding' as a responsible way of asking an agent for library recommendations, keyboard navigation handling, and structural architecture rather than just hoping code randomly appears.\n\n### In Claude code is /branch or /fork\n\n**Status: partial.** John mentions that Claude Code has built-in features (like 'by the way') for context isolation, though he does not directly reply to the chat text during the video chunk.\n\n### Please build up a prompt builder that uses Claude code's PR flags and create a ZSH function for it so that I can launch it with P-PR.\n\n**Status: partial.** The agent maps the user's local directory and targets layout to build a tailored wrapper script pattern, executing checks up to the shard boundary.\n\n## Exercises\n\n- **Try:** Configure custom Zsh prefixes or shorthand command aliases in your .zshrc configuration file to quickly spin up, clone, or clean context threads inside CLI-based AI agents.\n  **Basis:** Transcript time 02:41:48.250 to 02:42:16.570\n\n- **Try:** Open an interactive agent loop or prompt interface, run the help/documentation commands for two independent CLI tools you use frequently, and ask the agent to construct a unified shell function or shortcut that links their features together seamlessly.\n  **Basis:** 02:47:08.000\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [02:34:33](https://proud-anchor-53zn.here.now/watch.html?t=9273#recording-player) — John discusses the value of building personalized developer tools and workspaces.\n\n- [02:35:02](https://proud-anchor-53zn.here.now/watch.html?t=9302#recording-player) — John shares the link to his repository: https://github.com/johnlindquist/prompt-builder.\n\n- [02:35:45](https://proud-anchor-53zn.here.now/watch.html?t=9345#recording-player) — The reference document displays a table comparing prompt composing tools including Fabric, bis, aichat, espanso, and promptfoo.\n\n- [02:36:05](https://proud-anchor-53zn.here.now/watch.html?t=9365#recording-player) — John inputs the command pi in the terminal to demonstrate its startup delay.\n\n- [02:36:10](https://proud-anchor-53zn.here.now/watch.html?t=9370#recording-player) — John terminates the agent and invokes codex to show the initialization speed of the Rust tool.\n\n- [02:36:13](https://proud-anchor-53zn.here.now/watch.html?t=9373#recording-player) — John terminates the application and runs claude to demonstrate its Bun-based initialization speed.\n\n- [02:36:24](https://proud-anchor-53zn.here.now/watch.html?t=9384#recording-player) — John executes his custom prompt tool, which brings up the prompt-builder TUI instantaneously.\n\n- [02:36:50](https://proud-anchor-53zn.here.now/watch.html?t=9410#recording-player) — John types Oracleandhere-now in the Prompt field to demonstrate the active skills auto-completion pop-up menu.\n\n- [02:37:05](https://proud-anchor-53zn.here.now/watch.html?t=9425#recording-player) — John shifts focus to the conversation Name input field to illustrate naming sessions up front.\n\n- [02:37:30](https://proud-anchor-53zn.here.now/watch.html?t=9450#recording-player) — John interacts with the Target row selection at the bottom to toggle between execution models (pi, codex, claude).\n\n- [02:37:40](https://proud-anchor-53zn.here.now/watch.html?t=9460#recording-player) — John opens the flows menu overlay (Enter flows) in the TUI application.\n\n- [02:38:01](https://proud-anchor-53zn.here.now/watch.html?t=9481#recording-player) — The shard concludes with John detailing how a central TUI removes the need to remember individual CLI flags and parameters.\n\n- [02:38:07](https://proud-anchor-53zn.here.now/watch.html?t=9487#recording-player) — Transcript claim by John Lindquist regarding the purpose of the project allowing prompt history navigation across all models.\n\n- [02:38:10](https://proud-anchor-53zn.here.now/watch.html?t=9490#recording-player) — Visual shows John pressing the up arrow to populate the Prompt area with a past command (move to ./images).\n\n- [02:38:16](https://proud-anchor-53zn.here.now/watch.html?t=9496#recording-player) — Visual shows the TUI switching to a Search history: mockup overlay after pressing Ctrl+R.\n\n- [02:38:36](https://proud-anchor-53zn.here.now/watch.html?t=9516#recording-player) — Visual shows the workspace returning back to the TUI prompt builder, rendering an error label stating -editor: zed returned immediately without changes; GUI editors need a wait flag, e.g. VISUAL=\"zed --wait\";.\n\n- [02:38:52](https://proud-anchor-53zn.here.now/watch.html?t=9532#recording-player) — Transcript claim by John explaining that the external text entry failed because the VISUAL environment variable was not configured to await the GUI editor process properly.\n\n- [02:39:45](https://proud-anchor-53zn.here.now/watch.html?t=9585#recording-player) — Visual shows John scrolling past tables containing alternative prompt composition tools like Fabric, Bim, espanso, aichat, and promptfoo.\n\n- [02:41:14](https://proud-anchor-53zn.here.now/watch.html?t=9674#recording-player) — Transcript claim by John recognizing a participant's phrase and stating \"Agentic Engineering is the snobby way of saying it.\"\n\n- [02:41:55](https://proud-anchor-53zn.here.now/watch.html?t=9715#recording-player) — John types p- and presses Tab in the Zsh prompt, showing completion aliases: p-bird, p-bm, p-c, p-cm, p-cx, p-f, p-fl, p-kx, p-zx.\n\n- [02:42:33](https://proud-anchor-53zn.here.now/watch.html?t=9753#recording-player) — John runs p-c, opening a terminal prompt composition UI overlay with interactive fields (Name, Prompt, and checkboxes).\n\n- [02:44:24](https://proud-anchor-53zn.here.now/watch.html?t=9864#recording-player) — John types which p-zx and p-zx into the terminal prompt to inspect the alias mapping.\n\n- [02:44:30](https://proud-anchor-53zn.here.now/watch.html?t=9870#recording-player) — John types p-bird and which p-bird into the terminal.\n\n- [02:45:08](https://proud-anchor-53zn.here.now/watch.html?t=9908#recording-player) — John triggers an overlay window containing Name and Prompt fields to compose an agent task.\n\n- [02:45:14](https://proud-anchor-53zn.here.now/watch.html?t=9914#recording-player) — John types !claude --help into the Prompt input area.\n\n- [02:45:18](https://proud-anchor-53zn.here.now/watch.html?t=9918#recording-player) — The prompt tool executes the inline shell command, logging pi-cmdr loaded: type ! to open the command picker and planning execution.\n\n- [02:45:24](https://proud-anchor-53zn.here.now/watch.html?t=9924#recording-player) — The terminal prints the end section of the claude --help output.\n\n- [02:45:41](https://proud-anchor-53zn.here.now/watch.html?t=9941#recording-player) — John runs p --help inside the prompt field to feed Prompt Builder's context into the agent session.\n\n- [02:46:15](https://proud-anchor-53zn.here.now/watch.html?t=9975#recording-player) — John scrolls up and clicks to expand the previous tool execution blocks to ensure full help menus are loaded in the viewer.\n\n- [02:47:08](https://proud-anchor-53zn.here.now/watch.html?t=10028#recording-player) — John submits the task asking the agent to build up a prompt builder that uses Claude code's PR flags and create a ZSH function for it.\n\n- [02:47:33](https://proud-anchor-53zn.here.now/watch.html?t=10053#recording-player) — John executes which x (returning exit code 1) and enters a new instruction guiding the agent to ~/.config/zsh.\n\n- [02:47:52](https://proud-anchor-53zn.here.now/watch.html?t=10072#recording-player) — The agent restarts with the updated prompt and reports that it is inspecting the external Zsh configuration.\n\n- [02:47:55](https://proud-anchor-53zn.here.now/watch.html?t=10075#recording-player) — The agent shares its plan to inspect existing p wrappers and style conventions, mentioning Claude's --from-pr flag.\n\n- [02:47:58](https://proud-anchor-53zn.here.now/watch.html?t=10078#recording-player) — The agent runs an automated sequence of commands to inspect ~/.config/zsh and the p target help system.\n\n- [02:48:08](https://proud-anchor-53zn.here.now/watch.html?t=10088#recording-player) — The agent inspects local profiles by executing p target list and p target add --help.\n\n- [02:48:26](https://proud-anchor-53zn.here.now/watch.html?t=10106#recording-player) — Ghostty terminal window displays prompt-builder tool executing tests for resume wrappers.\n\n- [02:48:26](https://proud-anchor-53zn.here.now/watch.html?t=10106#recording-player) — John recommends building personal ZSH functions or scripts to encapsulate tool configurations.\n\n- [02:48:35](https://proud-anchor-53zn.here.now/watch.html?t=10115#recording-player) — The prompt builder updates targets.toml adding the claude-pr profile configuration.\n\n- [02:48:50](https://proud-anchor-53zn.here.now/watch.html?t=10130#recording-player) — The prompt builder system outputs text showing it has written the ZSH wrapper script to ~/.config/zsh/conf.d/44-ai-claude-pr-dsl.zsh.\n\n- [02:50:00](https://proud-anchor-53zn.here.now/watch.html?t=10200#recording-player) — John runs the ghv alias which opens the Chrome browser directly onto the mdflow repository on GitHub.\n\n- [02:50:31](https://proud-anchor-53zn.here.now/watch.html?t=10231#recording-player) — John runs the new wrapper command p-pr 24 in his terminal.\n\n### Unresolved: Exact keystrokes or string used to open prompt-builder tool at 02:36:24.\n\nThe interface switch occurs in a single frame update, hiding any prior input command typed into the shell.\n\n**Discriminating evidence:** Consult the user's open-source dotfiles repository or global keybindings.\n\n### Unresolved: The exact configuration variable syntax John intends to append next to resolve the Zed process wait issue.\n\nThe prompt tool only prints a diagnostic hint on the screen; John describes the bug orally but defers editing his profile configurations or setting the exact variable during the shard.\n\n**Discriminating evidence:** Wait for subsequent segments where terminal shell profiles or workspace configuration files are altered.\n\n### Unresolved: Exact definition and logic for all experimental prompt builder shortcuts (p-zx, p-bird, p-bm).\n\nJohn notes that these are experimental or need a 'cleanup pass' and does not successfully run or explain them all.\n\n**Discriminating evidence:** Can be verified in subsequent configuration or script walkthrough shards.\n\n### Demonstration detail: 02:36:05\n\n- Tested loading performance for terminal agents pi, codex, and claude inside the mdflow project directory.\n- Opened custom prompt-builder terminal user interface.\n- Demonstrated dropdown autocompletion for conversation skill definitions using token syntax.\n- Interacted with input fields for target applications and workflow options.\n\n**Tools observed:** Pi CLI, OpenAI Codex CLI, Claude Code, Prompt Builder TUI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\npi\ncodex\nclaude\n```\n\n### Demonstration detail: 02:38:01\n\n- Demonstrating prompt history by pressing up arrow in custom TUI prompt builder\n- Searching past prompts using Ctrl+R search history overlay\n- Launching external Zed editor to write prompt text\n- Observing process exit error due to lack of zed --wait flag setup\n- Manually typing placeholder text into the prompt input\n\n**Tools observed:** mdflow, Zed editor.\n\n### Demonstration detail: 02:39:36\n\n- Opening Google Chrome browser to view documentation\n- Navigating from Agentic Software Factory index page to prompt-builder section\n- Scrolling through prompt-builder CLI usage instructions, installation commands, and targets configuration format\n\n**Tools observed:** Google Chrome.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nprompt-builder --dry-run --print-command \"hello\"\nprompt-builder target list\n```\n\n### Demonstration detail: 02:41:55\n\n- Triggered Zsh autocomplete options via tab on prefix p-\n- Executed p-c command to launch terminal-based prompt overlay surface\n- Inspected script path routing via which command calls for p-zx and p-bird\n\n**Tools observed:** Ghostty, Zsh, Claude Code.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\np-c\nwhich p-zx\nwhich p-bird\n```\n\n### Demonstration detail: 02:45:08\n\n- Opened task overlay wizard from the command picker tool.\n- Executed help flags for Claude and Prompt Builder to feed tool descriptions into context.\n- Authored a prompt to synthesize a hybrid Zsh function named p-pr.\n- Aborted execution and redirected the agent to search local Zsh files.\n- Observed automated file exploration and config analysis performed by the agent.\n\n**Tools observed:** Ghostty, Prompt Builder CLI, Claude Code.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\n!claude --help\np --help\nwhich x\np target list\n```\n\n### Demonstration detail: 02:48:26\n\n- Automated generation of ZSH targets and file outputs via the prompt builder engine.\n\n**Tools observed:** Ghostty, Prompt Builder CLI.\n\n### Demonstration detail: 02:49:33\n\n- Checking repo via terminal, running the repo browser lookup command, and execution of pull request targeting.\n\n**Tools observed:** GitHub CLI, Google Chrome.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nghv\np-pr 24\n```"
    },
    {
      "id": "factory-prompt-builder-practice",
      "slug": "prompt-builder-practice",
      "title": "Compose the prompt before choosing the agent — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.",
      "category": "Context",
      "tags": [
        "prompts",
        "exercises",
        "prompt-builder"
      ],
      "sources": [
        {
          "label": "Compose the prompt before choosing the agent",
          "url": "https://shiny-bloom-f8hv.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://shiny-bloom-f8hv.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "04-prompt-builder/index.html#Quick start",
        "04-prompt-builder/index.html#Prompt library",
        "04-prompt-builder/index.html#Set it up (agent guide)",
        "04-prompt-builder/index.html#The fixit debugger persona",
        "04-prompt-builder/index.html#Have your agent write you a handoff wrapper",
        "04-prompt-builder/index.html#Add a second-account launch target",
        "04-prompt-builder/agent.md"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1309,
      "url": "/topics/factory-prompt-builder-practice/",
      "markdownUrl": "/markdown/factory-prompt-builder-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-prompt-builder-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "the-fixit-debugger-persona",
          "text": "The fixit debugger persona",
          "level": 3
        },
        {
          "id": "have-your-agent-write-you-a-handoff-wrapper",
          "text": "Have your agent write you a handoff wrapper",
          "level": 3
        },
        {
          "id": "add-a-second-account-launch-target",
          "text": "Add a second-account launch target",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "prompt-builder-p-agent-setup-guide",
          "text": "Prompt Builder (p) — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Compose the prompt before choosing the agent — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.\n\n## Quick start\n\n``` text\n# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nalias p=prompt-builder\np --dry-run --print-command \"hello\"    # prints the exact launch: pi hello\np                                      # open the composer: $ skills · @ files · Ctrl+R history\n```\n\n## Prompt library\n\n### The fixit debugger persona\n\n- Agent: Codex, launched through `p --target codex --developer-instructions \"…\"`\n- Working directory: the project with the bug\n- Expected result: the composer opens; whatever terse bug you type launches Codex carrying this persona\n\n``` text\nYou're an expert debugger who always starts with the $fusion skill. The user will pass a terse bug; investigate the behavior and fix it.\n```\n\n### Have your agent write you a handoff wrapper\n\n- Agent: any coding agent (Claude Code, Codex, Pi)\n- Working directory: wherever your shell config lives\n- Expected result: a new shell function whose launch is proven with the /bin/echo substitution test before anything real runs\n\n``` text\nWrite me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command <cmd> --handoff-arg <arg> passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo \"test\" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: <describe your move>.\n```\n\n### Add a second-account launch target\n\n- Agent: any coding agent with shell access\n- Working directory: anywhere\n- Expected result: a new target in `targets.toml` and a printed launch command carrying `CLAUDE_CONFIG_DIR`\n\n``` text\nAdd a prompt-builder launch target for a second Claude Code account: run prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' and then verify it with prompt-builder --dry-run --target second-account --print-command \"hello\". Show me the printed command so I can read the exact argv before any real launch.\n```\n\n## Set it up (agent guide)\n\n1.  Install the composer and alias it to `p`. Keep `--locked`: the lockfile pins patched `crossterm`/`ratatui` revisions.\n\n    ``` text\n    cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\n    echo 'alias p=prompt-builder' >> ~/.zshrc\n    source ~/.zshrc\n    ```\n\n2.  Add one launch target for an agent or account you already switch to by hand.\n\n    ``` text\n    prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n    ```\n\n    This writes `~/.prompt-builder/targets.toml`. On a fresh machine the file now reads exactly:\n\n    ``` text\n    [[targets]]\n    name = \"pi\"\n    kind = \"pi\"\n\n    [[targets]]\n    name = \"codex\"\n    kind = \"codex\"\n\n    [[targets]]\n    name = \"claude\"\n    kind = \"claude\"\n\n    [[targets]]\n    name = \"work-profile\"\n    kind = \"codex\"\n\n    [targets.env]\n    CODEX_HOME = \"~/.codex-work\"\n    ```\n\n**Success check:** print the launches without running anything, then list the targets.\n\n``` text\nprompt-builder --dry-run --print-command \"hello\"\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\nprompt-builder target list\n```\n\n``` text\npi hello\nCODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello\npi            pi      bin=pi\ncodex         codex   bin=codex\nclaude        claude  bin=claude\nwork-profile  codex   bin=codex   CODEX_HOME=~/.codex-work\n```\n\nIn real output the `CODEX_HOME` path appears expanded to your full home directory. Read the second line closely — that bypass flag is the reason dry-run comes first.\n\n## Complete reusable setup contract\n\n## Prompt Builder (p) — agent setup guide\n\nFollowing this file sets up: the `prompt-builder` terminal composer, aliased to `p`, with one custom launch target, verified end-to-end with dry-run flags (no agent is ever launched by these steps).\n\nPlaceholders used below: `~` = the user's home directory. All other paths are literal.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\ncargo --version\n```\n\nExpected: a Rust toolchain from rustup (the repo pins Rust 1.95.0; any recent stable cargo can build it). If `cargo` is missing, stop and tell your user to install rustup from https://rustup.rs — do not proceed.\n\nThe Pi, Codex, and Claude Code CLIs are NOT required for these steps: every verification below uses `--dry-run`/print flags, which work with no agent CLIs installed.\n\n## Steps\n\n1. Install the composer from the public repo. Keep `--locked` — the lockfile pins patched `crossterm` and `ratatui` revisions, so unlocked installs may behave differently in the terminal.\n\n   ```bash\n   cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\n   ```\n\n   This compiles from source and can take a few minutes.\n\n2. Alias the binary to `p`. For zsh:\n\n   ```bash\n   echo 'alias p=prompt-builder' >> ~/.zshrc\n   ```\n\n   For other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink:\n\n   ```bash\n   ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\n   ```\n\n3. Add one launch target (a named launch profile: binary + env vars + default args). This example creates a Codex profile with its own `CODEX_HOME`, i.e. a separate identity:\n\n   ```bash\n   prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n   ```\n\n   On a fresh machine this writes `~/.prompt-builder/targets.toml` with exactly this content:\n\n   ```toml\n   [[targets]]\n   name = \"pi\"\n   kind = \"pi\"\n\n   [[targets]]\n   name = \"codex\"\n   kind = \"codex\"\n\n   [[targets]]\n   name = \"claude\"\n   kind = \"claude\"\n\n   [[targets]]\n   name = \"work-profile\"\n   kind = \"codex\"\n\n   [targets.env]\n   CODEX_HOME = \"~/.codex-work\"\n   ```\n\n   If the user already has a `targets.toml`, `target add` appends to it instead; existing targets are preserved.\n\n## Success check\n\nRun:\n\n```bash\nprompt-builder --dry-run --print-command \"hello\"\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\nprompt-builder target list\n```\n\nExpected observable result:\n\n- Line 1 prints exactly: `pi hello`\n- Line 2 prints: `CODEX_HOME=<expanded home>/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello`\n- `target list` shows four targets: `pi`, `codex`, `claude`, `work-profile` (the last with `CODEX_HOME=~/.codex-work`)\n\nReport to your user: what you installed, the exact printed launch commands, and — importantly — that the Codex line contains `--dangerously-bypass-approvals-and-sandbox`. Real (non-dry-run) Codex and Claude launches use permission-bypass flags, so `p` should only be pointed at directories where the user accepts the agent modifying files and running commands.\n\n## Notes for agents\n\n- If `cargo install` fails on dependency resolution, you probably dropped `--locked`. Re-run with it.\n- If `target add` fails with a duplicate-name error, the user already has a `work-profile` target; pick another name and adjust the success check to match.\n- `target add` defaults to `--kind pi` — always pass `--kind` explicitly when creating codex/claude targets.\n- The default target is Pi. Real submissions (without `--dry-run`) fail if the `pi` CLI is not on `PATH`; that does not affect any step in this file.\n- The composer's interactive features ($ skills, @ files, Ctrl+R history, Tab to the `Target ‹name›` selector) need a real TTY; don't try to drive the TUI from a non-interactive shell. Verify with the print flags above instead.\n- Full docs and updates: https://github.com/johnlindquist/prompt-builder (page version of this guide: https://shiny-bloom-f8hv.here.now/)\n- The guide's `fixit` wrapper also ships as a skills.sh-format agent skill hosted on this site (same job, third form of the wrapper: zsh function → mdflow flow → SKILL.md). Machine-fetch URL: `https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw` (`?raw` required — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir named `skills/` (the skills CLI claims that name and you'd install an empty skill), e.g. `mkdir -p skill-src/fixit && curl -fsSL \"<url above>\" -o skill-src/fixit/SKILL.md && npx skills add ./skill-src --skill fixit -y`.\n- Two presentation pages accompany the guide, for humans walking through the section: https://shiny-bloom-f8hv.here.now/replay.html (Session Replay — the annotated transcript of the sessions that set up and wrapped `p`) and https://shiny-bloom-f8hv.here.now/dialogue.html (Socratic Dialogue — attendee questions driving the same material). They contain the same commands plus the complete wrapper file `p-wrap.zsh`, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo's `examples/` directory ships only `fixit.zsh` — so copy `p-wrap.zsh` from the workshop pages, not from the repo. This file remains the canonical machine copy for setup."
    },
    {
      "id": "factory-prompt-builder-questions",
      "slug": "prompt-builder-questions",
      "title": "Compose the prompt before choosing the agent — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Context",
      "tags": [
        "prompt-builder",
        "questions"
      ],
      "sources": [
        {
          "label": "Compose the prompt before choosing the agent — questions and tradeoffs",
          "url": "https://shiny-bloom-f8hv.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "04-prompt-builder/dialogue.html#The questions, in the order the room asks them"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1149,
      "url": "/topics/factory-prompt-builder-questions/",
      "markdownUrl": "/markdown/factory-prompt-builder-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-prompt-builder-questions.json",
      "headings": [
        {
          "id": "the-questions-in-the-order-the-room-asks-them",
          "text": "The questions, in the order the room asks them",
          "level": 2
        }
      ],
      "markdown": "# Compose the prompt before choosing the agent — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The questions, in the order the room asks them\n\nI already compose prompts inside Claude Code. Why does the prompt need a separate tool?\n\nBecause the prompt is the actual work product, and right now it lives inside someone else's REPL. Switch agents and you abandon your history, your paste handling, your muscle memory. `p` decouples them: `$` for skill lookup, `@` for file search, `Ctrl+R` for history that follows *you* — it reads Codex's own `~/.codex/history.jsonl` alongside its private file, so prompts from either tool come back. The agent is just a selector at the bottom of the screen.\n\n``` text\n# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nalias p=prompt-builder\np --dry-run --print-command \"hello\"    # prints the exact launch: pi hello\np                                      # open the composer: $ skills · @ files · Ctrl+R history\n```\n\nIt launches agents for me. How do I know what it's actually going to run?\n\nEvery launch path has a dry-run twin. `--print-command` shows the exact argv; `--print-launch-json` emits a stable manifest for scripts. Nothing is hidden behind the TUI:\n\n``` text\n$ prompt-builder --dry-run --print-command \"hello\"\npi hello\n\n$ prompt-builder --dry-run --print-launch-json \"hello\"\n{\n  \"schema_version\": 1,\n  \"mode\": \"pi\",\n  \"command\": \"pi\",\n  \"argv\": [\"pi\", \"hello\"],\n  \"env\": {},\n  \"prompt\": \"hello\",\n  \"pi\": {\"cwd\": \".\", \"session_name\": null}\n}\n```\n\nBefore trusting any target you add, run it once with `--dry-run --print-command` and read the argv aloud.\n\nI did read the argv aloud. It says `--dangerously-bypass-approvals-and-sandbox`. Isn't that terrifying?\n\nIt should give you pause — the flag says so out loud, and this page won't hide it:\n\n``` text\n$ prompt-builder --dry-run --target work-profile --print-command \"hello\"\nCODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello\n```\n\nExplicit Codex targets launch with that bypass flag; Claude targets launch with `--dangerously-skip-permissions`; Pi targets add no bypass flag and rely on Pi's own trust settings. The rule: only point `p` at directories where you accept the selected agent modifying files and running commands. Dry-run first is not a suggestion — it's the whole trust model.\n\nI have a work account and a personal account. Do I need two installs?\n\nNo — a different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity, and identities are just targets in `~/.prompt-builder/targets.toml`:\n\n``` text\nprompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second'\nprompt-builder target list\n```\n\n``` text\npi              pi      bin=pi\ncodex           codex   bin=codex\nclaude          claude  bin=claude\nwork-profile    codex   bin=codex   CODEX_HOME=~/.codex-work\nsecond-account  claude  bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second\n```\n\nIn the composer that's Tab to `Target ‹name›`, Space to cycle. Same prompt, different agent, different account.\n\nMy launcher isn't an agent at all — it's a zsh function that forks my last Codex session. Can `p` drive that?\n\nThat's handoff mode, and it's the interesting move of this whole section: `--handoff-command` makes the composer call *any* command with your submitted prompt as the final argv element — passed as data, never through shell eval. Here are the two wrapper patterns that run daily, complete:\n\n``` text\n# Wrapping \"p\" (prompt-builder) with custom tools — the two patterns.\n# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh\n# and the p-f/p-c family in your zsh config.\n\n# ── Pattern 1: bake instructions into the composer ─────────────────\n# The composer opens normally, but the launch carries your persona/context.\nfixit() {\n  prompt-builder \\\n    --target codex \\\n    -C \"$PWD\" \\\n    --developer-instructions \"You're an expert debugger who always starts with the \\$fusion skill. The user will pass a terse bug; investigate the behavior and fix it.\"\n}\n\n# ── Pattern 2: handoff mode — your shell function IS the launcher ──\n# prompt-builder composes, then calls your command with the prompt as\n# the final argv element (Command::arg, no shell eval).\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\n# Compose a prompt, then fork the latest Codex session and resume with it.\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\n# Same, but compact the forked session before resuming.\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ── The mdflow lead-in ──────────────────────────────────────────────\n# Every wrapper above is: instructions + context + a launch decision.\n# Declare that in a markdown file instead of a shell function and you\n# get an mdflow flow — reviewable, diffable, evaluable:\n#\n#   flows/fixit.codex.md\n#   ---\n#   engine: codex\n#   ---\n#   You're an expert debugger. Bug report: {{ _1 }}\n#\n# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter\n# for the fuzzy picker; flow `_inputs` render as form fields.\n```\n\n`p-f` composes a prompt, then forks the latest Codex session and resumes it with that prompt. One caveat, same as the section guide: it calls a private fork helper — point `_p_handoff_zsh` at your own function.\n\nHow do I write one of those wrappers without wrecking my shell config?\n\nYou don't hand-write it — you make your agent prove it first with the `/bin/echo` substitution test: your prompt has to appear verbatim as the final echoed argument before any real command gets wired in. This is the prompt to paste into your agent:\n\n``` text\nWrite me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command <cmd> --handoff-arg <arg> passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo \"test\" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: <describe your move>.\n```\n\nBonus: wrapper flags like `--fork-from` and `--compact` render as checkbox toggles in the TUI — the wrapper declares its own UI.\n\nThis is turning into a lot of shell functions. Where does it end?\n\nLook at what every wrapper actually is: instructions + context + a launch decision. That's a file format begging to exist. Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. The `fixit` wrapper restated as a flow:\n\n``` text\n--- flows/fixit.codex.md ---\nengine: codex\n---\nYou're an expert debugger. Bug report: {{ _1 }}\n```\n\nThat's mdflow, and the bridge already exists in the composer: with the mdflow CLI on `PATH`, a `Flow ‹name›` selector appears beside the target selector, and a flow's inputs render as form fields — with a ` ignores prompt` badge if the flow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. That's the next section."
    },
    {
      "id": "factory-prompt-builder-worked-example",
      "slug": "prompt-builder-worked-example",
      "title": "Compose the prompt before choosing the agent — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Context",
      "tags": [
        "prompt-builder",
        "examples"
      ],
      "sources": [
        {
          "label": "Compose the prompt before choosing the agent — worked example",
          "url": "https://shiny-bloom-f8hv.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "04-prompt-builder/replay.html#Part 1 — Compose first, inspect every launch",
        "04-prompt-builder/replay.html#Part 2 — Handoff: your shell functions become launch targets"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 974,
      "url": "/topics/factory-prompt-builder-worked-example/",
      "markdownUrl": "/markdown/factory-prompt-builder-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-prompt-builder-worked-example.json",
      "headings": [
        {
          "id": "part-1-compose-first-inspect-every-launch",
          "text": "Part 1 — Compose first, inspect every launch",
          "level": 2
        },
        {
          "id": "part-2-handoff-your-shell-functions-become-launch-targets",
          "text": "Part 2 — Handoff: your shell functions become launch targets",
          "level": 2
        }
      ],
      "markdown": "# Compose the prompt before choosing the agent — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## Part 1 — Compose first, inspect every launch\n\nYou\n\nInstall prompt-builder and alias it to `p`. Before it launches anything real, show me exactly what it would run.\n\nAgent\n\nInstalled from the public repo — `--locked` matters, the lockfile pins patched `crossterm`/`ratatui` revisions — then asked for the launch without running it:\n\n``` text\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nalias p=prompt-builder\nprompt-builder --dry-run --print-command \"hello\"\n```\n\n``` text\npi hello\n```\n\nThe first beat of every session with this tool: `--dry-run --print-command`. Nothing is hidden behind the TUI — the exact argv is printable before anything runs.\n\nYou\n\nI keep a second Codex identity by exporting `CODEX_HOME` by hand every time. Make it a launch target.\n\nAgent\n\nOne command; it appends to the targets file and preserves whatever is already there:\n\n``` text\nprompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n```\n\nOn a fresh machine `~/.prompt-builder/targets.toml` now reads exactly:\n\n``` text\n[[targets]]\nname = \"pi\"\nkind = \"pi\"\n\n[[targets]]\nname = \"codex\"\nkind = \"codex\"\n\n[[targets]]\nname = \"claude\"\nkind = \"claude\"\n\n[[targets]]\nname = \"work-profile\"\nkind = \"codex\"\n\n[targets.env]\nCODEX_HOME = \"~/.codex-work\"\n```\n\nA target is a named launch profile — binary + env + default args. A different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity; in the TUI it's just Tab to `Target ‹name›`, Space to cycle.\n\nYou\n\nAnd what would that target actually launch?\n\nAgent\n\n``` text\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\n```\n\n``` text\nCODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello\n```\n\nRead that line closely: explicit Codex targets launch with a permission-bypass flag. That is the reason dry-run comes first.\n\nThe safety beat, verbatim from the session: only point `p` at directories where you accept the selected agent modifying files and running commands. In real output the env path expands to your full home directory.\n\nYou\n\nI script against my tools. Give me the launch as data, not a string.\n\nAgent\n\n``` text\nprompt-builder --dry-run --print-launch-json \"hello\"\n```\n\n``` text\n{\n  \"schema_version\": 1,\n  \"mode\": \"pi\",\n  \"command\": \"pi\",\n  \"argv\": [\"pi\", \"hello\"],\n  \"env\": {},\n  \"prompt\": \"hello\",\n  \"pi\": {\"cwd\": \".\", \"session_name\": null}\n}\n```\n\nA stable `schema_version: 1` manifest — the same launch the TUI would perform, consumable by scripts. This is what \"the composer is inspectable\" means in practice.\n\n## Part 2 — Handoff: your shell functions become launch targets\n\nYou\n\nComposer-to-agent is fine. But my daily move is a shell function — fork my latest Codex session and resume it. Can `p` hand the composed prompt to *any* command?\n\nAgent\n\nThat's handoff mode. Proof with `/bin/echo` substituted in as the \"launcher\":\n\n``` text\nprompt-builder --submit --dry-run --handoff-command /bin/echo \"hello from handoff\"\n```\n\n``` text\n/bin/echo 'hello from handoff'\n```\n\nThe substitution proof: the composed prompt appears verbatim as the final argv element — passed as data (`Command::arg`), never through shell eval. Run this before wiring in any real command.\n\nYou\n\nMy fork helper takes flags — `--fork-from`, `--compact`. Do those survive?\n\nAgent\n\n``` text\nprompt-builder --submit --dry-run --handoff-command /bin/echo --fork-from last --compact \"continue\"\n```\n\n``` text\n/bin/echo --fork-from last --compact continue\n```\n\nThey pass through — and in the interactive TUI they render as checkbox toggles.\n\nThe wrapper declares its own UI: `--fork-from` / `--compact` / `--launch-option` become toggles in the composer. Your function's flags are now form controls.\n\nYou\n\nNow wrap it for real: bake my debugger persona into one function, and make another that composes a prompt, forks my latest Codex session, and resumes with it.\n\nAgent\n\nBoth patterns landed in one file — pattern 1 bakes instructions into the composer; pattern 2 makes your shell function the launcher:\n\n``` text\n# Wrapping \"p\" (prompt-builder) with custom tools — the two patterns.\n# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh\n# and the p-f/p-c family in your zsh config.\n\n# ── Pattern 1: bake instructions into the composer ─────────────────\n# The composer opens normally, but the launch carries your persona/context.\nfixit() {\n  prompt-builder \\\n    --target codex \\\n    -C \"$PWD\" \\\n    --developer-instructions \"You're an expert debugger who always starts with the \\$fusion skill. The user will pass a terse bug; investigate the behavior and fix it.\"\n}\n\n# ── Pattern 2: handoff mode — your shell function IS the launcher ──\n# prompt-builder composes, then calls your command with the prompt as\n# the final argv element (Command::arg, no shell eval).\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\n# Compose a prompt, then fork the latest Codex session and resume with it.\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\n# Same, but compact the forked session before resuming.\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ── The mdflow lead-in ──────────────────────────────────────────────\n# Every wrapper above is: instructions + context + a launch decision.\n# Declare that in a markdown file instead of a shell function and you\n# get an mdflow flow — reviewable, diffable, evaluable:\n#\n#   flows/fixit.codex.md\n#   ---\n#   engine: codex\n#   ---\n#   You're an expert debugger. Bug report: {{ _1 }}\n#\n# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter\n# for the fuzzy picker; flow `_inputs` render as form fields.\n```\n\nFile landed. `fixit` runs daily; `p-f` is compose → fork → resume in one keystroke family.\n\nRead the tail of that file again: every wrapper is instructions + context + a launch decision. Declare that in a markdown file instead of a shell function and you've invented mdflow — which is exactly where section 05 picks up. (`p-f` calls a private fork helper — supply your own; the pattern is the point.)"
    },
    {
      "id": "codex-context-packing-reference",
      "slug": "context-packing-reference",
      "title": "Context packing with Oracle and PackX: practical reference",
      "summary": "Documents the oracle-packx workflow: setup and verification prompts, bounded context selection, PackX preview and bundling, Oracle CLI/MCP browser execution, optional Tailscale routing, privacy exclusions, compact evidence, session-output review,…",
      "category": "Context",
      "tags": [
        "oracle",
        "packx"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Skill Reference",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Oracle Runtime Setup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Browser Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Tailscale TV Oracle Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/What The Skill Does",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/What PackX Is Doing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/What To Exclude",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Compact Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/Follow-Up Rules",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/01-oracle-packing-context.md#01. Oracle / Packing Context/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 2675,
      "url": "/topics/codex-context-packing-reference/",
      "markdownUrl": "/markdown/codex-context-packing-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-context-packing-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "skill-reference",
          "text": "Skill Reference",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "mental-model",
          "text": "Mental Model",
          "level": 2
        },
        {
          "id": "oracle-runtime-setup",
          "text": "Oracle Runtime Setup",
          "level": 2
        },
        {
          "id": "browser-mode",
          "text": "Browser Mode",
          "level": 2
        },
        {
          "id": "remote-oracle-browser-path",
          "text": "Remote Oracle Browser Path",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-the-skill-does",
          "text": "What The Skill Does",
          "level": 2
        },
        {
          "id": "what-packx-is-doing",
          "text": "What PackX Is Doing",
          "level": 2
        },
        {
          "id": "what-to-exclude",
          "text": "What To Exclude",
          "level": 2
        },
        {
          "id": "compact-evidence",
          "text": "Compact Evidence",
          "level": 2
        },
        {
          "id": "how-to-know-it-worked",
          "text": "How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "follow-up-rules",
          "text": "Follow-Up Rules",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Context packing with Oracle and PackX: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the oracle-packx skill, PackX bundle flow, Oracle browser runtime, MCP entrypoints, optional remote browser route, and local verification surfaces for this workspace.\n\n1. Resolve the oracle-packx skill. Check `skills/oracle-packx/SKILL.md` first, then `~/.agents/skills/oracle-packx/SKILL.md`. Confirm the PackX references exist under `skills/oracle-packx/references/` or the matching installed skill path. Read the skill before changing config. If the skill is missing, report the missing path and the smallest install or copy step needed; do not invent skill content.\n\n2. Verify PackX availability. Run `command -v packx || npx packx --help`. Confirm a preview command is available before building anything. Do not create a broad bundle during setup.\n\n3. Verify Oracle entrypoints. Run `command -v oracle oracle-mcp` and report both results. If either command is missing, inspect `~/dev/oracle/docs/configuration.md`, `~/dev/oracle/docs/mcp.md`, `~/dev/oracle/docs/browser-mode.md`, and `~/dev/oracle/docs/bridge.md` if present, then report the exact missing install or PATH step.\n\n4. Prepare local artifact directories. Confirm `~/.oracle/`, `~/.oracle/bundles/`, and `~/.oracle/sessions/` exist. Create only missing directories. Do not delete, overwrite, or rename existing sessions or bundles.\n\n5. Configure Oracle for deliberate browser mode. Inspect `~/.oracle/config.json` if it exists, preserving existing private values. Ensure this workflow resolves to `engine: \"browser\"`, with browser thinking set to extended, model label set to Latest, browser attachments set to always, browser file bundling enabled, and `maxFileSizeBytes` set to a reasonable upload guardrail such as `10485760`. Do not clobber unrelated config.\n\n6. Verify MCP/browser request fields. Confirm a setup run would pass or resolve these values: `engine: \"browser\"`, `browserThinkingTime: \"extended\"`, `browserModelLabel: \"Latest\"`, `browserAttachments: \"always\"`, and `browserBundleFiles: true`. Flag any condition where Oracle would fall back to API mode.\n\n7. Optional remote browser route. If remote browser routing is intended, verify the config shape without exposing values: `browser.remoteHost` should look like a Tailscale host and port, `browser.remoteToken` should be present but redacted, and `browser.remoteChrome.host` plus `browser.remoteChrome.port` should point at the remote Chrome debug bridge from the remote server's perspective. If no remote route is configured, report it as skipped.\n\n8. Enforce privacy boundaries. Never print or bundle tokens, cookies, API keys, private endpoints, raw `env` output, full private config, huge logs, generated output, `node_modules/`, `.git/`, build output, coverage output, or unrelated product areas. Confirm `CLAUDE.md` is excluded from Oracle PackX bundles. Use compact redacted notes when evidence is useful but unsafe or too large.\n\n9. Verify the PackX context flow with a tiny dry run. From a safe local project path, run a preview against a narrow path or harmless file set using the skill's PackX reference. Report file count, token count if available, and whether the scope would produce a non-empty bundle. Do not upload files to Oracle during this preview.\n\n10. Verify bundle and session surfaces. Using a short setup slug, confirm a bundle path like `~/.oracle/bundles/{slug}.txt` can be written and is non-empty if you build a tiny safe bundle. Confirm a session directory path like `~/.oracle/sessions/{slug}/` can exist, and that the expected post-run output file is `~/.oracle/sessions/{slug}/output.log`.\n\n11. If a live browser Oracle smoke test is safe and explicitly allowed by the local environment, run only a minimal browser-mode check with harmless content. Otherwise stop before sending anything and report the remaining manual check: signed-in browser availability, remote host reachability if used, and expected `output.log` location.\n\n12. Report the setup result plainly: skill path resolved, PackX status, Oracle CLI status, Oracle MCP status, directories present or created, browser-mode config status, resolved engine, remote route configured or skipped, preview result, bundle/session surface status, verification commands run, files created or changed, and anything still unproven. Redact all secrets and do not paste full config.\n```\n\n## Big Idea\n\nPhase: Context And Environment - make the software question, project boundary, and model runtime explicit before deeper work begins.\n\nUse the `oracle-packx` skill when a software question needs more context than a normal chat turn can hold, or when the answer should come from a stronger browser-backed model with a deliberate context packet.\n\n## Try This Now\n\nPick one risky software question, such as \"Why can this billing webhook double-process an invoice?\"\n\nWrite one sentence for each boundary:\n\n- in scope: likely source files, tests, logs, docs, screenshots, or prior notes\n- out of scope: generated output, secrets, unrelated product areas, broad history\n- useful answer: plan, bug theory, file-level review, first slice, or verification target\n\nAsk:\n\n```text\nUse the oracle-packx skill.\n\nBuild a bounded PackX bundle before recommending a fix. Use Oracle through\nbrowser mode. Read the full Oracle output from the local session log before\nturning it into project work.\n```\n\n## Skill Reference\n\nThe repeatable workflow lives in the bundled skill:\n\n```text\nskills/oracle-packx/SKILL.md\n```\n\nSupporting references:\n\n```text\nskills/oracle-packx/references/packx-quick-reference.md\nskills/oracle-packx/references/packx-deep-reference.md\n```\n\nA common local install path is:\n\n```text\n~/.agents/skills/oracle-packx/SKILL.md\n```\n\nOracle project reference:\n\n```text\nhttps://github.com/johnlindquist/oracle\n```\n\nPackX package and reference:\n\n```text\nhttps://www.npmjs.com/package/packx\nhttps://github.com/johnlindquist/pack#readme\n```\n\n## When To Reach For This\n\nUse `oracle-packx` when you are asking for:\n\n- architecture review across several files or packages\n- an implementation plan for a feature with real source context\n- cross-file debugging where the failure path spans source, tests, logs, and config\n- a second opinion before touching a risky subsystem\n- review of a failed implementation after you have logs or test output\n- a broad code review where local inspection alone is not enough\n- a browser-backed Oracle run that should use a signed-in ChatGPT/Gemini session instead of a normal API call\n\nSkip it when:\n\n- `rg` can answer the question\n- one test failure points at one obvious file\n- you already know the exact edit\n- the task is small enough for a normal Codex turn\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nPaste a broad prompt and trust the model to infer the right files.\n```\n\nWhat this workflow gives you now:\n\n```text\nGive oracle-packx a specific software question. It builds a bounded context\npacket first, then Oracle reasons over the code, docs, logs, and evidence that\nactually matter.\n```\n\n## Mental Model\n\nThere are three pieces:\n\n| Piece | Job |\n| --- | --- |\n| `oracle-packx` | Workflow wrapper: choose scope, preview PackX, build the bundle, call Oracle, read the result, apply it locally |\n| PackX | Context bundler: collect, filter, count, and write source context into an LLM-friendly packet |\n| Oracle | Model runner: CLI/MCP tool that can use API mode or browser mode, then save session output locally |\n\nDo not blur those together. PackX prepares the context. Oracle reasons over it. The agent still owns local edits and verification.\n\n## Oracle Runtime Setup\n\nOracle can run from the CLI or from the MCP tool.\n\nCommon entrypoints:\n\n```text\noracle\noracle-mcp\n```\n\nThe project includes browser-mode code, MCP tools, remote-browser routing, session storage, and launch helpers.\n\nUseful project files to inspect:\n\n```text\n~/dev/oracle/docs/browser-mode.md\n~/dev/oracle/docs/configuration.md\n~/dev/oracle/docs/mcp.md\n~/dev/oracle/docs/bridge.md\n~/dev/oracle/src/mcp/server.ts\n~/dev/oracle/src/mcp/tools/consult.ts\n~/dev/oracle/src/mcp/tools/sessions.ts\n~/dev/oracle/src/mcp/tools/sessionResources.ts\n~/dev/oracle/src/config.ts\n~/dev/oracle/src/remote/client.ts\n~/dev/oracle/src/remote/server.ts\n~/dev/oracle/src/browser/index.ts\n~/dev/oracle/scripts/oracle-serve-launchagent.sh\n```\n\nOracle session output is saved under:\n\n```text\n~/.oracle/sessions/{slug}/\n```\n\nFor `oracle-packx`, the main file to read after the run is normally:\n\n```text\n~/.oracle/sessions/{slug}/output.log\n```\n\n## Browser Mode\n\nBrowser mode sends the request through an automated signed-in browser session instead of the normal API path.\n\nUse it when the answer should come from ChatGPT/Gemini web capabilities, attached files, a visible remote browser, or a browser-only model surface.\n\nCritical MCP fields:\n\n```text\nengine: \"browser\"\nbrowserThinkingTime: \"extended\"\nbrowserModelLabel: \"Latest\"\n```\n\nWhy `engine: \"browser\"` matters:\n\n- Oracle can choose a default engine from config.\n- If API credentials exist, API mode may be available.\n- A deliberate browser run should not accidentally become an API run.\n\nBrowser attachment controls:\n\n```text\nbrowserAttachments: \"always\"\nbrowserBundleFiles: true\n```\n\nUse `browserAttachments: \"always\"` when files must be uploaded through the browser UI. Use bundling when many files should travel as one uploaded context artifact.\n\n## Remote Oracle Browser Path\n\nA common remote setup uses a Tailscale-reachable Oracle browser host. This lets the local agent send the job while the remote machine drives an already signed-in browser session, often visible on a TV or second display.\n\nThe path looks like this:\n\n```text\nlocal Codex / agent\n  -> Oracle MCP consult or oracle CLI\n  -> browser engine\n  -> browser.remoteHost over Tailscale\n  -> remote oracle serve process\n  -> remoteChrome on the remote host\n  -> signed-in ChatGPT/Gemini browser\n  -> local ~/.oracle/sessions/{slug}/ output\n```\n\nRedacted config shape:\n\n```json\n{\n  \"engine\": \"browser\",\n  \"browser\": {\n    \"remoteHost\": \"100.x.y.z:7333\",\n    \"remoteToken\": \"<redacted>\",\n    \"remoteChrome\": {\n      \"host\": \"127.0.0.1\",\n      \"port\": 55894\n    }\n  },\n  \"maxFileSizeBytes\": 10485760\n}\n```\n\nWhat each field means:\n\n| Field | Meaning |\n| --- | --- |\n| `engine` | Default Oracle runtime mode |\n| `browser.remoteHost` | Tailscale-reachable Oracle remote server |\n| `browser.remoteToken` | Bearer-style token required by the remote server |\n| `browser.remoteChrome.host` | Chrome debugging host from the remote server's point of view |\n| `browser.remoteChrome.port` | Chrome debugging port on the remote machine |\n| `maxFileSizeBytes` | Local upload guardrail for files sent to browser mode |\n\nThe token is private. Do not paste it into prompts, bundles, pages, logs, or screenshots.\n\n## Ask The Agent This\n\nGeneral review:\n\n```text\nUse the oracle-packx skill.\n\nReview the auth/session architecture before we add refresh-token rotation.\nBuild a focused PackX bundle from the auth package, session storage code,\nmiddleware, relevant tests, and existing ADRs. Exclude secrets, generated\noutput, node_modules, and unrelated product areas.\n\nAsk Oracle through browser mode for risks, a migration plan, file-level changes,\nverification checks, rollback notes, and the first shippable slice. Read the\nfull Oracle session output before editing local files.\n```\n\nDebugging:\n\n```text\nUse the oracle-packx skill.\n\nThe billing webhook intermittently double-processes an invoice. Bundle the\nwebhook handler, idempotency code, tests, payment-provider docs, and the latest\nfailure log. Ask Oracle through browser mode to identify likely causes, missing\ninvariants, and the smallest local check that would confirm the fix.\n```\n\nRemote browser setup check:\n\n```text\nUse the oracle-packx skill.\n\nInspect the local Oracle config and explain whether browser mode will route to a\nremote Tailscale Oracle host. Redact tokens and private host details. Confirm the\nengine choice, remoteHost shape, remoteChrome target, file-size guardrail, and\nwhere the session output will be saved.\n```\n\nKeep the bundle tight:\n\n```text\nUse the oracle-packx skill.\n\nStart with a PackX preview. If the bundle is too broad, narrow by package,\nentrypoint, git diff, or relevant search terms before consulting Oracle. Do not\nsend secrets, generated files, private env output, or raw huge logs.\n```\n\n## What The Skill Does\n\nThe `oracle-packx` skill runs this pipeline:\n\n1. Choose a short slug.\n2. Preview the PackX bundle before building it.\n3. Build a rich bundle, often targeting up to `900k` tokens for broad review.\n4. Confirm the bundle exists and is non-empty.\n5. Add compact evidence when raw logs or sessions are too large or unsafe.\n6. Send the bundle to Oracle through browser mode only.\n7. Use ChatGPT Pro Extended or equivalent browser thinking controls.\n8. Wait for Oracle instead of doing parallel local work.\n9. Read the full answer from `~/.oracle/sessions/{slug}/output.log`.\n10. Turn Oracle's answer into local implementation work.\n11. Write local plans, notes, code, or verification logs with local tools.\n\n## What PackX Is Doing\n\nPackX discovers files, applies ignore rules, filters by path/content/git state, optionally strips comments or minifies, counts tokens, and writes an LLM-friendly bundle.\n\nCommon PackX capabilities used by the skill:\n\n| Capability | What It Means |\n| --- | --- |\n| `--preview` | Dry run before building the bundle |\n| `--limit 900k` | Rich bundle target for broad Oracle review |\n| `-x` / `--exclude` | Leave out noise or unsafe files |\n| `-i` / `--include` | Include specific path/glob patterns |\n| `-s` / `--strings` | Find files containing relevant text |\n| `--diff` / `--dirty` / `--staged` | Focus on changed files |\n| `--follow-imports` | Start from an entrypoint and include local imports |\n| `--skeleton` | Send API/interface shape without full bodies |\n| `--strip-comments --minify` | Fit large projects into the bundle |\n| `-f markdown --no-interactive --stdout` | Scriptable output shape for Oracle |\n\nUse these flags conceptually. The exact combinations live in the skill and quick reference.\n\n## What To Exclude\n\nThe skill explicitly excludes `CLAUDE.md` from Oracle PackX bundles.\n\nWhy:\n\n- it may contain tool-specific or agent-specific instructions\n- it can confuse the Oracle review with instruction noise\n- repo guidance should be deliberately scoped\n\nPrefer a scoped `AGENTS.md`, project README, ADR, or short local summary when instructions are needed.\n\nAlso keep these out unless there is a deliberate reason:\n\n```text\nnode_modules/\n.git/\ndist/\nbuild/\n.next/\ncoverage/\n*.log\nlockfiles\nraw env output\ntokens\ncookies\nprivate endpoints\n```\n\nLogs can still be included intentionally when they are small and directly relevant. Large logs should usually become compact evidence.\n\n## Compact Evidence\n\nUse compact evidence when the raw material is useful but too noisy, too large, or unsafe to bundle directly.\n\nExamples:\n\n- a giant failure log\n- previous session history\n- screenshot observations\n- browser trace summary\n- CI output with many unrelated lines\n- a redacted production incident note\n- redacted Oracle config details\n- a failed PackX preview that proved the first scope was too broad\n\nShape:\n\n```markdown\n# Compact Evidence Supplement\n\n## Useful Facts\n\n- fact:\n- source path:\n- why it matters:\n\n## Raw Context Intentionally Omitted\n\n- path:\n- omitted because:\n\n## Current Narrowing\n\n- next slice:\n- out of scope:\n- how to confirm:\n```\n\n## How To Know It Worked\n\nAfter the skill runs, look for:\n\n- a non-empty bundle at `~/.oracle/bundles/{slug}.txt`\n- an Oracle session at `~/.oracle/sessions/{slug}/`\n- a full session output file, normally `output.log`\n- browser mode noted in the run, not accidental API mode\n- remote-browser routing redacted when config is discussed\n- exact file/function/test targets in the plan\n- risks and assumptions called out explicitly\n- a first shippable slice, not just a broad roadmap\n- local files written by the agent, not downloadable files created by Oracle\n\n## If It Goes Wrong\n\n| Symptom | Likely Cause | What To Do |\n| --- | --- | --- |\n| Oracle used API mode | `engine: \"browser\"` was omitted or config default changed | Re-run with explicit browser engine |\n| Browser did not open | Browser automation or remote host is unavailable | Check local Oracle config and browser-mode docs |\n| Remote host unreachable | Tailscale, host, port, or remote server is down | Confirm the `100.x.y.z:port` route and remote `oracle serve` process |\n| Token rejected | Remote token mismatch | Rotate or fix the token outside the bundle and prompt |\n| Remote Chrome unavailable | Debug port or Chrome session is not running on the remote host | Restart the remote Chrome/debug bridge or launch helper |\n| File upload rejected | Bundle or attachment exceeded guardrails | Narrow PackX scope, use compact evidence, or bundle fewer files |\n| Bundle is huge | Scope was too broad | Preview again with tighter includes, excludes, strings, diff, or entrypoints |\n| Bundle is empty | Include patterns missed the actual files | Run `rg`, inspect paths, and rebuild |\n| Oracle answer is vague | Context packet lacked logs, tests, or target question | Add compact evidence and ask for a falsifiable first check |\n| Sensitive data appears | Secrets or raw env output slipped in | Stop, remove the bundle, rebuild with redaction |\n\n## Follow-Up Rules\n\nOracle's answer is input, not the finished work.\n\nAfter reading it:\n\n- restate the useful recommendation in local project terms\n- identify the first file or test to touch\n- keep unrelated refactors out\n- run the smallest meaningful verification\n- save what changed and what remains unproven\n- use another PackX/Oracle pass only after forward progress or new evidence\n\nWhen returning to Oracle, include the delta:\n\n```text\n- prior_oracle_session:\n- last_oracle_recommendation:\n- implemented_since_prior_oracle:\n- verified_since_prior_oracle:\n- failed_check_or_blocker:\n- narrowing_decision:\n- files_functions_now_in_scope:\n- files_functions_out_of_scope:\n- next_falsifiable_verification:\n```\n\n## References And Resources\n\n```text\nskills/oracle-packx/SKILL.md\nskills/oracle-packx/references/packx-quick-reference.md\nskills/oracle-packx/references/packx-deep-reference.md\n~/dev/oracle/docs/browser-mode.md\n~/dev/oracle/docs/configuration.md\n~/dev/oracle/docs/mcp.md\n~/dev/oracle/docs/bridge.md\n~/.oracle/config.json\n~/.oracle/bundles/{slug}.txt\n~/.oracle/sessions/{slug}/output.log\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-context-packing-practice",
      "slug": "context-packing-practice",
      "title": "Context packing with Oracle and PackX: practice drills",
      "summary": "Six exercises cover explicit oracle-packx invocation, evidence mapping, raw-versus-compact evidence decisions, improving vague requests, gating follow-up Oracle calls with a prior-state ledger, and inspecting the published skill's safeguards.",
      "category": "Context",
      "tags": [
        "oracle",
        "packx",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 1: Write A Skill Invocation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 2: Identify Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 3: Decide What Should Be Compact Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 4: Review A Bad Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 5: Plan A Follow-Up Oracle Call",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/01-oracle-packing-context.md#Exercises: 01. Oracle / Packing Context/Exercise 6: Inspect The Skill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 462,
      "url": "/topics/codex-context-packing-practice/",
      "markdownUrl": "/markdown/codex-context-packing-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-context-packing-practice.json",
      "headings": [
        {
          "id": "exercise-1-write-a-skill-invocation",
          "text": "Exercise 1: Write A Skill Invocation",
          "level": 2
        },
        {
          "id": "exercise-2-identify-evidence",
          "text": "Exercise 2: Identify Evidence",
          "level": 2
        },
        {
          "id": "exercise-3-decide-what-should-be-compact-evidence",
          "text": "Exercise 3: Decide What Should Be Compact Evidence",
          "level": 2
        },
        {
          "id": "exercise-4-review-a-bad-prompt",
          "text": "Exercise 4: Review A Bad Prompt",
          "level": 2
        },
        {
          "id": "exercise-5-plan-a-follow-up-oracle-call",
          "text": "Exercise 5: Plan A Follow-Up Oracle Call",
          "level": 2
        },
        {
          "id": "exercise-6-inspect-the-skill",
          "text": "Exercise 6: Inspect The Skill",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Context packing with Oracle and PackX: practice drills\n\nThese exercises practice asking for the `oracle-packx` skill clearly. They do not require team members to memorize PackX or Oracle command syntax.\n\n## Exercise 1: Write A Skill Invocation\n\nPick a real software project, feature, or bug.\n\nWrite a prompt that starts with:\n\n```text\nUse the oracle-packx skill.\n```\n\nInclude:\n\n- desired software outcome\n- feature/module/subsystem in scope\n- source paths that probably matter\n- tests or logs that probably matter\n- docs or provider references that probably matter\n- files or areas to exclude\n- how you will know the answer is useful\n\nTemplate:\n\n```text\nUse the oracle-packx skill.\n\nI want to:\n\nRelevant code is probably in:\n\nRelevant tests/logs/docs are probably:\n\nExclude:\n\nAsk Oracle for:\n\nI will know this worked if:\n```\n\n## Exercise 2: Identify Evidence\n\nFor the same project, list what should go into the context packet.\n\n```markdown\n# Evidence Map\n\n## Source\n\n- path:\n- why it matters:\n\n## Tests\n\n- path:\n- why it matters:\n\n## Logs Or Failures\n\n- path:\n- why it matters:\n\n## Docs Or External Contracts\n\n- path or URL:\n- why it matters:\n\n## Out Of Scope\n\n- path/topic:\n- why excluded:\n```\n\n## Exercise 3: Decide What Should Be Compact Evidence\n\nSome material is useful but should not be packed raw.\n\nMark each item as `pack raw`, `summarize`, or `exclude`:\n\n```markdown\n# Compact Evidence Decisions\n\n- 30,000-line CI log:\n- screenshot of broken UI:\n- `.env.local`:\n- payment provider API docs:\n- one failing test output:\n- previous Oracle output:\n- entire session history:\n- generated build directory:\n```\n\n## Exercise 4: Review A Bad Prompt\n\nBad:\n\n```text\nUse Oracle to review my repo and tell me what to do.\n```\n\nRewrite it so the `oracle-packx` skill has enough direction:\n\n```text\nUse the oracle-packx skill.\n\n...\n```\n\nMake sure your rewrite includes:\n\n- exact project area\n- expected outcome\n- likely evidence\n- exclusions\n- what Oracle should return\n- how local work will be confirmed\n\n## Exercise 5: Plan A Follow-Up Oracle Call\n\nA second Oracle call should not repeat the same broad question.\n\nFill this out before asking again:\n\n```text\nPrior-State Ledger:\n- prior_oracle_session:\n- last_oracle_recommendation:\n- implemented_since_prior_oracle:\n- verified_since_prior_oracle:\n- failed_proof_or_blocker:\n- narrowing_decision:\n- files_functions_now_in_scope:\n- files_functions_out_of_scope:\n- next_falsifiable_verification:\n- forward_progress_index:\n```\n\nDecide which condition is true:\n\n```text\nimplemented:\nverified:\nblocked:\nnarrowed:\n```\n\nIf none are true, do local work before another Oracle run.\n\n## Exercise 6: Inspect The Skill\n\nOpen:\n\n```text\nskills/oracle-packx/SKILL.md\n```\n\nFind the sections that define:\n\n- runtime mode\n- PackX pipeline\n- compact evidence\n- `output.log`\n- follow-up call requirements\n- completion checklist\n\nWrite one sentence about what each section protects you from.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-goal-memory-field-guide",
      "slug": "goal-memory-field-guide",
      "title": "Goal, Memory, and Context Hygiene Field Guide",
      "summary": "Keep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.",
      "category": "Context",
      "tags": [
        "field guide",
        "goal memory"
      ],
      "sources": [
        {
          "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
        },
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        },
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#goal-memory/overview",
        "field-guides/guides.mjs#goal-memory/decision",
        "field-guides/guides.mjs#goal-memory/agentPrompt",
        "field-guides/guides.mjs#goal-memory/stories",
        "field-guides/guides.mjs#goal-memory/tips",
        "field-guides/guides.mjs#goal-memory/refs"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 393,
      "url": "/topics/foundations-goal-memory-field-guide/",
      "markdownUrl": "/markdown/foundations-goal-memory-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-goal-memory-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "goal-that-will-not-converge",
          "text": "Goal that will not converge",
          "level": 3
        },
        {
          "id": "memory-drift-cleanup",
          "text": "Memory drift cleanup",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Goal, Memory, and Context Hygiene Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nKeep long-running Codex work grounded with local files, compact prompts, and receipt checkpoints.\n\nUse this when /goal work burns tokens, drifts, or cannot converge because context is not being externalized.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| .goals/ | Durable objective and checkpoints | Long-running work | .goals/<task>.md |\n| .notes/ | Receipts and scratch state | Verification, logs, decisions | .notes/<task>/ |\n| Grill-me | Clarify before a big goal | Ambiguous or risky scope | .notes/<task>/questions.md |\n| Compact summaries | Keep Codex in the useful zone | Large sessions and repeated loops | .notes/<task>/handoff.md |\n\n## Agent-ready prompt\n\n```text\nBefore starting this goal, externalize state.\nCreate .goals/<task>.md with objective, constraints, stop condition, and verification.\nCreate .notes/<task>/ for receipts.\nEvery major phase must write a checkpoint: research, plan, implementation, verification, final diff review.\nIf context gets large, compact to .notes/<task>/handoff.md and resume from that artifact.\n```\n\n## Applied stories\n\n### Goal that will not converge\n\n**Role:** Solo developer\n\nCodex keeps exploring alternatives and never ships.\n\n**Agent brief:** Narrow to one shippable slice, write explicit stop condition, and require a verification receipt before continuing.\n\n**Done when:**\n\n- goal file\n- single next slice\n- verification command\n- final receipt\n\n### Memory drift cleanup\n\n**Role:** Repo maintainer\n\nAgent memory says old commands are true, but package scripts changed.\n\n**Agent brief:** Audit memories against package.json/CI, write corrections to local notes, and update durable instructions only after verification.\n\n**Done when:**\n\n- memory audit\n- verified commands\n- updated AGENTS.md or skill\n- stale facts removed\n\n## Tips and gotchas\n\n- Use local markdown as the durable memory for a task; do not rely on hidden conversational state.\n- Ask for numbered options with a recommended pick when you need to steer quickly.\n- Treat /goal as research + plan + implement + verify in one bounded loop, not infinite autoresearch.\n- Use compact summaries when receipts are better than raw chat history.\n\n## References\n\n- [Grill Me skill](https://www.aihero.dev/skills-grill-me)\n- [Beads](https://github.com/gastownhall/beads)\n- [Caveman](https://github.com/JuliusBrussee/caveman)\n\n## Related principles\n\n- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n- [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
    },
    {
      "id": "factory-image-prompts",
      "slug": "image-prompts",
      "title": "Images as precise task evidence",
      "summary": "Use a marked screenshot to identify the target, a sentence to express intent, and a running-app check to prove the change.",
      "category": "Context",
      "tags": [
        "image",
        "factory"
      ],
      "sources": [
        {
          "label": "Images as precise task evidence",
          "url": "https://amber-willow-n64j.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt"
        }
      ],
      "sourceUnits": [
        "03-images/index.html#TL;DR",
        "03-images/index.html#Why one arrow beats a paragraph",
        "03-images/index.html#Appendix",
        "03-images/index.html#How agents ingest the drop",
        "03-images/index.html#What good captures look like",
        "03-images/index.html#Check what leaves your machine",
        "learn.html#q2-annotated-image-prompt"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1223,
      "url": "/topics/factory-image-prompts/",
      "markdownUrl": "/markdown/factory-image-prompts.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-image-prompts.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "why-one-arrow-beats-a-paragraph",
          "text": "Why one arrow beats a paragraph",
          "level": 2
        },
        {
          "id": "how-agents-ingest-the-drop",
          "text": "How agents ingest the drop",
          "level": 2
        },
        {
          "id": "what-good-captures-look-like",
          "text": "What good captures look like",
          "level": 2
        },
        {
          "id": "check-what-leaves-your-machine",
          "text": "Check what leaves your machine",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "point-at-the-visual-problem",
          "text": "Point at the visual problem",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Images as precise task evidence\n\nUse a marked screenshot to identify the target, a sentence to express intent, and a running-app check to prove the change.\n\n## Related working material\n\n- [Images as precise task evidence — prompts and exercises](/topics/factory-image-prompts-practice/)\n- [Images as precise task evidence — questions and tradeoffs](/topics/factory-image-prompts-questions/)\n- [Images as precise task evidence — worked example](/topics/factory-image-prompts-worked-example/)\n\n## TL;DR\n\n- A capture→annotate→drop workflow: CleanShot hotkey, one fat red arrow, drag the image straight into the agent prompt.\n- You walk away with five copy-paste prompt shapes — including the two real prompts where a screenshot plus one sentence drove a bug fix all the way to a pull request.\n- The one move: when a prompt sentence starts describing a screen location (\"the row near the bottom…\"), stop typing and hit the capture hotkey instead.\n\n Have your agent adopt this — paste this into it:\n\n``` text\nFetch https://amber-willow-n64j.here.now/agent.md?raw and follow it to set up the screenshot-reading protocol in my current project. Run the success check at the end and show me the result.\n```\n\n## Why one arrow beats a paragraph\n\nSay your app's launcher sometimes moves focus to the wrong row while you type. Describe that in words alone — \"when I type in the menu, the selection sometimes jumps down to another item\" — and the agent must guess: which menu? which item? at what moment? A real session skipped the guessing: the entire bug report was the annotated screenshot in card 1 plus one sentence, and the session chained investigation, an external model consult, the fix, live verification in the running app, a commit, and a pull request.\n\nThe division of labor is simple. The arrow answers \"which element?\" The sentence answers \"what do you want done?\" Neither carries the other's job well: an arrow cannot express intent; a sentence cannot point. CleanShot's text tool collapses the two when that helps — card 3's capture carries the full design feedback as a red callout typed on the image, so the prompt shrinks to \"do what the annotation says.\"\n\nWeak version of the move: three arrows, two boxes, and a highlight on one screenshot — the agent now has five candidate subjects. Strong version: one fat arrow per idea. Two ideas, two screenshots. Crop tight.\n\n## How agents ingest the drop\n\nDifferent CLIs render a dropped image differently, but all of them get the pixels. Claude Code shows an inline `[Image #1]` marker. The Codex CLI rewrites a dragged file into a header:\n\n``` text\n# Files mentioned by the user:\n## capture.png:\n$HOME/screenshots/capture.png\n```\n\nThe difference only matters when you script prompts; drag-and-drop hides it. And the image is data, not decoration — one session opened with just a file path plus \"It is a 1612×1084 RGBA PNG. The visible symptom is…\" and the agent read the actual pixels.\n\n## What good captures look like\n\nAcross a reviewed week of ~45 captures, the annotated ones share one pattern: a single fat red arrow aimed at the one element the prompt is about — an input field, a status widget, an answer sentence. Almost never boxes or long callouts.\n\n![A Quick AI chat panel answering a World Cup schedule question, with a red arrow pointing at the empty 'Follow up…' input field at the top.](https://amber-willow-n64j.here.now/images/arrow-quick-ai-input.png)\n\nThe arrow singles out the follow-up input the prompt discussed, ignoring everything else on screen.\n\n![A terminal running Claude Code inside a coding project. A red arrow points at two small pill-shaped 'now' widgets floating in the center of an otherwise empty pane.](https://amber-willow-n64j.here.now/images/arrow-claude-code-pills.png)\n\nApplied to the agent's own UI: the arrow isolates two tiny status pills inside a busy terminal session.\n\n![A Quick AI panel showing eight web_search tool calls and an answer that begins 'I can't reliably pull today's latest news headlines from live sources right now'. A red arrow points at the answer text.](https://amber-willow-n64j.here.now/images/arrow-web-search-answer.png)\n\nFeedback aimed at agent behavior itself: the arrow marks the answer sentence under discussion, so the follow-up prompt can be one line.\n\nJudge success by the agent's first reply: it should name your arrow's target unprompted. If it misidentifies the target, don't add prose — crop tighter, keep one arrow, resend. Capture the *failure state*, not the app in general.\n\n## Check what leaves your machine\n\nScreenshots leak. The same week of captures that produced the five images on this page also contained personal message threads, a contact list with real names, a member directory, and personal photos — the same hotkey captured them all, and all of them were excluded here. An agent prompt is already a disclosure: everything visible in the frame — window titles, file paths, browser tabs, notification banners — goes to whatever service runs the model. Review the whole frame before you press send, and again, more strictly, before anything gets published. If a capture shows another person's data, re-take it rather than blurring it.\n\n## Appendix\n\n### Limits & caveats\n\n- The two real sessions are single successful runs, not controlled comparisons. No prose-only version of the same bug report was tried, so \"the arrow made the difference\" is a reasoned inference from the prompt's brevity, not a measurement.\n- The \"first reply names the arrow's target\" success test is an editorial rule of thumb, not something the sources measured.\n- The real prompts in cards 1–2 invoke the author's local slash commands (`/goal`, `/oracle-packx`, `/web-choices`) and card 5 uses a local `$image_gen` command — you won't have these. The portable versions remove them; that light generalization is the only edit.\n- The quick start and helper script assume macOS (CleanShot, `pbcopy`) and a capture folder at `~/screenshots`; set `CLEANSHOT_DIR` if CleanShot exports elsewhere.\n- Evidence is one developer's capture folder and session history over one week . It shows the workflow working; it does not measure it against alternatives.\n- Privacy exclusions, kept deliberately: personal Messages conversations, a contact list, a member-directory page, and personal photos from the same capture folder are described but never shown. Session ids and home paths are redacted in text; the five published images show only public app UIs and `~/dev`-style paths.\n- A published page is public and may be cached or indexed even if later deleted — the privacy bar for publishing is higher than for prompting.\n\n## Operating practice\n\n### Point at the visual problem\n\n#### What to notice\n\nReplace vague design prose with an **annotated image**, a bounded target, and a visible success condition.\n\n#### Try this\n\nMark the **smallest visual defect**, name what must remain unchanged, and ask for one observable correction.\n\n> “Screenshot, draw an arrow, or multiple arrows, and then paste.”\n\nJohn Lindquist · [02:18:19](https://proud-anchor-53zn.here.now/watch.html?t=8299#recording-player)\n\n#### Concept\n\nImages carry layout evidence that text often loses. Keep the request narrow: target, constraint, expected result, and one check at the viewport where the problem appears.\n\n#### Reflection\n\nAn image can show a symptom without proving its cause. Ask the agent to inspect the implementation before choosing a fix.\n\n**Recording evidence:** listen at 02:15:42.\n\n> “Please, after you're done generating the HTML, take a screenshot of the page and compare the two, so you get a diff.”\n\nJohn Lindquist · [02:21:37](https://proud-anchor-53zn.here.now/watch.html?t=8497#recording-player)\n\n[Open Prompting with Images](https://amber-willow-n64j.here.now/)\n\n#### Links shared for this topic\n\n- [Flameshot](https://flameshot.org/) — Cross-platform screenshot and annotation tooling.\n- [Shottr](https://shottr.cc/) — A macOS screenshot and annotation tool.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=8142#q2-annotated-image-prompt)"
    },
    {
      "id": "factory-image-prompts-discussion",
      "slug": "image-prompts-discussion",
      "title": "Images as precise task evidence — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Context",
      "tags": [
        "image-prompts",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[80]",
        "resource-manifest.json#videoEvidence.concepts[81]",
        "resource-manifest.json#videoEvidence.concepts[82]",
        "resource-manifest.json#videoEvidence.concepts[83]",
        "resource-manifest.json#videoEvidence.concepts[84]",
        "resource-manifest.json#videoEvidence.concepts[85]",
        "resource-manifest.json#videoEvidence.concepts[86]",
        "resource-manifest.json#videoEvidence.concepts[87]",
        "resource-manifest.json#videoEvidence.concepts[88]",
        "resource-manifest.json#videoEvidence.concepts[89]",
        "resource-manifest.json#videoEvidence.concepts[90]",
        "resource-manifest.json#videoEvidence.concepts[91]",
        "resource-manifest.json#videoEvidence.concepts[92]",
        "resource-manifest.json#videoEvidence.concepts[93]",
        "resource-manifest.json#videoEvidence.concepts[94]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[29]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[30]",
        "resource-manifest.json#videoEvidence.exercises[8]",
        "resource-manifest.json#videoEvidence.timeline[379]",
        "resource-manifest.json#videoEvidence.timeline[380]",
        "resource-manifest.json#videoEvidence.timeline[381]",
        "resource-manifest.json#videoEvidence.timeline[383]",
        "resource-manifest.json#videoEvidence.timeline[384]",
        "resource-manifest.json#videoEvidence.timeline[385]",
        "resource-manifest.json#videoEvidence.timeline[387]",
        "resource-manifest.json#videoEvidence.timeline[388]",
        "resource-manifest.json#videoEvidence.timeline[389]",
        "resource-manifest.json#videoEvidence.timeline[390]",
        "resource-manifest.json#videoEvidence.timeline[391]",
        "resource-manifest.json#videoEvidence.timeline[392]",
        "resource-manifest.json#videoEvidence.timeline[393]",
        "resource-manifest.json#videoEvidence.timeline[396]",
        "resource-manifest.json#videoEvidence.timeline[398]",
        "resource-manifest.json#videoEvidence.timeline[402]",
        "resource-manifest.json#videoEvidence.timeline[403]",
        "resource-manifest.json#videoEvidence.timeline[406]",
        "resource-manifest.json#videoEvidence.timeline[408]",
        "resource-manifest.json#videoEvidence.timeline[411]",
        "resource-manifest.json#videoEvidence.timeline[417]",
        "resource-manifest.json#videoEvidence.timeline[420]",
        "resource-manifest.json#videoEvidence.timeline[422]",
        "resource-manifest.json#videoEvidence.timeline[423]",
        "resource-manifest.json#videoEvidence.timeline[425]",
        "resource-manifest.json#videoEvidence.timeline[426]",
        "resource-manifest.json#videoEvidence.timeline[427]",
        "resource-manifest.json#videoEvidence.timeline[428]",
        "resource-manifest.json#videoEvidence.timeline[429]",
        "resource-manifest.json#videoEvidence.timeline[430]",
        "resource-manifest.json#videoEvidence.timeline[431]",
        "resource-manifest.json#videoEvidence.timeline[432]",
        "resource-manifest.json#videoEvidence.timeline[433]",
        "resource-manifest.json#videoEvidence.timeline[434]",
        "resource-manifest.json#videoEvidence.uncertainties[27]",
        "resource-manifest.json#videoEvidence.uncertainties[28]",
        "resource-manifest.json#videoEvidence.demos[45]",
        "resource-manifest.json#videoEvidence.demos[46]",
        "resource-manifest.json#videoEvidence.demos[47]",
        "resource-manifest.json#videoEvidence.demos[48]",
        "resource-manifest.json#videoEvidence.demos[49]",
        "resource-manifest.json#videoEvidence.demos[50]",
        "resource-manifest.json#videoEvidence.demos[51]",
        "resource-manifest.json#videoEvidence.demos[52]"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1837,
      "url": "/topics/factory-image-prompts-discussion/",
      "markdownUrl": "/markdown/factory-image-prompts-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-image-prompts-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "prompting-with-images",
          "text": "Prompting with Images",
          "level": 3
        },
        {
          "id": "screen-annotation-workflow",
          "text": "Screen Annotation Workflow",
          "level": 3
        },
        {
          "id": "visual-prompting-multimodal-input",
          "text": "Visual Prompting / Multimodal Input",
          "level": 3
        },
        {
          "id": "before-after-conversation-artifacts",
          "text": "Before/After Conversation Artifacts",
          "level": 3
        },
        {
          "id": "image-diffing",
          "text": "Image Diffing",
          "level": 3
        },
        {
          "id": "arrow-to-text-to-action-workflow",
          "text": "Arrow-to-Text-to-Action Workflow",
          "level": 3
        },
        {
          "id": "code-review-artifact-generator",
          "text": "Code Review Artifact Generator",
          "level": 3
        },
        {
          "id": "context-aware-automation-script-kit",
          "text": "Context-Aware Automation (Script Kit)",
          "level": 3
        },
        {
          "id": "information-architecture-information-ux",
          "text": "Information Architecture / Information UX",
          "level": 3
        },
        {
          "id": "commit-hooks-push-gates",
          "text": "Commit Hooks / Push Gates",
          "level": 3
        },
        {
          "id": "gpui-framework",
          "text": "GPUI Framework",
          "level": 3
        },
        {
          "id": "commit-hooks",
          "text": "Commit Hooks",
          "level": 3
        },
        {
          "id": "cargo-crate-disk-space-management",
          "text": "Cargo Crate Disk Space Management",
          "level": 3
        },
        {
          "id": "visual-prompting-prompting-with-images",
          "text": "Visual Prompting / Prompting with Images",
          "level": 3
        },
        {
          "id": "gpui-framework-2",
          "text": "GPUI Framework",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "what-is-the-arrow-pointing-to",
          "text": "--- What is the arrow pointing to?",
          "level": 3
        },
        {
          "id": "a-participant-when-you-say-commit-gate-what-does-that-translate-to",
          "text": "a participant: 'When you say commit gate, what does that translate to?'",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-the-exact-application-layout-type-running-at-02-26-28-550",
          "text": "Unresolved: The exact application layout type running at 02:26:28.550.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-hosting-deployment-or-resolution-path-of-the-changelog-site-interface",
          "text": "Unresolved: The exact hosting deployment or resolution path of the changelog site interface.",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-17-10",
          "text": "Demonstration detail: 02:17:10",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-19-28",
          "text": "Demonstration detail: 02:19:28",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-20-37",
          "text": "Demonstration detail: 02:20:37",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-23-21",
          "text": "Demonstration detail: 02:23:21",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-25-21",
          "text": "Demonstration detail: 02:25:21",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-27-04",
          "text": "Demonstration detail: 02:27:04",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-28-10",
          "text": "Demonstration detail: 02:28:10",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-31-35",
          "text": "Demonstration detail: 02:31:35",
          "level": 3
        }
      ],
      "markdown": "# Images as precise task evidence — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Prompting with Images\n\nUsing annotated visual context (such as screenshots with hand-drawn arrows) to precisely identify specific components or UI sections when prompting vision-capable large language models or software agents.\n\n### Screen Annotation Workflow\n\nA design/development shortcut involving a localized area capture tool that supports instant vector overlays (arrows, rectangles), streamlining the communication of UI components to an AI model with minimal steps.\n\n### Visual Prompting / Multimodal Input\n\nSupplying an LLM or autonomous agent with annotated screenshots containing simple drawings like arrows to establish spatial or element context instead of relying entirely on raw string selectors.\n\n### Before/After Conversation Artifacts\n\nRetaining original and updated web element screenshots inside chat history logs to allow easy visual diffs or visual reference verification by both the user and the agent.\n\n### Image Diffing\n\nAutomated pixel or feature-based comparison between an output page layout and the intended design asset to verify code correctness.\n\n### Arrow-to-Text-to-Action Workflow\n\nA technique using visually annotated screenshots (with arrows, shapes, and minimal text) to define tasks or movement trajectories for automated agents or video generators.\n\n### Code Review Artifact Generator\n\nAn automated AI pipeline that scans recent commits and generates a comprehensive, formatted report detailing security alerts, topology changes, and executive summaries.\n\n### Context-Aware Automation (Script Kit)\n\nEmpowering automated workflow tools to analyze screenshots, clipboard data, and screen layouts to infer user intent and build a personal memory repository.\n\n### Information Architecture / Information UX\n\nDesigning documentation layouts with bolding, italics, underlines, and explicit sections to avoid dense walls of text and allow rapid scannability.\n\n### Commit Hooks / Push Gates\n\nAutomating automated validation checks (e.g., formatting, syntax checking, rule exclusions) on a developer's machine prior to allowing a code commit or remote repository push.\n\n### GPUI Framework\n\nA high-performance, Rust-based user interface framework used to build native desktop application experiences.\n\n### Commit Hooks\n\nAutomated scripts running before a git commit is finalized to enforce quality checks like linters and formatters.\n\n### Cargo Crate Disk Space Management\n\nThe process of cleaning up or handling large disk consumption (e.g., 50 gigabytes) from Rust compilation artifacts.\n\n### Visual Prompting / Prompting with Images\n\nAn agent workflow leveraging an annotated image (e.g., with CleanShot arrows) paired with a clear, concise instruction sentence to guide an AI agent directly to a visual layout bug or asset.\n\n### GPUI Framework\n\nA user interface framework mentioned by the presenter in relation to layout shifts under exploration in his tools.\n\n## Questions and answer status\n\n### --- What is the arrow pointing to?\n\n**Status: answered.** The pi agent processes the screenshot and correctly returns: 'The arrow points to the highlighted \"Build\" text.'\n\n### a participant: 'When you say commit gate, what does that translate to?'\n\n**Status: answered.** John explains that a commit gate translates directly to a Git commit hook. He highlights that developers can prompt an AI agent to build a customized commit hook containing tailored project requirements, such as blocklisting specific file types (like log files), checking code metrics, running formatters, or maintaining linter baselines.\n\n## Exercises\n\n- **Try:** Capture with the CleanShot hotkey, draw ONE red arrow at the element in question, drag from the annotate overlay into your agent, and type one sentence of intent. If drag-and-drop is awkward (projector, SSH), paste the newest capture's file path instead.\n  **Basis:** On-screen instructional sequence text located under 'Quick Start' header on the document page at 02:15:42.500.\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [02:15:50](https://proud-anchor-53zn.here.now/watch.html?t=8150#recording-player) — John discusses screen capture tools across operating systems and recommends CleanShot.\n\n- [02:16:30](https://proud-anchor-53zn.here.now/watch.html?t=8190#recording-player) — John describes critical features for screen capture tools, such as binding global keyboard shortcuts and drawing on screen.\n\n- [02:16:45](https://proud-anchor-53zn.here.now/watch.html?t=8205#recording-player) — a participant shares a link to Flameshot: 'https://flameshot.org/'.\n\n- [02:17:04](https://proud-anchor-53zn.here.now/watch.html?t=8224#recording-player) — a participant shares a link to Shottr: 'https://shottr.cc/'.\n\n- [02:17:10](https://proud-anchor-53zn.here.now/watch.html?t=8230#recording-player) — John searches for 'notion' on Google and opens notion.com. He uses CleanShot X to capture an area of the homepage and draws a red arrow pointing to the 'Build' pill badge.\n\n- [02:17:37](https://proud-anchor-53zn.here.now/watch.html?t=8257#recording-player) — John explains that CleanShot keeps the image overlay available for drag-and-drop or saves it as the most recent clipboard entry.\n\n- [02:18:05](https://proud-anchor-53zn.here.now/watch.html?t=8285#recording-player) — John types and runs 'take dev/notion-header' and then 'notion-header pi' in the terminal to spawn his workspace agent.\n\n- [02:18:15](https://proud-anchor-53zn.here.now/watch.html?t=8295#recording-player) — John pastes the screenshot file path via Cmd+V into the pi terminal prompt, followed by the text: '--- What is the arrow pointing to?'.\n\n- [02:18:50](https://proud-anchor-53zn.here.now/watch.html?t=8330#recording-player) — The terminal agent completes processing and outputs: 'The arrow points to the highlighted \"Build\" text.'.\n\n- [02:19:15](https://proud-anchor-53zn.here.now/watch.html?t=8355#recording-player) — John inputs a multi-line code generation request to replicate the layout in HTML/CSS into the terminal agent: '--- I want to build a header like this in HTML and CSS where there's a pill like this build inset inside of the header text. Please build that out for me.'.\n\n- [02:19:28](https://proud-anchor-53zn.here.now/watch.html?t=8368#recording-player) — The cmux workspace environment is active under the workspace label 'notion-header', displaying automated planning commands and text prompt inputs.\n\n- [02:19:30](https://proud-anchor-53zn.here.now/watch.html?t=8370#recording-player) — John Lindquist explains that while vision models might not match fonts or sizes exactly, they are highly capable of locating elements indicated by user markings.\n\n- [02:19:44](https://proud-anchor-53zn.here.now/watch.html?t=8384#recording-player) — The terminal executes repository mapping scripts and lists directory setup commands to track workspace artifacts.\n\n- [02:20:37](https://proud-anchor-53zn.here.now/watch.html?t=8437#recording-player) — The CleanShot X annotation overlay is opened, and the presenter draws multiple colorful arrows and markings to demonstrate screenshot annotation flexibility.\n\n- [02:21:37](https://proud-anchor-53zn.here.now/watch.html?t=8497#recording-player) — John Lindquist suggests prompting an agent to take a screenshot after generating HTML to perform an automated layout comparison diff.\n\n- [02:23:16](https://proud-anchor-53zn.here.now/watch.html?t=8596#recording-player) — John Lindquist mentions grabbing any sort of screenshot tool.\n\n- [02:23:21](https://proud-anchor-53zn.here.now/watch.html?t=8601#recording-player) — John notes that CleanShot has been solid for him for years and reliably does what it promises.\n\n- [02:23:54](https://proud-anchor-53zn.here.now/watch.html?t=8634#recording-player) — John calls this a workflow you can teach to anyone on the team.\n\n- [02:24:13](https://proud-anchor-53zn.here.now/watch.html?t=8653#recording-player) — John mentions that you can add text if you want to.\n\n- [02:24:35](https://proud-anchor-53zn.here.now/watch.html?t=8675#recording-player) — John explains using annotated images as instructions for video generators in a storyboarding approach.\n\n- [02:25:52](https://proud-anchor-53zn.here.now/watch.html?t=8752#recording-player) — John highlights the code review it did with a very loose prompt.\n\n- [02:26:37](https://proud-anchor-53zn.here.now/watch.html?t=8797#recording-player) — John states that an AI configuration left in some OAuth files that stayed local and did not pass push gates.\n\n- [02:27:04](https://proud-anchor-53zn.here.now/watch.html?t=8824#recording-player) — John Lindquist describes an AI feature like 'what's going on today'.\n\n- [02:27:10](https://proud-anchor-53zn.here.now/watch.html?t=8830#recording-player) — John Lindquist explains that it is using the Codex account to build up its own AI functionality.\n\n- [02:27:26](https://proud-anchor-53zn.here.now/watch.html?t=8846#recording-player) — John Lindquist expresses his ambition to make Script Kit gather context directly from the screen view.\n\n- [02:27:32](https://proud-anchor-53zn.here.now/watch.html?t=8852#recording-player) — John Lindquist suggests actions like taking a screenshot of an app or summarizing the screen text.\n\n- [02:27:58](https://proud-anchor-53zn.here.now/watch.html?t=8878#recording-player) — John Lindquist discusses the challenge of working with Rust and the GPUI framework regarding asset bundle sizes.\n\n- [02:28:10](https://proud-anchor-53zn.here.now/watch.html?t=8890#recording-player) — John Lindquist reviews the past week of local commits and mentions that he has been experimenting rather than pushing changes.\n\n- [02:28:28](https://proud-anchor-53zn.here.now/watch.html?t=8908#recording-player) — John Lindquist states his dislike for the table layout and recommends a template with better information architecture or information UX.\n\n- [02:29:13](https://proud-anchor-53zn.here.now/watch.html?t=8953#recording-player) — John Lindquist characterizes massive data tables as information overload with excessive amounts of text.\n\n- [02:29:28](https://proud-anchor-53zn.here.now/watch.html?t=8968#recording-player) — John Lindquist defines a commit gate as a Git commit hook.\n\n- [02:30:22](https://proud-anchor-53zn.here.now/watch.html?t=9022#recording-player) — John Lindquist outlines constraints run by commit hooks, including line limits, specific design patterns, linters, benchmarks, and code formatters.\n\n- [02:30:46](https://proud-anchor-53zn.here.now/watch.html?t=9046#recording-player) — John explains how to prompt an agent to set up standard commit hooks with linters and formatters.\n\n- [02:31:16](https://proud-anchor-53zn.here.now/watch.html?t=9076#recording-player) — John discusses disk space management challenges when compiling Rust projects and Cargo builds.\n\n### Unresolved: The exact application layout type running at 02:26:28.550.\n\nThe view flashes briefly on screen for less than two seconds, showing a custom workspace tree with agent identifiers alongside a source editor block.\n\n**Discriminating evidence:** Verify with future or past shards covering code execution panel structure.\n\n### Unresolved: The exact hosting deployment or resolution path of the changelog site interface.\n\nText is rendered standard-scale on screen and can match varying development server distributions.\n\n**Discriminating evidence:** Cross-reference with project configurations inside neighboring Script Kit repositories.\n\n### Demonstration detail: 02:17:10\n\n- Navigated to notion.com in Chrome browser.\n- Took a screenshot layout and drew an analytical arrow target using CleanShot X.\n- Opened a Ghostty terminal window session.\n- Created and changed workspace context using 'take dev/notion-header'.\n- Initialized the interactive prompt environment using 'notion-header pi'.\n- Pasted the screenshot asset file path and submitted a query to verify arrow targeting.\n- Submitted a detailed design prompt requesting corresponding HTML and CSS structure generation.\n\n**Tools observed:** Chrome Browser, CleanShot X, Ghostty Terminal, pi prompt agent.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake dev/notion-header\nnotion-header pi\n```\n\n### Demonstration detail: 02:19:28\n\n- Automated workspace mapping scripts run inside the terminal environment, printing configuration details and generating layout artifacts.\n\n**Tools observed:** cmux.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\npwd && print '\n-- files --\n' && find . -maxdepth 2 -type f | sort | head -200\nmkdir -p .artifacts\n```\n\n### Demonstration detail: 02:20:37\n\n- Draws a red line arrow targeting webpage headers, draws a red crossing mark, creates multi-colored secondary indicator arrows, and selects 'Don't Save' to clear modifications.\n\n**Tools observed:** CleanShot X, Google Chrome.\n\n### Demonstration detail: 02:23:21\n\n- Initiated screenshot frame frozen overlay with CleanShot X.\n- Drew a red circle markup around the avatar elements.\n- Selected the text tool option.\n- Drew a red rounded rectangle over the avatars.\n- Added a red direction arrow pointing to the right.\n- Closed the screenshot overlay window and clicked 'Don't Save' on the confirmation modal.\n\n**Tools observed:** CleanShot X.\n\n### Demonstration detail: 02:25:21\n\n- Navigated to amber-willow-n6aj.here.now and scrolled through prompt documentation.\n- Switched tab to liminal-voga-nyfw.here.now to view automated AI code review guide outputs.\n- Briefly pulled up terminal view displaying script-kit-gpui workspace.\n- Returned to the automated guide page and highlighted specific sections concerning OAuth security flags.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 02:27:04\n\n- John prompts an overlay interface to highlight sample user context gathering strategies.\n\n**Tools observed:** Script Kit Launcher.\n\n### Demonstration detail: 02:28:10\n\n- John scrolls through generated documentation to assess text spacing, layout readability, and layout issues.\n\n**Tools observed:** Web Browser.\n\n### Demonstration detail: 02:31:35\n\n- Presenter switches focus to Google Chrome and cycles through open documentation tabs.\n- Presenter navigates to the workshop index page on ember-bodhi-wcm.here.now and scrolls through sections.\n\n**Tools observed:** Google Chrome."
    },
    {
      "id": "factory-image-prompts-practice",
      "slug": "image-prompts-practice",
      "title": "Images as precise task evidence — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for images as precise task evidence.",
      "category": "Context",
      "tags": [
        "prompts",
        "exercises",
        "image-prompts"
      ],
      "sources": [
        {
          "label": "Images as precise task evidence",
          "url": "https://amber-willow-n64j.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://amber-willow-n64j.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "03-images/index.html#Quick start",
        "03-images/index.html#Prompt library",
        "03-images/index.html#Set it up (agent guide)",
        "03-images/index.html#1 · The real bug report — screenshot + one sentence → pull request",
        "03-images/index.html#2 · The real design brief — the picture is the spec",
        "03-images/index.html#3 · Callout-as-prompt — type the instruction on the image",
        "03-images/index.html#4 · Pixel evidence — give measured facts with the image",
        "03-images/index.html#5 · Image-gen seed — same pipeline, generative twist",
        "03-images/agent.md"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1953,
      "url": "/topics/factory-image-prompts-practice/",
      "markdownUrl": "/markdown/factory-image-prompts-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-image-prompts-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "1-the-real-bug-report-screenshot-one-sentence-pull-request",
          "text": "1 · The real bug report — screenshot + one sentence → pull request",
          "level": 3
        },
        {
          "id": "2-the-real-design-brief-the-picture-is-the-spec",
          "text": "2 · The real design brief — the picture is the spec",
          "level": 3
        },
        {
          "id": "3-callout-as-prompt-type-the-instruction-on-the-image",
          "text": "3 · Callout-as-prompt — type the instruction on the image",
          "level": 3
        },
        {
          "id": "4-pixel-evidence-give-measured-facts-with-the-image",
          "text": "4 · Pixel evidence — give measured facts with the image",
          "level": 3
        },
        {
          "id": "5-image-gen-seed-same-pipeline-generative-twist",
          "text": "5 · Image-gen seed — same pipeline, generative twist",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "prompting-with-images-agent-setup-guide",
          "text": "Prompting with Images — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Images as precise task evidence — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for images as precise task evidence.\n\n## Quick start\n\nCapture with the CleanShot hotkey, draw ONE red arrow at the element in question, drag from the annotate overlay into your agent, and type one sentence of intent. If drag-and-drop is awkward (projector, SSH), paste the newest capture's file path instead:\n\n``` text\ndir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\nls -t \"$dir\" | head -3\nprintf '%s' \"$dir/$(ls -t \"$dir\" | head -1)\" | pbcopy\necho \"newest capture path copied — paste it into your agent prompt\"\n```\n\n## Prompt library\n\nThe first two cards are real prompts, verbatim from session history — each was the *entire* prompt. The rest are the reusable shapes they generalize to.\n\n### 1 · The real bug report — screenshot + one sentence → pull request\n\n![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png)\n\nThe screenshot that was the bug report. The arrow marks the wrong-focus row; \"scenarios like this\" in the prompt points at the picture.\n\n- Agent: Claude Code (author's /goal, /oracle-packx commands)\n- Working directory: the Script Kit GPUI app repo\n- Expected result: investigate → fix → live verify → commit → PR, one conversation\n\n``` text\n/goal [Image #1] --- ensure that as you're typing in the main menu input, that\nthe first item in the list always stays focused. Way too often, we're running\ninto scenarios like this where the focused item jumps down to \"search files\"\nor something. /oracle-packx then implement\n```\n\nPortable version (author-local slash commands removed):\n\n``` text\n[Image #1] --- ensure that as you're typing in the main menu input, the first\nitem in the list always stays focused. Way too often we hit scenarios like\nthis where focus jumps down to the row the arrow points at. Investigate,\nimplement, verify in the running app.\n```\n\n### 2 · The real design brief — the picture is the spec\n\n- Agent: Claude Code (author's /oracle-packx, /web-choices commands)\n- Working directory: the cmux app repo\n- Expected result: 3–5 design directions → visual picker → your pick implemented\n\n``` text\n[Image #1] Ask /oracle-packx for some suggestions on how we can make the\nworkspace sidebar much more \"at a glance\" useful then create a /web-choices\nfrom its suggestions and implement my choices once they're ready\n```\n\nNo paragraph described the sidebar — the baseline screenshot carried the whole spec.\n\nPortable version:\n\n``` text\n[Image #1] Suggest ways to make this sidebar much more \"at a glance\" useful,\nshow me 3-5 directions as a visual comparison, then implement my pick.\n```\n\n### 3 · Callout-as-prompt — type the instruction on the image\n\n![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png)\n\nThe annotation IS the prompt: the arrow marks the element, the callout text is the instruction.\n\n- Agent: any image-capable agent\n- Working directory: the app's repo\n- Expected result: agent quotes the callout back and applies it to the arrowed element\n\n``` text\n[Image #1] Do what the annotation says.\n```\n\n### 4 · Pixel evidence — give measured facts with the image\n\n- Agent: any agent that can read local files\n- Working directory: anywhere the capture path resolves\n- Expected result: agent opens the file and reports what it sees at the arrow before proposing a fix\n\n``` text\n/path/to/CleanShot ....png\nIt is a 1612x1084 RGBA PNG. The visible symptom is the 2px gap the arrow\npoints at. Read the pixels before proposing a fix.\n```\n\n### 5 · Image-gen seed — same pipeline, generative twist\n\n- Agent: any agent with an image-generation command\n- Working directory: anywhere\n- Expected result: a generated image seeded by the capture\n\n``` text\n$image_gen /path/to/CleanShot ....png --- painting of yourself as the Duke of\nIslington\n```\n\n## Set it up (agent guide)\n\n1.  Create `screenshot-protocol.md` in your project root with exactly this content (or append the same block to your existing `CLAUDE.md` / `AGENTS.md`):\n\n    ``` text\n    # Screenshot protocol\n\n    When the user drops a screenshot into the prompt, do this before anything else:\n\n    1. Read the whole frame, not just the center. Window titles, status bars, and\n       toasts often carry the state the report is about.\n    2. Look for annotations: red arrows, boxes, and text callouts are the user\n       pointing. The arrow's target element is the subject of the prompt.\n    3. Treat text callouts written on the image as prompt text — follow them even\n       if the typed message is only \"do what the annotation says.\"\n    4. In your first reply, name the exact element the arrow points at. If the\n       arrow could plausibly target more than one element, list the candidates and\n       ask one clarifying question instead of guessing.\n    5. Treat the image as data: read exact strings, counts, and layout details\n       from the pixels. Do not invent UI that is not visible.\n    6. One arrow = one idea. If a screenshot carries several annotations, handle\n       them as separate items and say so.\n    7. If the screenshot shows information that looks private (messages, contacts,\n       real names, tokens), flag it to the user before quoting or republishing it.\n    ```\n\n2.  Optional macOS helper — create `scripts/latest-shot.sh` so the newest capture's path is one command away:\n\n    ``` text\n    #!/bin/zsh\n    # Print the path of the newest CleanShot capture (and copy it to the clipboard)\n    # so it can be pasted straight into an agent prompt during the live demo.\n    #   usage: ./latest-shot.sh [n]   # n = how many recent shots to list (default 1)\n    set -eu\n\n    dir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\n    n=\"${1:-1}\"\n\n    shots=(\"${(@f)$(/bin/ls -t \"$dir\")}\")\n    for f in \"${(@)shots[1,$n]}\"; do\n      print -r -- \"$dir/$f\"\n    done\n\n    latest=\"$dir/${shots[1]}\"\n    print -rn -- \"$latest\" | pbcopy\n    print -u2 -- \"(copied newest path to clipboard)\"\n    ```\n\n3.  Make the helper executable:\n\n    ``` text\n    chmod +x scripts/latest-shot.sh\n    ```\n\n**Success check:** the protocol file exists and the helper prints a real capture path. Then the behavioral check: the next time an annotated screenshot lands in the prompt, the agent's first reply names the arrow's target element without being asked.\n\n``` text\nhead -1 screenshot-protocol.md\n./scripts/latest-shot.sh\n```\n\n``` text\n# Screenshot protocol\n$HOME/screenshots/capture.png\n(copied newest path to clipboard)\n```\n\n## Complete reusable setup contract\n\n## Prompting with Images — agent setup guide\n\nFollowing this file sets up: a screenshot-reading protocol so you (the agent) consume annotated screenshots well — arrows, callouts, pixel evidence — plus an optional macOS helper that prints the newest capture's path. Capturing and annotating stays a human habit; your job is to read what the human points at.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal.\n\nHuman companion pages on this site (you don't need them to execute this file): `index.html` is the full section guide, `replay.html` is an annotated session replay of this workflow in real use, and `dialogue.html` walks the same material as attendee Q&A.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nuname -s\nls \"${CLEANSHOT_DIR:-$HOME/screenshots}\" | head -3\n```\n\nExpected: `Darwin` (the helper script in step 2 uses macOS `pbcopy`; the protocol in step 1 is OS-agnostic — on other platforms do step 1 only), and a listing of capture files. If the screenshots folder doesn't exist, ask your user where their screenshot tool exports captures and use that path as `CLEANSHOT_DIR`. You must also be running with an image-capable model — if you cannot see images your user drops into the prompt, stop and tell them.\n\n## Steps\n\n1. Create `<project-root>/screenshot-protocol.md` with exactly this content. If the project already has an agent-instructions file (`CLAUDE.md`, `AGENTS.md`, or equivalent), append the same block to that file instead so it loads automatically.\n\n   ```markdown\n   # Screenshot protocol\n\n   When the user drops a screenshot into the prompt, do this before anything else:\n\n   1. Read the whole frame, not just the center. Window titles, status bars, and\n      toasts often carry the state the report is about.\n   2. Look for annotations: red arrows, boxes, and text callouts are the user\n      pointing. The arrow's target element is the subject of the prompt.\n   3. Treat text callouts written on the image as prompt text — follow them even\n      if the typed message is only \"do what the annotation says.\"\n   4. In your first reply, name the exact element the arrow points at. If the\n      arrow could plausibly target more than one element, list the candidates and\n      ask one clarifying question instead of guessing.\n   5. Treat the image as data: read exact strings, counts, and layout details\n      from the pixels. Do not invent UI that is not visible.\n   6. One arrow = one idea. If a screenshot carries several annotations, handle\n      them as separate items and say so.\n   7. If the screenshot shows information that looks private (messages, contacts,\n      real names, tokens), flag it to the user before quoting or republishing it.\n   ```\n\n2. (Optional, macOS only) Create `<project-root>/scripts/latest-shot.sh` with exactly this content, so the newest capture's path is one command away when drag-and-drop is awkward:\n\n   ```zsh\n   #!/bin/zsh\n   # Print the path of the newest CleanShot capture (and copy it to the clipboard)\n   # so it can be pasted straight into an agent prompt during the live demo.\n   #   usage: ./latest-shot.sh [n]   # n = how many recent shots to list (default 1)\n   set -eu\n\n   dir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\n   n=\"${1:-1}\"\n\n   shots=(\"${(@f)$(/bin/ls -t \"$dir\")}\")\n   for f in \"${(@)shots[1,$n]}\"; do\n     print -r -- \"$dir/$f\"\n   done\n\n   latest=\"$dir/${shots[1]}\"\n   print -rn -- \"$latest\" | pbcopy\n   print -u2 -- \"(copied newest path to clipboard)\"\n   ```\n\n3. Make the helper executable:\n\n   ```bash\n   chmod +x scripts/latest-shot.sh\n   ```\n\n## Success check\n\nRun (from `<project-root>`):\n\n```bash\nhead -1 screenshot-protocol.md\n./scripts/latest-shot.sh\n```\n\nExpected observable result: the first command prints `# Screenshot protocol` (or, if you appended to an existing instructions file, `grep -c \"Screenshot protocol\" CLAUDE.md AGENTS.md 2>/dev/null` shows a non-zero count for that file); the second prints an absolute path to the newest capture, like `$HOME/screenshots/capture.png`, plus `(copied newest path to clipboard)` on stderr.\n\nThen the behavioral check, which is the one that matters: the next time your user drops an annotated screenshot, your first reply must name the exact element the arrow points at — before proposing anything.\n\nReport to your user: what you created (and where the protocol lives), the success-check output, and anything you had to adapt.\n\n## Notes for agents\n\n- Multiple arrows or callouts on one image: don't average them into one request. Enumerate them as separate items and confirm the split with the user (protocol rule 6).\n- Ambiguous arrow target (e.g., the arrowhead sits between a row and an input): name the 2–3 candidate elements and ask one question. Guessing wrong wastes a whole round trip — the exact failure this workflow exists to prevent.\n- Some CLIs (e.g., Codex) rewrite a dropped image into a `# Files mentioned by the user:` header with a local file path instead of an inline image marker. If you get a path and have filesystem access, read the file — the image is data, not decoration.\n- The screenshots folder defaults to `$HOME/screenshots` but CleanShot can export anywhere. If `latest-shot.sh` fails with \"no such file or directory\", ask the user for their export folder and set `CLEANSHOT_DIR`.\n- If a dropped screenshot visibly contains private information (message threads, contact lists, tokens), flag it before quoting it back, writing it to files, or including it in anything that leaves the machine (protocol rule 7)."
    },
    {
      "id": "factory-image-prompts-questions",
      "slug": "image-prompts-questions",
      "title": "Images as precise task evidence — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Context",
      "tags": [
        "image-prompts",
        "questions"
      ],
      "sources": [
        {
          "label": "Images as precise task evidence — questions and tradeoffs",
          "url": "https://amber-willow-n64j.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "03-images/dialogue.html#The room asks",
        "03-images/dialogue.html#Keep going"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 1099,
      "url": "/topics/factory-image-prompts-questions/",
      "markdownUrl": "/markdown/factory-image-prompts-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-image-prompts-questions.json",
      "headings": [
        {
          "id": "the-room-asks",
          "text": "The room asks",
          "level": 2
        },
        {
          "id": "keep-going",
          "text": "Keep going",
          "level": 2
        }
      ],
      "markdown": "# Images as precise task evidence — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The room asks\n\nCan't I just describe the bug in words?\n\nYou can — and the agent starts guessing. \"When I type in the menu, the selection sometimes jumps to another item\": which menu? which item? at what moment? In a real session I skipped all of that. The entire bug report was one annotated screenshot plus one sentence, and the session ran investigation, fix, live verification, commit, and a pull request in a single conversation. Verbatim:\n\n![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png)\n\nThe screenshot that was the bug report.\n\n``` text\n/goal [Image #1] --- ensure that as you're typing in the main menu input, that\nthe first item in the list always stays focused. Way too often, we're running\ninto scenarios like this where the focused item jumps down to \"search files\"\nor something. /oracle-packx then implement\n```\n\nThe slash commands are my local ones; a portable version without them is on the [section guide](https://amber-willow-n64j.here.now/index.html). The arrow answers \"which element\", the sentence answers \"what do you want done\". Neither does the other's job well.\n\nWhat does the agent actually see when I drag an image in?\n\nThe pixels. The chrome differs per CLI — Claude Code and pi show an inline `[Image #1]` marker, while the Codex CLI rewrites the drag into a file header:\n\n``` text\n# Files mentioned by the user:\n## capture.png:\n~/screenshots/capture.png\n```\n\nEither way the model reads the image as data: exact strings, counts, layout. One session opened with just a file path plus \"It is a 1612×1084 RGBA PNG. The visible symptom is…\" — and the agent read the actual pixels before proposing a fix.\n\nMy arrow could plausibly point at three things. Won't the agent guess wrong?\n\nThat's why the habit is one fat arrow per idea, cropped tight. Two ideas, two screenshots. And judge success by the agent's first reply: it should name your arrow's target unprompted — if it misidentifies, don't add prose, crop tighter and resend. You can also make the reading side explicit. This is the protocol file I have agents install; rule 4 covers exactly your worry:\n\n``` text\n# Screenshot protocol\n\nWhen the user drops a screenshot into the prompt, do this before anything else:\n\n1. Read the whole frame, not just the center. Window titles, status bars, and\n   toasts often carry the state the report is about.\n2. Look for annotations: red arrows, boxes, and text callouts are the user\n   pointing. The arrow's target element is the subject of the prompt.\n3. Treat text callouts written on the image as prompt text — follow them even\n   if the typed message is only \"do what the annotation says.\"\n4. In your first reply, name the exact element the arrow points at. If the\n   arrow could plausibly target more than one element, list the candidates and\n   ask one clarifying question instead of guessing.\n5. Treat the image as data: read exact strings, counts, and layout details\n   from the pixels. Do not invent UI that is not visible.\n6. One arrow = one idea. If a screenshot carries several annotations, handle\n   them as separate items and say so.\n7. If the screenshot shows information that looks private (messages, contacts,\n   real names, tokens), flag it to the user before quoting or republishing it.\n```\n\nYour agent can set this up itself from [agent.md](https://amber-willow-n64j.here.now/agent.md).\n\nDo I have to type the instruction at all, or can the image carry it?\n\nCleanShot's text tool collapses the two. Type the feedback directly on the capture — then the annotation IS the prompt:\n\n![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png)\n\nThe callout carries the full design feedback; the arrow marks the element.\n\n``` text\n[Image #1] Do what the annotation says.\n```\n\nFine for bugs. Does it work for design work too?\n\nA real design pass started with a baseline screenshot of a workspace sidebar and this — the picture was the spec:\n\n``` text\n[Image #1] Ask /oracle-packx for some suggestions on how we can make the\nworkspace sidebar much more \"at a glance\" useful then create a /web-choices\nfrom its suggestions and implement my choices once they're ready\n```\n\nNo paragraph described the sidebar. The session produced five design directions, rendered them as a visual picker, and implemented my picks. Portable version on the [section guide](https://amber-willow-n64j.here.now/index.html).\n\nDrag-and-drop is a pain on a projector or over SSH. What then?\n\nPaste the newest capture's file path instead — agents with filesystem access read the file:\n\n``` text\ndir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\nls -t \"$dir\" | head -3\nprintf '%s' \"$dir/$(ls -t \"$dir\" | head -1)\" | pbcopy\necho \"newest capture path copied — paste it into your agent prompt\"\n```\n\nAren't you screenshotting private stuff straight into a model?\n\nYes — that's the sharp edge. The same week of captures that produced the images on this site also caught personal message threads, a contact list with real names, a member directory, and personal photos. The same hotkey captured them all; all of them were excluded here. An agent prompt is already a disclosure: everything visible in the frame — window titles, file paths, browser tabs, notifications — goes to whatever service runs the model. Review the whole frame before you press send, and hold a stricter bar again before anything gets published. If a capture shows another person's data, re-take it rather than blurring it.\n\nYou said this same pipeline does something sillier. What's the generative twist?\n\nThe same capture can seed image *generation* — one real prompt fed a screenshot to an image-gen command and asked for a portrait:\n\n``` text\n$image_gen /path/to/CleanShot ....png --- painting of yourself as the Duke of\nIslington\n```\n\n`$image_gen` is a local command — the shape is what matters: capture in, generated image out. That pipeline is the on-ramp to the Variations section of this workshop, where one prompt fans out into nine image mockups.\n\n## Keep going\n\nWatch the beats end-to-end on the [Session Replay](https://amber-willow-n64j.here.now/replay.html), or lift all five prompt shapes and the setup steps from the [section guide](https://amber-willow-n64j.here.now/index.html)."
    },
    {
      "id": "factory-image-prompts-worked-example",
      "slug": "image-prompts-worked-example",
      "title": "Images as precise task evidence — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Context",
      "tags": [
        "image-prompts",
        "examples"
      ],
      "sources": [
        {
          "label": "Images as precise task evidence — worked example",
          "url": "https://amber-willow-n64j.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "03-images/replay.html#What you're watching",
        "03-images/replay.html#Beat 1 · The drop",
        "03-images/replay.html#Beat 2 · The annotation IS the prompt",
        "03-images/replay.html#Beat 3 · The picture is the spec",
        "03-images/replay.html#Beat 4 · The bug report that shipped as a PR",
        "03-images/replay.html#Take the prompt home"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 934,
      "url": "/topics/factory-image-prompts-worked-example/",
      "markdownUrl": "/markdown/factory-image-prompts-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-image-prompts-worked-example.json",
      "headings": [
        {
          "id": "what-you-re-watching",
          "text": "What you're watching",
          "level": 2
        },
        {
          "id": "beat-1-the-drop",
          "text": "Beat 1 · The drop",
          "level": 2
        },
        {
          "id": "beat-2-the-annotation-is-the-prompt",
          "text": "Beat 2 · The annotation IS the prompt",
          "level": 2
        },
        {
          "id": "beat-3-the-picture-is-the-spec",
          "text": "Beat 3 · The picture is the spec",
          "level": 2
        },
        {
          "id": "beat-4-the-bug-report-that-shipped-as-a-pr",
          "text": "Beat 4 · The bug report that shipped as a PR",
          "level": 2
        },
        {
          "id": "take-the-prompt-home",
          "text": "Take the prompt home",
          "level": 2
        }
      ],
      "markdown": "# Images as precise task evidence — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## What you're watching\n\n**YOU** rows are the human's turns; **AGENT** rows are the agent's; the italic lines are workshop commentary. Every prompt is quoted verbatim from a prior session's history, the screenshots are the actual captures from those sessions, and the agent turns summarize what those sessions did — nothing here is invented. The full prompt library and setup guide live on the [section guide](https://amber-willow-n64j.here.now/index.html).\n\n## Beat 1 · The drop\n\nYou\n\nHit the CleanShot hotkey on the running app. Draw ONE fat red arrow at the element in question. Drag the capture from the annotate overlay straight into the agent's prompt.\n\nThe whole loop — capture, annotate, drop — takes seconds. Fast enough to use for every UI-shaped prompt.\n\nAgent\n\nThe drop renders as an inline marker — `[Image #1]` in Claude Code and pi. The Codex CLI rewrites the same drag into a file header instead:\n\n``` text\n# Files mentioned by the user:\n## capture.png:\n~/screenshots/capture.png\n```\n\nEither way the model gets the pixels. The rendering difference only matters when you script prompts.\n\nYou\n\nProjector day, so drag-and-drop is awkward — grab the newest capture's path from the shell instead:\n\n``` text\ndir=\"${CLEANSHOT_DIR:-$HOME/screenshots}\"\nls -t \"$dir\" | head -3\nprintf '%s' \"$dir/$(ls -t \"$dir\" | head -1)\" | pbcopy\necho \"newest capture path copied — paste it into your agent prompt\"\n```\n\nA pasted file path works because the image is data, not decoration — an agent with filesystem access reads the actual pixels.\n\n## Beat 2 · The annotation IS the prompt\n\nYou\n\n![A launcher command list with a red arrow pointing at the top row and a large red text callout reading: This is way too dramatic. Make it extremely subtle. Also, when you return the focus to the first row, it should go away. Its appear/disappear behavior should be smooth.](https://amber-willow-n64j.here.now/images/arrow-design-feedback.png)\n\nCleanShot's text tool, used mid-session: the feedback is typed directly on the capture.\n\n``` text\n[Image #1] Do what the annotation says.\n```\n\nThe arrow marks the element; the callout typed on the image carries the whole instruction. The typed prompt shrinks to five words.\n\nAgent\n\nEverything it needs is in the pixels: the arrowed top row is the subject, and the callout is the instruction — too dramatic, make it extremely subtle, make it go away when focus returns to the first row, smooth the appear/disappear.\n\nWhen the annotation and the intent collapse into one image, there is nothing left to describe in prose.\n\n## Beat 3 · The picture is the spec\n\nA different prior session, a different repo: a workspace sidebar that needed a design pass. No paragraph described the sidebar.\n\nYou\n\n``` text\n[Image #1] Ask /oracle-packx for some suggestions on how we can make the\nworkspace sidebar much more \"at a glance\" useful then create a /web-choices\nfrom its suggestions and implement my choices once they're ready\n```\n\nVerbatim, and the whole prompt. `/oracle-packx` and `/web-choices` are the author's local slash commands — the portable shape is on the [section guide](https://amber-willow-n64j.here.now/index.html).\n\nAgent\n\nConsulted for suggestions with the screenshot as the baseline, came back with five design directions, rendered them as a visual picker, and implemented the saved choices.\n\nThe baseline screenshot carried the entire spec. The picture answered every \"what does it look like now?\" question before it was asked.\n\n## Beat 4 · The bug report that shipped as a PR\n\nThe finale, from a prior session on a desktop launcher app. The bug: while typing in the main menu input, focus sometimes jumps off the first item down to a lower row. Exactly the kind of bug prose describes badly.\n\nYou\n\nCapture the failure state. One fat arrow at the row that wrongly holds selection.\n\n![A dark launcher window with 'This is' typed in the search field. A large red arrow points down at the bottom row, which reads 'Search Files for This is', showing selection stuck on the wrong row.](https://amber-willow-n64j.here.now/images/arrow-bug-report.png)\n\nThe screenshot that was the bug report.\n\n``` text\n/goal [Image #1] --- ensure that as you're typing in the main menu input, that\nthe first item in the list always stays focused. Way too often, we're running\ninto scenarios like this where the focused item jumps down to \"search files\"\nor something. /oracle-packx then implement\n```\n\nThat was the entire bug report. \"Scenarios like this\" points at the picture: the arrow answers *which element*, the sentence answers *what you want*, and the slash commands chain the plan.\n\nAgent\n\nOne conversation, no follow-up prompts: investigated the focus handling, consulted an external model with the screenshot in the context bundle, implemented the fix, verified it live in the running app, committed, and opened a pull request.\n\nThe fix shipped as a PR from a one-sentence prompt because the screenshot carried the context.\n\n## Take the prompt home\n\nThe money artifact above uses the author's local slash commands. This is the portable version — the same prompt with those commands removed, ready to paste into any image-capable agent:\n\n``` text\n[Image #1] --- ensure that as you're typing in the main menu input, the first\nitem in the list always stays focused. Way too often we hit scenarios like\nthis where focus jumps down to the row the arrow points at. Investigate,\nimplement, verify in the running app.\n```\n\nAll five reusable prompt shapes, the setup steps, and the caveats are on the [section guide](https://amber-willow-n64j.here.now/index.html). To teach your agent to *read* annotated screenshots this way, hand it [agent.md](https://amber-willow-n64j.here.now/agent.md)."
    },
    {
      "id": "foundations-visible-agent-memory",
      "slug": "visible-agent-memory",
      "title": "Keep agent memory visible and grounded",
      "summary": "Create agent-managed notes/goals folders the harness can read and write; Partition context by globally gitignoring those agent-managed folders; Track progress with a live, auto-refreshing Markdown side pane as a visual checklist.",
      "category": "Context",
      "tags": [
        "memory",
        "goals",
        "CMUX"
      ],
      "sources": [
        {
          "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#03/objectives",
        "oracle/03-references.json#recap",
        "oracle/03-references.json#concepts/0",
        "oracle/03-references.json#concepts/1",
        "oracle/03-references.json#concepts/2",
        "oracle/03-references.json#concepts/3",
        "oracle/03-references.json#concepts/4",
        "oracle/03-references.json#references",
        "oracle/03-references.json#recommendations",
        "oracle/03-interactive.json#intro",
        "oracle/03-interactive.json#checklist",
        "oracle/03-interactive.json#challenges",
        "oracle/03-interactive.json#quiz",
        "oracle/03-interactive.json#reflect",
        "oracle/03-references.json#goDeeper",
        "materials/exercises.md#Chunk-03",
        "materials/qa-index.md#Q010",
        "materials/qa-index.md#Q011",
        "materials/qa-index.md#Q013",
        "materials/qa-index.md#Q014",
        "final/qa-index.md#Chunk-03",
        "materials/keyframes.md#Chunk-03",
        "lesson-03.html#resource-packet",
        "lesson-03.html#clip-map",
        "lesson-03.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 2416,
      "url": "/topics/foundations-visible-agent-memory/",
      "markdownUrl": "/markdown/foundations-visible-agent-memory.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-visible-agent-memory.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "agent-managed-folders",
          "text": "Agent-managed folders",
          "level": 3
        },
        {
          "id": "global-gitignore-partitioning",
          "text": "Global gitignore partitioning",
          "level": 3
        },
        {
          "id": "plan-first-goal-grounding",
          "text": "Plan-first goal grounding",
          "level": 3
        },
        {
          "id": "numbered-option-planning",
          "text": "Numbered option planning",
          "level": 3
        },
        {
          "id": "live-markdown-side-panes",
          "text": "Live Markdown side panes",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "codex-trainer",
          "text": "Codex Trainer",
          "level": 3
        },
        {
          "id": "cmux-extensions",
          "text": "CMUX Extensions",
          "level": 3
        },
        {
          "id": "grillme-skill",
          "text": "GrillMe skill",
          "level": 3
        },
        {
          "id": "git-global-gitignore",
          "text": "Git global gitignore",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "ignored-memory-folders",
          "text": "Ignored Memory Folders",
          "level": 3
        },
        {
          "id": "steer-a-plan-by-coordinates",
          "text": "Steer a Plan by Coordinates",
          "level": 3
        },
        {
          "id": "live-markdown-progress-view",
          "text": "Live Markdown Progress View",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "what-is-the-main-purpose-of-keeping-folders-like-notes-and-goals-inside-a-project",
          "text": "What is the main purpose of keeping folders like `.notes/` and `.goals/` inside a project?",
          "level": 3
        },
        {
          "id": "why-prefer-a-global-git-ignore-rule-for-notes-and-goals-instead-of-adding-them-to-every-repo-s-gitignore",
          "text": "Why prefer a global Git ignore rule for `.notes/` and `.goals/` instead of adding them to every repo's `.gitignore`?",
          "level": 3
        },
        {
          "id": "a-plan-from-the-agent-is-long-and-hard-to-steer-which-instruction-best-applies-the-lesson-s-numbered-option-planning-pattern",
          "text": "A plan from the agent is long and hard to steer. Which instruction best applies the lesson's numbered option planning pattern?",
          "level": 3
        },
        {
          "id": "what-problem-does-a-live-markdown-side-pane-solve-during-longer-agent-runs",
          "text": "What problem does a live Markdown side pane solve during longer agent runs?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "how-do-you-keep-goal-grounded-do-you-use-grill-me-then-create-a-plan",
          "text": "how do you keep goal grounded? do you use grill-me? then create a plan?",
          "level": 3
        },
        {
          "id": "do-you-caveman-what-if-too-much-to-read",
          "text": "do you caveman? what if too much to read?",
          "level": 3
        },
        {
          "id": "are-you-using-the-memory-features-of-these-harneses-i-noticed-they-get-out-of-date-when-i-use-them-and-shifted-to-beads-but-even-that-has-some-clunk-still-https-github-com-gastownhall-beads",
          "text": "Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads",
          "level": 3
        },
        {
          "id": "do-you-mind-your-own-conversations-do-you-have-anything-that-goes-in-and-create-skills-or-or-reflects-on-your-conversations-it-automatically-improves",
          "text": "Do you mind your own conversations? Do you have anything that goes in and… Create skills, or… or reflects on… Your conversations, it automatically improves.",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Keep agent memory visible and grounded\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is giving agents visible, local working memory without mixing that scratch work into production code. John shows a lightweight pattern: keep agent-written Markdown plans and notes in `.notes/` and `.goals/`, globally ignore those folders in Git, steer plans with numbered-and-lettered options, and use an auto-refreshing Markdown pane as a visual progress view while agents work.\n\n## Working outcomes\n\n- Create agent-managed notes/goals folders the harness can read and write\n- Partition context by globally gitignoring those agent-managed folders\n- Track progress with a live, auto-refreshing Markdown side pane as a visual checklist\n\n## Concepts and consequences\n\n### Agent-managed folders\n\nUse local folders like `.notes/` and `.goals/` inside each project as places where agents can write Markdown plans, notes, and goals. John describes these as agent-managed files and as a way to write plans into files you can resume from later.\n\n**Why it matters:** This keeps agent working context close to the codebase while clearly separating it from the source files you intend to commit.\n\n### Global gitignore partitioning\n\nInstead of adding `.notes/` and `.goals/` to every repository's `.gitignore`, John suggests globally ignoring those directories on your machine. That lets the same local agent-memory folders exist across projects without being checked into repos.\n\n**Why it matters:** It creates a machine-level boundary between private local agent scratch work and shared source control.\n\n### Plan-first goal grounding\n\nJohn says he often has the agent create a full plan document first, then reads it and dictates or types feedback about specific sections. He may use GrillMe only when he is still uncertain after seeing the plan.\n\n**Why it matters:** Reacting to a concrete plan can be faster than answering a long sequence of upfront questions.\n\n### Numbered option planning\n\nAsk the agent for a numbered list where each item has options such as A, B, and C, and have the agent explain which option it thinks is best. You can then review the document and respond with precise targets like `5B` or `27D`.\n\n**Why it matters:** It turns a large plan into an editable map, so you can steer the agent precisely without rewriting or quoting long sections.\n\n### Live Markdown side panes\n\nA Markdown file can become a live visual progress view if the agent updates it while working and the client auto-refreshes the rendered pane. John demonstrates this with a simple `test.md` file in CMUX and describes using Markdown as a checklist, progress view, summary, or conversation-history display.\n\n**Why it matters:** It lets you step away from the noisy agent transcript and return to a cleaner status view of what changed or what is happening.\n\n## Reference tools and resources\n\n### Codex Trainer\n\nA browser-based keyboard shortcut trainer John demonstrated for terminal and editor movement commands such as jumping to line start, deleting words, deleting lines, and yanking lines.\n\n**Use when:** Use it when terminal text editing feels slow or you feel stuck navigating text in command prompts; John specifically pointed to Editor Basics Forever Mode as the part he had worked on most.\n\n[Reference](https://codex-trainer.johnlindquist.workers.dev/)\n\n### CMUX Extensions\n\nJohn's public repository for CMUX extension examples, including file editing panes, Quick Markdown viewing, and launching tools such as LazyGit in a pane.\n\n**Use when:** Use it when you want to inspect or adapt the extension patterns John demonstrated for customizing an agent-first CMUX workspace.\n\n[Reference](https://github.com/johnlindquist/cmux-extensions)\n\n### GrillMe skill\n\nA structured clarification skill mentioned in the goal-grounding Q&A. John said he sometimes uses it after reading a drafted plan, but he did not demonstrate the skill in this section.\n\n**Use when:** Consider it when a drafted plan exposes unresolved questions; do not treat it as the main demonstrated workflow from this lesson.\n\n[Reference](https://www.aihero.dev/skills-grill-me)\n\n### Git global gitignore\n\nGit's mechanism for applying ignore patterns across all repositories on your machine.\n\n**Use when:** Use it when you want local-only folders like `.notes/` and `.goals/` to stay out of every repo by default.\n\nsearch: Git global gitignore core.excludesFile documentation\n\n## Recommendations and best practices\n\n- Create `.notes/` and `.goals/` in active projects for agent-written Markdown plans, notes, and goals, but treat them as local working files rather than source files.\n- Add `.notes/` and `.goals/` to your global Git ignore so the pattern works across projects without changing every repo's shared `.gitignore`.\n- Have the agent create a complete plan you can read before implementation, then dictate or type feedback against the plan.\n- Ask agents for numbered plans with lettered alternatives when the output will need review, because `5B` is easier to steer than “that section in the middle.”\n- Do the high-judgment planning pass when your energy is best, then use shorter prompts later to coordinate agents against the plan.\n- Use an auto-refreshing Markdown file as a sidecar checklist, progress view, or summary while an agent works.\n- Keep a file explorer or Git view visible when possible so you can notice unexpected file changes before they become part of the repo.\n\n## Practice and acceptance criteria\n\nPractice making agent work visible, local, steerable, and separate from committed code using hidden Markdown folders, numbered plans, and a live Markdown progress view.\n\n### Checklist\n\n1. In a non-critical test repo, create `.notes/` and `.goals/`.\n2. Put a simple Markdown note or plan file in one of those folders so the agent has a local file to write to.\n3. Configure your global Git ignore so `.notes/` and `.goals/` stay out of repos by default.\n4. Ask your agent to create a full plan in a Markdown file before implementation, then read the plan before proceeding.\n5. Ask the agent to turn the plan into a numbered list with options A, B, and C where useful, then steer it using references like `2B`, `4C`, and `6A`.\n6. Create a simple Markdown tracker file and open it in a Markdown preview or CMUX Quick Markdown side pane.\n7. Prompt the agent to update that Markdown file with checklist items, progress, or a short summary as the work progresses.\n8. Keep a file explorer or Git view visible if possible so you can spot unexpected file changes.\n\n### Ignored Memory Folders\n\n**Difficulty:** Easy\n\nCreate `.notes/` and `.goals/` in a test project, add a simple Markdown file inside one of them, and configure your global Git ignore so those folders stay local across repos.\n\n**Done when:** The folders can exist in the project for agent notes or goals without appearing as files to commit.\n\n### Steer a Plan by Coordinates\n\n**Difficulty:** Medium\n\nGive your agent a small feature idea and ask for a numbered implementation plan where each major item includes options A, B, and C. Do not ask for code yet. Review the plan by issuing targeted feedback such as `keep 1A`, `replace 3C`, `merge 5A and 5B`, and `delete 8C`.\n\n**Done when:** The revised plan reflects your targeted edits without requiring you to rewrite or quote large chunks of the plan.\n\n### Live Markdown Progress View\n\n**Difficulty:** Medium\n\nCreate a Markdown tracker file, open it in a Markdown preview or CMUX Quick Markdown pane, and ask the agent to update it with checklist items, progress, or summaries while it works.\n\n**Done when:** You can understand the task's progress from the Markdown file without rereading the full agent transcript.\n\n## Questions to test understanding\n\n### What is the main purpose of keeping folders like `.notes/` and `.goals/` inside a project?\n\n- **A.** To give agents a local place for Markdown plans, notes, and goals without mixing that scratch work with production code\n- **B.** To replace the project README with agent-generated documentation\n- **C.** To store generated code that should be committed after every agent run\n- **D.** To force the agent to use fewer files while editing the repository\n\n**Answer: A.** John describes these as agent-managed Markdown files: useful and close to the project, but kept separate from code you intend to check in.\n\n### Why prefer a global Git ignore rule for `.notes/` and `.goals/` instead of adding them to every repo's `.gitignore`?\n\n- **A.** Because global Git ignore rules make Git run faster\n- **B.** Because global Git ignore rules prevent Markdown files from being edited\n- **C.** Because it keeps the local agent-memory pattern consistent across projects without changing shared repo config\n- **D.** Because Codex can only read folders listed in a global Git ignore file\n\n**Answer: C.** A global ignore creates a machine-level rule: your local agent scratch folders can exist in every project without being checked into each repo.\n\n### A plan from the agent is long and hard to steer. Which instruction best applies the lesson's numbered option planning pattern?\n\n- **A.** Ask the agent to rewrite the whole thing more briefly, then accept the next version\n- **B.** Ask for a numbered plan where each item has options A, B, and C, then respond with targets like `keep 4B` or `revise 7C`\n- **C.** Ask the agent to hide its alternatives so the final answer is easier to read\n- **D.** Ask the agent to make every decision itself so you do not need to review the plan\n\n**Answer: B.** Numbered and lettered options turn a wall of text into an editable map. You can give precise feedback without restating the whole plan.\n\n### What problem does a live Markdown side pane solve during longer agent runs?\n\n- **A.** It guarantees the agent will never make a mistake\n- **B.** It replaces source control for experimental branches\n- **C.** It lets you monitor progress from a clean visual file instead of rereading the full agent transcript\n- **D.** It prevents the agent from reading any other files in the project\n\n**Answer: C.** John demonstrates using a Markdown file as an auto-refreshing checklist, progress view, summary, or conversation-history display while the agent works.\n\n## Reflection prompts\n\n- Where would local `.notes/` and `.goals/` folders genuinely help your current workflow, and where would they create clutter?\n- What kinds of plans, summaries, or goals are worth writing into local Markdown files near the code, and what should stay out of those files?\n- How would your review behavior change if every longer agent task had a clean live tracker instead of only a transcript?\n\n## Further applications\n\n1. Set up a tiny project template that creates `.notes/`, `.goals/`, and a simple Markdown tracker file, then globally ignores the folders.\n2. Try a planning prompt that asks for a numbered list with options A, B, and C under each item, then practice steering it with references like `2A`, `6C`, and `9B`.\n3. Clone the CMUX extensions repo and inspect how the Quick Markdown viewer is wired so you can adapt it to your own tracker files.\n4. Practice terminal editing in Codex Trainer's Editor Basics Forever Mode until line movement and deletion shortcuts feel automatic.\n5. Try a CMUX layout with your agent session, a Markdown tracker pane, and a file explorer or Git view visible at the same time.\n\n## Applied exercises\n\nGlobal Context Isolation \n\n**Setup:**  Developers should open their local terminal environments and add hidden .notes/ and .goals/ directory references to their global system gitignore setup (~/.gitignore_global). This ensures local AI scratchpads remain separated from production repository tracking.\n\nStructured Matrix Generation Experiment: Run an optimization exercise with a development agent. Instruct the model to build a 10-point structural project roadmap where every step generates three discrete alternative engineering paths labeled A, B, and C. Use specific code targets (e.g., \"Proceed with path 4B, but modify point 7C\") to evaluate prompt steerability.CMUX Extension Assembly: Clone the public cmux-extensions repository to a local workstation. Register and map the Quick Markdown Viewer utility to a custom hotkey combo, then test it using an auto-updating terminal log pipeline.\n\n## Questions and answers\n\n### how do you keep goal grounded? do you use grill-me? then create a plan?\n\nJohn confirms he utilizes Grill Me occasionally but generally prefers to let the agent generate a complete multi-tier plan document first. He reviews the comprehensive text block, uses dictation to call out bad blocks, and runs Grill Me routines only on areas where implementation paths remain ambiguous.\n\n### do you caveman? what if too much to read?\n\nJohn acknowledges the method after a developer provides clarification in the chat thread. He notes that using short, token-efficient phrasing helps clear out dense walls of conversational text. He uses the high-focus hours of the morning to set up structured plans, so that he can simply manage and coordinate agents through shorter prompts later in the day.\n\n### Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads\n\nJohn notes he uninstalled beads because its state-retention behavior felt too aggressive for his daily workflows. He prefers to leave the native client harness memory settings turned on. While native platforms occasionally push problematic state updates, they typically course-correct quickly. He adds that he has built several bespoke setups (like an asset called Basic Memory), but chooses to trust native client systems to handle long-term context state over the long run.\n\n### Do you mind your own conversations? Do you have anything that goes in and… Create skills, or… or reflects on… Your conversations, it automatically improves.\n\nJohn states he intends to demonstrate specific automated pipeline patterns and custom plugins designed exactly for conversational reflex analysis later during the workshop session.\n\n## Operational playbooks\n\n- [Agent-managed memory folders](/topics/foundations-agent-memory-playbook/)\n\n- [CMUX Orchestration Field Guide](/topics/foundations-cmux-orchestration-field-guide/)\n- [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-03.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-03.html)\n\n### Visual reference index\n\n- [00:54:26](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-1): Terminal view showing hidden agent notes and goals directory setup steps\n- [00:54:48](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-2): System configuration screen depicting global gitignore assignment prompt syntax\n- [00:56:40](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-3): Markdown planning layout utilizing a numbered and indexed choice matrix\n- [00:59:14](https://codex-workshop-followup.pages.dev/lesson-03.html#clip-03-4): Browser output interface rendering the interactive line-editing trainer application tool\n- [00:59:58](https://codex-workshop-followup.pages.dev/lesson-03.html): Selection screen choosing Forever Mode navigation parameters within the trainer workspace\n- [01:02:38](https://codex-workshop-followup.pages.dev/lesson-03.html): CMUX command menu modal invoked via terminal macro short sequence\n- [01:02:53](https://codex-workshop-followup.pages.dev/lesson-03.html): Split screen layout tracking active shell setup file edits inside secondary console split\n- [01:03:06](https://codex-workshop-followup.pages.dev/lesson-03.html): Simultaneous active session view displaying embedded inline instance of LazyGit terminal client\n- [01:04:19](https://codex-workshop-followup.pages.dev/lesson-03.html): Quick Markdown visualization component displaying project README document\n- [01:05:38](https://codex-workshop-followup.pages.dev/lesson-03.html): Triple column workstation view with active workspace file manager and centralized auto-refresh tracking chart"
    },
    {
      "id": "foundations-oracle-packx-field-guide",
      "slug": "oracle-packx-field-guide",
      "title": "Oracle + PackX Handoff Field Guide",
      "summary": "Spend Codex on implementation, not on reading 500K tokens of context.",
      "category": "Context",
      "tags": [
        "field guide",
        "oracle packx"
      ],
      "sources": [
        {
          "label": "Agent foundations: Route large codebase questions through Oracle (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-01.html"
        },
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#oracle-packx/overview",
        "field-guides/guides.mjs#oracle-packx/quote",
        "field-guides/guides.mjs#oracle-packx/decision",
        "field-guides/guides.mjs#oracle-packx/agentPrompt",
        "field-guides/guides.mjs#oracle-packx/stories",
        "field-guides/guides.mjs#oracle-packx/tips",
        "field-guides/guides.mjs#oracle-packx/refs"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 380,
      "url": "/topics/foundations-oracle-packx-field-guide/",
      "markdownUrl": "/markdown/foundations-oracle-packx-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-oracle-packx-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "stale-test-suite-migration",
          "text": "Stale test-suite migration",
          "level": 3
        },
        {
          "id": "architecture-consistency-audit",
          "text": "Architecture consistency audit",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Oracle + PackX Handoff Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nSpend Codex on implementation, not on reading 500K tokens of context.\n\nUse this when the hard part is broad context synthesis and Codex should bring back an implementation-ready plan.\n\n> Use Oracle with a codebase.\n\n[Workshop transcript](https://askoracle.sh/)\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| PackX preview | Before any large handoff | Verify files and token estimate | ~/.oracle/bundles/<slug>.txt |\n| Browser Oracle | Expensive broad reasoning | Upload bundle to ChatGPT browser mode | ~/.oracle/sessions/<slug>/output.log |\n| Codex implementation | After plan returns | Patch, test, verify, summarize | .notes/<task>/verification.md |\n\n## Agent-ready prompt\n\n```text\nUse Oracle + PackX for this broad codebase question.\nPreview the bundle first.\nBuild a markdown bundle under ~/.oracle/bundles/<slug>.txt.\nRun Oracle in browser mode with a 3-5 word slug.\nRead the full Oracle output, write a local plan, implement the first shippable slice, and verify locally before asking Oracle again.\n```\n\n## Applied stories\n\n### Stale test-suite migration\n\n**Role:** Senior engineer\n\nHundreds of tests need classification into keep, rewrite, browser QA, or delete.\n\n**Agent brief:** Pack tests, source owners, failures, and CI logs; ask Oracle for a migration plan; Codex implements one bucket at a time.\n\n**Done when:**\n\n- bundle path\n- Oracle plan\n- migration goal file\n- first verified slice\n\n### Architecture consistency audit\n\n**Role:** Tech lead\n\nA repo has several competing patterns and nobody knows the current owner path.\n\n**Agent brief:** Bundle current source and docs, ask Oracle for live owner paths and invariants, then patch docs and tests locally.\n\n**Done when:**\n\n- owner map\n- invariant list\n- docs patch\n- verification commands\n\n## Tips and gotchas\n\n- Preview before packing so the handoff is intentional.\n- Keep Oracle text-only; the local agent owns artifacts and commits.\n- Do not ask Oracle again on the same topic until you implemented, verified, hit a blocker, or narrowed scope.\n- Preserve the session slug and output path for auditability.\n\n## References\n\n- [Oracle](https://askoracle.sh/)\n- [Oracle GitHub](https://github.com/johnlindquist/oracle)\n- [PackX npm](https://www.npmjs.com/package/packx)\n\n## Related principles\n\n- [Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n- [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)"
    },
    {
      "id": "foundations-oracle-handoff-playbook",
      "slug": "oracle-handoff-playbook",
      "title": "Oracle handoff for a huge codebase question playbook",
      "summary": "Working web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.",
      "category": "Context",
      "tags": [
        "Oracle",
        "PackX",
        "context",
        "quota",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Route large codebase questions through Oracle (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-01.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#oracle-handoff",
        "scenarios/oracle-handoff.json#audienceFit",
        "toolkit/prompts/01-oracle-codebase-handoff-prompt.md",
        "toolkit/codex-skills/oracle-codebase-handoff/SKILL.md",
        "scenarios/oracle-handoff.json#scenarios/0",
        "scenarios/oracle-handoff.json#scenarios/1",
        "scenarios/oracle-handoff.json#scenarios/2",
        "scenarios/oracle-handoff.json#implementationNotes",
        "scenarios/oracle-handoff.json#notTaughtOrAvoid/1",
        "scenarios/oracle-handoff.json#notTaughtOrAvoid/2",
        "scenarios/oracle-handoff.json#notTaughtOrAvoid/3",
        "scenarios/oracle-handoff.json#notTaughtOrAvoid/4",
        "scenarios/oracle-handoff.json#notTaughtOrAvoid/5",
        "scenarios/oracle-handoff.json#agentReferences",
        "toolkit/bundles/code-oracle-packx.md"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 3431,
      "url": "/topics/foundations-oracle-handoff-playbook/",
      "markdownUrl": "/markdown/foundations-oracle-handoff-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-oracle-handoff-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "unblock-a-tangled-next-js-auth-redirect-bug",
          "text": "Unblock a tangled Next.js auth redirect bug",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "find-the-real-owner-of-a-checkout-state-bug",
          "text": "Find the real owner of a checkout state bug",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "map-a-legacy-migration-before-touching-code",
          "text": "Map a legacy migration before touching code",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "oracle-codebase-handoff-prompt",
          "text": "Oracle codebase handoff prompt",
          "level": 3
        },
        {
          "id": "oracle-codebase-handoff-codex-skill",
          "text": "Oracle codebase handoff Codex skill",
          "level": 3
        },
        {
          "id": "verified-oracle-packx-command-surface",
          "text": "Verified Oracle + PackX command surface",
          "level": 3
        },
        {
          "id": "lesson-01-validated-references",
          "text": "Lesson 01 validated references",
          "level": 3
        },
        {
          "id": "packx-preview-command",
          "text": "PackX preview command",
          "level": 3
        },
        {
          "id": "packx-bundle-command",
          "text": "PackX bundle command",
          "level": 3
        },
        {
          "id": "oracle-browser-handoff-command",
          "text": "Oracle browser handoff command",
          "level": 3
        },
        {
          "id": "cmux-browser-local-verification-surface",
          "text": "CMUX browser/local verification surface",
          "level": 3
        },
        {
          "id": "command-reference",
          "text": "Command reference",
          "level": 2
        },
        {
          "id": "oracle-cli-browser-handoff-verified-flags",
          "text": "Oracle CLI (browser handoff) — verified flags",
          "level": 2
        },
        {
          "id": "packx-context-bundling-verified-flags-from-packx-help",
          "text": "PackX (context bundling) — verified flags from `packx --help`",
          "level": 2
        },
        {
          "id": "mcp-equivalent",
          "text": "MCP equivalent",
          "level": 2
        }
      ],
      "markdown": "# Oracle handoff for a huge codebase question playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWorking web developers routinely hit questions that are too broad for a local coding-agent thread: auth architecture, route ownership, stale data bugs, migration blast radius, or a tangled UI flow. Oracle handoff keeps Codex focused on local implementation while a browser ChatGPT Pro session reads the huge PackX bundle and returns a plan the agent can verify in the running app.\n\n[Core principles](/topics/foundations-oracle-context-routing/)\n\n## Copy-paste workflow\n\n**When to use:** When a read-heavy question spans a large codebase and would burn your Codex token/rate budget. Offload the heavy analysis to a browser ChatGPT Pro Extended Thinking session via Oracle + PackX, then bring the returned plan back into Codex and implement locally.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. I have a large, read-heavy question about this codebase and I want to offload the heavy analysis to a browser ChatGPT Pro session via Oracle + PackX instead of burning local tokens. Follow these steps exactly and do not skip the preview.\n\n1. Bundle the relevant files with PackX. First PREVIEW so we see what gets included and the token estimate:\n     packx --preview -s \"<TOPIC>\"\n   When the preview looks right, write the bundle:\n     packx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n\n2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words:\n     ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \\\n       -p \"<THE BIG ANALYSIS QUESTION>\" \\\n       --slug \"<3-5-word-kebab-slug>\" \\\n       --write-output .notes/oracle-plan.md \\\n       --file .notes/handoff-bundle.md\n\n3. Read .notes/oracle-plan.md, then implement the plan locally and verify (run the tests/build). Treat this as a plan -> implement -> verify loop.\n\nGuardrail: keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.\n```\n\n### How it works\n- `packx --preview -s \"<TOPIC>\"` shows the matched files and a token estimate before you commit — always preview first so the bundle is scoped, not bloated.\n- `packx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md` writes a scripted markdown bundle (no prompts).\n- `oracle --engine browser --browser-thinking-time extended` drives ChatGPT Pro in the browser with extended thinking; `--write-output` saves ONLY the final assistant message, and `--file` attaches the bundle (cap raised via `ORACLE_MAX_FILE_SIZE_BYTES=12000000`).\n- The `--slug` must be 3-5 kebab words or Oracle rejects it.\n- The returned plan is the durable artifact: read it back into Codex, implement, then verify. Keep concurrency low (2-3 browser requests) to stay within ChatGPT Pro limits.\n- Reference: [John's Oracle fork](https://github.com/johnlindquist/oracle), [PackX](https://www.npmjs.com/package/packx).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/oracle-codebase-handoff/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: oracle-codebase-handoff\ndescription: Trigger when a read-heavy question spans a large codebase and would burn Codex token/rate budget — offload heavy analysis to a browser ChatGPT Pro session via Oracle + PackX, then resume implementation locally. Do NOT trigger for small, local edits.\n---\n\n# Oracle codebase handoff\n\nOffload a big, read-heavy codebase analysis to a browser ChatGPT Pro session via Oracle + PackX, then bring the plan back and implement locally. Run as a plan -> implement -> verify loop.\n\n## Steps\n\n1. Bundle the relevant files with PackX. PREVIEW first to confirm scope and token estimate, then write the bundle:\n   ```bash\n   packx --preview -s \"<topic>\"\n   packx -s \"<topic>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n   ```\n   `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first; use `--no-interactive` for scripted bundles.\n\n2. Send the bundle to ChatGPT Pro in the browser with extended thinking. The slug MUST be 3-5 kebab words, and the prompt text must start with `[<slug>]` on line 1, a blank line, then the question:\n   ```bash\n   ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended \\\n     -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" \\\n     --slug \"<3-5-word-kebab-slug>\" \\\n     --write-output .notes/oracle-plan.md \\\n     --file .notes/handoff-bundle.md\n   ```\n   - `--engine browser` automates ChatGPT in the browser (GPT models).\n   - `--browser-thinking-time extended` sets ChatGPT thinking time (light|standard|extended|heavy).\n   - `--write-output` writes ONLY the final assistant message.\n   - `--file` attaches the bundle (size cap raised via `ORACLE_MAX_FILE_SIZE_BYTES`).\n\n3. Read `.notes/oracle-plan.md`, then implement the plan locally and verify (tests/build).\n\n## Guardrails\n- Slug MUST be 3-5 kebab words or Oracle rejects it.\n- Keep browser concurrency LOW — no more than 2-3 Oracle browser requests at once.\n- Do NOT use this for small, local edits — only for read-heavy, large-codebase questions.\n````\n\n## Scenarios\n\n### Unblock a tangled Next.js auth redirect bug\n\n**Role:** As a senior full-stack web developer owning a Next.js app\n\nA production-like local Next.js app has a login redirect loop that only appears after mixing middleware, server components, API route auth checks, and client-side session refresh. The issue spans many files, so asking Codex to read everything directly would burn the interactive session budget.\n\n> As a senior full-stack web developer, I want Codex to offload the broad auth-flow investigation through Oracle and PackX, so that Codex can spend its local context on implementing and verifying the fix instead of reading the whole repo.\n\n#### Agent brief\n\n```text\nYou are my coding agent in this repo. Investigate the auth redirect loop by using the Oracle codebase handoff workflow, then implement only the locally verifiable fix. Do not skip the PackX preview. Create `.notes/` if needed. First run `packx --preview -s \"Next.js auth redirect middleware session login callback API route\"` and inspect the matched files and token estimate. If the scope is reasonable, run `packx -s \"Next.js auth redirect middleware session login callback API route\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then send the bundle through Oracle browser mode with a 3-5 word kebab slug, and make the prompt start with the same bracketed slug on line 1: `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[auth-redirect-loop]\\n\\nWe have a Next.js auth redirect loop. Read the attached PackX bundle and produce: 1) the likely root cause, 2) the exact files/functions to inspect first, 3) a minimal implementation plan, 4) local verification steps using the dev server/browser, and 5) risks or false leads to avoid. Do not propose unrelated rewrites.\" --slug \"auth-redirect-loop\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, read `.notes/oracle-plan.md`, summarize the recommended fix in `.notes/auth-redirect-receipt.md`, implement the smallest safe change, then run the repo's existing typecheck/test/build command discovered from package scripts. Finally start the local dev server and verify the login flow in a browser.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"Next.js auth redirect middleware session login callback API route\"\n```\n\n```text\npackx -s \"Next.js auth redirect middleware session login callback API route\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[auth-redirect-loop]\\n\\n<question>\" --slug \"auth-redirect-loop\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nUse the running local app as proof, not source-code confidence. In a CMUX browser pane or browser-agent workflow, open the dev server, capture an accessibility snapshot of the login page, click the sign-in control, fill the test credentials or scripted local auth fields, submit, and evaluate `window.location.pathname` plus visible authenticated UI text. Save a screenshot or browser transcript showing the flow reaches the expected post-login route without bouncing back to `/login`.\n\n#### Definition of done\n\n- .notes/oracle-plan.md exists and contains the browser-side Oracle recommendation\n- .notes/auth-redirect-receipt.md records the selected fix, files changed, and why alternatives were rejected\n- Repo verification command passes, such as test/typecheck/build from package scripts\n- Browser proof shows login reaches the expected authenticated route without a redirect loop\n- Git diff is limited to the auth-related fix and does not include `.notes/` artifacts\n\n#### Failure modes and mitigations\n\n- Mistake: using Oracle before previewing the bundle, causing a bloated or irrelevant handoff. Mitigation: require `packx --preview` first and adjust the search topic before writing `.notes/handoff-bundle.md`.\n- Mistake: implementing the whole Oracle plan as if it were guaranteed correct. Mitigation: treat `.notes/oracle-plan.md` as a plan, then implement the smallest locally verifiable change and prove it in the browser.\n- Mistake: using a slug that Oracle rejects. Mitigation: use exactly 3-5 kebab words and start the prompt with `[same-slug]` followed by a blank line.\n- Mistake: trusting unit tests for a browser-only redirect bug. Mitigation: require browser proof against the running dev server.\n\n### Find the real owner of a checkout state bug\n\n**Role:** As a product engineer maintaining a checkout funnel\n\nA React or Remix checkout page loses cart state when the user changes shipping method, navigates back, or refreshes after payment intent creation. The logic is split across route loaders/actions, client state, server API handlers, and payment integration code.\n\n> As a product engineer, I want a huge-context Oracle pass to map the checkout state ownership and failure points, so that my local agent can make a targeted fix and prove the checkout flow in the browser.\n\n#### Agent brief\n\n```text\nYou are my coding agent. Use Oracle + PackX only for the broad read-heavy diagnosis, then return to local implementation and verification. Create `.notes/` if needed. Run `packx --preview -s \"checkout cart state shipping method payment intent loader action API\"`. Review the preview for checkout routes, cart/session modules, API handlers, and payment-related files. If relevant, run `packx -s \"checkout cart state shipping method payment intent loader action API\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[checkout-state-owner]\\n\\nRead the attached checkout-related codebase bundle. Identify which layer should own checkout/cart state, where the current flow can lose state during shipping changes, browser back navigation, refresh, or payment intent creation, and propose the smallest fix. Return exact file/function references, a step-by-step implementation plan, and browser verification steps. Avoid broad architecture rewrites unless the current code makes a minimal fix unsafe.\" --slug \"checkout-state-owner\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. Read the returned plan, write `.notes/checkout-handoff-receipt.md` with the chosen path, implement the minimal fix, then run existing tests/build. If the repo has no browser test, use the dev server plus a browser-agent or CMUX browser pane to verify the funnel manually and record evidence.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"checkout cart state shipping method payment intent loader action API\"\n```\n\n```text\npackx -s \"checkout cart state shipping method payment intent loader action API\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[checkout-state-owner]\\n\\n<question>\" --slug \"checkout-state-owner\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nUse browser verification because this bug is about real user navigation. In the local app, open the checkout route, capture a snapshot of cart line items and total, click through shipping method changes, use back/forward navigation, refresh once after the payment-intent step if safe in the local/test environment, and evaluate the visible cart total plus any checkout state exposed in the page. Save a screenshot or transcript proving the cart survives the exact sequence.\n\n#### Definition of done\n\n- PackX preview was inspected before bundle creation\n- .notes/oracle-plan.md contains a file/function-level checkout state diagnosis\n- .notes/checkout-handoff-receipt.md names the selected minimal fix and verification sequence\n- Existing repo checks pass\n- Browser proof shows the checkout state survives shipping change, back navigation, and refresh in the local/test flow\n\n#### Failure modes and mitigations\n\n- Mistake: asking Oracle for a generic checkout redesign. Mitigation: phrase the Oracle prompt around state ownership, exact failure paths, minimal fix, and browser proof.\n- Mistake: including live secrets, customer data, or real payment credentials in logs or screenshots. Mitigation: use local/test data only and redact artifacts before saving.\n- Mistake: letting Codex use Oracle for every small follow-up. Mitigation: use Oracle once for the broad read-heavy map, then continue locally unless another huge-codebase question appears.\n- Mistake: verifying only the happy path. Mitigation: require the back/refresh/shipping-change sequence that reproduced the bug.\n\n### Map a legacy migration before touching code\n\n**Role:** As a tech lead planning a risky front-end migration\n\nA large web app is moving one feature area from legacy pages to a newer app-router or component architecture. The team needs to know which files, routes, shared utilities, and tests are involved before assigning implementation work.\n\n> As a tech lead, I want an Oracle handoff to produce a migration map from the current codebase, so that the implementation agent can work from a grounded plan and avoid guessing across many files.\n\n#### Agent brief\n\n```text\nYou are my coding agent. This is a read-heavy migration-mapping task, so use Oracle handoff first and do not edit source files until the returned plan is reviewed. Create `.notes/` if needed. Run `packx --preview -s \"legacy feature migration routes components shared utilities tests\"`. If the preview includes the expected legacy feature area, run `packx -s \"legacy feature migration routes components shared utilities tests\" -f markdown --no-interactive -o .notes/handoff-bundle.md`. Then run `ORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[legacy-migration-map]\\n\\nRead the attached PackX bundle for a large web app migration. Produce an implementation-ready migration map: current entry points, route/page ownership, shared components/utilities, test/build commands to run, risky coupling points, safe first slice, and a plan -> implement -> verify sequence. Do not invent tools or recommend a broad rewrite; stay grounded in the attached code.\" --slug \"legacy-migration-map\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md`. After Oracle returns, create `.notes/migration-slice-receipt.md` with the first safe slice, explicit files to edit, verification commands, and browser proof needed. Implement only that first slice if it is small enough; otherwise stop with the migration map and receipt for human review.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-oracle-context-routing/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n```text\npackx --preview -s \"legacy feature migration routes components shared utilities tests\"\n```\n\n```text\npackx -s \"legacy feature migration routes components shared utilities tests\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[legacy-migration-map]\\n\\n<question>\" --slug \"legacy-migration-map\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n#### Browser verification\n\nBrowser proof is useful only after a concrete migration slice exists. For the planning-only phase, the right proof is `.notes/oracle-plan.md` plus a migration receipt. If implementing the first slice, open old and new routes in a local browser or CMUX browser pane, capture snapshots/screenshots of the same user-visible state, click the primary controls, and confirm the migrated route preserves the expected behavior.\n\n#### Definition of done\n\n- .notes/oracle-plan.md exists and maps entry points, route ownership, shared utilities, risks, and first safe slice\n- .notes/migration-slice-receipt.md converts the Oracle recommendation into a local implementation decision\n- No source files are changed unless the first slice is explicitly small and verifiable\n- If a slice is implemented, existing checks pass and browser comparison proof exists for old versus new route behavior\n- The final review artifact names what remains out of scope\n\n#### Failure modes and mitigations\n\n- Mistake: turning a migration map into a giant unreviewed rewrite. Mitigation: require a first safe slice and stop for review if the change is not small and verifiable.\n- Mistake: packing the entire repo without topic discipline. Mitigation: preview with a migration-specific search phrase and narrow before writing the bundle.\n- Mistake: treating Oracle's output as fresh repo truth after code changes. Mitigation: once implementation begins, inspect current files locally and verify against the running app.\n- Mistake: using browser proof too early. Mitigation: use browser proof after a concrete UI slice exists; use the Oracle plan and receipt as planning proof before edits.\n\n## Implementation notes\n\n- Use Oracle only for read-heavy, large-codebase analysis. Small local edits should stay in Codex without the browser handoff.\n- Always preview PackX output before writing `.notes/handoff-bundle.md`; the preview is the quality gate for scope and token cost.\n- The Oracle slug must be 3-5 kebab words, and the prompt must start with `[same-slug]`, then a blank line, then the question.\n- Keep browser concurrency low: no more than two or three Oracle browser requests at once.\n- Treat `.notes/oracle-plan.md` as a planning artifact, not a commandment. The local agent still has to inspect current files, implement the smallest safe slice, and verify with tests/build/browser proof.\n- Keep `.notes/` artifacts local working files. Do not commit Oracle bundles or plans unless the repo deliberately wants them.\n- For browser proof, prefer user-visible receipts: screenshot, accessibility snapshot, console-free run, route/path evaluation, or a short transcript of click/fill/evaluate steps.\n- Do not put secrets, customer data, real payment credentials, or private cookies into PackX bundles, logs, browser screenshots, or `.notes/` receipts.\n\n## Boundaries and caveats\n\n- Do not introduce NotebookLM as part of this Oracle workflow; it was not retained as a taught workflow for this topic.\n- Do not add a generic API/manual-copy lane as if it were taught here; keep the workflow centered on Oracle + PackX + browser handoff.\n- Do not claim browser-side work is permanently unlimited, free, or policy-proof. Frame quota behavior as the workshop setup and keep concurrency conservative.\n- Do not use Oracle to bypass normal local verification. The final proof still comes from tests, build logs, and the running web app.\n- Do not invent unverified CMUX, PackX, or Oracle flags. Use the verified command shapes in the command reference.\n\n## Agent reference map\n\n### Oracle codebase handoff prompt\n\nUse this as the copy-paste workflow shape for PackX preview, PackX bundle creation, Oracle browser handoff, returned-plan file, and local verification loop.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n### Oracle codebase handoff Codex skill\n\nUse this when the local agent needs the strict runnable version: preview first, slug rules, prompt prefix, `--write-output`, `--file`, and plan -> implement -> verify.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/)\n\n### Verified Oracle + PackX command surface\n\nUse this to avoid inventing flags. It includes the verified `oracle --engine browser --browser-thinking-time extended` command, `ORACLE_MAX_FILE_SIZE_BYTES`, PackX preview/write commands, token-limit notes, and slug rules.\n\n[Open reference](/topics/foundations-oracle-handoff-playbook/#command-reference)\n\n### Lesson 01 validated references\n\nUse this as the taught-source boundary for the Oracle topic: Codex-to-browser quota offloading, ChatGPT Pro Extended as a high-context browser surface, PackX context bundling, MCP/browser bridge, low concurrency, and plan -> implement -> verify.\n\n[Open reference](/topics/foundations-oracle-context-routing/)\n\n### PackX preview command\n\nRun before writing any bundle so the agent can check matched files and token estimate instead of blindly sending irrelevant context.\n\n```text\npackx --preview -s \"<TOPIC>\"\n```\n\n### PackX bundle command\n\nWrite the relevant codebase context into a model-readable markdown file that Oracle can attach.\n\n```text\npackx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\n```\n\n### Oracle browser handoff command\n\nSend the PackX bundle to browser ChatGPT with extended thinking and save only the final assistant message to a local plan file.\n\n```text\nORACLE_MAX_FILE_SIZE_BYTES=12000000 oracle --engine browser --browser-thinking-time extended -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" --slug \"<3-5-word-kebab-slug>\" --write-output .notes/oracle-plan.md --file .notes/handoff-bundle.md\n```\n\n### CMUX browser/local verification surface\n\nUse a browser pane or browser-agent-style workflow to prove web app behavior after local implementation, especially login, checkout, navigation, and route migration flows.\n\n```text\ncmux --json tree; cmux read-screen; local dev server URL from repo package scripts\n```\n\n## Command reference\n\nThese command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.\n\n## Oracle CLI (browser handoff) — verified flags\n```bash\nORACLE_MAX_FILE_SIZE_BYTES=12000000 \\\noracle --engine browser --browser-thinking-time extended \\\n  -p \"[<3-5-word-kebab-slug>]\\n\\n<the big analysis question>\" \\\n  --slug \"<3-5-word-kebab-slug>\" \\\n  --write-output .notes/oracle-plan.md \\\n  --file .notes/handoff-bundle.md\n```\nVerified options (from `oracle --help` and the Oracle source):\n- `--engine browser` — automate ChatGPT in the browser (GPT models). Default picks api when OPENAI_API_KEY set, else browser.\n- `--browser-thinking-time <light|standard|extended|heavy>` — ChatGPT thinking time (source: src/cli/browserConfig.ts, src/mcp/types.ts).\n- `--write-output <path>` — write ONLY the final assistant message to a file.\n- `--slug \"<words>\"` — session slug, MUST be 3-5 words.\n- `--file <paths...>` — attach files/dirs/globs (cap configurable via `ORACLE_MAX_FILE_SIZE_BYTES`).\n- `--browser-attachments <auto|never|always>`, `--browser-bundle-files` — control upload behavior.\n\nSlug rule (validated): 3-5 kebab words. The oracle prompt text MUST start with `[<slug>]` on line 1, blank line, then the prompt.\n\n## PackX (context bundling) — verified flags from `packx --help`\n```bash\npackx --preview -s \"<TOPIC>\"                                   # preview matching files + token estimate FIRST\npackx -s \"<TOPIC>\" -f markdown --no-interactive -o .notes/handoff-bundle.md\npackx <PATH> -i \"*.ts\" --no-interactive -o bundle.md          # positional path + glob include\npackx --diff -f markdown --no-interactive -o bundle.md         # only files changed from main\npackx --staged ...  | --dirty ...                              # staged-only / modified+untracked\npackx FILTERS --limit 900k -f markdown --no-interactive -o bundle.md   # token budget\npackx FILTERS --strip-comments --minify ...                    # compressed bundle\npackx FILTERS -M 32k                                           # split into chunks\npackx --no-packignore <DOTFILE_PATH>                           # include dotfiles / ignored paths\n```\nKey rules: `-i` is a name/extension GLOB, not a path selector — pass a known file/dir POSITIONALLY. Always `--preview` first. Use `--no-interactive` for scripted bundles. Formats: xml (default), markdown, plain, jsonl.\n\n## MCP equivalent\n`mcp__oracle__consult` with `engine: \"browser\"`, `slug`, `browserThinkingTime: \"extended\"`, `files`, `browserAttachments`. The packx bundle goes in `~/.oracle/bundles/{slug}.txt`; output in `~/.oracle/sessions/{slug}/output.log`. Browser-mode bundle target up to ~900k tokens. Keep concurrency low (2-3 browser requests max)."
    },
    {
      "id": "codex-browser-bridge",
      "slug": "browser-bridge",
      "title": "Pack local context for a browser review",
      "summary": "Your local agent is good at doing work inside the repo. The harder part is deciding what work should happen next when the answer depends on a lot of project context. This pattern uses PackX to turn a project into a focused context packet, Oracle to move…",
      "category": "Context",
      "tags": [
        "oracle",
        "packx",
        "context"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#browser-bridge"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/oracle-packx-browser-bridge.md",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass/The Role Split",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass/Pack Deliberately",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass/Use A Real Browser Session",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass/Verify Before Trusting",
        "src/content/final/oracle-packx-browser-bridge.md#The Browser Bridge: Pack Local Context, Ask A Browser Review Pass/What To Save",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#browser-bridge",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 611,
      "url": "/topics/codex-browser-bridge/",
      "markdownUrl": "/markdown/codex-browser-bridge.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-browser-bridge.json",
      "headings": [
        {
          "id": "the-role-split",
          "text": "The Role Split",
          "level": 2
        },
        {
          "id": "pack-deliberately",
          "text": "Pack Deliberately",
          "level": 2
        },
        {
          "id": "use-a-real-browser-session",
          "text": "Use A Real Browser Session",
          "level": 2
        },
        {
          "id": "verify-before-trusting",
          "text": "Verify Before Trusting",
          "level": 2
        },
        {
          "id": "what-to-save",
          "text": "What To Save",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Pack local context for a browser review\n\nYour local agent is good at doing work inside the repo. The harder part is deciding what work should happen next when the answer depends on a lot of project context. This pattern uses **[PackX](https://www.npmjs.com/package/packx)** to turn a project into a **focused context packet**, **[Oracle](https://github.com/johnlindquist/oracle)** to move that packet into a signed-in browser session, and a local **[Codex](https://developers.openai.com/codex)** session to turn the result back into edits, checks, and follow-up work.\n\n> It's so worth getting set up, like, it's worth sacrificing a day or two to get this locked in. So that you unlock, like, the next level of intelligence, and allow your local models to be more of workers than researchers or thinkers or reasoners.\n>\n> — John Lindquist\n\n## The Role Split\n\n- Local Codex is the worker: it inspects files, edits code, runs commands, and saves the outcome.\n- PackX prepares the context packet: it selects the project files, references, and setup material that matter for the question.\n- Oracle is the bridge: it carries the packed request into a browser session and brings the answer back.\n- The browser model is the planner, reviewer, or external critique pass: it handles a separate review lane.\n- The local loop owns the result: prompts, answers, verification commands, changed files, and unresolved questions should land back in the repo.\n\n## Pack Deliberately\n\nThe useful part is not \"send everything.\" The useful part is **choosing the files that make the question answerable** while leaving out unrelated output, secrets, logs, cookies, generated directories, and private local config.\n\nUse the bundled Oracle PackX skill when the question needs broad project context and a separate browser review pass. Keep exact flags and browser-mode call shapes in the reviewed skill. Use this mental model:\n\n```text\nproject files + references + skill docs\n  -> PackX bundle\n  -> Oracle browser session\n  -> answer returned to local Codex\n  -> edits, checks, and saved follow-up\n```\n\n## Use A Real Browser Session\n\nThe browser bridge depends on a **signed-in browser session**. That browser can run in the same environment as the repo, or in a **separate VM, container, or remote environment** so the local development loop stays usable while the browser lane runs.\n\n> I know this sounds like a very complicated setup, and it probably will take, take a while for you to figure out exactly how this would work for you and whatever system you have. But the payoff for it is immense.\n>\n> — John Lindquist\n\nKeep this boundary boring and explicit:\n\n- Do not share browser history, account sidebars, profile menus, cookies, tokens, private endpoints, hostnames, ports, or local usernames.\n- Do not make a private account setup look like a public requirement.\n- Do not promise a specific model name, price, quota, or plan behavior unless it has been checked immediately before sharing setup guidance.\n\n## Verify Before Trusting\n\nCheck the current package name, install command, browser session, hosted links, and model labels before relying on saved setup notes.\n\nBefore sharing exact install guidance, save a dated package-name check:\n\n```bash\nnpm view packx name version bin dist-tags --json\n```\n\nUse the dated check to confirm the package name, binary names, and current version. **Do not reuse install commands from old notes** without checking them.\n\n## What To Save\n\nSave enough context that the decision can be checked later:\n\n- bundle path\n- prompt\n- browser/model route used\n- answer\n- verification command\n- files changed because of the answer\n- unresolved claims or follow-ups\n\n**No saved check, no claim.**\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#browser-bridge)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "factory-continuity",
      "slug": "continuity",
      "title": "Recover state before continuing",
      "summary": "Use history to locate evidence, then rebuild a minimal trustworthy handoff from the current tree and artifacts.",
      "category": "Context",
      "tags": [
        "continuity",
        "history",
        "handoff"
      ],
      "sources": [
        {
          "label": "Continuity lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover"
        }
      ],
      "sourceUnits": [
        "learn.html#q3-continuity-recover"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 216,
      "url": "/topics/factory-continuity/",
      "markdownUrl": "/markdown/factory-continuity.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-continuity.json",
      "headings": [
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "recover-state-before-continuing",
          "text": "Recover state before continuing",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Recover state before continuing\n\nUse history to locate evidence, then rebuild a minimal trustworthy handoff from the current tree and artifacts.\n\n## Operating practice\n\n### Recover state before continuing\n\n#### What to notice\n\nReconstruct the smallest **trustworthy state packet** instead of asking a new session to absorb stale scrollback.\n\n#### Try this\n\nCapture objective, current tree, **last verified result**, settled decisions, open risks, next action, and its success check.\n\n> “Just ask the agent, or ask yourself: how could I break this into a smaller task?”\n\nJohn Lindquist · [04:28:49](https://proud-anchor-53zn.here.now/watch.html?t=16129#recording-player)\n\n#### Concept\n\nHistory tells you where to look. The working tree, commits, tests, files, and generated artifacts tell you what is true. End long runs with one named verification so the next session inherits evidence, not confidence.\n\n#### Reflection\n\nAn old continuity file can be worse than no file because it looks authoritative. Recheck it against current state.\n\n**Recording evidence:** listen at 04:20:03.\n\n> “So it has a context bundle to work against.”\n\nJohn Lindquist · [04:31:03](https://proud-anchor-53zn.here.now/watch.html?t=16263#recording-player)\n\n#### Links shared for this topic\n\n- [Screenpipe](https://screenpipe.com/) — Local activity capture for searchable work context.\n- [Pieces](https://pieces.app/) — A developer work-memory and context product.\n- [Atuin](https://atuin.sh/) — Searchable shell history across sessions and machines.\n- [CASS skill](https://jeffreys-skills.md/skills/cass) — A skill interface for coding-agent session search.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=15603#q3-continuity-recover)"
    },
    {
      "id": "factory-continuity-discussion",
      "slug": "continuity-discussion",
      "title": "Recover state before continuing — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Context",
      "tags": [
        "continuity",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[138]",
        "resource-manifest.json#videoEvidence.concepts[139]",
        "resource-manifest.json#videoEvidence.concepts[140]",
        "resource-manifest.json#videoEvidence.concepts[141]",
        "resource-manifest.json#videoEvidence.concepts[142]",
        "resource-manifest.json#videoEvidence.concepts[143]",
        "resource-manifest.json#videoEvidence.concepts[144]",
        "resource-manifest.json#videoEvidence.concepts[145]",
        "resource-manifest.json#videoEvidence.concepts[146]",
        "resource-manifest.json#videoEvidence.concepts[147]",
        "resource-manifest.json#videoEvidence.concepts[148]",
        "resource-manifest.json#videoEvidence.concepts[149]",
        "resource-manifest.json#videoEvidence.concepts[150]",
        "resource-manifest.json#videoEvidence.concepts[151]",
        "resource-manifest.json#videoEvidence.concepts[152]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[46]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[47]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[48]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[49]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[50]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[51]",
        "resource-manifest.json#videoEvidence.timeline[660]",
        "resource-manifest.json#videoEvidence.timeline[662]",
        "resource-manifest.json#videoEvidence.timeline[663]",
        "resource-manifest.json#videoEvidence.timeline[664]",
        "resource-manifest.json#videoEvidence.timeline[665]",
        "resource-manifest.json#videoEvidence.timeline[666]",
        "resource-manifest.json#videoEvidence.timeline[669]",
        "resource-manifest.json#videoEvidence.timeline[670]",
        "resource-manifest.json#videoEvidence.timeline[672]",
        "resource-manifest.json#videoEvidence.timeline[673]",
        "resource-manifest.json#videoEvidence.timeline[674]",
        "resource-manifest.json#videoEvidence.timeline[675]",
        "resource-manifest.json#videoEvidence.timeline[676]",
        "resource-manifest.json#videoEvidence.timeline[677]",
        "resource-manifest.json#videoEvidence.timeline[678]",
        "resource-manifest.json#videoEvidence.timeline[680]",
        "resource-manifest.json#videoEvidence.timeline[681]",
        "resource-manifest.json#videoEvidence.timeline[684]",
        "resource-manifest.json#videoEvidence.timeline[685]",
        "resource-manifest.json#videoEvidence.timeline[686]",
        "resource-manifest.json#videoEvidence.timeline[687]",
        "resource-manifest.json#videoEvidence.timeline[688]",
        "resource-manifest.json#videoEvidence.timeline[689]",
        "resource-manifest.json#videoEvidence.timeline[690]",
        "resource-manifest.json#videoEvidence.timeline[691]",
        "resource-manifest.json#videoEvidence.timeline[692]",
        "resource-manifest.json#videoEvidence.timeline[693]",
        "resource-manifest.json#videoEvidence.timeline[694]",
        "resource-manifest.json#videoEvidence.timeline[695]",
        "resource-manifest.json#videoEvidence.timeline[697]",
        "resource-manifest.json#videoEvidence.timeline[698]",
        "resource-manifest.json#videoEvidence.timeline[700]",
        "resource-manifest.json#videoEvidence.timeline[701]",
        "resource-manifest.json#videoEvidence.timeline[704]",
        "resource-manifest.json#videoEvidence.timeline[705]",
        "resource-manifest.json#videoEvidence.timeline[707]",
        "resource-manifest.json#videoEvidence.timeline[708]",
        "resource-manifest.json#videoEvidence.timeline[715]",
        "resource-manifest.json#videoEvidence.timeline[716]",
        "resource-manifest.json#videoEvidence.timeline[717]",
        "resource-manifest.json#videoEvidence.timeline[718]",
        "resource-manifest.json#videoEvidence.timeline[719]",
        "resource-manifest.json#videoEvidence.uncertainties[43]",
        "resource-manifest.json#videoEvidence.uncertainties[45]",
        "resource-manifest.json#videoEvidence.demos[78]",
        "resource-manifest.json#videoEvidence.demos[79]",
        "resource-manifest.json#videoEvidence.demos[80]",
        "resource-manifest.json#videoEvidence.demos[81]",
        "resource-manifest.json#videoEvidence.demos[82]",
        "resource-manifest.json#videoEvidence.demos[83]",
        "resource-manifest.json#videoEvidence.demos[84]",
        "resource-manifest.json#videoEvidence.demos[85]",
        "resource-manifest.json#videoEvidence.demos[86]",
        "resource-manifest.json#videoEvidence.demos[87]",
        "resource-manifest.json#videoEvidence.demos[88]",
        "resource-manifest.json#videoEvidence.demos[89]"
      ],
      "collection": "factory",
      "categoryId": "context",
      "wordCount": 2447,
      "url": "/topics/factory-continuity-discussion/",
      "markdownUrl": "/markdown/factory-continuity-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-continuity-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "terminal-history-management-with-atuin",
          "text": "Terminal History Management with Atuin",
          "level": 3
        },
        {
          "id": "agentic-continuity-through-history-inspection",
          "text": "Agentic Continuity through History Inspection",
          "level": 3
        },
        {
          "id": "human-centric-vs-agent-centric-data-formats",
          "text": "Human-Centric vs. Agent-Centric Data Formats",
          "level": 3
        },
        {
          "id": "recomputation-vs-persistence-trade-off",
          "text": "Recomputation vs. Persistence Trade-Off",
          "level": 3
        },
        {
          "id": "orchestration-task-breakdown",
          "text": "Orchestration & Task Breakdown",
          "level": 3
        },
        {
          "id": "context-compaction",
          "text": "Context Compaction",
          "level": 3
        },
        {
          "id": "token-efficiency",
          "text": "Token Efficiency",
          "level": 3
        },
        {
          "id": "context-bundle-reference-file",
          "text": "Context Bundle Reference File",
          "level": 3
        },
        {
          "id": "global-gitignore-for-agents",
          "text": "Global Gitignore for Agents",
          "level": 3
        },
        {
          "id": "html-artifacts-for-task-diagnostics",
          "text": "HTML Artifacts for Task Diagnostics",
          "level": 3
        },
        {
          "id": "agent-verification-scripts",
          "text": "Agent Verification Scripts",
          "level": 3
        },
        {
          "id": "codex-lifecycle-hooks",
          "text": "Codex Lifecycle Hooks",
          "level": 3
        },
        {
          "id": "alignment-comparison",
          "text": "Alignment Comparison",
          "level": 3
        },
        {
          "id": "context-compaction-hooks",
          "text": "Context Compaction Hooks",
          "level": 3
        },
        {
          "id": "agent-session-indexing",
          "text": "Agent Session Indexing",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "attuin-what-was-the-other-tool-and-why",
          "text": "attuin? what was the other tool and why?",
          "level": 3
        },
        {
          "id": "a-participant-attuin-what-was-the-other-tool-and-why",
          "text": "a participant: attuin? what was the other tool and why?",
          "level": 3
        },
        {
          "id": "elaborate-in-more-detail-on-how-do-you-handle-continuity-for-complex-long-tasks-or-a-series-of-related-tasks-that-may-partially-share-the-same-core-context-or-domain-knowledge-never-what-tools-we-use-to-optimize-the-context-inadvertently-it-drains-out-of-it-at-some-point-not-necessarily-certain-tooling-rather-approach-strategy",
          "text": "Elaborate in more detail on how do you handle continuity for complex long tasks or a series of related tasks that may partially share the same core context or domain knowledge. Never what tools we use to optimize the context inadvertently. It drains out of it at some point. Not necessarily certain tooling, rather approach strategy.",
          "level": 3
        },
        {
          "id": "do-you-have-things-you-do-after-the-task-has-already-bloated-to-recover-and-simplify-do-you-have-things-you-do-when-you-don-t-understand-what-the-agent-has-done-do-you-create-html-artifacts-quizes",
          "text": "do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?",
          "level": 3
        },
        {
          "id": "do-you-have-things-you-do-after-the-task-has-already-bloated-to-recover-and-simplify-do-you-have-things-you-do-when-you-don-t-understand-what-the-agent-has-done-do-you-create-html-artifacts-quizes-2",
          "text": "do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?",
          "level": 3
        },
        {
          "id": "how-can-a-developer-prevent-a-workflow-loop-from-triggering-on-tiny-follow-up-questions",
          "text": "How can a developer prevent a workflow loop from triggering on tiny follow-up questions?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-the-exact-role-or-integration-of-cmux-within-john-s-current-layout-environment",
          "text": "Unresolved: The exact role or integration of CMUX within John's current layout environment.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-tool-hosting-the-claude-agent-panel-execution-logs",
          "text": "Unresolved: The exact tool hosting the Claude agent panel execution logs.",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-20-03",
          "text": "Demonstration detail: 04:20:03",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-21-53",
          "text": "Demonstration detail: 04:21:53",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-22-26",
          "text": "Demonstration detail: 04:22:26",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-23-51",
          "text": "Demonstration detail: 04:23:51",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-24-45",
          "text": "Demonstration detail: 04:24:45",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-27-37",
          "text": "Demonstration detail: 04:27:37",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-28-14",
          "text": "Demonstration detail: 04:28:14",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-31-22",
          "text": "Demonstration detail: 04:31:22",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-31-24",
          "text": "Demonstration detail: 04:31:24",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-34-43",
          "text": "Demonstration detail: 04:34:43",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-37-11",
          "text": "Demonstration detail: 04:37:11",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-40-46",
          "text": "Demonstration detail: 04:40:46",
          "level": 3
        }
      ],
      "markdown": "# Recover state before continuing — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Terminal History Management with Atuin\n\nUtilizing an SQLite-backed shell history database instead of flat files to capture context, commands, and exit codes cleanly across all terminal sessions.\n\n### Agentic Continuity through History Inspection\n\nProviding AI agents access to rich shell history records so they can autonomously identify previous failure states, spin up separate replication panes, and confirm subsequent code corrections.\n\n### Human-Centric vs. Agent-Centric Data Formats\n\nEngineering data structures to match their primary consumers. Human interfaces prioritize inspectability, readability, and mutation capability (like SQLite databases), whereas agent pipelines benefit from highly condensed, stringless, position-indexed graphs optimized for context efficiency.\n\n### Recomputation vs. Persistence Trade-Off\n\nAn architectural standard where derived data layers are left unpersisted on disk if the deterministic build step from source files takes an insignificant duration (e.g., 10 seconds), driving the necessary storage footprint close to zero.\n\n### Orchestration & Task Breakdown\n\nDeconstructing a large, long-running task into discrete, smaller checkpoints managed by independent agent steps or event-driven agent chains.\n\n### Context Compaction\n\nThe dynamic reduction or compression of dialogue history that occurs as an LLM's context window fills up, which can cause an agent to lose tracking of early core knowledge.\n\n### Token Efficiency\n\nAn architectural improvement in advanced models (like Fable or 5.6) that helps agents complete long workflows before triggering context compaction limits.\n\n### Context Bundle Reference File\n\nA file-based strategy where essential domain context is stored in a temporary external file, allowing independent sub-agents to read and continuously update current state across tasks.\n\n### Global Gitignore for Agents\n\nCreating a dedicated directory (like .notes) that is globally gitignored across work trees, allowing AI sub-agents to share context files and updates without muddying the main Git repository history.\n\n### HTML Artifacts for Task Diagnostics\n\nInstructing an agent to generate interactive HTML representations or side-by-side visual diffs to help humans understand and recover control over bloated or complicated tasks.\n\n### Agent Verification Scripts\n\nCustom programmatic scripts that the user instructs the AI agent to write and run upon task completion to verify that the output conditions match expectations.\n\n### Codex Lifecycle Hooks\n\nExtensibility points in the Codex framework (such as user prompt submit, session start, and stop hooks) that allow developers to inject custom workflows or log context.\n\n### Alignment Comparison\n\nAn automated review triggered at the end of an agent session to compare the initial user intent and subsequent prompts with the agent's actual results and intermediate assumptions.\n\n### Context Compaction Hooks\n\nHooks (PreCompact, PostCompact) that execute logic immediately before or after an agent framework compacts its history.\n\n### Agent Session Indexing\n\nThe strategy of extracting conversation logs and tool calls into a searchable database to lower active context window usage.\n\n## Questions and answer status\n\n### attuin? what was the other tool and why?\n\n**Status: answered.** John clarified the tool name is Atuin (atuin.sh) and explained that it is a terminal history manager used for better terminal history search and keeping track of history across shells.\n\n### a participant: attuin? what was the other tool and why?\n\n**Status: partial.** The screen contents explicitly feature the Atuin framework experiencing session identification faults, validating its inclusion within the active environment.\n\n### Elaborate in more detail on how do you handle continuity for complex long tasks or a series of related tasks that may partially share the same core context or domain knowledge. Never what tools we use to optimize the context inadvertently. It drains out of it at some point. Not necessarily certain tooling, rather approach strategy.\n\n**Status: answered.** John states that big tasks should be broken down into smaller chunks or automated agent chains that react to events sequentially rather than relying on one long conversational thread. While modern models like Fable and 5.6 have better token efficiency that delays compaction problems, creators can also mitigate context bloat by externalizing core knowledge into a temporary bundle file that individual task steps read from and update.\n\n### do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?\n\n**Status: partial.** John begins to explain his structural project layout choices (like dedicated, gitignored folders for notes, goals, mocks, and issues) to partition distinct context categories, which continues past the current shard boundaries.\n\n### do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?\n\n**Status: answered.** John confirms he routinely makes agents build custom HTML artifacts showing clear before/after data comparisons to inspect the consequences of complex automated operations.\n\n### How can a developer prevent a workflow loop from triggering on tiny follow-up questions?\n\n**Status: answered.** By configuring conditions inside hooks to inspect prompt length, character markers, or time differences since the last prompt.\n\n## Exercises\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [04:20:03](https://proud-anchor-53zn.here.now/watch.html?t=15603#recording-player) — The screen displays a markdown document summary within the mdflow tool layout, detailing a list of Codex trusting directory fixes. John welcomes back participants from the break.\n\n- [04:20:14](https://proud-anchor-53zn.here.now/watch.html?t=15614#recording-player) — John scrolls up the main markdown pane to show the execution status text: 'All done, dude! Everything reproduced in live herder panes...'.\n\n- [04:20:24](https://proud-anchor-53zn.here.now/watch.html?t=15624#recording-player) — John explains how the agent script combed through ZSH terminal history to find failed commands, automatically spun up isolated herder test panes, and verified the permission fixes.\n\n- [04:20:43](https://proud-anchor-53zn.here.now/watch.html?t=15643#recording-player) — John highlights text containing the --ignore-user-config option with his cursor.\n\n- [04:20:57](https://proud-anchor-53zn.here.now/watch.html?t=15657#recording-player) — John highlights text reading 'commit and release this so the installed md gets the fixes'.\n\n- [04:21:52](https://proud-anchor-53zn.here.now/watch.html?t=15712#recording-player) — a participant asks: 'attuin? what was the other tool and why?'\n\n- [04:22:03](https://proud-anchor-53zn.here.now/watch.html?t=15723#recording-player) — John describes Atuin as a terminal history manager that provides superior history indexing and search capabilities.\n\n- [04:22:08](https://proud-anchor-53zn.here.now/watch.html?t=15728#recording-player) — John provides the link https://atuin.sh/ in the chat window.\n\n- [04:22:27](https://proud-anchor-53zn.here.now/watch.html?t=15747#recording-player) — A terminal sub-pane opens on the right side of the window, displaying the error message: 'ERROR: Failed to find $ATUIN_SESSION in the environment. Check that you have correctly set up your shell.'\n\n- [04:22:34](https://proud-anchor-53zn.here.now/watch.html?t=15754#recording-player) — John notices the error and indicates he needs to look into his Atuin session history configuration.\n\n- [04:22:54](https://proud-anchor-53zn.here.now/watch.html?t=15774#recording-player) — As John attempts to select text inside the active terminal sub-pane, the screen begins printing raw mouse-tracking escape character codes.\n\n- [04:22:57](https://proud-anchor-53zn.here.now/watch.html?t=15777#recording-player) — John explains that his window shortcuts are broken in a strange way, speculating whether it relates to CMUX or Herder behaviors.\n\n- [04:23:34](https://proud-anchor-53zn.here.now/watch.html?t=15814#recording-player) — John identifies that the terminal is sending raw mouse movement character codes due to extensive environment configuration modifications he made the previous evening.\n\n- [04:23:50](https://proud-anchor-53zn.here.now/watch.html?t=15830#recording-player) — John Lindquist identifies that his terminal interface is generating raw character sequences due to mouse movements.\n\n- [04:23:51](https://proud-anchor-53zn.here.now/watch.html?t=15831#recording-player) — The Ghostty terminal pane displays an initialization error: \"ERROR: Failed to find $ATUIN_SESSION in the environment. Check that you have correctly set up your shell.\" followed by continuous escaped mouse tracking coordinate text strings.\n\n- [04:24:05](https://proud-anchor-53zn.here.now/watch.html?t=15845#recording-player) — The layout updates to display an automated clipboard feedback string \"copied 1140 chars to clipboard\" at the base of the file content window.\n\n- [04:24:25](https://proud-anchor-53zn.here.now/watch.html?t=15865#recording-player) — John focuses the right-side interactive pane running Claude Code v1.2.212 and types a diagnostic instruction: \"[Image #1] --- investigate and fix this atuin issue and describe what the issue was\" next to the screenshot artifact.\n\n- [04:24:52](https://proud-anchor-53zn.here.now/watch.html?t=15892#recording-player) — John contrasts the data weights between human and agent systems, noting a 30MB SQLite storage vs a 263KB optimized packed binary representation.\n\n- [04:25:09](https://proud-anchor-53zn.here.now/watch.html?t=15909#recording-player) — John summarizes the web content's rationale, explaining that human databases prioritize ad-hoc querying and incremental mutations, while agents only require minimal faithful representations.\n\n- [04:25:45](https://proud-anchor-53zn.here.now/watch.html?t=15945#recording-player) — John describes the zero-byte design boundary where graphs can be built directly from a local disk cache within 10 seconds.\n\n- [04:26:02](https://proud-anchor-53zn.here.now/watch.html?t=15962#recording-player) — John voices mild skepticism regarding the absolute exclusion of SQLite for agent tasks but agrees with the performance upside of packed binary layers.\n\n- [04:26:40](https://proud-anchor-53zn.here.now/watch.html?t=16000#recording-player) — John advises engineers to run a \"smell test\" on their tools to distinguish whether they are structurally built for humans or optimized for AI context loops.\n\n- [04:27:37](https://proud-anchor-53zn.here.now/watch.html?t=16057#recording-player) — The web browser displays a page titled 'The Same Graph, Twice...' at URL 'sturdy-hazel-dbvt.here.now' describing CodeGraph database statistics and graph metrics.\n\n- [04:27:37](https://proud-anchor-53zn.here.now/watch.html?t=16057#recording-player) — John Lindquist discusses the design mindset of the CodeGraph project, explaining it was built thinking about how agents view the codebase.\n\n- [04:28:06](https://proud-anchor-53zn.here.now/watch.html?t=16086#recording-player) — John Lindquist reads a parting request from a participant asking how to handle context continuity for long complex tasks or related series of tasks sharing domain knowledge.\n\n- [04:28:14](https://proud-anchor-53zn.here.now/watch.html?t=16094#recording-player) — The right interface pane updates to display a text log summarizing a 'typography pass' that fluidly scales root sizes, increases body copy contrast, and ends with a recap of publishing the companion page.\n\n- [04:28:31](https://proud-anchor-53zn.here.now/watch.html?t=16111#recording-player) — John explains that orchestration is where solution strategy resides, and advises breaking large tasks down into smaller chunks or sequential sub-agent workflows.\n\n- [04:28:35](https://proud-anchor-53zn.here.now/watch.html?t=16115#recording-player) — The screen shows a status line indicating '● claude finished • x' along with an agent action instruction prompt ' bypass permissions on (shift+tab to cycle)'.\n\n- [04:30:12](https://proud-anchor-53zn.here.now/watch.html?t=16212#recording-player) — John names recent models like Fable and 5.6, stating their token efficiency minimizes the impact of context compaction limits.\n\n- [04:30:55](https://proud-anchor-53zn.here.now/watch.html?t=16255#recording-player) — John suggests creating a temporary context bundle file that consecutive steps can reference and update to preserve essential domain knowledge.\n\n- [04:31:22](https://proud-anchor-53zn.here.now/watch.html?t=16282#recording-player) — The workspace switches to a terminal view in the 'script-kit-gui' repository, showing output from a 'herdr' command listing three open flow panes: clipboard-flow, scout-flow, and screenshot-flow.\n\n- [04:31:25](https://proud-anchor-53zn.here.now/watch.html?t=16285#recording-player) — John Lindquist describes using a gitignored notes directory to dump project files.\n\n- [04:31:39](https://proud-anchor-53zn.here.now/watch.html?t=16299#recording-player) — The directory listing in the right pane changes to show a list of global gitignored files starting with .ignored_, such as .ignored_acorn and .ignored_action.\n\n- [04:34:25](https://proud-anchor-53zn.here.now/watch.html?t=16465#recording-player) — John states that he creates HTML artifacts all the time to analyze before-and-after states.\n\n- [04:34:43](https://proud-anchor-53zn.here.now/watch.html?t=16483#recording-player) — The screen switches to a web browser window displaying an HTML page titled 'The Same Graph, Twice — C...' at the URL 'sturdy-hazel-v0ax4.here.now' showcasing CodeGraph metrics.\n\n- [04:35:13](https://proud-anchor-53zn.here.now/watch.html?t=16513#recording-player) — The browser displays a webpage comparison titled 'The Same Graph, Twice' showing 30MB SQLite database versus 263KB graph.bin for agents.\n\n- [04:35:13](https://proud-anchor-53zn.here.now/watch.html?t=16513#recording-player) — John talks about asking the agent to run verification scripts after a long block of work.\n\n- [04:37:29](https://proud-anchor-53zn.here.now/watch.html?t=16649#recording-player) — John outlines how lifecycle hooks like user prompt submit hooks, session start hooks, and stop hooks can be utilized to run verification workflows.\n\n- [04:38:59](https://proud-anchor-53zn.here.now/watch.html?t=16739#recording-player) — John Lindquist explains how hooks can prevent unnecessary workflow execution by evaluating initial prompt length or time deltas.\n\n- [04:40:01](https://proud-anchor-53zn.here.now/watch.html?t=16801#recording-player) — John highlights the PreCompact and PostCompact hooks in the Codex documentation interface.\n\n- [04:40:49](https://proud-anchor-53zn.here.now/watch.html?t=16849#recording-player) — John shares a link to a Claude Code skill page (https://jeffreys-skills.md/skills/cass).\n\n- [04:41:16](https://proud-anchor-53zn.here.now/watch.html?t=16876#recording-player) — John navigates to and shares the GitHub repository https://github.com/Dicklesworthstone/coding_agent_session_search.\n\n### Unresolved: The exact role or integration of CMUX within John's current layout environment.\n\nThe presenter mentions CMUX changed pane behaviors, but the implementation rules are not visibly audited on screen.\n\n**Discriminating evidence:** Monitor upcoming terminal or system walkthroughs to map out the multiplexer setup.\n\n### Unresolved: The exact tool hosting the Claude agent panel execution logs.\n\nThe software wrapper includes custom UI controls and keybindings not fully declared by name during this precise segment.\n\n**Discriminating evidence:** Can be confirmed by matching standard layout features from preceding or subsequent presentation fragments within the workshop series.\n\n### Demonstration detail: 04:20:03\n\n- Reviewing an agent-generated markdown report summarizing code fixes and test pane executions for Codex trusting directories bugs.\n- Highlighting specific command flags like --ignore-user-config and commit instructions.\n\n**Tools observed:** mdflow, Herder.\n\n### Demonstration detail: 04:21:53\n\n- Opening a web browser, searching for the terminal history tool Atuin on Google, and presenting its homepage features.\n\n**Tools observed:** Arc Browser, Google Search.\n\n### Demonstration detail: 04:22:26\n\n- Switching back to the development workspace, opening a terminal pane that exhibits an ATUIN_SESSION environment variable failure, and encountering raw mouse tracking character code spam when trying to interact with the pane.\n\n**Tools observed:** mdflow, CMUX, Zsh.\n\n### Demonstration detail: 04:23:51\n\n- Selects and copies raw terminal text escape strings.\n- Initiates a chat instruction prompt referencing an attached image inside Claude Code to resolve Atuin configuration bugs.\n\n**Tools observed:** Ghostty, Claude Code.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\n[Image #1] --- investigate and fix this atuin issue and describe what the issue was\n```\n\n### Demonstration detail: 04:24:45\n\n- Navigates and reads a web essay detailing graph database performance profiles.\n- Highlights text sections regarding human vs agent context data requirements.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 04:27:37\n\n- Displaying the CodeGraph overview and byte optimization metrics web page in the browser.\n\n**Tools observed:** Web Browser.\n\n### Demonstration detail: 04:28:14\n\n- Reviewing the automated text recap report produced by an active agent workflow following a stylesheet typography pass.\n\n**Tools observed:** Claude Agent Workspace.\n\n### Demonstration detail: 04:31:22\n\n- Switching to an active Zsh terminal screen inside the script-kit-gui workspace project folder to review herdr pane control flow statuses.\n\n**Tools observed:** Zsh Terminal Shell, herdr CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr pane read w2P:p --source recent --lines 8 --format text\n```\n\n### Demonstration detail: 04:31:24\n\n- Showing layout structure of herdr panes and global gitignore lists inside Ghostty terminal window.\n\n**Tools observed:** Ghostty, herdr.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr pane read w2p:p4 --source recent --lines 8 --format text\n```\n\n### Demonstration detail: 04:34:43\n\n- Navigating and scrolling through an HTML artifact detailing CodeGraph database and binary layout performance differences.\n\n**Tools observed:** CodeGraph.\n\n### Demonstration detail: 04:37:11\n\n- Typed search query into address bar\n- Encountered Cloudflare Access login screen\n- Performed public Google search for codex hooks\n- Opened official documentation page from search results\n\n**Tools observed:** Google Chrome Browser, Google Search.\n\n### Demonstration detail: 04:40:46\n\n- Navigated to jeffreys-skills.md\n- Performed Google search for cass github conversation search\n- Opened public GitHub repository page\n\n**Tools observed:** Chrome Browser."
    },
    {
      "id": "codex-video-evidence-process",
      "slug": "video-evidence-process",
      "title": "Repeatable video evidence processing",
      "summary": "Evidence-preserving video follow-up workflow covering long and short recordings, project setup, segmentation, chat carry-forward, Oracle/Gemini analysis and recovery, prompt templates, verification, keyframes, Git practices, publication review, and planned…",
      "category": "Context",
      "tags": [
        "video",
        "evidence",
        "quality"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Project Structure",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Run Config",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Mode Matrix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Decision Tree",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Project Setup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Long Recording Workflow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Short Recording Workflow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Gemini Readiness And Failure Recovery",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Gemini Browser Cleanup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Gemini Chunk Analysis",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Omissions Pass",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Local Reconciliation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Short Clip Analysis",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Final Packet Generation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Prompt Templates/Oracle Review",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Verification Gates",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Keyframes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Git Workflow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Oracle Session Receipts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Final Packet Review",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/End-To-End Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/references/repeatable-video-followup-process.md#Repeatable Video Follow-Up Process/Later Automation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 4269,
      "url": "/topics/codex-video-evidence-process/",
      "markdownUrl": "/markdown/codex-video-evidence-process.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-video-evidence-process.json",
      "headings": [
        {
          "id": "project-structure",
          "text": "Project Structure",
          "level": 2
        },
        {
          "id": "run-config",
          "text": "Run Config",
          "level": 2
        },
        {
          "id": "mode-matrix",
          "text": "Mode Matrix",
          "level": 2
        },
        {
          "id": "decision-tree",
          "text": "Decision Tree",
          "level": 2
        },
        {
          "id": "project-setup",
          "text": "Project Setup",
          "level": 2
        },
        {
          "id": "long-recording-workflow",
          "text": "Long Recording Workflow",
          "level": 2
        },
        {
          "id": "short-recording-workflow",
          "text": "Short Recording Workflow",
          "level": 2
        },
        {
          "id": "gemini-readiness-and-failure-recovery",
          "text": "Gemini Readiness And Failure Recovery",
          "level": 2
        },
        {
          "id": "gemini-browser-cleanup",
          "text": "Gemini Browser Cleanup",
          "level": 2
        },
        {
          "id": "prompt-templates",
          "text": "Prompt Templates",
          "level": 2
        },
        {
          "id": "gemini-chunk-analysis",
          "text": "Gemini Chunk Analysis",
          "level": 3
        },
        {
          "id": "omissions-pass",
          "text": "Omissions Pass",
          "level": 3
        },
        {
          "id": "local-reconciliation",
          "text": "Local Reconciliation",
          "level": 3
        },
        {
          "id": "short-clip-analysis",
          "text": "Short Clip Analysis",
          "level": 3
        },
        {
          "id": "final-packet-generation",
          "text": "Final Packet Generation",
          "level": 3
        },
        {
          "id": "oracle-review",
          "text": "Oracle Review",
          "level": 3
        },
        {
          "id": "verification-gates",
          "text": "Verification Gates",
          "level": 2
        },
        {
          "id": "keyframes",
          "text": "Keyframes",
          "level": 2
        },
        {
          "id": "git-workflow",
          "text": "Git Workflow",
          "level": 2
        },
        {
          "id": "oracle-session-receipts",
          "text": "Oracle Session Receipts",
          "level": 2
        },
        {
          "id": "final-packet-review",
          "text": "Final Packet Review",
          "level": 2
        },
        {
          "id": "end-to-end-checklist",
          "text": "End-To-End Checklist",
          "level": 2
        },
        {
          "id": "automation-responsibilities",
          "text": "Automation Responsibilities",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Repeatable video evidence processing\n\nStatus: implementation-ready process spec\nOwner: local coding agent\nReference run: `workshop-followup/`\nPrimary output: verified follow-up materials from one or more source videos\n\nThis process turns a raw workshop recording, tutorial, app walkthrough, bug reproduction, or short screen recording into a reviewable artifact project. It is built from the completed `workshop-followup/` run and the Oracle review session `video-pipeline-repeatable-process`.\n\nThe pipeline has two main paths:\n\n1. Long workshop path: segment long recordings, remove verified breaks, carry forward break chat, analyze chunks, verify omissions, extract keyframes, reconcile, and assemble a teammate packet.\n2. Short recording path: skip segmentation unless needed, analyze the clip directly, optionally extract keyframes, verify outputs, and produce a compact follow-up note, bug packet, design brief, or requirements document.\n\nThe core rule is evidence preservation. Keep the original media immutable, preserve original timestamps when a source timeline exists, save model prompts/results/logs, and keep verification receipts next to every generated claim.\n\nFor this browser-based workflow, Gemini video analysis uses\nOracle browser mode and must clean up after itself. After a chunk's analysis is saved\nand verified, close the Gemini tab opened for that chunk. Leave the browser/profile\nalive for reuse, but do not leave accumulated `gemini.google.com/app` tabs on the\nremote Mac mini.\n\n## Project Structure\n\nUse one run folder per video or video set:\n\n```text\nruns/\n  YYYY-MM-DD-slug/\n    README.md\n    run-config.json\n    inputs/\n      source-video.mp4\n      source-video.sha256\n      transcript.vtt\n      transcript.md\n      chat.txt\n      chat.md\n      screenshots/\n      clips/\n    receipts/\n      ffprobe.source.json\n      media-info.md\n      source-file-list.txt\n      tool-versions.txt\n      git-status.before.txt\n      git-status.after.txt\n    analysis/\n      timeline-initial.json\n      silencedetect.log\n      boundary-candidates.md\n      segmentation-notes.md\n      source-timeline.md\n    segments/\n      segment-manifest.v1.json\n      segment-manifest.v1.md\n      segment-manifest.v2.json\n      segment-manifest.v2.md\n    break-chat/\n      morning-break.chat.md\n      lunch-break.chat.md\n      other-break.chat.md\n    chunks/\n      video-manifest.json\n      01/\n        chunk.mp4\n        chunk.ffprobe.json\n        transcript.md\n        chat.md\n        carry-forward-chat.md\n        next-chunk-preview.md\n        gemini-prompt.md\n        expected-sentinel.txt\n        gemini-run.log\n        gemini-result.json\n        gemini-analysis.md\n        gemini-analysis.extracted.json\n        gemini-omissions-prompt.md\n        gemini-omissions-run.log\n        gemini-omissions-result.json\n        gemini-omissions.md\n        final-reconciled.md\n        final-reconciled.json\n        keyframes/\n          candidates.json\n          extracted/\n          strips/\n          contact-sheet.jpg\n          review.md\n        verification/\n          expected-items.json\n          extracted-items.json\n          coverage-report.md\n          hallucination-report.md\n          timestamp-report.md\n          qa-report.md\n          visual-claim-report.md\n    oracle/\n      planning.md\n      review.md\n      sessions/\n    final/\n      README.md\n      teammate-followup-guide.md\n      chapter-index.md\n      resources-and-links.md\n      qa-index.md\n      exercises.md\n      keyframes-manifest.md\n      keyframes-manifest.json\n      instructor-review-checklist.md\n    publication/\n      public-draft/\n      private-redactions.md\n      publish-checklist.md\n```\n\nThe current reference artifacts live in `workshop-followup/`. New runs should use `runs/<date>-<slug>/` so the reference run remains untouched.\n\n## Run Config\n\nCreate `run-config.json` before processing:\n\n```json\n{\n  \"run_id\": \"example-workshop\",\n  \"title\": \"Example Workshop\",\n  \"mode\": \"long_workshop\",\n  \"source\": {\n    \"video\": \"inputs/source-video.mp4\",\n    \"transcript\": \"inputs/transcript.vtt\",\n    \"chat\": \"inputs/chat.txt\",\n    \"screenshots\": \"inputs/screenshots\",\n    \"clips\": \"inputs/clips\"\n  },\n  \"policy\": {\n    \"preserve_original_timestamps\": true,\n    \"chunk_target_minutes\": \"semantic-under-30\",\n    \"chunk_max_minutes\": 30,\n    \"dead_space_removal\": \"only verified long silence plus transcript/chat break evidence\",\n    \"default_video_overlap_seconds\": 0,\n    \"semantic_boundary_overlap_seconds\": 5,\n    \"qa_boundary_overlap_seconds\": 15,\n    \"chat_carry_forward\": true,\n    \"dedupe_final_materials\": true,\n    \"large_binary_git_policy\": \"local-only-unless-explicitly-approved\"\n  },\n  \"outputs\": {\n    \"student_packet\": true,\n    \"keyframes\": true,\n    \"contact_sheets\": true,\n    \"verification_reports\": true\n  }\n}\n```\n\n## Mode Matrix\n\n| Mode | Typical input | Segmentation | Transcript/chat | Keyframes | Gemini video pass | Output |\n|---|---|---:|---:|---:|---:|---|\n| Long workshop | 2-8 hour Zoom/workshop recording | Required | Required if available | Required | Required | Full teammate packet |\n| Medium tutorial | 20-60 minute lesson | Optional semantic chunks | Transcript required, chat optional | Recommended | Required when deriving facts from video | Guide, chapter index, resources |\n| Short bug reproduction | 30 sec-8 min screen recording | Skip | Optional | Required | Required for observed behavior | Bug report, repro steps, implementation brief |\n| Quick design feedback | 1-12 min screen and voice | Skip | Recommended if voiceover matters | Required | Required for visual/audio claims | Design-change brief, QA checklist |\n| Raw app walkthrough | 5-30 min app demo | Skip under 12 min; segment over 20 min | Recommended | Required | Required for requirements/QA extraction | Requirements doc, acceptance criteria |\n\n\"Optional\" applies only to extra Oracle planning/review over text artifacts. It does\nnot mean the video-watching step can be skipped when the deliverable depends on what\nis visible or audible in the recording.\n\n## Decision Tree\n\nSegment when any of these are true:\n\n- Video duration is over 30 minutes.\n- There are real breaks, lunch, pre-roll, or dead air.\n- Q&A spans topic transitions.\n- Chat must be aligned to the video.\n- The target output is a course packet, teammate packet, chapter index, or publication bundle.\n\nSkip segmentation when all of these are true:\n\n- Video duration is 12 minutes or less.\n- There is no long dead air or break.\n- Chat is absent, irrelevant, or small enough to include directly.\n- One model pass can analyze the whole video reliably.\n- The target output is a short note, bug report, design feedback memo, or compact implementation plan.\n\nUse a medium path when the video is 12-45 minutes, has no real breaks, and has 2-4 obvious sections. In that case, keep one physical video and create timestamped sections unless model upload/runtime gets awkward.\n\nRemove a video span only when long silence or inactive-screen evidence, transcript evidence, and chat evidence agree that the span is a break or dead space. Never discard chat from a removed span. Save it in `break-chat/` and carry it forward to the next spoken chunk when it contains a question, answer, link, or context used later.\n\nExtract keyframes when screen share, terminal commands, browser pages, demos, design feedback, or visual claims appear. Skip keyframes only for pure audio/talking-head content where visual evidence cannot change the output.\n\nRun an omissions pass when coverage is incomplete, missing URLs exist, missing chat questions exist, keyframe candidates are thin, machine JSON is missing/unparseable, timestamps are out of range, or hallucination checks find invented tools/links/commands.\n\n## Project Setup\n\n```bash\ncd /path/to/workshop-video-followup-pipeline\nRUN_ID=\"$(date +%Y-%m-%d)-example-workshop\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,segments,break-chat,chunks,oracle/sessions,final,publication}\ngit status --short > \"$RUN_DIR/receipts/git-status.before.txt\"\n```\n\nRecord tool versions:\n\n```bash\n{\n  echo \"# Tool Versions\"\n  echo\n  echo \"date: $(date -u +%Y-%m-%dT%H:%M:%SZ)\"\n  echo\n  echo \"## ffmpeg\"\n  ffmpeg -version | head -n 3 || true\n  echo\n  echo \"## ffprobe\"\n  ffprobe -version | head -n 3 || true\n  echo\n  echo \"## git\"\n  git --version || true\n  echo\n  echo \"## jq\"\n  jq --version || true\n  echo\n  echo \"## python\"\n  python3 --version || true\n} > \"$RUN_DIR/receipts/tool-versions.txt\"\n```\n\nCopy inputs. Do not mutate originals:\n\n```bash\ncp \"/absolute/path/to/source-video.mp4\" \"$RUN_DIR/inputs/source-video.mp4\"\n\n# Optional\ncp \"/absolute/path/to/transcript.vtt\" \"$RUN_DIR/inputs/transcript.vtt\"\ncp \"/absolute/path/to/chat.txt\" \"$RUN_DIR/inputs/chat.txt\"\n```\n\nHash source assets and save file list:\n\n```bash\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" > \"$RUN_DIR/inputs/source-video.sha256\"\nfind \"$RUN_DIR/inputs\" -maxdepth 2 -type f -print0 \\\n  | xargs -0 shasum -a 256 \\\n  > \"$RUN_DIR/receipts/source-file-list.txt\"\n```\n\nProbe the source video:\n\n```bash\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nCreate a human-readable media receipt:\n\n```bash\n{\n  echo \"# Media Info\"\n  echo\n  echo \"source: $RUN_DIR/inputs/source-video.mp4\"\n  echo \"sha256: $(cut -d ' ' -f1 \"$RUN_DIR/inputs/source-video.sha256\")\"\n  echo\n  jq -r '.format | \"- duration: \\(.duration)\\n- size: \\(.size)\\n- bit_rate: \\(.bit_rate)\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n  echo\n  echo \"## Streams\"\n  jq -r '.streams[] | \"- index=\\(.index) type=\\(.codec_type) codec=\\(.codec_name) duration=\\(.duration // \"unknown\") width=\\(.width // \"-\") height=\\(.height // \"-\")\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n} > \"$RUN_DIR/receipts/media-info.md\"\n```\n\nCommit the initial evidence:\n\n```bash\ngit add \"$RUN_DIR/run-config.json\" \"$RUN_DIR/inputs\" \"$RUN_DIR/receipts\"\ngit commit -m \"Capture source evidence for $RUN_ID\"\n```\n\n## Long Recording Workflow\n\n1. Detect silence:\n\n```bash\nffmpeg -hide_banner -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -af silencedetect=noise=-35dB:d=5 \\\n  -f null - 2> \"$RUN_DIR/analysis/silencedetect-35db-5s.log\"\n```\n\n2. Draft `analysis/boundary-candidates.md` from silence, transcript, and chat evidence.\n\n3. Create `segments/segment-manifest.v1.json` and `.md`. Preserve original timestamps. Use semantic chunks under 30 minutes. Remove break spans only when evidence supports removal.\n\n4. Run `$oracle-packx` before finalizing segmentation when the run is long, public, or ambiguous. Bundle only text artifacts:\n\n```bash\nmkdir -p ~/.oracle/bundles\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --preview --no-interactive\n\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --limit 900k -f markdown --no-interactive --stdout --strip-comments --minify \\\n  > ~/.oracle/bundles/video-followup-segmentation-review.txt\n\ntest -s ~/.oracle/bundles/video-followup-segmentation-review.txt\n```\n\nAsk Oracle in browser mode only. If using the skill, invoke `$oracle-packx`; if using the CLI fallback, keep browser mode explicit:\n\n```bash\noracle --engine browser \\\n  --model gpt-5.5-pro \\\n  --browser-thinking-time extended \\\n  --slug video-followup-segmentation-review \\\n  --file ~/.oracle/bundles/video-followup-segmentation-review.txt \\\n  -p \"$(cat \"$RUN_DIR/oracle/planning.md\")\"\n```\n\nSave the Oracle conversation URL, local bundle path, prompt, and `~/.oracle/sessions/<slug>/output.log` reference in `oracle/sessions/<slug>.md`.\n\n5. Revise into `segments/segment-manifest.v2.json` and `.md`.\n\n6. Cut chunks from the original source:\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01\"\nffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -map 0 -c copy \\\n  \"$RUN_DIR/chunks/01/chunk.mp4\"\n\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/chunks/01/chunk.mp4\" \\\n  > \"$RUN_DIR/chunks/01/chunk.ffprobe.json\"\n```\n\nUse `-c copy` for fast archival cuts when keyframe accuracy is acceptable. Use re-encode for frame-exact cuts:\n\n```bash\nffmpeg -hide_banner -ss 00:05:44 -to 00:30:30 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -map 0 -c:v libx264 -crf 18 -preset veryfast -c:a aac \\\n  \"$RUN_DIR/chunks/01/chunk.frame-exact.mp4\"\n```\n\n7. Slice transcript and chat into `chunks/<nn>/transcript.md`, `chat.md`, and `carry-forward-chat.md`.\n\n8. Create `chunks/video-manifest.json` with chunk id, original range, file path, transcript path, chat path, carry-forward path, ffprobe path, and verification status.\n\n## Short Recording Workflow\n\nUse this path for quick screen captures, short bug reproductions, design notes, and small app walkthroughs.\n\n```bash\nRUN_ID=\"$(date +%Y-%m-%d)-quick-clip\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,chunks/01,final}\ncp \"/absolute/path/to/clip.mov\" \"$RUN_DIR/inputs/source-video.mov\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mov\" > \"$RUN_DIR/inputs/source-video.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mov\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor short clips, do not cut video by default. Symlink or copy it as the single chunk:\n\n```bash\nln -s ../../inputs/source-video.mov \"$RUN_DIR/chunks/01/chunk.mov\"\n```\n\nCreate `chunks/01/gemini-prompt.md` using the short clip prompt in this doc, attach the clip directly to Gemini/video model, and save:\n\n```text\nchunks/01/expected-sentinel.txt\nchunks/01/gemini-run.log\nchunks/01/gemini-result.json\nchunks/01/gemini-analysis.md\nchunks/01/final-reconciled.md\nfinal/README.md\n```\n\nFinal output by short mode:\n\n- Bug reproduction: `final/bug-report.md`, `final/repro-steps.md`, `final/acceptance-checks.md`\n- Design feedback: `final/design-brief.md`, `final/visual-acceptance-criteria.md`\n- App walkthrough: `final/requirements.md`, `final/qa-checklist.md`\n- Tiny tutorial: `final/summary.md`, `final/resources-and-links.md`\n\nRun the same malformed URL and hallucination checks even for short clips.\n\nFor YouTube research batches, add these source-selection rules before downloading:\n\n- Search broadly, but select by actual YouTube metadata (`upload_date`), not title text.\n- Enforce user cutoffs exactly. Example: after a chosen cutoff means\n  `upload_date >= CUTOFF_YYYYMMDD`.\n- Exclude topic collisions, coupon/affiliate uploads, auto-generated music/topic\n  uploads, and unrelated videos.\n- Save selected videos in `queue.json` with `id`, `title`, `uploader`,\n  `upload_date`, `duration`, and `url`.\n- Use Chrome cookies with `yt-dlp` when YouTube challenges require it.\n- Space Gemini upload starts by about five minutes for batch runs only after the first\n  attached-video probe passes and no unresolved run is pending, unless the user asks\n  for a different cadence.\n\nFor each batch item, use a topic-specific prompt. Do not copy old prompt text from a\ndifferent topic without replacing the product/domain language.\n\n## Gemini Readiness And Failure Recovery\n\nBefore a large batch, run one tiny attached-video Gemini probe. Do not rely on a\ntext-only Gemini probe as the sole readiness check because text-only runs may use a\ndifferent HTTP/cookie path than attached-video DOM upload.\n\nRequired preflight receipts:\n\n- configured browser mode and Gemini provider routing;\n- visible signed-in Gemini UI, or a completed attached-video probe;\n- prompt path and exact expected sentinel;\n- run/session metadata;\n- attachment upload completion;\n- final response or recovered visible response with sentinel;\n- completed tab cleanup.\n\nOn any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit,\nor upload warning, stop new batch starts. Inspect the active Gemini tab, classify the\nstate, and retry only the affected chunk if no valid sentinel response exists.\n\nWrite the exact expected sentinel into `chunks/<nn>/expected-sentinel.txt` before each\nGemini run. Verification and recovery should compare against that file, not infer the\nsentinel shape from memory.\n\n## Gemini Browser Cleanup\n\nWhen using Oracle CLI fallback with `--browser-keep-browser`, cleanup is mandatory:\n\n1. Wait for the run to finish.\n2. Save every needed extraction artifact from the Gemini response:\n   `gemini-result.json`, `gemini-analysis.md`, `gemini-analysis.extracted.json` when\n   expected, machine JSON, and any recovery note if the response was recovered by tab\n   inspection.\n3. Verify the analysis is non-empty and contains the expected\n   `END_OF_VIDEO_ANALYSIS ...` sentinel.\n4. Close only the completed and fully extracted Gemini tab for that run.\n5. Do not close tabs for active uploads, still-generating sessions, unresolved wrapper\n   errors, or completed-looking tabs whose visible response has not been extracted.\n6. Do not kill Chrome; Oracle needs the signed-in profile for future runs.\n\nFor scripted runs, implement cleanup as a post-extraction step, not as a generic\n`finally` block. A safe script order is: save wrapper result, inspect/recover tab output\nif needed, write extracted JSON, verify the exact expected sentinel, then close the\nspecific Gemini tab target. If any extraction or sentinel check fails, leave the tab\nopen and record the Chrome port/target for recovery.\n\nIf exact target close tooling is available, use Chrome DevTools Protocol to close the\nspecific `gemini.google.com/app` target created for the run. If not, list tabs first,\nidentify completed or empty Gemini tabs, and close only those. Avoid broad \"close all\nGemini\" actions while a batch is running.\n\nWhen classifying stale tabs:\n\n- Empty generic Gemini tabs from failed diagnostics may be closed after inspection.\n- Active upload/generation tabs must stay open.\n- Tabs with conversation state or auto-generated titles must be checked for saved\n  output and the expected sentinel before closing.\n- Never use broad \"close all Gemini tabs\" while a batch is active.\n\n## Prompt Templates\n\n### Gemini Chunk Analysis\n\n```markdown\nYou are analyzing one source-preserving video chunk for a follow-up packet.\n\nRun metadata:\n- run_key: {{run_key}}\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- chunk_video: {{chunk_video_path}}\n- transcript: included below\n- chat: included below\n- carry_forward_chat: included below\n- next_chunk_preview: included below\n\nHard rules:\n1. Preserve original recording timestamps.\n2. Separate transcript evidence, chat evidence, visual evidence, and inference.\n3. Do not invent tools, commands, URLs, files, speakers, or UI labels.\n4. Include unanswered and deferred questions.\n5. Flag every policy-sensitive area, especially browser automation, cookies, quota/rate limits, private accounts, and publishing.\n6. Return both Markdown and fenced JSON.\n7. End with: END_OF_VIDEO_ANALYSIS {{run_key}} {{chunk_id}}\n\nReturn:\n# Chunk Analysis: {{chunk_id}}\n## 1. Overview\n## 2. Dense Timeline\n## 3. Concept Inventory\n## 4. Demo / Screen Activity\n## 5. Questions And Answers\n## 6. Links / Tools / Commands / References\n## 7. Keyframes To Capture\n## 8. teammate Exercises\n## 9. Uncertainties / Needs Review\n## 10. Machine JSON\n```\n\n### Omissions Pass\n\n```markdown\nYou are auditing a prior video analysis for omissions.\n\nInputs:\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- coverage_report: {{coverage_report}}\n- expected_items: {{expected_items_json}}\n- prior_analysis: {{prior_analysis}}\n\nFind only omissions and corrections. Do not repeat complete items.\n\nRequired focus:\n1. Missing URLs exactly as they appeared.\n2. Missing chat questions, including unanswered/deferred questions.\n3. Missing demo steps.\n4. Missing keyframe candidates.\n5. Unsupported visual claims.\n6. Hallucinated tools, commands, links, or files.\n7. Parseable fenced JSON.\n\nReturn:\n# Omissions And Corrections: {{chunk_id}}\n## Additions\n## Corrections\n## Remove Or Downgrade\n## Remaining Human Review\n## Machine JSON\n```\n\n### Local Reconciliation\n\n```markdown\nReconcile one analyzed chunk into an evidence-grounded final chunk record.\n\nInputs:\n- segment manifest entry\n- transcript slice\n- chat slice\n- carry-forward chat\n- main analysis\n- omissions analysis\n- verification reports\n- keyframe review\n\nRules:\n1. Preserve original timestamps.\n2. Remove malformed URLs.\n3. Do not include any URL/tool/command unless supported by transcript, chat, carry-forward chat, local path, or keyframe review.\n4. Do not claim a visual is visible unless keyframe review confirms it.\n5. Preserve unanswered/deferred questions.\n6. Preserve editorial warnings.\n7. Deduplicate overlap by normalized timestamp + item type + text hash.\n\nReturn Markdown and JSON with:\n- status: PASS | PASS_WITH_WARNINGS | FAIL\n- counts\n- timeline summary\n- concepts\n- Q&A\n- links/tools/commands\n- demos\n- keyframes\n- warnings\n- teammate-material candidates\n```\n\n### Short Clip Analysis\n\n```markdown\nYou are analyzing a short screen recording or app walkthrough.\n\nSource:\n- run_key: {{run_key}}\n- recording_type: short_clip | bug_reproduction | design_feedback | app_walkthrough\n- original_recording_range: 00:00:00 -> {{duration}}\n- source_video_sha256: {{source_video_sha256}}\n\nHard rules:\n1. Use timestamps relative to the clip unless an original recording timeline is provided.\n2. Do not invent commands, files, UI labels, URLs, or implementation details.\n3. Separate observed behavior from inferred intent.\n4. Include timestamped screenshot/keyframe candidates for visual claims.\n5. For a bug reproduction, produce repro steps and expected vs actual behavior.\n6. For design feedback, produce requested changes and visual acceptance criteria.\n7. For an app walkthrough, produce requirements and QA checks.\n8. Include uncertainties and manual review points.\n\nReturn:\n# Short Video Analysis: {{run_key}}\n## 1. Summary\n## 2. Observed Timeline\n## 3. User Intent / Requirements\n## 4. Reproduction Steps Or Walkthrough Steps\n## 5. Expected Vs Actual Behavior\n## 6. Implementation Notes\n## 7. QA / Acceptance Criteria\n## 8. Keyframes To Extract\n## 9. Risks / Unknowns\n## 10. Machine JSON\n```\n\n### Final Packet Generation\n\n```markdown\nAssemble a teammate follow-up packet from verified chunk records.\n\nInputs:\n- segments/segment-manifest.v2.md\n- chunks/*/final-reconciled.md\n- chunks/*/final-reconciled.json\n- chunks/*/verification/*.md\n- final/keyframes-manifest.json if present\n- resources extracted from chat/transcript\n\nRules:\n1. Use original recording timestamps.\n2. Do not include unverified visual claims.\n3. Do not include malformed URLs.\n4. Do not present experimental tools as official recommendations unless approved.\n5. Keep policy-sensitive automation/cookie/quota/rate-limit sections as editorial notes.\n6. Distinguish publication-ready files from reference drafts.\n7. Deduplicate overlap and carry-forward repeated material.\n\nCreate:\n- final/README.md\n- final/teammate-followup-guide.md\n- final/chapter-index.md\n- final/resources-and-links.md\n- final/qa-index.md\n- final/exercises.md\n- final/keyframes-manifest.md\n- final/keyframes-manifest.json\n- final/instructor-review-checklist.md\n```\n\n### Oracle Review\n\n```markdown\n[{{slug}}]\n\nProject briefing:\n{{project_briefing}}\n\nGoal:\n{{goal}}\n\nPrior-State Ledger:\n- prior_oracle_session: {{prior_oracle_session_or_none}}\n- last_oracle_recommendation: {{summary_or_none}}\n- implemented_since_prior_oracle: {{files_or_none}}\n- verified_since_prior_oracle: {{commands_or_none}}\n- failed_proof_or_blocker: {{receipt_or_none}}\n- narrowing_decision: {{one_slice}}\n- files_functions_now_in_scope: {{paths}}\n- files_functions_out_of_scope: {{paths}}\n- next_falsifiable_verification: {{command_or_receipt}}\n- forward_progress_index: {{score_and_arithmetic}}\n\nDeliverable:\nEvaluate segmentation, chat carry-forward, analysis prompts, verification gates, final packet readiness, privacy/security risks, and the one highest-leverage next local action.\n\nReturn your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools.\n```\n\n## Verification Gates\n\nRun malformed URL checks on every final packet:\n\n```bash\nrg -n 'https://www\\.\\.\\.|https://www\\s|/\"|\\| .*: \\||Context:' \"$RUN_DIR/final\" || true\n```\n\nExtract exact URLs from chat/transcript and compare against final resources:\n\n```bash\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/chunks\" \"$RUN_DIR/break-chat\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.expected-urls.txt\"\n\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/final/resources-and-links.md\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.final-urls.txt\"\n\ncomm -23 \"$RUN_DIR/verification.expected-urls.txt\" \"$RUN_DIR/verification.final-urls.txt\" \\\n  > \"$RUN_DIR/verification.missing-urls.txt\"\n```\n\nValidate timestamps stay within range, except carry-forward chat:\n\n```bash\npython3 scripts/validate-timestamps.py \"$RUN_DIR\" \\\n  > \"$RUN_DIR/receipts/timestamp-validation.log\"\n```\n\nIf the script does not exist yet, perform a manual timestamp pass and save it as `chunks/<nn>/verification/timestamp-report.md`.\n\nCheck machine JSON:\n\n```bash\nfind \"$RUN_DIR/chunks\" -name '*.json' -print0 | xargs -0 -n1 jq empty\n```\n\nRequired chunk gate files:\n\n```text\nchunks/<nn>/verification/coverage-report.md\nchunks/<nn>/verification/hallucination-report.md\nchunks/<nn>/verification/timestamp-report.md\nchunks/<nn>/verification/qa-report.md\nchunks/<nn>/final-reconciled.md\nchunks/<nn>/final-reconciled.json\n```\n\nChunk status meanings:\n\n- `PASS`: complete and publication-safe after ordinary instructor review.\n- `PASS_WITH_WARNINGS`: usable evidence, but warnings must be reviewed before publication.\n- `FAIL`: rerun analysis, omissions, or reconciliation before using the chunk.\n\n## Keyframes\n\nCandidate extraction prompt output should include timestamp, reason, expected visual, priority, and confidence.\n\nExtract deterministic frames:\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01/keyframes/extracted\"\nffmpeg -hide_banner -ss 00:23:48 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -frames:v 1 \\\n  \"$RUN_DIR/chunks/01/keyframes/extracted/00-23-48-automation-verification.jpg\"\n```\n\nCreate contact sheet:\n\n```bash\nfind \"$RUN_DIR/chunks/01/keyframes/extracted\" -name '*.jpg' | sort \\\n  > \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\"\n\nffmpeg -hide_banner -f concat -safe 0 \\\n  -i <(sed \"s#^#file '#; s#$#'#\" \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\") \\\n  -vf \"scale=320:-1,tile=3x4\" \\\n  \"$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg\"\n```\n\nIf process substitution is unavailable, generate the concat list as a real file and pass it to ffmpeg.\n\n## Git Workflow\n\nInitialize a new artifact project:\n\n```bash\nmkdir -p /path/to/new-video-followup-project\ncd /path/to/new-video-followup-project\ngit init\ncat > README.md <<'EOF'\n# Video Follow-Up Pipeline\n\nLocal artifact project for repeatable video follow-up runs.\nEOF\ngit add README.md\ngit commit -m \"Initialize video follow-up project\"\n```\n\nUse proof-oriented commit boundaries:\n\n```bash\ngit commit -m \"Capture source evidence for <run_id>\"\ngit commit -m \"Draft initial segmentation for <run_id>\"\ngit commit -m \"Record Oracle segmentation review for <run_id>\"\ngit commit -m \"Revise semantic chunk manifest\"\ngit commit -m \"Cut video chunks and ffprobe receipts\"\ngit commit -m \"Slice transcript and chat by chunk\"\ngit commit -m \"Run Gemini analysis for chunks 01-03\"\ngit commit -m \"Add verification reports for chunks 01-03\"\ngit commit -m \"Run omissions pass for chunk 01\"\ngit commit -m \"Reconcile verified chunk analyses\"\ngit commit -m \"Extract and review keyframe candidates\"\ngit commit -m \"Assemble teammate follow-up packet\"\ngit commit -m \"Document repeatable video follow-up process\"\n```\n\nDefault binary policy for future runs:\n\n- Commit text artifacts, manifests, prompts, logs, JSON, Markdown, reports, and checksums.\n- Do not commit large raw videos unless explicitly approved.\n- Commit chunk videos only for local archival projects or when Git LFS is configured.\n- Commit keyframes/contact sheets only when they are small enough and useful for review.\n\nSuggested `.gitignore` for future automation projects:\n\n```gitignore\nruns/**/inputs/*.mp4\nruns/**/inputs/*.mov\nruns/**/inputs/*.mkv\nruns/**/chunks/**/*.mp4\nruns/**/chunks/**/*.mov\n\n!runs/**/inputs/*.sha256\n!runs/**/receipts/**\n!runs/**/segments/**\n!runs/**/chunks/**/*.json\n!runs/**/chunks/**/*.md\n!runs/**/chunks/**/*.log\n!runs/**/final/**\n!runs/**/oracle/**\n\nruns/**/chunks/**/keyframes/extracted/*.jpg\nruns/**/chunks/**/keyframes/extracted/*.png\nruns/**/chunks/**/keyframes/strips/*.jpg\nruns/**/chunks/**/keyframes/contact-sheet*.jpg\n```\n\nIf committing binaries intentionally:\n\n```bash\ngit add -f \"$RUN_DIR/chunks/01/chunk.mp4\"\ngit add -f \"$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg\"\n```\n\n## Oracle Session Receipts\n\nFor every `$oracle-packx` call, save:\n\n```text\n- slug\n- date\n- run id\n- browser mode: true\n- ChatGPT conversation URL\n- bundle path\n- bundle sha256\n- prompt path\n- output log path\n- local decisions accepted/rejected\n- commit before\n- commit after\n```\n\nTemplate:\n\n```markdown\n# Oracle Session: {{session_slug}}\n\n- date:\n- local_run:\n- browser_mode: true\n- session_url:\n- bundle_path:\n- bundle_sha256:\n- prompt_file:\n- output_file:\n- commit_before:\n- commit_after:\n\n## Question\n\n## Oracle Response Summary\n\n## Local Decisions\n\nAccepted:\n\nRejected:\n\nFollow-up:\n```\n\n## Final Packet Review\n\nTreat these as first publication candidates:\n\n- `final/README.md`\n- `final/teammate-followup-guide.md`\n- `final/chapter-index.md`\n- `final/resources-and-links.md`\n- `final/instructor-review-checklist.md`\n\nTreat these as reference drafts until edited:\n\n- `final/qa-index.md`\n- `final/exercises.md`\n- `final/keyframes-manifest.md`\n\nManual approval is mandatory for:\n\n- platform automation\n- browser automation\n- cookies\n- session replay\n- quota/rate-limit behavior\n- account credentials\n- private emails\n- private chat exports\n- meeting transcript bot URLs\n- teammate names\n- screenshots of private repos\n- local network addresses\n- QR codes\n- API keys\n- package security claims\n- third-party service recommendations\n- public publishing\n\n## End-To-End Checklist\n\nProject setup:\n\n- [ ] Create run folder.\n- [ ] Copy source video into `inputs/`.\n- [ ] Copy transcript/chat/screenshots/clips if available.\n- [ ] Save source SHA256.\n- [ ] Save ffprobe source receipt.\n- [ ] Save tool versions.\n- [ ] Commit source evidence receipts.\n\nLong recording preprocessing:\n\n- [ ] Run `silencedetect`.\n- [ ] Review transcript and chat around silence spans.\n- [ ] Draft boundary candidates.\n- [ ] Create `segment-manifest.v1.json` and `.md`.\n- [ ] Bundle planning context with `$oracle-packx`.\n- [ ] Run Oracle review in browser mode.\n- [ ] Save Oracle session link/output locally.\n- [ ] Create `segment-manifest.v2.json` and `.md`.\n- [ ] Commit segmentation.\n\nChunk creation:\n\n- [ ] Cut chunks from original video.\n- [ ] `ffprobe` every chunk.\n- [ ] Create `chunks/video-manifest.json`.\n- [ ] Slice transcript per chunk.\n- [ ] Slice chat per chunk.\n- [ ] Preserve break chat separately.\n- [ ] Add carry-forward chat to next spoken chunk.\n- [ ] Add next-chunk preview.\n- [ ] Commit chunk receipts and slices.\n\nChunk analysis:\n\n- [ ] Create Gemini prompt per chunk.\n- [ ] Attach MP4, prompt, transcript, chat, carry-forward chat, and preview.\n- [ ] Save Gemini raw result/log.\n- [ ] Verify `END_OF_VIDEO_ANALYSIS` sentinel.\n- [ ] Extract all required information from the response into local artifacts.\n- [ ] Close the completed Gemini tab only after extraction and sentinel verification;\n      leave active Gemini tabs and the browser profile alive.\n- [ ] Extract machine JSON.\n- [ ] Build `expected-items.json`.\n- [ ] Run coverage verification.\n- [ ] Run hallucination/timestamp/Q&A checks.\n- [ ] Run omissions pass if any gate fails.\n- [ ] Commit analysis and verification reports.\n\nVisual evidence:\n\n- [ ] Generate keyframe candidates.\n- [ ] Extract deterministic frames.\n- [ ] Extract Gemini-proposed frames.\n- [ ] Extract strips for visual demos.\n- [ ] Create contact sheet.\n- [ ] Review frames.\n- [ ] Downgrade unsupported visual claims.\n- [ ] Commit visual manifests/reviews.\n\nReconciliation:\n\n- [ ] Merge main analysis, omissions, verification, and keyframe review.\n- [ ] Write `final-reconciled.md/json` per chunk.\n- [ ] Preserve warnings.\n- [ ] Remove malformed URLs.\n- [ ] Deduplicate carried-forward overlap.\n- [ ] Commit reconciled chunks.\n\nFinal packet:\n\n- [ ] Generate final README.\n- [ ] Generate teammate guide.\n- [ ] Generate chapter index.\n- [ ] Generate resources and links.\n- [ ] Generate Q&A index.\n- [ ] Generate exercises.\n- [ ] Generate keyframes manifest.\n- [ ] Generate instructor checklist.\n- [ ] Run malformed URL scan.\n- [ ] Run URL resolution check if public.\n- [ ] Run final packet review.\n- [ ] Commit final packet.\n\nProcess documentation:\n\n- [ ] Save this process as `docs/repeatable-video-followup-process.md`.\n- [ ] Inspect for exact commands, mode branches, prompts, and gates.\n- [ ] Commit process doc.\n\n## Automation Responsibilities\n\nReview the process before automating it. These are proposed implementation boundaries, not supplied executables:\n\n```text\nscripts/video-followup/init-run.ts\nscripts/video-followup/probe-source.ts\nscripts/video-followup/detect-silence.ts\nscripts/video-followup/build-segment-manifest.ts\nscripts/video-followup/cut-chunks.ts\nscripts/video-followup/slice-transcript.ts\nscripts/video-followup/slice-chat.ts\nscripts/video-followup/build-gemini-prompts.ts\nscripts/video-followup/extract-machine-json.ts\nscripts/video-followup/verify-coverage.ts\nscripts/video-followup/scan-malformed-urls.ts\nscripts/video-followup/extract-keyframes.ts\nscripts/video-followup/build-contact-sheet.ts\nscripts/video-followup/reconcile-chunk.ts\nscripts/video-followup/build-final-packet.ts\ntemplates/gemini/chunk-analysis.md\ntemplates/gemini/omissions.md\ntemplates/oracle/planning-review.md\ntemplates/oracle/final-review.md\ntemplates/final/README.md\ntemplates/final/teammate-followup-guide.md\ntemplates/final/chapter-index.md\ntemplates/final/resources-and-links.md\ntemplates/final/instructor-review-checklist.md\ndocs/automation-roadmap.md\n```\n\nAutomation priority:\n\n1. Malformed URL scanner.\n2. Timestamp validator.\n3. Expected-items builder from chat/transcript.\n4. Chunk prompt generator.\n5. ffmpeg chunk cutter.\n6. Keyframe extractor/contact sheet builder.\n7. Final packet assembler.\n\n## Operational boundaries\n\n- Apply the media/privacy ignore policy before the example staging command. Do not stage raw recordings, chats, transcripts, or account-bearing screenshots merely because they live under `inputs/`.\n- Automation file lists are proposed boundaries, not supplied programs. Template fields must be filled from real evidence, and a sentinel is a completion signal rather than proof of accuracy.\n- The video-capable provider, browser routing, model aliases, upload limits, and cleanup commands are integration-specific. Verify the attached-video readiness probe and retain uncertainty when evidence is missing.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-oracle-context-routing",
      "slug": "oracle-context-routing",
      "title": "Route large codebase questions through Oracle",
      "summary": "Route huge, read-heavy codebase questions to a browser ChatGPT session instead of burning Codex quota; Bundle dense repo context with PackX and hand it off via Oracle + an MCP/browser automation bridge; Drive a plan → implement → verify loop with Oracle on a separate high-context session.",
      "category": "Context",
      "tags": [
        "Oracle",
        "PackX",
        "context",
        "quota"
      ],
      "sources": [
        {
          "label": "Agent foundations: Route large codebase questions through Oracle (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-01.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#01/objectives",
        "oracle/01-references.json#recap",
        "oracle/01-references.json#concepts/0",
        "oracle/01-references.json#concepts/1",
        "oracle/01-references.json#concepts/2",
        "oracle/01-references.json#concepts/3",
        "oracle/01-references.json#concepts/4",
        "oracle/01-references.json#concepts/5",
        "oracle/01-references.json#references",
        "oracle/01-references.json#recommendations",
        "oracle/01-interactive.json#intro",
        "oracle/01-interactive.json#checklist",
        "oracle/01-interactive.json#challenges",
        "oracle/01-interactive.json#quiz",
        "oracle/01-interactive.json#reflect",
        "oracle/01-references.json#goDeeper",
        "materials/exercises.md#Chunk-01",
        "materials/qa-index.md#Q001",
        "materials/qa-index.md#Q002",
        "materials/keyframes.md#Chunk-01",
        "lesson-01.html#resource-packet",
        "lesson-01.html#clip-map",
        "lesson-01.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "context",
      "wordCount": 2309,
      "url": "/topics/foundations-oracle-context-routing/",
      "markdownUrl": "/markdown/foundations-oracle-context-routing.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-oracle-context-routing.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "codex-to-browser-quota-offloading",
          "text": "Codex-to-browser quota offloading",
          "level": 3
        },
        {
          "id": "chatgpt-pro-extended-context-window",
          "text": "ChatGPT Pro Extended context window",
          "level": 3
        },
        {
          "id": "oracle-browser-handoff",
          "text": "Oracle browser handoff",
          "level": 3
        },
        {
          "id": "packx-context-bundling",
          "text": "PackX context bundling",
          "level": 3
        },
        {
          "id": "mcp-browser-automation-bridge",
          "text": "MCP/browser automation bridge",
          "level": 3
        },
        {
          "id": "plan-implement-verify-loop",
          "text": "Plan, implement, verify loop",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "askoracle-sh",
          "text": "askoracle.sh",
          "level": 3
        },
        {
          "id": "john-lindquist-s-oracle-fork",
          "text": "John Lindquist's Oracle fork",
          "level": 3
        },
        {
          "id": "packx-pack-tool",
          "text": "PackX / pack tool",
          "level": 3
        },
        {
          "id": "model-context-protocol",
          "text": "Model Context Protocol",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "design-a-codex-vs-oracle-routing-table",
          "text": "Design a Codex-vs-Oracle Routing Table",
          "level": 3
        },
        {
          "id": "recreate-a-small-oracle-pass",
          "text": "Recreate a Small Oracle Pass",
          "level": 3
        },
        {
          "id": "build-a-plan-implement-verify-loop",
          "text": "Build a Plan-Implement-Verify Loop",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "what-problem-is-john-mainly-trying-to-solve-with-the-oracle-chatgpt-browser-workflow",
          "text": "What problem is John mainly trying to solve with the Oracle + ChatGPT browser workflow?",
          "level": 3
        },
        {
          "id": "what-does-oracle-primarily-do-in-the-demonstrated-workflow",
          "text": "What does Oracle primarily do in the demonstrated workflow?",
          "level": 3
        },
        {
          "id": "in-the-oracle-packx-mcp-pattern-shown-in-the-demo-what-does-packx-primarily-contribute",
          "text": "In the Oracle + PackX + MCP pattern shown in the demo, what does PackX primarily contribute?",
          "level": 3
        },
        {
          "id": "what-is-the-safest-way-to-understand-the-workshop-s-claim-about-chatgpt-pro-extended-versus-codex-token-mechanics",
          "text": "What is the safest way to understand the workshop's claim about ChatGPT Pro Extended versus Codex token mechanics?",
          "level": 3
        },
        {
          "id": "what-practical-limit-did-john-mention-for-running-these-browser-based-requests",
          "text": "What practical limit did John mention for running these browser-based requests?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "exercise-1-set-up-an-automated-remote-browser-prompt-agent",
          "text": "Exercise 1: Set Up an Automated Remote Browser Prompt Agent",
          "level": 3
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "goal-is-causing-me-to-hit-my-rate-limits-any-ideas-on-how-to-optimize-the-token-usage-when-running-goal",
          "text": "/goal is causing me to hit my rate limits.  Any ideas on how to optimize the token usage when running goal?",
          "level": 3
        },
        {
          "id": "is-this-mcp-only-limited-to-chatgpt-or-can-we-also-use-gemini",
          "text": "Is this MCP only limited to ChatGPT, or can we also use Gemini?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Route large codebase questions through Oracle\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is escaping Codex token and rate-limit pressure by separating huge read-only analysis from the interactive coding session. John shows that his ChatGPT Pro Extended browser session can accept far larger context than older sessions and, in his setup, does not consume the same Codex token budget; then he demonstrates Oracle plus PackX plus MCP/browser automation sending roughly 585,000 tokens from a codebase into ChatGPT on a separate Mac mini and bringing the result back into the workflow.\n\n## Working outcomes\n\n- Route huge, read-heavy codebase questions to a browser ChatGPT session instead of burning Codex quota\n- Bundle dense repo context with PackX and hand it off via Oracle + an MCP/browser automation bridge\n- Drive a plan → implement → verify loop with Oracle on a separate high-context session\n\n## Concepts and consequences\n\n### Codex-to-browser quota offloading\n\nJohn explains that dense, high-context questions can be sent to ChatGPT Pro Extended in the browser instead of spending Codex's interactive token and rate-limit budget. He describes this as useful for complicated questions where you want a large amount of packed context.\n\n**Why it matters:** Large repo-reading prompts can burn through Codex limits quickly. Routing the heavyweight analysis to the browser keeps Codex available for the parts of the workflow that need an agent to continue acting.\n\n### ChatGPT Pro Extended context window\n\nJohn says his $200-plan browser session exposes ChatGPT 5.5 Pro / Pro Extended with much longer context than before: he contrasts older ~50,000-token sessions with newer sessions that can take around a million tokens and often return in 10–15 minutes.\n\n**Why it matters:** The exact limits may change, but the taught idea is to notice that different surfaces have different context limits and to route work accordingly.\n\n### Oracle browser handoff\n\nOracle lets a current Codex session ask a browser session to do the heavy analysis: it packs things up, sends them to the browser, waits for the browser model to work, and then brings the result back into the coding session.\n\n**Why it matters:** This creates a handoff between a local agent workflow and a logged-in browser model without manually copying a massive prompt every time.\n\n### PackX context bundling\n\nIn the demo, John's Oracle PackX skill uses a pack tool to gather files related to a query. The run shown packs 45 files and reports roughly 585,000 tokens before sending the bundle to Oracle.\n\n**Why it matters:** PackX is the part of the workflow that turns scattered repo files into one large model-readable payload for the browser analysis pass.\n\n### MCP/browser automation bridge\n\nAfter the context is packed, the workflow makes an MCP call that reaches over to a browser on John's Mac mini, opens the ChatGPT session, inserts the prompt, and submits it.\n\n**Why it matters:** The MCP step is the bridge that lets the current agent trigger the outside browser workflow instead of requiring John to manually paste the packed prompt.\n\n### Plan, implement, verify loop\n\nJohn shows the broader pattern he uses: create a list of QA stories or goals, use Oracle to create a plan for each one, then implement it and verify it.\n\n**Why it matters:** The value is not just a one-off giant prompt; it is turning high-context planning into a repeatable loop that feeds back into actual code work.\n\n## Reference tools and resources\n\n### askoracle.sh\n\nPublic Oracle landing page shared in the workshop chat.\n\n**Use when:** Use it to understand the baseline Oracle concept before comparing it with John's workshop-specific fork.\n\n[Reference](https://askoracle.sh/)\n\n### John Lindquist's Oracle fork\n\nThe fork John points developers to for his specific setup, including browser mode, cookie debugging guidance, agents setup help, and the Oracle PackX skill.\n\n**Use when:** Use it when trying to study or reproduce the exact workflow John demonstrated.\n\n[Reference](https://github.com/johnlindquist/oracle)\n\n### PackX / pack tool\n\nThe context-packing layer used by John's Oracle PackX skill to gather relevant files and produce the large token bundle shown in the demo.\n\n**Use when:** Use it when you need Oracle to send a bundled codebase context prompt into the browser model.\n\n[Reference](https://github.com/johnlindquist/oracle)\n\n### Model Context Protocol\n\nThe tool-bridge mechanism John names when the packed request is handed off from the current agent workflow to the browser automation path.\n\n**Use when:** Use it as background for understanding the MCP call in the Oracle demo, not as a separate MCP configuration lesson from this section.\n\n[Reference](https://modelcontextprotocol.io/)\n\n## Recommendations and best practices\n\n- Use browser-side ChatGPT Pro Extended for huge, read-heavy codebase questions that would otherwise burn Codex context, but treat John's quota observations as his workshop setup rather than a permanent pricing or limit promise.\n- Use Oracle and PackX only when the request really needs a large repo bundle: PackX gathers the files, Oracle sends the bundle to the browser through MCP, and the answer comes back into the coding workflow.\n- Follow the fork's README, cookie-debugging, and agent setup guidance before trying to reproduce the browser workflow, because John says the setup is system-specific and may take effort.\n- Keep concurrency low. John says he would not run more than two or three browser requests at a time and has seen temporary pause popups after too many requests.\n- Shape repeat work as a loop: list the stories or goals, use Oracle to create a plan for each one, then implement and verify the result.\n\n## Practice and acceptance criteria\n\nPractice routing huge code-reading questions through an Oracle/PackX browser pass while keeping Codex focused on orchestration, implementation, and verification.\n\n### Checklist\n\n1. Identify one Codex request in your workflow that is mostly large-scale reading or planning rather than immediate local editing.\n2. Check whether your ChatGPT browser session and Codex session expose the same or different model surfaces, as John and the participants observed.\n3. Review askoracle.sh and John's Oracle fork, especially the README, cookie-debugging guidance, agents file, and Oracle PackX skill.\n4. Try the smallest version of the demo on a non-critical repo: ask for files related to one topic, let PackX build a bundle, and send it through Oracle/MCP to a browser session.\n5. Bring the returned plan back into your coding workflow and have Codex implement and verify one concrete item.\n6. Keep browser requests low-concurrency at first; use John's two-or-three-at-a-time guidance as the ceiling unless your own monitored setup proves otherwise.\n\n### Design a Codex-vs-Oracle Routing Table\n\n**Difficulty:** Medium\n\nFor one repo you actively use, list ten realistic AI requests and route each one to either the Codex session or an Oracle/browser analysis pass. Include a one-line reason for each route.\n\n**Done when:** Your table keeps local implementation and verification in the Codex workflow while moving huge read-only analysis to the Oracle/browser lane.\n\n### Recreate a Small Oracle Pass\n\n**Difficulty:** Hard\n\nUsing a small, non-critical repo, follow the Oracle fork guidance to send one topic-focused codebase question through the PackX → Oracle → MCP/browser path.\n\n**Done when:** You can point to the packed bundle/token count, the browser-submitted question, and the returned answer that came back into the workflow.\n\n### Build a Plan-Implement-Verify Loop\n\n**Difficulty:** Hard\n\nCreate three QA stories or goals for a repo. For each one, use Oracle to create the plan, then have the coding session implement the chosen change and verify it.\n\n**Done when:** Each story has an Oracle-generated plan, an implementation step, and a verification result.\n\n## Questions to test understanding\n\n### What problem is John mainly trying to solve with the Oracle + ChatGPT browser workflow?\n\n- **A.** Replacing all coding work with a workshop archive.\n- **B.** Moving dense, high-context analysis out of Codex so it does not burn the same Codex token and rate-limit budget.\n- **C.** Making Codex run tests faster by skipping browser sessions.\n- **D.** Avoiding the need to pack repository files at all.\n\n**Answer: B.** John frames the workflow as a way to send huge context to ChatGPT Pro Extended in the browser while preserving Codex's interactive budget for ongoing work.\n\n### What does Oracle primarily do in the demonstrated workflow?\n\n- **A.** It stores the workshop recording and screenshots for later search.\n- **B.** It replaces the local code editor.\n- **C.** It lets the current Codex session send packed context to a browser model and bring the result back.\n- **D.** It chooses the cheapest API model for every request.\n\n**Answer: C.** John describes Oracle as the bridge from the current Codex session to the browser: pack things up, send them to the browser, let the browser work, then bring the answer back.\n\n### In the Oracle + PackX + MCP pattern shown in the demo, what does PackX primarily contribute?\n\n- **A.** It decides which model is cheapest at runtime.\n- **B.** It packs relevant repository files into a large model-readable context bundle and estimates its size.\n- **C.** It runs the test suite after Codex applies changes.\n- **D.** It schedules workshop breaks.\n\n**Answer: B.** PackX is the context-packing layer: in the demo it gathers files related to the search topic and reports a roughly 585,000-token bundle.\n\n### What is the safest way to understand the workshop's claim about ChatGPT Pro Extended versus Codex token mechanics?\n\n- **A.** Assume browser-side work is permanently unlimited and free.\n- **B.** Treat the pricing and limits as a snapshot, but keep the architecture idea: separate high-context analysis from the Codex budget when possible.\n- **C.** Move all work out of Codex because Codex is only useful for small prompts.\n- **D.** Use browser automation specifically to bypass platform rules.\n\n**Answer: B.** The durable lesson is routing work across surfaces with different context and quota behavior. Account plans, rate limits, and platform behavior can change.\n\n### What practical limit did John mention for running these browser-based requests?\n\n- **A.** Never run more than one request per week.\n- **B.** Run as many parallel requests as possible because there are no pauses.\n- **C.** Keep it to about two or three at a time because too many requests can trigger a temporary pause.\n- **D.** Only run the workflow through the workshop archive.\n\n**Answer: C.** John says he has hit popups after too many requests and would not do more than two or three at a time.\n\n## Reflection prompts\n\n- Which of your current Codex requests are really huge-context reading or planning tasks?\n- Where would an Oracle browser pass be useful in your workflow, and where would it be overkill?\n- What concurrency limit would you set so browser automation remains monitorable and does not trigger the pause behavior John described?\n- Would a separate machine, browser profile, or dedicated screen make this workflow less disruptive for you, the way John's Mac mini did for him?\n\n## Further applications\n\n1. Read askoracle.sh to understand the general Oracle idea before studying John's fork.\n2. Review John's Oracle fork with attention to the README, cookie-debugging instructions, agents file, and Oracle PackX skill.\n3. Recreate the demonstrated flow on a small, non-critical repo: ask for files related to one topic, let PackX build the bundle, send it through Oracle, and compare the returned plan with what Codex can implement.\n4. Test your own account behavior cautiously with one browser request first, then increase only if you can monitor it and avoid the pause behavior John described.\n\n## Applied exercises\n\n### Exercise 1: Set Up an Automated Remote Browser Prompt Agent\n\n**Objective:**  Configure an isolated environment to programmatically inject codebase scripts into a standard browser instance using local session cookies.\n\n**Setup:** Clone the custom tracking engine fork from [https://github.com/johnlindquist/oracle](https://github.com/johnlindquist/oracle).Authenticate into an active web-based chat account inside your system's primary browser layout.\n\n**Task:** Execute the repository bundle scripts to pinpoint and read structural active authentication cookies (cookie debugging step).Use the provided automated templates via the repository agents instructions to link your workspace context directly with an active automation host loop.Execute a context collection command across a folder path of choice containing multiple files, ensuring the terminal processes and shifts token management completely to the browser interface window.\n\n**Acceptance Check:**  Verification is complete when text fields inside the separate browser app update and execute queries hands-free without using direct local API credentials.\n\n**Estimated Difficulty:**  Hard.\n\n## Questions and answers\n\n### /goal is causing me to hit my rate limits.  Any ideas on how to optimize the token usage when running goal?\n\nJohn addresses this broadly by showing how to move complex context out of direct local execution bounds and offloading it through the browser-driven Oracle process. This lets you execute large analytical loops outside your standard account limits.\n\n### Is this MCP only limited to ChatGPT, or can we also use Gemini?\n\nJohn details that his specific, customized structural additions in his personal fork focus heavily on ChatGPT integration because it bypasses the Codex quota. He notes the original baseline repository includes Gemini mechanics, though he hasn't personally validated that loop. However, since the engine operates by automating browser elements, it can theoretically hook any session (Perplexity, Devin, etc.) by extracting local browser session cookies.\n\n## Operational playbooks\n\n- [Oracle handoff for a huge codebase question](/topics/foundations-oracle-handoff-playbook/)\n\n- [Oracle + PackX Handoff Field Guide](/topics/foundations-oracle-packx-field-guide/)\n\n## Recording references\n\n- [Recording part 1](https://codex-workshop-followup.pages.dev/video/lessons/lesson-01-part-01.mp4)\n- [Recording part 2](https://codex-workshop-followup.pages.dev/video/lessons/lesson-01-part-02.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-01.html)\n\n### Visual reference index\n\n- [00:11:18](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-1): Visual reference at this recording position.\n- [00:21:55](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-2): Visual reference at this recording position.\n- [00:23:48](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-3): Visual reference at this recording position.\n- [00:10:55](https://codex-workshop-followup.pages.dev/lesson-01.html#clip-01-4): Visual reference at this recording position.\n- [00:11:40](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position. NotebookLM appears as context, not a taught implementation workflow.\n- [00:15:10](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position.\n- [00:19:28](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position.\n- [00:20:56](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position.\n- [00:22:25](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position.\n- [00:30:10](https://codex-workshop-followup.pages.dev/lesson-01.html): Visual reference at this recording position."
    },
    {
      "id": "codex-video-packets",
      "slug": "video-packets",
      "title": "Turn recordings into video evidence packets",
      "summary": "A long recording is not one prompt. It is a pile of evidence with a timeline.",
      "category": "Context",
      "tags": [
        "video",
        "evidence",
        "oracle"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#video-packets"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/The Failure",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/The Move",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Keep The Video",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Chunk By Evidence Density",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Ask For Screen Evidence",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Carry Prior Chunks Forward",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Use It For Software Work",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Copyable Artifact: Video Evidence Packet",
        "src/content/final/chunk-12-turn-long-recordings-into-video-evidence-packets.md#Turn Long Recordings Into Video Evidence Packets/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#video-packets",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 1233,
      "url": "/topics/codex-video-packets/",
      "markdownUrl": "/markdown/codex-video-packets.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-video-packets.json",
      "headings": [
        {
          "id": "the-failure",
          "text": "The Failure",
          "level": 2
        },
        {
          "id": "the-move",
          "text": "The Move",
          "level": 2
        },
        {
          "id": "keep-the-video",
          "text": "Keep The Video",
          "level": 2
        },
        {
          "id": "chunk-by-evidence-density",
          "text": "Chunk By Evidence Density",
          "level": 2
        },
        {
          "id": "ask-for-screen-evidence",
          "text": "Ask For Screen Evidence",
          "level": 2
        },
        {
          "id": "carry-prior-chunks-forward",
          "text": "Carry Prior Chunks Forward",
          "level": 2
        },
        {
          "id": "use-it-for-software-work",
          "text": "Use It For Software Work",
          "level": 2
        },
        {
          "id": "copyable-artifact-video-evidence-packet",
          "text": "Copyable Artifact: Video Evidence Packet",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Turn recordings into video evidence packets\n\nA long recording is not one prompt. It is a pile of evidence with a timeline.\n\nDo not reduce it to a transcript too early. Keep the video as prompt material, cut the recording into chunks, send each chunk through the video-watching lane, extract screen evidence while it is still visible, and carry prior summaries forward.\n\nThe artifact you want is not a summary. It is a **video evidence packet**.\n\n## The Failure\n\nA five-hour workshop, app walkthrough, or bug reproduction contains too much visual detail for one tidy answer.\n\nIf one model response has to summarize the whole recording, it will usually flatten the exact details software work needs:\n\n- tooltip text\n- disabled button states\n- cursor actions\n- modal transitions\n- terminal output\n- code snippets\n- missing steps\n- retries and failed attempts\n- loading, error, and empty states\n\nThe problem is not only upload size. The problem is **answer density**. One huge answer cannot carry every useful screen fact.\n\n> It's very difficult to get good information out of it that way, because it's limited by the amount of tokens it can provide in one response.\n>\n> — John Lindquist\n\n## The Move\n\nCreate video evidence packets.\n\nA video evidence packet is a **chunked, source-preserving record** of what happened in a slice of video:\n\n- clip\n- transcript slice\n- chat slice\n- key frames\n- visible text\n- UI states\n- actions\n- code snippets or terminal output\n- omissions\n- model output\n- verification notes\n\nThe packet gives the next agent inspectable context without pretending it watched the whole recording.\n\n## Keep The Video\n\nVideo is not just a transcript with pictures nearby. For UI work, the screen matters.\n\nA tooltip, hover state, selected tab, disabled button, cursor path, dialog, terminal frame, or loading spinner can be the evidence. Keep the clip attached as prompt material until the visual claims have been extracted and checked.\n\nIn the demonstrated workflow, the local agent owned the files, prompts, saved outputs, and verification. **[Oracle](https://github.com/johnlindquist/oracle)** handled the browser handoff. **[Gemini](https://gemini.google.com/app)** was the video-watching lane for that run. The repo received the output as reviewable files.\n\nTreat exact model behavior, limits, quotas, pricing, and account budget as current-product details that must be rechecked before relying on them in shared guidance.\n\n## Chunk By Evidence Density\n\nUse chunks small enough that each answer can stay specific.\n\n> What you can do with an agent is split the video into, like, 15-minute chunks, and then in each of those chunks, you can say, what are the key frames, what are the key ideas, what are the key transcript points.\n>\n> — John Lindquist\n\nFifteen minutes is a reasonable default for workshop or walkthrough material. Five minutes can be useful when the screen is dense, the bug is subtle, or the output needs frame-level detail.\n\nDo not turn those numbers into doctrine. **Choose chunk size by evidence density.**\n\nBefore analysis, remove confirmed dead space when it is safe:\n\n- long silence\n- blank screens\n- motionless regions\n- breaks\n- inactive spans\n\nDo not delete chat, links, questions, or setup context that explains the next spoken section. Carry that forward.\n\n## Ask For Screen Evidence\n\nUse the same evidence lanes for each chunk.\n\n```text\nFor this video chunk, extract:\n\nVisual evidence:\n- key frames\n- visible text\n- UI states\n- cursor actions\n- modal/dialog states\n- loading/error/empty states\n- code snippets or terminal output\n- colors, layout shifts, and visual changes\n\nTranscript evidence:\n- key spoken points\n- claims made\n- instructions given\n- unanswered questions\n- deferred follow-ups\n\nAction evidence:\n- user actions\n- app responses\n- navigation steps\n- failed attempts\n- retries\n- omissions or confusing transitions\n\nVerification:\n- what is directly visible\n- what is transcript-supported\n- what is inferred\n- what needs manual review\n```\n\nThis is the difference between \"the user clicked around\" and \"the tooltip text appeared next to the control, then the follow-up prompt asked what it said.\"\n\n## Carry Prior Chunks Forward\n\nChunking solves the density problem and creates a **continuity problem**.\n\nFix that by carrying a compact **previous-summary ledger** into every later prompt:\n\n```text\nYou are analyzing chunk 10 of 15 from a long software workshop.\n\nPrevious chunk summary:\n- Chunk 01 introduced the repo and evidence boundary.\n- Chunk 02 covered agent-ready repo setup.\n- Chunk 03 covered narrow workspace agents.\n- Chunk 04 covered generated variations.\n- Chunk 05 covered visual review before implementation.\n\nFor this chunk:\n- preserve original timestamps\n- extract visible UI states, actions, text, code snippets, and omissions\n- separate transcript evidence, visual evidence, and inference\n- return a chunk summary that can be carried into the next prompt\n```\n\nEvery later chunk should know what came before it: active concepts, unresolved questions, decisions already made, and what the current chunk must not re-explain.\n\n## Use It For Software Work\n\nGood fits:\n\n- QA records a checkout regression and the packet extracts the disabled button state, selected shipping option, console error, and missing validation message.\n- A designer records a settings walkthrough and the packet extracts empty states, modal transitions, keyboard traps, contrast concerns, and confusing copy.\n- A product team records its own onboarding flow and the packet turns it into acceptance criteria.\n- A developer combines a debug marker packet with the video chunk around the marked moment.\n\nProduct research also fits, but keep the ethics boundary clear. Use public walkthroughs for UX critique, accessibility review, flow comparison, and internal design study. Do not present this as a way to copy proprietary UI, assets, copy, CSS, or product behavior.\n\n## Copyable Artifact: Video Evidence Packet\n\n```text\nSource:\n- recording:\n- source hash:\n- original timestamp range:\n- transcript slice:\n- chat slice:\n- chunk id:\n- prior summary included? yes/no\n\nPreprocessing:\n- silence reviewed:\n- motionless/blank spans reviewed:\n- removed spans:\n- carried-forward chat/questions:\n\nAsk the video model to extract:\n- key frames:\n- visible text:\n- transcript points:\n- user actions:\n- UI states:\n- code snippets or terminal output:\n- colors/layout changes:\n- loading/error/empty states:\n- omissions:\n- uncertainties:\n\nCumulative context:\n- previous chunks summarized:\n- unresolved questions:\n- concepts already introduced:\n- what this chunk must not re-explain:\n\nVerification:\n- claims supported by transcript:\n- claims supported by visual evidence:\n- claims supported by chat:\n- claims that are inference only:\n- private details removed:\n- screenshots/keyframes sanitized:\n- model/cost/limit claims removed or verified:\n```\n\nExample prompt:\n\n```text\nAnalyze this checkout bug recording as chunk 03 of 08.\n\nPrevious summary:\n[paste compact prior-summary ledger]\n\nExtract:\n- visible UI states\n- cursor actions\n- selected fields\n- loading/error/empty states\n- visible text\n- transcript claims\n- omitted steps\n- uncertainties\n\nSeparate visual evidence, transcript evidence, chat evidence, and inference.\nReturn a short carry-forward summary for the next chunk.\n```\n\n## Claim Boundaries\n\nThis workflow does not prove model limits, pricing, quota behavior, speed, or model superiority.\n\nIt proves that a recording was processed through a chunked, source-preserving workflow and that shared claims can be checked against transcript, video evidence, key frames, chat, and saved outputs.\n\nBefore sharing screenshots or key frames, sanitize them, copy them into the shared asset tree, add alt text, and review for private browser/account state.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#video-packets)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-video-workflows-reference",
      "slug": "video-workflows-reference",
      "title": "Video analysis and evidence workflows: practical reference",
      "summary": "Repeatable video-to-prompt workflow covering source preservation, hashing and media receipts, chunking, Oracle/Gemini analysis, timestamped evidence lanes, sentinel checks, keyframes, omissions review, privacy gates, and downstream implementation, QA, and…",
      "category": "Context",
      "tags": [
        "video",
        "oracle",
        "evidence"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Tool Reference",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Core Pattern",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Short Path vs Long Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Run Folder Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Preserve The Source",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Evidence Lanes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Prompt With A Sentinel",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Analyze With Gemini",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Verify The Analysis",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Omissions Pass",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Turn Video Into Prompt Material",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/No Source Hash",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/No `ffprobe` Output",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/Oracle Call Used API Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/File Path Was Relative",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/Sentinel Missing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/Analysis Only Summarizes Transcript",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/Visual Claim Has No Keyframe",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/URL, Tool, Command, Or File Appears Without Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/If It Goes Wrong/Long Recording Was Not Chunked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/07-video-as-prompts.md#07. Video As Prompts/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 2668,
      "url": "/topics/codex-video-workflows-reference/",
      "markdownUrl": "/markdown/codex-video-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-video-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "tool-reference",
          "text": "Tool Reference",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "core-pattern",
          "text": "Core Pattern",
          "level": 2
        },
        {
          "id": "short-path-vs-long-path",
          "text": "Short Path vs Long Path",
          "level": 2
        },
        {
          "id": "run-folder-shape",
          "text": "Run Folder Shape",
          "level": 2
        },
        {
          "id": "preserve-the-source",
          "text": "Preserve The Source",
          "level": 2
        },
        {
          "id": "evidence-lanes",
          "text": "Evidence Lanes",
          "level": 2
        },
        {
          "id": "prompt-with-a-sentinel",
          "text": "Prompt With A Sentinel",
          "level": 2
        },
        {
          "id": "analyze-with-gemini",
          "text": "Analyze With Gemini",
          "level": 2
        },
        {
          "id": "verify-the-analysis",
          "text": "Verify The Analysis",
          "level": 2
        },
        {
          "id": "omissions-pass",
          "text": "Omissions Pass",
          "level": 2
        },
        {
          "id": "turn-video-into-prompt-material",
          "text": "Turn Video Into Prompt Material",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "no-source-hash",
          "text": "No Source Hash",
          "level": 3
        },
        {
          "id": "no-ffprobe-output",
          "text": "No `ffprobe` Output",
          "level": 3
        },
        {
          "id": "oracle-call-used-api-mode",
          "text": "Oracle Call Used API Mode",
          "level": 3
        },
        {
          "id": "file-path-was-relative",
          "text": "File Path Was Relative",
          "level": 3
        },
        {
          "id": "sentinel-missing",
          "text": "Sentinel Missing",
          "level": 3
        },
        {
          "id": "analysis-only-summarizes-transcript",
          "text": "Analysis Only Summarizes Transcript",
          "level": 3
        },
        {
          "id": "visual-claim-has-no-keyframe",
          "text": "Visual Claim Has No Keyframe",
          "level": 3
        },
        {
          "id": "url-tool-command-or-file-appears-without-evidence",
          "text": "URL, Tool, Command, Or File Appears Without Evidence",
          "level": 3
        },
        {
          "id": "long-recording-was-not-chunked",
          "text": "Long Recording Was Not Chunked",
          "level": 3
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Video analysis and evidence workflows: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up a repeatable video-as-prompt run for this project before doing any full video analysis.\n\n1. Resolve the `oracle-video` skill first. Check for `skills/oracle-video/SKILL.md`; if it is not bundled, check the common local install path at `.agents/skills/oracle-video/SKILL.md`. Read the skill and any directly referenced repeatable video process file before creating outputs. If the skill is missing, stop and report the missing path checks.\n\n2. Create a run id like `<YYYY-MM-DD>-<short-slug>` and a run folder at `runs/<run-id>/` with this structure: `inputs/`, `receipts/`, `chunks/01/`, `analysis/`, `final/`, `keyframes/`, and `contact-sheets/`.\n\n3. Accept either a local video path or a video URL. For a local file, copy it to `inputs/source-video.<ext>` and keep that copy immutable. For a URL, first save metadata with `yt-dlp --dump-single-json --skip-download --no-check-formats` to `receipts/source.metadata.json`, then download with `yt-dlp -f \"bv*+ba/best\"` into `inputs/`.\n\n4. Write a source hash with `shasum -a 256` to `inputs/source-video.sha256`. Confirm the file exists and is non-empty.\n\n5. Capture media facts with `ffprobe -hide_banner -show_format -show_streams -of json` and save them to `receipts/ffprobe.source.json`. Confirm the file exists and is non-empty. If `ffprobe`, `ffmpeg`, or `yt-dlp` is missing, stop setup and report the missing tool plus the failed command.\n\n6. Prepare `chunks/01/chunk.mp4`. For a short video, copy the source video into that path. For a long video, create additional numbered chunk folders as needed and save a timestamp mapping note before any analysis. Use absolute paths for every video file that will be attached to Oracle.\n\n7. Write `chunks/01/gemini-prompt.md`. It must request separate lanes for transcript evidence, chat evidence, visual evidence, and inference. It must require preserved timestamps, forbid invented URLs, tools, commands, files, UI labels, and speakers, and end with the exact final line `END_OF_VIDEO_ANALYSIS`.\n\n8. Write `chunks/01/expected-sentinel.txt` containing only `END_OF_VIDEO_ANALYSIS`. Confirm the sentinel appears in `gemini-prompt.md` and that the expected sentinel file is non-empty.\n\n9. Prepare `chunks/01/oracle-call.json` or equivalent setup notes with the required Gemini browser-mode contract: `engine: \"browser\"`, `model: \"gemini-3-pro\"`, `browserAttachments: \"always\"`, `files` containing an absolute path to `chunks/01/chunk.mp4`, and a stable slug. Do not use API mode for video analysis.\n\n10. Generate keyframes and a contact sheet if `ffmpeg` is available. Save frames under `keyframes/` using a low-frequency extraction such as `fps=1/10`, then save a tiled contact sheet under `contact-sheets/`. If generation is skipped, save the exact commands to run later and report why they were not run.\n\n11. Create evidence lane files under `analysis/`: `transcript.md`, `chat.md`, `visual-evidence.md`, and `inference.md`. Keep spoken claims, chat or comments, visible facts, and reasoned conclusions separate. Label inference clearly until code, runtime behavior, or visual checks support it.\n\n12. Create `analysis/omissions-pass-prompt.md`. It should ask only for missing visible UI states, skipped timestamps, unsupported claims, invented details, uncertainty, and patch-style corrections. It must require the response to end with `END_OF_VIDEO_ANALYSIS`.\n\n13. Create downstream artifact stubs under `final/`, such as `implementation-prompt.md`, `qa-checklist.md`, and `variation-matrix.md`. Leave evidence-dependent fields blank until verified analysis exists.\n\n14. Enforce privacy boundaries before any upload or external analysis. Do not print full environment output, tokens, cookies, API keys, private endpoints, resolved secret values, or raw private config. Do not copy secret helper files into the run folder. If the video, metadata, transcript, or chat text contains credentials or private config, stop and report the issue instead of uploading.\n\n15. Run a setup verification gate before Gemini analysis. Report `OK` or `MISSING` for: `oracle-video` skill resolved, source video exists, source hash non-empty, `ffprobe.source.json` non-empty, URL metadata present when the input is a URL, chunk file exists, Gemini prompt exists, sentinel file exists, Oracle call uses browser mode with `gemini-3-pro` and `browserAttachments: \"always\"`, Oracle file path is absolute, evidence lane files exist, keyframes/contact sheet exist or commands are saved, omissions prompt exists, and downstream stubs exist.\n\n16. Stop before full video analysis unless every required setup check passes. Return the run id, absolute run folder path, commands run, verification report, failed checks, and the smallest next fix if anything is missing. Only say it is ready for Gemini analysis after the setup gate passes.\n```\n\n## Big Idea\n\nVideo is prompt material.\n\n## Try This Now\n\nFor a short bug repro video, create a run folder and save a source hash.\nWrite the Gemini prompt with separate lanes: transcript, chat, visual evidence, inference.\nEnd the prompt with `END_OF_VIDEO_ANALYSIS` before analysis starts.\n\nA screen recording can show things a written prompt usually loses:\n\n- order of operations\n- cursor movement\n- hesitation\n- timing\n- hidden assumptions\n- actual UI state\n- terminal output\n- visible browser pages\n- misclicks\n- loading states\n- visual hierarchy\n- broken affordances\n- spoken explanation\n- chat context\n\nA transcript can tell you what someone said. A video can show what happened.\n\n## Tool Reference\n\nUse `oracle-video` when the task depends on what is visible or audible in a recording.\n\nConceptually:\n\n```text\noracle-packx bundles code/text context for ChatGPT.\noracle-video attaches video and sends it to Gemini through Oracle browser mode.\n```\n\nCorrect Oracle call shape for video analysis:\n\n```js\nmcp__oracle__consult({\n  prompt: \"[video-analysis-slug]\\n\\n{contents of chunks/01/gemini-prompt.md}\",\n  files: [\"/absolute/path/to/runs/bug-repro/chunks/01/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",\n  browserAttachments: \"always\",\n  slug: \"video-analysis-slug\"\n})\n```\n\nRequired:\n\n```text\nengine: \"browser\"\nmodel: \"gemini-3-pro\"\nbrowserAttachments: \"always\"\nabsolute file path\n```\n\nDo not use API mode for video analysis.\n\n## When To Reach For This\n\nUse video when the important context is visible, temporal, or hard to describe.\n\n| Use Video For | Why |\n| --- | --- |\n| bug reproduction clip | captures exact UI state, clicks, errors, timing |\n| design feedback video | preserves visual hierarchy and spoken intent |\n| app walkthrough | turns observed workflow into requirements and QA checks |\n| loading/timing bug | shows delay, spinner, race, or order of events |\n| terminal/browser workflow | preserves commands, pages, output, and sequence |\n| long tutorial or workshop recording | can become chapters, exercises, references, and follow-up prompts |\n\nSkip video when:\n\n- a short log already proves the issue\n- a failing test names the exact bug\n- the needed context is one code path\n- the video source cannot be preserved\n- claims cannot be verified against timestamps, keyframes, or source output\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nWatch the video, summarize from memory, then ask the agent to fix the vague thing.\n```\n\nWhat the workflow gives you now:\n\n```text\nPreserve the source, capture hashes and media facts, analyze with Gemini, keep\nevidence lanes separate, verify claims, then turn the result into a grounded\nprompt.\n```\n\nWhat you used to expect:\n\n```text\nA transcript is the prompt.\n```\n\nWhat the workflow gives you now:\n\n```text\nThe transcript is one evidence lane. Visual state, timing, chat, cursor motion,\nand inference stay separate until verified.\n```\n\n## Core Pattern\n\n```text\nsource media\n-> source receipts\n-> Gemini analysis\n-> evidence lanes\n-> verification\n-> downstream prompt\n```\n\nDo not skip the middle.\n\n```text\nvideo without source receipts = hard to trust\nanalysis without timestamps = hard to verify\ntranscript without visuals = incomplete\nclaims without keyframes = risky\nprompt without verification = hallucination bait\n```\n\n## Short Path vs Long Path\n\n| Path | Use For | Shape |\n| --- | --- | --- |\n| short path | bug repros, design feedback clips, quick app walkthroughs | preserve source, one Gemini pass, keyframes, downstream artifact |\n| long path | long tutorials, workshop recordings, multi-section demos | source receipts, segment/chunk, analyze chunks, omissions pass, reconcile, final packet |\n\nShort path output examples:\n\n- repro steps\n- implementation prompt\n- design-change brief\n- QA checklist\n- requirements note\n\nLong path output examples:\n\n- chapter index\n- lesson notes\n- exercise packet\n- resource list\n- follow-up prompts\n- Section 6 variation matrix\n\n## Run Folder Shape\n\nUse a run folder so the video stays tied to its analysis.\n\n```text\nruns/<date>-<slug>/\n  inputs/\n    source-video.mp4\n    source-video.sha256\n  receipts/\n    ffprobe.source.json\n  chunks/\n    01/\n      chunk.mp4\n      gemini-prompt.md\n      expected-sentinel.txt\n      output.log\n      analysis.md\n  analysis/\n  final/\n  keyframes/\n  contact-sheets/\n```\n\nCreate the folders:\n\n```bash\nRUN_ID=\"checkout-repro\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,final,keyframes,contact-sheets}\nmkdir -p \"$RUN_DIR/chunks/01\"\n```\n\n## Preserve The Source\n\nKeep the original media immutable.\n\nFor a local file:\n\n```bash\ncp /path/to/source-video.mp4 \"$RUN_DIR/inputs/source-video.mp4\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/inputs/source-video.sha256\"\n```\n\nFor a URL source, capture metadata first when useful:\n\n```bash\nyt-dlp --dump-single-json --skip-download --no-check-formats \"$URL\" \\\n  > \"$RUN_DIR/receipts/source.metadata.json\"\n```\n\nThen download:\n\n```bash\nyt-dlp -f \"bv*+ba/best\" -o \"$RUN_DIR/inputs/source-video.%(ext)s\" \"$URL\"\n```\n\nCapture media facts:\n\n```bash\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nConfirm:\n\n```bash\ntest -s \"$RUN_DIR/inputs/source-video.sha256\" && echo \"sha256:OK\"\ntest -s \"$RUN_DIR/receipts/ffprobe.source.json\" && echo \"ffprobe:OK\"\n```\n\n## Evidence Lanes\n\nKeep these lanes separate:\n\n| Lane | What It Means | Example |\n| --- | --- | --- |\n| transcript | spoken words | “The save button disappears.” |\n| chat | chat messages or comments | “This only happens after refresh.” |\n| visual evidence | visible UI state | save button hidden at `00:01:34` |\n| inference | reasoned conclusion | likely state reset after token refresh |\n\nPlain rule:\n\n```text\nA spoken claim is not a visible fact.\nA visible fact is not automatically the cause.\nAn inference must stay labeled until code or runtime proof confirms it.\n```\n\n## Prompt With A Sentinel\n\nSave the Gemini prompt beside the chunk.\n\n```bash\ncat > \"$RUN_DIR/chunks/01/gemini-prompt.md\" <<'EOF'\nAnalyze this video as prompt material for a software project.\n\nReturn:\n\n1. short summary\n2. timestamped workflow\n3. transcript evidence\n4. chat evidence\n5. visual evidence\n6. inferences, clearly labeled\n7. likely downstream artifacts\n8. omissions or uncertainty\n\nRules:\n\n- Do not invent URLs, tools, commands, files, UI labels, or speakers.\n- Preserve original timestamps.\n- Separate visible facts from spoken claims and inferences.\n- Include the exact sentinel below as the last line.\n\nEND_OF_VIDEO_ANALYSIS\nEOF\n\nprintf 'END_OF_VIDEO_ANALYSIS\\n' \\\n  > \"$RUN_DIR/chunks/01/expected-sentinel.txt\"\n```\n\nConfirm:\n\n```bash\nrg -n \"END_OF_VIDEO_ANALYSIS\" \"$RUN_DIR/chunks/01/gemini-prompt.md\"\ntest -s \"$RUN_DIR/chunks/01/expected-sentinel.txt\" && echo \"sentinel:OK\"\n```\n\n## Analyze With Gemini\n\nUse Oracle browser mode and attach the video.\n\n```js\nmcp__oracle__consult({\n  prompt: \"[checkout-repro-video]\\n\\n{contents of runs/.../chunks/01/gemini-prompt.md}\",\n  files: [\"/absolute/path/to/runs/checkout-repro/chunks/01/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",\n  browserAttachments: \"always\",\n  slug: \"checkout-repro-video\"\n})\n```\n\nAfter the run, read the local output:\n\n```bash\nsed -n '1,220p' ~/.oracle/sessions/checkout-repro-video/output.log\nrg -n \"END_OF_VIDEO_ANALYSIS\" ~/.oracle/sessions/checkout-repro-video/output.log\n```\n\nIf the output is clipped in a tool response, treat `output.log` as the local source to inspect.\n\n## Verify The Analysis\n\nCheck that the answer is grounded.\n\n| Check | Command Or Evidence |\n| --- | --- |\n| source hash exists | `test -s \"$RUN_DIR/inputs/source-video.sha256\"` |\n| media facts exist | `test -s \"$RUN_DIR/receipts/ffprobe.source.json\"` |\n| prompt saved | `test -s \"$RUN_DIR/chunks/01/gemini-prompt.md\"` |\n| sentinel present | `rg -n \"END_OF_VIDEO_ANALYSIS\" output.log` |\n| timestamps preserved | compare analysis timestamps to source duration |\n| visual claims checked | keyframes or contact sheet |\n| invented facts removed | no unsupported URLs/tools/commands/files |\n| omissions captured | missing sections are listed as uncertainty |\n\nExtract keyframes for visual checks:\n\n```bash\nmkdir -p \"$RUN_DIR/keyframes\"\nffmpeg -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -vf \"fps=1/10\" \\\n  \"$RUN_DIR/keyframes/frame-%04d.jpg\"\n```\n\nCreate a contact sheet:\n\n```bash\nffmpeg -pattern_type glob -i \"$RUN_DIR/keyframes/*.jpg\" \\\n  -vf \"scale=320:-1,tile=4x4\" \\\n  \"$RUN_DIR/contact-sheets/source-contact-sheet.jpg\"\n```\n\n## Omissions Pass\n\nRun an omissions pass when coverage is incomplete.\n\nAsk:\n\n```text\nReview the prior video analysis for omissions.\n\nFocus only on missing visible UI states, skipped timestamps, unsupported claims,\ninvented details, and uncertainty. Do not rewrite the whole analysis. Return a\npatch-style list of corrections and end with END_OF_VIDEO_ANALYSIS.\n```\n\nUse the omissions pass when:\n\n- the first analysis only summarizes the transcript\n- key UI states are missing\n- timestamps are vague\n- the model invents tools, URLs, files, or labels\n- a long recording was not chunked\n- the downstream prompt depends on visual details\n\n## Turn Video Into Prompt Material\n\nCommon downstream artifacts:\n\n| Video Source | Downstream Artifact |\n| --- | --- |\n| bug reproduction | repro steps, expected vs actual behavior, implementation prompt |\n| design feedback | visual acceptance criteria, change brief, QA checklist |\n| app walkthrough | requirements, acceptance criteria, open questions |\n| terminal workflow | command sequence, failure point, debugging prompt |\n| long recording | chapters, exercises, resources, follow-up packet |\n| UI alternatives | Section 6 variation matrix |\n\nBug prompt shape:\n\n```markdown\n# Implementation Prompt From Video\n\n## Source\n\n- video:\n- source hash:\n- ffprobe:\n- analysis:\n- keyframes:\n\n## Observed Failure\n\n- timestamp:\n- visual evidence:\n- transcript/chat evidence:\n- expected behavior:\n- actual behavior:\n\n## Request\n\nImplement the smallest safe fix.\n\n## Constraints\n\n- do not change:\n- preserve:\n\n## Verification\n\n- command:\n- what passing means:\n```\n\nVariation seed shape:\n\n```markdown\n# Video-Derived Variation Matrix\n\n## Goal\n\n## Evidence From Video\n\n- timestamp:\n- observation:\n- keyframe:\n- why it matters:\n\n## Invariants\n\n- same source evidence:\n- same target flow:\n- same verification command:\n- same review criteria:\n\n## Variable Under Test\n\n- variable:\n- why this variable matters:\n- what is out of scope:\n```\n\n## Ask The Agent This\n\nAnalyze a bug reproduction:\n\n```text\nUse the video analysis workflow.\n\nPreserve the source video, save a source hash and ffprobe output, write a Gemini\nprompt with END_OF_VIDEO_ANALYSIS, analyze the video through Oracle browser mode\nwith Gemini, then separate transcript evidence, visual evidence, chat evidence,\nand inference. Turn the verified result into repro steps and an implementation\nprompt for the smallest safe fix.\n```\n\nReview design feedback:\n\n```text\nTurn this design feedback video into a change brief.\n\nKeep visible UI facts separate from spoken opinions. Save keyframes for the\nvisual claims. Produce acceptance criteria, a QA checklist, and open questions.\nDo not invent UI labels or routes that are not visible or spoken.\n```\n\nCreate a Section 6 seed:\n\n```text\nUse this verified video analysis to create a controlled variation matrix.\n\nChoose one variable under test, preserve the same source evidence and\nverification command for every candidate, and write three candidate settings.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| source preserved | original media exists under `inputs/` |\n| source hash saved | `source-video.sha256` exists and is non-empty |\n| media facts saved | `ffprobe.source.json` exists |\n| prompt saved | `chunks/01/gemini-prompt.md` exists |\n| sentinel required | `expected-sentinel.txt` exists |\n| Oracle call shape correct | `engine: \"browser\"`, `model: \"gemini-3-pro\"`, `browserAttachments: \"always\"` |\n| output inspected | `~/.oracle/sessions/<slug>/output.log` read |\n| sentinel present | `END_OF_VIDEO_ANALYSIS` found in output |\n| lanes separated | transcript, chat, visual evidence, inference are separate |\n| visual claims checked | keyframes/contact sheet exists |\n| unsupported claims removed | no invented URLs/tools/commands/files |\n| downstream artifact saved | repro, requirements, QA, brief, lesson, or matrix exists |\n\n## If It Goes Wrong\n\n### No Source Hash\n\nCreate it before analysis:\n\n```bash\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/inputs/source-video.sha256\"\n```\n\n### No `ffprobe` Output\n\nRun:\n\n```bash\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\n### Oracle Call Used API Mode\n\nRerun with browser mode.\n\n```text\nengine: \"browser\"\nmodel: \"gemini-3-pro\"\nbrowserAttachments: \"always\"\n```\n\n### File Path Was Relative\n\nUse an absolute video path in `files`.\n\n```bash\nrealpath \"$RUN_DIR/chunks/01/chunk.mp4\"\n```\n\n### Sentinel Missing\n\nRead `output.log`. If the sentinel is truly missing, rerun or ask for an omissions pass.\n\n```bash\nrg -n \"END_OF_VIDEO_ANALYSIS\" ~/.oracle/sessions/<slug>/output.log\n```\n\n### Analysis Only Summarizes Transcript\n\nRun an omissions pass focused on visual evidence:\n\n```text\nFind missing visual UI states, cursor actions, timing, browser/terminal state,\nand unsupported claims. Preserve timestamps.\n```\n\n### Visual Claim Has No Keyframe\n\nExtract keyframes or create a contact sheet. Downgrade unsupported claims to inference.\n\n### URL, Tool, Command, Or File Appears Without Evidence\n\nRemove it or label it as inference. Do not let invented details become prompt constraints.\n\n### Long Recording Was Not Chunked\n\nCreate chunks and analyze them separately. Preserve original timestamps across chunks.\n\n## References And Resources\n\n- `oracle-video` local skill: `skills/oracle-video/SKILL.md` if bundled, or common local skill install under `.agents/skills/oracle-video/SKILL.md`\n- `yt-dlp`: https://github.com/yt-dlp/yt-dlp\n- FFmpeg documentation: https://ffmpeg.org/documentation.html\n- `ffprobe` documentation: https://ffmpeg.org/ffprobe.html\n- Gemini app: https://gemini.google.com/app\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-video-workflows-practice",
      "slug": "video-workflows-practice",
      "title": "Video analysis and evidence workflows: practice drills",
      "summary": "Exercises for choosing video input, preserving and hashing source media, recording metadata, constructing analysis prompts and Oracle calls, separating evidence lanes, checking outputs, extracting visual evidence, reviewing omissions, and producing…",
      "category": "Context",
      "tags": [
        "video",
        "oracle",
        "evidence",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 1: Decide Whether Video Is Useful",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 2: Create The Run Folder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 3: Preserve Source Media",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 4: Write The Gemini Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 5: Check Oracle Call Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 6: Separate Evidence Lanes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 7: Verify The Analysis",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 8: Extract Keyframes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 9: Write An Omissions Pass Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 10: Create A Bug Repro Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 11: Convert Video Evidence Into A Section 6 Matrix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Exercise 12: Section 8 Bridge",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/07-video-as-prompts.md#Exercises: 07. Video As Prompts/Final Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "context",
      "wordCount": 1262,
      "url": "/topics/codex-video-workflows-practice/",
      "markdownUrl": "/markdown/codex-video-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-video-workflows-practice.json",
      "headings": [
        {
          "id": "exercise-1-decide-whether-video-is-useful",
          "text": "Exercise 1: Decide Whether Video Is Useful",
          "level": 2
        },
        {
          "id": "exercise-2-create-the-run-folder",
          "text": "Exercise 2: Create The Run Folder",
          "level": 2
        },
        {
          "id": "exercise-3-preserve-source-media",
          "text": "Exercise 3: Preserve Source Media",
          "level": 2
        },
        {
          "id": "exercise-4-write-the-gemini-prompt",
          "text": "Exercise 4: Write The Gemini Prompt",
          "level": 2
        },
        {
          "id": "exercise-5-check-oracle-call-shape",
          "text": "Exercise 5: Check Oracle Call Shape",
          "level": 2
        },
        {
          "id": "exercise-6-separate-evidence-lanes",
          "text": "Exercise 6: Separate Evidence Lanes",
          "level": 2
        },
        {
          "id": "exercise-7-verify-the-analysis",
          "text": "Exercise 7: Verify The Analysis",
          "level": 2
        },
        {
          "id": "exercise-8-extract-keyframes",
          "text": "Exercise 8: Extract Keyframes",
          "level": 2
        },
        {
          "id": "exercise-9-write-an-omissions-pass-prompt",
          "text": "Exercise 9: Write An Omissions Pass Prompt",
          "level": 2
        },
        {
          "id": "exercise-10-create-a-bug-repro-prompt",
          "text": "Exercise 10: Create A Bug Repro Prompt",
          "level": 2
        },
        {
          "id": "exercise-11-convert-video-evidence-into-a-section-6-matrix",
          "text": "Exercise 11: Convert Video Evidence Into A Section 6 Matrix",
          "level": 2
        },
        {
          "id": "exercise-12-section-8-bridge",
          "text": "Exercise 12: Section 8 Bridge",
          "level": 2
        },
        {
          "id": "final-check",
          "text": "Final Check",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Video analysis and evidence workflows: practice drills\n\nThese exercises practice turning video into verified prompt material.\n\nUse a short clip when possible. A 30-90 second bug reproduction or design feedback clip is enough.\n\n## Exercise 1: Decide Whether Video Is Useful\n\nChoose `video`, `text/log`, or `code context`.\n\n| Scenario | Best Input | Why |\n| --- | --- | --- |\n| checkout button disappears after a sequence of clicks | | |\n| unit test failure points to one function | | |\n| designer explains spacing problems while moving through UI | | |\n| terminal command prints one clear stack trace | | |\n| app feels slow after refresh but logs are clean | | |\n| long tutorial should become exercises and references | | |\n| auth/session architecture needs cross-file review | | |\n\nFill out:\n\n```markdown\n# Input Choice\n\n- scenario:\n- chosen input:\n- why:\n- what video would add:\n- what text/logs would add:\n- what code context would add:\n```\n\n## Exercise 2: Create The Run Folder\n\nRun:\n\n```bash\nRUN_ID=\"exercise-video-$(date +%Y%m%d-%H%M%S)\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,final,keyframes,contact-sheets}\nmkdir -p \"$RUN_DIR/chunks/01\"\nfind \"$RUN_DIR\" -maxdepth 3 -type d | sort\n```\n\nFill out:\n\n```markdown\n# Video Run Folder\n\n- run id:\n- run dir:\n- inputs:\n- receipts:\n- chunks:\n- analysis:\n- final:\n- keyframes:\n```\n\n## Exercise 3: Preserve Source Media\n\nFor a local video:\n\n```bash\ncp /path/to/source-video.mp4 \"$RUN_DIR/inputs/source-video.mp4\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/inputs/source-video.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor a URL:\n\n```bash\nyt-dlp --dump-single-json --skip-download --no-check-formats \"$URL\" \\\n  > \"$RUN_DIR/receipts/source.metadata.json\"\nyt-dlp -f \"bv*+ba/best\" -o \"$RUN_DIR/inputs/source-video.%(ext)s\" \"$URL\"\n```\n\nConfirm:\n\n```bash\ntest -s \"$RUN_DIR/inputs/source-video.sha256\" && echo \"sha256:OK\"\ntest -s \"$RUN_DIR/receipts/ffprobe.source.json\" && echo \"ffprobe:OK\"\n```\n\nFill out:\n\n```markdown\n# Source Media Notes\n\n- source path or URL:\n- local video path:\n- sha256 path:\n- ffprobe path:\n- original duration:\n- original timestamps preserved? yes/no\n```\n\n## Exercise 4: Write The Gemini Prompt\n\nRun:\n\n```bash\ncat > \"$RUN_DIR/chunks/01/gemini-prompt.md\" <<'EOF'\nAnalyze this video as prompt material for a software project.\n\nReturn:\n\n1. short summary\n2. timestamped workflow\n3. transcript evidence\n4. chat evidence\n5. visual evidence\n6. inferences, clearly labeled\n7. likely downstream artifacts\n8. omissions or uncertainty\n\nRules:\n\n- Do not invent URLs, tools, commands, files, UI labels, or speakers.\n- Preserve original timestamps.\n- Separate visible facts from spoken claims and inferences.\n- Include the exact sentinel below as the last line.\n\nEND_OF_VIDEO_ANALYSIS\nEOF\n\nprintf 'END_OF_VIDEO_ANALYSIS\\n' \\\n  > \"$RUN_DIR/chunks/01/expected-sentinel.txt\"\n\nrg -n \"END_OF_VIDEO_ANALYSIS\" \"$RUN_DIR/chunks/01/gemini-prompt.md\"\n```\n\nFill out:\n\n```markdown\n# Gemini Prompt Notes\n\n- prompt path:\n- sentinel:\n- required lanes:\n- forbidden inventions:\n- timestamp rule:\n- uncertainty rule:\n```\n\n## Exercise 5: Check Oracle Call Shape\n\nWrite the call shape with an absolute video path.\n\n```js\nmcp__oracle__consult({\n  prompt: \"[exercise-video-analysis]\\n\\n{contents of chunks/01/gemini-prompt.md}\",\n  files: [\"/absolute/path/to/runs/<run-id>/chunks/01/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",\n  browserAttachments: \"always\",\n  slug: \"exercise-video-analysis\"\n})\n```\n\nFill out:\n\n```markdown\n# Oracle Video Call Shape\n\n- engine:\n- model:\n- browserAttachments:\n- file path absolute? yes/no\n- slug:\n- why API mode is wrong:\n```\n\n## Exercise 6: Separate Evidence Lanes\n\nUse a video analysis result or a short mock result. Fill the lanes separately.\n\n```markdown\n# Evidence Lanes\n\n## Transcript Evidence\n\n- timestamp:\n- quote or paraphrase:\n\n## Chat Evidence\n\n- timestamp:\n- message:\n\n## Visual Evidence\n\n- timestamp:\n- visible fact:\n- keyframe:\n\n## Inference\n\n- inference:\n- based on:\n- confidence:\n- what would confirm it:\n```\n\nQuestion:\n\n```text\nWhich claims are visible facts, and which are only spoken claims or inferences?\n```\n\n## Exercise 7: Verify The Analysis\n\nRun checks against the saved files.\n\n```bash\ntest -s \"$RUN_DIR/inputs/source-video.sha256\" && echo \"source-hash:OK\"\ntest -s \"$RUN_DIR/receipts/ffprobe.source.json\" && echo \"ffprobe:OK\"\ntest -s \"$RUN_DIR/chunks/01/gemini-prompt.md\" && echo \"prompt:OK\"\ntest -s \"$RUN_DIR/chunks/01/expected-sentinel.txt\" && echo \"sentinel-file:OK\"\n```\n\nIf Oracle output exists:\n\n```bash\nrg -n \"END_OF_VIDEO_ANALYSIS\" ~/.oracle/sessions/<slug>/output.log\n```\n\nFill out:\n\n```markdown\n# Analysis Verification\n\n- source hash exists? yes/no\n- ffprobe exists? yes/no\n- prompt exists? yes/no\n- sentinel required? yes/no\n- sentinel found in output? yes/no\n- timestamps preserved? yes/no\n- unsupported URLs/tools/commands removed? yes/no\n- visual claims have keyframes? yes/no\n```\n\n## Exercise 8: Extract Keyframes\n\nRun:\n\n```bash\nmkdir -p \"$RUN_DIR/keyframes\"\nffmpeg -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -vf \"fps=1/10\" \\\n  \"$RUN_DIR/keyframes/frame-%04d.jpg\"\nfind \"$RUN_DIR/keyframes\" -type f | head\n```\n\nOptional contact sheet:\n\n```bash\nffmpeg -pattern_type glob -i \"$RUN_DIR/keyframes/*.jpg\" \\\n  -vf \"scale=320:-1,tile=4x4\" \\\n  \"$RUN_DIR/contact-sheets/source-contact-sheet.jpg\"\n```\n\nFill out:\n\n```markdown\n# Keyframe Notes\n\n- keyframe folder:\n- contact sheet:\n- visual claim checked:\n- timestamp:\n- confirmed? yes/no\n```\n\n## Exercise 9: Write An Omissions Pass Prompt\n\nRun:\n\n```bash\ncat > \"$RUN_DIR/analysis/omissions-prompt.md\" <<'EOF'\nReview the prior video analysis for omissions.\n\nFocus only on missing visible UI states, skipped timestamps, unsupported claims,\ninvented details, and uncertainty. Do not rewrite the whole analysis. Return a\npatch-style list of corrections and end with END_OF_VIDEO_ANALYSIS.\nEOF\n```\n\nFill out:\n\n```markdown\n# Omissions Pass\n\n- why an omissions pass is needed:\n- missing visual state:\n- missing timestamp:\n- unsupported claim:\n- uncertainty:\n- expected correction:\n```\n\n## Exercise 10: Create A Bug Repro Prompt\n\nWrite:\n\n```markdown\n# Implementation Prompt From Video\n\n## Source\n\n- video:\n- source hash:\n- ffprobe:\n- analysis:\n- keyframes:\n\n## Observed Failure\n\n- timestamp:\n- visual evidence:\n- transcript/chat evidence:\n- expected behavior:\n- actual behavior:\n\n## Request\n\nImplement the smallest safe fix.\n\n## Constraints\n\n- do not change:\n- preserve:\n\n## Verification\n\n- command:\n- what passing means:\n```\n\nConfirm:\n\n```bash\ntest -s \"$RUN_DIR/final/implementation-prompt.md\" && echo \"implementation-prompt:OK\"\n```\n\n## Exercise 11: Convert Video Evidence Into A Section 6 Matrix\n\nPick one variable from the video-derived work.\n\n```markdown\n# Video-Derived Variation Matrix\n\n## Goal\n\n## Evidence From Video\n\n- timestamp:\n- observation:\n- keyframe:\n- why it matters:\n\n## Invariants\n\n- same repo state:\n- same source evidence:\n- same target flow:\n- same verification command:\n- same review criteria:\n\n## Variable Under Test\n\n- variable:\n- why this variable matters:\n- what is out of scope:\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command |\n| --- | --- | --- | --- |\n| v1 | | | |\n| v2 | | | |\n| v3 | | | |\n```\n\n## Exercise 12: Section 8 Bridge\n\nWrite a marker that carries the evidence discipline forward.\n\n```bash\nmkdir -p \"$RUN_DIR/final\"\ncat > \"$RUN_DIR/final/section8-bridge-agent-marker.md\" <<'EOF'\n# Agent Marker Bridge\n\n- previous section: Section 7\n- evidence type: video prompt material\n- source hash:\n- ffprobe:\n- analysis:\n- output.log:\n- sentinel:\n- visual evidence:\n- uncertainty:\n- next marker:\n- Section 8 target: Debugging with Agent Markers\nEOF\n\ntest -s \"$RUN_DIR/final/section8-bridge-agent-marker.md\" \\\n  && echo \"agent-marker-bridge:OK\"\n```\n\nFill out:\n\n```markdown\n# Section 8 Bridge Notes\n\n- what evidence was preserved:\n- what uncertainty remains:\n- what marker should the debugging agent leave next:\n- what would be lost without the marker:\n```\n\n## Final Check\n\nRun:\n\n```bash\ntest -s \"$RUN_DIR/inputs/source-video.sha256\" && echo \"sha256:OK\"\ntest -s \"$RUN_DIR/receipts/ffprobe.source.json\" && echo \"ffprobe:OK\"\ntest -s \"$RUN_DIR/chunks/01/gemini-prompt.md\" && echo \"prompt:OK\"\ntest -s \"$RUN_DIR/chunks/01/expected-sentinel.txt\" && echo \"sentinel:OK\"\nfind \"$RUN_DIR/final\" -type f | sort\n```\n\nFill out:\n\n```markdown\n# Final Video Prompt Run Check\n\n- source preserved? yes/no\n- source hash saved? yes/no\n- ffprobe saved? yes/no\n- original timestamps preserved? yes/no\n- prompt saved? yes/no\n- Oracle call shape correct? yes/no\n- output.log checked? yes/no\n- sentinel verified? yes/no\n- evidence lanes separated? yes/no\n- keyframes/contact sheet saved? yes/no\n- unsupported claims removed? yes/no\n- omissions pass considered? yes/no\n- downstream artifact saved? yes/no\n- ready to use as prompt material? yes/no\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-design-md-playbook",
      "slug": "design-md-playbook",
      "title": "A reusable design.md standard playbook",
      "summary": "Web developers already ship UI inside real repos, so a design.md gives their AI agent a concrete visual contract instead of vague taste prompts. It keeps design direction reusable while still forcing implementation decisions to come from the current codebase.",
      "category": "Planning",
      "tags": [
        "design.md",
        "source of truth",
        "variants",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#design-md",
        "scenarios/design-md.json#audienceFit",
        "toolkit/prompts/04-generate-design-md-standard.md",
        "toolkit/codex-skills/design-md-standard/SKILL.md",
        "scenarios/design-md.json#scenarios/0",
        "scenarios/design-md.json#scenarios/1",
        "scenarios/design-md.json#scenarios/2",
        "scenarios/design-md.json#implementationNotes",
        "scenarios/design-md.json#notTaughtOrAvoid/1",
        "scenarios/design-md.json#notTaughtOrAvoid/2",
        "scenarios/design-md.json#notTaughtOrAvoid/3",
        "scenarios/design-md.json#notTaughtOrAvoid/4",
        "scenarios/design-md.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "planning",
      "wordCount": 2533,
      "url": "/topics/foundations-design-md-playbook/",
      "markdownUrl": "/markdown/foundations-design-md-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-design-md-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "rescue-a-drifting-saas-dashboard-redesign",
          "text": "Rescue a drifting SaaS dashboard redesign",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "pick-a-landing-page-direction-with-disposable-route-variants",
          "text": "Pick a landing page direction with disposable route variants",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "standardize-ai-ui-work-for-an-existing-component-library",
          "text": "Standardize AI UI work for an existing component library",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "validated-lesson-04-references",
          "text": "Validated lesson 04 references",
          "level": 3
        },
        {
          "id": "design-md-standard-prompt",
          "text": "Design.md standard prompt",
          "level": 3
        },
        {
          "id": "design-md-codex-skill",
          "text": "Design.md Codex skill",
          "level": 3
        },
        {
          "id": "throwaway-route-variants-skill-bundle",
          "text": "Throwaway route variants skill bundle",
          "level": 3
        },
        {
          "id": "inspiration-board",
          "text": "Inspiration Board",
          "level": 3
        },
        {
          "id": "cmux-cli-reference",
          "text": "CMUX CLI reference",
          "level": 3
        }
      ],
      "markdown": "# A reusable design.md standard playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already ship UI inside real repos, so a design.md gives their AI agent a concrete visual contract instead of vague taste prompts. It keeps design direction reusable while still forcing implementation decisions to come from the current codebase.\n\n[Core principles](/topics/foundations-source-truth-and-design/)\n\n## Copy-paste workflow\n\n**When to use:** When you want AI design work to follow a durable standard instead of one-off vibes. This turns visual inspiration into a `design.md` design contract (style DNA, color, type, layout, motion) that the agent reuses on every UI task.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. Author a durable design contract at design.md, then build UI FROM it. The goal is to turn taste into a concrete, reusable artifact — not stale memory. Code stays the source of truth; design.md is a stable design brief.\n\n1. First, gather visual inspiration: collect the generated inspiration images I provide (or generate a sheet of options) and note what I actually picked.\n\n2. Distill those references into design.md with these sections, each concrete and specific:\n     - references (the images/directions I chose)\n     - style DNA (the overall feel in a few words)\n     - color (palette + usage rules)\n     - typography (families, scale, weights)\n     - layout (grid, spacing, density)\n     - composition\n     - shape (radii, borders, elevation)\n     - motion (timing, easing, where motion is/ isn't used)\n     - constraints (hard rules the UI must respect)\n\n3. Now build the UI FROM design.md (e.g. a landing page <PAGE/COMPONENT>), referencing the contract for every visual decision so the result reflects the standard, not ad-hoc choices.\n\n4. To explore directions, pair this with the throwaway multi-route variant move: generate a few variants, compare, keep one, delete the rest.\n```\n\n### How it works\n- The workflow is: collect generated inspiration images first, then distill them into `design.md`, then have the agent build UI FROM `design.md` so taste becomes a concrete artifact.\n- The `design.md` sections (references, style DNA, color, typography, layout, composition, shape, motion, constraints) form a stable design contract the agent reuses.\n- Code is the source of truth; `design.md` is a stable design brief, not stale memory to drift from.\n- Pair it with the throwaway multi-route variant move (generate, compare, keep one) to explore directions cheaply.\n- Reference: [Inspiration Board](https://inspiration-board.pages.dev/), [Codex CLI](https://github.com/openai/codex).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/design-md-standard/SKILL.md`, then restart Codex.\n\n```markdown\n---\nname: design-md-standard\ndescription: Trigger when starting UI/design work that should follow a durable standard rather than one-off prompts — author or update a design.md design contract, then build UI from it. Do NOT use as stale long-term project memory.\n---\n\n# design.md standard\n\nCreate or maintain a durable `design.md` design contract, then build UI FROM it so taste becomes a concrete, reusable artifact. Code stays the source of truth; `design.md` is a stable brief, not memory to drift.\n\n## Steps\n\n1. Gather visual inspiration first: collect the generated inspiration images the user provides (or generate a sheet of options) and note which direction was actually picked.\n\n2. Distill the references into `design.md` with these sections, each concrete and specific:\n   - **references** — the chosen images/directions\n   - **style DNA** — the overall feel in a few words\n   - **color** — palette + usage rules\n   - **typography** — families, scale, weights\n   - **layout** — grid, spacing, density\n   - **composition**\n   - **shape** — radii, borders, elevation\n   - **motion** — timing, easing, where motion is / isn't used\n   - **constraints** — hard rules the UI must respect\n\n3. Build the UI FROM `design.md`, referencing the contract for every visual decision (color, type, spacing, motion) so the result reflects the standard, not ad-hoc choices.\n\n## Guardrails\n- Treat code as the source of truth; `design.md` is a stable design brief, NOT stale long-term memory.\n- Pair with the throwaway route-variants move (generate, compare, keep one) when exploring directions.\n```\n\n## Scenarios\n\n### Rescue a drifting SaaS dashboard redesign\n\n**Role:** As a frontend lead maintaining a Next.js SaaS dashboard\n\nA Next.js app has accumulated one-off AI-generated cards, empty states, tables, and settings screens. The current dashboard works, but every new agent pass makes the UI feel less coherent because there is no shared design contract.\n\n> As a frontend lead, I want the agent to inspect the current dashboard code, author a design.md from selected generated inspiration, and refactor one screen from that contract, so that future UI work follows the same visual standard instead of adding more drift.\n\n#### Agent brief\n\n```text\nYou are my coding agent in this repo. Treat the current code as the source of truth. First inspect the existing app structure, routes, shared components, styling setup, and one representative dashboard screen. Do not rely on stale memory. Then create or update design.md with these sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Use only the generated inspiration references I provide or the selected direction I name; do not scrape or clone live websites. After design.md exists, refactor exactly one dashboard route or component to follow it. Run the repo's normal lint/typecheck/test command if available, start the local dev server, and verify the edited screen in a browser. Expected output: design.md, a small focused diff to the selected screen/components, terminal test output, and a short note explaining which design.md rules drove the visual decisions.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](https://inspiration-board.pages.dev/)\n\n```text\nlocal commands: inspect package.json, then run the repo's existing lint/typecheck/test and dev-server scripts\n```\n\n#### Browser verification\n\nUse the running local app, ideally in a CMUX browser pane or an agent-browser style flow. Open the edited dashboard route, take an accessibility snapshot, verify the main landmarks/headings/buttons are still present, click through at least one existing interactive control, and capture a screenshot or browser note showing the screen follows design.md. If using Playwright, script the same route load and one interaction rather than relying on visual claims only.\n\n#### Definition of done\n\n- design.md exists and includes references, style DNA, color, typography, layout, composition, shape, motion, and constraints\n- the changed dashboard screen visibly follows design.md and does not introduce unrelated route or architecture changes\n- lint/typecheck/test or the closest repo-local verification command has been run and logged\n- browser proof includes the local URL, the edited route, an accessibility snapshot or equivalent DOM evidence, and a screenshot or concise visual review note\n\n#### Failure modes and mitigations\n\n- The agent writes a generic design.md without inspecting the repo first; mitigate by requiring a short source-of-truth evidence section listing the files/components/routes it inspected before editing\n- The agent treats design.md like permanent stale memory and overrides current implementation constraints; mitigate by stating that code remains the source of truth and design.md is only the visual brief\n- The agent makes broad design-system rewrites; mitigate by limiting implementation to one route or one component family and requiring a small focused diff\n\n### Pick a landing page direction with disposable route variants\n\n**Role:** As an indie product developer launching a marketing page\n\nA new product landing page needs a strong visual direction, but the developer does not want to set up Storybook or maintain a gallery of experiments. The app already has a local dev server and route-based pages.\n\n> As an indie product developer, I want the agent to turn selected generated inspiration into design.md, generate several temporary landing-page route variants, let me compare them in the browser, and delete the losers, so that I can choose a direction quickly without creating maintenance baggage.\n\n#### Agent brief\n\n```text\nYou are my coding agent. Use the current app code as the source of truth for routing, styling, and component conventions. First create design.md from my selected generated inspiration with the required sections: references, style DNA, color, typography, layout, composition, shape, motion, and constraints. Then generate 3 to 5 temporary route-level variants of the same landing page inside the running app. Add simple left/right navigation between variants if it fits the app, such as links or arrow-key handling. Do not create a permanent Storybook-style catalog. Start the dev server, open the variants in the browser, and produce a comparison note that names the strongest variant and why. After I choose a winner, promote that implementation to the real landing route and delete the rejected temporary routes. Expected output: design.md, temporary variants only during review, a promoted final route, deleted losers, and browser proof from the local app.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](https://inspiration-board.pages.dev/)\n\n```text\nlocal commands: run the repo's dev server and verify the temporary variant routes in browser\n```\n\n#### Browser verification\n\nUse a local browser session to compare each temporary route in the real app. In CMUX, keep the dev server visible and open a browser pane on the variant index or first variant. Use browser snapshot/click/evaluate actions to move through left/right navigation, confirm each variant renders, and record the winning route. A screenshot grid or one screenshot per variant is useful proof here.\n\n#### Definition of done\n\n- design.md is created before variants and each variant visibly follows the same contract\n- 3 to 5 temporary route-level variants render in the local app with simple navigation or clear links between them\n- a comparison note identifies the winning variant using concrete design.md criteria\n- the final route is promoted and rejected temporary routes are deleted\n- browser proof shows the variants were reviewed in the running app, not just inferred from source\n\n#### Failure modes and mitigations\n\n- The agent keeps all variants and leaves a maintenance mess; mitigate by making deletion of rejected routes part of the definition of done\n- The agent builds variants before writing design.md, causing random styles; mitigate by requiring design.md first and asking each variant to cite which contract rules it uses\n- The browser review only checks the happy screenshot and misses broken navigation; mitigate by requiring click or keyboard navigation through every variant\n\n### Standardize AI UI work for an existing component library\n\n**Role:** As a design-minded full-stack developer maintaining a shared React component set\n\nA repo has reusable components but no durable visual language. Agents keep adding new button, card, modal, and form styles that technically compile but do not feel like one product.\n\n> As a full-stack developer, I want the agent to extract stable visual rules from current components and selected generated inspiration into design.md, then update one component example page from that contract, so that future AI-assisted UI work has a practical standard to follow.\n\n#### Agent brief\n\n```text\nYou are my coding agent. First inspect the current component files, styling conventions, route examples, and package scripts. Summarize the source-of-truth evidence before writing anything. Then create or update design.md as a design contract with references, style DNA, color, typography, layout, composition, shape, motion, and constraints. The contract should preserve stable conventions already present in the code unless they conflict with the chosen generated inspiration direction. Next update exactly one example/demo route or one small component cluster, such as Button/Card/Form, to follow design.md. Run the repo's available lint/typecheck/test command and start the local dev server. Expected output: design.md, one focused component/example diff, verification logs, and a browser review of the demo route.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n```text\ncmux markdown open design.md --direction right --focus false\n```\n\n```text\nlocal commands: inspect package.json, run existing lint/typecheck/test, run the dev server\n```\n\n#### Browser verification\n\nOpen design.md in a live CMUX Markdown pane while the dev server and browser are visible. In the browser, open the component example/demo route, use an accessibility snapshot to confirm labels and roles survived the visual pass, then click/fill one interactive component such as a button, input, select, or modal trigger. Browser proof matters because component styling can compile while still breaking focus states, labels, or layout.\n\n#### Definition of done\n\n- the agent records which current component files and routes were inspected before writing design.md\n- design.md captures both selected inspiration and existing repo constraints without becoming a stale architecture memory file\n- one demo route or component cluster is updated from the contract with a focused diff\n- lint/typecheck/test or closest available verification command passes or has a documented failure with exact output\n- browser proof includes a rendered demo route plus at least one accessibility or interaction check\n\n#### Failure modes and mitigations\n\n- The agent invents a design system from scratch and ignores existing components; mitigate by requiring source-of-truth evidence from current component files before design.md\n- The agent edits too many components at once; mitigate by limiting the first pass to one component cluster or one demo route\n- The agent verifies only with tests and skips browser behavior; mitigate by requiring a browser snapshot plus one click/fill interaction on the changed example\n\n## Implementation notes\n\n- Require the agent to inspect current repo files before writing or applying design.md; implementation details come from live code, not memory.\n- Keep design.md human-readable and stable: it should describe visual decisions, not duplicate fast-changing component internals.\n- Browser verification is part of the web-dev workflow here. A compile pass is not enough when the task changes layout, interaction, focus, or responsive behavior.\n- When exploring visual direction, prefer temporary route/page variants inside the app and delete rejected variants after selection.\n- Use generated inspiration as direction-setting material. Do not ask the agent to scrape or clone live websites.\n- Keep the first implementation slice small: one route, one page, or one component cluster. A design standard gets trusted by proving it on a narrow diff first.\n\n## Boundaries and caveats\n\n- Do not reintroduce AGENTS.md, Codex Sandbox approvals, Beads, Chrome DevTools MCP, Deep Wiki Map, Impeccable implementation steps, or YOLO-style approval bypassing for this topic.\n- Do not present million-token snapshots as a proven design.md workflow; this workflow treated that as an unproven possible direction.\n- Do not build a permanent Storybook-style catalog unless the project already requires one; the taught move is disposable route variants.\n- Do not treat design.md as an auto-updated memory system that must change on every commit.\n\n## Agent reference map\n\n### Validated lesson 04 references\n\nUse this as the ground truth for taught concepts: code as source of truth, lightweight Markdown memory, generated inspiration, design.md, and throwaway route variants.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Design.md standard prompt\n\nUse this as the copy-paste implementation prompt shape for authoring design.md and building UI from it.\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n### Design.md Codex skill\n\nUse this when packaging the workflow for Codex so the agent knows when to create or maintain design.md and when not to treat it as stale memory.\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n### Throwaway route variants skill bundle\n\nUse this for the anti-Storybook move: generate route-level variants, compare in the app, keep one, and delete the rest.\n\n[Open reference](/topics/foundations-design-md-playbook/)\n\n### Inspiration Board\n\nUse this when the human needs generated visual references before asking the agent to write design.md.\n\n[Open reference](https://inspiration-board.pages.dev/)\n\n### CMUX CLI reference\n\nUse this only for taught local workflow support such as opening a live Markdown design.md pane or inspecting panes while the dev server/browser run.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)"
    },
    {
      "id": "factory-bounded-prompts",
      "slug": "bounded-prompts",
      "title": "Bounded prompts for factory work",
      "summary": "Six complete exercises with explicit input, expected output, and success evidence, plus the read-only audit setup.",
      "category": "Planning",
      "tags": [
        "prompts",
        "contracts",
        "audit"
      ],
      "sources": [
        {
          "label": "Factory prompt library",
          "url": "https://proud-anchor-53zn.here.now/prompts.html"
        }
      ],
      "sourceUnits": [
        "prompts.html#TL;DR",
        "prompts.html#Quick start",
        "prompts.html#Prompt library",
        "prompts.html#Set up the boundary audit",
        "prompts.html#Use the smallest prompt that can change the result"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 1327,
      "url": "/topics/factory-bounded-prompts/",
      "markdownUrl": "/markdown/factory-bounded-prompts.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-bounded-prompts.json",
      "headings": [
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "audit-one-factory-boundary",
          "text": "Audit one factory boundary",
          "level": 3
        },
        {
          "id": "compose-the-smallest-useful-evidence-packet",
          "text": "Compose the smallest useful evidence packet",
          "level": 3
        },
        {
          "id": "generate-structural-variations",
          "text": "Generate structural variations",
          "level": 3
        },
        {
          "id": "recover-a-trustworthy-handoff",
          "text": "Recover a trustworthy handoff",
          "level": 3
        },
        {
          "id": "prepare-a-maximum-intelligence-consult",
          "text": "Prepare a maximum-intelligence consult",
          "level": 3
        },
        {
          "id": "earn-the-right-to-automate",
          "text": "Earn the right to automate",
          "level": 3
        },
        {
          "id": "set-up-the-boundary-audit",
          "text": "Set up the boundary audit",
          "level": 2
        },
        {
          "id": "use-the-smallest-prompt-that-can-change-the-result",
          "text": "Use the smallest prompt that can change the result",
          "level": 2
        }
      ],
      "markdown": "# Bounded prompts for factory work\n\nSix complete exercises with explicit input, expected output, and success evidence, plus the read-only audit setup.\n\n## TL;DR\n\n- **Every prompt declares** its input, expected result, and success check.\n- **Copying is preparation;** attempting and verifying are separate progress stages.\n- **Your agent can install** the complete audit from agent.md.\n\nPaste this into your agent:\n\n``` text\nFetch https://proud-anchor-53zn.here.now/agent.md and follow it to install the factory-loop audit in my current project. Run the success check and show me the result.\n```\n\n## Quick start\n\nOrient yourself in the current repository before choosing a prompt.\n\n``` text\nROOT=\"$(git rev-parse --show-toplevel)\"\ncd \"$ROOT\"\nprintf 'Repository: %s\\n' \"$ROOT\"\ngit status --short\ngit diff --stat\nfind . -maxdepth 2 -type f \\( -name AGENTS.md -o -name README.md -o -name package.json -o -name pyproject.toml -o -name Cargo.toml \\) -print | sort\n```\n\n## Prompt library\n\n### Audit one factory boundary\n\n- Agent: Repository-capable coding agent\n- Working directory: Project root\n- Inputs: One recurring task and the current repository\n- Expected result: A seven-part boundary map with one human gate\n\n**Success:** All claims are Observed, Inferred, or Proposed; the tree is unchanged.\n\n``` text\nYou are auditing one recurring software task as a bounded factory loop. Work read-only until I explicitly approve a change.\n\nFirst inspect the current repository and ask me to name the recurring task if it is not already clear. Then return these seven sections:\n\n1. Task contract — input, desired outcome, and what is outside scope.\n2. Required context — the minimum current evidence needed before acting.\n3. Boundary map — repository rule, launch rule, command rule, human gate, and automated check.\n4. Risk gate — the first expensive, destructive, public, or hard-to-reverse action that must stop for approval.\n5. Success evidence — one exact command or observable signal that can prove the task worked.\n6. Receipt — what the next session needs to reproduce the result and understand the decision.\n7. Smallest reversible delta — the first experiment that tests this loop without production mutation.\n\nLabel every statement Observed, Inferred, or Proposed. Do not install tools, use credentials, mutate data, publish, or edit files. If evidence is missing, stop and name the missing evidence instead of guessing.\n```\n\n### Compose the smallest useful evidence packet\n\n- Agent: Coding agent\n- Working directory: Project root\n- Inputs: Task, relevant files, fresh command output, optional annotated image\n- Expected result: A source list, omissions, and one verification plan\n\n**Success:** Every included source changes the decision, action, or verification.\n\n``` text\nPrepare the smallest evidence packet for this task before proposing a solution. Separate: task, constraints, current implementation, fresh runtime evidence, visual evidence, and success check. For each source, say which decision it can change. Identify stale, duplicated, contradictory, or irrelevant material and exclude it. End with the exact evidence still missing. Do not implement yet.\n```\n\n### Generate structural variations\n\n- Agent: Design-capable coding agent\n- Working directory: Project root; write only to a scratch route or directory\n- Inputs: Stable content, product goal, design constraints\n- Expected result: Four meaningfully different mockups and a comparison index\n\n**Success:** Options differ in structure, not only color or type.\n\n``` text\nCreate four dependency-free design variations without editing production files. Hold the content and product goal constant. Vary information architecture, hierarchy, density, navigation, and interaction emphasis. Give every option a distinct design thesis. Build a comparison index that explains what each option optimizes, what it sacrifices, and which user behavior it makes easiest. Stop before choosing a winner. Label this a Companion-authored exercise.\n```\n\n### Recover a trustworthy handoff\n\n- Agent: Coding agent with repository and history access\n- Working directory: Project root\n- Inputs: Working tree, recent commits, notes, artifacts, available session history\n- Expected result: A compact recovery memo and one next check\n\n**Success:** The memo distinguishes verified state from remembered or inferred state.\n\n``` text\nRecover this task from durable evidence. Report: current objective, current repository state, last verified result, decisions already settled, open risks, failed attempts worth preserving, next bounded action, and the exact command or observation that will prove it. Use history only to locate evidence; verify important claims against the current tree or artifacts. Do not continue implementation until the recovery memo is internally consistent.\n```\n\n### Prepare a maximum-intelligence consult\n\n- Agent: Strong independent reasoning model\n- Working directory: Project root or supplied evidence bundle\n- Inputs: One hard decision and filtered supporting evidence\n- Expected result: Alternatives, hidden assumptions, experiment, reversal plan\n\n**Success:** The recommendation is falsifiable and does not depend on missing context.\n\n``` text\nReview this decision independently. State the decision in one sentence. Identify hidden assumptions and the most costly way the current framing could be wrong. Propose at least three materially different options, including the simplest viable option. For each, give evidence, tradeoffs, reversibility, and failure modes. Recommend the smallest discriminating experiment and define the result that would change your recommendation. Finish with a reversal plan.\n```\n\n### Earn the right to automate\n\n- Agent: Coding agent and human owner\n- Working directory: Project root\n- Inputs: VISION.md or product evidence plus one recurring review\n- Expected result: Manual → script → agent → CI → blocking-gate promotion plan\n\n**Success:** Every promotion has an owner, evidence threshold, cost boundary, and recovery path.\n\n``` text\nMap this recurring review onto an automation ladder: manual run, deterministic script, bounded agent, non-blocking CI report, blocking gate, schedule, or human approval. Keep it at the lowest stage that is currently justified. For each possible promotion, specify the evidence threshold, false-positive tolerance, latency and cost budget, owner, stop condition, and recovery path. Run nothing and schedule nothing. End with the next five manual receipts we should collect.\n```\n\n## Set up the boundary audit\n\nThese steps mirror [agent.md](https://proud-anchor-53zn.here.now/agent.md).\n\n1.  Confirm Git and preserve the working tree.\n\n2.  Create the complete prompt:\n\n    ``` text\n    # Factory Loop Boundary Audit\n\n    Use this prompt before automating or expanding a recurring software task.\n\n    ## Instructions\n\n    You are auditing one recurring software task as a bounded factory loop. Work read-only until I explicitly approve a change.\n\n    First inspect the current repository and ask me to name the recurring task if it is not already clear. Then return these seven sections:\n\n    1. Task contract — input, desired outcome, and what is outside scope.\n    2. Required context — the minimum current evidence needed before acting.\n    3. Boundary map — repository rule, launch rule, command rule, human gate, and automated check.\n    4. Risk gate — the first expensive, destructive, public, or hard-to-reverse action that must stop for approval.\n    5. Success evidence — one exact command or observable signal that can prove the task worked.\n    6. Receipt — what the next session needs to reproduce the result and understand the decision.\n    7. Smallest reversible delta — the first experiment that tests this loop without production mutation.\n\n    Label every statement Observed, Inferred, or Proposed. Do not install tools, use credentials, mutate data, publish, or edit files. If evidence is missing, stop and name the missing evidence instead of guessing.\n\n    ## Success contract\n\n    - The output contains all seven named sections.\n    - Every statement is labeled Observed, Inferred, or Proposed.\n    - One explicit human gate and one exact verification signal are named.\n    - The audit makes no repository changes.\n    ```\n\n3.  Run the structural check:\n\n    ``` text\n    mkdir -p .agents/prompts\n    test -s .agents/prompts/factory-loop-audit.md\n    grep -q '^## Success contract' .agents/prompts/factory-loop-audit.md\n    printf 'factory loop prompt installed\\n'\n    ```\n\n**Success check:** the installed audit returns seven labeled sections, one human gate, one exact verification signal, and changes no pre-existing file.\n\n``` text\nfactory loop prompt installed\n```\n\n## Use the smallest prompt that can change the result\n\nBefore: name the boundary. Prompt: include only decisive evidence. Success evidence: run one exact check. Reflect: record what changed your decision. Continue: return to the related lesson.\n\nThe prompts are companion-authored exercises grounded in the recorded operating patterns. They are not presented as verbatim workshop quotations."
    },
    {
      "id": "codex-workflow-selection",
      "slug": "workflow-selection",
      "title": "Choose the next agent workflow",
      "summary": "Provides a bottleneck-driven agent prompt and an eleven-step workflow connecting context, shell visibility, routing, composition, verified variations, evidence, delegation, council critique, and human selection.",
      "category": "Planning",
      "tags": [
        "workflow",
        "bottlenecks",
        "decisions"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Phase Map",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Phase Map/Phase 1: Context And Environment",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Phase Map/Phase 2: Routing And Composition",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Phase Map/Phase 3: Generation And Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Phase Map/Phase 4: Delegation And Review",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/Section Map",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/00-index.md#00. Workshop Workflow Index/How To Use The Set",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 804,
      "url": "/topics/codex-workflow-selection/",
      "markdownUrl": "/markdown/codex-workflow-selection.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-workflow-selection.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "phase-map",
          "text": "Phase Map",
          "level": 2
        },
        {
          "id": "phase-1-context-and-environment",
          "text": "Phase 1: Context And Environment",
          "level": 3
        },
        {
          "id": "phase-2-routing-and-composition",
          "text": "Phase 2: Routing And Composition",
          "level": 3
        },
        {
          "id": "phase-3-generation-and-evidence",
          "text": "Phase 3: Generation And Evidence",
          "level": 3
        },
        {
          "id": "phase-4-delegation-and-review",
          "text": "Phase 4: Delegation And Review",
          "level": 3
        },
        {
          "id": "section-map",
          "text": "Section Map",
          "level": 2
        },
        {
          "id": "how-to-use-the-set",
          "text": "How To Use The Set",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Choose the next agent workflow\n\nUse this as the map for the full workflow. Each section stands alone, but the sequence is deliberate.\n\n## Agent Setup Prompt\n\n```text\nUse this workflow index to choose the next agent move for a software project.\n\nFirst identify the current bottleneck:\n- missing context\n- missing shell tools\n- unclear helper behavior\n- wrong workspace or session\n- weak prompt shape\n- too many plausible implementations\n- video or runtime evidence to analyze\n- bounded debug packet to preserve\n- narrow task to delegate\n- risky decision that needs independent model critique\n- generated options that need a human pick\n\nThen pick the matching section and ask the agent to follow that workflow. Keep the request concrete: name the repo, the bug or decision, the files or logs to inspect, and the proof you expect before the work is considered done.\n```\n\n## Phase Map\n\n### Phase 1: Context And Environment\n\nMake invisible project context and agent shell context explicit before asking for work.\n\n1. Pack context when broad code reasoning needs Oracle.\n2. Make the shell and tools visible to Codex.\n3. Classify zsh helper names and fallback boundaries.\n\nTransition: Once the agent can see the right context and tool surface, route the work to the right place before launch.\n\n### Phase 2: Routing And Composition\n\nPut work in the right workspace, pane, session, and prompt shape before it runs.\n\n4. Route the right pane/session.\n5. Compose before launch.\n\nTransition: Once launch is deliberate, use the agent surface to produce, compare, and preserve evidence.\n\n### Phase 3: Generation And Evidence\n\nGenerate useful options and turn rich runtime or media evidence into prompt material.\n\n6. Generate verified variations.\n7. Use video as prompt material.\n8. Mark debug moments with bounded evidence.\n\nTransition: Once the work is bounded and evidenced, delegate narrow packets or ask for independent review.\n\n### Phase 4: Delegation And Review\n\nHand small tool-shaped work to narrow agents, use councils for expensive decisions, and capture human choices before implementation.\n\n9. Hand tool-shaped packets to narrow Imps.\n10. Ask a model council when independent disagreement improves a risky decision.\n11. Capture a phone-friendly human selection from generated options and resume from saved JSON.\n\n## Section Map\n\n| Phase | Section | Workflow Move | File |\n| --- | --- | --- | --- |\n| Context And Environment | 1 | Pack context when broad code reasoning needs Oracle | [01-oracle-packing-context.md](/topics/codex-context-packing-reference/) |\n| Context And Environment | 2 | Make the shell and tools visible to Codex | [02-loading-zsh-env-into-codex.md](/topics/codex-shell-environment-reference/) |\n| Context And Environment | 3 | Classify zsh helper names and fallback boundaries | [03-zsh-functions-aliases.md](/topics/codex-shell-functions-reference/) |\n| Routing And Composition | 4 | Route the right pane/session | [04-agentic-dev-environment-orchestrator.md](/topics/codex-workspace-routing-reference/) |\n| Routing And Composition | 5 | Compose before launch | [05-prompt-builder.md](/topics/codex-prompt-composition-reference/) |\n| Generation And Evidence | 6 | Generate verified variations | [06-code-is-free-generate-variations.md](/topics/codex-variation-workflows-reference/) |\n| Generation And Evidence | 7 | Use video as prompt material | [07-video-as-prompts.md](/topics/codex-video-workflows-reference/) |\n| Generation And Evidence | 8 | Mark debug moments with bounded evidence | [08-debugging-with-agent-markers.md](/topics/codex-marker-workflows-reference/) |\n| Delegation And Review | 9 | Hand tool-shaped packets to narrow Imps | [09-imps.md](/topics/codex-imp-workflows-reference/) |\n| Delegation And Review | 10 | Ask a model council when independent disagreement improves a risky decision | [10-fusion-model-council.md](/topics/codex-fusion-workflows-reference/) |\n| Delegation And Review | 11 | Capture a phone-friendly human selection from generated options | [11-web-choices.md](/topics/codex-choice-workflows-reference/) |\n\n## How To Use The Set\n\nStart with the section that matches the current bottleneck:\n\n| Bottleneck | Start With |\n| --- | --- |\n| The agent needs a broad codebase answer | Section 1 |\n| A command works locally but not in Codex | Section 2 |\n| A helper name is unclear or shell-only | Section 3 |\n| Work is landing in the wrong pane or session | Section 4 |\n| The prompt needs shaping before launch | Section 5 |\n| Several implementations are plausible | Section 6 |\n| A recording contains the missing context | Section 7 |\n| Logs exist but the important moment is unclear | Section 8 |\n| The task is mostly one command-line tool | Section 9 |\n| Several strong models may disagree on a risky architecture or implementation choice | Section 10 |\n| The agent generated good options but needs a human pick or feedback before continuing | Section 11 |\n\nSection 10 is especially useful after Section 6 for comparing strategies, or after Section 9 when a bounded packet needs independent review before a risky implementation choice.\nSection 11 is especially useful after Section 6 or Section 10 when generated options need a human selection, ranking, or feedback before implementation continues.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-prompt-builder",
      "slug": "prompt-builder",
      "title": "Compose the first prompt before launch",
      "summary": "The first prompt does more than start a chat. It names the work, chooses the launch path, loads useful references, and decides whether this is a fresh thread, a fork, a compacted branch, or a wrapper handoff.",
      "category": "Planning",
      "tags": [
        "prompt-builder",
        "preflight",
        "prompts"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#prompt-builder"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-08-compose-before-the-agent-starts.md",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Start With A Name",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Compose Before Launch",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Prompt Builder For Preflight",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Hooks For Every-Turn Behavior",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Imps For Repeated Specialized Jobs",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Optional Patterns: Fork, Compact, Handoff",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Copyable Artifact: First Prompt Preflight Checklist",
        "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Verify Commands Before Use",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#prompt-builder",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 874,
      "url": "/topics/codex-prompt-builder/",
      "markdownUrl": "/markdown/codex-prompt-builder.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-prompt-builder.json",
      "headings": [
        {
          "id": "start-with-a-name",
          "text": "Start With A Name",
          "level": 2
        },
        {
          "id": "compose-before-launch",
          "text": "Compose Before Launch",
          "level": 2
        },
        {
          "id": "use-prompt-builder-for-preflight",
          "text": "Use Prompt Builder For Preflight",
          "level": 2
        },
        {
          "id": "use-hooks-for-every-turn-behavior",
          "text": "Use Hooks For Every-Turn Behavior",
          "level": 2
        },
        {
          "id": "use-imps-for-repeated-specialized-jobs",
          "text": "Use Imps For Repeated Specialized Jobs",
          "level": 2
        },
        {
          "id": "optional-patterns-fork-compact-handoff",
          "text": "Optional Patterns: Fork, Compact, Handoff",
          "level": 2
        },
        {
          "id": "copyable-artifact-first-prompt-preflight-checklist",
          "text": "Copyable Artifact: First Prompt Preflight Checklist",
          "level": 2
        },
        {
          "id": "verify-commands-before-use",
          "text": "Verify Commands Before Use",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Compose the first prompt before launch\n\nThe first prompt does more than start a chat. It names the work, chooses the launch path, loads useful references, and decides whether this is a fresh thread, a fork, a compacted branch, or a wrapper handoff.\n\nDo the deliberate setup before the agent session starts. Use **[hooks](https://developers.openai.com/codex/hooks)** for repeated interception during the session. Use **[imps](https://github.com/johnlindquist/codex-imps)** or CLI helpers for reusable specialist behavior.\n\n## Start With A Name\n\n**Unnamed sessions decay quickly.** A name gives search, resumption, review, and reporting something stable to grab.\n\n> The thing I like about this is that I can just give a conversation a name from the start. And it kind of forces me to think about what the conversation is going to be about.\n>\n> — John Lindquist\n\nGood names sound like software work:\n\n- Checkout saved payment methods\n- Billing webhook retry audit\n- Auth session rotation review\n- Settings empty-state cleanup\n\nThe name does not need to be clever. It needs to be **short, searchable, and tied to the work**.\n\n## Compose Before Launch\n\nThe core loop is:\n\n```text\nintent -> name -> prompt -> references -> preview -> submit\n```\n\n**[Prompt Builder](https://github.com/johnlindquist/prompt-builder)** is useful because it **moves composition before the full launch path**. You can shape the prompt, add the name, include the references, inspect the launch, and then hand the result to [Codex](https://developers.openai.com/codex) or a wrapper command.\n\n> Pre-flight, preload, pre-plan. Sessions before, before anything about the agents kicks in, before the system prompt kicks in, before anything.\n>\n> — John Lindquist\n\n## Use Prompt Builder For Preflight\n\nUse a preflight surface when the setup belongs to the first prompt.\n\nFeature kickoff:\n\n```text\nName:\nCheckout saved payment methods\n\nPrompt:\nInspect the checkout flow, list the files likely involved, identify the smallest safe implementation plan, and name the first verification command.\n\nDo not edit yet.\n```\n\nBug-fix preflight:\n\n```text\nName:\nBilling webhook retry bug\n\nPrompt:\nUse the failing test output and billing webhook files to identify the likely regression.\n\nReturn the smallest patch plan and the verification command before editing.\n```\n\nArchitecture review:\n\n```text\nName:\nAuth session rotation review\n\nPrompt:\nReview the auth/session architecture and find risks around token rotation, stale sessions, and logout behavior.\n\nReturn findings grouped by risk and proof needed.\n```\n\n## Use Hooks For Every-Turn Behavior\n\nPrompt Builder helps before the session starts. Hooks are a better fit when something must happen **on every prompt or at a lifecycle checkpoint**.\n\nFor voice-to-text cleanup:\n\n- Use Prompt Builder when cleanup only needs to happen before the first prompt.\n- Use a prompt-submit hook when cleanup must happen on every turn.\n- Use an imp or CLI helper when cleanup belongs to a reusable specialist command.\n\nExample boundaries:\n\n- Initial only: clean up a dictated feature kickoff, apply a glossary, attach project references, then launch.\n- Every turn: normalize dictated acronyms, product names, ticket IDs, and file names before each prompt reaches the agent.\n- Specialist job: take rough dictated text and return a launch-ready prompt without touching the repo.\n\n## Use Imps For Repeated Specialized Jobs\n\nIf the behavior becomes a reusable tool-shaped job, move it out of the first prompt.\n\nGood candidates:\n\n- prompt cleanup\n- bug triage\n- screenshot capture\n- route inspection\n- dependency audit\n- ticket drafting\n\n**The first prompt should start the work.** It should not become the permanent home for every repeated workflow.\n\n## Optional Patterns: Fork, Compact, Handoff\n\nPrompt Builder can compose first, then hand the prompt to another command. In that mode, fork and compact options are routing choices.\n\nKeep the model simple:\n\n```text\ncompose first -> fork selected session -> compact when needed -> resume with named prompt\ncompose first -> hand off to wrapper -> wrapper owns the routing\n```\n\nTreat this as advanced launch routing. The main lesson is still **preflight**: name the work, shape the request, preview the launch, and submit deliberately.\n\n## Copyable Artifact: First Prompt Preflight Checklist\n\n```text\nBefore launching the agent, fill in:\n\nName:\n[short, searchable task name]\n\nGoal:\n[what should be true when this work is done]\n\nContext:\n[files, logs, screenshots, tickets, or docs to inspect first]\n\nConstraints:\n[files to avoid, behaviors to preserve, risky areas]\n\nLaunch shape:\n[fresh thread / named thread / fork / compact fork / wrapper handoff]\n\nFirst output:\n[plan only / edit / diagnosis / test list / comparison]\n\nProof:\n[command, screenshot, trace, diff, or review artifact required]\n\nStop rule:\n[what should block completion]\n```\n\nExample:\n\n```text\nName:\nCheckout saved payment methods\n\nGoal:\nFix the saved-card selection regression without changing the payment-provider adapter.\n\nContext:\nCheckout route, saved payment method component, failing test output.\n\nConstraints:\nDo not touch provider SDK wrappers.\nDo not rewrite checkout state management.\n\nLaunch shape:\nNamed thread.\n\nFirst output:\nDiagnosis and smallest safe patch plan.\n\nProof:\nRun the checkout component test and billing smoke test.\n```\n\n## Verify Commands Before Use\n\nPrompt Builder command examples are implementation details. Before running them, verify the current binary name, install path, `--name`, dry-run, print, submit, handoff, fork, compact, and launch-option behavior against the current source and CLI help.\n\nThe pattern is stable. Command details can change.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#prompt-builder)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-variation-workflows-reference",
      "slug": "variation-workflows-reference",
      "title": "Controlled variation workflows: practical reference",
      "summary": "Controlled software-variation workflow covering setup-only agent prompts, single-variable matrices, baseline repository capture, isolation and fan-out, identical verification, diff and UI review, five decision outcomes, convergence, troubleshooting, and…",
      "category": "Planning",
      "tags": [
        "variations",
        "verification",
        "comparison"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Core Pattern",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/One Dimension Rule",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Variation Matrix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Variation Matrix/Example: Billing Webhook Duplicate Processing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Start From The Section 5 Seed",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Save Repo State Before Fan-Out",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Choose Isolation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Build Candidate Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Fan-Out",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Verify Every Candidate",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Review Surface",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Decision Outcomes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Candidates Changed Multiple Variables",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Verification Differs Per Candidate",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Repo Was Dirty Before Fan-Out",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/Best Idea Is Split Across Candidates",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/If It Goes Wrong/All Candidates Fail",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/06-code-is-free-generate-variations.md#06. Code Is Free / Generate Variations/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 3881,
      "url": "/topics/codex-variation-workflows-reference/",
      "markdownUrl": "/markdown/codex-variation-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-variation-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "core-pattern",
          "text": "Core Pattern",
          "level": 2
        },
        {
          "id": "one-dimension-rule",
          "text": "One Dimension Rule",
          "level": 2
        },
        {
          "id": "variation-matrix",
          "text": "Variation Matrix",
          "level": 2
        },
        {
          "id": "example-billing-webhook-duplicate-processing",
          "text": "Example: Billing Webhook Duplicate Processing",
          "level": 3
        },
        {
          "id": "start-from-the-section-5-seed",
          "text": "Start From The Section 5 Seed",
          "level": 2
        },
        {
          "id": "save-repo-state-before-fan-out",
          "text": "Save Repo State Before Fan-Out",
          "level": 2
        },
        {
          "id": "choose-isolation",
          "text": "Choose Isolation",
          "level": 2
        },
        {
          "id": "build-candidate-prompts",
          "text": "Build Candidate Prompts",
          "level": 2
        },
        {
          "id": "fan-out",
          "text": "Fan-Out",
          "level": 2
        },
        {
          "id": "verify-every-candidate",
          "text": "Verify Every Candidate",
          "level": 2
        },
        {
          "id": "review-surface",
          "text": "Review Surface",
          "level": 2
        },
        {
          "id": "decision-outcomes",
          "text": "Decision Outcomes",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "candidates-changed-multiple-variables",
          "text": "Candidates Changed Multiple Variables",
          "level": 3
        },
        {
          "id": "verification-differs-per-candidate",
          "text": "Verification Differs Per Candidate",
          "level": 3
        },
        {
          "id": "repo-was-dirty-before-fan-out",
          "text": "Repo Was Dirty Before Fan-Out",
          "level": 3
        },
        {
          "id": "best-idea-is-split-across-candidates",
          "text": "Best Idea Is Split Across Candidates",
          "level": 3
        },
        {
          "id": "all-candidates-fail",
          "text": "All Candidates Fail",
          "level": 3
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Controlled variation workflows: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up a controlled variation run before any candidate implementation starts. Build the files, folders, isolation lanes, verification ledger, review surfaces, and saved-decision template first, then stop and report whether setup is ready.\n\n1. Work from the repository root. Choose a short run id that names the software decision, such as `billing-webhook-$(date +%Y%m%d-%H%M%S)`, and set `ROOT=\"artifacts/variations/$RUN_ID\"`.\n\n2. Create the run structure: `prompts/`, `launch/`, `logs/`, `review/`, `decisions/`, and `candidates/v1`, `candidates/v2`, `candidates/v3` under `$ROOT`. If the variation is visual, also create `review/screenshots/`.\n\n3. Write `$ROOT/matrix.md` before launching anything. Include Goal, Invariants, Variable Under Test, Candidate Count, Candidates, and Review Criteria. The matrix must name exactly one variable. Keep repo state, base prompt, target feature or bug, constraints, verification command, and review criteria identical for every candidate. If a second dimension matters, record it as a future round.\n\n4. Save the shared base prompt to `$ROOT/prompts/base.prompt.md`. Save matching launch metadata to `$ROOT/launch/base.launch.json` using Prompt Builder when available, for example `p --print-prompt \"$PROMPT\"` and `p --print-launch-json \"$PROMPT\"`. If Prompt Builder is unavailable, still write the base prompt file and create a small valid launch JSON file that records the prompt text, run id, candidate ids, artifact root, isolation method, and verification command.\n\n5. Capture baseline repo state before fan-out: save `git status --short` to `$ROOT/review/git-status-before.txt`, `git diff` to `$ROOT/review/dirty-before.patch`, and `git diff --staged` to `$ROOT/review/staged-before.patch`. If the repo has unknown dirty state, stop and report it instead of creating candidate code lanes.\n\n6. Choose the isolation strategy and record it. For prompt, plan, or docs-only variations, use `$ROOT/candidates/v1`, `v2`, and `v3`. For parallel code edits, prefer git worktrees at `../variation-$RUN_ID/v1`, `v2`, and `v3`, each on its own branch, then save `git worktree list` to `$ROOT/review/worktrees.txt`. Each candidate must have a distinct branch, worktree, or directory.\n\n7. Create `$ROOT/prompts/v1.prompt.md`, `$ROOT/prompts/v2.prompt.md`, and `$ROOT/prompts/v3.prompt.md` from the same base prompt. Append only the candidate override: candidate id, variable name, that candidate's setting, and the instruction to change no other dimension.\n\n8. Define one verification command and save it in the matrix plus `$ROOT/review/verification-command.txt`. Create `$ROOT/review/verification.tsv` with columns for candidate id, status, and command. Do not run implementation verification yet. The command must be identical for every candidate; if a candidate needs different proof, make that a new variation round.\n\n9. Create review artifacts before generation: `$ROOT/review/comparison.md` with Goal, Variable Under Test, Verification, Diff Review, Review Criteria, and Notes sections; placeholder paths for `logs/v1.verify.log`, `logs/v2.verify.log`, `logs/v3.verify.log`; placeholder paths for `review/v1.diffstat.txt`, `review/v1.diff.patch`, and matching v2/v3 files. Leave results blank until candidates exist.\n\n10. Create `$ROOT/decisions/selection.md` with fields for outcome, primary candidate, secondary candidate ids, decision, why, rejected candidates, required follow-up, final verification command, per-candidate notes, and a continue prompt. The outcome must later be exactly one of Pick, Combine, Refine, Expand, or Reject.\n\n11. Run setup checks only: confirm the matrix, base prompt, launch JSON, candidate prompts, repo-state files, verification command file, comparison template, decision template, and isolation lanes exist. Print OK or FAIL for each check and show the run file list with `find \"$ROOT\" -maxdepth 3 -type f | sort`.\n\n12. Respect privacy boundaries. Do not copy secrets, tokens, cookies, private endpoints, full environment dumps, raw private config, or unrelated home-directory files into prompts, logs, launch JSON, matrix files, review artifacts, or decisions. Summarize sensitive configuration instead of pasting it.\n\n13. Report back with the artifact root, candidate ids, chosen isolation strategy, single variable under test, single verification command, repo-state classification, setup check results, any files you intentionally did not copy for privacy, and any blocker. Do not generate candidate implementations, run candidate verification, fill comparison results, or make a Pick/Combine/Refine/Expand/Reject decision until setup verification passes and the next step is explicitly requested.\n```\n\n## Big Idea\n\nPhase: Generation And Evidence - use the prepared surface to generate comparable options and preserve the proof that decides between them.\n\n`Code is free` does not mean quality is free.\n\n## Try This Now\n\nFinish this sentence before generating candidates:\n`We are comparing candidates that differ only by __________.`\nFor a billing webhook bug, try: `idempotency strategy`.\nWrite the same verification command before any fan-out.\n\nIt means another candidate is cheap enough that the workflow should change:\n\n```text\ndo not bet everything on the first generated answer\n```\n\nProduce candidates, verify them, compare them, converge deliberately, and save the decision.\n\nCheap:\n\n- another implementation option\n- another UI integration strategy\n- another idempotency strategy\n- another test boundary\n- another prompt framing\n- another documentation organization\n\nStill expensive:\n\n- understanding the problem\n- keeping candidates controlled\n- integrating the winner\n- running verification\n- resolving conflicts\n- preserving why the decision was made\n\nPractical rule:\n\n```text\nGenerate more because comparison improves the decision, not because you are avoiding the decision.\n```\n\n## When To Reach For This\n\nUse variations when several plausible approaches exist and comparison will make the final choice better.\n\n| Use Variations For | Example |\n| --- | --- |\n| UI integration strategy | saved payment methods in checkout: inline selector vs drawer vs review-step picker |\n| idempotency strategy | billing webhook duplicate-processing: provider event guard vs invoice lock vs processing ledger |\n| auth/session architecture | middleware-first vs session-store-first vs token-rotation boundary |\n| state management | local reducer vs server state cache vs URL-backed state |\n| test boundary | unit regression vs integration replay vs end-to-end checkout path |\n| API shape | command endpoint vs resource endpoint vs explicit workflow endpoint |\n| data loading model | route loader vs component query vs server action |\n| implementation alternatives | minimal patch vs extracted helper vs explicit state machine |\n| prompt framing | plan-first vs patch-first vs test-first |\n| documentation organization | quickstart-first vs concept-first vs task checklist |\n\nSkip variations when another candidate adds noise.\n\n| Skip Variations For | Better Move |\n| --- | --- |\n| one-line typo fix | patch it and test it |\n| obvious hotfix | apply the smallest safe change |\n| strict migration | follow the migration plan exactly |\n| exact requested implementation | build what was specified |\n| unverifiable candidates | define verification first |\n| dirty repo with no saved state | checkpoint before fan-out |\n| failing test names the exact bug | fix the bug first |\n| candidates would share unsafe state | isolate before launching |\n\nHard rule:\n\n```text\nVariation is a decision tool, not a procrastination tool.\n```\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nAsk for one implementation, inspect it, tweak it, and hope the first path was good enough.\n```\n\nWhat the workflow gives you now:\n\n```text\nStart from one deliberate prompt, generate controlled candidates, verify each\nthe same way, compare results, then save the chosen path.\n```\n\nWhat you used to expect:\n\n```text\nMore candidates automatically means better work.\n```\n\nWhat the workflow gives you now:\n\n```text\nUnverified candidates are just noise. The value comes from controlled\ndifferences, identical verification, and a saved decision.\n```\n\n## Core Pattern\n\n```text\ngoal\n-> variable\n-> matrix\n-> isolation\n-> fan-out\n-> verify\n-> review\n-> selection\n-> convergence\n-> saved decision\n```\n\nDo not skip the middle:\n\n```text\nfan-out without isolation = collisions\nfan-out without verification = noise\nfan-out without review = drift\nfan-out without saved decision = repeated debate\n```\n\n## One Dimension Rule\n\nVary exactly one dimension across candidates.\n\nFinish this sentence before launching anything:\n\n```text\nWe are comparing candidates that differ only by __________.\n```\n\nGood variables:\n\n| Variable | Good Comparison Question |\n| --- | --- |\n| UI integration strategy | Where should saved payment methods enter checkout? |\n| idempotency strategy | Which duplicate-processing guard is safest for billing webhooks? |\n| state management | Which state boundary keeps the checkout flow simplest? |\n| test boundary | Which test layer catches this regression with the least brittleness? |\n| API shape | Which endpoint shape keeps auth/session changes clear? |\n| data loading model | Where should this screen load account and payment data? |\n| prompt framing | Which prompt produces the most verifiable implementation plan? |\n| documentation organization | Which doc structure helps the next maintainer act fastest? |\n\nBad variables:\n\n| Bad Variable | Why It Fails |\n| --- | --- |\n| random ideas | no controlled comparison |\n| each one different | impossible to know what mattered |\n| explore everything | no review question |\n| make five better versions | vague and untestable |\n| let every agent decide | candidates drift apart |\n\nIf two dimensions matter, run two rounds.\n\n```text\nRound 1: compare idempotency strategy.\nRound 2: compare test boundary for the selected strategy.\n```\n\n## Variation Matrix\n\nWrite the matrix before launching candidates.\n\n```markdown\n# Variation Matrix\n\n## Goal\n\n<What software outcome are we trying to achieve?>\n\n## Invariants\n\nThese stay the same for every candidate:\n\n- same repo state:\n- same base prompt:\n- same target feature or bug:\n- same constraints:\n- same verification command:\n- same review criteria:\n\n## Variable Under Test\n\n- variable:\n- why this matters:\n- what is out of scope:\n\n## Candidate Count\n\n- count:\n- ids: v1, v2, v3\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command | Notes |\n| --- | --- | --- | --- | --- |\n| v1 | | | | |\n| v2 | | | | |\n| v3 | | | | |\n\n## Review Criteria\n\nCompare candidates on:\n\n1. passes verification\n2. preserves invariants\n3. smallest durable change\n4. easiest integration path\n5. clearest rollback path\n```\n\n### Example: Billing Webhook Duplicate Processing\n\n```markdown\n# Variation Matrix\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Invariants\n\n- Provider webhook contract stays fixed.\n- Database schema stays fixed for this round.\n- Existing invoice state transitions stay compatible.\n- Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command |\n| --- | --- | --- | --- |\n| v1 | provider event id guard | `../variation-<run-id>/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n| v2 | invoice-level processing lock | `../variation-<run-id>/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n| v3 | webhook processing ledger | `../variation-<run-id>/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` |\n\n## Review Criteria\n\nWhich strategy prevents duplicate invoice processing with the smallest durable change?\n```\n\n## Start From The Section 5 Seed\n\nUse Prompt Builder to save the base prompt and launch JSON under the variation run.\n\n```bash\nRUN_ID=\"billing-webhook-$(date +%Y%m%d-%H%M%S)\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT\"/{prompts,launch,logs,review,decisions}\nmkdir -p \"$ROOT\"/candidates/{v1,v2,v3}\n\nPROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.'\n\np --print-prompt \"$PROMPT\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \"$PROMPT\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\nSave the matrix next to the seed:\n\n```bash\ncat > \"$ROOT/matrix.md\" <<'EOF'\n# Variation Matrix\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Invariants\n\n- Provider webhook contract stays fixed.\n- Database schema stays fixed.\n- Existing invoice state transitions stay compatible.\n- Same verification command: `pnpm test billing-webhook -- --runInBand && pnpm build`.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Candidate Count\n\n- count: 3\n- ids: v1, v2, v3\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command | Notes |\n| --- | --- | --- | --- | --- |\n| v1 | provider event id guard | `../variation-<run-id>/v1` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n| v2 | invoice-level processing lock | `../variation-<run-id>/v2` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n| v3 | webhook processing ledger | `../variation-<run-id>/v3` | `pnpm test billing-webhook -- --runInBand && pnpm build` | |\n\n## Review Criteria\n\n- prevents duplicate processing\n- preserves provider contract\n- keeps rollback simple\n- passes the same verification command\nEOF\n```\n\nConfirm the setup:\n\n```bash\nfind \"$ROOT\" -maxdepth 3 -type d | sort\ntest -s \"$ROOT/matrix.md\" && echo \"matrix:OK\"\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\ntest -s \"$ROOT/launch/base.launch.json\" && echo \"launch-json:OK\"\n```\n\n## Save Repo State Before Fan-Out\n\nBefore parallel code edits, save the current state.\n\n```bash\ngit status --short | tee \"$ROOT/review/git-status-before.txt\"\ngit diff > \"$ROOT/review/dirty-before.patch\"\ngit diff --staged > \"$ROOT/review/staged-before.patch\"\n```\n\nIf the repo is dirty, choose one:\n\n| State | Safe Next Move |\n| --- | --- |\n| intentional local work | commit or stash before fan-out |\n| unrelated local work | move it out of the candidate path |\n| generated files only | clean or save them under `artifacts/` |\n| unsure | stop and inspect before launching candidates |\n\nDo not fan out code edits from unknown dirty state.\n\n## Choose Isolation\n\nParallel candidates must not overwrite each other.\n\n| Isolation Option | Use When | Example |\n| --- | --- | --- |\n| copied prompt/output folders | candidates are plans, docs, prompts, or generated artifacts | `artifacts/variations/<run-id>/candidates/v1` |\n| branch | edits are small and reviewed one at a time | `git switch -c variation/<run-id>-v1` |\n| git worktree | candidates need parallel repo edits | `git worktree add ../variation-<run-id>/v1 -b variation/<run-id>-v1` |\n| directory copy | no git worktree support, but file edits must be separated | `cp -R app app-v1` |\n| feature flag | candidates can coexist in one app behind flags | `CHECKOUT_VARIANT=v1` |\n| unique process state | candidates run services | `PORT=3101`, `PORT=3102`, `PORT=3103` |\n\nFor code edits, prefer worktrees:\n\n```bash\nBASE=\"$(git rev-parse --show-toplevel)\"\nPARENT=\"$(dirname \"$BASE\")/variation-$RUN_ID\"\n\ngit -C \"$BASE\" worktree add \"$PARENT/v1\" -b \"variation/$RUN_ID-v1\"\ngit -C \"$BASE\" worktree add \"$PARENT/v2\" -b \"variation/$RUN_ID-v2\"\ngit -C \"$BASE\" worktree add \"$PARENT/v3\" -b \"variation/$RUN_ID-v3\"\n\ngit -C \"$BASE\" worktree list | tee \"$ROOT/review/worktrees.txt\"\n```\n\n## Build Candidate Prompts\n\nStart with the same base prompt. Add only the candidate setting.\n\n```bash\nfor id in v1 v2 v3; do\n  cp \"$ROOT/prompts/base.prompt.md\" \"$ROOT/prompts/$id.prompt.md\"\ndone\n\ncat >> \"$ROOT/prompts/v1.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v1\n- variable: idempotency strategy\n- setting: provider event id guard\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v2.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v2\n- variable: idempotency strategy\n- setting: invoice-level processing lock\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v3.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v3\n- variable: idempotency strategy\n- setting: webhook processing ledger\n- do not change any other dimension\nEOF\n\nfor id in v1 v2 v3; do\n  test -s \"$ROOT/prompts/$id.prompt.md\" && echo \"$id prompt:OK\"\ndone\n```\n\nFor checkout UI integration, the same shape works:\n\n```text\nvariable: UI integration strategy\nv1 setting: inline payment method selector in checkout form\nv2 setting: account drawer payment method selector\nv3 setting: review-step payment method selector\n```\n\nKeep database contracts, provider APIs, security constraints, and verification fixed unless those are the chosen variable.\n\n## Fan-Out\n\nUse the same launch shape for every candidate.\n\nLocal background shape:\n\n```bash\nGEN=\"codex\"\n\nfor id in v1 v2 v3; do\n  (\n    cd \"$PARENT/$id\"\n    \"$GEN\" \"$(cat \"$ROOT/prompts/$id.prompt.md\")\"\n  ) > \"$ROOT/logs/$id.generate.log\" 2>&1 &\ndone\n\nwait\n```\n\nVisible pane shape:\n\n```bash\ncmux-run-surface \"cd '$PARENT/v1' && codex \\\"$(cat '$ROOT/prompts/v1.prompt.md')\\\"\"\ncmux-run-surface \"cd '$PARENT/v2' && codex \\\"$(cat '$ROOT/prompts/v2.prompt.md')\\\"\"\ncmux-run-surface \"cd '$PARENT/v3' && codex \\\"$(cat '$ROOT/prompts/v3.prompt.md')\\\"\"\n```\n\nWhat to preserve:\n\n```text\nsame base prompt\nsame invariants\nsame launch shape\none isolated lane per candidate\none log per candidate\n```\n\n## Verify Every Candidate\n\nRun the same verification command for every candidate.\n\n```bash\nVERIFY='pnpm test billing-webhook -- --runInBand && pnpm build'\n: > \"$ROOT/review/verification.tsv\"\n\nfor id in v1 v2 v3; do\n  (\n    cd \"$PARENT/$id\"\n    bash -lc \"$VERIFY\"\n  ) > \"$ROOT/logs/$id.verify.log\" 2>&1\n  status=$?\n  printf '%s\\t%s\\t%s\\n' \"$id\" \"$status\" \"$VERIFY\" \\\n    >> \"$ROOT/review/verification.tsv\"\ndone\n\ncolumn -t -s $'\\t' \"$ROOT/review/verification.tsv\"\n```\n\nSave diff material for review:\n\n```bash\nfor id in v1 v2 v3; do\n  git -C \"$PARENT/$id\" diff --stat \\\n    > \"$ROOT/review/$id.diffstat.txt\"\n  git -C \"$PARENT/$id\" diff \\\n    > \"$ROOT/review/$id.diff.patch\"\ndone\n```\n\nFor UI candidates, also save screenshots:\n\n```bash\nmkdir -p \"$ROOT/review/screenshots\"\n# Save:\n# \"$ROOT/review/screenshots/v1.png\"\n# \"$ROOT/review/screenshots/v2.png\"\n# \"$ROOT/review/screenshots/v3.png\"\n```\n\n## Review Surface\n\nUse the lightest surface that makes comparison honest.\n\n| Surface | Use When | Save |\n| --- | --- | --- |\n| simple matrix | text, plans, test results, diffs | `review/comparison.md` |\n| diff review | code changes matter most | `review/v*.diff.patch` |\n| screenshots | UI integration or visual changes | `review/screenshots/` |\n| test results | correctness is the main gate | `logs/*.verify.log`, `review/verification.tsv` |\n| structured feedback | choice needs to be preserved exactly | `decisions/selection.md` or saved JSON |\n\nCreate comparison notes:\n\n```bash\ncat > \"$ROOT/review/comparison.md\" <<EOF\n# Variation Comparison\n\n## Goal\n\nPrevent duplicate processing of paid billing webhook events.\n\n## Variable Under Test\n\nIdempotency strategy.\n\n## Verification\n\n| Candidate | Status | Log |\n| --- | --- | --- |\n| v1 | see \\`verification.tsv\\` | \\`$ROOT/logs/v1.verify.log\\` |\n| v2 | see \\`verification.tsv\\` | \\`$ROOT/logs/v2.verify.log\\` |\n| v3 | see \\`verification.tsv\\` | \\`$ROOT/logs/v3.verify.log\\` |\n\n## Diff Review\n\n| Candidate | Diff Stat | Full Diff |\n| --- | --- | --- |\n| v1 | \\`$ROOT/review/v1.diffstat.txt\\` | \\`$ROOT/review/v1.diff.patch\\` |\n| v2 | \\`$ROOT/review/v2.diffstat.txt\\` | \\`$ROOT/review/v2.diff.patch\\` |\n| v3 | \\`$ROOT/review/v3.diffstat.txt\\` | \\`$ROOT/review/v3.diff.patch\\` |\n\n## Review Criteria\n\n- prevents duplicate processing\n- preserves provider contract\n- keeps rollback simple\n- passes the same verification command\n- minimizes unnecessary code movement\n\n## Notes\n\n| Candidate | Strengths | Risks | Keep / Drop |\n| --- | --- | --- | --- |\n| v1 | | | |\n| v2 | | | |\n| v3 | | | |\nEOF\n```\n\n## Decision Outcomes\n\nEnd every review with one action.\n\n| Outcome | Meaning | Next Step |\n| --- | --- | --- |\n| Pick | choose one candidate as-is | polish and verify selected candidate |\n| Combine | use one primary candidate plus named pieces from others | merge only named pieces, then verify |\n| Refine | keep one candidate and apply specific feedback | apply bounded edits, then verify |\n| Expand | run another controlled round on a new dimension | write a new matrix |\n| Reject | throw away the set | rewrite the prompt, matrix, or verification |\n\nSaved decision shape:\n\n```bash\ncat > \"$ROOT/decisions/selection.md\" <<'EOF'\n# Saved Decision\n\n- outcome:\n- primary candidate:\n- secondary candidate ids:\n- decision:\n- why:\n- rejected candidates:\n- required follow-up:\n- final verification command:\n\n## Review Notes\n\n- v1:\n- v2:\n- v3:\n\n## Continue Prompt\n\nContinue from this saved decision.\nDo not reopen the entire search.\nPreserve the selected candidate.\nApply only the named feedback.\nRun final verification and save the result.\nEOF\n```\n\nUse the saved decision as the next prompt material:\n\n```bash\ncat \"$ROOT/decisions/selection.md\" \\\n  | p --stdin --print-prompt \\\n  \"Use this saved decision to converge the variation set. Keep scope narrow and run the required verification.\" \\\n  > \"$ROOT/prompts/converge.prompt.md\"\n\ntest -s \"$ROOT/prompts/converge.prompt.md\" && echo \"converge-prompt:OK\"\n```\n\n## Ask The Agent This\n\nCreate a variation matrix:\n\n```text\nCreate a controlled variation matrix for adding saved payment methods to checkout.\n\nUse exactly one variable: UI integration strategy. Keep database schema,\nprovider API, auth behavior, and verification fixed. Propose three candidates,\nthe same verification command for each, isolation strategy, review criteria,\nand the saved decision file shape.\n```\n\nGenerate candidate prompts:\n\n```text\nUsing this base Prompt Builder prompt, create three candidate prompts.\n\nEach candidate must preserve the same goal, invariants, verification command,\nand review criteria. Only vary the idempotency strategy for the billing webhook:\nprovider event id guard, invoice-level processing lock, and webhook processing\nledger. Do not introduce a second variable.\n```\n\nReview a finished variation set:\n\n```text\nReview this variation run.\n\nInspect the matrix, candidate prompts, verification logs, diffs, and comparison\nnotes. Decide Pick, Combine, Refine, Expand, or Reject. If Combine, choose one\nprimary candidate and name the exact pieces to take from the others.\n```\n\nConverge after selection:\n\n```text\nUse this saved decision to converge the variation set.\n\nDo not reopen the entire search. Preserve the selected candidate, apply only\nthe named feedback, run the final verification command, and save the result.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| base prompt saved | `test -s \"$ROOT/prompts/base.prompt.md\"` |\n| launch shape saved | `test -s \"$ROOT/launch/base.launch.json\"` |\n| matrix exists | `test -s \"$ROOT/matrix.md\"` |\n| one variable named | matrix has one `Variable Under Test` |\n| candidates isolated | each candidate has a distinct branch/worktree/directory |\n| same verification | `verification.tsv` shows the same command for every candidate |\n| logs saved | `find \"$ROOT/logs\" -type f | sort` |\n| diff/review material saved | `find \"$ROOT/review\" -type f | sort` |\n| comparison complete | `test -s \"$ROOT/review/comparison.md\"` |\n| decision saved | `test -s \"$ROOT/decisions/selection.md\"` |\n| convergence prompt saved | `test -s \"$ROOT/prompts/converge.prompt.md\"` |\n\n## If It Goes Wrong\n\n### Candidates Changed Multiple Variables\n\nStop and rewrite the matrix.\n\n```text\nIf the candidate changes UI, database schema, and test strategy, it is not a controlled variation.\n```\n\nRecovery:\n\n```text\nKeep one chosen variable.\nMove every other change into invariants or out-of-scope.\nRegenerate candidate prompts.\n```\n\n### Verification Differs Per Candidate\n\nThe comparison is weak if every candidate gets a different proof command.\n\nRecovery:\n\n```text\nPick one verification command before generation.\nIf a candidate needs a different proof, that is evidence for a new round.\n```\n\n### Repo Was Dirty Before Fan-Out\n\nDirty state is not forbidden. Unknown dirty state is the problem.\n\nRecovery:\n\n```bash\ngit status --short\ngit diff\ngit diff --staged\n```\n\nThen commit, stash, clean, or explicitly record what should carry into every candidate.\n\n### Best Idea Is Split Across Candidates\n\nUse `Combine`, not vague merging.\n\n```text\nprimary candidate: v2\ntake from v1: rollback guard\ntake from v3: test fixture\nforbidden: unrelated renames\n```\n\nThen run final verification after convergence.\n\n### All Candidates Fail\n\nDo not pretend one failed candidate won.\n\nUse:\n\n```text\nReject\n```\n\nor:\n\n```text\nExpand with a narrower matrix\n```\n\nSave what the failures proved before starting the next round.\n\n## References And Resources\n\n- Prompt Builder seed prompt: `p --print-prompt`\n- Prompt Builder launch JSON: `p --print-launch-json`\n- Local run folder: `artifacts/variations/<run-id>/`\n- Candidate isolation: `git worktree`\n- Repo state checks: `git status --short`, `git diff`, `git diff --staged`\n- Review artifacts: `review/verification.tsv`, `review/comparison.md`, `decisions/selection.md`\n\n## Operational boundaries\n\n- The fan-out snippets describe the launch shape, not a universally executable harness. Resolve `$ROOT` to an absolute artifact directory before changing into worktrees; validate nested quoting and the installed Codex non-interactive invocation.\n- A candidate process exiting or `wait` returning is not passing proof. Capture each generation exit status and run the same project-valid verification command in every lane.\n- Git worktrees start from committed state. A plain `git diff` omits staged, untracked, and already committed candidate changes; preserve the actual baseline and all relevant review evidence.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-variation-workflows-practice",
      "slug": "variation-workflows-practice",
      "title": "Controlled variation workflows: practice drills",
      "summary": "Fourteen exercises covering variation suitability, single-variable matrices, run artifacts, saved prompt seeds, repository checkpoints, candidate isolation and overrides, uniform verification, comparison, selection, convergence, failure recovery, and final…",
      "category": "Planning",
      "tags": [
        "variations",
        "verification",
        "comparison",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 1: Decide Whether Variations Are Appropriate",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 2: Find The Variable",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 3: Write A Variation Matrix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 4: Create The Run Folder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 5: Save The Section 5 Seed",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 6: Checkpoint Repo State",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 7: Choose Isolation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 8: Build Candidate Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 9: Run The Same Verification",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 10: Build A Comparison File",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 11: Pick The Decision Outcome",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 12: Save The Decision And Convergence Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 13: Failure Path Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/06-code-is-free-generate-variations.md#Exercises: 06. Code Is Free / Generate Variations/Exercise 14: Final Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 2018,
      "url": "/topics/codex-variation-workflows-practice/",
      "markdownUrl": "/markdown/codex-variation-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-variation-workflows-practice.json",
      "headings": [
        {
          "id": "exercise-1-decide-whether-variations-are-appropriate",
          "text": "Exercise 1: Decide Whether Variations Are Appropriate",
          "level": 2
        },
        {
          "id": "exercise-2-find-the-variable",
          "text": "Exercise 2: Find The Variable",
          "level": 2
        },
        {
          "id": "exercise-3-write-a-variation-matrix",
          "text": "Exercise 3: Write A Variation Matrix",
          "level": 2
        },
        {
          "id": "exercise-4-create-the-run-folder",
          "text": "Exercise 4: Create The Run Folder",
          "level": 2
        },
        {
          "id": "exercise-5-save-the-section-5-seed",
          "text": "Exercise 5: Save The Section 5 Seed",
          "level": 2
        },
        {
          "id": "exercise-6-checkpoint-repo-state",
          "text": "Exercise 6: Checkpoint Repo State",
          "level": 2
        },
        {
          "id": "exercise-7-choose-isolation",
          "text": "Exercise 7: Choose Isolation",
          "level": 2
        },
        {
          "id": "exercise-8-build-candidate-prompts",
          "text": "Exercise 8: Build Candidate Prompts",
          "level": 2
        },
        {
          "id": "exercise-9-run-the-same-verification",
          "text": "Exercise 9: Run The Same Verification",
          "level": 2
        },
        {
          "id": "exercise-10-build-a-comparison-file",
          "text": "Exercise 10: Build A Comparison File",
          "level": 2
        },
        {
          "id": "exercise-11-pick-the-decision-outcome",
          "text": "Exercise 11: Pick The Decision Outcome",
          "level": 2
        },
        {
          "id": "exercise-12-save-the-decision-and-convergence-prompt",
          "text": "Exercise 12: Save The Decision And Convergence Prompt",
          "level": 2
        },
        {
          "id": "exercise-13-failure-path-drill",
          "text": "Exercise 13: Failure Path Drill",
          "level": 2
        },
        {
          "id": "exercise-14-final-check",
          "text": "Exercise 14: Final Check",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Controlled variation workflows: practice drills\n\nThese exercises practice turning one deliberate prompt into controlled, verified candidates.\n\nUse a real software project when possible. Keep each exercise small. The goal is not to generate the most candidates; the goal is to compare useful options without losing control.\n\n## Exercise 1: Decide Whether Variations Are Appropriate\n\nFor each task, choose `use variations` or `skip variations`.\n\n| Task | Use / Skip | Why |\n| --- | --- | --- |\n| Add saved payment methods to checkout, with several plausible UI entry points | | |\n| Fix a one-character typo in a route name | | |\n| Stop duplicate billing webhook processing, with multiple plausible idempotency strategies | | |\n| Apply a strict framework migration with exact steps | | |\n| Compare auth/session architecture before refresh-token rotation | | |\n| Implement an exact requested API shape | | |\n| Choose the right test boundary for a regression | | |\n| Repo is dirty and there is no saved state | | |\n| No verification command exists for the candidates | | |\n\nWrite:\n\n```markdown\n# Variation Decision\n\n- task:\n- decision:\n- why:\n- verification available:\n- state safe for fan-out:\n```\n\n## Exercise 2: Find The Variable\n\nPick one request and identify the single variable under test.\n\n| Request | Possible Variable |\n| --- | --- |\n| Checkout saved payment methods could be integrated several ways. | UI integration strategy |\n| Billing webhooks sometimes process the same invoice twice. | idempotency strategy |\n| Auth/session code is becoming hard to reason about. | architecture boundary |\n| This regression needs better coverage. | test boundary |\n| The agent keeps producing broad implementation plans. | prompt framing |\n| The docs are technically correct but hard to use. | documentation organization |\n\nFill out:\n\n```markdown\n# Variable Notes\n\n- request:\n- chosen variable:\n- why this variable matters:\n- invariants:\n  -\n  -\n  -\n- out of scope:\n  -\n  -\n  -\n- candidate count:\n- review question:\n```\n\nRule:\n\n```text\nIf you cannot finish \"we are comparing candidates that differ only by ___,\" stop and narrow.\n```\n\n## Exercise 3: Write A Variation Matrix\n\nUse one of these scenarios:\n\n```text\ncheckout saved payment methods\nbilling webhook duplicate-processing\nauth/session architecture\ntest strategy for a regression\n```\n\nTemplate:\n\n```markdown\n# Variation Matrix\n\n## Goal\n\n## Invariants\n\n- same repo state:\n- same base prompt:\n- same target feature or bug:\n- same constraints:\n- same verification command:\n- same review criteria:\n\n## Variable Under Test\n\n- variable:\n- why this matters:\n- what is out of scope:\n\n## Candidate Count\n\n- count:\n- ids:\n\n## Candidates\n\n| ID | Variable setting | Output location | Verification command | Notes |\n| --- | --- | --- | --- | --- |\n| v1 | | | | |\n| v2 | | | | |\n| v3 | | | | |\n\n## Review Criteria\n\n1.\n2.\n3.\n4.\n5.\n```\n\nCheck it:\n\n```bash\nrg -n \"Goal|Invariants|Variable Under Test|Candidate Count|Review Criteria\" matrix.md\n```\n\n## Exercise 4: Create The Run Folder\n\nCreate a run root under `artifacts/variations`.\n\n```bash\nRUN_ID=\"exercise-$(date +%Y%m%d-%H%M%S)\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT\"/{prompts,launch,logs,review,decisions}\nmkdir -p \"$ROOT\"/candidates/{v1,v2,v3}\nfind \"$ROOT\" -maxdepth 3 -type d | sort\n```\n\nFill out:\n\n```markdown\n# Run Folder Notes\n\n- run id:\n- root:\n- prompt folder:\n- launch folder:\n- candidate folders:\n- logs folder:\n- review folder:\n- decisions folder:\n```\n\n## Exercise 5: Save The Section 5 Seed\n\nUse Prompt Builder to save the base prompt and launch JSON.\n\nCheckout example:\n\n```bash\nPROMPT='Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes.'\n\np --print-prompt \"$PROMPT\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \"$PROMPT\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\nBilling example:\n\n```bash\nPROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.'\n\np --print-prompt \"$PROMPT\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \"$PROMPT\" \\\n  > \"$ROOT/launch/base.launch.json\"\n```\n\nFill out:\n\n```markdown\n# Seed Notes\n\n- base prompt path:\n- launch JSON path:\n- software goal:\n- invariant 1:\n- invariant 2:\n- variable:\n- candidate count:\n- verification command:\n- seed ready? yes/no\n- one improvement before fan-out:\n```\n\n## Exercise 6: Checkpoint Repo State\n\nBefore fan-out, save the current repo state.\n\n```bash\ngit status --short | tee \"$ROOT/review/git-status-before.txt\"\ngit diff > \"$ROOT/review/dirty-before.patch\"\ngit diff --staged > \"$ROOT/review/staged-before.patch\"\n```\n\nFill out:\n\n```markdown\n# Repo State Before Fan-Out\n\n- status file:\n- unstaged patch file:\n- staged patch file:\n- repo clean? yes/no\n- if dirty, what is the dirty work:\n- safe next move:\n```\n\nChoose one safe next move:\n\n| Situation | Move |\n| --- | --- |\n| repo clean | continue |\n| intentional local work | commit or stash |\n| unrelated local work | move it out of the candidate path |\n| generated noise | clean or move under `artifacts/` |\n| unsure | inspect before launching |\n\n## Exercise 7: Choose Isolation\n\nPick the isolation level for your variation set.\n\n| Candidate Type | Best Isolation | Why |\n| --- | --- | --- |\n| prompt rewrites only | copied prompt/output folders | |\n| implementation candidates editing same files | git worktrees | |\n| small sequential experiments | branches | |\n| UI variants that can coexist | feature flags | |\n| services that need ports | unique process state | |\n| generated docs | output directories | |\n\nWrite:\n\n```markdown\n# Isolation Plan\n\n- chosen isolation:\n- why:\n- what could collide:\n- how collisions are prevented:\n- where outputs go:\n- where logs go:\n- how to clean up:\n```\n\n## Exercise 8: Build Candidate Prompts\n\nCopy the base prompt, then append one candidate setting.\n\n```bash\nfor id in v1 v2 v3; do\n  cp \"$ROOT/prompts/base.prompt.md\" \"$ROOT/prompts/$id.prompt.md\"\ndone\n```\n\nCheckout UI integration example:\n\n```bash\ncat >> \"$ROOT/prompts/v1.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v1\n- variable: UI integration strategy\n- setting: inline payment method selector in the checkout form\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v2.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v2\n- variable: UI integration strategy\n- setting: account drawer payment method selector\n- do not change any other dimension\nEOF\n\ncat >> \"$ROOT/prompts/v3.prompt.md\" <<'EOF'\nCandidate override:\n- candidate id: v3\n- variable: UI integration strategy\n- setting: review-step payment method selector\n- do not change any other dimension\nEOF\n```\n\nConfirm:\n\n```bash\nfor id in v1 v2 v3; do\n  echo \"== $id ==\"\n  rg -n \"Candidate override|variable:|setting:|do not change\" \"$ROOT/prompts/$id.prompt.md\"\ndone\n```\n\nFill out:\n\n```markdown\n# Candidate Prompt Notes\n\n| Candidate | Variable setting | Same base prompt? | Same invariants? |\n| --- | --- | --- | --- |\n| v1 | | | |\n| v2 | | | |\n| v3 | | | |\n```\n\n## Exercise 9: Run The Same Verification\n\nPick one verification command for every candidate.\n\nExamples:\n\n```bash\nVERIFY='pnpm test checkout -- --runInBand && pnpm build'\nVERIFY='pnpm test billing-webhook -- --runInBand && pnpm build'\nVERIFY='pnpm test auth -- --runInBand && pnpm build'\nVERIFY='pnpm test -- --runInBand'\n```\n\nRun:\n\n```bash\n: > \"$ROOT/review/verification.tsv\"\n\nfor id in v1 v2 v3; do\n  (\n    cd \"$PARENT/$id\"\n    bash -lc \"$VERIFY\"\n  ) > \"$ROOT/logs/$id.verify.log\" 2>&1\n  status=$?\n  printf '%s\\t%s\\t%s\\n' \"$id\" \"$status\" \"$VERIFY\" \\\n    >> \"$ROOT/review/verification.tsv\"\ndone\n\ncolumn -t -s $'\\t' \"$ROOT/review/verification.tsv\"\n```\n\nFill out:\n\n```markdown\n# Verification Notes\n\n- verification command:\n- v1 status:\n- v1 log:\n- v2 status:\n- v2 log:\n- v3 status:\n- v3 log:\n- candidates excluded from review because they failed:\n- candidates allowed into review:\n```\n\n## Exercise 10: Build A Comparison File\n\nCreate a simple review surface.\n\n```bash\ncat > \"$ROOT/review/comparison.md\" <<EOF\n# Variation Comparison\n\n## Goal\n\n## Variable Under Test\n\n## Verification\n\n| Candidate | Status | Log |\n| --- | --- | --- |\n| v1 | see \\`verification.tsv\\` | \\`$ROOT/logs/v1.verify.log\\` |\n| v2 | see \\`verification.tsv\\` | \\`$ROOT/logs/v2.verify.log\\` |\n| v3 | see \\`verification.tsv\\` | \\`$ROOT/logs/v3.verify.log\\` |\n\n## Review Criteria\n\n1.\n2.\n3.\n4.\n5.\n\n## Notes\n\n| Candidate | Strengths | Risks | Keep / Drop |\n| --- | --- | --- | --- |\n| v1 | | | |\n| v2 | | | |\n| v3 | | | |\nEOF\n```\n\nConfirm:\n\n```bash\ntest -s \"$ROOT/review/comparison.md\" && echo \"comparison:OK\"\n```\n\n## Exercise 11: Pick The Decision Outcome\n\nChoose one outcome.\n\n| Outcome | Use When |\n| --- | --- |\n| Pick | one candidate wins as-is |\n| Combine | one primary candidate wins, but named pieces from others should be merged |\n| Refine | one candidate wins but needs specific improvements |\n| Expand | the round was useful, but a new dimension needs another round |\n| Reject | the set is not worth continuing |\n\nFill out:\n\n```markdown\n# Decision Outcome\n\n- outcome:\n- primary candidate:\n- secondary candidate ids:\n- why:\n- rejected candidates:\n- what to keep:\n- what to drop:\n- required final verification command:\n```\n\n## Exercise 12: Save The Decision And Convergence Prompt\n\nWrite the saved decision file.\n\n```bash\ncat > \"$ROOT/decisions/selection.md\" <<'EOF'\n# Saved Decision\n\n- outcome:\n- primary candidate:\n- secondary candidate ids:\n- decision:\n- why:\n- rejected candidates:\n- required follow-up:\n- final verification command:\n\n## Review Notes\n\n- v1:\n- v2:\n- v3:\n\n## Continue Prompt\n\nContinue from this saved decision.\nDo not reopen the entire search.\nPreserve the selected candidate.\nApply only the named feedback.\nRun final verification and save the result.\nEOF\n```\n\nCreate the convergence prompt:\n\n```bash\ncat \"$ROOT/decisions/selection.md\" \\\n  | p --stdin --print-prompt \\\n  \"Use this saved decision to converge the variation set. Keep scope narrow and run the required verification.\" \\\n  > \"$ROOT/prompts/converge.prompt.md\"\n\ntest -s \"$ROOT/decisions/selection.md\" && echo \"decision:OK\"\ntest -s \"$ROOT/prompts/converge.prompt.md\" && echo \"converge-prompt:OK\"\n```\n\n## Exercise 13: Failure Path Drill\n\nFor each failure, choose the recovery.\n\n| Failure | Recovery |\n| --- | --- |\n| candidates changed multiple variables | |\n| verification command was different for every candidate | |\n| repo was dirty and unrelated changes leaked into diffs | |\n| v1 passed but merge into the main branch conflicts | |\n| best idea is split between v1 and v3 | |\n| all candidates fail verification | |\n| review notes say “I like parts of all of them” | |\n| candidate output folders overwrote each other | |\n| UI candidates have no screenshots | |\n| Expand round changes the previous decision | |\n\nRecovery options:\n\n```text\nrewrite matrix\nregenerate candidates\ndefine verification first\ncheckpoint repo state\nuse worktrees or separate directories\npick a primary candidate\nuse Combine with named parts\nuse Reject\nuse Expand with a new matrix\nsave screenshots\nrerun final verification\n```\n\nFill out:\n\n```markdown\n# Failure Recovery Notes\n\n- failure:\n- likely cause:\n- recovery:\n- command or file to inspect:\n- how to know recovery worked:\n```\n\n## Exercise 14: Final Check\n\nRun these checks on your variation run.\n\n```bash\ntest -s \"$ROOT/matrix.md\" && echo \"matrix:OK\"\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\ntest -s \"$ROOT/launch/base.launch.json\" && echo \"launch-json:OK\"\nfind \"$ROOT/prompts\" -type f | sort\nfind \"$ROOT/logs\" -type f | sort\ntest -s \"$ROOT/review/comparison.md\" && echo \"comparison:OK\"\ntest -s \"$ROOT/decisions/selection.md\" && echo \"decision:OK\"\n```\n\nFill out:\n\n```markdown\n# Final Variation Run Check\n\n- every candidate had the same base prompt? yes/no\n- every candidate changed one variable? yes/no\n- every candidate was isolated? yes/no\n- every candidate used the same verification command? yes/no\n- verification logs saved? yes/no\n- comparison notes saved? yes/no\n- decision saved? yes/no\n- convergence prompt saved? yes/no\n- ready to implement selected path? yes/no\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-design-video-qa-field-guide",
      "slug": "design-video-qa-field-guide",
      "title": "Design, Video, and QA Story Field Guide",
      "summary": "Convert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.",
      "category": "Planning",
      "tags": [
        "field guide",
        "design video qa"
      ],
      "sources": [
        {
          "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
        },
        {
          "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
        },
        {
          "label": "Agent foundations: Use images, video, and task-shaped model routing (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-06.html"
        },
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#design-video-qa/overview",
        "field-guides/guides.mjs#design-video-qa/decision",
        "field-guides/guides.mjs#design-video-qa/agentPrompt",
        "field-guides/guides.mjs#design-video-qa/stories",
        "field-guides/guides.mjs#design-video-qa/tips",
        "field-guides/guides.mjs#design-video-qa/refs"
      ],
      "collection": "foundations",
      "categoryId": "planning",
      "wordCount": 440,
      "url": "/topics/foundations-design-video-qa-field-guide/",
      "markdownUrl": "/markdown/foundations-design-video-qa-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-design-video-qa-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "reference-image-to-ui",
          "text": "Reference image to UI",
          "level": 3
        },
        {
          "id": "narrated-bug-report",
          "text": "Narrated bug report",
          "level": 3
        },
        {
          "id": "5-monkeys-qa-swarm",
          "text": "5 Monkeys QA swarm",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Design, Video, and QA Story Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nConvert taste, screenshots, narrated videos, and weird user behavior into Codex-ready implementation stories.\n\nUse this when words are weak and Codex needs visual requirements plus browser-verifiable acceptance criteria.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| design.md | Durable taste contract | Style DNA, type, color, layout | design.md |\n| Image reference | Human-selected direction | Implement one concrete look | .notes/design/reference.png |\n| Video requirements | Narrated UX behavior | Extract acceptance criteria and edge cases | .goals/<feature>-video.md |\n| QA swarm | Weird-path exploration | Personas, broken paths, browser receipts | .notes/qa/ |\n\n## Agent-ready prompt\n\n```text\nTreat the visual artifact as requirements, not decoration.\nExtract acceptance criteria, user stories, responsive states, and proof moves.\nImplement only the selected direction.\nVerify in browser with screenshots/logs.\nWrite the durable contract to design.md, .goals/<feature>.md, or .notes/qa/<flow>.md depending on the task.\n```\n\n## Applied stories\n\n### Reference image to UI\n\n**Role:** Product engineer\n\nThe team can recognize the desired look but cannot write the CSS spec.\n\n**Agent brief:** Ask Codex to distill the selected image into design.md, implement one route, then browser-proof the result.\n\n**Done when:**\n\n- design.md update\n- implemented route\n- desktop/mobile screenshots\n- diff review\n\n### Narrated bug report\n\n**Role:** Full-stack developer\n\nA PM records cart behavior that is faster to show than explain.\n\n**Agent brief:** Extract requirements from video into a goal file, implement behavior, and prove cart states in browser.\n\n**Done when:**\n\n- video-derived goal\n- acceptance criteria\n- browser proof\n- test/typecheck log\n\n### 5 Monkeys QA swarm\n\n**Role:** QA-minded frontend lead\n\nHappy path passes, but users hit weird navigation and state sequences.\n\n**Agent brief:** Launch persona-based QA workers that write reproducible findings, then collate only high-signal bugs.\n\n**Done when:**\n\n- persona findings\n- dedupe summary\n- screenshots\n- repro steps\n\n## Tips and gotchas\n\n- Do not ask Codex to invent taste from nothing; hand it references and constraints.\n- A video should become acceptance criteria, not a brittle click macro.\n- Keep visual QA disposable until the flow stabilizes; promote only stable checks to tests.\n- Every visual/design story should end with browser proof across relevant viewports.\n\n## References\n\n- [Impeccable](https://impeccable.style/)\n- [Inspiration board](https://inspiration-board.pages.dev/)\n- [OpenAI Codex Figma/frontend post](https://developers.openai.com/codex)\n- [Playwright screenshots](https://playwright.dev/docs/screenshots)\n\n## Related principles\n\n- [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n- [Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
    },
    {
      "id": "codex-verified-variations",
      "slug": "verified-variations",
      "title": "Generate controlled, verified variations",
      "summary": "When code and design candidates are cheap, the mistake is not generating too many. The mistake is generating them randomly. Start by defining the candidates, keep the comparison controlled, run each option through the same constraints, and review the…",
      "category": "Planning",
      "tags": [
        "variations",
        "comparison",
        "proof"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#verified-variations"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-04-generate-verified-variations.md",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Start With A Candidate List",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Vary One Thing At A Time",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Use The Same Base Prompt",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Fan Out After The Matrix Is Clear",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Preserve The Review Surface",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Pick, Combine, Refine, Expand, Or Reject",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Turn The Winner Into A Real Build",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Copyable Prompt: Candidate Matrix",
        "src/content/final/chunk-04-generate-verified-variations.md#Generate Variations Before You Trust One Answer/Copyable Prompt: Refine The Winner",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#verified-variations",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 544,
      "url": "/topics/codex-verified-variations/",
      "markdownUrl": "/markdown/codex-verified-variations.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-verified-variations.json",
      "headings": [
        {
          "id": "start-with-a-candidate-list",
          "text": "Start With A Candidate List",
          "level": 2
        },
        {
          "id": "vary-one-thing-at-a-time",
          "text": "Vary One Thing At A Time",
          "level": 2
        },
        {
          "id": "use-the-same-base-prompt",
          "text": "Use The Same Base Prompt",
          "level": 2
        },
        {
          "id": "fan-out-after-the-matrix-is-clear",
          "text": "Fan Out After The Matrix Is Clear",
          "level": 2
        },
        {
          "id": "preserve-the-review-surface",
          "text": "Preserve The Review Surface",
          "level": 2
        },
        {
          "id": "pick-combine-refine-expand-or-reject",
          "text": "Pick, Combine, Refine, Expand, Or Reject",
          "level": 2
        },
        {
          "id": "turn-the-winner-into-a-real-build",
          "text": "Turn The Winner Into A Real Build",
          "level": 2
        },
        {
          "id": "copyable-prompt-candidate-matrix",
          "text": "Copyable Prompt: Candidate Matrix",
          "level": 2
        },
        {
          "id": "copyable-prompt-refine-the-winner",
          "text": "Copyable Prompt: Refine The Winner",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Generate controlled, verified variations\n\nWhen code and design candidates are cheap, the mistake is not generating too many. **The mistake is generating them randomly.** Start by defining the candidates, keep the comparison controlled, run each option through the same constraints, and review the outputs on a surface that makes the decision obvious enough to defend later.\n\n## Start With A Candidate List\n\nAsk the agent to **generate the dataset first**: styles, strategies, prompts, layouts, implementation approaches, or test boundaries. Remove duplicates, rename vague entries, and make sure each candidate is **different for a reason**.\n\n> To do variations, like, you come up with the variations first.\n>\n> — John Lindquist\n\n## Vary One Thing At A Time\n\nIf every candidate changes layout, data model, tests, and copy, you are **no longer comparing candidates**. You are just admiring chaos with a folder structure.\n\n## Use The Same Base Prompt\n\nCandidate prompts should **differ only by the named variable**. Keep the base prompt, constraints, review criteria, and verification command identical.\n\n## Fan Out After The Matrix Is Clear\n\nParallelization is useful after you know what each lane is supposed to test. **Treat the candidate list like data**: each lane gets a candidate id, one variable setting, and the same proof requirement.\n\n> I definitely wouldn't rely on setting a long loop… Because then you get into, like, after a while, compaction and other things where you lose that context and things start to look alike.\n>\n> — John Lindquist\n\n## Preserve The Review Surface\n\nFor UI work, use screenshots or a [gallery](https://inspiration-board.pages.dev/variations/01-masonry-grid). For code, use diffs, test logs, and a short comparison table. **Save the artifacts before choosing** so the decision does not disappear into memory.\n\n## Pick, Combine, Refine, Expand, Or Reject\n\nThose are the valid outcomes. **Choose one explicitly.** If two candidates each have one strong idea, combine the named pieces. If the whole batch is wrong, reject the batch and update the matrix.\n\n## Turn The Winner Into A Real Build\n\nA generated mockup is **direction, not shipped UI**. Use the selected candidate as the reference for a verified implementation pass. The next prompt should say what won, why it won, what to preserve, what to fix, and what proof counts as done.\n\n## Copyable Prompt: Candidate Matrix\n\n```text\nCreate a variation matrix for a software UI concept.\n\nGoal:\nDesign a mobile app screen for browsing saved listings.\n\nVariable under test:\nVisual layout direction.\n\nGenerate 8 candidate directions.\n\nFor each candidate, include:\n- id\n- layout direction\n- design constraints\n- what should stay identical\n- what would make this candidate fail review\n\nDo not generate the UI yet.\nReturn the candidate matrix first.\n```\n\n## Copyable Prompt: Refine The Winner\n\n```text\nContinue from this saved variation decision.\n\nOutcome:\nRefine.\n\nPrimary candidate:\nv2.\n\nWhy:\nIt best preserves the constraints and passes the review criteria.\n\nPreserve:\n- the selected layout structure\n- the interaction model\n- the accepted visual hierarchy\n\nFix:\n- tighten spacing on mobile\n- improve empty-state copy\n- keep the same data model\n\nVerification:\nRun the same verification command from the matrix and save the result.\n\nDo not reopen the candidate search.\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#verified-variations)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "factory-design-variations",
      "slug": "design-variations",
      "title": "Generate to diverge, code to converge",
      "summary": "Keep the subject fixed while exploring structural alternatives, then turn the selected bitmap into verified code.",
      "category": "Planning",
      "tags": [
        "design",
        "factory"
      ],
      "sources": [
        {
          "label": "Generate to diverge, code to converge",
          "url": "https://indigo-kayak-2zw8.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste"
        }
      ],
      "sourceUnits": [
        "07-variations/index.html#TL;DR",
        "07-variations/index.html#Design exploration stalls on production, not taste",
        "07-variations/index.html#Appendix",
        "07-variations/index.html#Two CLIs, one pattern",
        "07-variations/index.html#Hold the subject constant",
        "07-variations/index.html#From party trick to 200-style pipeline",
        "07-variations/index.html#Bitmap to real code",
        "learn.html#q3-variations-taste"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 1189,
      "url": "/topics/factory-design-variations/",
      "markdownUrl": "/markdown/factory-design-variations.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "design-exploration-stalls-on-production-not-taste",
          "text": "Design exploration stalls on production, not taste",
          "level": 2
        },
        {
          "id": "two-clis-one-pattern",
          "text": "Two CLIs, one pattern",
          "level": 2
        },
        {
          "id": "hold-the-subject-constant",
          "text": "Hold the subject constant",
          "level": 2
        },
        {
          "id": "from-party-trick-to-200-style-pipeline",
          "text": "From party trick to 200-style pipeline",
          "level": 2
        },
        {
          "id": "bitmap-to-real-code",
          "text": "Bitmap to real code",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "diverge-first-then-record-taste",
          "text": "Diverge first, then record taste",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Generate to diverge, code to converge\n\nKeep the subject fixed while exploring structural alternatives, then turn the selected bitmap into verified code.\n\n## Related working material\n\n- [Generate to diverge, code to converge — prompts and exercises](/topics/factory-design-variations-practice/)\n- [Generate to diverge, code to converge — questions and tradeoffs](/topics/factory-design-variations-questions/)\n- [Generate to diverge, code to converge — worked example](/topics/factory-design-variations-worked-example/)\n\n## TL;DR\n\n- One prompt to Codex (`$imagegen`) or the Antigravity CLI (`agy`) generates **9 wildly different design mockups** straight into your project — no API key.\n- You walk away with both verbatim 9x prompts, both run scripts, and a live-updating contact-sheet gallery that fills in as images land.\n- The one move: **hold the subject constant, vary only the style** — then rebuild the winning bitmap as real HTML/CSS. Generate to diverge, code to converge.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://indigo-kayak-2zw8.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## Design exploration stalls on production, not taste\n\nYou sit down to design a landing page. The usual move is to build one draft and iterate. Each iteration costs an hour or more, so you see maybe three directions before you commit. That is not a taste problem — it is a production problem: you cannot prefer an option you never saw. When a mockup costs a minute instead of an hour, exploring nine directions becomes the cheap default. Prior sessions on this machine show the whole loop fitting in one sitting: one run produced five bitmap mockup directions for a storefront, collected them into a gallery page, and finished with a chosen winner rebuilt as real code.\n\n## Two CLIs, one pattern\n\nCodex ships an `$imagegen` skill that routes image requests through its built-in `image_gen` tool — no API key required, and its contract explicitly lists UI mockups and wireframes as intended uses. The Antigravity CLI exposes a `generate_image` tool the same way. Both run non-interactively (`codex exec \"…\"` / `agy -p \"…\"`) and both follow the same batch rule: one image call per mockup, never a switch to an API fallback.\n\nTwo traps, both from real runs. Codex saves built-in image output under `$CODEX_HOME/generated_images/` — if your prompt doesn't say \"copy each image into `./mockups/`\", the run can succeed while your project folder stays empty. And agy's `--print-timeout` defaults to five minutes; nine images take longer, so the run script raises it to fifteen. The failure signal for both is the same: an empty contact sheet. Read the run log before blaming the model.\n\n## Hold the subject constant\n\nNine images are only useful if you can compare them, and they are only comparable if exactly one variable changes. \"Make nine cool designs\" gives you nine incomparable posters. \"Same homepage, same hero, same call to action — nine styles\" gives you a controlled experiment you can read at a glance. The inspiration-board pipeline enforces this discipline with a shared subject file appended to every style prompt, \"so you can compare how each visual approach handles\" the same material. Before you run, write your subject as one sentence that names the page type and its content; if a mockup comes back as a different page type, regenerate it — don't compare it.\n\n## From party trick to 200-style pipeline\n\nNine mockups is a live demo. Two hundred is a pipeline, and the difference is error handling. The [inspiration-board](https://inspiration-board.pages.dev/variations/01-masonry-grid) project generates its images by driving the Antigravity CLI from a bash loop across 200 named web-design styles. Its generator demands machine-readable status from every run — the JSON contract in the prompt library above — fixes each output filename in advance, and skips any file already on disk above 100 KB, so quota-interrupted runs resume instead of restarting. When your own loop grows past a handful of images, adopt those in order: fixed names, skip-if-exists, JSON status, then background jobs with progress lines.\n\nThe variations idea applies twice there: the images are style variations, and the gallery pages themselves are twelve layout variations of the same image set — masonry grid, infinite scroll, carousel, lightbox, compare-split, magazine editorial, filmstrip, table list, mood board, fullscreen slideshow, grouped categories, search-first.\n\n## Bitmap to real code\n\nThe mockups are bitmaps — for deciding, not shipping. The loop closes when you pick one tile and hand it back to a coding agent as a reference image, using the converge prompt in the library. Your decision rule: pick the tile you would be embarrassed to lose. If no tile clears that bar, the styles were not divergent enough — widen the directions and rerun rather than polishing the least-bad option.\n\n## Appendix\n\n### Limits & caveats\n\n- The quota-handling and skip-guard evidence comes from one project's scripts driving one CLI. The sources do not establish that other agents fail the same way, or how often quota errors occur — only how this pipeline survives them.\n- No source here measures whether any generated direction is aesthetically *better*. That judgment stays with you.\n- A prior batch run stalled silently mid-generation and the operator had to ping the session (\"hello? What is happening?\"). The recorded lesson: run each image generation as its own background job and make the agent narrate progress.\n- Codex also has a gated CLI fallback for image generation (needs `OPENAI_API_KEY` and an explicit request). You never need it for this workflow — \"many assets\" still means one built-in call per asset.\n- `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` skip permission prompts. Use them in projects you trust, not on machines or folders you care about being prompted for.\n- agy image quota errors are real; the JSON status contract exists because retrying silently wastes the whole loop. Report the reset time instead.\n- The workshop agenda spells the skill `$imgagegen` — that's a typo; it's `$imagegen`.\n\n## Operating practice\n\n### Diverge first, then record taste\n\n#### What to notice\n\nMake important design choices visible while change is cheap, then turn preference into a reusable contract.\n\n#### Try this\n\nGenerate four structurally distinct options, compare pairs, and record both the winning property and the **rejection reason**.\n\n> “When code is disposable, code is cheap.”\n\nJohn Lindquist · [04:43:09](https://proud-anchor-53zn.here.now/watch.html?t=16989#recording-player)\n\n#### Concept\n\nHold content and product intent constant while varying hierarchy, density, navigation, and interaction emphasis. Promote repeated choices into DESIGN.md so the next agent can apply and challenge them.\n\n#### Reflection\n\nFour options is a bounded companion exercise. The recorded demonstration produced more; neither count is a universal rule.\n\n**Recording evidence:** listen at 04:42:47.\n\n> “Never underestimate the power of just, being a curator. When the agent can be a generator.”\n\nJohn Lindquist · [04:50:49](https://proud-anchor-53zn.here.now/watch.html?t=17449#recording-player)\n\n[Open Generate Variations](https://indigo-kayak-2zw8.here.now/)[Open This or That — Preference Capture](https://gentle-lasso-9d5n.here.now/)\n\n#### Links shared for this topic\n\n- [Mini Arcade](https://miniarcade.dev/) — A generated product used as a design and implementation example.\n- [Mini Arcade source](https://github.com/johnlindquist/miniarcade) — The source repository behind the product example.\n- [Inspiration Board](https://inspiration-board.pages.dev/) — A board for collecting and comparing visual references.\n- [Impeccable](https://impeccable.style/) — Design guidance and reusable taste constraints for agents.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=16967#q3-variations-taste)"
    },
    {
      "id": "factory-design-variations-discussion",
      "slug": "design-variations-discussion",
      "title": "Generate to diverge, code to converge — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Planning",
      "tags": [
        "design-variations",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[153]",
        "resource-manifest.json#videoEvidence.concepts[154]",
        "resource-manifest.json#videoEvidence.concepts[155]",
        "resource-manifest.json#videoEvidence.concepts[156]",
        "resource-manifest.json#videoEvidence.concepts[157]",
        "resource-manifest.json#videoEvidence.concepts[158]",
        "resource-manifest.json#videoEvidence.concepts[159]",
        "resource-manifest.json#videoEvidence.concepts[160]",
        "resource-manifest.json#videoEvidence.concepts[161]",
        "resource-manifest.json#videoEvidence.concepts[162]",
        "resource-manifest.json#videoEvidence.concepts[163]",
        "resource-manifest.json#videoEvidence.concepts[164]",
        "resource-manifest.json#videoEvidence.concepts[165]",
        "resource-manifest.json#videoEvidence.concepts[166]",
        "resource-manifest.json#videoEvidence.concepts[167]",
        "resource-manifest.json#videoEvidence.concepts[168]",
        "resource-manifest.json#videoEvidence.concepts[169]",
        "resource-manifest.json#videoEvidence.concepts[170]",
        "resource-manifest.json#videoEvidence.concepts[171]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[54]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[55]",
        "resource-manifest.json#videoEvidence.exercises[12]",
        "resource-manifest.json#videoEvidence.exercises[13]",
        "resource-manifest.json#videoEvidence.exercises[14]",
        "resource-manifest.json#videoEvidence.exercises[15]",
        "resource-manifest.json#videoEvidence.timeline[728]",
        "resource-manifest.json#videoEvidence.timeline[729]",
        "resource-manifest.json#videoEvidence.timeline[730]",
        "resource-manifest.json#videoEvidence.timeline[731]",
        "resource-manifest.json#videoEvidence.timeline[732]",
        "resource-manifest.json#videoEvidence.timeline[733]",
        "resource-manifest.json#videoEvidence.timeline[734]",
        "resource-manifest.json#videoEvidence.timeline[736]",
        "resource-manifest.json#videoEvidence.timeline[737]",
        "resource-manifest.json#videoEvidence.timeline[738]",
        "resource-manifest.json#videoEvidence.timeline[739]",
        "resource-manifest.json#videoEvidence.timeline[740]",
        "resource-manifest.json#videoEvidence.timeline[741]",
        "resource-manifest.json#videoEvidence.timeline[742]",
        "resource-manifest.json#videoEvidence.timeline[743]",
        "resource-manifest.json#videoEvidence.timeline[744]",
        "resource-manifest.json#videoEvidence.timeline[745]",
        "resource-manifest.json#videoEvidence.timeline[746]",
        "resource-manifest.json#videoEvidence.timeline[759]",
        "resource-manifest.json#videoEvidence.timeline[760]",
        "resource-manifest.json#videoEvidence.timeline[767]",
        "resource-manifest.json#videoEvidence.timeline[769]",
        "resource-manifest.json#videoEvidence.timeline[770]",
        "resource-manifest.json#videoEvidence.timeline[771]",
        "resource-manifest.json#videoEvidence.timeline[772]",
        "resource-manifest.json#videoEvidence.timeline[774]",
        "resource-manifest.json#videoEvidence.timeline[775]",
        "resource-manifest.json#videoEvidence.timeline[779]",
        "resource-manifest.json#videoEvidence.timeline[780]",
        "resource-manifest.json#videoEvidence.timeline[781]",
        "resource-manifest.json#videoEvidence.timeline[782]",
        "resource-manifest.json#videoEvidence.timeline[783]",
        "resource-manifest.json#videoEvidence.timeline[787]",
        "resource-manifest.json#videoEvidence.timeline[789]",
        "resource-manifest.json#videoEvidence.timeline[791]",
        "resource-manifest.json#videoEvidence.timeline[792]",
        "resource-manifest.json#videoEvidence.timeline[795]",
        "resource-manifest.json#videoEvidence.timeline[799]",
        "resource-manifest.json#videoEvidence.timeline[802]",
        "resource-manifest.json#videoEvidence.timeline[803]",
        "resource-manifest.json#videoEvidence.timeline[808]",
        "resource-manifest.json#videoEvidence.uncertainties[49]",
        "resource-manifest.json#videoEvidence.uncertainties[50]",
        "resource-manifest.json#videoEvidence.uncertainties[51]",
        "resource-manifest.json#videoEvidence.uncertainties[52]",
        "resource-manifest.json#videoEvidence.uncertainties[53]",
        "resource-manifest.json#videoEvidence.demos[90]",
        "resource-manifest.json#videoEvidence.demos[91]",
        "resource-manifest.json#videoEvidence.demos[92]",
        "resource-manifest.json#videoEvidence.demos[93]",
        "resource-manifest.json#videoEvidence.demos[94]",
        "resource-manifest.json#videoEvidence.demos[95]",
        "resource-manifest.json#videoEvidence.demos[96]",
        "resource-manifest.json#videoEvidence.demos[97]",
        "resource-manifest.json#videoEvidence.demos[98]",
        "resource-manifest.json#videoEvidence.demos[99]",
        "resource-manifest.json#videoEvidence.demos[100]",
        "resource-manifest.json#videoEvidence.demos[101]",
        "resource-manifest.json#videoEvidence.demos[102]"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 2261,
      "url": "/topics/factory-design-variations-discussion/",
      "markdownUrl": "/markdown/factory-design-variations-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "design-variations",
          "text": "Design Variations",
          "level": 3
        },
        {
          "id": "rlhf-style-selection",
          "text": "RLHF Style Selection",
          "level": 3
        },
        {
          "id": "style-dna-prompting",
          "text": "Style DNA Prompting",
          "level": 3
        },
        {
          "id": "taste-curation-preference-training",
          "text": "Taste Curation / Preference Training",
          "level": 3
        },
        {
          "id": "exposing-agent-decision-spaces",
          "text": "Exposing Agent Decision Spaces",
          "level": 3
        },
        {
          "id": "curator-vs-generator-framework",
          "text": "Curator vs. Generator Framework",
          "level": 3
        },
        {
          "id": "style-dna-extraction",
          "text": "Style DNA Extraction",
          "level": 3
        },
        {
          "id": "automated-visual-verification",
          "text": "Automated Visual Verification",
          "level": 3
        },
        {
          "id": "github-cli-agent-discovery",
          "text": "GitHub CLI Agent Discovery",
          "level": 3
        },
        {
          "id": "browser-terminal-emulation",
          "text": "Browser Terminal Emulation",
          "level": 3
        },
        {
          "id": "design-system-specification-file-design-md",
          "text": "Design System Specification File (DESIGN.md)",
          "level": 3
        },
        {
          "id": "modular-agent-design-skills",
          "text": "Modular Agent Design Skills",
          "level": 3
        },
        {
          "id": "local-named-domain-proxying-portless",
          "text": "Local Named Domain Proxying (Portless)",
          "level": 3
        },
        {
          "id": "cdp-automation-via-ai-agents",
          "text": "CDP Automation via AI Agents",
          "level": 3
        },
        {
          "id": "generative-ui-rendering",
          "text": "Generative UI Rendering",
          "level": 3
        },
        {
          "id": "iconography-vs-custom-svg",
          "text": "Iconography vs. Custom SVG",
          "level": 3
        },
        {
          "id": "9x-mockups-rapid-variation",
          "text": "9x Mockups / Rapid Variation",
          "level": 3
        },
        {
          "id": "this-or-that-rlhf-for-agents",
          "text": "This or That / RLHF for Agents",
          "level": 3
        },
        {
          "id": "inverse-questioning-grillme-vs-filtering",
          "text": "Inverse Questioning (GrillMe vs. Filtering)",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "how-do-you-maintain-design-consistency-across-iterations-for-example-once-you-ve-chosen-a-branding-direction-how-do-you-ensure-the-model-keeps-generating-assets-in-that-exact-style",
          "text": "How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style?",
          "level": 3
        },
        {
          "id": "how-do-you-maintain-design-consistency-across-iterations-once-a-branding-direction-is-chosen",
          "text": "How do you maintain design consistency across iterations once a branding direction is chosen?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-specific-cli-shell-configuration-parameter-shortcuts-utilized-at-04-43-40-000",
          "text": "Unresolved: Specific CLI shell configuration parameter shortcuts utilized at 04:43:40.000.",
          "level": 3
        },
        {
          "id": "unresolved-exact-structural-data-lines-passed-inside-the-prompt-package",
          "text": "Unresolved: Exact structural data lines passed inside the prompt package.",
          "level": 3
        },
        {
          "id": "unresolved-exact-arguments-passed-to-gh-api-in-claude-code-sub-shell-call",
          "text": "Unresolved: Exact arguments passed to gh api in Claude Code sub-shell call",
          "level": 3
        },
        {
          "id": "unresolved-claude-code-agent-execution-results-for-mdflow-dev-performance-audit",
          "text": "Unresolved: Claude Code agent execution results for mdflow.dev performance audit.",
          "level": 3
        },
        {
          "id": "unresolved-specific-model-names-used-during-image-generation-in-the-prompt-library-examples",
          "text": "Unresolved: Specific model names used during image generation in the prompt library examples.",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-43-40",
          "text": "Demonstration detail: 04:43:40",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-45-22",
          "text": "Demonstration detail: 04:45:22",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-46-47",
          "text": "Demonstration detail: 04:46:47",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-51-28",
          "text": "Demonstration detail: 04:51:28",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-53-41",
          "text": "Demonstration detail: 04:53:41",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-54-30",
          "text": "Demonstration detail: 04:54:30",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-55-27",
          "text": "Demonstration detail: 04:55:27",
          "level": 3
        },
        {
          "id": "demonstration-detail-04-56-31",
          "text": "Demonstration detail: 04:56:31",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-00-28",
          "text": "Demonstration detail: 05:00:28",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-01-39",
          "text": "Demonstration detail: 05:01:39",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-02-05",
          "text": "Demonstration detail: 05:02:05",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-02-24",
          "text": "Demonstration detail: 05:02:24",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-04-03",
          "text": "Demonstration detail: 05:04:03",
          "level": 3
        }
      ],
      "markdown": "# Generate to diverge, code to converge — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Design Variations\n\nAutomated generation of distinct visual interfaces via decoupled parallel sub-agents.\n\n### RLHF Style Selection\n\nExtracting human visual taste parameters through continuous paired choice evaluations.\n\n### Style DNA Prompting\n\nRe-injecting ranked image reference structures back into generation agents to guide aesthetic consistency.\n\n### Taste Curation / Preference Training\n\nThe process of providing targeted human feedback and stylistic constraints to train and shape AI output patterns according to the user's specific aesthetics or architectural choices.\n\n### Exposing Agent Decision Spaces\n\nAn architectural pattern where an agent surfaces multiple internal candidates or configurations to the user for explicit human selection, rather than making hidden decisions autonomously.\n\n### Curator vs. Generator Framework\n\nSteering generative capabilities by applying precise personal aesthetic constraints and reference examples.\n\n### Style DNA Extraction\n\nConsolidating specific font, layout, and color metadata into a standardized design specification doc to inform automated multi-page layouts.\n\n### Automated Visual Verification\n\nUsing headless browser frameworks within an AI pipeline to validate rendering outputs prior to reporting task completion.\n\n### GitHub CLI Agent Discovery\n\nLeveraging gh CLI inside an AI agent prompt to programmatically search, filter, and summarize open-source repository contributions.\n\n### Browser Terminal Emulation\n\nSimulating agent CLI execution flows inside browser web components (as seen on mdflow.dev) to present workshop exercises deterministically without execution delays.\n\n### Design System Specification File (DESIGN.md)\n\nStoring detailed design system rules, color palettes, and constraints in a standardized DESIGN.md file to lock AI models into exact visual styles.\n\n### Modular Agent Design Skills\n\nSpecialized slash commands (e.g. /typeset, /colorize, /critique, /polish) that direct LLMs to evaluate and fix specific aspects of frontend layout and UI.\n\n### Local Named Domain Proxying (Portless)\n\nReplacing port-based localhost URLs with named .localhost domains to streamline OAuth authentication and callbacks.\n\n### CDP Automation via AI Agents\n\nLeveraging Chrome DevTools Protocol inside headless browser agents to profile latency, first paint, and network performance.\n\n### Generative UI Rendering\n\nLLMs generating structured JSON UI specifications that front-end packages render dynamically.\n\n### Iconography vs. Custom SVG\n\nModels tend to draw inline SVG code when generating UI visuals, which often results in poor layout quality; specifying standardized icon libraries like Lucide yields cleaner outcomes.\n\n### 9x Mockups / Rapid Variation\n\nGenerating multiple image/UI mockups from a single prompt allows developers to explore design options before writing production code.\n\n### This or That / RLHF for Agents\n\nA rapid comparative choice loop where human preference selections ('swipe left, swipe right') train or guide agent decisions and teach aesthetic taste.\n\n### Inverse Questioning (GrillMe vs. Filtering)\n\nRather than conducting an extensive upfront technical interview (as in grill-me), an inverse flow generates candidate options first and discards unselected choices.\n\n## Questions and answer status\n\n### How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style?\n\n**Status: answered.** John recommends using Impeccable (impeccable.style), which records styling choices in a DESIGN.md file and provides dedicated design skills (/typeset, /colorize, /animate, /critique) to prevent AI style drift.\n\n### How do you maintain design consistency across iterations once a branding direction is chosen?\n\n**Status: answered.** John demonstrates using structured design systems (e.g., Impeccable) and explicit system rules regarding icons/SVGs to maintain consistency across AI generations.\n\n## Exercises\n\n- **Try:** Select four design references from your workspace, extract their elements into a clear markdown file named DESIGN.md, and run an autonomous agent cycle to automatically build and host matching variations.\n  **Basis:** 04:50:19.335 visual log of files read and written to configure design presets.\n\n- **Try:** Use Impeccable to create a DESIGN.md specification for an app and run /typeset or /colorize skills to maintain design consistency across AI generations.\n  **Basis:** Demonstrated by John Lindquist between 04:56:31 and 04:57:53 in response to a participant's question.\n\n- **Try:** Author agent prompts leveraging agent-browser and CDP to inspect page load latency and initial paint metrics.\n  **Basis:** John prompts Claude Code to use agent-browser for detecting latency and perf issues in mdflow.dev.\n\n- **Try:** Set up a 'This or That' comparative choice skill/flow to evaluate generated design variations and teach agent taste.\n  **Basis:** You can set up a skill for this... walks through setting up the skill or the flow for this... give it a shot to see how you like it. (transcript 05:03:31 - 05:05:22)\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [04:44:43](https://proud-anchor-53zn.here.now/watch.html?t=17083#recording-player) — Describes the image generation scripting process using Codex, Antigravity, and Grok engines.\n\n- [04:45:22](https://proud-anchor-53zn.here.now/watch.html?t=17122#recording-player) — Triggers the side-by-side tournament UI layout game.\n\n- [04:46:15](https://proud-anchor-53zn.here.now/watch.html?t=17175#recording-player) — Completes visual alignment selections to load the taste profile screen.\n\n- [04:46:28](https://proud-anchor-53zn.here.now/watch.html?t=17188#recording-player) — Extracts the generated structured prompt block text to system clipboard.\n\n- [04:46:32](https://proud-anchor-53zn.here.now/watch.html?t=17192#recording-player) — Pastes markdown style data rules directly into the clipboard.md active buffer view.\n\n- [04:46:34](https://proud-anchor-53zn.here.now/watch.html?t=17194#recording-player) — Code editor displays clipboard.md containing Reference 1 - Pop Art Publication, Reference 2 - Garden and Botanical Journal, and Reference 3 - Newspaper Sunday Comics style specifications.\n\n- [04:46:35](https://proud-anchor-53zn.here.now/watch.html?t=17195#recording-player) — John Lindquist references the PopArt publication style prompt used to generate the reference images.\n\n- [04:46:58](https://proud-anchor-53zn.here.now/watch.html?t=17218#recording-player) — John Lindquist pastes 171 lines from clipboard.md into Claude Code and appends user feedback requesting a variation integrating these styles, finalized with a publication command.\n\n- [04:47:48](https://proud-anchor-53zn.here.now/watch.html?t=17268#recording-player) — Claude Code prints out the final response requirements, design deliverables list, and initiates network file requests to pull reference assets.\n\n- [04:47:48](https://proud-anchor-53zn.here.now/watch.html?t=17268#recording-player) — John Lindquist explains that human feedback and reinforcement learning allow developers to train models based on their unique style and structural tastes.\n\n- [04:48:28](https://proud-anchor-53zn.here.now/watch.html?t=17308#recording-player) — John Lindquist advocates for agents exposing all choice paths to the driver's seat instead of autonomously choosing one hidden alternative out of a billion options.\n\n- [04:48:49](https://proud-anchor-53zn.here.now/watch.html?t=17329#recording-player) — Claude Code records tool logs completing a file write action that saves 570 lines of data to DESIGN.md.\n\n- [04:49:58](https://proud-anchor-53zn.here.now/watch.html?t=17398#recording-player) — Claude Code invokes the custom Skill(here-now), resulting in a successful load status message.\n\n- [04:50:07](https://proud-anchor-53zn.here.now/watch.html?t=17407#recording-player) — John Lindquist suggests capturing bookmarks, screenshots, and photos of real-world inspiration to inject into agent environments to align design outcomes.\n\n- [04:50:19](https://proud-anchor-53zn.here.now/watch.html?t=17419#recording-player) — The terminal window displays an ongoing agent loop log showing files read and code written to DESIGN.md by Claude.\n\n- [04:50:19](https://proud-anchor-53zn.here.now/watch.html?t=17419#recording-player) — John talks about collecting items of personal inspiration around the house to refine design taste.\n\n- [04:50:46](https://proud-anchor-53zn.here.now/watch.html?t=17446#recording-player) — The terminal display updates to show all pane tests passed and a list of updated configuration targets.\n\n- [04:51:24](https://proud-anchor-53zn.here.now/watch.html?t=17484#recording-player) — A Markdown table becomes visible in the terminal log containing nine style variations and their corresponding live deployment links.\n\n- [04:53:26](https://proud-anchor-53zn.here.now/watch.html?t=17606#recording-player) — John return to the terminal pane to observe agent logs documenting index.html rendering and agent-browser actions.\n\n- [04:53:34](https://proud-anchor-53zn.here.now/watch.html?t=17614#recording-player) — John points out that the agent is utilizing agent-browser for live UI checks.\n\n- [04:54:27](https://proud-anchor-53zn.here.now/watch.html?t=17667#recording-player) — John mentions using the GitHub CLI with an agent to look up Chris Tate's projects.\n\n- [04:54:35](https://proud-anchor-53zn.here.now/watch.html?t=17675#recording-player) — Atuin v18.10.0 history menu opens briefly in Ghostty terminal.\n\n- [04:54:43](https://proud-anchor-53zn.here.now/watch.html?t=17683#recording-player) — John launches Claude Code v2.1.212 in the terminal.\n\n- [04:54:48](https://proud-anchor-53zn.here.now/watch.html?t=17688#recording-player) — John types a prompt into Claude Code asking to use gh cli to find ctate projects from the past 3 months.\n\n- [04:55:09](https://proud-anchor-53zn.here.now/watch.html?t=17709#recording-player) — Claude Code begins running gh CLI commands to query GitHub API and pull requests.\n\n- [04:55:27](https://proud-anchor-53zn.here.now/watch.html?t=17727#recording-player) — John switches browser tab to mdflow.dev demonstrating browser-based terminal emulation.\n\n- [04:55:36](https://proud-anchor-53zn.here.now/watch.html?t=17736#recording-player) — John explains using web terminal emulation to build workshop exercises that emulate agent flows without waiting for live runs.\n\n- [04:56:31](https://proud-anchor-53zn.here.now/watch.html?t=17791#recording-player) — John recommends Impeccable as a tool for maintaining design consistency.\n\n- [04:56:44](https://proud-anchor-53zn.here.now/watch.html?t=17804#recording-player) — John Lindquist shares https://impeccable.style/ link in chat.\n\n- [04:56:48](https://proud-anchor-53zn.here.now/watch.html?t=17808#recording-player) — John describes how Impeccable captures design rules into a DESIGN.md file.\n\n- [04:57:20](https://proud-anchor-53zn.here.now/watch.html?t=17840#recording-player) — John scrolls through impeccable.style/designing/ showing skills like /typeset, /colorize, and /animate.\n\n- [04:57:53](https://proud-anchor-53zn.here.now/watch.html?t=17873#recording-player) — John presents Impeccable design workflow stages and AI slop detection features at impeccable.style.\n\n- [04:59:47](https://proud-anchor-53zn.here.now/watch.html?t=17987#recording-player) — John explains agent-browser capabilities with Chrome DevTools Protocol for latency and paint timing analysis.\n\n- [05:00:35](https://proud-anchor-53zn.here.now/watch.html?t=18035#recording-player) — John enters prompt instructing Claude Code to run agent-browser against mdflow.dev.\n\n- [05:01:39](https://proud-anchor-53zn.here.now/watch.html?t=18099#recording-player) — John mentions Lucide iconography and advises avoiding custom SVG generation by models.\n\n- [05:02:05](https://proud-anchor-53zn.here.now/watch.html?t=18125#recording-player) — John switches to Ghostty terminal showing Claude CLI agent build logs and publication confirmation for misty-rosette-fqyt.here.now.\n\n- [05:02:27](https://proud-anchor-53zn.here.now/watch.html?t=18147#recording-player) — John emphasizes the power of mockups and mentions generating images with Codex, Anti-Gravity, and Grok.\n\n- [05:03:09](https://proud-anchor-53zn.here.now/watch.html?t=18189#recording-player) — John remarks on image generators frequently producing copyrighted character styles even without direct prompts.\n\n- [05:03:31](https://proud-anchor-53zn.here.now/watch.html?t=18211#recording-player) — John explains setting up a 'this or that' skill/flow for collecting human feedback to guide agent design choices.\n\n- [05:03:58](https://proud-anchor-53zn.here.now/watch.html?t=18238#recording-player) — John references Matt Pocock's GrillMe skill as an example of an intensive upfront questioning process.\n\n- [05:04:31](https://proud-anchor-53zn.here.now/watch.html?t=18271#recording-player) — John describes how filtering generated choices ('swipe left, swipe right') is the inverse of upfront technical questioning.\n\n### Unresolved: Specific CLI shell configuration parameter shortcuts utilized at 04:43:40.000.\n\nTerminal screen elements change lines rapidly right before launch rendering cycles occur.\n\n**Discriminating evidence:** Verify matching bash alias mappings within user setup workspace initialization documentation profiles.\n\n### Unresolved: Exact structural data lines passed inside the prompt package.\n\nThe terminal window condenses large inputs using a custom UI banner displaying '[Pasted text #1 +171 lines]' instead of listing the whole body.\n\n**Discriminating evidence:** Requires access to the source code file clipboard.md to evaluate the exact text contents of the prompt template block.\n\n### Unresolved: Exact arguments passed to gh api in Claude Code sub-shell call\n\nText scrolled rapidly in the terminal buffer during execution.\n\n**Discriminating evidence:** Recorded key visible commands (gh search prs --author=ctate).\n\n### Unresolved: Claude Code agent execution results for mdflow.dev performance audit.\n\nThe CLI execution runs in background/asynchronously and output is not shown prior to shard end.\n\n**Discriminating evidence:** Check subsequent video shards for output of the performance audit.\n\n### Unresolved: Specific model names used during image generation in the prompt library examples.\n\nTranscript mentions 'codecs, anti-gravity and grok', but specific model endpoints are not executed live in this shard.\n\n**Discriminating evidence:** Recorded high-level tool names as described by the presenter.\n\n### Demonstration detail: 04:43:40\n\n- Opened terminal inside mdflow project root\n- Submitted instructions to Claude Code requesting 9 multi-agent variations\n\n**Tools observed:** Claude Code CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nclx\n```\n\n### Demonstration detail: 04:45:22\n\n- Completed visual style tournament matching loops\n- Copied custom context configuration properties layout\n- Pasted code payload structures directly into local file asset\n\n**Tools observed:** Google Chrome, Cursor.\n\n### Demonstration detail: 04:46:47\n\n- Switched focus to terminal pane running Claude Code CLI.\n- Pasted text block from clipboard.md into the Claude Code prompt interface.\n- Appended style criteria and instructions to publish with the /here-now directive.\n- Observed automated file creation log for DESIGN.md and internal tool initialization loops.\n\n**Tools observed:** Claude Code v2.1.212.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nmkdir -p ./refs\ncurl -L\n```\n\n### Demonstration detail: 04:51:28\n\n- Switched through multiple generated style tabs in Google Chrome\n- Inspected individual page treatments on live subdomains\n- Checked the here.now active project dashboard panel\n- Compared variants against the primary mdflow.dev design layout\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 04:53:41\n\n- Searched for agent-browser on Google\n- Opened agent-browser.dev documentation page\n- Typed a GitHub profile address in the URL address bar\n\n**Tools observed:** Google Chrome, Google Search.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nnpm install -g agent-browser\nbrew install agent-browser/tap/agent-browser\nnpx agent-browser open example.com\n```\n\n### Demonstration detail: 04:54:30\n\n- Opened Claude Code CLI in Ghostty terminal\n- Submitted prompt to query ctate GitHub projects via gh CLI\n\n**Tools observed:** Ghostty, Claude Code v2.1.212, gh CLI, Atuin.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nclaude\ngh search prs --author=ctate\ngh api users/ctate/events\n```\n\n### Demonstration detail: 04:55:27\n\n- Navigated to mdflow.dev in Chrome\n- Demonstrated step-by-step browser terminal simulator\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 04:56:31\n\n- Opened impeccable.style in Chrome\n- Explored designing workflow and slash commands\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 05:00:28\n\n- Opened Claude Code terminal session in ~/dev/mdflow\n- Submitted performance analysis prompt using agent-browser tool\n\n**Tools observed:** Claude Code, agent-browser, zsh.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nclaude\nUse agent-browser to detect where we can optimize page load, latency, and any perf-related issues in mdflow.dev\n```\n\n### Demonstration detail: 05:01:39\n\n- Reviewing rendered landing page mockup on misty-rosette-fqyt.here.now\n- Inspecting section layouts, font styling, and icon blocks\n\n**Tools observed:** Google Chrome, Ghostty.\n\n### Demonstration detail: 05:02:05\n\n- Examining Claude CLI execution logs in Ghostty terminal\n- Verifying reference downloads and publication confirmation\n\n**Tools observed:** Ghostty, Claude CLI.\n\n### Demonstration detail: 05:02:24\n\n- Navigating workshop documentation guides on mockups and RLHF\n- Browsing inspiration grid images\n\n**Tools observed:** Google Chrome.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ncurl -s \"http://127.0.0.1:8871/vote\"\n```\n\n### Demonstration detail: 05:04:03\n\n- Searching Google for Matt Pocock's grill-me skill\n- Navigating Matt Pocock's skills repository on GitHub\n- Copying repo link and pasting into meeting chat\n\n**Tools observed:** Google Chrome, Google Search, GitHub."
    },
    {
      "id": "factory-design-variations-practice",
      "slug": "design-variations-practice",
      "title": "Generate to diverge, code to converge — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for generate to diverge, code to converge.",
      "category": "Planning",
      "tags": [
        "prompts",
        "exercises",
        "design-variations"
      ],
      "sources": [
        {
          "label": "Generate to diverge, code to converge",
          "url": "https://indigo-kayak-2zw8.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://indigo-kayak-2zw8.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "07-variations/index.html#Quick start",
        "07-variations/index.html#Prompt library",
        "07-variations/index.html#Set it up (agent guide)",
        "07-variations/index.html#Attachments — install the page skill",
        "07-variations/index.html#Codex — 9x wildly different website mockups",
        "07-variations/index.html#agy (Antigravity) — 9x wildly different mobile mockups",
        "07-variations/index.html#JSON status contract — for scripting image gen at scale",
        "07-variations/index.html#Converge — rebuild the winner as real code",
        "07-variations/agent.md"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 3702,
      "url": "/topics/factory-design-variations-practice/",
      "markdownUrl": "/markdown/factory-design-variations-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "codex-9x-wildly-different-website-mockups",
          "text": "Codex — 9x wildly different website mockups",
          "level": 3
        },
        {
          "id": "agy-antigravity-9x-wildly-different-mobile-mockups",
          "text": "agy (Antigravity) — 9x wildly different mobile mockups",
          "level": 3
        },
        {
          "id": "json-status-contract-for-scripting-image-gen-at-scale",
          "text": "JSON status contract — for scripting image gen at scale",
          "level": 3
        },
        {
          "id": "converge-rebuild-the-winner-as-real-code",
          "text": "Converge — rebuild the winner as real code",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "attachments-install-the-page-skill",
          "text": "Attachments — install the page skill",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "variations-9x-mockups-from-one-prompt-agent-setup-guide",
          "text": "Variations: 9x Mockups from One Prompt — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        },
        {
          "id": "attachment-the-here-now-workshop-page-skill-multi-file",
          "text": "Attachment: the here-now-workshop-page skill (multi-file)",
          "level": 2
        }
      ],
      "markdown": "# Generate to diverge, code to converge — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for generate to diverge, code to converge.\n\n## Quick start\n\nFastest possible taste — 9 website mockups landing in `./mockups/` (needs the Codex CLI; the agy version is in the prompt library):\n\n**Before you run it:** this launches Codex — a paid agent — with sandboxing and approval prompts disabled (`--dangerously-bypass-approvals-and-sandbox`). Read the command first and run it only in a project where you're comfortable with the cost and with an unsandboxed agent writing files.\n\n``` text\nmkdir -p mockups\ncodex exec --dangerously-bypass-approvals-and-sandbox 'Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for a landing page for an indie coffee roaster. The subject stays identical in all 9 - ONLY the visual style varies. One built-in image_gen call per mockup. After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png. Announce progress after each one.'\nls mockups/\n```\n\n## Prompt library\n\nThe first two prompts use a `{{SUBJECT}}` placeholder — replace it before pasting, or let the run scripts (below) substitute it for you. Keep the subject identical across all 9; that's what makes the results comparable.\n\n### Codex — 9x wildly different website mockups\n\n- Agent: Codex CLI (\\$imagegen skill)\n- Working directory: your project root\n- Expected result: mockups/mockup-01.png … mockup-09.png + 9 named style directions\n\n``` text\nUse the $imagegen skill to generate 9 WILDLY different website homepage mockups\nfor {{SUBJECT}}.\n\nRules:\n- The SUBJECT stays identical in all 9 — same product, same page type\n  (homepage), same rough content (hero, nav, one CTA). ONLY the visual style\n  varies. This is what makes them comparable.\n- Pick 9 maximally divergent directions, e.g.: swiss/international typographic,\n  neo-brutalist, glassmorphic dark, editorial magazine, retro terminal,\n  playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine.\n  Name each direction before generating.\n- One built-in image_gen call per mockup (do NOT drop to the CLI fallback).\n- Desktop aspect, full homepage visible, legible headline text.\n- After each image completes, copy it from $CODEX_HOME/generated_images/\n  into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction\n  order you announced).\n- Announce progress after each one — never go silent.\n- When all 9 exist, list the 9 directions next to their filenames.\n```\n\n### agy (Antigravity) — 9x wildly different mobile mockups\n\n- Agent: agy (Google Antigravity CLI)\n- Working directory: your project root\n- Expected result: mockups/mockup-01.png … mockup-09.png, phone aspect, 9 named directions\n\n``` text\nGenerate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your\ngenerate_image tool.\n\nRules:\n- SUBJECT is constant across all 9 — same app, same home screen (listing feed,\n  search, one primary action). ONLY the visual style varies.\n- 9 divergent directions, e.g.: iOS glass minimal, material-you expressive,\n  neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif,\n  cyberpunk neon, paper-collage tactile. Name each before generating.\n- One generate_image call per mockup with ImageName mockup_01 ... mockup_09.\n- Phone aspect ratio (9:19-ish), single screen per image.\n- After each generation, use run_command to copy the artifact into\n  ./mockups/ as mockup-01.png ... mockup-09.png.\n- If you hit an image quota error, report it immediately with the reset time\n  instead of retrying silently.\n- Announce progress after each image.\n```\n\n### JSON status contract — for scripting image gen at scale\n\n- Agent: any image-gen agent driven from bash\n- Working directory: append to your generation prompt\n- Expected result: one parseable JSON line per run — this is how inspiration-board loops over 200 styles unattended\n\n``` text\nRespond with ONLY a JSON object (no markdown, no explanation):\n- Success:     {\"status\":\"ok\",\"path\":\"<output_path>\"}\n- Quota error: {\"status\":\"quota_exhausted\",\"reset_seconds\":<N>,\"reset_time\":\"<ISO8601>\"}\n- Other error: {\"status\":\"error\",\"message\":\"<description>\"}\n```\n\n### Converge — rebuild the winner as real code\n\n- Agent: Codex or Claude Code\n- Working directory: project root, after picking a winner (replace 0N)\n- Expected result: winner/index.html — real text and layout, no bitmap backgrounds\n\n``` text\nmockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at\n./winner/index.html, using the image strictly as a visual reference — real\ntext, real layout, no bitmap backgrounds.\n```\n\n## Set it up (agent guide)\n\n1.  Create the Codex prompt file. The run script extracts its first fenced block and substitutes the subject.\n\n    ```` text\n    # Codex prompt — 9x wildly different website mockups\n\n    Replace `{{SUBJECT}}` with the site you're designing (keep it constant across all 9!).\n\n    ```\n    Use the $imagegen skill to generate 9 WILDLY different website homepage mockups\n    for {{SUBJECT}}.\n\n    Rules:\n    - The SUBJECT stays identical in all 9 — same product, same page type\n      (homepage), same rough content (hero, nav, one CTA). ONLY the visual style\n      varies. This is what makes them comparable.\n    - Pick 9 maximally divergent directions, e.g.: swiss/international typographic,\n      neo-brutalist, glassmorphic dark, editorial magazine, retro terminal,\n      playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine.\n      Name each direction before generating.\n    - One built-in image_gen call per mockup (do NOT drop to the CLI fallback).\n    - Desktop aspect, full homepage visible, legible headline text.\n    - After each image completes, copy it from $CODEX_HOME/generated_images/\n      into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction\n      order you announced).\n    - Announce progress after each one — never go silent.\n    - When all 9 exist, list the 9 directions next to their filenames.\n    ```\n\n    ## Follow-up (converge on a winner)\n\n    ```\n    mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at\n    ./winner/index.html, using the image strictly as a visual reference — real\n    text, real layout, no bitmap backgrounds.\n    ```\n    ````\n\n2.  Create the agy prompt file (same pattern, mobile mockups, plus the scripted status contract).\n\n    ```` text\n    # agy (Antigravity) prompt — 9x wildly different mobile mockups\n\n    Replace `{{SUBJECT}}` with the app you're designing. Historical workshop subject:\n    \"a mobile app for selling houses\".\n\n    ```\n    Generate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your\n    generate_image tool.\n\n    Rules:\n    - SUBJECT is constant across all 9 — same app, same home screen (listing feed,\n      search, one primary action). ONLY the visual style varies.\n    - 9 divergent directions, e.g.: iOS glass minimal, material-you expressive,\n      neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif,\n      cyberpunk neon, paper-collage tactile. Name each before generating.\n    - One generate_image call per mockup with ImageName mockup_01 ... mockup_09.\n    - Phone aspect ratio (9:19-ish), single screen per image.\n    - After each generation, use run_command to copy the artifact into\n      ./mockups/ as mockup-01.png ... mockup-09.png.\n    - If you hit an image quota error, report it immediately with the reset time\n      instead of retrying silently.\n    - Announce progress after each image.\n    ```\n\n    ## Scripted status contract (from the inspiration-board pipeline)\n\n    When driving agy from bash at scale, demand machine-readable status:\n\n    ```\n    Respond with ONLY a JSON object (no markdown, no explanation):\n    - Success:     {\"status\":\"ok\",\"path\":\"<output_path>\"}\n    - Quota error: {\"status\":\"quota_exhausted\",\"reset_seconds\":<N>,\"reset_time\":\"<ISO8601>\"}\n    - Other error: {\"status\":\"error\",\"message\":\"<description>\"}\n    ```\n\n    This is the exact contract `generate.sh` in the inspiration-board pipeline uses\n    to loop over 200 styles unattended, with a skip-if-exists guard (file > 100KB).\n    ````\n\n3.  Create the Codex run script.\n\n    ``` text\n    #!/bin/bash\n    # Fire Codex $imagegen: 9 wildly different website mockups for one subject.\n    # Usage: ./scripts/run-codex-mockups.sh \"a landing page for an indie coffee roaster\"\n    set -euo pipefail\n\n    SUBJECT=\"${1:?usage: $0 \\\"<subject, e.g. a landing page for an indie coffee roaster>\\\"}\"\n    DIR=\"$(cd \"$(dirname \"$0\")/..\" && pwd)\"\n    mkdir -p \"$DIR/mockups\"\n\n    # Extract the first fenced block from the prompt file, substitute the subject.\n    PROMPT=\"$(sed \"s/{{SUBJECT}}/$(printf '%s' \"$SUBJECT\" | sed 's/[&/\\]/\\\\&/g')/g\" \"$DIR/prompts/codex-9x-website.md\" \\\n      | awk '/^```/{f++;next} f==1')\"\n\n    echo \"── codex \\$imagegen → 9 mockups for: $SUBJECT\"\n    echo \"── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)\"\n\n    cd \"$DIR\"\n    codex exec --dangerously-bypass-approvals-and-sandbox \"$PROMPT\"\n    ```\n\n4.  Create the agy run script (note it raises `--print-timeout` to 15m — the 5m default is too short for 9 images).\n\n    ``` text\n    #!/bin/bash\n    # Fire agy (Google Antigravity CLI): 9 wildly different mobile mockups for one subject.\n    # Usage: ./scripts/run-agy-mockups.sh \"a mobile app for selling houses\"\n    set -euo pipefail\n\n    SUBJECT=\"${1:?usage: $0 \\\"<subject, e.g. a mobile app for selling houses>\\\"}\"\n    DIR=\"$(cd \"$(dirname \"$0\")/..\" && pwd)\"\n    mkdir -p \"$DIR/mockups\"\n\n    # Extract the first fenced block from the prompt file, substitute the subject.\n    PROMPT=\"$(sed \"s/{{SUBJECT}}/$(printf '%s' \"$SUBJECT\" | sed 's/[&/\\]/\\\\&/g')/g\" \"$DIR/prompts/agy-9x-mobile.md\" \\\n      | awk '/^```/{f++;next} f==1')\"\n\n    echo \"── agy generate_image → 9 mobile mockups for: $SUBJECT\"\n    echo \"── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)\"\n\n    cd \"$DIR\"\n    agy -p \"$PROMPT\" --dangerously-skip-permissions --print-timeout 15m\n    ```\n\n5.  Create the contact-sheet gallery. It polls every 5 seconds, so tiles fill in live while the run generates.\n\n    ``` text\n    <!doctype html>\n    <html lang=\"en\">\n    <head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>9x Mockup Contact Sheet</title>\n    <style>\n      :root { color-scheme: dark; }\n      body { margin: 0; font: 14px/1.4 ui-sans-serif, system-ui; background: #0d0f12; color: #e8e6e1; }\n      header { padding: 20px 24px 8px; display: flex; align-items: baseline; gap: 12px; }\n      h1 { font-size: 18px; margin: 0; letter-spacing: .02em; }\n      header span { color: #8a8f98; font-size: 12px; }\n      .grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; padding: 16px 24px 32px; }\n      figure { margin: 0; background: #16191e; border: 1px solid #262b33; border-radius: 10px; overflow: hidden; }\n      .frame { aspect-ratio: 4 / 3; display: grid; place-items: center; background:\n        repeating-conic-gradient(#14171c 0% 25%, #101318 0% 50%) 50% / 24px 24px; }\n      .frame img { width: 100%; height: 100%; object-fit: cover; display: block; }\n      .frame .empty { color: #4a5058; font-size: 12px; text-align: center; padding: 12px; }\n      figcaption { padding: 8px 12px; color: #b8bdc4; font-size: 12px; display: flex; justify-content: space-between; }\n      figcaption b { color: #e8e6e1; font-weight: 600; }\n      .frame img:hover { cursor: zoom-in; }\n      dialog { border: 0; padding: 0; background: transparent; max-width: 92vw; }\n      dialog img { max-width: 92vw; max-height: 92vh; border-radius: 8px; }\n      dialog::backdrop { background: rgba(0,0,0,.8); }\n    </style>\n    </head>\n    <body>\n    <header>\n      <h1>9x Wildly Different Mockups</h1>\n      <span>same subject · nine styles · auto-refreshes every 5s while generating</span>\n    </header>\n    <div class=\"grid\" id=\"grid\"></div>\n    <dialog id=\"zoom\"><img id=\"zoomimg\" alt=\"\"></dialog>\n    <script>\n      const grid = document.getElementById('grid');\n      const zoom = document.getElementById('zoom');\n      const zoomimg = document.getElementById('zoomimg');\n      for (let i = 1; i <= 9; i++) {\n        const n = String(i).padStart(2, '0');\n        const fig = document.createElement('figure');\n        fig.innerHTML = `\n          <div class=\"frame\" data-n=\"${n}\"><div class=\"empty\">mockup-${n}.png<br>waiting…</div></div>\n          <figcaption><b>#${n}</b><span class=\"dir\" data-n=\"${n}\"></span></figcaption>`;\n        grid.appendChild(fig);\n      }\n      function tryLoad() {\n        document.querySelectorAll('.frame').forEach(frame => {\n          if (frame.querySelector('img')) return;\n          const n = frame.dataset.n;\n          const img = new Image();\n          img.src = `mockup-${n}.png?t=${Date.now()}`;\n          img.onload = () => {\n            frame.innerHTML = '';\n            frame.appendChild(img);\n            img.addEventListener('click', () => { zoomimg.src = img.src; zoom.showModal(); });\n          };\n        });\n      }\n      zoom.addEventListener('click', () => zoom.close());\n      tryLoad();\n      setInterval(tryLoad, 5000);\n    </script>\n    </body>\n    </html>\n    ```\n\n6.  Make the scripts executable and fire a run (background it — 9 images take a few minutes):\n\n    ``` text\n    chmod +x scripts/run-codex-mockups.sh scripts/run-agy-mockups.sh\n    ./scripts/run-codex-mockups.sh \"a landing page for an indie coffee roaster\"\n    # or, for mobile:\n    ./scripts/run-agy-mockups.sh \"a mobile app for selling houses\"\n    ```\n\n**Success check:** nine numbered PNGs exist and the gallery shows nine tiles — same subject, nine styles.\n\n``` text\nls mockups/mockup-0*.png\nopen mockups/index.html   # macOS; use xdg-open on Linux\n```\n\n``` text\nmockups/mockup-01.png  mockups/mockup-02.png  mockups/mockup-03.png\nmockups/mockup-04.png  mockups/mockup-05.png  mockups/mockup-06.png\nmockups/mockup-07.png  mockups/mockup-08.png  mockups/mockup-09.png\n```\n\n## Attachments — install the page skill\n\nThis is the exact `here-now-workshop-page` skill — with the Elo-voted Instrument Panel theme — that built every page in this workshop, published on this site byte-for-byte (SKILL.md plus its four `templates/` files). Download all five, then `npx skills` copies the whole folder into your project's `.agents/skills/`, `templates/` included. Two tested gotchas are baked in: `.md` URLs on here.now serve an HTML viewer, so the two markdown files must be fetched with `?raw`; and the download is staged in `./page-skill/`, not `./skills/` — the installer treats an existing `./skills/` as an agent's project skill dir and will clobber your download with a symlink.\n\n``` text\nmkdir -p page-skill/here-now-workshop-page/templates\ncurl -fsSL -o page-skill/here-now-workshop-page/SKILL.md \"https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/SKILL.md?raw\"\ncurl -fsSL -o page-skill/here-now-workshop-page/templates/agent.md \"https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/agent.md?raw\"\ncurl -fsSL -o page-skill/here-now-workshop-page/templates/index.html \"https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/index.html\"\ncurl -fsSL -o page-skill/here-now-workshop-page/templates/styles.css \"https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/styles.css\"\ncurl -fsSL -o page-skill/here-now-workshop-page/templates/app.js \"https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/app.js\"\nnpx skills add ./page-skill --skill here-now-workshop-page -y\n```\n\n## Complete reusable setup contract\n\n## Variations: 9x Mockups from One Prompt — agent setup guide\n\nFollowing this file sets up: a 9x design-mockup generator in the user's current project — two prompt files, two run scripts, and a live-updating contact-sheet gallery. One command then generates nine wildly different mockups (same subject, nine styles) into `mockups/`.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal and relative to `<project-root>`.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\ncommand -v codex && codex --version\ncommand -v agy && agy --version\n```\n\nExpected: at least ONE of the two prints a version. `codex` (OpenAI Codex CLI) drives the website-mockup script; `agy` (Google Antigravity CLI) drives the mobile-mockup script. If both are missing, stop and tell your user what to install. Also confirm you are in `<project-root>` and it is writable.\n\n## Steps\n\n1. Create `prompts/codex-9x-website.md` with exactly this content (the run script extracts the first fenced block and substitutes the subject):\n\n````markdown\n# Codex prompt — 9x wildly different website mockups\n\nReplace `{{SUBJECT}}` with the site you're designing (keep it constant across all 9!).\n\n```\nUse the $imagegen skill to generate 9 WILDLY different website homepage mockups\nfor {{SUBJECT}}.\n\nRules:\n- The SUBJECT stays identical in all 9 — same product, same page type\n  (homepage), same rough content (hero, nav, one CTA). ONLY the visual style\n  varies. This is what makes them comparable.\n- Pick 9 maximally divergent directions, e.g.: swiss/international typographic,\n  neo-brutalist, glassmorphic dark, editorial magazine, retro terminal,\n  playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine.\n  Name each direction before generating.\n- One built-in image_gen call per mockup (do NOT drop to the CLI fallback).\n- Desktop aspect, full homepage visible, legible headline text.\n- After each image completes, copy it from $CODEX_HOME/generated_images/\n  into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction\n  order you announced).\n- Announce progress after each one — never go silent.\n- When all 9 exist, list the 9 directions next to their filenames.\n```\n\n## Follow-up (converge on a winner)\n\n```\nmockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at\n./winner/index.html, using the image strictly as a visual reference — real\ntext, real layout, no bitmap backgrounds.\n```\n````\n\n2. Create `prompts/agy-9x-mobile.md` with exactly this content:\n\n````markdown\n# agy (Antigravity) prompt — 9x wildly different mobile mockups\n\nReplace `{{SUBJECT}}` with the app you're designing. Historical workshop subject:\n\"a mobile app for selling houses\".\n\n```\nGenerate 9 WILDLY different mobile app UI mockups for {{SUBJECT}} using your\ngenerate_image tool.\n\nRules:\n- SUBJECT is constant across all 9 — same app, same home screen (listing feed,\n  search, one primary action). ONLY the visual style varies.\n- 9 divergent directions, e.g.: iOS glass minimal, material-you expressive,\n  neo-brutalist, dark luxury, pastel neumorphic, retro pixel, editorial serif,\n  cyberpunk neon, paper-collage tactile. Name each before generating.\n- One generate_image call per mockup with ImageName mockup_01 ... mockup_09.\n- Phone aspect ratio (9:19-ish), single screen per image.\n- After each generation, use run_command to copy the artifact into\n  ./mockups/ as mockup-01.png ... mockup-09.png.\n- If you hit an image quota error, report it immediately with the reset time\n  instead of retrying silently.\n- Announce progress after each image.\n```\n\n## Scripted status contract (from the inspiration-board pipeline)\n\nWhen driving agy from bash at scale, demand machine-readable status:\n\n```\nRespond with ONLY a JSON object (no markdown, no explanation):\n- Success:     {\"status\":\"ok\",\"path\":\"<output_path>\"}\n- Quota error: {\"status\":\"quota_exhausted\",\"reset_seconds\":<N>,\"reset_time\":\"<ISO8601>\"}\n- Other error: {\"status\":\"error\",\"message\":\"<description>\"}\n```\n\nThis is the exact contract `generate.sh` in the inspiration-board pipeline uses\nto loop over 200 styles unattended, with a skip-if-exists guard (file > 100KB).\n````\n\n3. Create `scripts/run-codex-mockups.sh` with exactly this content:\n\n```bash\n#!/bin/bash\n# Fire Codex $imagegen: 9 wildly different website mockups for one subject.\n# Usage: ./scripts/run-codex-mockups.sh \"a landing page for an indie coffee roaster\"\nset -euo pipefail\n\nSUBJECT=\"${1:?usage: $0 \\\"<subject, e.g. a landing page for an indie coffee roaster>\\\"}\"\nDIR=\"$(cd \"$(dirname \"$0\")/..\" && pwd)\"\nmkdir -p \"$DIR/mockups\"\n\n# Extract the first fenced block from the prompt file, substitute the subject.\nPROMPT=\"$(sed \"s/{{SUBJECT}}/$(printf '%s' \"$SUBJECT\" | sed 's/[&/\\]/\\\\&/g')/g\" \"$DIR/prompts/codex-9x-website.md\" \\\n  | awk '/^```/{f++;next} f==1')\"\n\necho \"── codex \\$imagegen → 9 mockups for: $SUBJECT\"\necho \"── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)\"\n\ncd \"$DIR\"\ncodex exec --dangerously-bypass-approvals-and-sandbox \"$PROMPT\"\n```\n\n4. Create `scripts/run-agy-mockups.sh` with exactly this content:\n\n```bash\n#!/bin/bash\n# Fire agy (Google Antigravity CLI): 9 wildly different mobile mockups for one subject.\n# Usage: ./scripts/run-agy-mockups.sh \"a mobile app for selling houses\"\nset -euo pipefail\n\nSUBJECT=\"${1:?usage: $0 \\\"<subject, e.g. a mobile app for selling houses>\\\"}\"\nDIR=\"$(cd \"$(dirname \"$0\")/..\" && pwd)\"\nmkdir -p \"$DIR/mockups\"\n\n# Extract the first fenced block from the prompt file, substitute the subject.\nPROMPT=\"$(sed \"s/{{SUBJECT}}/$(printf '%s' \"$SUBJECT\" | sed 's/[&/\\]/\\\\&/g')/g\" \"$DIR/prompts/agy-9x-mobile.md\" \\\n  | awk '/^```/{f++;next} f==1')\"\n\necho \"── agy generate_image → 9 mobile mockups for: $SUBJECT\"\necho \"── output: $DIR/mockups/mockup-0{1..9}.png (watch mockups/index.html)\"\n\ncd \"$DIR\"\nagy -p \"$PROMPT\" --dangerously-skip-permissions --print-timeout 15m\n```\n\n5. Create `mockups/index.html` with exactly this content (it polls every 5 seconds so tiles fill in live during generation):\n\n```html\n<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>9x Mockup Contact Sheet</title>\n<style>\n  :root { color-scheme: dark; }\n  body { margin: 0; font: 14px/1.4 ui-sans-serif, system-ui; background: #0d0f12; color: #e8e6e1; }\n  header { padding: 20px 24px 8px; display: flex; align-items: baseline; gap: 12px; }\n  h1 { font-size: 18px; margin: 0; letter-spacing: .02em; }\n  header span { color: #8a8f98; font-size: 12px; }\n  .grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; padding: 16px 24px 32px; }\n  figure { margin: 0; background: #16191e; border: 1px solid #262b33; border-radius: 10px; overflow: hidden; }\n  .frame { aspect-ratio: 4 / 3; display: grid; place-items: center; background:\n    repeating-conic-gradient(#14171c 0% 25%, #101318 0% 50%) 50% / 24px 24px; }\n  .frame img { width: 100%; height: 100%; object-fit: cover; display: block; }\n  .frame .empty { color: #4a5058; font-size: 12px; text-align: center; padding: 12px; }\n  figcaption { padding: 8px 12px; color: #b8bdc4; font-size: 12px; display: flex; justify-content: space-between; }\n  figcaption b { color: #e8e6e1; font-weight: 600; }\n  .frame img:hover { cursor: zoom-in; }\n  dialog { border: 0; padding: 0; background: transparent; max-width: 92vw; }\n  dialog img { max-width: 92vw; max-height: 92vh; border-radius: 8px; }\n  dialog::backdrop { background: rgba(0,0,0,.8); }\n</style>\n</head>\n<body>\n<header>\n  <h1>9x Wildly Different Mockups</h1>\n  <span>same subject · nine styles · auto-refreshes every 5s while generating</span>\n</header>\n<div class=\"grid\" id=\"grid\"></div>\n<dialog id=\"zoom\"><img id=\"zoomimg\" alt=\"\"></dialog>\n<script>\n  const grid = document.getElementById('grid');\n  const zoom = document.getElementById('zoom');\n  const zoomimg = document.getElementById('zoomimg');\n  for (let i = 1; i <= 9; i++) {\n    const n = String(i).padStart(2, '0');\n    const fig = document.createElement('figure');\n    fig.innerHTML = `\n      <div class=\"frame\" data-n=\"${n}\"><div class=\"empty\">mockup-${n}.png<br>waiting…</div></div>\n      <figcaption><b>#${n}</b><span class=\"dir\" data-n=\"${n}\"></span></figcaption>`;\n    grid.appendChild(fig);\n  }\n  function tryLoad() {\n    document.querySelectorAll('.frame').forEach(frame => {\n      if (frame.querySelector('img')) return;\n      const n = frame.dataset.n;\n      const img = new Image();\n      img.src = `mockup-${n}.png?t=${Date.now()}`;\n      img.onload = () => {\n        frame.innerHTML = '';\n        frame.appendChild(img);\n        img.addEventListener('click', () => { zoomimg.src = img.src; zoom.showModal(); });\n      };\n    });\n  }\n  zoom.addEventListener('click', () => zoom.close());\n  tryLoad();\n  setInterval(tryLoad, 5000);\n</script>\n</body>\n</html>\n```\n\n6. Make the scripts executable:\n\n```bash\nchmod +x scripts/run-codex-mockups.sh scripts/run-agy-mockups.sh\n```\n\n7. Ask your user for a subject if they haven't given one (one sentence, naming the page type and its content — the subject must stay constant across all 9 mockups). **Warning — confirm before firing:** both scripts launch a paid external agent with sandboxing and approval prompts disabled (`--dangerously-bypass-approvals-and-sandbox` for codex, `--dangerously-skip-permissions` for agy). Show your user the command and make sure they are comfortable with the cost and permissions before running. Then fire a run. Prefer running it in the background and narrating progress; a full run takes several minutes.\n\n```bash\n# website mockups via Codex:\n./scripts/run-codex-mockups.sh \"a landing page for an indie coffee roaster\"\n# OR mobile mockups via agy:\n./scripts/run-agy-mockups.sh \"a mobile app for selling houses\"\n```\n\n## Success check\n\nRun:\n\n```bash\nls mockups/mockup-0*.png\nopen mockups/index.html   # macOS; use xdg-open on Linux\n```\n\nExpected observable result: nine files, `mockups/mockup-01.png` through `mockups/mockup-09.png`, and the gallery page shows nine filled tiles — the same subject rendered in nine different visual styles.\n\nReport to your user: the subject used, the nine style directions the generating agent announced, the success-check output, and anything you had to adapt.\n\n## Notes for agents\n\n- **Codex saves images to the wrong place by default.** Built-in `image_gen` output lands under `$CODEX_HOME/generated_images/`. The prompt explicitly orders a copy into `./mockups/` — if tiles stay empty but the run \"succeeded\", look there and copy manually.\n- **agy's `--print-timeout` defaults to 5 minutes** — too short for 9 images. The run script already passes `--print-timeout 15m`; keep it if you modify the script.\n- **Quota errors are real on agy.** If a run reports `quota_exhausted`, report the reset time to your user instead of retrying silently. For scripted loops, demand the JSON status contract shown at the bottom of `prompts/agy-9x-mobile.md`.\n- **Never go silent.** A prior run stalled without output and the user had to ask \"hello? What is happening?\" — narrate progress after each image, or background the run and poll.\n- **Subject drift ruins comparability.** If a mockup comes back as a different page type, regenerate that one; do not compare it.\n- **Converge afterwards.** When the user picks a winner, rebuild it with: \"mockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at ./winner/index.html, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds.\"\n\n## Attachment: the here-now-workshop-page skill (multi-file)\n\nThe skill that built this page — SKILL.md plus its `templates/` folder, carrying the Elo-voted Instrument Panel theme — is published on this site byte-for-byte. Gotcha: bare `.md` URLs serve here.now's HTML viewer; the two markdown files MUST be fetched with `?raw` (the .html/.css/.js files serve raw bytes as-is):\n\n- https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/SKILL.md?raw\n- https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/agent.md?raw\n- https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/index.html\n- https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/styles.css\n- https://indigo-kayak-2zw8.here.now/skills/here-now-workshop-page/templates/app.js\n\nTo install it in a project: download all five into `./page-skill/here-now-workshop-page/` (keeping the `templates/` subfolder), then run `npx skills add ./page-skill --skill here-now-workshop-page -y` — it copies the whole folder, templates included, into `./.agents/skills/here-now-workshop-page/`. Do NOT stage the download in `./skills/` — the installer treats an existing `./skills/` as an agent's project skill dir and overwrites the staged folder with a symlink, leaving an empty install (verified empirically). The exact command block is on the guide page under \"Attachments — install the page skill\".\n\n---\n\nHuman-readable version of this guide: https://indigo-kayak-2zw8.here.now/\n\nPresentation companions (for humans; no setup steps beyond this file):\n\n- https://indigo-kayak-2zw8.here.now/replay.html — Session Replay: an annotated transcript of the real sessions behind this workflow (diverge → pick with eyes → converge).\n- https://indigo-kayak-2zw8.here.now/dialogue.html — Socratic Dialogue: skeptical Q&A that lands the same prompts where each question demands them."
    },
    {
      "id": "factory-design-variations-questions",
      "slug": "design-variations-questions",
      "title": "Generate to diverge, code to converge — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Planning",
      "tags": [
        "design-variations",
        "questions"
      ],
      "sources": [
        {
          "label": "Generate to diverge, code to converge — questions and tradeoffs",
          "url": "https://indigo-kayak-2zw8.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "07-variations/dialogue.html#The room asks"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 871,
      "url": "/topics/factory-design-variations-questions/",
      "markdownUrl": "/markdown/factory-design-variations-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations-questions.json",
      "headings": [
        {
          "id": "the-room-asks",
          "text": "The room asks",
          "level": 2
        }
      ],
      "markdown": "# Generate to diverge, code to converge — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The room asks\n\nWhy generate images at all? Your agent can write nine real HTML pages.\n\nIt can — at roughly an hour a draft, which is why you normally see three directions before you commit. A bitmap mockup costs about a minute, so nine directions becomes the cheap default, and you can't prefer an option you never saw. Images are for deciding; code is for shipping. Generate to diverge, code to converge. Here's the whole first taste, one paste — fair warning: it launches Codex, a paid agent, with sandboxing and approvals off, so read it and be comfortable with the cost and permissions before you run it:\n\n``` text\nmkdir -p mockups\ncodex exec --dangerously-bypass-approvals-and-sandbox 'Use the $imagegen skill to generate 9 WILDLY different website homepage mockups for a landing page for an indie coffee roaster. The subject stays identical in all 9 - ONLY the visual style varies. One built-in image_gen call per mockup. After each image completes, copy it from $CODEX_HOME/generated_images/ into ./mockups/ as mockup-01.png ... mockup-09.png. Announce progress after each one.'\nls mockups/\n```\n\nWon't “nine wildly different mockups” just give me nine incomparable posters?\n\nOnly if you let the subject drift. The prompt pins the subject — same product, same page type, same rough content — and varies nothing but the style. That turns nine images into a controlled experiment you can read at a glance. This is the exact prompt, verbatim (the agy mobile version is on the [guide](https://indigo-kayak-2zw8.here.now/)):\n\n``` text\nUse the $imagegen skill to generate 9 WILDLY different website homepage mockups\nfor {{SUBJECT}}.\n\nRules:\n- The SUBJECT stays identical in all 9 — same product, same page type\n  (homepage), same rough content (hero, nav, one CTA). ONLY the visual style\n  varies. This is what makes them comparable.\n- Pick 9 maximally divergent directions, e.g.: swiss/international typographic,\n  neo-brutalist, glassmorphic dark, editorial magazine, retro terminal,\n  playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine.\n  Name each direction before generating.\n- One built-in image_gen call per mockup (do NOT drop to the CLI fallback).\n- Desktop aspect, full homepage visible, legible headline text.\n- After each image completes, copy it from $CODEX_HOME/generated_images/\n  into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction\n  order you announced).\n- Announce progress after each one — never go silent.\n- When all 9 exist, list the 9 directions next to their filenames.\n```\n\nAnd if one mockup comes back as a different page type anyway: regenerate it. Don't compare it.\n\nI ran it. The run “succeeded” and my `mockups/` folder is empty. So the model lied?\n\nNo — it saved your images, just not where you looked. Codex's built-in `image_gen` writes to `$CODEX_HOME/generated_images/` by default, which is why the prompt explicitly orders a copy into `./mockups/`. The other classic: agy's `--print-timeout` defaults to five minutes, and nine images take longer — the run script raises it to fifteen. An empty contact sheet means read the run log before blaming the model.\n\nNine tiles and no rubric. How do I “pick with my eyes” honestly?\n\nOpen the contact-sheet gallery — it polls every five seconds, so tiles fill in live while the run generates — and pick the tile you would be embarrassed to lose. If nothing clears that bar, your styles weren't divergent enough: widen the directions and rerun. Never polish the least-bad option.\n\nFine, I picked one. It's a PNG. What do I actually ship?\n\nYou hand the winner back to a coding agent as a reference image. The bitmap decided; the code converges:\n\n``` text\nmockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at\n./winner/index.html, using the image strictly as a visual reference — real\ntext, real layout, no bitmap backgrounds.\n```\n\nReal text, real layout, no bitmap backgrounds — the image is strictly a visual reference.\n\nCute demo. Does it survive contact with 200 images?\n\nThat's exactly what [inspiration-board](https://inspiration-board.pages.dev/variations/01-masonry-grid) is: a bash loop driving the Antigravity CLI across 200 named web-design styles. Scale is mostly error handling — fixed output filenames, a skip-if-exists guard (file already on disk above 100 KB), and machine-readable status demanded from every single run:\n\n``` text\nRespond with ONLY a JSON object (no markdown, no explanation):\n- Success:     {\"status\":\"ok\",\"path\":\"<output_path>\"}\n- Quota error: {\"status\":\"quota_exhausted\",\"reset_seconds\":<N>,\"reset_time\":\"<ISO8601>\"}\n- Other error: {\"status\":\"error\",\"message\":\"<description>\"}\n```\n\nQuota errors are real; a JSON reset time beats a silent retry. And the variations idea applies twice there: the images are style variations, and the gallery pages themselves are twelve layout variations of the same image set.\n\nDo you actually trust this loop for anything real, or is it a workshop trick?\n\nThe page you're reading is the proof. Its theme was picked by this exact loop: wildly different theme candidates rendered over this section's real content, three rounds of Elo voting, 130 recorded votes — and the winner, Instrument Panel, undefeated in both light and dark, became the template for every site in this workshop. The annotated transcript is on the [Session Replay](https://indigo-kayak-2zw8.here.now/replay.html) page.\n\nAnd you can take the winner home: the resulting `here-now-workshop-page` skill is [downloadable and installable from the guide](https://indigo-kayak-2zw8.here.now/#attachments-install-the-page-skill)."
    },
    {
      "id": "factory-design-variations-reference-patterns",
      "slug": "design-variations-reference-patterns",
      "title": "Generate to diverge, code to converge — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Planning",
      "tags": [
        "design-variations",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://indigo-kayak-2zw8.here.now/"
        }
      ],
      "sourceUnits": [
        "07-variations/folio/index.html#Abstract",
        "07-variations/folio/index.html#Notice where design exploration stalls",
        "07-variations/folio/index.html#Test one prompt against nine mockups",
        "07-variations/folio/index.html#Compare fairly: hold the subject constant",
        "07-variations/folio/index.html#Adjust the trick into an unattended pipeline",
        "07-variations/folio/index.html#Choose a winner and converge to real code",
        "07-variations/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 1776,
      "url": "/topics/factory-design-variations-reference-patterns/",
      "markdownUrl": "/markdown/factory-design-variations-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-where-design-exploration-stalls",
          "text": "Notice where design exploration stalls",
          "level": 2
        },
        {
          "id": "test-one-prompt-against-nine-mockups",
          "text": "Test one prompt against nine mockups",
          "level": 2
        },
        {
          "id": "compare-fairly-hold-the-subject-constant",
          "text": "Compare fairly: hold the subject constant",
          "level": 2
        },
        {
          "id": "adjust-the-trick-into-an-unattended-pipeline",
          "text": "Adjust the trick into an unattended pipeline",
          "level": 2
        },
        {
          "id": "choose-a-winner-and-converge-to-real-code",
          "text": "Choose a winner and converge to real code",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Generate to diverge, code to converge — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nEarly design work stalls on the cost of producing options, not on taste. Coding agents that carry an image-generation tool collapse that cost: one prompt can return nine divergent website or mobile mockups in minutes. The results only stay comparable when the subject is held constant and only the visual style varies. With a strict machine-readable status contract, the same pattern runs unattended at two-hundred-style scale, as a deployed gallery project demonstrates. The evidence here covers workflow mechanics from tool contracts, CLI output, pipeline scripts, and prior session records. It does not measure whether any generated direction is aesthetically better — that judgment stays with you.\n\n## Notice where design exploration stalls\n\nYou sit down to design a landing page. The usual move is to build one draft and iterate on it. Each iteration costs an hour or more, so you see perhaps three directions before you commit. The mistake is treating that scarcity as a taste problem. It is a production problem: you cannot prefer an option you never saw.\n\nThe workshop agenda names image generation as a shared capability of current coding agents and treats prototypes as a compounding asset: the more you build, the deeper the well of examples you can pull from (S1). [1](https://indigo-kayak-2zw8.here.now/#note-1)\n\n1\\. The same agenda lists Codex, Grok, and Antigravity as agents that \"can all generate images\" — this section is where that thread gets demonstrated (S1). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-1)\n\nPrior sessions on this machine show the pattern working in practice: one run produced five bitmap mockup directions for a storefront, collected them into a gallery page, and finished within a single sitting (S5).\n\nFrom those records, this folio draws its central inference: when a mockup costs a minute instead of an hour, exploring nine directions becomes the cheap default rather than a luxury.\n\nThe signal to watch in your own work: if you are polishing draft one before you have seen draft five, you are iterating too early. Diverge first.\n\n## Test one prompt against nine mockups\n\nTwo CLIs run this demo. Codex ships an imagegen skill — a packaged instruction set that routes image requests through its built-in `image_gen` tool. The Antigravity CLI (`agy`) exposes a `generate_image` tool the same way. Try both with the same shape of prompt:\n\n``` text\n# Codex: 9 wildly different website mockups\n./scripts/run-codex-mockups.sh \"a landing page for an indie coffee roaster\"\n\n# agy: 9 wildly different mobile mockups\n./scripts/run-agy-mockups.sh \"a mobile app for selling houses\"\n```\n\nBoth scripts expand a prompt that names nine divergent style directions, asks for one image call per mockup, and requires the agent to copy each result into `mockups/` as `mockup-01.png` through `mockup-09.png`. A contact-sheet page in the same folder polls for the files and fills a three-by-three grid as they land.\n\nThe imagegen skill contract lists UI mockups, product mockups, and wireframes as intended uses, prefers the built-in tool over its API fallback, and states that a batch request means one built-in call per asset — not a switch to the CLI path (S2). [2](https://indigo-kayak-2zw8.here.now/#note-2)\n\n2\\. The fallback path exists but is gated: it requires an API key and an explicit user request. For this workflow you never need it (S2). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-2)\n\n| Concern | Codex `$imagegen` | agy (Antigravity) |\n|----|----|----|\n| Non-interactive run | `codex exec \"<prompt>\"` | `agy -p \"<prompt>\"` |\n| Image tool | built-in `image_gen` | `generate_image` (ImageName, Prompt, ImagePaths) |\n| Default output location | `$CODEX_HOME/generated_images/` | agent workspace artifact; copy via `run_command` |\n| Batch rule | one built-in call per asset (S2) | one `generate_image` call per mockup (S4) |\n| Timeout to watch | none specific to images | `--print-timeout`, default 5 minutes (S3) |\n\nTable 1. The two CLI surfaces, side by side. Derived display: reorganized from the imagegen skill contract (S2), `agy --help` output (S3), and pipeline scripts (S4).\n\nCodex saves built-in image output under its own home directory by default, and the skill contract forbids leaving a project-referenced asset there (S2).\n\n**Evidence limit** If your prompt does not say \"copy each image into `./mockups/`\", the run can succeed while your project folder stays empty. The same trap applies to agy's five-minute default print timeout: nine images take longer, so the demo script raises it to fifteen minutes. Watch for an empty contact sheet as the failure signal.\n\nThe test is simple: fire a script, open `mockups/index.html`, and count. Nine tiles filled means the contract held. Fewer means read the run log before blaming the model.\n\n## Compare fairly: hold the subject constant\n\nNine images are only useful if you can compare them. The likely mistake is letting the subject drift with the style — a coffee site in one tile, a coffee app in the next. Then differences in appeal tell you nothing about the style, because two variables changed at once.\n\nThe gallery pipeline enforces this discipline explicitly: a shared subject file defines one fixed cast of seven characters plus a prompt suffix appended to every style prompt, \"so you can compare how each visual approach handles\" the same material (S4).\n\nA prior session applied the same rule to product work: mock up one constant subject — a mobile app for selling houses — once per visual style, varying nothing else (S5). [3](https://indigo-kayak-2zw8.here.now/#note-3)\n\n3\\. That session's record also captures a stronger prompt pattern: each style prompt opens with \"STYLE IS PARAMOUNT\" and demands the image be instantly recognizable as that style (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-3)\n\nWeak judgment says \"make nine cool designs.\" Strong judgment says \"same homepage, same hero, same call to action — nine styles.\" The first gives you nine incomparable posters. The second gives you a controlled experiment you can read at a glance.\n\nPractice it now: before you run the script, write your subject as one sentence and check that it names the page type and its content. If any mockup back changes the page type, regenerate that one — do not compare it.\n\n## Adjust the trick into an unattended pipeline\n\nNine mockups is a live demo. Two hundred is a pipeline, and the difference is error handling. The inspiration-board project — the deployed gallery this workshop shows off — generates its images by driving the Antigravity CLI from a bash loop, one style at a time.\n\nIts generator script demands a machine-readable status from every run: plain JSON, no markdown, one of three shapes (S4).\n\n``` text\n// Success\n{\"status\": \"ok\", \"path\": \"<output_path>\"}\n// Quota exhausted\n{\"status\": \"quota_exhausted\", \"reset_seconds\": 3600, \"reset_time\": \"<ISO8601>\"}\n// Anything else\n{\"status\": \"error\", \"message\": \"<description>\"}\n```\n\nThe same script controls filenames by passing a fixed image name per style, copies each artifact to a predictable path, and skips any output that already exists above a size threshold, so interrupted runs resume instead of restarting (S4). [4](https://indigo-kayak-2zw8.here.now/#note-4)\n\n4\\. The skip guard is one line: if the file exists and exceeds 100 KB, print SKIP and return. Cheap idempotence is what lets a quota-limited loop run for days (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-4)\n\nThe instruction suffix also closes escape hatches: on quota errors the agent must return JSON immediately, and it may not reach for scripts, external APIs, downloads, or any workaround (S4).\n\nScale evidence: the web-design category alone carries 200 named styles with full prompts in its styles file and roughly as many generated images beside it, with sibling categories for app design, branding, editorial, and more (S4).\n\nA prior batch run stalled silently mid-generation, and the operator had to ping the session to ask what was happening; the recorded lesson was to run each image as its own background job and to narrate progress (S5).\n\n**Evidence limit** The quota-handling and skip-guard evidence comes from one project's scripts driving one CLI. The sources do not establish that other agents fail the same way, or how often quota errors occur — only how this pipeline survives them.\n\nWhen your own loop grows past a handful of images, adjust in this order: fixed output names first, skip-if-exists second, JSON status third, background jobs with progress lines fourth. Each step has a visible test — rerun the loop and watch it skip, resume, or report instead of stalling.\n\n## Choose a winner and converge to real code\n\nThe mockups are bitmaps. They are for deciding, not shipping. The loop closes when you pick one tile and hand it back to a coding agent as a reference image.\n\nA prior session shows the full arc: five generated mockup directions went into a gallery page, one winner was selected, and that winner was rebuilt \"as actual HTML/CSS instead of an image-backed\" page (S5).\n\nThe follow-up prompt is one sentence: \"Rebuild `mockup-07.png` as a real single-file HTML/CSS page, using the image strictly as a visual reference — real text, real layout, no bitmap backgrounds.\" Generate to diverge; code to converge.\n\nThe variations idea applies twice in the inspiration-board project. The images are style variations, and the gallery pages themselves are twelve layout variations rendering the same image set (S4). [5](https://indigo-kayak-2zw8.here.now/#note-5)\n\n5\\. The masonry page even hardcodes its own public URL as a prompt base, so a visitor can copy any style straight into their own agent session (S4). [↩](https://indigo-kayak-2zw8.here.now/#note-ref-5)\n\n- 01 masonry grid\n- 02 infinite scroll\n- 03 carousel slider\n- 04 lightbox thumbnails\n- 05 compare split\n- 06 magazine editorial\n- 07 filmstrip preview\n- 08 table list\n- 09 mood board\n- 10 fullscreen slideshow\n- 11 grouped categories\n- 12 search-first\n\n**Figure 1.** The twelve gallery layout variations shipped by the inspiration-board project. Derived display: transcribed from the project's variations directory listing (S4); the live masonry page at inspiration-board.pages.dev returned HTTP 200 when checked in the observed snapshot.\n\nYour decision rule: pick the tile you would be embarrassed to lose. If no tile clears that bar, the styles were not divergent enough — widen the directions and rerun, rather than polishing the least-bad option.\n\n## Practical action\n\nNext time a design has no direction, run this sequence in the demo project. Write one constant-subject sentence. Fire `run-codex-mockups.sh` for the website and `run-agy-mockups.sh` for mobile, each in its own pane. Open the contact sheet and wait for nine tiles per run. Success signal: filenames `mockup-01.png` through `mockup-09.png` exist and every tile shows the same subject in a different style. If a run stalls, check the agent's log for a quota status and its reset time before retrying. Then choose one winner and issue the converge prompt to rebuild it as real HTML/CSS. If nothing wins, widen the style directions and regenerate — do not iterate on a weak favorite."
    },
    {
      "id": "factory-design-variations-worked-example",
      "slug": "design-variations-worked-example",
      "title": "Generate to diverge, code to converge — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Planning",
      "tags": [
        "design-variations",
        "examples"
      ],
      "sources": [
        {
          "label": "Generate to diverge, code to converge — worked example",
          "url": "https://indigo-kayak-2zw8.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "07-variations/replay.html#Act 1 — Diverge: ten styles, one subject",
        "07-variations/replay.html#Act 2 — Pick with your eyes, converge as code",
        "07-variations/replay.html#Act 3 — The same loop chose this page's theme",
        "07-variations/replay.html#The artifact those sessions distilled"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 976,
      "url": "/topics/factory-design-variations-worked-example/",
      "markdownUrl": "/markdown/factory-design-variations-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-design-variations-worked-example.json",
      "headings": [
        {
          "id": "act-1-diverge-ten-styles-one-subject",
          "text": "Act 1 — Diverge: ten styles, one subject",
          "level": 2
        },
        {
          "id": "act-2-pick-with-your-eyes-converge-as-code",
          "text": "Act 2 — Pick with your eyes, converge as code",
          "level": 2
        },
        {
          "id": "act-3-the-same-loop-chose-this-page-s-theme",
          "text": "Act 3 — The same loop chose this page's theme",
          "level": 2
        },
        {
          "id": "the-artifact-those-sessions-distilled",
          "text": "The artifact those sessions distilled",
          "level": 2
        }
      ],
      "markdown": "# Generate to diverge, code to converge — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## Act 1 — Diverge: ten styles, one subject\n\nYou\n\nGive me 10 current popular web design styles.\n\nAgent\n\nReturned ten named style directions — the menu for the batch run.\n\nYou can't have taste about options you never saw. Naming the directions first is what makes the batch comparable later.\n\nYou\n\nFor each of these styles: Use \\$imagegen to mock up a mobile app for selling houses in a background thread.\n\nAgent\n\nFired the generations as background jobs. The built-in `image_gen` tool saved every result under `$CODEX_HOME/generated_images/` — not the project — so each finished image had to be copied into the workspace.\n\nTwo rules are already visible: the subject stays constant (a mobile app for selling houses — only the style varies), and the default save path is a trap the prompt has to handle.\n\nYou\n\nhello? What is happening?\n\nAgent\n\nThe batch had gone silent mid-run. It was still generating — but nothing said so. The session summary recorded the fix as an explicit preference: run each image generation as its own background job, and announce progress after every image.\n\nThat ping is why every prompt on this page now ends with \"Announce progress after each one — never go silent.\"\n\n## Act 2 — Pick with your eyes, converge as code\n\nYou\n\nUse the \\$imagegen skill, passing the `./refs/*` files as references so output is guided by the actual styles.\n\nAgent\n\nGenerated five bitmap mockup directions, copied them into `mockups/`, and built a gallery `index.html` that opened them side by side — a contact sheet.\n\nThe contact sheet is the decision instrument. This project's version polls every 5 seconds, so tiles fill in live while the run is still generating.\n\nYou\n\nmock-03 is the winner. Rebuild it as actual HTML/CSS instead of an image-backed page.\n\nAgent\n\nBuilt the winner as a real page — real text, real layout, no bitmap backgrounds. Diverge, pick, converge: the full loop, one session.\n\nImage generation explores; code generation commits. Neither replaces the other.\n\n## Act 3 — The same loop chose this page's theme\n\nThe candidates don't have to be images. A later session pointed the exact same workflow at this page's own design — wildly different page themes as the variations, Elo votes as the eyes. The lab lives in this project (`template-lab/`, votes in `votes*.jsonl`, outcome in `RESULTS.md`).\n\nAgent\n\nStood up a local template lab: 8 wildly different themes rendered over this section's real content, paired into duels you arrow-key through, every vote appended to a JSONL file. Round 2 widened it to 12 themes (top 3 survivors + 9 new directions) under Elo pairing — 88 votes across two sessions:\n\n``` text\nRound 2 final standings (Elo, session 1 / session 2)\n 1  V09 Gallery (Luxe × Brutalist)   1115 / 1047\n 2  V13 Functionalist (Rams/Braun)   1055 / 1063\n 3  V06 Luxe Minimal                 1035 / 1000\n …\n12  V16 Riso Print                    880 /  936\nHead-to-head: Gallery over Functionalist, 4–2 → Gallery shipped\n```\n\nSame discipline as the mockups: subject held constant (the real page content), only the style varies, and the picking is done with eyes — one duel at a time.\n\nYou\n\nThese are all WAAAAY too similar.\n\nA refinement round had produced near-clones of the winner. Verdict recorded in the lab's RESULTS.md — near-clones can't be voted on, exactly the way nine same-ish posters can't be compared.\n\nAgent\n\nRebuilt the round from scratch: 12 structurally distinct dialects on an oklch token system with variable system fonts, duels alternating light and dark, win-loss tracked per mode. 30 votes later:\n\n``` text\nRound 3b standings (30 votes, light/dark alternating)\n 1  N02 Instrument Panel   1063   light 2-0   dark 2-0\n 2  N08 Type Specimen      1048   light 0-1   dark 4-0\n 3  N10 Chip Bar           1017   light 3-0   dark 0-2\n 4  N00 Gallery (shipped)  1016   light 3-1   dark 0-1\n```\n\nInstrument Panel — the only theme undefeated in both modes — became the canonical template for every site in this workshop. The page you are reading is wearing the winner.\n\n## The artifact those sessions distilled\n\nEvery lesson above, folded into one liftable prompt. Replace `{{SUBJECT}}` and keep it constant across all nine — \"announce progress\" traces to the silent stall, the copy-out-of-`$CODEX_HOME` rule traces to the empty project folder, and \"WILDLY different\" traces to the too-similar round that broke the vote.\n\n``` text\nUse the $imagegen skill to generate 9 WILDLY different website homepage mockups\nfor {{SUBJECT}}.\n\nRules:\n- The SUBJECT stays identical in all 9 — same product, same page type\n  (homepage), same rough content (hero, nav, one CTA). ONLY the visual style\n  varies. This is what makes them comparable.\n- Pick 9 maximally divergent directions, e.g.: swiss/international typographic,\n  neo-brutalist, glassmorphic dark, editorial magazine, retro terminal,\n  playful memphis, luxury minimal, bento-grid dashboard, hand-drawn zine.\n  Name each direction before generating.\n- One built-in image_gen call per mockup (do NOT drop to the CLI fallback).\n- Desktop aspect, full homepage visible, legible headline text.\n- After each image completes, copy it from $CODEX_HOME/generated_images/\n  into ./mockups/ as mockup-01.png ... mockup-09.png (match the direction\n  order you announced).\n- Announce progress after each one — never go silent.\n- When all 9 exist, list the 9 directions next to their filenames.\n```\n\nWhen your eyes have picked, converge:\n\n``` text\nmockup-0N.png is the winner. Rebuild it as a real single-file HTML/CSS page at\n./winner/index.html, using the image strictly as a visual reference — real\ntext, real layout, no bitmap backgrounds.\n```\n\nThe full setup — both run scripts, the agy mobile version, and the live-updating contact-sheet gallery — is on the [guide](https://indigo-kayak-2zw8.here.now/), mirrored for machines in [agent.md](https://indigo-kayak-2zw8.here.now/agent.md).\n\nThe winning theme itself ships too: the `here-now-workshop-page` skill that built this page is [downloadable and installable from the guide](https://indigo-kayak-2zw8.here.now/#attachments-install-the-page-skill)."
    },
    {
      "id": "codex-goals",
      "slug": "goals",
      "title": "Keep notes private and goals verifiable",
      "summary": "Agent-heavy work creates a lot of half-formed context: dictated notes, failed prompts, benchmark ideas, security worries, skill candidates, and \"try this later\" scraps.",
      "category": "Planning",
      "tags": [
        "goals",
        "proof",
        "skills"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#goals"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/The Move",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Notes Become Goals",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Long Agent Work Needs Intervals",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Understanding Becomes Proof Design",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Ask For Lists, Not Comfort",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Treat Public Skills As Candidates",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Force Known Context",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Copyable Artifact: Goal Packet",
        "src/content/final/chunk-13-keep-notes-local-make-goals-verifiable.md#Keep Notes Local, Make Goals Verifiable/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#goals",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 1212,
      "url": "/topics/codex-goals/",
      "markdownUrl": "/markdown/codex-goals.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-goals.json",
      "headings": [
        {
          "id": "the-move",
          "text": "The Move",
          "level": 2
        },
        {
          "id": "notes-become-goals",
          "text": "Notes Become Goals",
          "level": 2
        },
        {
          "id": "long-agent-work-needs-intervals",
          "text": "Long Agent Work Needs Intervals",
          "level": 2
        },
        {
          "id": "understanding-becomes-proof-design",
          "text": "Understanding Becomes Proof Design",
          "level": 2
        },
        {
          "id": "ask-for-lists-not-comfort",
          "text": "Ask For Lists, Not Comfort",
          "level": 2
        },
        {
          "id": "treat-public-skills-as-candidates",
          "text": "Treat Public Skills As Candidates",
          "level": 2
        },
        {
          "id": "force-known-context",
          "text": "Force Known Context",
          "level": 2
        },
        {
          "id": "copyable-artifact-goal-packet",
          "text": "Copyable Artifact: Goal Packet",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Keep notes private and goals verifiable\n\nAgent-heavy work creates a lot of half-formed context: dictated notes, failed prompts, benchmark ideas, security worries, skill candidates, and \"try this later\" scraps.\n\nDo not commit that pile. Keep scratch private, ignored, and temporary until it **earns its way into a goal**.\n\n```text\nprivate scratch note\n-> reviewed goal packet\n-> bounded agent work\n-> proof scenario\n-> saved evidence\n-> next goal\n```\n\n## The Move\n\nUse a project-local scratch space for messy notes and a **reviewed goal packet** for actual work.\n\nLocal conventions such as `.notes/` and `.goals/` can work well when they are globally ignored and treated as private workspace files. The names are not important. The boundary is.\n\n> Notes is just kind of like the junk, or the research, or whatever. Goals are the things I can feed into the model to produce work.\n>\n> — John Lindquist\n\n- Scratch notes are not documentation.\n- Goals are not wish lists.\n- A note is where messy thinking lands.\n- A goal is what survives review and becomes work.\n\n## Notes Become Goals\n\nA goal packet is a reviewed project-local work item that turns scratch notes into bounded agent work, names the proof scenario, and records what counts as done.\n\nExample:\n\n```text\nScratch note:\nCheckout submit stayed disabled after selecting shipping.\n\nGoal:\nFind the smallest cause of the disabled checkout submit state.\n\nLikely areas:\n- checkout form state\n- shipping selection reducer\n- submit button disabled logic\n\nProof:\n- reproduce failing state\n- add or run component test\n- run checkout smoke test\n- capture before/after result\n\nStop if:\n- payment-provider adapter must change\n- no reproducible failing state exists\n```\n\nPrivate notes stay private. Sanitized patterns can become docs later.\n\n## Long Agent Work Needs Intervals\n\nTreat long agent runs as **interval work**.\n\nSet an explicit check-in interval before launch. Leave the agent with a stop rule and proof requirement. Step away. Come back to inspect evidence, not vibes.\n\nField rule:\n\n```text\nIf the agent has a bounded goal and a proof command,\nstep away until the interval ends.\nWatching the terminal harder does not make the benchmark finish.\n```\n\nGood launch shape:\n\n```text\nStart a migration lane with:\n- allowed files\n- files to avoid\n- verification command\n- check-in interval\n- stop condition\n\nReturn when:\n- the timer fires\n- the agent reports blocked\n- the proof command finishes\n- a boundary conflict appears\n```\n\n**AFK does not mean unsupervised merge.** It means the work unit is bounded enough that the human can leave and return to concrete evidence.\n\n## Understanding Becomes Proof Design\n\nYou still need judgment. What changes is the unit of understanding.\n\n> The best you can hope for is understanding the scenarios that prove the code works the way you expect it to.\n>\n> — John Lindquist\n\nThe useful unit is no longer \"I have read every line.\" The useful unit is \"I know the scenario, the boundary, and the evidence that prove this behavior.\"\n\nExamples:\n\n| Task | Proof Scenario | Evidence | Does Not Prove |\n|---|---|---|---|\n| Checkout disabled state | Shipping selected, submit enables | Component test, smoke test | Every payment-provider state |\n| Billing retry | Duplicate event processed once | Fixture, idempotency test, log | All provider outage modes |\n| Auth/session rotation | Stale session rejected safely | Security test, route check | Every browser/session store |\n| Performance change | Same fixture before/after | Benchmark output | Production latency |\n\n**Proof scenarios are how codebase understanding stays grounded** when code is moving quickly.\n\n## Ask For Lists, Not Comfort\n\nAvoid vague reassurance prompts:\n\n```text\nAre you sure?\nIs this correct?\nWhy did this work?\n```\n\nAsk for structured reasons instead:\n\n```text\nDo not reassure me.\n\nList 5 reasons this proof actually covers the checkout disabled-state bug.\nFor each reason, include:\n- the behavior it checks\n- the evidence source\n- what it does not prove\n- one way this could still be wrong\n```\n\nMore useful prompts:\n\n```text\nList 5 ways this benchmark could be misleading.\n```\n\n```text\nList 7 security assumptions this auth/session change depends on.\n```\n\n```text\nList 4 reasons the smoke test covers the regression, then list 4 gaps it leaves open.\n```\n\nAgents are good at sounding certain. **Lists force certainty to expose its assumptions.**\n\n## Treat Public Skills As Candidates\n\nPublic skills are **supply-chain inputs**. Evaluate before installing.\n\nFor a software task, search with multiple terms instead of one narrow phrase.\n\nExample task:\n\n```text\nImprove accessibility checks for a Svelte checkout flow.\n```\n\nSearch terms:\n\n```text\naccessibility audit\na11y test\nSvelte accessibility\nPlaywright axe\nWCAG checker\nkeyboard navigation\nscreen reader smoke test\nARIA validation\nform accessibility\ncontrast checker\n```\n\nThen ask a model council or **[Oracle](https://github.com/johnlindquist/oracle)** to compare candidates:\n\n```text\nCompare candidate skills for this task.\n\nFor each candidate:\n- what it claims to do\n- source/repo/package origin\n- maintenance signals\n- install or execution risk\n- whether it reads project files\n- whether it runs code\n- what useful prompt or function can be extracted without installing\n- recommendation: install / adapt / reject\n```\n\nReading a skill is not the same as trusting it. Installing it is a separate decision.\n\n## Force Known Context\n\nIf the relevant files, constraints, stack, or proof command are already known, put them directly in the prompt. **Search should fill unknowns, not rediscover known facts.**\n\nWeak:\n\n```text\nFind the right skill and fix checkout.\n```\n\nBetter:\n\n```text\nWe use SvelteKit.\nThe failing path is /checkout.\nThe bug is submit disabled after shipping selection.\nDo not touch the payment provider adapter.\nThe proof is the checkout component test plus billing smoke test.\nSearch for skills only if they help inspect this exact scenario.\n```\n\n## Copyable Artifact: Goal Packet\n\n```text\nScratch source:\n- note id or summary:\n- why this matters now:\n\nGoal:\n- what should be true when this is done:\n\nKnown context:\n- repo area:\n- likely files:\n- constraints:\n- files/tools to avoid:\n\nAgent work:\n- first inspection step:\n- allowed edits:\n- stop conditions:\n\nProof scenario:\n- user path or system behavior:\n- test:\n- smoke check:\n- benchmark:\n- security check:\n- debug/log evidence:\n\nReason list required:\nAsk the agent to list:\n- 5 reasons this proof covers the goal\n- 5 gaps this proof leaves open\n- 3 assumptions that could make the result wrong\n\nPacing:\n- check-in interval:\n- what to inspect when returning:\n\nSkill evaluation, if needed:\n- 10 search terms:\n- candidate skills:\n- Oracle/Fusion comparison saved?\n- source scraped/read before install?\n- useful parts extracted?\n- install decision: install / adapt / reject\n\nCompletion:\n- evidence attached:\n- remaining uncertainty:\n- next goal created:\n```\n\n## Claim Boundaries\n\nDo not share private note contents, global ignore files, local config, machine paths, usernames, or private skill contents.\n\nDo not claim a model council can guarantee supply-chain safety. It can compare candidates and surface risk. The install decision still belongs to the human and the repo owner.\n\nDo not claim developers no longer need to understand code. The narrower claim is stronger: understanding should be grounded in proof scenarios.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#goals)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-prompt-composition-reference",
      "slug": "prompt-composition-reference",
      "title": "Prompt Builder composition and handoff: practical reference",
      "summary": "Prompt Builder setup and reference covering installation and binary identity, interactive and stdin composition, launch inspection, named Codex threads, safe final-argument handoffs, fork/compact wrappers, composer controls, file and skill lookup, slash…",
      "category": "Planning",
      "tags": [
        "prompt-builder",
        "prompts",
        "preflight"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Install And Identity Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Basic Use",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Inspection Modes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Stdin Plus Prefill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Conversation Naming",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Handoff Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Handoff Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Compose Before Fork Or Compact",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/`@` File Selector",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/Skills Lookup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/Slash Commands",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/`p` Is Missing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Wrong Version Runs",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Wrong Codex Binary Runs",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Empty Prompt Rejected",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Named Thread Did Not Happen",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Shell Function Handoff Fails",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Quoting Looks Scary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Fork/Compact Options Do Nothing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Variation Seed Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 3369,
      "url": "/topics/codex-prompt-composition-reference/",
      "markdownUrl": "/markdown/codex-prompt-composition-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-prompt-composition-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "install-and-identity-check",
          "text": "Install And Identity Check",
          "level": 2
        },
        {
          "id": "basic-use",
          "text": "Basic Use",
          "level": 2
        },
        {
          "id": "inspection-modes",
          "text": "Inspection Modes",
          "level": 2
        },
        {
          "id": "stdin-plus-prefill",
          "text": "Stdin Plus Prefill",
          "level": 2
        },
        {
          "id": "conversation-naming",
          "text": "Conversation Naming",
          "level": 2
        },
        {
          "id": "handoff-mode",
          "text": "Handoff Mode",
          "level": 2
        },
        {
          "id": "handoff-options",
          "text": "Handoff Options",
          "level": 2
        },
        {
          "id": "compose-before-fork-or-compact",
          "text": "Compose Before Fork Or Compact",
          "level": 2
        },
        {
          "id": "composer-affordances",
          "text": "Composer Affordances",
          "level": 2
        },
        {
          "id": "file-selector",
          "text": "`@` File Selector",
          "level": 3
        },
        {
          "id": "skills-lookup",
          "text": "Skills Lookup",
          "level": 3
        },
        {
          "id": "slash-commands",
          "text": "Slash Commands",
          "level": 3
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "p-is-missing",
          "text": "`p` Is Missing",
          "level": 3
        },
        {
          "id": "wrong-version-runs",
          "text": "Wrong Version Runs",
          "level": 3
        },
        {
          "id": "wrong-codex-binary-runs",
          "text": "Wrong Codex Binary Runs",
          "level": 3
        },
        {
          "id": "empty-prompt-rejected",
          "text": "Empty Prompt Rejected",
          "level": 3
        },
        {
          "id": "named-thread-did-not-happen",
          "text": "Named Thread Did Not Happen",
          "level": 3
        },
        {
          "id": "shell-function-handoff-fails",
          "text": "Shell Function Handoff Fails",
          "level": 3
        },
        {
          "id": "quoting-looks-scary",
          "text": "Quoting Looks Scary",
          "level": 3
        },
        {
          "id": "fork-compact-options-do-nothing",
          "text": "Fork/Compact Options Do Nothing",
          "level": 3
        },
        {
          "id": "variation-seed-prompt",
          "text": "Variation Seed Prompt",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Prompt Builder composition and handoff: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up Prompt Builder and its zsh helper wiring on this machine. Do setup and verification only; do not modify Prompt Builder source, create new skills, or launch Codex prompts.\n\nStep 1: Locate or install Prompt Builder.\nIf a local checkout of https://github.com/johnlindquist/prompt-builder exists, inspect `README.md`, `src/cli.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, and `src/app_server_launch.rs`, then install from that checkout:\n  cargo install --path . --locked --force\nIf no checkout exists, clone it first. If `cargo` is missing, stop and report that blocker.\n\nStep 2: Verify `prompt-builder` and `p` identity.\nRun:\n  which -a prompt-builder p\n  prompt-builder --version\n  p --version\nConfirm both commands resolve to the intended install location and report the same version. `p` must be a real executable or symlink, not only an interactive shell alias.\nIf `prompt-builder` exists but `p` is missing, run:\n  ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\n  hash -r 2>/dev/null || true; rehash 2>/dev/null || true\nThen repeat the identity and version checks.\n\nStep 3: Verify print, dry-run, and launch inspection modes.\nRun:\n  p --print-prompt \"Review checkout saved payment method regressions.\"\n  p --dry-run --print-command \"Review the failing billing webhook test and identify the smallest patch.\"\n  p --print-launch-json \"Review auth/session architecture.\" | jq '.mode, .command, .argv, .env, .prompt'\n  p --submit --dry-run --print-command \"Verify submit dry-run.\"\nConfirm the prompt is preserved, the command preview is sane, `argv` is structured, and no accidental shell splitting appears.\n\nStep 4: Verify app-server named threads and `CODEX_THREAD_NAME`.\nRun:\n  p --print-launch-json --name \"Auth rotation review\" \"Review auth/session architecture.\" | jq '.mode, .env, .app_server'\nConfirm `mode` is `app-server-named-thread`, `env` includes `CODEX_THREAD_NAME` with the current directory basename plus the requested name, and the app-server flow includes `thread/name/set`.\n\nStep 5: Verify handoff mode and final argv safety.\nRun:\n  p --print-launch-json --handoff-command /bin/echo \"fix this\nkeep \\$HOME literal\" | jq '.mode, .argv'\nConfirm `mode` is `handoff`, the composed prompt is the final `argv` element, and `$HOME`, spaces, quotes, semicolons, pipes, and newlines remain literal prompt text. Treat `Command::arg` behavior as the contract; do not add shell eval to wrappers.\n\nStep 6: Verify handoff options only in handoff mode.\nRun:\n  p --print-launch-json \\\n    --handoff-command /bin/echo \\\n    --handoff-arg wrapper \\\n    --fork-from last \\\n    --compact \\\n    --launch-option \"trace=--trace-app-server\" \\\n    \"continue from here\" | jq '.handoff, .argv'\nConfirm the ordering is command, static handoff args, enabled toggle args, then final prompt.\n\nStep 7: Wire and verify zsh helpers.\nInspect `zsh/conf.d/40-ai.zsh` and confirm it contains wiring for `p-f`, `p-c`, `p-cm`, `xfl`, `xfc`, `_p_handoff_zsh`, and `_codex_prompt_builder_fork`.\nVerify the loaded helper functions:\n  zsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\nEach helper should resolve as a function.\nConfirm the intended behavior:\n  p-f composes in `p`, then forks from the selected or current source.\n  p-c composes in `p`, then forks, compacts, and resumes.\n  p-cm composes in `p`, then compact-forks from conversation `m`.\n  xfl forks immediately with an already-obvious prompt.\n  xfc forks, compacts, and resumes immediately.\nUse `zsh -lc` with explicit sourcing for handoffs to shell functions because a normal subprocess cannot directly run those functions.\n\nStep 8: Prove one helper handoff shape with a dry run.\nRun:\n  p --submit --dry-run --print-command \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n    --handoff-arg xfc \\\n    \"continue from this compact fork\"\nConfirm the prompt is still the final argv element before the fork runs.\n\nStep 9: Respect privacy boundaries.\nDo not print full `env`. Do not copy private shell config, full Codex config, secret helper files, API variables, cookies, tokens, private endpoints, or key-resolving startup output. Use narrow command output only. For safe binary override checks, prefer:\n  PROMPT_BUILDER_CODEX_BIN=/bin/echo p --submit --dry-run --print-command \"hello override\"\n\nStep 10: Report results.\nReturn a concise setup report with:\n  - files inspected or changed\n  - resolved paths for `prompt-builder` and `p`\n  - matching version output\n  - named-thread JSON evidence for `mode`, `CODEX_THREAD_NAME`, and `thread/name/set`\n  - handoff JSON evidence that the prompt is the final argv element\n  - zsh helper `whence -w` evidence\n  - any skipped or failed step with the exact failing command and output\n```\n\n## Big Idea\n\nPrompt Builder is the terminal prompt composer at <https://github.com/johnlindquist/prompt-builder>.\nIt opens a small TUI for composing, naming, inspecting, and handing a prompt to Codex or a wrapper command.\n\nUse it as the preflight step before a prompt launches Codex, a fork, a compact, or a wrapper command.\n\n## Try This Now\n\nPreview one software prompt before launching it:\n`p --print-launch-json \"Debug the checkout saved-payment regression and name the first verification command.\" | jq '.mode, .argv, .prompt'`\nSubmit only after the final argv and prompt text match what you intend.\n\nThe practical question is:\n\n```text\nWhat exactly am I about to send, where will it run, and what launch shape will it use?\n```\n\nUse Prompt Builder when the prompt needs to be deliberate before the agent gets authority to work in a repo.\n\n```text\ncompose -> inspect -> name -> preview launch -> submit deliberately\n```\n\n## Files To Inspect\n\nLocal helper file:\n\n```text\nzsh/conf.d/40-ai.zsh\n```\n\nInside the Prompt Builder checkout:\n\n```text\nREADME.md\nsrc/cli.rs\nsrc/app.rs\nsrc/composer_input.rs\nsrc/file_search.rs\nsrc/skill_popup.rs\nsrc/slash_commands.rs\nsrc/handoff.rs\nsrc/launch_manifest.rs\nsrc/app_server_launch.rs\n```\n\nMain commands:\n\n```bash\nprompt-builder\np\n```\n\n`p` is the short command. It should resolve to the same installed binary as `prompt-builder`.\n\n## When To Reach For This\n\nUse Prompt Builder when:\n\n- a checkout-flow implementation prompt needs file references and constraints\n- a billing webhook fix should fork from the right Codex session\n- an auth/session architecture review needs a named thread\n- a failing test investigation needs pasted output plus a careful instruction\n- a wrapper needs the prompt as the final argument\n- you want to inspect the prompt, command, or launch JSON before launch\n- routing has selected the right session and you still need to compose the right prompt\n- a controlled-variation run needs one deliberate base prompt\n\nSkip it when the prompt is tiny and obvious:\n\n```bash\nxfl \"continue with the smallest safe patch\"\n```\n\nUse it when you need time to compose:\n\n```bash\np-f\np-c\np-cm\n```\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nTyping directly into Codex or a fork command is enough if the idea is clear.\n```\n\nWhat the workflow gives you now:\n\n```text\nPrompt Builder lets you compose first, inspect the exact prompt and launch\nshape, then submit once the request is specific enough to trust.\n```\n\nWhat you used to expect:\n\n```text\nThe latest Codex session is probably the right one.\n```\n\nWhat the workflow gives you now:\n\n```text\nRouting chooses the session. Prompt Builder shapes the prompt before the fork,\ncompact, or wrapper runs.\n```\n\n## The Mental Model\n\nPrompt Builder sits between intent and execution.\n\n```text\nhuman intent\n-> Prompt Builder composer\n-> exact prompt text\n-> optional name\n-> launch preview\n-> direct Codex / named thread / handoff wrapper\n```\n\nThree launch paths matter:\n\n| Mode | What Happens | Use When |\n| --- | --- | --- |\n| direct Codex | `codex ... <prompt>` | no name, no wrapper |\n| named thread | create thread, call `thread/name/set`, resume thread | you pass `--name` |\n| handoff | call another command with prompt as final argv | `p-f`, `p-c`, wrappers |\n\nPrompt Builder owns composition and launch metadata. Wrappers own repo-specific behavior such as fork, compact, resume, and cmux tab naming.\n\n## Install And Identity Check\n\nStart with the binary check:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nWhat to look for:\n\n- both commands resolve\n- both resolve to the intended install location\n- both report the same version\n- `p` is not just an interactive-only alias\n\nIf working from a local Prompt Builder checkout, install durably:\n\n```bash\ncargo install --path . --locked --force\n```\n\nIf `p` is missing but `prompt-builder` exists:\n\n```bash\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\nwhich -a prompt-builder p\np --version\n```\n\n## Basic Use\n\nOpen the interactive composer:\n\n```bash\np\n```\n\nLong form:\n\n```bash\nprompt-builder\n```\n\nPrefill the composer:\n\n```bash\np \"Debug the checkout flow failing test and propose the smallest safe fix.\"\n```\n\nSubmit noninteractively:\n\n```bash\nprintf 'Debug the billing webhook duplicate-processing bug.\\n' | p --submit\n```\n\nSafer first pass:\n\n```bash\nprintf 'Debug the billing webhook duplicate-processing bug.\\n' \\\n  | p --submit --dry-run --print-command\n```\n\nUse `--submit` only when the prompt has already been composed by you or a trusted script.\n\n## Inspection Modes\n\nUse inspection modes before launch.\n\n| Need | Command |\n| --- | --- |\n| exact prompt text | `p --print-prompt \"hello\"` |\n| human-readable command preview | `p --dry-run --print-command \"hello\"` |\n| script-readable launch manifest | `p --print-launch-json \"hello\"` |\n| rehearse submit without launch | `p --submit --dry-run --print-command \"hello\"` |\n\nPrint the prompt:\n\n```bash\np --print-prompt \\\n  \"Review the checkout flow for saved payment method regressions.\"\n```\n\nPrint the command:\n\n```bash\np --dry-run --print-command \\\n  \"Review the failing billing webhook test and identify the smallest patch.\"\n```\n\nWhat to look for:\n\n- expected command\n- expected cwd from `-C`\n- prompt appears as one quoted argument\n- no accidental shell splitting\n\nPrint launch JSON:\n\n```bash\np --print-launch-json \\\n  \"Review the auth/session architecture before refresh-token rotation.\"\n```\n\nUseful fields:\n\n```text\nmode\ncommand\nargv\nenv\nprompt\n```\n\nFor scripts, prefer JSON over parsing shell-quoted command text.\n\n## Stdin Plus Prefill\n\nPrompt Builder can combine prefilled text and stdin.\n\n```bash\nprintf 'failing test output here\\n' \\\n  | p --stdin --print-prompt \\\n  \"Use this test output to debug the checkout flow.\"\n```\n\nGood software workflow:\n\n```bash\npnpm test checkout -- --runInBand 2>&1 \\\n  | p --stdin --print-prompt \\\n  \"Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked.\"\n```\n\nFor a diff review:\n\n```bash\ngit diff -- src/checkout src/billing \\\n  | p --stdin --print-prompt \\\n  \"Review this diff for bugs, missing tests, and risky behavior changes.\"\n```\n\n## Conversation Naming\n\nUse `--name` when the work should create a named Codex thread.\n\n```bash\np --name \"Checkout saved payment methods\"\n```\n\nNoninteractive preview:\n\n```bash\np --submit --dry-run --name \"Checkout saved payment methods\" \\\n  \"Plan the first shippable slice.\"\n```\n\nPrompt Builder prefixes the submitted name with the current working directory basename:\n\n```text\ncwd basename: shop-app\nname: Checkout saved payment methods\nCODEX_THREAD_NAME: shop-app:Checkout saved payment methods\n```\n\nWhat to know:\n\n- the name is not just text inside the prompt\n- default named launches use Codex app-server\n- Prompt Builder creates a thread, calls `thread/name/set`, then resumes the thread with the prompt\n- handoff mode passes `CODEX_THREAD_NAME` to the child command environment\n\nConfirm named mode:\n\n```bash\np --print-launch-json \\\n  --name \"Auth rotation review\" \\\n  \"Review auth/session architecture.\" \\\n  | jq '.mode, .env, .app_server'\n```\n\nWhat to look for:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n## Handoff Mode\n\nUse handoff mode when Prompt Builder should compose first, then call another command.\n\nBasic handoff preview:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command /bin/echo \\\n  \"hello handoff\"\n```\n\nAdd static handoff args:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --handoff-arg before-launch \\\n  \"hello handoff\"\n```\n\nImportant rule:\n\n```text\nThe composed prompt is passed with Command::arg as the safe final argv element.\nIt is not shell-evaluated.\n```\n\nPrompt text with spaces, newlines, quotes, `$HOME`, semicolons, or pipes stays prompt text.\n\nConfirm with JSON:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix this\nand keep \\$HOME literal\" \\\n  | jq '.mode, .argv'\n```\n\nWhat to look for:\n\n- mode is `handoff`\n- prompt is the final argv element\n- `$HOME` stays literal inside the prompt value\n\n## Handoff Options\n\nThese options become wrapper toggles when `--handoff-command` is present:\n\n```text\n--fork-from\n--compact\n--launch-option\n```\n\nExample:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  --launch-option \"trace=--trace-app-server\" \\\n  \"continue from here\" \\\n  | jq '.handoff, .argv'\n```\n\nExpected ordering:\n\n```text\n<command> <handoff args> <enabled toggle args> <final prompt>\n```\n\nIf `--fork-from`, `--compact`, or `--launch-option` are used without `--handoff-command`, they are ignored for default Codex launch.\n\n## Compose Before Fork Or Compact\n\nRouting gets work to the right Codex session. Prompt Builder composes the prompt before that routed action runs.\n\n| Helper | Use It When |\n| --- | --- |\n| `xfl` | fork now with an already-obvious prompt |\n| `xfc` | fork, compact, and resume now |\n| `p-f` | compose in `p`, then fork from the selected/current source |\n| `p-c` | compose in `p`, then fork, compact, and resume |\n| `p-cm` | compose in `p`, then compact-fork from conversation `m` |\n\nConfirm the helpers:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\n```\n\nInspect the package copy:\n\n```bash\nrg -n 'p-f|p-c|p-cm|xfl|xfc|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh\n```\n\nConceptual shape:\n\n```text\np-f\n-> p\n-> compose prompt\n-> handoff to zsh -lc\n-> source 40-ai.zsh\n-> _codex_prompt_builder_fork --fork-from <source> <prompt>\n```\n\nCompact shape:\n\n```text\np-c\n-> p\n-> compose prompt\n-> handoff to zsh -lc\n-> source 40-ai.zsh\n-> _codex_prompt_builder_fork --fork-from <source> --compact <prompt>\n```\n\nWhy `zsh -lc` is there:\n\n```text\n`p-f`, `p-c`, `xfl`, and `xfc` are zsh functions in common setups.\nA normal subprocess cannot run a shell function unless zsh loads the file that defines it.\n```\n\n## Composer Affordances\n\nPrompt Builder mirrors the important parts of the Codex composer so editing habits stay consistent.\n\n| Action | Behavior |\n| --- | --- |\n| `Enter` | submit |\n| `Shift+Enter` | insert newline |\n| bracketed paste | pasted text arrives as a paste event |\n| large paste | visible placeholder, full text restored on submit |\n| `Ctrl+C` with draft text | clear current draft |\n| `Ctrl+C` on empty draft | quit |\n| `@` | file selector |\n| `$` | skills lookup |\n| `/` at prompt start | slash command popup |\n| `Tab` | move between Name, Prompt, and options |\n| `Space` on an option | toggle wrapper option |\n\n### `@` File Selector\n\nOpen:\n\n```bash\np\n```\n\nType:\n\n```text\nReview @\n```\n\nSelect the file instead of typing the path from memory.\n\nGood prompts:\n\n```text\nReview @src/checkout/CheckoutForm.tsx for saved payment method regressions.\n```\n\n```text\nUse @src/billing/webhook.ts and @tests/billing/webhook.test.ts to debug duplicate invoice processing.\n```\n\n### Skills Lookup\n\nType:\n\n```text\n$\n```\n\nUse skills when the prompt should invoke a known local workflow instead of retyping every step.\n\nExample:\n\n```text\nUse $oracle-packx to review the auth/session architecture before refresh-token rotation.\n```\n\n### Slash Commands\n\nSlash commands are structured verbs. Put them at the beginning of the prompt.\n\n```text\n/review\n/plan\n/compact\n```\n\n## Ask The Agent This\n\nDebug a checkout-flow prompt before launch:\n\n```text\nUse Prompt Builder as the preflight boundary.\n\nI want to implement saved payment methods in checkout. Help me compose a prompt\nfor `p --print-prompt` first. It should reference the likely checkout files,\ncall out invariants, name tests to run, and ask for the smallest shippable slice.\nDo not launch Codex until the prompt and launch shape have been inspected.\n```\n\nUse a named auth review:\n\n```text\nCreate a Prompt Builder command for an auth/session architecture review.\n\nUse `--name`, show the `--print-launch-json` command, and confirm the launch\nmode uses `app-server-named-thread` with `thread/name/set`. The prompt should\nask for risks, migration steps, and verification commands.\n```\n\nDebug handoff quoting:\n\n```text\nA Prompt Builder handoff to a wrapper is splitting the prompt.\n\nInspect the `--print-launch-json` argv. Confirm the prompt is the final argv\nelement. If the wrapper re-splits it, fix the wrapper rather than adding shell\neval. Use `Command::arg` behavior as the contract.\n```\n\nConnect routed fork:\n\n```text\n`Esc+P` routed to the correct Codex session and launched `p-f`.\n\nInspect how `p-f` uses Prompt Builder, `--handoff-command zsh`, `--handoff-arg`,\n`--fork-from`, and `40-ai.zsh`. Show the dry-run command that proves the prompt\nwill be the final argv element before the fork runs.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| correct binary | `which -a prompt-builder p` shows intended paths |\n| version match | `prompt-builder --version` and `p --version` match |\n| local install updated | `cargo install --path . --locked --force` succeeds |\n| exact prompt saved | `p --print-prompt ... > file` and `test -s file` |\n| command preview sane | `p --dry-run --print-command ...` shows expected command |\n| launch JSON sane | `p --print-launch-json ...` has expected `mode`, `argv`, `env` |\n| named thread | JSON mode is `app-server-named-thread` |\n| thread name | JSON env includes `CODEX_THREAD_NAME` |\n| handoff safe | JSON mode is `handoff` and prompt is last argv |\n| zsh helpers available | `zsh -lc 'source ...40-ai.zsh; whence -w p-f p-c xfl xfc'` |\n| variation seed ready | saved base prompt is non-empty and has invariants |\n\n## If It Goes Wrong\n\n### `p` Is Missing\n\nCheck:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nLikely causes:\n\n- `prompt-builder` is installed but `p` symlink is missing\n- `p` is only an alias in an interactive shell\n- PATH changed after install\n\nFix shape:\n\n```bash\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\nhash -r 2>/dev/null || true\nrehash 2>/dev/null || true\nwhich -a prompt-builder p\np --version\n```\n\n### Wrong Version Runs\n\nCheck all matches:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nIf working from the local checkout:\n\n```bash\ncargo install --path . --locked --force\nwhich -a prompt-builder p\np --version\n```\n\n### Wrong Codex Binary Runs\n\nInspect:\n\n```bash\np --dry-run --print-command \"hello\"\n```\n\nOverride for a safe demo:\n\n```bash\nPROMPT_BUILDER_CODEX_BIN=/bin/echo \\\n  p --submit --dry-run --print-command \\\n  \"hello override\"\n```\n\nOr pass the binary explicitly:\n\n```bash\np --codex-bin /bin/echo --submit --dry-run --print-command \"hello\"\n```\n\n### Empty Prompt Rejected\n\nCheck producer output:\n\n```bash\nproducer_command | tee /tmp/prompt-builder-input.txt\ntest -s /tmp/prompt-builder-input.txt && echo \"input:OK\"\n```\n\nThen:\n\n```bash\np --stdin --print-prompt < /tmp/prompt-builder-input.txt\n```\n\n### Named Thread Did Not Happen\n\nCheck mode:\n\n```bash\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env, .app_server'\n```\n\nWhat to look for:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n### Shell Function Handoff Fails\n\nSymptom:\n\n```text\nxfc: command not found\n```\n\nBad shape:\n\n```bash\np --handoff-command xfc\n```\n\nBetter shape:\n\n```bash\np \\\n  --handoff-command zsh \\\n  --handoff-arg -lc \\\n  --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n  --handoff-arg xfc\n```\n\nDry-run:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command zsh \\\n  --handoff-arg -lc \\\n  --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n  --handoff-arg xfc \\\n  \"continue from this compact fork\"\n```\n\n### Quoting Looks Scary\n\nUse launch JSON instead of guessing from shell text:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix checkout\nkeep \\$HOME literal\ndo not shell-eval this\" \\\n  | jq '.argv'\n```\n\nWhat to look for:\n\n- the prompt is one JSON string\n- it is the final argv element\n- shell metacharacters remain text\n\nIf a wrapper splits the final argument, fix the wrapper.\n\n### Fork/Compact Options Do Nothing\n\nCause:\n\n```text\n--fork-from, --compact, and --launch-option only matter in handoff mode.\n```\n\nCheck:\n\n```bash\np --print-launch-json --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nFix:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --fork-from last \\\n  --compact \\\n  \"continue\" \\\n  | jq '.mode, .argv'\n```\n\n## Variation Seed Prompt\n\nA useful variation seed has:\n\n- a concrete software goal\n- invariants that must not change\n- one variable dimension\n- verification command\n- output path or comparison criteria\n\nExample:\n\n```bash\nRUN_ID=\"billing-webhook-variations\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT/prompts\" \"$ROOT/launch\"\n\np --print-prompt \\\n  \"Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk.\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \\\n  \"Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk.\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\n## References And Resources\n\n- Prompt Builder command: `prompt-builder`\n- Prompt Builder repo: <https://github.com/johnlindquist/prompt-builder>\n- Short command: `p`\n- Zsh helper file: `zsh/conf.d/40-ai.zsh`\n- Prompt Builder checkout files: `README.md`, `src/cli.rs`, `src/main.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, `src/app_server_launch.rs`, `src/composer_input.rs`\n- Local install command from Prompt Builder checkout: `cargo install --path . --locked --force`\n- Useful debug env var: `PROMPT_BUILDER_CODEX_BIN`\n- Useful key debug env var: `PROMPT_BUILDER_DEBUG_KEYS`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-prompt-composition-practice",
      "slug": "prompt-composition-practice",
      "title": "Prompt Builder composition and handoff: practice drills",
      "summary": "Sixteen exercises cover Prompt Builder identity and installation, prompt/command/JSON inspection, stdin composition, named threads, argument-safe handoffs, zsh wrappers, file and skill selection, launch toggles, binary overrides, debugging,…",
      "category": "Planning",
      "tags": [
        "prompt-builder",
        "prompts",
        "preflight",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 1: Identity Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 2: Print A Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 3: Compare Prompt, Command, And Launch JSON",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 4: Stdin Plus Prefill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 5: Named Thread Manifest",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 6: Handoff Final Arg",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 7: Handoff With Newlines And Quotes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 8: Shell Function Handoff",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 9: Map `xfl` / `xfc` To `p-f` / `p-c`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 10: File Selector Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 11: Skills And Slash Commands Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 12: Preview Wrapper Toggles",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 13: Override The Codex Binary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 14: Debug A Broken Prompt Builder Flow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 15: Create A Section 6 Seed Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/05-prompt-builder.md#Exercises: 05. Prompt Builder/Exercise 16: Write A Better Implementation Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "planning",
      "wordCount": 1581,
      "url": "/topics/codex-prompt-composition-practice/",
      "markdownUrl": "/markdown/codex-prompt-composition-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-prompt-composition-practice.json",
      "headings": [
        {
          "id": "exercise-1-identity-check",
          "text": "Exercise 1: Identity Check",
          "level": 2
        },
        {
          "id": "exercise-2-print-a-prompt",
          "text": "Exercise 2: Print A Prompt",
          "level": 2
        },
        {
          "id": "exercise-3-compare-prompt-command-and-launch-json",
          "text": "Exercise 3: Compare Prompt, Command, And Launch JSON",
          "level": 2
        },
        {
          "id": "exercise-4-stdin-plus-prefill",
          "text": "Exercise 4: Stdin Plus Prefill",
          "level": 2
        },
        {
          "id": "exercise-5-named-thread-manifest",
          "text": "Exercise 5: Named Thread Manifest",
          "level": 2
        },
        {
          "id": "exercise-6-handoff-final-arg",
          "text": "Exercise 6: Handoff Final Arg",
          "level": 2
        },
        {
          "id": "exercise-7-handoff-with-newlines-and-quotes",
          "text": "Exercise 7: Handoff With Newlines And Quotes",
          "level": 2
        },
        {
          "id": "exercise-8-shell-function-handoff",
          "text": "Exercise 8: Shell Function Handoff",
          "level": 2
        },
        {
          "id": "exercise-9-map-xfl-xfc-to-p-f-p-c",
          "text": "Exercise 9: Map `xfl` / `xfc` To `p-f` / `p-c`",
          "level": 2
        },
        {
          "id": "exercise-10-file-selector-drill",
          "text": "Exercise 10: File Selector Drill",
          "level": 2
        },
        {
          "id": "exercise-11-skills-and-slash-commands-drill",
          "text": "Exercise 11: Skills And Slash Commands Drill",
          "level": 2
        },
        {
          "id": "exercise-12-preview-wrapper-toggles",
          "text": "Exercise 12: Preview Wrapper Toggles",
          "level": 2
        },
        {
          "id": "exercise-13-override-the-codex-binary",
          "text": "Exercise 13: Override The Codex Binary",
          "level": 2
        },
        {
          "id": "exercise-14-debug-a-broken-prompt-builder-flow",
          "text": "Exercise 14: Debug A Broken Prompt Builder Flow",
          "level": 2
        },
        {
          "id": "exercise-15-create-a-section-6-seed-prompt",
          "text": "Exercise 15: Create A Section 6 Seed Prompt",
          "level": 2
        },
        {
          "id": "exercise-16-write-a-better-implementation-prompt",
          "text": "Exercise 16: Write A Better Implementation Prompt",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Prompt Builder composition and handoff: practice drills\n\nThese exercises practice composing, inspecting, naming, and handing off prompts before launching agents.\n\nUse a real software project when possible. Prefer dry-runs and print modes until the prompt is specific enough to submit.\n\n## Exercise 1: Identity Check\n\nRun:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nFill out:\n\n```markdown\n# Prompt Builder Identity\n\n- `prompt-builder` path:\n- `p` path:\n- versions match? yes/no\n- expected install location:\n- action needed:\n```\n\nIf working from a local Prompt Builder checkout, run:\n\n```bash\ncargo install --path . --locked --force\nwhich -a prompt-builder p\np --version\n```\n\n## Exercise 2: Print A Prompt\n\nCreate a prompt for a real software task.\n\n```bash\nmkdir -p artifacts/prompt-builder\n\np --print-prompt \\\n  \"Review the checkout flow for saved payment method regressions. Identify the smallest safe implementation slice and the tests to run.\" \\\n  > artifacts/prompt-builder/checkout.prompt.md\n\ntest -s artifacts/prompt-builder/checkout.prompt.md && echo \"prompt:OK\"\ncat artifacts/prompt-builder/checkout.prompt.md\n```\n\nFill out:\n\n```markdown\n# Printed Prompt\n\n- command:\n- output path:\n- prompt non-empty? yes/no\n- software goal:\n- files or subsystems named:\n- verification command named:\n- one improvement before launch:\n```\n\n## Exercise 3: Compare Prompt, Command, And Launch JSON\n\nRun:\n\n```bash\nmkdir -p artifacts/prompt-builder\n\np --print-prompt \"hello checkout\" \\\n  > artifacts/prompt-builder/hello.prompt.txt\n\np --dry-run --print-command \"hello checkout\" \\\n  > artifacts/prompt-builder/hello.command.txt\n\np --print-launch-json \"hello checkout\" \\\n  > artifacts/prompt-builder/hello.launch.json\n\ncat artifacts/prompt-builder/hello.prompt.txt\ncat artifacts/prompt-builder/hello.command.txt\njq '.mode, .command, .argv, .env, .prompt' artifacts/prompt-builder/hello.launch.json\n```\n\nFill out:\n\n```markdown\n# Inspection Mode Comparison\n\n| Mode | What It Shows | When To Use |\n| --- | --- | --- |\n| `--print-prompt` | | |\n| `--print-command` | | |\n| `--print-launch-json` | | |\n| `--dry-run` | | |\n\n- direct launch mode:\n- final argv:\n- prompt value:\n```\n\n## Exercise 4: Stdin Plus Prefill\n\nRun a small stdin test:\n\n```bash\nprintf 'failing test output\\nline two\\n' \\\n  | p --stdin --print-prompt \\\n  \"Debug this checkout test failure.\" \\\n  > artifacts/prompt-builder/stdin-prefill.prompt.md\n\ncat artifacts/prompt-builder/stdin-prefill.prompt.md\n```\n\nThen try with a project command:\n\n```bash\npnpm test checkout -- --runInBand 2>&1 \\\n  | p --stdin --print-prompt \\\n  \"Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked.\" \\\n  > artifacts/prompt-builder/checkout-test.prompt.md\n```\n\nFill out:\n\n```markdown\n# Stdin Plus Prefill\n\n- prefill instruction:\n- stdin producer:\n- separator present? yes/no\n- final prompt starts with:\n- final prompt includes command output? yes/no\n- would you submit this as-is? yes/no\n- what to trim or add:\n```\n\n## Exercise 5: Named Thread Manifest\n\nRun:\n\n```bash\np --print-launch-json \\\n  --name \"Billing webhook review\" \\\n  \"Review duplicate billing webhook processing and propose the smallest safe fix.\" \\\n  > artifacts/prompt-builder/named-thread.launch.json\n\njq '.mode, .env, .app_server' artifacts/prompt-builder/named-thread.launch.json\n```\n\nFill out:\n\n```markdown\n# Named Thread Manifest\n\n- mode:\n- `CODEX_THREAD_NAME`:\n- app-server create method:\n- app-server name method:\n- where `thread/name/set` appears:\n- why this is different from direct Codex launch:\n```\n\n## Exercise 6: Handoff Final Arg\n\nRun:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  \"fix this and keep \\$HOME literal\" \\\n  > artifacts/prompt-builder/handoff.launch.json\n\njq '.mode, .handoff, .argv' artifacts/prompt-builder/handoff.launch.json\n```\n\nFill out:\n\n```markdown\n# Handoff Final Arg\n\n- mode:\n- command:\n- static handoff args:\n- toggled args:\n- final argv element:\n- does `$HOME` stay literal? yes/no\n- why `Command::arg` matters:\n- shell eval used? yes/no\n```\n\n## Exercise 7: Handoff With Newlines And Quotes\n\nRun:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"Fix the billing webhook.\nKeep \\\"invoice paid\\\" idempotent.\nDo not shell-eval \\$HOME or pipes | here.\" \\\n  > artifacts/prompt-builder/handoff-multiline.launch.json\n\njq '.argv' artifacts/prompt-builder/handoff-multiline.launch.json\n```\n\nFill out:\n\n```markdown\n# Multiline Handoff\n\n- number of argv elements:\n- final argv element contains newlines? yes/no\n- final argv element contains quotes? yes/no\n- final argv element contains `$HOME` literally? yes/no\n- what would break if a wrapper re-split the final argument:\n```\n\n## Exercise 8: Shell Function Handoff\n\nProve the functions exist when the zsh helper file is sourced:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\n```\n\nThen preview a handoff to `xfc`:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command zsh \\\n  --handoff-arg -lc \\\n  --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n  --handoff-arg xfc \\\n  \"Continue from this compact fork and focus only on the failing checkout test.\"\n```\n\nFill out:\n\n```markdown\n# Zsh Function Handoff\n\n- sourced file:\n- function called:\n- why `zsh -lc` is required:\n- prompt position:\n- dry-run command:\n- what would fail with `--handoff-command xfc`:\n```\n\n## Exercise 9: Map `xfl` / `xfc` To `p-f` / `p-c`\n\nInspect:\n\n```bash\nrg -n 'xfl|xfc|p-f|p-c|p-cm|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh\n```\n\nFill out:\n\n```markdown\n# Section 4 To Section 5 Bridge\n\n| Helper | Direct action or compose-first? | Fork? | Compact? | Uses Prompt Builder? |\n| --- | --- | --- | --- | --- |\n| `xfl` | | | | |\n| `xfc` | | | | |\n| `p-f` | | | | |\n| `p-c` | | | | |\n| `p-cm` | | | | |\n\n- when to use `xfl`:\n- when to use `xfc`:\n- when to use `p-f`:\n- when to use `p-c`:\n```\n\n## Exercise 10: File Selector Drill\n\nOpen:\n\n```bash\np\n```\n\nType:\n\n```text\nReview @\n```\n\nSelect a file from the popup. Use a project example such as:\n\n```text\nReview @src/checkout/CheckoutForm.tsx for saved payment method regressions.\n```\n\nFill out:\n\n```markdown\n# @ File Selector\n\n- cwd:\n- selected path:\n- why this path matters:\n- did the inserted path match the real file? yes/no\n- why selecting beats typing from memory:\n```\n\n## Exercise 11: Skills And Slash Commands Drill\n\nOpen:\n\n```bash\np\n```\n\nTry the skills popup:\n\n```text\n$\n```\n\nThen try a slash command at the prompt start:\n\n```text\n/re\n```\n\nAccept `/review`.\n\nFill out:\n\n```markdown\n# Composer Vocabulary\n\n- skill mention inserted:\n- slash command inserted:\n- what triggered skills:\n- what triggered slash commands:\n- why slash commands belong at the prompt start:\n- what `Shift+Enter` does:\n- what `Ctrl+C` does with text:\n- what `Ctrl+C` does when empty:\n```\n\n## Exercise 12: Preview Wrapper Toggles\n\nRun:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  --launch-option \"trace=--trace-app-server\" \\\n  --launch-option \"debug=--debug\" \\\n  \"Continue the auth/session review.\" \\\n  > artifacts/prompt-builder/toggles.launch.json\n\njq '.handoff.enabled_launch_options, .argv' artifacts/prompt-builder/toggles.launch.json\n```\n\nFill out:\n\n```markdown\n# Wrapper Toggles\n\n- enabled launch options:\n- argv order:\n- where static handoff args appear:\n- where toggle args appear:\n- where prompt appears:\n- why options are ignored without `--handoff-command`:\n```\n\n## Exercise 13: Override The Codex Binary\n\nRun:\n\n```bash\nPROMPT_BUILDER_CODEX_BIN=/bin/echo \\\n  p --submit --dry-run --print-command \\\n  \"hello override\" \\\n  > artifacts/prompt-builder/override-command.txt\n\ncat artifacts/prompt-builder/override-command.txt\n```\n\nFill out:\n\n```markdown\n# Codex Binary Override\n\n- env var:\n- command used:\n- output:\n- why this is useful for safe demos:\n- how to remove the override:\n```\n\n## Exercise 14: Debug A Broken Prompt Builder Flow\n\nPick one failure and write the debug commands.\n\n| Failure | Useful Checks |\n| --- | --- |\n| `p: command not found` | `which -a prompt-builder p`, symlink check |\n| wrong Prompt Builder version | `--version`, `cargo install --path . --locked --force` |\n| wrong Codex binary | `PROMPT_BUILDER_CODEX_BIN`, `--codex-bin`, `--print-command` |\n| named thread missing | `--print-launch-json --name ...`, check `.mode` |\n| `xfc: command not found` | `zsh -lc 'source ...40-ai.zsh; whence -w xfc'` |\n| prompt split into args | `--print-launch-json`, inspect `.argv` |\n| fork/compact ignored | check whether `--handoff-command` is present |\n\nFill out:\n\n```markdown\n# Debug Notes\n\n- failure chosen:\n- first proof command:\n- expected output:\n- likely cause:\n- smallest fix:\n- confirmation command:\n```\n\n## Exercise 15: Create A Section 6 Seed Prompt\n\nUse Prompt Builder to save one deliberate prompt for controlled variations.\n\n```bash\nRUN_ID=\"checkout-seed\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT/prompts\" \"$ROOT/launch\"\n\np --print-prompt \\\n  \"Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes.\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \\\n  \"Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes.\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\nFill out:\n\n```markdown\n# Section 6 Seed\n\n- prompt path:\n- launch JSON path:\n- software goal:\n- invariant 1:\n- invariant 2:\n- variable under test:\n- required verification:\n- ready for controlled variations? yes/no\n- what would make this prompt stronger:\n```\n\n## Exercise 16: Write A Better Implementation Prompt\n\nBad prompt:\n\n```text\nfix checkout\n```\n\nRewrite it for Prompt Builder:\n\n```markdown\nImplement saved payment methods in checkout.\n\nScope:\n- inspect:\n- change:\n- do not change:\n\nConstraints:\n- invariant:\n- security concern:\n- migration concern:\n\nVerification:\n- command:\n- what passing means:\n\nReturn:\n- first shippable slice:\n- files changed:\n- risks:\n```\n\nThen print it:\n\n```bash\ncat artifacts/prompt-builder/better-checkout.prompt.md \\\n  | p --stdin --print-prompt \\\n  \"Use this implementation prompt as the final composed prompt.\" \\\n  > artifacts/prompt-builder/better-checkout.final.prompt.md\n```\n\nFill out:\n\n```markdown\n# Better Prompt Review\n\n- original was weak because:\n- rewritten prompt names files/subsystems? yes/no\n- rewritten prompt names verification? yes/no\n- rewritten prompt limits scope? yes/no\n- final prompt path:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-throwaway-variants-playbook",
      "slug": "throwaway-variants-playbook",
      "title": "Throwaway route variants playbook",
      "summary": "Web developers often need to compare UI directions in the real app, against real routing, styling, auth, responsive behavior, and browser state. Throwaway route variants give an AI agent a concrete way to generate options quickly, prove them in localhost, promote one winner, and remove the experimental surface before it becomes maintenance debt.",
      "category": "Planning",
      "tags": [
        "design.md",
        "source of truth",
        "variants",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#throwaway-variants",
        "scenarios/throwaway-variants.json#audienceFit",
        "toolkit/codex-skills/throwaway-route-variants/SKILL.md",
        "scenarios/throwaway-variants.json#scenarios/0",
        "scenarios/throwaway-variants.json#scenarios/1",
        "scenarios/throwaway-variants.json#scenarios/2",
        "scenarios/throwaway-variants.json#implementationNotes",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/1",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/2",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/3",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/4",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/5",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/6",
        "scenarios/throwaway-variants.json#notTaughtOrAvoid/7",
        "scenarios/throwaway-variants.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "planning",
      "wordCount": 2324,
      "url": "/topics/foundations-throwaway-variants-playbook/",
      "markdownUrl": "/markdown/foundations-throwaway-variants-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-throwaway-variants-playbook.json",
      "headings": [
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "landing-page-direction-sprint",
          "text": "Landing page direction sprint",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "authenticated-onboarding-alternatives",
          "text": "Authenticated onboarding alternatives",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "responsive-dashboard-density-bake-off",
          "text": "Responsive dashboard density bake-off",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "throwaway-route-variants-skill",
          "text": "Throwaway route variants skill",
          "level": 3
        },
        {
          "id": "lesson-04-validated-references",
          "text": "Lesson 04 validated references",
          "level": 3
        },
        {
          "id": "lesson-04-validation-guardrails",
          "text": "Lesson 04 validation guardrails",
          "level": 3
        },
        {
          "id": "lesson-04-interactive-checklist",
          "text": "Lesson 04 interactive checklist",
          "level": 3
        },
        {
          "id": "local-dev-command",
          "text": "Local dev command",
          "level": 3
        },
        {
          "id": "cmux-state-inspection",
          "text": "CMUX state inspection",
          "level": 3
        },
        {
          "id": "cmux-pane-list",
          "text": "CMUX pane list",
          "level": 3
        }
      ],
      "markdown": "# Throwaway route variants playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers often need to compare UI directions in the real app, against real routing, styling, auth, responsive behavior, and browser state. Throwaway route variants give an AI agent a concrete way to generate options quickly, prove them in localhost, promote one winner, and remove the experimental surface before it becomes maintenance debt.\n\n[Core principles](/topics/foundations-source-truth-and-design/)\n\n## Reusable skill\n\nInstall as `~/.agents/skills/throwaway-route-variants/SKILL.md`, then restart Codex.\n\n```markdown\n---\nname: throwaway-route-variants\ndescription: Trigger when exploring UI/layout directions and you want fast comparison without a permanent component catalog — generate several route-level variants in-app, review, keep one, delete the rest. Do NOT use when a maintained design system is required.\n---\n\n# Throwaway route variants\n\nThe anti-Storybook move: generate several route-level UI variants inside the running app, compare them, keep the winner, and DELETE the losers. Favors shipping momentum over a maintained catalog. These variants are explicitly disposable.\n\n## Steps\n\n1. Generate 5 route-level variants of the target UI INSIDE the running app — each variant is its own route (e.g. `/variant-a`, `/variant-b`, ...), not a permanent component.\n\n2. Add simple left/right navigation between the variants so the human can flip through and compare them live.\n\n3. Let the human pick the winner.\n\n4. DELETE the losing routes/variants — do not keep them around as a catalog.\n\n## Guardrails\n- Variants are explicitly disposable; this favors shipping momentum over a maintained component catalog.\n- Do NOT use when a maintained design system / permanent component library is required.\n```\n\n## Scenarios\n\n### Landing page direction sprint\n\n**Role:** As a frontend product engineer working in a Next.js-style marketing app\n\nThe team has a design.md for a new homepage, but the visual direction is still unsettled before a stakeholder review. The app already has shared typography, buttons, cards, and layout primitives, and the developer wants to compare several real routes in localhost instead of asking for more static mockups or setting up Storybook.\n\n> As a frontend product engineer, I want an agent to create disposable homepage route variants from the current code and design.md, so that I can review real browser-rendered options, pick one, and ship without keeping a permanent variant catalog.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill only. First inspect the current routing structure, package.json scripts, existing homepage route, shared components, and design.md if present. Do not trust stale memory about the app structure. Create 5 temporary route-level variants of the homepage inside the app using the existing routing convention, for example /variant-a through /variant-e or the equivalent framework-native paths. Reuse existing components where practical, but keep variant-specific layout/styling isolated to the temporary routes so cleanup is simple. Add simple left/right navigation between variants, including visible Previous/Next controls and keyboard ArrowLeft/ArrowRight handling if that fits the app. Run the repo's actual dev command from package.json, usually npm run dev, pnpm dev, or bun dev. Prove every variant renders in the browser at localhost. After the human chooses a winner, promote only that implementation to the real homepage route, delete every losing variant route and temporary navigation wrapper, then run the relevant lint/typecheck/build command from package.json. Expected output: a short comparison table of the 5 variants, the chosen route, browser proof notes, commands run, and a final git diff summary showing only the promoted implementation remains.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\npackage.json scripts in the target repo\n```\n\n```text\ndesign.md in the target repo if present\n```\n\n```text\napp/page.tsx, pages/index.tsx, src/routes, or the repo's current homepage route discovered by inspection\n```\n\n#### Browser verification\n\nUse the running local dev server as the proof surface. In a CMUX browser pane or normal local browser, open the first temporary route, then use the variant navigation controls or ArrowLeft/ArrowRight to cycle through all variants. If using an agent-browser-style workflow, collect an accessibility snapshot for each route, evaluate window.location.pathname after navigation, and capture screenshots or concise visual notes for the human review.\n\n#### Definition of done\n\n- All temporary routes render successfully in localhost using the repo's real dev command.\n- Browser proof exists for every variant: screenshots, accessibility snapshots, or explicit route-by-route notes with no console-blocking runtime errors.\n- The selected variant is promoted to the real homepage route.\n- All losing route variants and temporary navigation scaffolding are deleted.\n- The final diff does not leave behind a Storybook-like catalog, hidden demo routes, or unused variant components.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent creates polished variants but leaves all 5 routes in the app. Mitigation: require a final cleanup pass and verify with git diff plus route search for variant-a, variant-b, variant-c, variant-d, and variant-e.\n- Mistake: the agent rewrites shared components so every variant leaks into production styling. Mitigation: keep variant-specific changes route-local until the winner is chosen, then promote deliberately.\n\n### Authenticated onboarding alternatives\n\n**Role:** As a full-stack web developer responsible for signup and first-run onboarding\n\nA SaaS app has a working auth flow, but the post-signup onboarding page feels confusing. The team wants to compare several onboarding layouts in the real authenticated shell without risking the existing auth guard, database writes, or production onboarding state machine.\n\n> As a full-stack web developer, I want an agent to create disposable authenticated onboarding route variants that reuse the current app shell and safe fixture data, so that I can compare real UX options without breaking auth or business logic.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill for UI exploration only. Inspect the current auth guard, onboarding route, layout shell, data-loading pattern, and package.json scripts before editing. Do not change authentication logic, database schema, real onboarding mutations, or production redirects. Create 3 to 5 temporary route-level onboarding variants under a clearly disposable dev-only path, such as /onboarding/variant-a through /onboarding/variant-e or the framework's equivalent. Each variant should reuse the current authenticated shell and existing components, but it may use safe fixture data or read-only mocks when live data would create side effects. Add simple Previous/Next navigation between variants. Run the dev server using the actual package.json script and verify the routes in a browser. If auth is required, document the exact login path or test-user setup needed; do not assume cookies are shared with a browser agent. After the human chooses a winner, promote only that UI to the real onboarding route and delete every temporary variant path. Expected output: route list, auth assumptions, browser verification notes, commands run, cleanup confirmation, and final diff summary.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\nCurrent auth guard and onboarding route discovered from source inspection\n```\n\n```text\npackage.json scripts in the target repo\n```\n\n```text\nExisting app shell/layout components\n```\n\n```text\nExisting onboarding components, forms, and safe fixture or mock-data patterns\n```\n\n#### Browser verification\n\nUse a browser proof that respects auth reality. In a CMUX browser pane or agent-browser-style session, start from the documented login path, click/fill the test login only if the repo provides safe credentials or a local fixture path, then visit each onboarding variant. Capture an accessibility snapshot showing the page heading, primary CTA, progress indicator, and navigation controls. If login is not available, verify the variant routes with a safe mocked/read-only local route and state that authenticated production behavior was not mutated.\n\n#### Definition of done\n\n- Temporary onboarding variants are reachable in the local app without changing auth guards or production redirects.\n- Each variant has browser proof showing the authenticated shell or clearly documented safe mock shell.\n- No database schema, mutation path, or real onboarding state transition is changed for the experiment.\n- The selected UI is promoted to the real onboarding route after human selection.\n- All temporary onboarding variant routes and navigation wrappers are removed.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent makes the variant work by weakening the auth guard. Mitigation: explicitly forbid auth changes and require the final diff to show no auth-guard or session-validation edits unless the human requested them separately.\n- Mistake: the agent assumes the browser agent has the developer's cookies. Mitigation: require an explicit login path, safe test account instructions, or a read-only mock route for browser proof.\n\n### Responsive dashboard density bake-off\n\n**Role:** As a senior frontend engineer cleaning up a dense admin dashboard\n\nA dashboard route has grown cluttered after several feature additions. Product wants to compare a compact data-heavy layout, a guided summary layout, and a card-based layout before committing to a redesign. The current code has real components and data boundaries that should be treated as source of truth.\n\n> As a senior frontend engineer, I want an agent to generate disposable dashboard route variants using the current code as source of truth, so that I can compare density, hierarchy, and responsive behavior in-browser before replacing the real dashboard route.\n\n#### Agent brief\n\n```text\nUse the throwaway-route-variants skill. Inspect the current dashboard route, layout components, data-fetching boundaries, responsive utilities, and package.json scripts. Create exactly 3 temporary dashboard route variants: one compact/data-dense, one guided/summary-first, and one card-based. Keep data access read-only and preserve existing component contracts. Add simple left/right navigation among the 3 variants. Run the local dev server with the actual package.json command, then verify desktop and narrow viewport behavior in a browser. Do not create Storybook stories, a permanent examples directory, or a dashboard variant gallery. After human selection, promote the winner to the real dashboard route and delete the 3 temporary routes. Expected output: variant intent summary, browser proof at desktop and mobile/narrow viewport, commands run, selected winner, and cleanup proof from git diff or route search.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n```text\nCurrent dashboard route discovered from source inspection\n```\n\n```text\nCurrent shared dashboard/card/table/chart components\n```\n\n```text\npackage.json scripts in the target repo\n```\n\n#### Browser verification\n\nUse browser verification because layout density and responsiveness cannot be proven from source alone. In a CMUX browser pane, local browser, Playwright-backed check, or agent-browser-style workflow, open each temporary dashboard route at a desktop width and a narrow mobile-like width. Use evaluate to record viewport width and current pathname, take screenshots or visual notes, and verify that Previous/Next navigation reaches all three variants without a runtime error.\n\n#### Definition of done\n\n- Three route-level dashboard variants exist temporarily and match the requested density directions.\n- Desktop and narrow-viewport browser proof is captured for all variants.\n- Existing data contracts remain read-only and stable during the experiment.\n- Only the selected dashboard implementation remains after cleanup.\n- A final route search or git diff proves temporary variants were removed.\n\n#### Failure modes and mitigations\n\n- Mistake: the agent judges responsiveness from code without opening the browser. Mitigation: require viewport-based browser proof for every variant before selection.\n- Mistake: the agent turns route variants into a permanent demo gallery. Mitigation: define the routes as disposable from the start and require post-selection deletion as part of done.\n\n## Implementation notes\n\n- Start by inspecting the live repo. Routing conventions, package scripts, app shell, auth boundaries, and component names must come from current code, not memory.\n- Make the temporary routes obvious and searchable. Names like variant-a, variant-b, and variant-c are boring on purpose because cleanup is easier.\n- Keep variant-specific implementation route-local until the winner is selected. Promote only the winning idea into the real route after review.\n- Browser proof matters for this technique. A successful typecheck is not enough when the decision is visual hierarchy, flow, density, responsive behavior, or auth-shell fit.\n- The final cleanup is not optional. The technique only works if the losing variants are deleted instead of becoming a second design system.\n- When an authenticated browser proof is needed, spell out the login/test-user path or use safe local fixture data. Do not assume a browser agent has access to the developer's existing cookies.\n\n## Boundaries and caveats\n\n- Do not build or recommend a full Storybook-style maintained catalog for these experiments.\n- Do not keep rejected variants as hidden routes, examples, or future inspiration unless the human explicitly asks for a maintained catalog.\n- Do not rely on stale project memory when route structure or implementation details matter.\n- Do not scrape or copy existing websites as design source material; the taught design workflow used generated visual inspiration and design.md.\n- Do not introduce removed this workflow items as implementation requirements: Codex Sandbox and Approvals, AGENTS.md, Impeccable, Beads, Chrome DevTools MCP, or Deep Wiki Map.\n- Do not use YOLO, skip-trust, or approval-bypass aliases as part of this playbook.\n- Do not present large-context snapshots as the proven route-variant workflow; in this lesson they were framed as a possible escape hatch, not the demonstrated technique.\n\n## Agent reference map\n\n### Throwaway route variants skill\n\nPrimary workflow contract for this topic: generate route-level variants in the running app, add simple navigation, let the human pick, then delete losers.\n\n[Open reference](/topics/foundations-throwaway-variants-playbook/)\n\n### Lesson 04 validated references\n\nGrounding source for the taught concepts: code as source of truth, design.md from generated inspiration, and disposable route variants.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Lesson 04 validation guardrails\n\nUse this to avoid reintroducing tools and claims that were removed as only mentioned or not taught in this section.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Lesson 04 interactive checklist\n\nUseful for the implementation shape: prompt the agent to inspect current files, generate route-level variants, review in browser, promote one, and delete temporary routes.\n\n[Open reference](/topics/foundations-source-truth-and-design/)\n\n### Local dev command\n\nThe agent should inspect the target repo and run the real dev, lint, typecheck, and build scripts rather than guessing commands.\n\n```text\npackage.json\n```\n\n### CMUX state inspection\n\nWhen working in CMUX, the agent can inspect the current pane/workspace before opening or using browser/terminal panes for proof.\n\n```text\ncmux --json tree\n```\n\n### CMUX pane list\n\nUse when coordinating a terminal pane running the dev server and a browser pane used for route review.\n\n```text\ncmux list-panes\n```"
    },
    {
      "id": "foundations-source-truth-and-design",
      "slug": "source-truth-and-design",
      "title": "Trust current source and capture design decisions",
      "summary": "Tell the difference between basic memory and dangerous stale memory; Treat code as the source of truth with million-token snapshot contexts; Capture a design.md standard and generate multi-route structural variants.",
      "category": "Planning",
      "tags": [
        "design.md",
        "source of truth",
        "variants"
      ],
      "sources": [
        {
          "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#04/objectives",
        "oracle/04-references.json#recap",
        "oracle/04-references.json#concepts/0",
        "oracle/04-references.json#concepts/1",
        "oracle/04-references.json#concepts/2",
        "oracle/04-references.json#concepts/3",
        "oracle/04-references.json#concepts/4",
        "oracle/04-references.json#references",
        "oracle/04-references.json#recommendations",
        "oracle/04-interactive.json#intro",
        "oracle/04-interactive.json#checklist",
        "oracle/04-interactive.json#challenges",
        "oracle/04-interactive.json#quiz",
        "oracle/04-interactive.json#reflect",
        "oracle/04-references.json#goDeeper",
        "materials/exercises.md#Chunk-04",
        "materials/qa-index.md#Q015",
        "materials/qa-index.md#Q016",
        "materials/qa-index.md#Q017",
        "materials/qa-index.md#Q018",
        "materials/keyframes.md#Chunk-04",
        "lesson-04.html#resource-packet",
        "lesson-04.html#clip-map",
        "lesson-04.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "planning",
      "wordCount": 2458,
      "url": "/topics/foundations-source-truth-and-design/",
      "markdownUrl": "/markdown/foundations-source-truth-and-design.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-source-truth-and-design.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "code-as-the-source-of-truth",
          "text": "Code as the Source of Truth",
          "level": 3
        },
        {
          "id": "lightweight-markdown-memory",
          "text": "Lightweight Markdown Memory",
          "level": 3
        },
        {
          "id": "large-context-snapshots-as-a-possible-escape-hatch",
          "text": "Large-Context Snapshots as a Possible Escape Hatch",
          "level": 3
        },
        {
          "id": "design-md-from-generated-inspiration",
          "text": "Design.md from Generated Inspiration",
          "level": 3
        },
        {
          "id": "throwaway-route-variants",
          "text": "Throwaway Route Variants",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "inspiration-board",
          "text": "Inspiration Board",
          "level": 3
        },
        {
          "id": "codex-cli",
          "text": "Codex CLI",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "stale-memory-audit",
          "text": "Stale Memory Audit",
          "level": 3
        },
        {
          "id": "design-md-landing-page-contract",
          "text": "Design.md Landing Page Contract",
          "level": 3
        },
        {
          "id": "anti-storybook-variant-sprint",
          "text": "Anti-Storybook Variant Sprint",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "your-coding-agent-confidently-says-a-project-still-uses-an-old-routing-structure-but-you-know-the-app-has-changed-recently-what-should-you-do-first",
          "text": "Your coding agent confidently says a project still uses an old routing structure, but you know the app has changed recently. What should you do first?",
          "level": 3
        },
        {
          "id": "when-is-lightweight-markdown-memory-most-useful-in-this-workflow",
          "text": "When is lightweight Markdown memory most useful in this workflow?",
          "level": 3
        },
        {
          "id": "why-did-john-emphasize-that-the-inspiration-board-images-were-generated-rather-than-scraped",
          "text": "Why did John emphasize that the inspiration board images were generated rather than scraped?",
          "level": 3
        },
        {
          "id": "what-job-does-design-md-perform-in-this-lesson-s-ai-design-workflow",
          "text": "What job does design.md perform in this lesson's AI design workflow?",
          "level": 3
        },
        {
          "id": "why-generate-throwaway-route-level-variants-instead-of-immediately-building-a-full-storybook-style-setup",
          "text": "Why generate throwaway route-level variants instead of immediately building a full Storybook-style setup?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "are-you-using-the-memory-features-of-these-harneses-i-noticed-they-get-out-of-date-when-i-use-them-and-shifted-to-beads-but-even-that-has-some-clunk-still-https-github-com-gastownhall-beads",
          "text": "Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads",
          "level": 3
        },
        {
          "id": "i-use-basic-memory-that-i-got-from-you-a-while-back-i-still-find-it-to-be-an-excellent-tool-i-like-to-use-it-to-keep-things-documented-for-developers-within-the-same-repository-would-love-to-know-if-you-still-use-it-and-for-what-purpose-i-know-karpathy-popularized-simple-obsidian-graph-knowledge-as-opposed-to-a-rag-vector-retrieval-basic-memory-seems-to-have-best-of-both-worlds",
          "text": "I use basic memory that i got from you a while back, I still find it to be an excellent tool, I like to use it to keep things documented for developers within the same repository, would love to know if you still use it, and for what purpose, I know karpathy popularized simple, obsidian graph knowledge as opposed to a rag vector retrieval, basic memory seems to have best of both worlds",
          "level": 3
        },
        {
          "id": "were-you-ever-a-fan-of-warp-terminal-this-cmux-looks-like-i-might-be-able-to-get-rid-of-that-subscription",
          "text": "Were you ever a fan of warp terminal? This cmux looks like I might be able to get rid of that subscription!",
          "level": 3
        },
        {
          "id": "this-is-a-little-off-topic-but-when-generating-a-lot-of-research-what-guiding-principles-do-you-reach-for-to-staying-organized-as-well-as-optimize-for-the-ai-s-retrieval",
          "text": "This is a little off topic but when generating a lot of research what guiding principles do you reach for to staying organized as well as optimize for the ai’s retrieval ?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Trust current source and capture design decisions\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is grounding AI coding workflows in the live project instead of trusting stale memory. John recommends keeping memory simple with Markdown and straightforward retrieval, treating the code as the source of truth, using generated visual inspiration to produce a durable design.md, and creating disposable UI variants directly in the app so you can compare directions quickly and delete the losers.\n\n## Working outcomes\n\n- Tell the difference between basic memory and dangerous stale memory\n- Treat code as the source of truth with million-token snapshot contexts\n- Capture a design.md standard and generate multi-route structural variants\n\n## Concepts and consequences\n\n### Code as the Source of Truth\n\nProject memory can be useful, but it drifts as the code changes. John’s main point is that trying to update memory on every commit can turn into a parallel maintenance problem, so the safest default is to make the agent look at the current code when implementation details matter.\n\n**Why it matters:** It keeps agents from confidently acting on outdated assumptions and keeps the workflow tied to what actually exists in the repo.\n\n### Lightweight Markdown Memory\n\nJohn still sees value in basic memory when it stays simple: Markdown files, simple RAG, and human-readable notes. The danger starts when memory becomes a second system that has to be kept in sync with a fast-moving codebase.\n\n**Why it matters:** Good memory reduces repeated explanation; bad memory becomes stale documentation that misleads both humans and agents.\n\n### Large-Context Snapshots as a Possible Escape Hatch\n\nJohn briefly floated million-token context windows as a possible way to take useful snapshots of codebases, but he explicitly framed it as something he had not really tried yet. In this lesson, it is a possible direction, not a proven replacement for memory.\n\n**Why it matters:** The useful idea is that current code text is more trustworthy than detached summaries, but this section does not teach a full large-context snapshot workflow.\n\n### Design.md from Generated Inspiration\n\nJohn demonstrated starting design work from an inspiration board made of generated images, not scraped sites. He selected visual directions, copied them into an AI prompt, asked Codex to create a hoodie company landing page, and showed the generated design.md with references, style DNA, colors, typography, layout, composition, shape, and motion.\n\n**Why it matters:** It turns vague taste into a concrete design artifact that the agent can use to generate UI that follows a direction instead of producing a generic layout.\n\n### Throwaway Route Variants\n\nInstead of building a heavy Storybook setup for every experiment, John often asks agents to generate multiple temporary routes or page copies using the same components with different styles. He compares them in the app with simple navigation, picks the best direction, and deletes the rest.\n\n**Why it matters:** It supports fast visual exploration without creating another maintenance surface that has to be kept up to date.\n\n## Reference tools and resources\n\n### Inspiration Board\n\nThe generated visual inspiration board John used to select design directions and copy a structured prompt into AI tools.\n\n**Use when:** Use it when you do not know what a UI should feel like yet and need generated visual references to guide a design.md.\n\n[Reference](https://inspiration-board.pages.dev/)\n\n### Codex CLI\n\nThe local coding agent environment John used in the demo to create the hoodie company project, generate a design.md, and build the landing page.\n\n**Use when:** Use it when you want an agent working directly against a local project for repo-aware coding and prototyping.\n\n[Reference](https://github.com/openai/codex)\n\n## Recommendations and best practices\n\n- Keep memory files light, boring, and close to the repo; avoid building a second knowledge system that must be updated every time the code changes.\n- When implementation details matter, have the agent inspect the current code instead of trusting memory.\n- Treat large-context repo snapshots as an experiment John mentioned, not as a proven workflow from this lesson.\n- Start AI design work from concrete visual inspiration, then turn that inspiration into a design.md before asking the agent to build UI.\n- Use generated inspiration images as design references rather than scraping or copying existing websites.\n- Generate temporary route or page variants when exploring visual direction, compare them in the app, pick one, and delete the rest.\n\n## Practice and acceptance criteria\n\nPractice treating the live repo as the source of truth, then turn generated visual inspiration into a design.md and fast, disposable UI variants.\n\n### Checklist\n\n1. Pick a small active repo and identify one task where stale memory could mislead an agent, such as routing, data fetching, auth, or component structure.\n2. Ask Codex or your coding agent to inspect the current files before proposing changes, then have it summarize the source-of-truth evidence.\n3. Create or trim a repo-local Markdown memory file so it contains only stable conventions, setup notes, and human-useful guidance.\n4. For a larger task, give the agent the relevant current files or source context directly instead of relying only on detached summaries.\n5. Draft a design.md with sections for references, style DNA, colors, typography, layout, composition, shape, and motion.\n6. Prompt the agent to generate 3 route-level or page-level UI variants from design.md, with simple navigation between them in the local app.\n7. Review the variants in the browser, promote the best one to the real route, and delete the temporary routes.\n\n### Stale Memory Audit\n\n**Difficulty:** Easy\n\nFind one existing project note, README section, or memory file that might be outdated. Ask the agent to compare it against the current code and produce a small patch that either fixes, shrinks, or deletes the stale guidance.\n\n**Done when:** The repo has less misleading documentation, and the agent's recommendation is based on current files rather than remembered assumptions.\n\n### Design.md Landing Page Contract\n\n**Difficulty:** Medium\n\nCreate a design.md for a fictional product landing page using concrete rules for references, style DNA, typography, color, layout, composition, shape, and motion. Then ask the agent to build one route from that contract.\n\n**Done when:** The generated page visibly follows the design.md instead of feeling like a generic template.\n\n### Anti-Storybook Variant Sprint\n\n**Difficulty:** Hard\n\nGenerate 5 disposable route-level variants of the same page from your design.md, add left and right arrow navigation, review them in the browser, promote the strongest version, and delete the other four.\n\n**Done when:** Only the chosen implementation remains in the app, the rejected variants are removed, and the final route still follows the design contract.\n\n## Questions to test understanding\n\n### Your coding agent confidently says a project still uses an old routing structure, but you know the app has changed recently. What should you do first?\n\n- **A.** Ask the agent to rely on its saved memory because it has seen the project before.\n- **B.** Have the agent inspect the current repo or provide current source context before making changes.\n- **C.** Create a longer memory file describing the old routing structure in more detail.\n- **D.** Skip investigation and let the agent implement the change directly.\n\n**Answer: B.** The live codebase is the source of truth when implementation details may have changed. Stale memory is most dangerous when it sounds confident but no longer matches the repo.\n\n### When is lightweight Markdown memory most useful in this workflow?\n\n- **A.** When it captures stable, human-readable guidance close to the repo.\n- **B.** When it replaces the need to inspect code for implementation-dependent tasks.\n- **C.** When it becomes a separate system that must be updated after every commit.\n- **D.** When it hides project knowledge inside an opaque retrieval pipeline nobody reviews.\n\n**Answer: A.** John’s version of useful memory is simple: Markdown, straightforward retrieval, and information that remains useful to humans. The moment it becomes a parallel system to maintain, it starts creating the stale-memory problem.\n\n### Why did John emphasize that the inspiration board images were generated rather than scraped?\n\n- **A.** Because the workflow is about getting visual direction without copying live websites directly.\n- **B.** Because scraped websites cannot be used by AI tools at all.\n- **C.** Because generated images remove the need for design review.\n- **D.** Because the inspiration board is only meant for backend architecture planning.\n\n**Answer: A.** John used generated images as inspiration material: something to look at when deciding what the UI should feel like. The point was to guide direction, not clone an existing site.\n\n### What job does design.md perform in this lesson's AI design workflow?\n\n- **A.** It stores every rejected mockup so the agent can reuse them later.\n- **B.** It acts as a reusable design brief covering references, style DNA, typography, color, layout, composition, shape, and motion.\n- **C.** It replaces visual review because the agent can infer the best design automatically.\n- **D.** It is only useful for copying an existing website exactly.\n\n**Answer: B.** design.md turns selected visual inspiration into reusable instructions the agent can build from. John showed Codex using the design document and reference files to produce a workable hoodie landing page direction.\n\n### Why generate throwaway route-level variants instead of immediately building a full Storybook-style setup?\n\n- **A.** Because variants should become permanent maintenance surfaces.\n- **B.** Because route variants avoid needing to review the UI in a browser.\n- **C.** Because agents cannot generate components directly.\n- **D.** Because you can compare real layouts quickly in the app, pick a winner, and delete the rest.\n\n**Answer: D.** John favors quick prototyping directly inside the app when he is not being disciplined about a full design system. Temporary routes are useful only if the losing experiments are cleaned up.\n\n## Reflection prompts\n\n- Where does your current workflow still ask agents to trust memory when they should inspect the live code instead?\n- What project knowledge is stable enough to live in Markdown, and what knowledge changes too often to be trusted outside the code?\n- What visual references and style details would make your design.md specific enough for an agent to build from?\n\n## Further applications\n\n1. Create a small design.md template with sections for references, style DNA, colors, typography, layout, composition, shape, and motion.\n2. Run the anti-Storybook exercise: generate several landing page routes, add left/right arrow navigation, pick one, and remove the rest.\n3. Try a small current-code snapshot experiment: give the agent the relevant current files for one task and compare the result to an answer based only on an old memory note.\n4. Write a reusable prompt that asks the agent to inspect the current code first, summarize the source-of-truth evidence, and only then propose or implement a change.\n\n## Applied exercises\n\nExercise: Variant Navigation Pattern (The Anti-Storybook Method)\n\n**Objective:**  Build a rapid visual alternative to heavy interface sandboxes by spawning page variants directly inside an active dev server environment.\n\n**Task Parameters:** Create a prototype folder and initialize a workspace using your agent framework.Prompt your model tool to generate 3 to 5 discrete variations of a landing layout block, rendering them as raw inline HTML implementations within adjacent testing folders.Program a basic temporary navigation wrapper into the page footers (e.g., binding standard Left Arrow and Right Arrow key actions) to switch seamlessly between layout iterations.Review your layout choices directly inside your active browser view. Once you select a winning design pattern, instruct your agent runner to delete the temporary variants and promote the chosen layout to your core project file path.\n\n## Questions and answers\n\n### Are you using the memory features of these harneses? I noticed they get out of date when I use them and shifted to beads but even that has some clunk still https://github.com/gastownhall/beads\n\nMemory systems frequently run out of date because the underlying codebase is the ultimate source of truth. Attempting to continuously update external memory stores on every commit quickly turns into an administrative bottleneck. John suggests keeping project memories as lightweight as possible. He also mentions an alternative: leveraging large context allowances (like Oracle's 1 million token limit) to pass raw codebase snapshots directly into the context window, bypassing the need for explicit memory stores.\n\n### I use basic memory that i got from you a while back, I still find it to be an excellent tool, I like to use it to keep things documented for developers within the same repository, would love to know if you still use it, and for what purpose, I know karpathy popularized simple, obsidian graph knowledge as opposed to a rag vector retrieval, basic memory seems to have best of both worlds\n\nJohn agrees that basic memory approaches that rely on simple Markdown file formatting combined with straightforward RAG mechanisms work well because they avoid unnecessary over-engineering. He notes that unless an advanced automated context synchronization system emerges, keeping documentation minimal and close to the raw source files remains the most practical path forward.\n\n### Were you ever a fan of warp terminal? This cmux looks like I might be able to get rid of that subscription!\n\nJohn used Warp for a short period but eventually ran into specific workflow limitations. Certain built-in keyboard shortcuts and essential macro behaviors were unsupported at the time, leading him to return to terminal workflows like `cmux`. He notes that Warp has since moved open-source, and mentions he would gladly return to any terminal harness layer if it becomes highly agentic, performant, and serves his user experience goals better.\n\n### This is a little off topic but when generating a lot of research what guiding principles do you reach for to staying organized as well as optimize for the ai’s retrieval ?\n\nThe question continues into the perspective-based research discussion: assign expert, new-user, grandparent, and power-user lenses to separate workstreams, then use numbered QA assignments to make the results targeted and retrievable.\n\n## Operational playbooks\n\n- [A reusable design.md standard](/topics/foundations-design-md-playbook/)\n- [Throwaway route variants](/topics/foundations-throwaway-variants-playbook/)\n\n- [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-04.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-04.html)\n\n### Visual reference index\n\n- [01:23:45](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-1): Browser screen shot demonstrating multiple layout panels stacked on the inspiration-board application interface.\n- [01:26:14](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-2): Selection highlight highlighting layout component segments prior to executing copy commands.\n- [01:27:19](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-3): Terminal window capturing structural parameters pasted cleanly into the main prompt console input field.\n- [01:28:55](https://codex-workshop-followup.pages.dev/lesson-04.html#clip-04-4): Editor viewport capturing structural variables mapping colors and typography metrics inside the design.md file.\n- [01:31:16](https://codex-workshop-followup.pages.dev/lesson-04.html): Dual terminal workspace capture displaying secondary script workers generating page instances side-by-side.\n- [01:33:30](https://codex-workshop-followup.pages.dev/lesson-04.html): Terminal display capturing structural prompt bypass responses responding to systemic skip trust flags.\n- [01:34:50](https://codex-workshop-followup.pages.dev/lesson-04.html): Live interface preview screen showcasing vector hoodie styling data compiled via background generation passes.\n- [01:37:45](https://codex-workshop-followup.pages.dev/lesson-04.html): Terminal logs showing completed codebase outputs verifying final production code frameworks."
    },
    {
      "id": "factory-preference-capture",
      "slug": "preference-capture",
      "title": "Turn preference into reusable decisions",
      "summary": "Pairwise comparisons, honest rejection, recorded axes, and durable taste rules instead of vague adjectives.",
      "category": "Planning",
      "tags": [
        "preference",
        "factory"
      ],
      "sources": [
        {
          "label": "Turn preference into reusable decisions",
          "url": "https://gentle-lasso-9d5n.here.now/"
        }
      ],
      "sourceUnits": [
        "10-this-or-that/index.html#TL;DR",
        "10-this-or-that/index.html#The principle",
        "10-this-or-that/index.html#Appendix",
        "10-this-or-that/index.html#Taste is a dataset, not a description",
        "10-this-or-that/index.html#The case study: 130 votes to a shipped template",
        "10-this-or-that/index.html#The rules that make votes cheap and honest",
        "10-this-or-that/index.html#Beyond design: any decision an agent can render"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 948,
      "url": "/topics/factory-preference-capture/",
      "markdownUrl": "/markdown/factory-preference-capture.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-preference-capture.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "the-principle",
          "text": "The principle",
          "level": 2
        },
        {
          "id": "taste-is-a-dataset-not-a-description",
          "text": "Taste is a dataset, not a description",
          "level": 2
        },
        {
          "id": "the-case-study-130-votes-to-a-shipped-template",
          "text": "The case study: 130 votes to a shipped template",
          "level": 2
        },
        {
          "id": "the-rules-that-make-votes-cheap-and-honest",
          "text": "The rules that make votes cheap and honest",
          "level": 2
        },
        {
          "id": "beyond-design-any-decision-an-agent-can-render",
          "text": "Beyond design: any decision an agent can render",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        }
      ],
      "markdown": "# Turn preference into reusable decisions\n\nPairwise comparisons, honest rejection, recorded axes, and durable taste rules instead of vague adjectives.\n\n## Related working material\n\n- [Turn preference into reusable decisions — prompts and exercises](/topics/factory-preference-capture-practice/)\n- [Turn preference into reusable decisions — questions and tradeoffs](/topics/factory-preference-capture-questions/)\n- [Turn preference into reusable decisions — worked example](/topics/factory-preference-capture-worked-example/)\n\n## TL;DR\n\n- A local **this-or-that lab**: options render side by side, you arrow-key through Elo-paired duels, and every vote + note lands in `votes.jsonl` — data your agent reads, not vibes it guesses.\n- You walk away with the whole kit (one harness page, one 30-line server, one manifest) and the loop: **generate options → vote → agent reads votes → sharper round**.\n- The one move: never answer \"what do you like?\" — demand options and answer **\"this or that\"** instead. This workshop's own page template went from \"ugly as sin\" to shipped in 3 rounds and 130 votes.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://gentle-lasso-9d5n.here.now/agent.md?raw and follow it to set up a this-or-that voting lab in my current project. Run the success check at the end and show me the result.\n```\n\n## The principle\n\n## Taste is a dataset, not a description\n\nAsk someone what they like and you get adjectives — \"clean\", \"modern\", \"not too busy\" — words an agent can't execute. Show the same person two options and they answer instantly, reliably, hundreds of times in a row. That asymmetry is the whole trick. It's the same one RLHF is built on: humans are bad at writing reward functions and good at picking between two outputs. A this-or-that lab makes you the reward model, and `votes.jsonl` is the training signal your agent reads.\n\n## The case study: 130 votes to a shipped template\n\nThis workshop's own pages are the receipt. The starting point was a template the author called \"ugly as sin... extremely difficult to read at a glance.\" Round 1: eight wildly different page themes, king-of-the-hill voting. It produced a ranking in 24 seconds — and felt thin, because each loser died after one duel. Round 2 fixed the harness because the votes said so: Elo pairing so every option faces many opponents, a live leaderboard, both-bad and skip buttons, synced scrolling. Twelve themes, 88 votes, a winner shipped to ten live sites.\n\nThen came the sharpest lesson. A refinement round built twelve variations orbiting the winner — and got rejected on sight: *\"These designs are all WAAAY too similar.\"* Single-knob deltas waste votes; a duel only teaches something when the options genuinely diverge. The rebuilt round used structural moves — different section chrome, different code treatments, different layouts — plus a light/dark axis where duels alternated modes and the harness tracked per-mode records. Thirty votes later the data showed something no one would have articulated: one theme was undefeated in *both* modes (it shipped), another was a dark-mode specialist (4-0 dark, lost in light), a third the exact mirror. Total: 130 votes across three rounds, each round's harness and roster rebuilt from what the previous round's votes revealed.\n\n## The rules that make votes cheap and honest\n\n**Options must differ structurally.** If two options could be confused at arm's length, you're spending votes on noise. **Hold the subject constant** — vary only the approach, or the comparison teaches nothing (the same rule as the 9x image-mockup pattern in the Variations section). **Never force a choice:** both-bad is a real signal (it says the whole region of design space is wrong), and quitting early must be free — votes stop being honest the moment they feel like a chore. **Record every axis you care about** (mode, device width, section) on the vote itself; splits you didn't record are insights you lost. **Elo over knockout:** pairing least-played, closest-rated options keeps every duel informative, and ratings survive an unfinished session. And **notes beat scores** — a one-line \"C's header wins but B's spacing is calmer\" is worth ten silent votes to the agent reading the file.\n\n## Beyond design: any decision an agent can render\n\nNothing in the kit knows about CSS. An option is any file an iframe can show — so the same loop ranks error-message copy, README structures, CLI output formats, API response shapes, function names, landing-page headlines, chart styles. The agent's job is always the same three steps: render genuinely distinct options, stay out of the way while you vote, then read `votes.jsonl` and turn your picks into rules it applies — and into a `DECISIONS.md` the next session inherits. That last step is the compounding one: taste captured once stops being re-litigated forever.\n\n## Appendix\n\n### Limits & caveats\n\n- Small vote counts are directional, not statistical. 30 votes over 12 options ≈ 5 games each; Elo with K=32 at that depth is a rough sort. Treat standings as \"top cluster / bottom cluster\", not a precise order.\n- The pairing heuristic (least-played, closest-rated, no immediate repeats) is not true adaptive sampling; informative pairs can be missed. In the case study, the \\#1 and \\#2 finishers never met head-to-head — read the pairings before over-trusting a margin.\n- One voter = a personal taste model, not user research. It optimizes for *your* preference, which is the point — but don't present the output as market evidence.\n- Iframe rendering means options should be same-origin and self-contained; cross-origin options lose scroll-sync and the mode toggle (both fail silently by design).\n- The light/dark axis requires options to respond to `<html data-mode=\"...\">`; options styled with only `prefers-color-scheme` won't flip inside the harness.\n- \"Both bad\" applies a flat −12 to both options — a pragmatic penalty, not principled Elo."
    },
    {
      "id": "factory-preference-capture-practice",
      "slug": "preference-capture-practice",
      "title": "Turn preference into reusable decisions — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for turn preference into reusable decisions.",
      "category": "Planning",
      "tags": [
        "prompts",
        "exercises",
        "preference-capture"
      ],
      "sources": [
        {
          "label": "Turn preference into reusable decisions",
          "url": "https://gentle-lasso-9d5n.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://gentle-lasso-9d5n.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "10-this-or-that/index.html#Quick start",
        "10-this-or-that/index.html#Prompt library",
        "10-this-or-that/index.html#The loop, productized",
        "10-this-or-that/index.html#Set it up (agent guide)",
        "10-this-or-that/index.html#Kick off a lab for any decision",
        "10-this-or-that/index.html#Read my votes (the RLHF step)",
        "10-this-or-that/index.html#Ship the winner and bank the taste",
        "10-this-or-that/agent.md"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 4974,
      "url": "/topics/factory-preference-capture-practice/",
      "markdownUrl": "/markdown/factory-preference-capture-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-preference-capture-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "kick-off-a-lab-for-any-decision",
          "text": "Kick off a lab for any decision",
          "level": 3
        },
        {
          "id": "read-my-votes-the-rlhf-step",
          "text": "Read my votes (the RLHF step)",
          "level": 3
        },
        {
          "id": "ship-the-winner-and-bank-the-taste",
          "text": "Ship the winner and bank the taste",
          "level": 3
        },
        {
          "id": "the-loop-productized",
          "text": "The loop, productized",
          "level": 2
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "this-or-that-rlhf-for-your-agent-agent-setup-guide",
          "text": "This or That: RLHF for Your Agent — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Turn preference into reusable decisions — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for turn preference into reusable decisions.\n\n## Quick start\n\nThe kit with three demo options, running in under a minute (needs `python3` + `curl`):\n\n``` text\nmkdir -p this-or-that && cd this-or-that\nfor f in compare.html server.py options.json options/sample-a.html options/sample-b.html options/sample-c.html; do\n  curl -s --create-dirs -o \"$f\" \"https://gentle-lasso-9d5n.here.now/kit/$f\"\ndone\npython3 server.py\n# then open http://127.0.0.1:8477/compare.html and vote with your arrow keys\n```\n\n## Prompt library\n\nThree prompts run the whole loop: kick off a lab for any decision, have the agent read your votes, ship the winner. Replace the `<ANGLE-BRACKET>` slots before pasting.\n\n### Kick off a lab for any decision\n\n- Agent: any coding agent\n- Working directory: your project root\n- Expected result: a this-or-that/ dir, N distinct option files, a 127.0.0.1 URL to vote at\n\n``` text\nBuild me a local \"this or that\" voting lab for this decision: <DECISION — e.g. \"the hero section of our landing page\" / \"our CLI error-message style\" / \"the README structure\">.\n\nRules:\n- Generate 8 genuinely DISTINCT options. Different structure, not one knob turned — if two options could be confused at arm's length, replace one. Keep the SUBJECT constant across all options; only the approach varies.\n- Each option is one self-contained file an iframe can render (HTML page, image, or plain code/text file).\n- Set up the this-or-that kit (compare.html + server.py + options.json — from https://gentle-lasso-9d5n.here.now/agent.md?raw) with my options listed in options.json, start the server, and give me the URL.\n- I'll vote with arrow keys; every vote and note is saved to votes.jsonl. Don't interpret my taste yet — wait until I say done.\n```\n\n### Read my votes (the RLHF step)\n\n- Agent: same session or a fresh one\n- Working directory: project root, after you pressed f\n- Expected result: a ranking, explicit taste rules with quoted evidence, a round-2 plan\n\n``` text\nI finished voting. Read this-or-that/votes.jsonl and:\n1. Give me the final ranking with win-loss records (and per-mode splits if present).\n2. Tell me what my taste IS — concrete rules inferred from the winners, the losers, the both-bad votes, and my notes. Quote the evidence for each rule.\n3. Propose round 2: keep the top 2-3, cut the bottom, and generate NEW options that push harder on what won. If my votes contradict each other, say so and ask me one sharp question instead of guessing.\n```\n\n### Ship the winner and bank the taste\n\n- Agent: same project\n- Working directory: project root\n- Expected result: the real artifact updated, plus a DECISIONS.md entry future sessions can read\n\n``` text\n<WINNER> won. Apply it for real:\n1. Translate the winning option into the actual artifact (template / copy / config / code) in this project.\n2. Verify it end-to-end, then show me before/after.\n3. Record the decision: append the final standings, what won and why, and the taste rules you learned to DECISIONS.md — so future sessions start from my recorded preferences instead of re-asking.\n```\n\n## The loop, productized\n\nThis loop has now run on the workshop twice. The first round (130 votes) chose the page template you're reading. The second pointed the kit at its own question — *how should these guides be authored?* — 13 structurally distinct formats over one constant subject, 27 votes, and a decisive note later, every section ships a **Session Replay + Socratic Dialogue page pair**. Watch that round happen: [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) · [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html).\n\nBecause it worked twice, the loop is captured twice. In the workshop repo it's an mdflow flow — one command that scaffolds a lab from this kit, fans out option authors, and injects the banked taste records fresh on every run:\n\n``` text\nmd flows/this-or-that.md --_question \"<WHAT TO DECIDE>\" --_subject \"<CONTENT HELD CONSTANT ACROSS EVERY OPTION>\"\n```\n\nThe flow file, verbatim:\n\n``` text\n---\ndescription: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules\n_inputs: [_question, _subject]\n_interactive: true\n---\n\nYou are running one round of the **this-or-that decision flow**: the user can't\narticulate their taste, but they can pick between two things all day. Turn the\nquestion below into an Elo-voted decision with a durable record.\n\n**Question to decide:** {{ _question }}\n\n**Subject / content source (hold constant across every option):** {{ _subject }}\n\n## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)\n\n1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy,\n   API shape). Everything else — subject content, visual theme — is held constant\n   so votes measure only that axis.\n2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html`\n   and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json`\n   (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base\n   stylesheet all options link, so theme stays constant; support\n   `html[data-mode=\"light|dark\"]` (light default, `prefers-color-scheme` +\n   `data-mode` override) — the harness stamps it and records the mode on every vote.\n3. **Generate 9–13 structurally distinct options.** Same subject, different\n   approach; if two could be confused at arm's length, replace one. Include the\n   incumbent as a control when one exists. Write one exemplar option yourself,\n   then fan out parallel subagents, each authoring 2–3 options from one tight\n   shared brief (subject digest + format rules + per-option spec + the exemplar\n   path). Real content only — never lorem ipsum, never invented names.\n4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit\n   (zero external requests, no absolute home paths, no secrets); render both light\n   and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`,\n   remove it.\n5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the\n   background and give the user the `compare.html` URL. Controls: ←/→ pick ·\n   ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field\n   saves with each vote (tell the user: one note outweighs ten votes).\n6. **When the user says \"done\":** read `votes.jsonl` — ranking, per-mode W-L\n   splits, `both_bad` lines, and especially notes. State the user's taste as\n   explicit, quotable rules backed by vote evidence (head-to-heads, splits,\n   quoted notes). A user note that makes a decision IS the decision.\n7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings\n   table, the decision with quoted evidence, taste rules, ship plan), update\n   agent memory so it is never re-litigated. Then propose round 2 from the\n   winners — or ship.\n\n## Accumulated taste record (injected fresh each run — read before generating options)\n\n@../authoring-lab/RESULTS.md\n\n@../07-variations/template-lab/RESULTS.md\n```\n\nThe flow file is published as a downloadable attachment on this site (the `?raw` suffix skips the HTML viewer — required for machine fetches). Pull it into your own repo's `flows/` and run it; note it injects two taste-record files by relative path (the `@`-lines at the bottom), so outside the workshop repo point those at your own `RESULTS.md` files:\n\n``` text\nmkdir -p flows\ncurl -fsSL \"https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw\" -o flows/this-or-that.md\nmd flows/this-or-that.md --_question \"<WHAT TO DECIDE>\" --_subject \"<CONTENT HELD CONSTANT ACROSS EVERY OPTION>\"\n```\n\n`md install \"https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw\"` also works — it registers the flow verbatim in the mdflow registry (reversible with `md remove this-or-that.md`) — but the registry copy can't resolve the flow's relative `@`-imports, so the `flows/`-local copy above is the layout that runs as-is.\n\nOutside the repo, the same loop is a generalized agent skill — `this-or-that`, at `~/.agents/skills/this-or-that/SKILL.md` — which pulls `compare.html` and `server.py` straight from this site's `/kit/` files and works in any project. The SKILL.md is also a downloadable attachment; install it into a project with the `skills` CLI (stage it anywhere *except* a dir named `skills/` — the CLI claims that name as its own symlink target and you'd install an empty skill):\n\n``` text\nmkdir -p skill-src/this-or-that\ncurl -fsSL \"https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw\" -o skill-src/this-or-that/SKILL.md\nnpx skills add ./skill-src --skill this-or-that -y\n```\n\n## Set it up (agent guide)\n\nEverything below is also published as [agent.md](https://gentle-lasso-9d5n.here.now/agent.md) for agents to execute cold. Three files make the kit; three sample options make it demo instantly.\n\n1.  Create `this-or-that/compare.html` — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling):\n\n    ``` text\n    <!doctype html>\n    <html lang=\"en\">\n    <head>\n    <meta charset=\"utf-8\">\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n    <title>this or that</title>\n    <style>\n    :root{color-scheme:dark}\n    *{box-sizing:border-box}\n    body{margin:0;font:14px/1.45 system-ui,-apple-system,\"Segoe UI\",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}\n    header{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}\n    #status{font-weight:700;white-space:nowrap}\n    #mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}\n    #mode.on{display:inline-block}\n    #mode.light{background:#f5f2ea;color:#3a3830}\n    #mode.dark{background:#0d0b08;color:#d8d2c4}\n    #board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}\n    #board b{color:#ffd479}\n    #hint{color:#8b8d94;font-size:12px}\n    .hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}\n    .hbtn:hover{border-color:#4a4c55;color:#fff}\n    .hbtn.warn{color:#ff9d9d}\n    #note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}\n    #note::placeholder{color:#5b5d66}\n    .stage{flex:1;display:flex;min-height:0}\n    .pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}\n    .pane:last-child{border-right:0}\n    .pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}\n    .pane-bar b{font-size:13px}\n    .pane-bar .side{color:#8b8d94;font-size:12px}\n    .pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}\n    .pane-bar button:hover{background:#3d7bff}\n    iframe{flex:1;border:0;width:100%;background:#fff}\n    kbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}\n    #overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}\n    #overlay.show{display:grid}\n    .card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}\n    .card h2{margin:0 0 .7rem}\n    .card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}\n    .card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}\n    .card th{color:#8b8d94;font-weight:600}\n    .card p{color:#b9bbc3}\n    .card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}\n    </style>\n    </head>\n    <body>\n    <header>\n      <span id=\"status\"></span>\n      <button id=\"mode\" onclick=\"toggleMode(true)\"></button>\n      <span id=\"board\"></span>\n      <button class=\"hbtn warn\" onclick=\"bothBad()\">Both bad <kbd>↓</kbd></button>\n      <button class=\"hbtn\" onclick=\"skip()\">Skip <kbd>s</kbd></button>\n      <button class=\"hbtn\" onclick=\"finish()\">Finish <kbd>f</kbd></button>\n      <span id=\"hint\"></span>\n      <input id=\"note\" placeholder=\"optional note — saved with vote\">\n    </header>\n    <div class=\"stage\" id=\"stage\"></div>\n    <div id=\"overlay\"><div class=\"card\" id=\"ocard\"></div></div>\n    <script>\n    'use strict';\n    let V = [], MODES = false, TITLE = 'this or that';\n    const K = 32;\n    let elo = [], games = [], rec = [];\n    let mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';\n    let uiMode = 'light', toggled = false;\n\n    const stage = document.getElementById('stage');\n    const statusEl = document.getElementById('status');\n    const modeEl = document.getElementById('mode');\n    const board = document.getElementById('board');\n    const hint = document.getElementById('hint');\n    const note = document.getElementById('note');\n    const overlay = document.getElementById('overlay');\n\n    const N = () => V.length;\n    const src = i => V[i].src;\n    const name = i => V[i].name;\n\n    function post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }\n    function expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }\n    function applyResult(w, l){\n      const ew = expected(elo[w], elo[l]);\n      elo[w] = Math.round(elo[w] + K*(1-ew));\n      elo[l] = Math.round(elo[l] - K*(1-ew));\n      games[w]++; games[l]++;\n      if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;\n    }\n    function ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }\n    function renderBoard(){\n      board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');\n    }\n    function renderMode(){\n      if (!MODES) return;\n      modeEl.className = 'on ' + uiMode;\n      modeEl.textContent = (uiMode === 'light' ? ' light' : ' dark') + ' — d flips';\n    }\n    function applyMode(){\n      renderMode();\n      if (!MODES) return;\n      document.querySelectorAll('iframe').forEach(f => {\n        try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}\n      });\n    }\n    window.toggleMode = (manual) => {\n      if (!MODES) return;\n      uiMode = uiMode === 'light' ? 'dark' : 'light';\n      if (manual) toggled = true;\n      applyMode();\n    };\n    function pickPair(){\n      let best = null, bestScore = Infinity;\n      for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){\n        const key = i+'-'+j;\n        if (key === lastKey) continue;\n        const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;\n        if (score < bestScore){ bestScore = score; best = [i,j]; }\n      }\n      lastKey = best[0]+'-'+best[1];\n      return Math.random() < .5 ? best : [best[1], best[0]];\n    }\n    function hookIframes(){\n      const frames = [...document.querySelectorAll('iframe')];\n      frames.forEach(f => f.addEventListener('load', () => {\n        try {\n          if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;\n          f.contentWindow.addEventListener('keydown', onKey);\n          const other = frames.find(x => x !== f);\n          if (!other) return;\n          let lock = false;\n          f.contentWindow.addEventListener('scroll', () => {\n            if (lock) { lock = false; return; }\n            try {\n              const a = f.contentWindow, b = other.contentWindow;\n              const ah = a.document.documentElement.scrollHeight - a.innerHeight;\n              const bh = b.document.documentElement.scrollHeight - b.innerHeight;\n              if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }\n            } catch(e){}\n          }, {passive:true});\n        } catch(e){}\n      }));\n    }\n    function paneHTML(i, side, key){\n      return `<div class=\"pane\"><div class=\"pane-bar\"><b>${name(i)}</b><span class=\"side\">${side} · elo ${elo[i]} · ${games[i]} games</span>`+\n            `<button onclick=\"pick('${side}')\">This one <kbd>${key}</kbd></button></div>`+\n            `<iframe src=\"${src(i)}\"></iframe></div>`;\n    }\n    function renderDuel(){\n      [A, B] = pickPair();\n      duelN++;\n      if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }\n      stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');\n      statusEl.textContent = `Vote ${voteN+1}`;\n      hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';\n      renderBoard(); renderMode();\n      hookIframes();\n    }\n    window.pick = side => {\n      if (mode !== 'duel') return;\n      const w = side === 'left' ? A : B, l = side === 'left' ? B : A;\n      applyResult(w, l);\n      voteN++;\n      const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),\n                 elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};\n      if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }\n      post(d);\n      note.value = '';\n      renderDuel();\n    };\n    window.bothBad = () => {\n      if (mode !== 'duel') return;\n      elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);\n      games[A]++; games[B]++;\n      voteN++;\n      const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',\n                 elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};\n      if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }\n      post(d);\n      note.value = '';\n      renderDuel();\n    };\n    window.skip = () => { if (mode === 'duel') renderDuel(); };\n    window.finish = () => {\n      if (mode !== 'duel') return;\n      mode = 'browse'; browseI = ranked()[0];\n      const table = ranked().map(i => {\n        const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};\n        if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }\n        return r;\n      });\n      post({mode:'final', votes:voteN, table});\n      document.getElementById('ocard').innerHTML =\n        `<h2>Standings — ${voteN} votes</h2>`+\n        `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+\n        table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+\n        `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+\n        `<button onclick=\"closeOverlay()\">Browse →</button>`;\n      overlay.classList.add('show');\n    };\n    window.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };\n    function renderBrowse(){\n      stage.innerHTML = `<div class=\"pane\"><div class=\"pane-bar\"><b>${name(browseI)}</b>`+\n        `<span class=\"side\">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src=\"${src(browseI)}\"></iframe></div>`;\n      statusEl.textContent = 'Browse';\n      hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';\n      hookIframes();\n    }\n    function onKey(e){\n      if (e.target === note) return;\n      if (e.key === 'd'){ toggleMode(true); return; }\n      if (mode === 'duel'){\n        if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }\n        else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }\n        else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }\n        else if (e.key === 's'){ skip(); }\n        else if (e.key === 'f' || e.key === 'Enter'){ finish(); }\n      } else {\n        const order = ranked();\n        const pos = order.indexOf(browseI);\n        if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }\n        else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }\n        else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }\n      }\n    }\n    document.addEventListener('keydown', onKey);\n\n    fetch('options.json').then(r => r.json()).then(cfg => {\n      TITLE = cfg.title || TITLE;\n      MODES = !!cfg.modes;\n      V = cfg.options;\n      document.title = TITLE + ' — this or that';\n      elo = V.map(() => 1000);\n      games = V.map(() => 0);\n      rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));\n      renderDuel();\n    }).catch(() => {\n      stage.innerHTML = '<div style=\"padding:2rem;color:#ff9d9d\">Could not load options.json — serve this directory with server.py, not file://</div>';\n    });\n    </script>\n    </body>\n    </html>\n    ```\n\n2.  Create `this-or-that/server.py` — serves the dir and appends every POSTed vote to `votes.jsonl`:\n\n    ``` text\n    #!/usr/bin/env python3\n    \"\"\"this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl.\"\"\"\n    import json, os, sys, time\n    from http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler\n\n    ROOT = os.path.dirname(os.path.abspath(__file__))\n    PORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477\n\n    class Handler(SimpleHTTPRequestHandler):\n        def __init__(self, *a, **kw):\n            super().__init__(*a, directory=ROOT, **kw)\n\n        def do_POST(self):\n            if self.path != \"/vote\":\n                self.send_response(404); self.end_headers(); return\n            n = int(self.headers.get(\"Content-Length\", 0))\n            try:\n                data = json.loads(self.rfile.read(n) or b\"{}\")\n            except Exception:\n                data = {\"error\": \"unparseable\"}\n            data[\"ts\"] = time.strftime(\"%Y-%m-%dT%H:%M:%S\")\n            with open(os.path.join(ROOT, \"votes.jsonl\"), \"a\", encoding=\"utf-8\") as f:\n                f.write(json.dumps(data) + \"\\n\")\n            self.send_response(204); self.end_headers()\n\n        def log_message(self, *a):\n            pass\n\n    if __name__ == \"__main__\":\n        print(f\"this-or-that → http://127.0.0.1:{PORT}/compare.html\")\n        ThreadingHTTPServer((\"127.0.0.1\", PORT), Handler).serve_forever()\n    ```\n\n3.  Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render; set `\"modes\": true` to add a light/dark axis (duels alternate modes, `d` flips, per-mode records are tracked — options must respond to `<html data-mode=\"light|dark\">`):\n\n    ``` text\n    {\n      \"title\": \"Pick a direction\",\n      \"modes\": false,\n      \"options\": [\n        { \"id\": \"a\", \"name\": \"Option A\", \"src\": \"options/sample-a.html\" },\n        { \"id\": \"b\", \"name\": \"Option B\", \"src\": \"options/sample-b.html\" },\n        { \"id\": \"c\", \"name\": \"Option C\", \"src\": \"options/sample-c.html\" }\n      ]\n    }\n    ```\n\n4.  Create the three demo options (same subject, three styles — replace with real options for a real decision):\n\n    ``` text\n    <!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>A</title>\n    <style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}\n    .hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}\n    .hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>\n    <body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>\n    ```\n\n    ``` text\n    <!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>B</title>\n    <style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}\n    .hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}\n    .hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>\n    <body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>\n    ```\n\n    ``` text\n    <!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>C</title>\n    <style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}\n    .hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:\"$ \";color:oklch(75% .15 150)}\n    .hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>\n    <body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>\n    ```\n\n5.  Run it:\n\n    ``` text\n    cd this-or-that && python3 server.py\n    # open http://127.0.0.1:8477/compare.html\n    ```\n\n**Success check:** with the server running, this must append one line to `votes.jsonl`:\n\n``` text\ncurl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{\"probe\":true}'\ntail -1 this-or-that/votes.jsonl\n```\n\nExpected: a JSON line containing `\"probe\": true` plus a `\"ts\"` timestamp — and `http://127.0.0.1:8477/compare.html` shows two options side by side. Report both results to your user, then delete the probe line.\n\nEvery real vote looks like this — `winner`, `loser`, a full Elo snapshot, and the optional note; a `final` line with the standings table lands when the voter presses `f`:\n\n``` text\n{\"mode\": \"elo\", \"vote\": 12, \"left\": \"Option C\", \"right\": \"Option B\", \"winner\": \"Option C\", \"loser\": \"Option B\", \"elo\": {\"a\": 1000, \"b\": 984, \"c\": 1016}, \"note\": \"C's header wins but B's spacing is calmer\", \"lab\": \"Pick a direction\", \"ts\": \"the example workflow-16T22:35:47\"}\n```\n\n## Complete reusable setup contract\n\n## This or That: RLHF for Your Agent — agent setup guide\n\nFollowing this file sets up: a local \"this or that\" voting lab in the user's current project — a duel harness page, a tiny vote-recording server, a manifest of options, and three demo options. The user votes with arrow keys; every vote is appended to `votes.jsonl` for you (the agent) to read and act on.\n\nHuman companion pages on this site: the [section guide](https://gentle-lasso-9d5n.here.now/) (kit, prompts, the full write-up), the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) (turn-by-turn replay of the round where this loop chose the workshop's own page format — 13 formats, 27 votes), and the [Socratic Dialogue](https://gentle-lasso-9d5n.here.now/dialogue.html) (attendee Q&A).\n\nPlaceholders used below: `<project-root>` = the project you are working in. All paths are relative to `<project-root>`.\n\n## Prerequisites\n\nCheck each before starting:\n\n- `python3 --version` — any Python 3.8+.\n- A browser on the same machine (the lab runs at `http://127.0.0.1:8477`).\n- Port 8477 free (or pick another: `python3 server.py 8481`).\n\n## Steps\n\n1. Create `this-or-that/compare.html` with exactly this content — the duel harness (Elo pairing, ←/→ voting, ↓ both-bad, `s` skip, `f` finish, per-vote notes, optional light/dark axis, synced scrolling):\n\n```html\n<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>this or that</title>\n<style>\n:root{color-scheme:dark}\n*{box-sizing:border-box}\nbody{margin:0;font:14px/1.45 system-ui,-apple-system,\"Segoe UI\",Roboto,sans-serif;background:#101114;color:#e8e8ea;height:100vh;display:flex;flex-direction:column;overflow:hidden}\nheader{display:flex;align-items:center;gap:.9rem;padding:.5rem .9rem;background:#17181c;border-bottom:1px solid #26272c;flex:0 0 auto;flex-wrap:wrap}\n#status{font-weight:700;white-space:nowrap}\n#mode{font-weight:700;font-size:12px;padding:.2rem .6rem;border-radius:99px;border:1px solid #34353c;cursor:pointer;white-space:nowrap;display:none}\n#mode.on{display:inline-block}\n#mode.light{background:#f5f2ea;color:#3a3830}\n#mode.dark{background:#0d0b08;color:#d8d2c4}\n#board{color:#9fa3ad;font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}\n#board b{color:#ffd479}\n#hint{color:#8b8d94;font-size:12px}\n.hbtn{background:#26272c;color:#c9cbd2;border:1px solid #34353c;border-radius:6px;padding:.3rem .7rem;font:inherit;font-size:12px;cursor:pointer;white-space:nowrap}\n.hbtn:hover{border-color:#4a4c55;color:#fff}\n.hbtn.warn{color:#ff9d9d}\n#note{margin-left:auto;background:#0d0e11;border:1px solid #2a2b31;color:#e8e8ea;border-radius:6px;padding:.35rem .6rem;width:240px;font:inherit}\n#note::placeholder{color:#5b5d66}\n.stage{flex:1;display:flex;min-height:0}\n.pane{flex:1;display:flex;flex-direction:column;min-width:0;border-right:1px solid #26272c}\n.pane:last-child{border-right:0}\n.pane-bar{display:flex;align-items:center;gap:.6rem;padding:.38rem .8rem;background:#131418;border-bottom:1px solid #26272c}\n.pane-bar b{font-size:13px}\n.pane-bar .side{color:#8b8d94;font-size:12px}\n.pane-bar button{margin-left:auto;background:#2b6cf6;color:#fff;border:0;border-radius:6px;padding:.3rem .85rem;font-weight:600;cursor:pointer;font:inherit}\n.pane-bar button:hover{background:#3d7bff}\niframe{flex:1;border:0;width:100%;background:#fff}\nkbd{background:#26272c;border:1px solid #34353c;border-bottom-width:2px;border-radius:4px;padding:0 .4rem;font-family:ui-monospace,Menlo,monospace;font-size:12px}\n#overlay{position:fixed;inset:0;background:rgba(8,8,10,.93);display:none;place-items:center;z-index:9}\n#overlay.show{display:grid}\n.card{background:#17181c;border:1px solid #2a2b31;border-radius:14px;padding:1.5rem 1.9rem;max-width:680px;max-height:85vh;overflow:auto}\n.card h2{margin:0 0 .7rem}\n.card table{border-collapse:collapse;width:100%;margin:.5rem 0 1rem}\n.card td,.card th{padding:.28rem .6rem;border-bottom:1px solid #26272c;text-align:left;font-size:13px}\n.card th{color:#8b8d94;font-weight:600}\n.card p{color:#b9bbc3}\n.card button{background:#2b6cf6;color:#fff;border:0;border-radius:8px;padding:.5rem 1.1rem;font-weight:600;cursor:pointer;font:inherit}\n</style>\n</head>\n<body>\n<header>\n  <span id=\"status\"></span>\n  <button id=\"mode\" onclick=\"toggleMode(true)\"></button>\n  <span id=\"board\"></span>\n  <button class=\"hbtn warn\" onclick=\"bothBad()\">Both bad <kbd>↓</kbd></button>\n  <button class=\"hbtn\" onclick=\"skip()\">Skip <kbd>s</kbd></button>\n  <button class=\"hbtn\" onclick=\"finish()\">Finish <kbd>f</kbd></button>\n  <span id=\"hint\"></span>\n  <input id=\"note\" placeholder=\"optional note — saved with vote\">\n</header>\n<div class=\"stage\" id=\"stage\"></div>\n<div id=\"overlay\"><div class=\"card\" id=\"ocard\"></div></div>\n<script>\n'use strict';\nlet V = [], MODES = false, TITLE = 'this or that';\nconst K = 32;\nlet elo = [], games = [], rec = [];\nlet mode = 'duel', A = -1, B = -1, voteN = 0, duelN = 0, browseI = 0, lastKey = '';\nlet uiMode = 'light', toggled = false;\n\nconst stage = document.getElementById('stage');\nconst statusEl = document.getElementById('status');\nconst modeEl = document.getElementById('mode');\nconst board = document.getElementById('board');\nconst hint = document.getElementById('hint');\nconst note = document.getElementById('note');\nconst overlay = document.getElementById('overlay');\n\nconst N = () => V.length;\nconst src = i => V[i].src;\nconst name = i => V[i].name;\n\nfunction post(d){ d.lab = TITLE; fetch('/vote',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(d)}).catch(()=>{}); }\nfunction expected(ra, rb){ return 1/(1+Math.pow(10,(rb-ra)/400)); }\nfunction applyResult(w, l){\n  const ew = expected(elo[w], elo[l]);\n  elo[w] = Math.round(elo[w] + K*(1-ew));\n  elo[l] = Math.round(elo[l] - K*(1-ew));\n  games[w]++; games[l]++;\n  if (MODES) rec[w][uiMode].w++, rec[l][uiMode].l++;\n}\nfunction ranked(){ return V.map((v,i)=>i).sort((a,b)=>elo[b]-elo[a]); }\nfunction renderBoard(){\n  board.innerHTML = 'top: ' + ranked().slice(0,3).map(i=>`<b>${name(i)}</b> ${elo[i]}`).join(' · ');\n}\nfunction renderMode(){\n  if (!MODES) return;\n  modeEl.className = 'on ' + uiMode;\n  modeEl.textContent = (uiMode === 'light' ? ' light' : ' dark') + ' — d flips';\n}\nfunction applyMode(){\n  renderMode();\n  if (!MODES) return;\n  document.querySelectorAll('iframe').forEach(f => {\n    try { f.contentWindow.document.documentElement.dataset.mode = uiMode; } catch(e){}\n  });\n}\nwindow.toggleMode = (manual) => {\n  if (!MODES) return;\n  uiMode = uiMode === 'light' ? 'dark' : 'light';\n  if (manual) toggled = true;\n  applyMode();\n};\nfunction pickPair(){\n  let best = null, bestScore = Infinity;\n  for (let i=0;i<N();i++) for (let j=i+1;j<N();j++){\n    const key = i+'-'+j;\n    if (key === lastKey) continue;\n    const score = (games[i]+games[j])*60 + Math.abs(elo[i]-elo[j]) + Math.random()*40;\n    if (score < bestScore){ bestScore = score; best = [i,j]; }\n  }\n  lastKey = best[0]+'-'+best[1];\n  return Math.random() < .5 ? best : [best[1], best[0]];\n}\nfunction hookIframes(){\n  const frames = [...document.querySelectorAll('iframe')];\n  frames.forEach(f => f.addEventListener('load', () => {\n    try {\n      if (MODES) f.contentWindow.document.documentElement.dataset.mode = uiMode;\n      f.contentWindow.addEventListener('keydown', onKey);\n      const other = frames.find(x => x !== f);\n      if (!other) return;\n      let lock = false;\n      f.contentWindow.addEventListener('scroll', () => {\n        if (lock) { lock = false; return; }\n        try {\n          const a = f.contentWindow, b = other.contentWindow;\n          const ah = a.document.documentElement.scrollHeight - a.innerHeight;\n          const bh = b.document.documentElement.scrollHeight - b.innerHeight;\n          if (ah > 0 && bh > 0){ lock = true; b.scrollTo(0, a.scrollY/ah*bh); }\n        } catch(e){}\n      }, {passive:true});\n    } catch(e){}\n  }));\n}\nfunction paneHTML(i, side, key){\n  return `<div class=\"pane\"><div class=\"pane-bar\"><b>${name(i)}</b><span class=\"side\">${side} · elo ${elo[i]} · ${games[i]} games</span>`+\n        `<button onclick=\"pick('${side}')\">This one <kbd>${key}</kbd></button></div>`+\n        `<iframe src=\"${src(i)}\"></iframe></div>`;\n}\nfunction renderDuel(){\n  [A, B] = pickPair();\n  duelN++;\n  if (MODES){ uiMode = duelN % 2 ? 'light' : 'dark'; toggled = false; }\n  stage.innerHTML = paneHTML(A,'left','←') + paneHTML(B,'right','→');\n  statusEl.textContent = `Vote ${voteN+1}`;\n  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> pick · winner-agnostic pairing · vote until it stops being informative';\n  renderBoard(); renderMode();\n  hookIframes();\n}\nwindow.pick = side => {\n  if (mode !== 'duel') return;\n  const w = side === 'left' ? A : B, l = side === 'left' ? B : A;\n  applyResult(w, l);\n  voteN++;\n  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), winner:name(w), loser:name(l),\n             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};\n  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }\n  post(d);\n  note.value = '';\n  renderDuel();\n};\nwindow.bothBad = () => {\n  if (mode !== 'duel') return;\n  elo[A] = Math.round(elo[A] - 12); elo[B] = Math.round(elo[B] - 12);\n  games[A]++; games[B]++;\n  voteN++;\n  const d = {mode:'elo', vote:voteN, left:name(A), right:name(B), result:'both_bad',\n             elo:Object.fromEntries(V.map((v,i)=>[v.id,elo[i]])), note:note.value.trim()};\n  if (MODES){ d.ui_mode = uiMode; d.toggled = toggled; }\n  post(d);\n  note.value = '';\n  renderDuel();\n};\nwindow.skip = () => { if (mode === 'duel') renderDuel(); };\nwindow.finish = () => {\n  if (mode !== 'duel') return;\n  mode = 'browse'; browseI = ranked()[0];\n  const table = ranked().map(i => {\n    const r = {id:V[i].id, name:name(i), elo:elo[i], games:games[i]};\n    if (MODES){ r.light = `${rec[i].light.w}-${rec[i].light.l}`; r.dark = `${rec[i].dark.w}-${rec[i].dark.l}`; }\n    return r;\n  });\n  post({mode:'final', votes:voteN, table});\n  document.getElementById('ocard').innerHTML =\n    `<h2>Standings — ${voteN} votes</h2>`+\n    `<table><tr><th>#</th><th>Option</th><th>Elo</th><th>Games</th>${MODES?'<th>Light W-L</th><th>Dark W-L</th>':''}</tr>`+\n    table.map((r,i)=>`<tr><td>${i+1}</td><td>${r.name}</td><td>${r.elo}</td><td>${r.games}</td>${MODES?`<td>${r.light}</td><td>${r.dark}</td>`:''}</tr>`).join('')+\n    `</table><p>Saved to <code>votes.jsonl</code> — tell your agent to read it. <kbd>←</kbd>/<kbd>→</kbd> browse · <kbd>r</kbd> keep voting</p>`+\n    `<button onclick=\"closeOverlay()\">Browse →</button>`;\n  overlay.classList.add('show');\n};\nwindow.closeOverlay = () => { overlay.classList.remove('show'); renderBrowse(); };\nfunction renderBrowse(){\n  stage.innerHTML = `<div class=\"pane\"><div class=\"pane-bar\"><b>${name(browseI)}</b>`+\n    `<span class=\"side\">elo ${elo[browseI]} · ${ranked().indexOf(browseI)+1} of ${N()}</span></div><iframe src=\"${src(browseI)}\"></iframe></div>`;\n  statusEl.textContent = 'Browse';\n  hint.innerHTML = '<kbd>←</kbd>/<kbd>→</kbd> cycle by rank · <kbd>r</kbd> keep voting';\n  hookIframes();\n}\nfunction onKey(e){\n  if (e.target === note) return;\n  if (e.key === 'd'){ toggleMode(true); return; }\n  if (mode === 'duel'){\n    if (e.key === 'ArrowLeft'){ e.preventDefault(); pick('left'); }\n    else if (e.key === 'ArrowRight'){ e.preventDefault(); pick('right'); }\n    else if (e.key === 'ArrowDown'){ e.preventDefault(); bothBad(); }\n    else if (e.key === 's'){ skip(); }\n    else if (e.key === 'f' || e.key === 'Enter'){ finish(); }\n  } else {\n    const order = ranked();\n    const pos = order.indexOf(browseI);\n    if (e.key === 'ArrowLeft'){ browseI = order[(pos+N()-1)%N()]; renderBrowse(); }\n    else if (e.key === 'ArrowRight'){ browseI = order[(pos+1)%N()]; renderBrowse(); }\n    else if (e.key === 'r'){ mode = 'duel'; renderDuel(); }\n  }\n}\ndocument.addEventListener('keydown', onKey);\n\nfetch('options.json').then(r => r.json()).then(cfg => {\n  TITLE = cfg.title || TITLE;\n  MODES = !!cfg.modes;\n  V = cfg.options;\n  document.title = TITLE + ' — this or that';\n  elo = V.map(() => 1000);\n  games = V.map(() => 0);\n  rec = V.map(() => ({light:{w:0,l:0}, dark:{w:0,l:0}}));\n  renderDuel();\n}).catch(() => {\n  stage.innerHTML = '<div style=\"padding:2rem;color:#ff9d9d\">Could not load options.json — serve this directory with server.py, not file://</div>';\n});\n</script>\n</body>\n</html>\n```\n\n2. Create `this-or-that/server.py` — serves the directory and appends every POSTed vote to `votes.jsonl`:\n\n```python\n#!/usr/bin/env python3\n\"\"\"this-or-that server: serves the kit dir + appends POST /vote JSON bodies to votes.jsonl.\"\"\"\nimport json, os, sys, time\nfrom http.server import ThreadingHTTPServer, SimpleHTTPRequestHandler\n\nROOT = os.path.dirname(os.path.abspath(__file__))\nPORT = int(sys.argv[1]) if len(sys.argv) > 1 else 8477\n\nclass Handler(SimpleHTTPRequestHandler):\n    def __init__(self, *a, **kw):\n        super().__init__(*a, directory=ROOT, **kw)\n\n    def do_POST(self):\n        if self.path != \"/vote\":\n            self.send_response(404); self.end_headers(); return\n        n = int(self.headers.get(\"Content-Length\", 0))\n        try:\n            data = json.loads(self.rfile.read(n) or b\"{}\")\n        except Exception:\n            data = {\"error\": \"unparseable\"}\n        data[\"ts\"] = time.strftime(\"%Y-%m-%dT%H:%M:%S\")\n        with open(os.path.join(ROOT, \"votes.jsonl\"), \"a\", encoding=\"utf-8\") as f:\n            f.write(json.dumps(data) + \"\\n\")\n        self.send_response(204); self.end_headers()\n\n    def log_message(self, *a):\n        pass\n\nif __name__ == \"__main__\":\n    print(f\"this-or-that → http://127.0.0.1:{PORT}/compare.html\")\n    ThreadingHTTPServer((\"127.0.0.1\", PORT), Handler).serve_forever()\n```\n\n3. Create `this-or-that/options.json` — the manifest. `src` is anything an iframe can render (HTML page, image, code/text file). Set `\"modes\": true` only if every option responds to `<html data-mode=\"light|dark\">`; duels then alternate modes, `d` flips both panes, and per-mode win-loss records are tracked:\n\n```json\n{\n  \"title\": \"Pick a direction\",\n  \"modes\": false,\n  \"options\": [\n    { \"id\": \"a\", \"name\": \"Option A\", \"src\": \"options/sample-a.html\" },\n    { \"id\": \"b\", \"name\": \"Option B\", \"src\": \"options/sample-b.html\" },\n    { \"id\": \"c\", \"name\": \"Option C\", \"src\": \"options/sample-c.html\" }\n  ]\n}\n```\n\n4. Create the three demo options (same subject, three deliberately different styles). For a real decision, replace these with the user's options and update `options.json`:\n\n`this-or-that/options/sample-a.html`:\n\n```html\n<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>A</title>\n<style>body{margin:0;font-family:system-ui;background:oklch(98% .008 80);color:oklch(16% .008 80);display:grid;place-items:center;min-height:100vh}\n.hero{max-width:26rem;padding:2rem}.hero h1{font-size:2.6rem;font-weight:820;letter-spacing:-.03em;line-height:1;margin:0 0 .6rem}\n.hero p{color:oklch(55% .016 80)}.hero button{background:oklch(60% .19 40);color:#fff;border:0;padding:.7rem 1.4rem;font:inherit;font-weight:700;text-transform:uppercase;font-size:.7rem;letter-spacing:.06em}</style></head>\n<body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option A: big type, one accent, flat.</p><button>Get started</button></div></body></html>\n```\n\n`this-or-that/options/sample-b.html`:\n\n```html\n<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>B</title>\n<style>body{margin:0;font-family:ui-serif,Georgia,serif;background:oklch(97% .02 85);color:oklch(22% .015 80);display:grid;place-items:center;min-height:100vh}\n.hero{max-width:24rem;padding:2rem;text-align:center}.hero h1{font-size:2.1rem;font-weight:650;margin:0 0 .6rem}\n.hero p{font-style:italic;color:oklch(50% .03 80)}.hero button{background:none;color:oklch(45% .13 25);border:2px solid currentColor;border-radius:99px;padding:.6rem 1.5rem;font:inherit;font-weight:600}</style></head>\n<body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option B: centered serif, soft, outlined.</p><button>Get started</button></div></body></html>\n```\n\n`this-or-that/options/sample-c.html`:\n\n```html\n<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\"><title>C</title>\n<style>body{margin:0;font-family:ui-monospace,Menlo,monospace;background:oklch(15% .01 250);color:oklch(90% .01 250);display:grid;place-items:center;min-height:100vh}\n.hero{max-width:26rem;padding:2rem;border:1px solid oklch(35% .02 250)}.hero h1{font-size:1.6rem;font-weight:700;margin:0 0 .6rem}.hero h1::before{content:\"$ \";color:oklch(75% .15 150)}\n.hero p{color:oklch(65% .02 250)}.hero button{background:oklch(75% .15 150);color:oklch(15% .05 150);border:0;padding:.6rem 1.2rem;font:inherit;font-weight:700}</style></head>\n<body><div class=\"hero\"><h1>Ship the winner</h1><p>Same subject, different style. This is Option C: terminal dark, mono, green go.</p><button>Get started</button></div></body></html>\n```\n\n5. Start the server and tell the user where to vote:\n\n```bash\ncd this-or-that && python3 server.py\n# → this-or-that → http://127.0.0.1:8477/compare.html\n```\n\n## Success check\n\nWith the server running:\n\n```bash\ncurl -s -X POST http://127.0.0.1:8477/vote -H 'Content-Type: application/json' -d '{\"probe\":true}'\ntail -1 this-or-that/votes.jsonl\ncurl -s -o /dev/null -w \"%{http_code}\\n\" http://127.0.0.1:8477/compare.html\n```\n\nExpected: the `tail` prints a JSON line containing `\"probe\": true` plus a `\"ts\"` timestamp, and the last command prints `200`. Also confirm in a browser that `compare.html` shows two options side by side with \"This one\" buttons. Report all results to your user, then remove the probe line from `votes.jsonl`.\n\n## Notes for agents\n\n- **Serve, don't open as a file.** `compare.html` fetches `options.json` and POSTs votes — `file://` breaks both. Always go through `server.py`.\n- **Options must be same-origin** (files inside `this-or-that/`). Cross-origin option URLs render, but scroll-sync and the light/dark stamp fail silently.\n- **Generating options for a real decision:** make them genuinely DISTINCT — different structure, not one knob turned. If two options could be confused at arm's length, replace one. Keep the subject constant across all options; only the approach varies. 6–12 options is the useful range.\n- **When the user says they're done voting:** read `this-or-that/votes.jsonl`. Vote lines carry `winner`, `loser`, a full `elo` snapshot, and an optional `note`; a `\"mode\": \"final\"` line carries the standings table. Report the ranking, infer explicit taste rules (quote the evidence — especially notes and `both_bad` results), and propose the next round: keep the top 2–3, cut the rest, generate new options that push on what won.\n- **Bank the outcome.** After a winner ships, append the standings and the inferred taste rules to the project's `DECISIONS.md` so future sessions inherit the preference record instead of re-asking.\n- **Productized forms of this loop.** In John's workshop repo, `flows/this-or-that.md` runs an entire round as one mdflow command — `md flows/this-or-that.md --_question \"...\" --_subject \"...\"` — and injects the banked taste records fresh on every run (the flow file is printed verbatim on the section guide). For any other repo, the generalized `this-or-that` agent skill (`~/.agents/skills/this-or-that/SKILL.md`) runs the same loop and pulls this exact kit from `https://gentle-lasso-9d5n.here.now/kit/`. Both artifacts are published on this site as machine-fetchable attachments (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer): the flow at `https://gentle-lasso-9d5n.here.now/flows/this-or-that.md?raw` (fetch it into `flows/this-or-that.md`; it @-imports two taste-record files by relative path — point those at your own `RESULTS.md` files outside the workshop repo), and the skill at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`. Skill install: `mkdir -p skill-src/this-or-that && curl -fsSL \"https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw\" -o skill-src/this-or-that/SKILL.md && npx skills add ./skill-src --skill this-or-that -y` — do NOT stage in a dir named `skills/`; the skills CLI claims that name as its own symlink target and installs an empty skill. Proof it works: a second real round (13 authoring formats, 27 votes) chose the Session Replay + Socratic Dialogue page pair now used across the workshop sites — replayed at `https://gentle-lasso-9d5n.here.now/replay.html`.\n- **Known failure modes:** port already in use → pass another port (`python3 server.py 8481`) and use that URL everywhere; `votes.jsonl` missing → no votes have been cast yet (the file is created on first POST); a duel pane is blank → that option's `src` path in `options.json` is wrong (paths are relative to `this-or-that/`)."
    },
    {
      "id": "factory-preference-capture-questions",
      "slug": "preference-capture-questions",
      "title": "Turn preference into reusable decisions — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Planning",
      "tags": [
        "preference-capture",
        "questions"
      ],
      "sources": [
        {
          "label": "Turn preference into reusable decisions — questions and tradeoffs",
          "url": "https://gentle-lasso-9d5n.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "10-this-or-that/dialogue.html#The room asks"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 1393,
      "url": "/topics/factory-preference-capture-questions/",
      "markdownUrl": "/markdown/factory-preference-capture-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-preference-capture-questions.json",
      "headings": [
        {
          "id": "the-room-asks",
          "text": "The room asks",
          "level": 2
        }
      ],
      "markdown": "# Turn preference into reusable decisions — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The room asks\n\nWhy not just tell the agent what I like?\n\nTry it — you'll produce adjectives. \"Clean.\" \"Modern.\" \"Not too busy.\" An agent can't execute an adjective. But show the same person two options and they answer instantly, honestly, hundreds of times in a row. That asymmetry is what RLHF is built on: humans are bad at writing reward functions and good at picking between two outputs. The harness just makes *you* the reward model, and instead of a vibe the agent gets a file. Every keystroke lands like this:\n\n``` text\n{\"mode\": \"elo\", \"vote\": 7, \"left\": \"Installable Skill\", \"right\": \"Session Replay\",\n \"winner\": \"Session Replay\", \"loser\": \"Installable Skill\",\n \"elo\": { …all 13 ratings after the vote… },\n \"note\": \"\", \"ui_mode\": \"light\", \"lab\": \"How should workshop projects be authored?\"}\n```\n\nTwenty-seven votes sounds like homework. How long did that actually take?\n\nAbout ten minutes, by the timestamps in the vote record. A duel is one keystroke; notes are optional; quitting early is free — Elo standings survive an unfinished session, which is exactly what keeps votes honest instead of dutiful. For scale: the template rendering this page took 130 votes across three rounds, and that's still cheaper than one \"can you make it pop?\" meeting.\n\nWhat stops the options from all looking the same?\n\nA round that got thrown out. A refinement pass once built twelve near-clones of a winning theme and was rejected on sight — \"These designs are all WAAAY too similar.\" Single-knob deltas waste votes; a duel only teaches something when the options genuinely diverge. So the rule is structural, and it's written into the captured flow:\n\n``` text\n3. **Generate 9–13 structurally distinct options.** Same subject, different\n   approach; if two could be confused at arm's length, replace one. Include the\n   incumbent as a control when one exists.\n```\n\nThe other half is holding the subject constant. In the authoring round, all 13 formats rendered the same zsh material — so every vote measured format and nothing else.\n\nDialogue won that round. So why am I looking at two pages?\n\nBecause of one note on duel 26 — the top two head-to-head:\n\n``` text\n{\"vote\": 26, \"left\": \"Session Replay\", \"right\": \"Socratic Dialogue\",\n \"winner\": \"Socratic Dialogue\", \"ui_mode\": \"dark\", \"toggled\": true,\n \"note\": \"I love _both_ the \\\"session replay - custom zsh functions\\\" and\n          \\\"dialogue - custom zsh functions\\\". I think we could use both in\n          separate pages so that each project has a session replay and a\n          dialogue page\"}\n```\n\nThe ranking said \"ship Dialogue.\" The note said \"ship both, as a pair\" — and the pair is what shipped, on every section of this workshop. If the harness only recorded winners, that decision would have been lost. That's why the note field exists, and why every axis you care about (light/dark here) is recorded on the vote itself.\n\nI pressed `f`. What do I actually do with votes.jsonl?\n\nHand it to the agent — this is the RLHF step, and it's a prompt you can lift as-is:\n\n``` text\nI finished voting. Read this-or-that/votes.jsonl and:\n1. Give me the final ranking with win-loss records (and per-mode splits if present).\n2. Tell me what my taste IS — concrete rules inferred from the winners, the losers, the both-bad votes, and my notes. Quote the evidence for each rule.\n3. Propose round 2: keep the top 2-3, cut the bottom, and generate NEW options that push harder on what won. If my votes contradict each other, say so and ask me one sharp question instead of guessing.\n```\n\nThen bank the outcome: standings, the quoted evidence, and the taste rules go into a `RESULTS.md` and the raw record gets archived as `votes-round<N>.jsonl`. Future sessions start from your recorded preferences instead of re-asking. Taste captured once stops being re-litigated forever.\n\nAnd next month, when the next decision comes up — do I re-explain all of this?\n\nNo. In the workshop repo the whole loop is one command; the flow injects the banked taste records fresh on every run, so round N+1 starts where round N ended:\n\n``` text\nmd flows/this-or-that.md --_question \"<WHAT TO DECIDE>\" --_subject \"<CONTENT HELD CONSTANT ACROSS EVERY OPTION>\"\n```\n\nThe flow file itself is short enough to read on one screen — and to lift:\n\n``` text\n---\ndescription: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules\n_inputs: [_question, _subject]\n_interactive: true\n---\n\nYou are running one round of the **this-or-that decision flow**: the user can't\narticulate their taste, but they can pick between two things all day. Turn the\nquestion below into an Elo-voted decision with a durable record.\n\n**Question to decide:** {{ _question }}\n\n**Subject / content source (hold constant across every option):** {{ _subject }}\n\n## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)\n\n1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy,\n   API shape). Everything else — subject content, visual theme — is held constant\n   so votes measure only that axis.\n2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html`\n   and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json`\n   (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base\n   stylesheet all options link, so theme stays constant; support\n   `html[data-mode=\"light|dark\"]` (light default, `prefers-color-scheme` +\n   `data-mode` override) — the harness stamps it and records the mode on every vote.\n3. **Generate 9–13 structurally distinct options.** Same subject, different\n   approach; if two could be confused at arm's length, replace one. Include the\n   incumbent as a control when one exists. Write one exemplar option yourself,\n   then fan out parallel subagents, each authoring 2–3 options from one tight\n   shared brief (subject digest + format rules + per-option spec + the exemplar\n   path). Real content only — never lorem ipsum, never invented names.\n4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit\n   (zero external requests, no absolute home paths, no secrets); render both light\n   and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`,\n   remove it.\n5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the\n   background and give the user the `compare.html` URL. Controls: ←/→ pick ·\n   ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field\n   saves with each vote (tell the user: one note outweighs ten votes).\n6. **When the user says \"done\":** read `votes.jsonl` — ranking, per-mode W-L\n   splits, `both_bad` lines, and especially notes. State the user's taste as\n   explicit, quotable rules backed by vote evidence (head-to-heads, splits,\n   quoted notes). A user note that makes a decision IS the decision.\n7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings\n   table, the decision with quoted evidence, taste rules, ship plan), update\n   agent memory so it is never re-litigated. Then propose round 2 from the\n   winners — or ship.\n\n## Accumulated taste record (injected fresh each run — read before generating options)\n\n@../authoring-lab/RESULTS.md\n\n@../07-variations/template-lab/RESULTS.md\n```\n\nOutside this repo, the same loop is a generalized agent skill (`this-or-that`, at `~/.agents/skills/this-or-that/SKILL.md`) — it pulls `compare.html` and `server.py` straight from this site's `/kit/` files. Both the flow file and the skill are downloadable attachments with one-line install commands on the [section guide](https://gentle-lasso-9d5n.here.now/index.html).\n\nIsn't one person's 27 votes just… bias?\n\nYes — deliberately. This is a personal taste model, not user research; don't present the standings as market evidence. The point is that your bias becomes data an agent can act on and cite back at you, instead of a mood it has to guess at. And it isn't limited to design: an option is anything an iframe can render — error copy, README structures, API shapes, function names. The authoring round voted on *formats*, not colors, and it ended with the page pair you're navigating right now. Want to watch that round happen turn by turn? That's the [Session Replay](https://gentle-lasso-9d5n.here.now/replay.html) page.\n\nEvery standing, quote, and vote excerpt above is verbatim from the two banked voting rounds — the template lab (130 votes) and the authoring lab (27 votes) — via their RESULTS.md files and archived vote records. Session evidence is referred to generically. Full caveats: the [section guide's](https://gentle-lasso-9d5n.here.now/index.html) appendix."
    },
    {
      "id": "factory-preference-capture-worked-example",
      "slug": "preference-capture-worked-example",
      "title": "Turn preference into reusable decisions — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Planning",
      "tags": [
        "preference-capture",
        "examples"
      ],
      "sources": [
        {
          "label": "Turn preference into reusable decisions — worked example",
          "url": "https://gentle-lasso-9d5n.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "10-this-or-that/replay.html#The session",
        "10-this-or-that/replay.html#Run this round yourself"
      ],
      "collection": "factory",
      "categoryId": "planning",
      "wordCount": 1161,
      "url": "/topics/factory-preference-capture-worked-example/",
      "markdownUrl": "/markdown/factory-preference-capture-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-preference-capture-worked-example.json",
      "headings": [
        {
          "id": "the-session",
          "text": "The session",
          "level": 2
        },
        {
          "id": "run-this-round-yourself",
          "text": "Run this round yourself",
          "level": 2
        }
      ],
      "markdown": "# Turn preference into reusable decisions — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\nThis transcript restages a prior working session in beats. Every vote line, the standings table, and the quoted note are verbatim from the round's vote record (archived as `authoring-lab/votes-round1.jsonl`) and its `RESULTS.md`.\n\nYou\n\nI want the workshop guides to move away from numbered exercises toward write-ups grounded in what actually happened in past sessions — user stories, skills, something in that direction. I can't describe the format I want. Run the this-or-that loop on it: the question is *how should workshop projects be authored?*\n\nThe classic opening condition for this loop: a real decision, more than one plausible answer, and taste the deciding factor the owner can't articulate.\n\nAgent\n\nFramed the axis before generating anything. One thing varies: **content architecture**. Everything else held constant — every option renders the same subject (another section's custom-zsh-functions material) through one shared stylesheet, with light/dark supported so the mode lands on every vote. Then scaffolded `authoring-lab/` at the repo root: `compare.html` and `server.py` copied *verbatim* from this section's kit, plus the manifest — 13 concepts, incumbent included as the control:\n\n``` text\n{\n  \"title\": \"How should workshop projects be authored?\",\n  \"modes\": true,\n  \"options\": [\n    { \"id\": \"exercise\", \"name\": \"Exercise (incumbent)\", \"src\": \"options/01-exercise.html\" },\n    { \"id\": \"user-story\", \"name\": \"User Story\", \"src\": \"options/02-user-story.html\" },\n    { \"id\": \"session-replay\", \"name\": \"Session Replay\", \"src\": \"options/03-session-replay.html\" },\n    { \"id\": \"scar-story\", \"name\": \"Scar → Fix\", \"src\": \"options/04-scar-story.html\" },\n    { \"id\": \"skill-card\", \"name\": \"Installable Skill\", \"src\": \"options/05-skill-card.html\" },\n    { \"id\": \"before-after\", \"name\": \"Before / After\", \"src\": \"options/06-before-after.html\" },\n    { \"id\": \"case-file\", \"name\": \"Case File\", \"src\": \"options/07-case-file.html\" },\n    { \"id\": \"prompt-anthology\", \"name\": \"Prompt Anthology\", \"src\": \"options/08-prompt-anthology.html\" },\n    { \"id\": \"decision-journal\", \"name\": \"Decision Journal\", \"src\": \"options/09-decision-journal.html\" },\n    { \"id\": \"dialogue\", \"name\": \"Socratic Dialogue\", \"src\": \"options/10-dialogue.html\" },\n    { \"id\": \"field-manual\", \"name\": \"Field Manual\", \"src\": \"options/11-field-manual.html\" },\n    { \"id\": \"run-of-show\", \"name\": \"Run of Show\", \"src\": \"options/12-run-of-show.html\" },\n    { \"id\": \"agent-brief\", \"name\": \"Agent-First Brief\", \"src\": \"options/13-agent-brief.html\" }\n  ]\n}\n```\n\nThe kit teaching this section is the kit being used — copied, not rebuilt. And 13 is deliberately past the comfort zone: structural distinctness is what makes votes cheap. If two options could be confused at arm's length, one gets replaced.\n\nAgent\n\nAuthored one exemplar option directly, then fanned out parallel subagents, each writing 2–3 formats from one tight shared brief: subject digest, format rules, per-option spec, the exemplar's path. All 13 render the same zsh material; only the architecture differs — an annotated session transcript, a Socratic Q&A, an investigation case file, a time-coded run of show, an installable skill, an agent-first brief, the incumbent exercise…\n\nQA before handover: every option HTTP 200 through `server.py`; grep audit for external requests, absolute home paths, secrets; both modes rendered; one smoke vote POSTed to `/vote`, confirmed in `votes.jsonl`, then removed. Server started in the background — here's the URL. Controls: ←/→ pick · ↓ both bad · `d` flips light/dark · `s` skip · `f` finish. The note field saves with each vote.\n\nThe handover ends with \"one note outweighs ten votes\" — about to be proven — and then the agent gets out of the way. Hovering ruins honest voting.\n\nYou\n\n\\[arrow keys, 27 duels, about ten minutes by the timestamps\\]\n\nAgent\n\nMeanwhile, every keystroke lands as a full record. Vote 7 as it hit `votes.jsonl` (Elo snapshot elided here — the real line carries all 13 ratings):\n\n``` text\n{\"mode\": \"elo\", \"vote\": 7, \"left\": \"Installable Skill\", \"right\": \"Session Replay\",\n \"winner\": \"Session Replay\", \"loser\": \"Installable Skill\",\n \"elo\": { …all 13 ratings after the vote… },\n \"note\": \"\", \"ui_mode\": \"light\", \"lab\": \"How should workshop projects be authored?\"}\n```\n\nSession Replay beat the Installable Skill twice (votes 7 and 20) — that head-to-head became a banked taste rule: show the session, not just the recipe. Past-session evidence outranks the same content written as instructions.\n\nYou\n\nDuel 26 — the top two meet head-to-head, Session Replay vs Socratic Dialogue. Instead of just picking, a note goes into the field:\n\n``` text\n{\"vote\": 26, \"left\": \"Session Replay\", \"right\": \"Socratic Dialogue\",\n \"winner\": \"Socratic Dialogue\", \"ui_mode\": \"dark\", \"toggled\": true,\n \"note\": \"I love _both_ the \\\"session replay - custom zsh functions\\\" and\n          \\\"dialogue - custom zsh functions\\\". I think we could use both in\n          separate pages so that each project has a session replay and a\n          dialogue page\"}\n```\n\nThe decisive artifact of the whole round is one typed sentence. The ranking alone would have shipped Dialogue and discarded Replay. A note that makes a decision *is* the decision.\n\nYou\n\nDone — read the votes.\n\nAgent\n\nRead `votes.jsonl` back: 27 votes, zero both-bad, per-mode splits on every line. Final standings:\n\n``` text\n #     Format                 Elo   W-L   Light  Dark\n 1     Socratic Dialogue      1064  4-0   2-0    2-0\n 2     Session Replay         1048  4-1   2-0    2-1\n 3     Agent-First Brief      1031  3-1   2-0    1-1\n 4     Exercise (incumbent)   1016  3-2   1-2    2-0\n 5–9   User Story · Scar → Fix · Installable Skill ·\n       Prompt Anthology · Run of Show          all 1000, 2-2\n 10–12 Before/After · Decision Journal ·\n       Field Manual                            all  968, 1-3\n 13    Case File               937  0-4   0-1    0-3\n```\n\nStated the taste as rules with the evidence attached: **conversation beats document** — the top three all read as turns addressed to someone, and every dossier-shaped format sank. **Show the session, not just the recipe.** **Numbered steps can live inside a page but can't be its identity** — the incumbent finished 4th, outclassed rather than hated. **Bureaucratic chrome kills** — case numbers and PROC blocks took the bottom slots, and Case File went 0-3 in dark mode alone.\n\nAll of it banked: standings, the quoted note, and the taste rules written to RESULTS.md; the raw record archived as votes-round1.jsonl. Decided once, with evidence — never re-litigated.\n\nAgent\n\nThen the loop itself got captured, so the next round costs one command instead of a re-explanation: an mdflow flow at `flows/this-or-that.md` that runs the whole process and injects the accumulated taste records fresh on every run, and a generalized agent skill at `~/.agents/skills/this-or-that/SKILL.md` that pulls this same kit from this site's `/kit/` files for any repo. Both are on the [section guide](https://gentle-lasso-9d5n.here.now/index.html), flow file included verbatim.\n\nThe outcome is what you're reading. Every workshop section now ships a Session Replay page and a Socratic Dialogue page — and this one replays the round that decided that.\n\n## Run this round yourself\n\nIn the workshop repo, the whole loop — frame the axis, scaffold from the kit, fan out authors, QA, hand over, read the votes, bank the taste — is one command:\n\n``` text\nmd flows/this-or-that.md --_question \"<WHAT TO DECIDE>\" --_subject \"<CONTENT HELD CONSTANT ACROSS EVERY OPTION>\"\n```\n\nAnywhere else: paste the kickoff prompt from the [section guide's](https://gentle-lasso-9d5n.here.now/index.html) prompt library, or use the `this-or-that` agent skill — it fetches `compare.html` and `server.py` straight from this site's `/kit/` files. Both the flow file and the skill are downloadable attachments with one-line install commands on the [section guide](https://gentle-lasso-9d5n.here.now/index.html)."
    },
    {
      "id": "codex-hooks",
      "slug": "hooks",
      "title": "Automate lifecycle work with hooks",
      "summary": "A hook is not a better prompt. It is a lifecycle checkpoint. Use it when the behavior should happen whether or not the model remembers.",
      "category": "Execution",
      "tags": [
        "hooks",
        "automation",
        "gates"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#hooks"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Put Setup At Session Start",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Route Before The Prompt Leaves",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Use Stop Hooks As Final Gates",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Keep Hooks Out Of Jobs That Need Judgment",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Use Documented Events",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Copyable Artifact: Hook Decision Checklist",
        "src/content/final/chunk-07-automate-the-agent-loop-with-hooks.md#Automate The Agent Loop With Hooks/Implementation Notes To Verify",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#hooks",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 875,
      "url": "/topics/codex-hooks/",
      "markdownUrl": "/markdown/codex-hooks.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-hooks.json",
      "headings": [
        {
          "id": "put-setup-at-session-start",
          "text": "Put Setup At Session Start",
          "level": 2
        },
        {
          "id": "route-before-the-prompt-leaves",
          "text": "Route Before The Prompt Leaves",
          "level": 2
        },
        {
          "id": "use-stop-hooks-as-final-gates",
          "text": "Use Stop Hooks As Final Gates",
          "level": 2
        },
        {
          "id": "keep-hooks-out-of-jobs-that-need-judgment",
          "text": "Keep Hooks Out Of Jobs That Need Judgment",
          "level": 2
        },
        {
          "id": "use-documented-events",
          "text": "Use Documented Events",
          "level": 2
        },
        {
          "id": "copyable-artifact-hook-decision-checklist",
          "text": "Copyable Artifact: Hook Decision Checklist",
          "level": 2
        },
        {
          "id": "implementation-notes-to-verify",
          "text": "Implementation Notes To Verify",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Automate lifecycle work with hooks\n\nA hook is not a better prompt. It is a **lifecycle checkpoint**. Use it when the behavior should happen **whether or not the model remembers**.\n\nUse session start for setup and binding, user prompt submit for pre-submit routing, context, and safety, and stop hooks for final gates. Keep skills, [imps](https://github.com/johnlindquist/codex-imps), CLI helpers, and manual prompts for jobs that need optional invocation, model judgment, or task-specific context.\n\n> If you want things to happen automatically, that's not what skills are for. If you want them to happen automatically, that's what hooks are for.\n>\n> — John Lindquist\n\n## Put Setup At Session Start\n\nSession start is the **setup moment**. Use it for identifiers and state that later tooling needs to find without scraping the screen or asking the model to remember.\n\nAt session start, a project might record:\n\n- session id\n- working directory\n- transcript location, when available\n- branch name\n- visible workspace surface\n- a searchable session name or tag\n\nKeep this setup boring and reliable. If later shortcuts, dashboards, or review tools need to find the right conversation, **this is where the lookup trail starts**.\n\n> That's the key piece of information, is that session start, like, a place to set things up.\n>\n> — John Lindquist\n\n## Route Before The Prompt Leaves\n\nUser prompt submit is the **pre-submit moment**. Use it when a project-specific prompt pattern should trigger local work **before the model spends a turn**.\n\nPrompt submit triggers can do things like:\n\n- `#test` loads files tagged for test context\n- `#api` loads route and schema context\n- `!ticket` creates a tracking issue from the prompt body\n- `!summary` sends the current thread to a summarizer\n- sensitive release terms trigger a confirmation check\n\nChoose syntax that fits the project and team. Do not assume custom symbols will remain collision-free forever.\n\n## Use Stop Hooks As Final Gates\n\nStop hooks are for **final checks near the end of a turn**, so missing proof is surfaced before the work is treated as done.\n\nGood stop-gate candidates:\n\n- run the smallest relevant test\n- run a formatter or linter\n- check for unresolved uncertainty language\n- verify an issue or summary was created\n- check whether a forbidden file changed\n- surface missing proof and report blocked only when the current hook behavior supports that flow\n\nDo not claim a hook guarantees correctness. A hook can run final checks and surface missing proof; exact blocking, continuation, mutation, and appended-context behavior must be verified against the current docs and installed tool. The verification still has to be well designed.\n\n## Keep Hooks Out Of Jobs That Need Judgment\n\nHooks are best for **mechanical behavior**. If the action needs fresh reasoning each time, a hook is probably the wrong surface.\n\nUse a hook when:\n\n- the trigger is predictable\n- the action should run automatically\n- the behavior can be reviewed and trusted\n- the result should not depend on the model remembering a rule\n\nUse another surface when:\n\n- the action is optional\n- the model needs to decide whether it applies\n- the work needs a large body of task-specific context\n- a normal prompt, skill, CLI helper, or narrow imp would be clearer\n\n## Use Documented Events\n\nVerify the current [Codex hook docs](https://developers.openai.com/codex/hooks) before relying on exact event lists or payload behavior. Treat event names as **current-tool details, not the durable lesson**. A hook workflow should name the lifecycle moment, state what it automates, and keep examples easy to recheck.\n\nOnly some events may honor matchers, and handler support can change. Keep implementation examples conceptual until the exact matcher behavior, payload shape, return behavior, and trust flow have been checked against current docs.\n\nThat matters for shared examples: start with the workflow shape, then attach exact event names only after checking the installed tool and current docs.\n\n## Copyable Artifact: Hook Decision Checklist\n\n```text\nUse a SessionStart hook when:\n- the session needs setup before the first prompt\n- you need to bind session id, cwd, transcript, branch, or visible workspace state\n- later tools need to find this session without screen scraping\n\nUse a UserPromptSubmit hook when:\n- a prompt pattern should trigger local context loading\n- a project shortcut should route work before the model spends a turn\n- a safety check should confirm or block a risky prompt\n\nUse a Stop hook when:\n- a final check should run before the work is treated as done\n- missing proof should be surfaced or reported according to verified hook behavior\n- final output needs proof\n\nDo not use a hook when:\n- the behavior needs model judgment every time\n- the action is optional\n- the implementation is not reviewed or trusted\n- a normal prompt, skill, CLI helper, or narrow imp is clearer\n```\n\n## Implementation Notes To Verify\n\nBefore sharing executable hook examples, verify:\n\n- exact payload fields\n- whether the example blocks, continues, appends context, or only reports\n- timeout behavior\n- trust-review behavior\n- event matcher behavior\n- current docs for the installed Codex version\n\n**Concepts are portable. Hook code is version-sensitive.**\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#hooks)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-workspace-agents",
      "slug": "workspace-agents",
      "title": "Build hyper-specific workspace agents",
      "summary": "The fastest useful agent is usually not the biggest one. Wrap the tools you already trust, preload only the context the job needs, and keep broad agents out of small repeated tasks.",
      "category": "Execution",
      "tags": [
        "imps",
        "specialists",
        "context"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#workspace-agents"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Start With The Tool",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Preload The Right Context",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Keep The Agent Narrow",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Prefer Tools With CLIs Or APIs",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Treat Account Permissions As Setup",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Make Self-Improvement Reviewable",
        "src/content/final/chunk-03-hyper-specific-workspace-agents.md#Create Hyper-Specific Workspace Agents/Prove Generated Helpers",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#workspace-agents",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 364,
      "url": "/topics/codex-workspace-agents/",
      "markdownUrl": "/markdown/codex-workspace-agents.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-workspace-agents.json",
      "headings": [
        {
          "id": "start-with-the-tool",
          "text": "Start With The Tool",
          "level": 2
        },
        {
          "id": "preload-the-right-context",
          "text": "Preload The Right Context",
          "level": 2
        },
        {
          "id": "keep-the-agent-narrow",
          "text": "Keep The Agent Narrow",
          "level": 2
        },
        {
          "id": "prefer-tools-with-clis-or-apis",
          "text": "Prefer Tools With CLIs Or APIs",
          "level": 2
        },
        {
          "id": "treat-account-permissions-as-setup",
          "text": "Treat Account Permissions As Setup",
          "level": 2
        },
        {
          "id": "make-self-improvement-reviewable",
          "text": "Make Self-Improvement Reviewable",
          "level": 2
        },
        {
          "id": "prove-generated-helpers",
          "text": "Prove Generated Helpers",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Build hyper-specific workspace agents\n\nThe fastest useful agent is usually not the biggest one. Wrap the tools you already trust, **preload only the context the job needs**, and keep broad agents out of small repeated tasks.\n\n## Start With The Tool\n\nBuild the agent around **one CLI, API, repo, or repeatable workflow**. A narrow helper should have a clear job before it gets a clever personality.\n\n## Preload The Right Context\n\n**Static prompt context** works for stable jobs. **Dynamic context** works when the helper needs to load files, docs, API data, or a project-specific bundle before answering.\n\n> This is about as instant as I've ever seen an AI respond to anything, because it just has that context preloaded in.\n>\n> — John Lindquist\n\n## Keep The Agent Narrow\n\nIf the task needs web research, product judgment, or multi-system reasoning, send it back to a general agent or a heavier planning workflow. The narrow agent should stay **boring, quick, and predictable**.\n\n> I don't want them to reason or think about things. I want them to know exact file paths, exact examples, and then maybe some basic file editing, but not too much more than that.\n>\n> — John Lindquist\n\n## Prefer Tools With CLIs Or APIs\n\nCommand-line and API surfaces give the agent something concrete to **inspect, execute, and verify**. They also make it easier to turn a vague repeat task into a small wrapper with reliable inputs and outputs.\n\n## Treat Account Permissions As Setup\n\nOAuth screens, account state, credential storage, scopes, and admin permissions are setup concerns. They should be checked deliberately and kept out of shared examples unless they are sanitized and current.\n\n## Make Self-Improvement Reviewable\n\nStore suggested changes, inspect them, and apply them deliberately. A self-improving helper is only useful if its changes are **reviewable and reversible**.\n\n## Prove Generated Helpers\n\nA newly generated **[imp](https://github.com/johnlindquist/codex-imps)** is draft tooling until the source, link/install behavior, and smoke tests check out. Do not share the generated helper as a setup path until it can **answer one harmless query and show the command evidence**.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#workspace-agents)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "foundations-narrow-daemons-and-agent-graphs",
      "slug": "narrow-daemons-and-agent-graphs",
      "title": "Build narrow daemons and inspectable agent graphs",
      "summary": "Run focused background daemons that update a human-readable HTML dashboard; Use low-reasoning iteration with a deliberately small-context strategy; Coordinate SDK multi-agent graphs with a multimodal verification loop.",
      "category": "Execution",
      "tags": [
        "daemons",
        "SDK",
        "low reasoning"
      ],
      "sources": [
        {
          "label": "Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-09.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#09/objectives",
        "oracle/09-references.json#recap",
        "oracle/09-references.json#concepts/0",
        "oracle/09-references.json#concepts/1",
        "oracle/09-references.json#concepts/2",
        "oracle/09-references.json#concepts/3",
        "oracle/09-references.json#concepts/4",
        "oracle/09-references.json#concepts/5",
        "oracle/09-references.json#concepts/6",
        "oracle/09-references.json#references",
        "oracle/09-references.json#recommendations",
        "oracle/09-interactive.json#intro",
        "oracle/09-interactive.json#checklist",
        "oracle/09-interactive.json#challenges",
        "oracle/09-interactive.json#quiz",
        "oracle/09-interactive.json#reflect",
        "oracle/09-references.json#goDeeper",
        "materials/exercises.md#Chunk-09",
        "materials/qa-index.md#Q042",
        "materials/qa-index.md#Q043",
        "materials/qa-index.md#Q044",
        "materials/qa-index.md#Q045",
        "materials/qa-index.md#Q046",
        "materials/qa-index.md#Q047",
        "materials/qa-index.md#Q048",
        "materials/keyframes.md#Chunk-09",
        "lesson-09.html#resource-packet",
        "lesson-09.html#clip-map",
        "lesson-09.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 3126,
      "url": "/topics/foundations-narrow-daemons-and-agent-graphs/",
      "markdownUrl": "/markdown/foundations-narrow-daemons-and-agent-graphs.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-narrow-daemons-and-agent-graphs.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "background-daemons",
          "text": "Background daemons",
          "level": 3
        },
        {
          "id": "low-reasoning-iteration",
          "text": "Low-reasoning iteration",
          "level": 3
        },
        {
          "id": "small-context-and-specialized-tool-context",
          "text": "Small context and specialized tool context",
          "level": 3
        },
        {
          "id": "self-improving-daemons",
          "text": "Self-improving daemons",
          "level": 3
        },
        {
          "id": "sdk-agent-graphs",
          "text": "SDK agent graphs",
          "level": 3
        },
        {
          "id": "multimodal-verification-loops",
          "text": "Multimodal verification loops",
          "level": 3
        },
        {
          "id": "agent-readable-code-structure",
          "text": "Agent-readable code structure",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "johnlindquist-codex-daemons",
          "text": "johnlindquist/codex-daemons",
          "level": 3
        },
        {
          "id": "openai-codex-sdk",
          "text": "@openai/codex-sdk",
          "level": 3
        },
        {
          "id": "bun",
          "text": "Bun",
          "level": 3
        },
        {
          "id": "prompt-quest-comic-demo",
          "text": "Prompt Quest comic demo",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "warm-html-dashboard-daemon",
          "text": "Warm HTML Dashboard Daemon",
          "level": 3
        },
        {
          "id": "low-reasoning-cli-specialist",
          "text": "Low-Reasoning CLI Specialist",
          "level": 3
        },
        {
          "id": "self-improving-narrow-tool-daemon",
          "text": "Self-Improving Narrow Tool Daemon",
          "level": 3
        },
        {
          "id": "sdk-agent-graph-with-analysis",
          "text": "SDK Agent Graph With Analysis",
          "level": 3
        },
        {
          "id": "multimodal-continuity-check",
          "text": "Multimodal Continuity Check",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "when-is-a-background-daemon-the-right-tool-in-this-lesson-s-workflow",
          "text": "When is a background daemon the right tool in this lesson's workflow?",
          "level": 3
        },
        {
          "id": "what-did-john-say-low-reasoning-needs-in-order-to-be-useful",
          "text": "What did John say low reasoning needs in order to be useful?",
          "level": 3
        },
        {
          "id": "when-did-john-say-you-should-reach-for-the-sdk",
          "text": "When did John say you should reach for the SDK?",
          "level": 3
        },
        {
          "id": "where-did-john-say-self-improving-daemon-patterns-fit-best",
          "text": "Where did John say self-improving daemon patterns fit best?",
          "level": 3
        },
        {
          "id": "what-should-happen-after-several-parallel-agents-produce-research-or-plans",
          "text": "What should happen after several parallel agents produce research or plans?",
          "level": 3
        },
        {
          "id": "what-is-the-point-of-the-multimodal-verification-loop-john-describes",
          "text": "What is the point of the multimodal verification loop John describes?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "exercise-1-build-a-self-aware-shebang-script",
          "text": "Exercise 1: Build a Self-Aware Shebang Script",
          "level": 3
        },
        {
          "id": "exercise-2-mathematical-layout-verification",
          "text": "Exercise 2: Mathematical Layout Verification",
          "level": 3
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "i-have-heard-a-few-people-say-that-low-reasoning-is-under-utilized-and-i-never-understood-that-till-now",
          "text": "I have heard a few people say that low reasoning is under utilized and I never understood that till now.",
          "level": 3
        },
        {
          "id": "do-you-ever-get-rate-limited-or-failures-when-running-things-in-parallel-with-that-tool",
          "text": "Do you ever get rate limited? Or failures? When running things in parallel with that tool?",
          "level": 3
        },
        {
          "id": "are-these-human-dashboards-ephemeral-or-persisted",
          "text": "Are these human dashboards ephemeral or persisted?",
          "level": 3
        },
        {
          "id": "do-you-have-any-good-resources-where-you-look-for-skills-plugins-clis-before-creating-your-own",
          "text": "Do you have any good resources where you look for skills, plugins, clis, before creating your own?",
          "level": 3
        },
        {
          "id": "on-self-improvement-thoughts-on-karpathy-auto-research-as-a-general-pattern",
          "text": "On self-improvement, thoughts on karpathy auto-research as a general pattern?",
          "level": 3
        },
        {
          "id": "isn-t-goal-kind-of-an-implementation-of-autoresearch",
          "text": "Isn’t /goal kind of an implementation of autoresearch?",
          "level": 3
        },
        {
          "id": "do-you-subscribe-to-the-thought-that-modules-should-be-under-500-lines-function-should-be-under-50-lines-classes-should-be-under-200-lines-or-anything-like-that",
          "text": "Do you subscribe to the thought that modules should be under 500 lines, function should be under 50 lines, classes should be under 200 lines or anything like that?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Build narrow daemons and inspectable agent graphs\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe focus is focused Codex daemons: small background helpers that can update a human-facing dashboard, keep their own threads and settings warm through the SDK, and work best when their scope and context stay small. John then extends the pattern to self-improving agents for narrow CLIs/APIs, SDK-built agent graphs with analysis steps, and verification loops for UI layout and generated images.\n\n## Working outcomes\n\n- Run focused background daemons that update a human-readable HTML dashboard\n- Use low-reasoning iteration with a deliberately small-context strategy\n- Coordinate SDK multi-agent graphs with a multimodal verification loop\n\n## Concepts and consequences\n\n### Background daemons\n\nThe “human” daemon runs behind the main session. At each hook, it updates an HTML page from the conversation so far, tracks tool calls, customizes the page for the current work, and gives John a summary when it is done. Right now that dashboard is ephemeral and written to a temp directory, but John says it could be persisted.\n\n**Why it matters:** A daemon is useful when a narrow support task should keep running without interrupting the main session.\n\n### Low-reasoning iteration\n\nJohn says low reasoning is underutilized, but it needs a different style of prompting. You should expect it to fail while you dial it in, because it will not deeply think through ambiguous work on its own. It works better when the job is narrow and the prompt accounts for the specific tool, CLI, API, or failure modes involved.\n\n**Why it matters:** Small, focused low-reasoning runs can be useful for high-frequency automation when the prompt and tool scope are explicit.\n\n### Small context and specialized tool context\n\nJohn repeatedly frames these daemon runs as small compared with normal Codex/GPT sessions, mentioning a target of staying under about 10,000 tokens of context. He also uses the Vercel plugin story to show that giving a weaker model the right tools and focused context can outperform a stronger model without that context.\n\n**Why it matters:** Narrow context lowers usage and keeps the model focused on the job it was built to do.\n\n### Self-improving daemons\n\nJohn shows the self-improve idea: when each turn ends, the daemon reads the transcript, looks for ways it can improve, finds its own file, and updates its own prompts or source. He says this is much more plausible for specific CLIs, tools, or APIs with clear tasks and predictable failure modes than for large projects that can branch in many directions.\n\n**Why it matters:** For narrow tools, repeated failures can become better operating instructions for future runs.\n\n### SDK agent graphs\n\nJohn says the SDK is the right tool when you need custom agents with managed threads, managed settings, warm background behavior, and structured workflows. He describes workflows where one agent hands work to another, branches into parallel research agents, then uses an analysis step to choose or synthesize the best plans before implementation.\n\n**Why it matters:** The SDK is useful when the workflow has explicit roles, sequencing, branching, fan-out, or fan-in that should be locked into code instead of improvised in one chat.\n\n### Multimodal verification loops\n\nJohn explains a comic-generation workflow where Codex generates an image, then reads the generated image back in and compares it to previous images. The verification pass can check continuity details such as whether a character has legs or whether counts match across frames. He also discusses asking UI work to return mathematical payloads for padding, margins, spacing, and layout.\n\n**Why it matters:** Generated artifacts should be inspected against concrete constraints instead of trusted after one prompt.\n\n### Agent-readable code structure\n\nWhen asked about file and function line limits, John rejects arbitrary size rules. The guideline he gives is to prefer state machines, named switch cases, and English-labeled conditions over dense conditional structures.\n\n**Why it matters:** Agents can read, verify, and reason about code more reliably when the control flow exposes human-readable state names.\n\n## Reference tools and resources\n\n### johnlindquist/codex-daemons\n\nThe repo John shows for background daemon setup and single-purpose Codex daemon scripts.\n\n**Use when:** Use it when you want to inspect or adapt the daemon pattern John discusses: clone the repo, install with Bun, and expose the executables on your path.\n\n[Reference](https://github.com/johnlindquist/codex-daemons)\n\n### @openai/codex-sdk\n\nThe SDK John says to reach for when building custom agents with managed threads, managed settings, warm daemon behavior, or structured agent graphs.\n\n**Use when:** Use it when a workflow needs explicit sequencing, branching, parallel roles, or handoffs between agents.\n\n[Reference](https://www.npmjs.com/package/@openai/codex-sdk)\n\n### Bun\n\nThe runtime John identifies as a prerequisite for the daemon shebang files and setup flow.\n\n**Use when:** Use it to install and run the daemon scripts shown in the repo setup instructions.\n\n[Reference](https://bun.sh)\n\n### Prompt Quest comic demo\n\nJohn’s comic example used to explain image continuity and multimodal verification loops.\n\n**Use when:** Use it as inspiration for workflows that generate an artifact, inspect it, compare it to references, and continue only when the checks pass.\n\n[Reference](https://www.dev.build/comics/prompt-quest/0?page=5)\n\n## Recommendations and best practices\n\n- Build daemons around narrow jobs, not vague all-purpose assistants. A dashboard updater, CLI specialist, or platform-specific helper is easier to prompt and trust than one giant agent.\n- Use low reasoning only with explicit prompting and narrow scope. Expect iteration while you dial in the prompt, because the model will not reliably infer the full workflow on its own.\n- Keep daemon context small. John’s target in this section is under about 10,000 tokens, with only the context and tools the daemon actually needs.\n- Reach for the SDK when you need managed threads, managed settings, warm background behavior, or a workflow where agents hand work to other agents.\n- Apply self-improvement first to narrow CLIs, tools, or APIs with clear failure modes. Large projects can branch too many ways for simple self-improvement to stay clean.\n- Do not spawn many agents unless you also design the analysis or synthesis step. Parallel work without review leaves the human with a pile of artifacts.\n- Use verification loops for generated artifacts. For UI, ask for concrete layout numbers; for images, feed the generated result back in and compare counts, continuity, and constraints.\n- For code that agents will read, prefer state machines, named cases, and English-readable conditions over arbitrary line-count rules.\n\n## Practice and acceptance criteria\n\nPractice designing focused Codex daemons and SDK agent workflows that stay narrow, warm, observable, and verified.\n\n### Checklist\n\n1. Pick one narrow daemon job you actually need, such as updating an HTML dashboard, summarizing turns, wrapping a specific CLI, or tracking tool calls.\n2. Write the daemon prompt so the job, tool scope, expected behavior, and likely failure modes are explicit.\n3. Use SDK-style managed threads and settings only when the workflow needs warm background behavior, agent handoffs, branching, or role-specific agents.\n4. Keep the daemon's context small, aiming under about 10,000 tokens and avoiding unrelated tool or plugin context.\n5. For a human-facing daemon, record the latest summary, conversation state, and tool calls in an HTML dashboard.\n6. For a self-improving daemon, start with a narrow CLI, tool, or API where failures are specific enough to improve prompts or tool-call guidance.\n7. For multi-agent workflows, include an analysis or synthesis step after parallel workers before implementation continues.\n8. For generated images or UI, add a verification pass that checks concrete details such as counts, continuity, padding, margins, or spacing.\n9. For code that agents will inspect, prefer named states, switch cases, and English-readable conditions over deeply nested conditionals.\n\n### Warm HTML Dashboard Daemon\n\n**Difficulty:** Easy\n\nBuild a tiny background daemon that watches a local session log and updates an HTML dashboard with the latest summary, conversation state, and tool calls.\n\n**Done when:** After three separate interactions, the HTML dashboard updates without you manually editing it and without interrupting your main Codex session.\n\n### Low-Reasoning CLI Specialist\n\n**Difficulty:** Medium\n\nCreate a focused wrapper for one CLI or tool you use often, such as Wrangler, Neon, the Vercel CLI, or another specific API-backed tool. Give it a narrow job, explicit instructions, and guidance for the common failure modes you expect.\n\n**Done when:** It completes five small scripted tasks and handles one intentionally bad input by explaining what failed instead of wandering into unrelated work.\n\n### Self-Improving Narrow Tool Daemon\n\n**Difficulty:** Medium\n\nPrototype a daemon for a narrow CLI or API that reads the latest transcript or log at the end of a turn and proposes one improvement to its own prompt or source instructions.\n\n**Done when:** After two repeated failures, it identifies the repeated pattern and produces a concise prompt/source improvement that you can inspect.\n\n### SDK Agent Graph With Analysis\n\n**Difficulty:** Hard\n\nDesign a small SDK-style workflow where one agent starts the task, several focused workers run in parallel, and an analysis agent compares their outputs before anything is implemented.\n\n**Done when:** The final result clearly shows which worker outputs were accepted, which were rejected or merged, and what the analysis step chose to pass forward.\n\n### Multimodal Continuity Check\n\n**Difficulty:** Hard\n\nCreate a small generation-and-verification loop for an image or UI artifact. Generate the artifact, inspect it, return concrete counts or layout values, and compare those values against the required constraints.\n\n**Done when:** The workflow catches at least one mismatch, such as a missing visual element, wrong count, or inconsistent spacing, before accepting the final artifact.\n\n## Questions to test understanding\n\n### When is a background daemon the right tool in this lesson's workflow?\n\n- **A.** When a narrow support task should run behind the main session\n- **B.** When one giant agent should own every tool and decision\n- **C.** When you want to maximize context for every prompt\n- **D.** When you want to avoid defining the daemon's job\n\n**Answer: A.** John’s “human” daemon runs in the background, updates an HTML dashboard at hooks, tracks tool calls, and summarizes the session without taking over the main work.\n\n### What did John say low reasoning needs in order to be useful?\n\n- **A.** A vague goal and freedom to infer the whole workflow\n- **B.** Every plugin and every possible context file\n- **C.** More explicit prompting, narrow scope, and iteration through failures\n- **D.** Only tasks that require deep strategic judgment\n\n**Answer: C.** John says low reasoning is underutilized, but it needs a lot of prompt detail and you should expect failures while you dial it in.\n\n### When did John say you should reach for the SDK?\n\n- **A.** For every normal one-off Codex question\n- **B.** When building custom agents with managed threads, settings, warm behavior, or agent graphs\n- **C.** Only when you want to avoid writing workflow logic\n- **D.** Only for image generation\n\n**Answer: B.** John frames the SDK as the tool for custom agents, managed threads/settings, warm background daemons, and structured workflows with handoffs or branches.\n\n### Where did John say self-improving daemon patterns fit best?\n\n- **A.** Specific CLIs, tools, or APIs with clear tasks and predictable failure modes\n- **B.** Large projects with many possible directions\n- **C.** Unscoped brainstorming chats\n- **D.** Any workflow where the agent should ignore its previous failures\n\n**Answer: A.** John says self-improvement is difficult in large projects but more plausible when the agent works against a narrow tool whose failures can be accounted for in prompts and tool calls.\n\n### What should happen after several parallel agents produce research or plans?\n\n- **A.** The human should manually sift through every artifact without help\n- **B.** An analysis or synthesis step should compare the outputs and choose or combine the best ones\n- **C.** Every worker should implement its own separate result\n- **D.** The workflow should always stop before implementation\n\n**Answer: B.** John describes workflows where parallel research agents feed into an analysis step that checks the plans and decides what should move forward.\n\n### What is the point of the multimodal verification loop John describes?\n\n- **A.** To trust the first generated image without checking it\n- **B.** To make image generation unrelated to previous frames\n- **C.** To feed the generated image back in, count or compare details, and verify continuity\n- **D.** To replace all UI checks with arbitrary line-count rules\n\n**Answer: C.** John explains that Codex can generate an image and then inspect that image against previous frames or reference images, checking concrete details such as counts and continuity.\n\n## Reflection prompts\n\n- Where in your current workflow are you using a large general agent when a small daemon with a narrow job would be cheaper and easier to trust?\n- Which tools, plugins, or context could be removed from one agent profile so it stays focused on its actual job?\n- Where would an analysis or synthesis step reduce artifact-sifting in a workflow that uses multiple agents?\n- What generated artifact in your workflow should be verified with concrete counts, layout values, or continuity checks before you trust it?\n- Where would named states or English-readable switch cases make your code easier for an agent to inspect than nested conditionals or arbitrary line-count rules?\n\n## Further applications\n\n1. Inspect one daemon file in the codex-daemons repo and identify what makes it narrow: its trigger, its context, its settings, and its output.\n2. Build a tiny daemon that updates an HTML dashboard from a local session log with the latest summary and tool-call state.\n3. Sketch one SDK workflow with a first agent, several parallel worker agents, an analysis step, and a final implementation step.\n4. Try a small multimodal verification loop: generate an image, ask a vision-capable pass to count or compare required elements, then regenerate only if the check fails.\n5. Refactor a small conditional-heavy module into named states or switch cases so an agent can read the control flow in clearer English.\n\n## Applied exercises\n\n### Exercise 1: Build a Self-Aware Shebang Script\n\n**Objective:**  Create a local executable file using BUN that reads its own file block on failure and alters its own instruction prompt.\n\n**Requirements:** Write a basic shell-executable script utilizing a #!/usr/bin/env bun shebang line.Integrate a small hook that passes the current execution log file straight to a low-reasoning LLM completion endpoint.Instruct the script to rewrite its internal system prompt string if a failure signature is detected.\n\n### Exercise 2: Mathematical Layout Verification\n\n**Objective:**  Build a QA assertion script that verifies a component UI layout against strict structural bounds rather than visual guesswork.\n\n**Requirements:** Design a mock UI rendering block outputting Tailwind CSS utility classes.Write an agent extraction prompt requiring Codex to parse the raw markup and isolate all padding, margin, and alignment variables into a structured JSON payload.Create an assertion step evaluating if the extracted values strictly conform to a standardized geometric spacing layout scale.\n\n## Questions and answers\n\n### I have heard a few people say that low reasoning is under utilized and I never understood that till now.\n\nLow reasoning requires a different approach. You have to expect it to fail a bunch initially before you get it exactly where you want it. It isn’t going to independently think through complex problems, so you must write precise prompts and account for explicit tool failures ahead of time. However, it uses very small footprints compared to huge model passes, keeping interactions well under 10,000 tokens of context. \n\n### Do you ever get rate limited? Or failures? When running things in parallel with that tool?\n\nNo, I haven't been rate-limited with this approach at all. The context usage is exceptionally small compared to normal prompt loops run inside major general-purpose sessions—it's barely a drop in the bucket. \n\nThis is an observation about John’s small-context setup, not a guarantee that parallel work cannot hit rate limits.\n\n### Are these human dashboards ephemeral or persisted?\n\nRight now they write to a local temp directory, making them ephemeral. However, you can cleanly persist them. The instructions are included inside the repository: you just clone the repo, run bun install, and execute unlink to place the executables directly onto your global path system. \n\nCommand caveat: the Q&A wording says `unlink`, but the concrete daemon setup instructions use `bun link` to add executables to PATH. Follow the command reference rather than interpreting `unlink` as installation.\n\n### Do you have any good resources where you look for skills, plugins, clis, before creating your own?\n\nJohn highlights two primary on-screen resources for the AI workspace context: skills.sh and the Codex Awesome Plugins ecosystem repository. \n\n### On self-improvement, thoughts on karpathy auto-research as a general pattern?\n\nI haven't implemented it directly yet, but it is firmly on my list. We can definitely construct tailored background daemons around this pattern to execute autonomous research loops for active projects. It fits neatly into the concept of agents reading their own source to iterate past failures. \n\n### Isn’t /goal kind of an implementation of autoresearch?\n\nThey are closely aligned. The beauty of the /goal implementation in GPT-5.5 is its clean interface—putting it behind a keyword slash command works incredibly well. I am working on adding a tracking plugin to my /goal usage that saves metrics on tool calls, execution effort, and compaction events so that subsequent agent passes can look back at historic execution paths. \n\n### Do you subscribe to the thought that modules should be under 500 lines, function should be under 50 lines, classes should be under 200 lines or anything like that?\n\nNo, I don't follow or subscribe to arbitrary line count rules. The single most important code style structure for agent workflows is to avoid deep conditional chains and use explicit state machines or named switch statements instead. When you choose clear English naming keys inside your code structures over complex syntax trees, the reading agents can interpret the underlying execution paths far more effectively. \n\n## Operational playbooks\n\n- [Isolated Codex daemon profile](/topics/foundations-daemon-profile-playbook/)\n\n- [Codex Daemon Profile Field Guide](/topics/foundations-daemon-profiles-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-09.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-09.html)\n\n### Visual reference index\n\n- [03:58:04](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-1): Terminal workspace around the background daemon discussion; dashboard output is not clearly visible in this still.\n- [04:00:44](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-2): Screen view of John typing the pro browser automate OpenX.com... command parameters inside the shell prompt.\n- [04:01:40](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-3): Display of the daemon project repository instructions containing setup steps for bun install and path unlinking.\n- [04:02:35](https://codex-workshop-followup.pages.dev/lesson-09.html#clip-09-4): Code layout showing a self-improving shebang daemon file reading its own source script context.\n- [04:04:54](https://codex-workshop-followup.pages.dev/lesson-09.html): Code/repository view during the community registry discussion; skills.sh/plugin-list claims should remain transcript evidence unless a closer browser still is selected.\n- [04:13:00](https://codex-workshop-followup.pages.dev/lesson-09.html): Dark editor/workspace view during SDK-vs-UI workflow discussion; graph-chain specifics are transcript evidence here.\n- [04:17:30](https://codex-workshop-followup.pages.dev/lesson-09.html): n8n-style workflow graph page visible during layout/automation discussion.\n- [04:19:12](https://codex-workshop-followup.pages.dev/lesson-09.html): Browser display of the comic layout via dev.build showing character image coherence validation passes."
    },
    {
      "id": "foundations-cmux-orchestration-field-guide",
      "slug": "cmux-orchestration-field-guide",
      "title": "CMUX Orchestration Field Guide",
      "summary": "Use panes, browser tabs, and a manager agent without letting workers step on each other.",
      "category": "Execution",
      "tags": [
        "field guide",
        "cmux orchestration"
      ],
      "sources": [
        {
          "label": "Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-02.html"
        },
        {
          "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#cmux-orchestration/overview",
        "field-guides/guides.mjs#cmux-orchestration/decision",
        "field-guides/guides.mjs#cmux-orchestration/agentPrompt",
        "field-guides/guides.mjs#cmux-orchestration/stories",
        "field-guides/guides.mjs#cmux-orchestration/tips",
        "field-guides/guides.mjs#cmux-orchestration/refs"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 383,
      "url": "/topics/foundations-cmux-orchestration-field-guide/",
      "markdownUrl": "/markdown/foundations-cmux-orchestration-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-cmux-orchestration-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "route-migration-split",
          "text": "Route migration split",
          "level": 3
        },
        {
          "id": "bug-bash-control-room",
          "text": "Bug bash control room",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# CMUX Orchestration Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nUse panes, browser tabs, and a manager agent without letting workers step on each other.\n\nUse this when one Codex session should coordinate multiple focused workers, a dev server, and browser verification.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| Manager pane | Human-facing planning and delegation | One agent owns status and decisions | .notes/cmux-manager.md |\n| Worker pane | Narrow research or implementation slice | One task, one output file | .notes/workers/<name>.md |\n| Browser pane | Local rendered proof | Keep visible app state nearby | .notes/browser-proof/<task>.md |\n| Server pane | Long-running dev server | Keep logs stable and inspectable | .notes/server-log.md |\n\n## Agent-ready prompt\n\n```text\nAct as the CMUX manager.\nInspect the current repo and create a pane plan before opening workers.\nEach worker gets one bounded task, writes one markdown receipt, and does not edit outside its assigned files.\nKeep a dev-server pane and browser-proof pane visible for web work.\nCollate findings into .notes/cmux-summary.md before asking me for decisions.\n```\n\n## Applied stories\n\n### Route migration split\n\n**Role:** Full-stack lead\n\nA Next.js migration needs source audit, implementation, browser proof, and docs update in parallel.\n\n**Agent brief:** Manager opens workers for route audit, component patch, browser proof, and docs. Only manager summarizes and asks for decisions.\n\n**Done when:**\n\n- worker receipts\n- server log\n- browser proof\n- single manager summary\n\n### Bug bash control room\n\n**Role:** Frontend lead\n\nSeveral agents should explore different app personas without losing track.\n\n**Agent brief:** Assign each pane a persona and require numbered findings, screenshots, severity, and reproducibility.\n\n**Done when:**\n\n- per-persona QA files\n- deduped summary\n- known false positives removed\n\n## Tips and gotchas\n\n- Give every pane a name and a single owner.\n- Use workers for gathering and narrow edits; keep decisions in the manager pane.\n- Put servers behind panes that need them so logs do not disappear.\n- Have Codex read worker screens/files back before summarizing.\n\n## References\n\n- [CMUX](https://cmux.com/)\n- [cmux extensions](https://github.com/johnlindquist/cmux-extensions)\n- [Zellij](https://zellij.dev/)\n\n## Related principles\n\n- [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/)\n- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)"
    },
    {
      "id": "foundations-daemon-profiles-field-guide",
      "slug": "daemon-profiles-field-guide",
      "title": "Codex Daemon Profile Field Guide",
      "summary": "Turn repeated web-dev chores into narrow, cheap, low-context Codex workers.",
      "category": "Execution",
      "tags": [
        "field guide",
        "daemon profiles"
      ],
      "sources": [
        {
          "label": "Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-09.html"
        },
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#daemon-profiles/overview",
        "field-guides/guides.mjs#daemon-profiles/decision",
        "field-guides/guides.mjs#daemon-profiles/agentPrompt",
        "field-guides/guides.mjs#daemon-profiles/stories",
        "field-guides/guides.mjs#daemon-profiles/tips",
        "field-guides/guides.mjs#daemon-profiles/refs"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 371,
      "url": "/topics/foundations-daemon-profiles-field-guide/",
      "markdownUrl": "/markdown/foundations-daemon-profiles-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-daemon-profiles-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "preview-deploy-checker",
          "text": "Preview deploy checker",
          "level": 3
        },
        {
          "id": "log-triage-worker",
          "text": "Log triage worker",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Codex Daemon Profile Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nTurn repeated web-dev chores into narrow, cheap, low-context Codex workers.\n\nUse this when a repeated CLI or browser-adjacent task deserves its own focused Codex profile instead of a full general agent.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| Daemon profile | Repeated narrow task | Preview deploy checks, log triage, changelog drafting | profiles/pro-<tool>.ts |\n| Fake CODEX_HOME | Hard isolation | Disable memories/MCP/plugins unless needed | .codex-daemon-home/ |\n| Command map | Small tool vocabulary | Literal tasks with predictable outputs | README plus examples |\n\n## Agent-ready prompt\n\n```text\nDesign a narrow Codex daemon profile for this repeated task.\nUse one command map, one output shape, low reasoning by default, and no broad memory/MCP/plugin access unless required.\nKeep it read-only first.\nWrite docs, examples, and a smoke test before using it on a real repo.\n```\n\n## Applied stories\n\n### Preview deploy checker\n\n**Role:** Frontend lead\n\nEvery PR needs preview status, changed-route browser proof, and a short verdict.\n\n**Agent brief:** Create a read-only deploy-check profile that discovers preview URL, opens changed routes, and writes a browser receipt.\n\n**Done when:**\n\n- profile file\n- command map\n- read-only proof\n- smoke test\n\n### Log triage worker\n\n**Role:** On-call engineer\n\nA local dev server spews logs and general Codex wastes context reading everything.\n\n**Agent brief:** Create a profile that tails, filters, summarizes, and writes exact blocker text for the main Codex session.\n\n**Done when:**\n\n- filtered log\n- blocker summary\n- no source edits\n- handoff path\n\n## Tips and gotchas\n\n- A daemon profile should be boring: one job, one command map, one output format.\n- Disable unrelated memories, MCPs, apps, and skills to keep context small.\n- Start read-only; add mutation only after a smoke test proves the profile is scoped.\n- Use low reasoning for literal CLI wrappers and reserve smarter models for ambiguous planning.\n\n## References\n\n- [codex-daemons](https://github.com/johnlindquist/codex-daemons)\n- [Codex SDK](https://developers.openai.com/codex/sdk)\n- [Codex MCP](https://developers.openai.com/codex/mcp)\n\n## Related principles\n\n- [Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n- [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)"
    },
    {
      "id": "foundations-context-triad-and-overnight-work",
      "slug": "context-triad-and-overnight-work",
      "title": "Combine intent, implementation, and output for autonomous work",
      "summary": "Bundle the context triad — intent, implementation, and live output — for diagnosis; Run specialized Codex daemons as overnight emulated crons; Coordinate agents through natural-language loose coupling.",
      "category": "Execution",
      "tags": [
        "context triad",
        "overnight",
        "goals"
      ],
      "sources": [
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#10/objectives",
        "oracle/10-references.json#recap",
        "oracle/10-references.json#concepts/0",
        "oracle/10-references.json#concepts/1",
        "oracle/10-references.json#concepts/2",
        "oracle/10-references.json#concepts/3",
        "oracle/10-references.json#concepts/4",
        "oracle/10-references.json#concepts/5",
        "oracle/10-references.json#references",
        "oracle/10-references.json#recommendations",
        "oracle/10-interactive.json#intro",
        "oracle/10-interactive.json#checklist",
        "oracle/10-interactive.json#challenges",
        "oracle/10-interactive.json#quiz",
        "oracle/10-interactive.json#reflect",
        "oracle/10-references.json#goDeeper",
        "materials/exercises.md#Chunk-10",
        "materials/qa-index.md#Q049",
        "materials/qa-index.md#Q050",
        "materials/qa-index.md#Q051",
        "materials/qa-index.md#Q052",
        "materials/qa-index.md#Q053",
        "materials/qa-index.md#Q054",
        "materials/qa-index.md#Q055",
        "materials/qa-index.md#Q056",
        "materials/qa-index.md#Q057",
        "final/qa-index.md#Chunk-10",
        "materials/keyframes.md#Chunk-10",
        "lesson-10.html#resource-packet",
        "lesson-10.html#clip-map",
        "lesson-10.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 3162,
      "url": "/topics/foundations-context-triad-and-overnight-work/",
      "markdownUrl": "/markdown/foundations-context-triad-and-overnight-work.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-context-triad-and-overnight-work.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "context-triad-intent-implementation-output",
          "text": "Context triad: intent, implementation, output",
          "level": 3
        },
        {
          "id": "qa-artifacts-as-live-application-evidence",
          "text": "QA artifacts as live application evidence",
          "level": 3
        },
        {
          "id": "specialized-agents-and-codex-daemons",
          "text": "Specialized agents and Codex daemons",
          "level": 3
        },
        {
          "id": "short-goal-files-and-oracle-generated-plans",
          "text": "Short /goal files and Oracle-generated plans",
          "level": 3
        },
        {
          "id": "overnight-emulated-crons",
          "text": "Overnight emulated crons",
          "level": 3
        },
        {
          "id": "natural-language-loose-coupling",
          "text": "Natural-language loose coupling",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "packx",
          "text": "PackX",
          "level": 3
        },
        {
          "id": "codex-daemons",
          "text": "codex-daemons",
          "level": 3
        },
        {
          "id": "agent-browser",
          "text": "Agent Browser",
          "level": 3
        },
        {
          "id": "oracle",
          "text": "Oracle",
          "level": 3
        },
        {
          "id": "screenpipe",
          "text": "ScreenPipe",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "build-a-context-triad-debug-bundle",
          "text": "Build a Context Triad Debug Bundle",
          "level": 3
        },
        {
          "id": "write-a-plain-english-goal-flow",
          "text": "Write a Plain-English Goal Flow",
          "level": 3
        },
        {
          "id": "design-an-overnight-investigation-loop",
          "text": "Design an Overnight Investigation Loop",
          "level": 3
        },
        {
          "id": "draft-a-specialized-codex-daemon-brief",
          "text": "Draft a Specialized Codex Daemon Brief",
          "level": 3
        },
        {
          "id": "turn-a-meeting-transcript-into-workflow-feedback",
          "text": "Turn a Meeting Transcript into Workflow Feedback",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "a-web-app-test-is-failing-but-the-source-code-alone-does-not-make-the-cause-obvious-what-context-bundle-gives-codex-the-best-chance-of-diagnosing-it",
          "text": "A web app test is failing, but the source code alone does not make the cause obvious. What context bundle gives Codex the best chance of diagnosing it?",
          "level": 3
        },
        {
          "id": "what-is-john-s-practical-point-about-planner-builder-researcher-and-validator-style-responsibilities",
          "text": "What is John’s practical point about Planner, Builder, Researcher, and Validator-style responsibilities?",
          "level": 3
        },
        {
          "id": "what-is-the-key-safety-and-control-feature-of-an-overnight-emulated-cron-prompt",
          "text": "What is the key safety and control feature of an overnight emulated cron prompt?",
          "level": 3
        },
        {
          "id": "in-this-section-what-did-john-actually-teach-about-codex-daemons",
          "text": "In this section, what did John actually teach about Codex daemons?",
          "level": 3
        },
        {
          "id": "what-does-natural-language-loose-coupling-mean-in-this-lesson",
          "text": "What does natural-language loose coupling mean in this lesson?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "assuming-convex-improvement-in-intelligence-are-you-saving-prototypes-ideas-convos-second-brain-now-so-future-smarter-models-and-better-tools-can-synthesize-and-build-them-later-or-are-you-planning-for-future-in-any-way",
          "text": "assuming convex improvement in intelligence, Are you saving prototypes/ideas/convos/second-brain now, so future smarter models and better tools can synthesize and build them later? or are you planning for future in any way?",
          "level": 3
        },
        {
          "id": "what-are-your-thoughts-on-learning-new-skills-how-do-you-use-ai-to-either-accelerate-it-or-optimize-for-something-else-i",
          "text": "What are your thoughts on learning new skills. How do you use AI to either accelerate it or optimize for something else? I",
          "level": 3
        },
        {
          "id": "do-you-use-agents-md-or-claude-md-guardrails-md-don-t-do-this-tool-usage-specificity-etc",
          "text": "do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc",
          "level": 3
        },
        {
          "id": "can-you-give-some-examples-on-how-you-prompt-goal",
          "text": "can you give some examples on how you prompt /goal?",
          "level": 3
        },
        {
          "id": "any-thoughts-on-security-for-example-this-minimum-package-age-setting-in-pnpm-seems-to-be-an-idea-people-are-converging-on",
          "text": "Any thoughts on security. For example this minimum package age setting in pnpm seems to be an idea people are converging on.",
          "level": 3
        },
        {
          "id": "in-your-view-what-does-a-practical-ai-sdlc-look-like-for-a-real-engineering-team-from-requirements-and-design-through-implementation-testing-deployment-and-maintenance",
          "text": "in your view, what does a practical AI SDLC look like for a real engineering team, from requirements and design through implementation, testing, deployment, and maintenance?",
          "level": 3
        },
        {
          "id": "are-you-using-only-agent-browser-or-also-playwright",
          "text": "are you using only agent-browser or also playwright?",
          "level": 3
        },
        {
          "id": "did-you-show-a-goal-example-for-the-packx-for-example-i-think-i-will-convert-400-of-my-tests-to-qa-or-packages-that-are-stable",
          "text": "Did you show a /goal example for the packx ? For example I think I will convert 400 of my tests to QA or packages that are stable.",
          "level": 3
        },
        {
          "id": "so-most-of-the-time-in-goal-you-don-t-define-how-the-agent-can-check-if-the-goal-is-achieved-correct",
          "text": "so most of the time in /goal you don't define how the agent can check if the goal is achieved, correct?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Combine intent, implementation, and output for autonomous work\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nJohn revisits PackX as a way to bundle QA artifacts so a model can compare intent, implementation, and output. He then talks through reusable specialized Codex daemon-style agents, short plain-English /goal files, Oracle-generated goal files for complex work, a timestamp-based workaround for overnight loops, and the importance of keeping team and tool workflows flexible through natural-language contracts.\n\n## Working outcomes\n\n- Bundle the context triad — intent, implementation, and live output — for diagnosis\n- Run specialized Codex daemons as overnight emulated crons\n- Coordinate agents through natural-language loose coupling\n\n## Concepts and consequences\n\n### Context triad: intent, implementation, output\n\nFor difficult debugging, John teaches bundling the expected behavior, the relevant code, and the observed runtime evidence. The evidence can include logs, console output, screenshots, traces, performance profiles, QA-script artifacts, and other files produced while the app is actually running.\n\n**Why it matters:** Models reason better when they can compare what should have happened, how the code attempted it, and what actually happened during execution.\n\n### QA artifacts as live application evidence\n\nJohn describes logs as a representation of the live app running and recommends shaping QA scripts and project-specific dev tools so they deliberately write useful artifacts. Those artifacts can then be bundled with code using PackX or another bundler for analysis by a stronger model.\n\n**Why it matters:** A model that sees real artifacts from a user flow can diagnose behavior instead of guessing from source files alone.\n\n### Specialized agents and Codex daemons\n\nJohn connects Planner, Builder, Researcher, and Validator-style responsibilities to specialized agents. His Codex daemon point in this section is high level: create custom, reusable agents for a specific project need, give them the relevant requirements, and reuse them instead of making one agent handle everything.\n\n**Why it matters:** Custom systems that understand your project can support workflows that generic shared skills may not cover.\n\n### Short /goal files and Oracle-generated plans\n\nJohn shows that many of his goal prompts are plain and short, such as asking for a specific layout fix. For complex work, he often asks Oracle to research the problem and generate a more detailed goal file, then drops that file into his `.goals` directory for Codex to run through research, implementation, and verification.\n\n**Why it matters:** Simple tasks do not need massive prompts, while complex tasks benefit from a stronger planning pass before Codex executes the work.\n\n### Overnight emulated crons\n\nBecause Codex does not have a built-in cron in this workflow, John describes writing a goal that creates a timestamp, repeats a task every 10 minutes, and continues until a fixed duration or target time such as 9 AM.\n\n**Why it matters:** This gives Codex a bounded long-running loop without pretending it is a real scheduler.\n\n### Natural-language loose coupling\n\nFor team workflows and tools, John recommends staying flexible: capture meetings and workflow complaints, iterate on how the team works, and prefer open-source, agent-first tools whose main contract is natural language. He uses the ability to abandon a tool easily as the point.\n\n**Why it matters:** Tools are changing quickly, so teams should avoid investing too heavily in brittle workflows tied to one vendor or interface.\n\n## Reference tools and resources\n\n### PackX\n\nA bundling tool John uses to package code, logs, screenshots, traces, and other artifacts into a single context bundle for model analysis.\n\n**Use when:** Reach for it when a difficult bug needs the full intent, implementation, and output picture instead of code alone.\n\n[Reference](https://www.npmjs.com/package/packx)\n\n### codex-daemons\n\nJohn’s specialized Codex daemon project/concept, discussed here at a high level as a way to create reusable agents customized for a project need.\n\n**Use when:** Study it when you want to build a focused reusable Codex helper instead of relying on one broad agent for every responsibility.\n\n[Reference](https://github.com/johnlindquist/codex-daemons)\n\n### Agent Browser\n\nA web-app verification tool John names as an example of collecting Chrome DevTools console logs and screenshots as live-run artifacts.\n\n**Use when:** Use this pattern when verifying a web project and you need browser evidence to bundle with source and intent.\n\n[Reference](https://www.npmjs.com/package/agent-browser)\n\n### Oracle\n\nJohn’s name in this workshop for a stronger planning and analysis workflow he uses to inspect bundles and generate detailed goal files.\n\n**Use when:** Use this pattern when a task is complex enough that you want research, implementation, and verification planned before handing the goal to Codex.\n\nsearch: John Lindquist Oracle Codex goal files\n\n### ScreenPipe\n\nA tool John uses as an example of capturing observational screen data so an agent can analyze how you work and suggest workflow improvements.\n\n**Use when:** Consider the pattern when you want to feed agents relevant observational data about your work; in this section it was an example, not a Codex daemon requirement.\n\nsearch: ScreenPipe screen recording workflow analysis\n\n## Recommendations and best practices\n\n- For hard bugs, do not send code alone. Bundle the stated intent, relevant implementation, and runtime output such as logs, screenshots, traces, performance profiles, and console errors.\n- Shape QA scripts and project-specific dev tools to produce artifacts deliberately; do not wait until a failure and then wish you had logs.\n- Use short, plain-English `/goal` prompts for simple tasks. John’s examples were not hyper-specific; they named the concrete thing to fix or investigate.\n- For complex work, have a stronger planning or research pass produce a goal file, then run that file from `.goals/` so the research context flows into implementation and verification.\n- Use specialized Codex daemon-style agents for recurring project roles, but keep the claim high-level: customize the agent with requirements and reuse it.\n- For overnight work, write the loop into the goal with a timestamp, interval, and stop point such as four hours later or 9 AM.\n- For team workflows, capture meeting or stand-up transcripts, look for repeated complaints or friction, and keep tool contracts flexible enough to swap tools when the ecosystem changes.\n\n## Practice and acceptance criteria\n\nPractice building evidence-rich context bundles, short goal files, specialized Codex helpers, and bounded overnight loops without turning them into one giant magical agent.\n\n### Checklist\n\n1. Choose one small repo task that has a visible outcome, such as a failing test, broken UI flow, flaky script, or dependency investigation.\n2. Write a short plain-English goal for the task: what to inspect, what result you want, and any obvious constraints.\n3. Create an `intent.md` file with 2-4 sentences describing the expected behavior and specific success criteria.\n4. Run the relevant command or user flow and save the real output to an artifact such as `execution.log`, `console.log`, `trace.txt`, or a screenshot.\n5. Bundle the intent, relevant source files, and runtime output into one inspectable context package using PackX or a simple manual text bundle.\n6. Ask the model to compare intent, implementation, and output and identify where the mismatch starts.\n7. For a complex task, ask a stronger planning or research pass to generate a goal file that includes research, implementation, and verification.\n8. For any repeated or overnight run, add a timestamp, interval, and fixed stop condition before starting.\n\n### Build a Context Triad Debug Bundle\n\n**Difficulty:** Easy\n\nPick one failing test or bug. Create `intent.md`, capture the failing command output into `execution.log`, include the smallest relevant source files, and ask Codex to identify where output diverges from intent.\n\n**Done when:** Codex can point to a specific mismatch between expected behavior, implementation, and runtime evidence instead of giving generic advice.\n\n### Write a Plain-English Goal Flow\n\n**Difficulty:** Medium\n\nTake a medium-sized change and draft a short `/goal` that asks for research, implementation, and verification. Name the artifact or tool that should prove the result, such as logs, tests, browser output, screenshots, traces, or a QA script.\n\n**Done when:** The goal is short enough to understand quickly, but clear enough that the agent knows what to investigate, what to change, and how to verify it.\n\n### Design an Overnight Investigation Loop\n\n**Difficulty:** Medium\n\nWrite a `.goals/overnight-investigation.md` file that tells Codex to create a timestamp, run an investigation every 10 minutes, record findings, and stop after a fixed duration or target clock time.\n\n**Done when:** The goal file contains the loop interval, artifact path, and stop condition, and it does not describe an unbounded keep-working-forever task.\n\n### Draft a Specialized Codex Daemon Brief\n\n**Difficulty:** Hard\n\nChoose one recurring project need, such as planning a change, researching an API, verifying a web flow, or packaging context. Draft a brief for a reusable specialized Codex helper: what it is for, what project context it needs, and what output it should return.\n\n**Done when:** Another developer can tell exactly what the helper is for, when to use it, and what useful artifact it should produce.\n\n### Turn a Meeting Transcript into Workflow Feedback\n\n**Difficulty:** Medium\n\nTake a real or sample engineering meeting transcript and ask an agent to extract repeated complaints, workflow friction, what is working, and one concrete process improvement to discuss with the team.\n\n**Done when:** The output identifies specific team workflow issues from the transcript rather than producing generic AI SDLC advice.\n\n## Questions to test understanding\n\n### A web app test is failing, but the source code alone does not make the cause obvious. What context bundle gives Codex the best chance of diagnosing it?\n\n- **A.** The intended behavior, relevant source files, and actual runtime output such as logs, screenshots, traces, or console errors\n- **B.** The entire repository plus a request to find anything suspicious\n- **C.** Only the stack trace, because implementation details can bias the model\n- **D.** A short description of the bug with no files, so the model reasons from first principles\n\n**Answer: A.** John’s debugging bundle is intent, implementation, and output. Codex can reason much better when it can compare what should have happened against the code and what actually happened.\n\n### What is John’s practical point about Planner, Builder, Researcher, and Validator-style responsibilities?\n\n- **A.** They are flexible responsibilities you can use to clarify or split a workflow when the task gets complex\n- **B.** Every Codex workflow must always run exactly four separate agents\n- **C.** They eliminate the need to inspect logs, screenshots, traces, or other artifacts\n- **D.** They are only useful for non-code writing tasks\n\n**Answer: A.** John uses these as useful workflow responsibilities, not a rigid ceremony. He also says he often keeps research, implementation, and verification in one goal, then separates more as complexity grows.\n\n### What is the key safety and control feature of an overnight emulated cron prompt?\n\n- **A.** A request to use the most powerful model available\n- **B.** A broad instruction to keep improving the repo until there is nothing left to do\n- **C.** A clear timestamp-based loop with a fixed duration or target stop time\n- **D.** A requirement to rewrite the whole project before reporting back\n\n**Answer: C.** John describes creating a timestamp, doing work every 10 minutes, and stopping after a fixed duration or target time such as 9 AM.\n\n### In this section, what did John actually teach about Codex daemons?\n\n- **A.** They can be customized as reusable specialized agents for a specific project need\n- **B.** They are a replacement for collecting QA artifacts\n- **C.** They should all share one broad responsibility for planning, coding, testing, deployment, and communication\n- **D.** They are the same thing as a production cron scheduler\n\n**Answer: A.** John’s daemon point here is high level: create a specialized agent, give it the requirements it needs, and reuse it for that project responsibility.\n\n### What does natural-language loose coupling mean in this lesson?\n\n- **A.** Writing vague prompts so any tool can interpret them however it wants\n- **B.** Keeping the durable workflow contract in natural language so tools can be swapped later\n- **C.** Avoiding open-source tools because they change too quickly\n- **D.** Building deep proprietary integrations as early as possible\n\n**Answer: B.** John warns against over-investing in one fast-changing tool or vendor workflow. His point is to keep the contract between you and the tool flexible and mostly natural-language driven.\n\n## Reflection prompts\n\n- Where are you currently asking one goal or agent to do too much, and which responsibility would become clearer if you split it out?\n- For your hardest recurring bugs, which part of the context triad is usually missing: intent, implementation, or output?\n- Which QA or devtool artifact would make your live app behavior easier for a model to analyze?\n- Which parts of your workflow are too tightly coupled to one tool or vendor, and what would the natural-language contract look like if you had to swap that tool next month?\n\n## Further applications\n\n1. Build a PackX-style debugging bundle: `intent.md`, relevant source, `execution.log`, screenshots or traces if available, and a prompt asking where output diverges from intent.\n2. Modify one QA script so it deliberately emits artifacts a model can inspect later: logs, console output, screenshots, traces, performance profiles, or a short user-flow summary.\n3. Create a `.goals/` directory and save a few short goal files for real tasks; for one complex task, ask a planning model to generate the goal file instead of writing every detail yourself.\n4. Write an overnight goal that creates a timestamp, repeats a research or verification pass every 10 minutes, and stops at a fixed duration or target clock time.\n5. Draft a high-level specialized Codex daemon brief for one recurring project job: what the agent is for, what project context it needs, and what output or artifact it should return.\n6. Try the team-workflow loop John described: feed a meeting transcript into an agent and ask it to identify what is working, what is not, and what workflow changes the team should discuss.\n\n## Applied exercises\n\nExercise: Building an Intent-Implementation-Output Bundle\n\n**Objective:**  Manually replicate a PackX-style context container to help an external agent debug a local execution discrepancy.\n\n**Instructions:** Select a simple function in your local workspace that currently exhibits a bug or unexpected behavior.Create a clean file named intent.md and document what the code is intended to accomplish in two sentences.Run your program and pipe its runtime exceptions or logs directly into a file: npm run dev > execution.log or equivalent.Combine your raw target source code file, your intent.md instructions, and your execution.log outputs into a single text block.Pass this combined context bundle to your development model using the following prompt header:\"Analyze this context bundle. The intent, implementation, and output layers do not align. Identify the exact line where the execution output diverges from my intent.\"\n\n## Questions and answers\n\n### assuming convex improvement in intelligence, Are you saving prototypes/ideas/convos/second-brain now, so future smarter models and better tools can synthesize and build them later? or are you planning for future in any way?\n\nJohn believes precise long-term future planning is effectively impossible given the speed of changes. From a personal perspective, he uses agents to offload administrative burdens to preserve real-world human experiences (hiking, spending time with family). Professionally, he focuses on immediate, just-in-time contextual tracking (like scraping or parsing on demand) rather than heavy pre-engineered setups.\n\n### What are your thoughts on learning new skills. How do you use AI to either accelerate it or optimize for something else? I\n\nJohn highlights the power of specialized vocal and visual analysis agents. Instead of replacing the skill, these tools act as localized coaches—monitoring screen inputs, speaking registers, or physical sports form to detect precise areas of failure and generate personalized training plans.\n\n### do you use agents.md or claude.md, guardrails.md...? don't do this... tool usage specificity... etc\n\nLiving guardrail files are discussed alongside the terminal workflow. Use AGENTS.md or CLAUDE.md for discovered project boundaries; symlinking is one way John shares rules across harnesses. He favors adapting rules to real errors, not building rigid frameworks. See the contracts and state-machines topic for the fuller guardrail answer.\n\n### can you give some examples on how you prompt /goal?\n\nJohn displays his personal workspace markdown documents on screen. He reveals that his own hand-written goals are surprisingly short and plain-spoken (e.g., \"The buttons on the footer are misaligned. Please calculate the padding...\"). For highly complex workflows, he relies on an upstream model like Oracle to author detailed step-by-step goal files, which are dropped into a local .goals/ folder and run automatically.\n\n### Any thoughts on security. For example this minimum package age setting in pnpm seems to be an idea people are converging on.\n\nJohn notes that the security landscape for rapidly changing agent workflows appears exceptionally challenging, citing recent high-profile vulnerabilities like Mac kernel breaches. His primary operational advice is basic: keep environments updated, while acknowledging the inherent risks of supply chain tracking.\n\n### in your view, what does a practical AI SDLC look like for a real engineering team, from requirements and design through implementation, testing, deployment, and maintenance?\n\nA practical AI-driven SDLC relies heavily on team agility and continuous ambient context extraction. John recommends recording engineering meetings or stand-ups, converting them to clean transcripts, and feeding those directly into project agents to track active friction. Teams should avoid heavy lock-in to proprietary design tools, favoring open-source platforms bound by natural language interfaces.\n\n### are you using only agent-browser or also playwright?\n\n(Context confirms active rely on Agent Browser for console log bundling; specific tool trade-offs were not detailed further in this chunk).\n\n### Did you show a /goal example for the packx ? For example I think I will convert 400 of my tests to QA or packages that are stable.\n\nThe PackX example is the Oracle handoff skill. Bundle the intent, current implementation, and live output for diagnosis; for a large test migration, ask for a classified plan and implement verified slices. The companion does not capture a separate complete 400-test migration demonstration.\n\n### so most of the time in /goal you don't define how the agent can check if the goal is achieved, correct?\n\nCorrect for basic tasks, but for complex loops, the validation criteria are explicitly structured as a multi-step pipeline prefix (e.g., Oracle Research, Implement, and Verify) tied directly to custom verification tooling or browser instrumentation.\n\n## Operational playbooks\n\n- [Overnight emulated-cron loop](/topics/foundations-overnight-cron-playbook/)\n\n- [Oracle + PackX Handoff Field Guide](/topics/foundations-oracle-packx-field-guide/)\n- [Goal, Memory, and Context Hygiene Field Guide](/topics/foundations-goal-memory-field-guide/)\n- [Codex Daemon Profile Field Guide](/topics/foundations-daemon-profiles-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-10.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-10.html)\n\n### Visual reference index\n\n- [04:22:45](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-1): Terminal mapping execution output directly to a data log file ta\n- [04:23:25](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-2): Text overview tracking the interaction loops between oracle pack\n- [04:24:40](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-3): Core listing on screen breaking down the verification triad elem\n- [04:36:15](https://codex-workshop-followup.pages.dev/lesson-10.html#clip-10-4): Code surface overview detailing screenpipe setup logic and opera\n- [04:39:58](https://codex-workshop-followup.pages.dev/lesson-10.html): Editor display outlining production goal text documents placed i\n- [04:41:52](https://codex-workshop-followup.pages.dev/lesson-10.html): Ui panel showcasing image based design debugging instructions\n- [04:43:08](https://codex-workshop-followup.pages.dev/lesson-10.html): Automation script rendering showcasing multi hour task loops ini\n- [04:46:00](https://codex-workshop-followup.pages.dev/lesson-10.html): Terminal text showing connection flags routed to local infrastru"
    },
    {
      "id": "foundations-cmux-orchestrate-playbook",
      "slug": "cmux-orchestrate-playbook",
      "title": "Command a CMUX manager/worker layout playbook",
      "summary": "Web developers already juggle dev servers, test runners, browser verification, and agent chats; this pattern turns that chaos into one visible Manager pane coordinating narrow worker panes. It matters most when a local app needs code changes plus runtime proof, because the Manager can inspect panes, send targeted tasks, read worker output, and keep the human focused on decisions instead of pane babysitting.",
      "category": "Execution",
      "tags": [
        "CMUX",
        "orchestration",
        "delegation",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-02.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#cmux-orchestrate",
        "scenarios/cmux-orchestrate.json#audienceFit",
        "toolkit/prompts/02-cmux-manager-worker-layout.md",
        "toolkit/codex-skills/cmux-orchestrate/SKILL.md",
        "scenarios/cmux-orchestrate.json#scenarios/0",
        "scenarios/cmux-orchestrate.json#scenarios/1",
        "scenarios/cmux-orchestrate.json#scenarios/2",
        "scenarios/cmux-orchestrate.json#implementationNotes",
        "scenarios/cmux-orchestrate.json#notTaughtOrAvoid/1",
        "scenarios/cmux-orchestrate.json#notTaughtOrAvoid/2",
        "scenarios/cmux-orchestrate.json#notTaughtOrAvoid/3",
        "scenarios/cmux-orchestrate.json#notTaughtOrAvoid/4",
        "scenarios/cmux-orchestrate.json#notTaughtOrAvoid/5",
        "scenarios/cmux-orchestrate.json#agentReferences",
        "toolkit/bundles/code-cmux-cli.md"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 2916,
      "url": "/topics/foundations-cmux-orchestrate-playbook/",
      "markdownUrl": "/markdown/foundations-cmux-orchestrate-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-cmux-orchestrate-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "triage-a-broken-localhost-checkout-flow",
          "text": "Triage a broken localhost checkout flow",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "coordinate-a-design-drift-review-before-touching-css",
          "text": "Coordinate a design-drift review before touching CSS",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "run-a-bounded-afk-manager-check-in-on-parallel-workers",
          "text": "Run a bounded AFK manager check-in on parallel workers",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "existing-cmux-manager-worker-prompt",
          "text": "Existing CMUX manager/worker prompt",
          "level": 3
        },
        {
          "id": "cmux-orchestration-skill",
          "text": "CMUX orchestration skill",
          "level": 3
        },
        {
          "id": "verified-cmux-cli-command-map",
          "text": "Verified CMUX CLI command map",
          "level": 3
        },
        {
          "id": "lesson-02-validated-references",
          "text": "Lesson 02 validated references",
          "level": 3
        },
        {
          "id": "lesson-02-validation-notes",
          "text": "Lesson 02 validation notes",
          "level": 3
        },
        {
          "id": "command-reference",
          "text": "Command reference",
          "level": 2
        },
        {
          "id": "panes-layout",
          "text": "Panes / layout",
          "level": 2
        },
        {
          "id": "reading-sending",
          "text": "Reading / sending",
          "level": 2
        },
        {
          "id": "tabs-markdown-notifications",
          "text": "Tabs / markdown / notifications",
          "level": 2
        },
        {
          "id": "global-options-before-the-command",
          "text": "Global options (before the command)",
          "level": 2
        }
      ],
      "markdown": "# Command a CMUX manager/worker layout playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already juggle dev servers, test runners, browser verification, and agent chats; this pattern turns that chaos into one visible Manager pane coordinating narrow worker panes. It matters most when a local app needs code changes plus runtime proof, because the Manager can inspect panes, send targeted tasks, read worker output, and keep the human focused on decisions instead of pane babysitting.\n\n[Core principles](/topics/foundations-manager-worker-orchestration/)\n\n## Copy-paste workflow\n\n**When to use:** When you want to drive several agent panes in parallel but only talk to one. This sets up a Manager pane plus worker panes in CMUX using natural language; the Manager opens, inspects, and delegates to the workers while you only converse with the Manager.\n\n### Copy-paste prompt\n\n```text\nYou are the Manager agent running in my focused CMUX pane. I will only talk to you; you coordinate worker panes. Use the REAL cmux CLI (do not invent flags). Keep the upfront planning human-led — confirm the plan with me before delegating.\n\n1. Build the layout. Open a worker surface to the right and create additional worker panes as needed:\n     cmux new-split right\n     cmux new-pane\n   Name the tabs so they stay findable:\n     cmux rename-tab \"<role-name>\"\n\n2. Always inspect live state before acting on a worker:\n     cmux --json tree        # full pane/surface tree as JSON (focused pane, refs, cwd)\n     cmux list-panes         # enumerate worker panes\n\n3. Delegate a task into a worker surface, then read its output back as context:\n     cmux send -- \"<TASK TEXT FOR THAT WORKER>\"\n     cmux read-screen        # read that worker's terminal text back\n\n4. Loop: you (Manager) talk to me, workers do the research/implementation. Report status back to me; do not let workers drift without checking cmux --json tree.\n\nGuardrail: prefer PANES over tab groups — tab groups are easy to lose track of.\n```\n\n### How it works\n- `cmux new-split right` and `cmux new-pane` build the manager/worker layout; `cmux rename-tab \"<name>\"` keeps roles findable.\n- `cmux --json tree` returns the live window/workspace/pane/surface tree as JSON (focused pane, refs like `pane:89`/`surface:126`, working directory) — inspect it before acting.\n- `cmux list-panes` enumerates worker panes.\n- `cmux send -- \"<text>\"` injects a task into a worker surface; `cmux read-screen` reads that worker's terminal text back as context for the Manager.\n- The Manager talks to the human; workers do research/implementation. Keep upfront planning human-led.\n- Prefer panes over tab groups — tab groups are easy to lose track of.\n- Reference: [CMUX](https://cmux.com/).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/cmux-orchestrate/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: cmux-orchestrate\ndescription: Trigger when the user wants to drive multiple terminal/agent panes in CMUX from natural language — build manager/worker layouts, open/arrange panes, inspect or send work to other panes. Do NOT trigger outside a CMUX workspace.\n---\n\n# CMUX orchestration\n\nAct as the Manager agent: build a pane layout, inspect live state, and delegate work to worker panes using the REAL cmux CLI. Do not invent flags. Inspect with `cmux --json tree` before acting.\n\n## Command map (real cmux CLI)\n\n```bash\ncmux new-split <left|right|up|down>   # split from the focused surface in a direction\ncmux new-pane                         # create a pane (terminal or browser content)\ncmux --json tree                      # full window/workspace/pane/surface tree as JSON\ncmux list-panes                       # enumerate panes in the workspace\ncmux send -- \"<text>\"                 # send a task into a terminal surface\ncmux read-screen                      # read a surface's terminal text back as context\ncmux rename-tab \"<name>\"              # name a tab so it stays findable\ncmux focus-pane <ref>                 # focus a pane (ref like pane:89 or surface:126)\n```\n\nHandles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes.\n\n## Manager-worker pattern\n1. Build the layout: `cmux new-split right`, then `cmux new-pane` for each worker; name them with `cmux rename-tab \"<role>\"`.\n2. Before acting on any worker, inspect live state: `cmux --json tree` (focused pane, refs, cwd) and `cmux list-panes`.\n3. Delegate work: `cmux send -- \"<task>\"` into a worker, then `cmux read-screen` to pull its output back as context.\n4. You (Manager) talk to the human; workers do research/implementation. Report status back.\n\n## Guardrails\n- Prefer PANES over tab groups — tab groups are easy to lose track of.\n- Only use inside a CMUX workspace.\n````\n\n## Scenarios\n\n### Triage a broken localhost checkout flow\n\n**Role:** As a full-stack Next.js developer shipping a checkout fix\n\nA Next.js storefront runs locally, the checkout route intermittently loses cart state after refresh, and the developer needs one agent to coordinate source inspection, dev-server logs, and browser proof without manually switching between terminals.\n\n> As a full-stack Next.js developer, I want one CMUX Manager pane to spin up focused workers for server logs, cart-state source review, and browser validation, so that I can fix the checkout bug with visible evidence instead of trusting a single agent transcript.\n\n#### Agent brief\n\n```text\nYou are the Manager agent in my focused CMUX pane. Do not implement yet. First inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Build a visible pane layout using only real CMUX commands: create worker panes with `cmux new-split right` and `cmux new-pane`, then name the workspace tab with `cmux rename-tab \"checkout-triage\"`. Create three worker roles: `server-log-worker`, `source-worker`, and `browser-proof-worker`. Send each worker a narrow task using `cmux send -- \"<task>\"`: server-log-worker runs or watches the local dev server and captures errors; source-worker inspects cart and checkout route code only; browser-proof-worker verifies the localhost checkout flow in a browser or browser-agent workflow and reports exact observed behavior. After each worker responds, read its visible terminal output with `cmux read-screen`, summarize conflicts between source, logs, and browser behavior, then propose the smallest fix. Expected output: a Manager report containing pane refs from `cmux --json tree`, each worker assignment, each worker result, the chosen fix plan, and the browser/dev-server proof shape required before merging.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n```text\ncmux --json tree\n```\n\n```text\ncmux list-panes\n```\n\n```text\ncmux new-split right\n```\n\n```text\ncmux new-pane\n```\n\n```text\ncmux send -- \"<task>\"\n```\n\n```text\ncmux read-screen\n```\n\n```text\ncmux rename-tab \"checkout-triage\"\n```\n\n#### Browser verification\n\nUse the browser-proof-worker for runtime proof: open the local checkout URL, take an accessibility-style snapshot of the page state, click through cart → checkout → refresh/back navigation, fill only safe test fields, and report URL, visible cart count, console/runtime errors, and whether state survives refresh. If a CMUX browser pane is available, keep that proof visible beside the Manager; otherwise use the project's existing browser automation or local browser and paste the observation back into the worker pane.\n\n#### Definition of done\n\n- Manager report includes the live CMUX pane refs from `cmux --json tree` and the named roles assigned to each worker.\n- Dev-server or test-runner output is copied from a worker via `cmux read-screen`, not summarized from memory.\n- Browser proof includes the exact localhost route, user actions, visible before/after state, and any console/runtime error text.\n- A final review artifact lists the minimal code area to change and the verification commands or browser steps to rerun.\n\n#### Failure modes and mitigations\n\n- The Manager delegates before inspecting live state; mitigate by requiring `cmux --json tree` and `cmux list-panes` before every send/read cycle.\n- Workers drift into broad refactors; mitigate by assigning each worker one narrow responsibility and having the Manager reject unrelated changes.\n- The browser worker reports success without proof; mitigate by requiring concrete URL, visible UI state, action sequence, and error/log evidence.\n\n### Coordinate a design-drift review before touching CSS\n\n**Role:** As a frontend engineer maintaining a dashboard UI\n\nA dashboard page has visual drift across cards, filters, and responsive layout after several agent-generated edits, and the developer wants separate workers to inspect current code, compare live UI behavior, and propose a bounded cleanup.\n\n> As a frontend engineer, I want a CMUX Manager to coordinate code, browser, and review workers before editing CSS, so that cleanup is based on current source and visible UI proof rather than vague design taste.\n\n#### Agent brief\n\n```text\nYou are the Manager agent in my focused CMUX pane. Keep the human interaction surface to you only. Use `cmux --json tree` and `cmux list-panes` first. Create a visible Manager/worker layout with `cmux new-split right` and `cmux new-pane`; name the tab `dashboard-drift-review` with `cmux rename-tab \"dashboard-drift-review\"`. Create workers named `current-code-worker`, `responsive-browser-worker`, and `cleanup-plan-worker`. Use `cmux send -- \"<task>\"` to assign: current-code-worker identifies the current dashboard route, component files, and styling sources; responsive-browser-worker opens the local dashboard in a browser and records desktop and narrow-width observations; cleanup-plan-worker waits for the first two worker outputs, then drafts a small numbered cleanup plan with options A/B/C and a recommended pick. Read worker panes with `cmux read-screen`. Expected output: a numbered implementation plan that says which files are source of truth, what the browser showed, which visual issues are real, and which cleanup option the Manager recommends before implementation.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-manager-worker-orchestration/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n```text\ncmux --json tree\n```\n\n```text\ncmux list-panes\n```\n\n```text\ncmux send -- \"<task>\"\n```\n\n```text\ncmux read-screen\n```\n\n```text\ncmux rename-tab \"dashboard-drift-review\"\n```\n\n#### Browser verification\n\nUse a CMUX browser pane or local browser verification to inspect the dashboard at desktop and narrow widths. The browser worker should capture a snapshot-style summary of headings, card order, filter controls, overflow, empty states, and any console errors; click filters and navigation only enough to prove whether drift is visual, state-related, or route-specific.\n\n#### Definition of done\n\n- Manager names the CMUX tab and can list all worker panes with `cmux list-panes`.\n- Current-code-worker identifies the actual source files instead of relying on memory.\n- Responsive-browser-worker provides desktop and narrow-width observations with route and visible-state evidence.\n- Cleanup-plan-worker produces numbered options with a recommended pick, so the human can steer with a terse choice such as `2B`.\n\n#### Failure modes and mitigations\n\n- The agent treats design.md or memory as more authoritative than the current code; mitigate by making current-code-worker inspect the live repo first.\n- The browser check becomes a full QA swarm; mitigate by limiting it to the dashboard route, two viewport sizes, and the specific drift symptoms.\n- The Manager hides worker uncertainty; mitigate by requiring each worker output to include what it verified and what it did not verify.\n\n### Run a bounded AFK manager check-in on parallel workers\n\n**Role:** As a senior developer supervising several local agent tasks\n\nThree workers are already running in CMUX on separate subtasks: one is fixing a flaky unit test, one is checking a build failure, and one is investigating docs or dependency usage. The developer wants the Manager to periodically inspect panes and answer simple blocking questions, but not run forever.\n\n> As a senior developer, I want a CMUX Manager to check worker panes at a fixed interval with a hard stop condition, so that parallel work keeps moving while I step away without creating an unbounded autonomous loop.\n\n#### Agent brief\n\n```text\nYou are the Manager agent in my focused CMUX pane. Start by creating a timestamp in your notes and inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Do not create new broad goals. Identify the existing worker panes by role, cwd, visible command, or recent terminal text. Every check-in cycle, use `cmux read-screen` to read each worker pane, summarize status, and if a worker is blocked by a simple question, choose the safest reasonable answer only when it stays inside that worker's assigned task. Use `cmux send -- \"<answer or nudge>\"` only after confirming the target pane from `cmux --json tree`. Stop after the explicit bound I give you, or after 3 check-in cycles if no bound is provided. Expected output: a check-in ledger with timestamp, pane refs, worker status, any answers sent, any panes needing human attention, and final stop reason.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-manager-worker-orchestration/)\n\n[Open reference](/topics/foundations-manager-worker-orchestration/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n```text\ncmux --json tree\n```\n\n```text\ncmux list-panes\n```\n\n```text\ncmux read-screen\n```\n\n```text\ncmux send -- \"<answer or nudge>\"\n```\n\n```text\ncmux notify\n```\n\n#### Browser verification\n\nBrowser proof is only appropriate if one of the existing workers is assigned to a web-app runtime task. In that case, the Manager should ask that worker for the local URL, exact browser action taken, and visible result; otherwise the correct proof is terminal evidence from `cmux read-screen`, test logs, and the check-in ledger.\n\n#### Definition of done\n\n- The Manager records a start timestamp and a hard stop condition before the loop begins.\n- Each cycle includes pane refs, worker status, and terminal evidence read from the worker pane.\n- Any `cmux send -- \"<answer or nudge>\"` action is tied to a verified target pane from `cmux --json tree`.\n- The final ledger states whether each worker is done, blocked, still running, or needs human review, plus the stop reason.\n\n#### Failure modes and mitigations\n\n- The loop runs without a bound; mitigate by requiring a duration, target time, iteration cap, or default 3-cycle limit before starting.\n- The Manager answers high-risk questions for a worker; mitigate by only answering simple in-scope blockers and escalating destructive, production, credential, or broad architecture decisions to the human.\n- The Manager sends a message to the wrong pane; mitigate by rechecking `cmux --json tree` immediately before each `cmux send`.\n\n## Implementation notes\n\n- The Manager should inspect with `cmux --json tree` before acting and again before sending to a target pane; stale pane refs are how agents nudge the wrong worker.\n- Keep worker tasks narrow: one worker for logs, one for source, one for browser/runtime proof is usually better than three agents all editing the same files.\n- Prefer panes over tab groups for visible parallel work, because hidden tab groups are easy to lose track of during agent-heavy sessions.\n- Use `cmux read-screen` as evidence. Do not let the Manager summarize worker progress from memory or from optimistic worker claims.\n- Browser verification should prove live web behavior when the task is a web-app task; for non-browser tasks, terminal logs, test output, and a Manager ledger are stronger proof.\n- AFK-style loops need an explicit interval and stop condition. Without a bound, the workflow becomes token-burning theater.\n\n## Boundaries and caveats\n\n- Do not present CMUX browser automation skills as a taught this workflow workflow; use browser proof only where a web app needs runtime verification.\n- Do not prescribe Claude Code scheduling, Codex Mobile, tmux migration, Zellij, or Vault search as implementation requirements for this playbook.\n- Do not invent CMUX flags beyond the verified command map.\n- Do not turn workers loose on unrelated broad refactors; the taught pattern is Manager-led orchestration with narrow worker assignments.\n- Do not run unbounded AFK loops or let a Manager approve risky production, credential, billing, deployment, or destructive actions without the human.\n\n## Agent reference map\n\n### Existing CMUX manager/worker prompt\n\nUse this as the copy-paste baseline for Manager behavior, worker delegation, live-state inspection, and the human-led planning guardrail.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n### CMUX orchestration skill\n\nUse this as the reusable Codex skill contract for triggering CMUX orchestration only inside a CMUX workspace and for staying on the real command surface.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/)\n\n### Verified CMUX CLI command map\n\nUse this to avoid invented flags and to keep pane creation, state inspection, send/read, focus, and tab naming grounded in the verified commands.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n### Lesson 02 validated references\n\nUse this as the taught-concept source for agent-first tooling, natural-language terminal orchestration, cross-pane reading, manager-worker topology, and bounded AFK loops.\n\n[Open reference](/topics/foundations-manager-worker-orchestration/)\n\n### Lesson 02 validation notes\n\nUse this to stay inside the transcript-validated boundary and avoid reintroducing removed or merely mentioned tools as taught workflows.\n\n[Open reference](/topics/foundations-manager-worker-orchestration/)\n\n## Command reference\n\nThese command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.\n\nThese are REAL commands. Do not invent flags.\n\n## Panes / layout\n- `cmux new-split <left|right|up|down> [flags]` — split from the focused surface in a direction.\n- `cmux new-pane [flags]` — create a pane with terminal or browser content.\n- `cmux new-workspace [--name <title>] [--description <text>] [--cwd <path>] [--command <text>] [--layout <json>] [--focus <true|false>]`\n- `cmux focus-pane [--pane <id|ref> | <ref>]`\n- `cmux list-panes` — enumerate panes in a workspace.\n- `cmux tree [flags]` / `cmux --json tree` — print the window/workspace/pane/surface tree (JSON with `--json`).\n\nLive `cmux --json tree` returns an object with `active` (focused pane/surface refs, `is_browser_surface`, etc.) plus the full tree — this is the \"CMUX state as JSON\" / \"inspect\" the workflow uses (focused pane, refs, working directory).\n\n## Reading / sending\n- `cmux read-screen [flags]` — read terminal text from a surface back as context.\n- `cmux send [flags] -- <text>` — send text to a terminal surface.\n- `cmux send-key <key>` — send one key.\n\n## Tabs / markdown / notifications\n- `cmux rename-tab \"<name>\"` (compat wrapper for `cmux tab-action rename`).\n- `cmux markdown open <path> [--direction <left|right|up|down>] [--focus <true|false>]` — open a markdown file in a formatted viewer panel with **live file watching** (auto-refresh). This is the \"live Markdown side pane\" tracker.\n- `cmux notify` — send a notification to a workspace/surface.\n- `cmux events` — stream reconnectable cmux events as newline-delimited JSON (agent-readable telemetry / audit log).\n\n## Global options (before the command)\n`--socket <path>`, `--password <value>`, `--json`, `--id-format <refs|uuids|both>`, `--window <id|ref|index>`.\n\nHandles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes."
    },
    {
      "id": "foundations-hooks-and-context-hygiene",
      "slug": "hooks-and-context-hygiene",
      "title": "Control agent lifecycle with hooks and context hygiene",
      "summary": "Manage context with compaction and conversation forking; Wire user-prompt, tool-use, and stop hooks into your workflow; Choose between skills and plugins and run a Ralph loop.",
      "category": "Execution",
      "tags": [
        "hooks",
        "plugins",
        "Ralph loop",
        "compaction"
      ],
      "sources": [
        {
          "label": "Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-07.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#07/objectives",
        "oracle/07-references.json#recap",
        "oracle/07-references.json#concepts/0",
        "oracle/07-references.json#concepts/1",
        "oracle/07-references.json#concepts/2",
        "oracle/07-references.json#concepts/3",
        "oracle/07-references.json#concepts/4",
        "oracle/07-references.json#references",
        "oracle/07-references.json#recommendations",
        "oracle/07-interactive.json#intro",
        "oracle/07-interactive.json#checklist",
        "oracle/07-interactive.json#challenges",
        "oracle/07-interactive.json#quiz",
        "oracle/07-interactive.json#reflect",
        "oracle/07-references.json#goDeeper",
        "materials/exercises.md#Chunk-07",
        "materials/qa-index.md#Q035",
        "materials/qa-index.md#Q036",
        "materials/qa-index.md#Q037",
        "materials/qa-index.md#Q038",
        "materials/qa-index.md#Q039",
        "final/qa-index.md#Chunk-07",
        "materials/keyframes.md#Chunk-07",
        "lesson-07.html#resource-packet",
        "lesson-07.html#clip-map",
        "lesson-07.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 2966,
      "url": "/topics/foundations-hooks-and-context-hygiene/",
      "markdownUrl": "/markdown/foundations-hooks-and-context-hygiene.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-hooks-and-context-hygiene.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "compaction-and-conversation-forking",
          "text": "Compaction and conversation forking",
          "level": 3
        },
        {
          "id": "the-big-three-hooks",
          "text": "The big three hooks",
          "level": 3
        },
        {
          "id": "the-ralph-loop",
          "text": "The Ralph Loop",
          "level": 3
        },
        {
          "id": "skills-versus-plugins",
          "text": "Skills versus plugins",
          "level": 3
        },
        {
          "id": "custom-grammar-triggers",
          "text": "Custom grammar triggers",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "codex-plugins-documentation",
          "text": "Codex Plugins documentation",
          "level": 3
        },
        {
          "id": "codex-build-plugins-guide",
          "text": "Codex Build Plugins guide",
          "level": 3
        },
        {
          "id": "codex-hooks-documentation",
          "text": "Codex Hooks documentation",
          "level": 3
        },
        {
          "id": "better-plugins-repository",
          "text": "Better Plugins repository",
          "level": 3
        },
        {
          "id": "human-view-plugin",
          "text": "human-view plugin",
          "level": 3
        },
        {
          "id": "toolsmith-plugin",
          "text": "toolsmith plugin",
          "level": 3
        },
        {
          "id": "gemini-video-plugin",
          "text": "gemini-video plugin",
          "level": 3
        },
        {
          "id": "marksnip-chrome-extension",
          "text": "MarkSnip Chrome extension",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "compact-and-fork-drill",
          "text": "Compact-and-Fork Drill",
          "level": 3
        },
        {
          "id": "custom-trigger-plugin",
          "text": "Custom Trigger Plugin",
          "level": 3
        },
        {
          "id": "toolsmith-style-review",
          "text": "Toolsmith-Style Review",
          "level": 3
        },
        {
          "id": "ralph-loop-prototype",
          "text": "Ralph Loop Prototype",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "a-codex-session-has-grown-long-and-now-contains-several-unrelated-debugging-trails-what-is-the-best-next-move-before-asking-the-agent-to-focus-on-one-failing-test-file",
          "text": "A Codex session has grown long and now contains several unrelated debugging trails. What is the best next move before asking the agent to focus on one failing test file?",
          "level": 3
        },
        {
          "id": "which-lifecycle-hook-is-the-natural-place-to-detect-a-custom-trigger-like-human-or-toolsmith-before-the-agent-starts-working",
          "text": "Which lifecycle hook is the natural place to detect a custom trigger like #human or #toolsmith before the agent starts working?",
          "level": 3
        },
        {
          "id": "you-want-every-tool-call-in-a-session-to-be-recorded-so-you-can-later-ask-what-scripts-tools-or-workflow-improvements-might-be-missing-should-this-be-a-skill-or-a-plugin",
          "text": "You want every tool call in a session to be recorded so you can later ask what scripts, tools, or workflow improvements might be missing. Should this be a skill or a plugin?",
          "level": 3
        },
        {
          "id": "what-makes-the-ralph-loop-different-from-simply-prompting-the-model-to-keep-going-until-done",
          "text": "What makes the Ralph Loop different from simply prompting the model to 'keep going until done'?",
          "level": 3
        },
        {
          "id": "why-does-john-like-using-custom-triggers-instead-of-loading-every-repeatable-workflow-as-a-default-skill",
          "text": "Why does John like using custom # triggers instead of loading every repeatable workflow as a default skill?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "do-you-have-any-ideas-on-how-to-create-levers-for-agents-so-they-can-do-big-data-stuff-without-having-all-the-data-in-their-context",
          "text": "Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context?",
          "level": 3
        },
        {
          "id": "i-saw-you-use-compact-when-do-you-use-this-skill-what-is-the-skill",
          "text": "i saw you use /compact, when do you use this skill? what is the skill?",
          "level": 3
        },
        {
          "id": "are-you-organizing-your-general-knowledge-somehow-pulling-in-meeting-transcripts-emails-conversations-with-agents-and-organizing-them-in-such-a-way-to-retrieve-them-later-as-needed-agents-having-access-to-all-but-perhaps-synthesizing-basic-memories-and-mining-for-insights-i-saw-earlier-you-use-pieces-mcp-bee-computer-etc",
          "text": "are you organizing your general knowledge somehow? pulling in meeting transcripts, emails, conversations with agents, and organizing them in such a way to retrieve them later as needed, agents having access to all, but perhaps synthesizing (basic memories) and mining for insights... i saw earlier you use pieces mcp, bee.computer, etc...",
          "level": 3
        },
        {
          "id": "what-are-the-basic-lifecycle-events-in-an-agent-harness",
          "text": "What are the basic lifecycle events in an agent harness?",
          "level": 3
        },
        {
          "id": "john-do-you-subscribe-to-this-idea-that-the-context-window-has-a-smart-zone-first-100k-tokens-and-dumb-zone-and-to-try-and-keep-the-work-in-the-smart-zone-if-so-how-do-you-keep-the-goal-sessions-in-the-smart-zone-i-have-noticed-long-running-goals-really-chew-through-tokens-which-makes-me-think-there-might-be-context-management-sacrifices-being-made-to-unlock-long-running-tasks",
          "text": "John do you subscribe to this idea that the context window has a smart zone (first 100k tokens) and dumb zone and to try and keep the work in the smart zone? If so how do you keep the /goal sessions in the smart zone? I have noticed long running goals really chew through tokens which makes me think there might be context management sacrifices being made to unlock long running tasks.",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Control agent lifecycle with hooks and context hygiene\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nStart with context hygiene: compacting or forking long conversations so the next branch focuses only on what matters, such as a specific test file or active goal. John then teaches the three core hook moments in an agent loop: User Prompt, Tool Use, and Stop. From there, he explains the Ralph Loop, demonstrates a #human User Prompt hook that opens a live progress dashboard, and argues that plugins are the better tool when you want deterministic control instead of relying on a skill description being inferred correctly.\n\n## Working outcomes\n\n- Manage context with compaction and conversation forking\n- Wire user-prompt, tool-use, and stop hooks into your workflow\n- Choose between skills and plugins and run a Ralph loop\n\n## Concepts and consequences\n\n### Compaction and conversation forking\n\nCompaction is the move of shrinking a long conversation down to the pieces that still matter. John framed it as useful when you fork a conversation and want the new branch to focus on one topic, like a specific test file, instead of carrying unrelated history forward. The practical benefits he called out were fewer tokens, faster runs, lower budget/quota pressure, and a clearer sense of what the agent is working on.\n\n**Why it matters:** Long conversations can carry a lot of irrelevant context. Forking plus focused compaction gives the next session a cleaner starting point.\n\n### The big three hooks\n\nJohn breaks the agent loop into three core events: User Prompt, Tool Use, and Stop. User Prompt fires when you type something and submit it, Tool Use fires when a tool runs, and Stop fires when the conversation would normally end and wait for you. These are the main places where a hook can do something with the session.\n\n**Why it matters:** Once you understand these three events, plugins stop feeling mysterious. They become small programs attached to predictable moments in the agent lifecycle.\n\n### The Ralph Loop\n\nThe Ralph Loop is John's shorthand for a Stop-hook-driven loop. When the agent tries to stop, the hook can tell the harness not to stop yet, look back at what the user originally asked for, and keep working until a condition is met. John described this as the basic idea behind goal-style sessions.\n\n**Why it matters:** This matters when you want an agent to keep working on a goal instead of handing control back after one assistant turn.\n\n### Skills versus plugins\n\nJohn contrasts skills with plugins as a difference between context-based guidance and deterministic control. Skills put descriptions into the model's context so the agent can infer when and how to use them. Plugins can hook into events and enforce behavior, including starting or stopping things, allowing or disallowing actions, or calling specific tools.\n\n**Why it matters:** For workflows you want to enforce, John recommends reaching for a plugin with hooks instead of trying to make skill instructions clearer and clearer.\n\n### Custom grammar triggers\n\nA custom grammar trigger is a small token like #human, #toolsmith, #memory, or #search that a User Prompt hook can detect before the agent proceeds. John likes this because it keeps Codex vanilla by default and only loads the specific system, plugin, skill, or context bundle when he explicitly asks for it.\n\n**Why it matters:** This gives you a clean way to personalize sessions without polluting every conversation with skills or context the task does not need.\n\n## Reference tools and resources\n\n### Codex Plugins documentation\n\nThe main OpenAI developer documentation John opened for Codex plugins.\n\n**Use when:** Use it when you want to understand how plugins package and install things like hooks and skills.\n\n[Reference](https://developers.openai.com/codex/plugins)\n\n### Codex Build Plugins guide\n\nThe OpenAI guide John showed as a starting point for creating plugin projects.\n\n**Use when:** Use it as source material when asking an agent to generate a documented starter plugin or hook example.\n\n[Reference](https://developers.openai.com/codex/plugins/build)\n\n### Codex Hooks documentation\n\nThe OpenAI reference John opened for hook behavior.\n\n**Use when:** Use it when learning what User Prompt, Tool Use, and Stop hooks can do, or when feeding hook docs to an agent so it can build an example.\n\n[Reference](https://developers.openai.com/codex/hooks)\n\n### Better Plugins repository\n\nJohn Lindquist's prototype repository containing examples such as human-view, Gemini Video, and Toolsmith.\n\n**Use when:** Use it as a reference repo for real plugin patterns, while remembering that John described this work as prototype-stage and personally configured.\n\n[Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins)\n\n### human-view plugin\n\nA Better Plugins example that activates with #human and opens a live browser dashboard showing task progress and tool-call activity.\n\n**Use when:** Reach for this when you want to study the #human pattern John demonstrated: a User Prompt hook that starts a live progress view for a session.\n\n[Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/human-view)\n\n### toolsmith plugin\n\nA Better Plugins example John described as recording tool calls and conversation activity so you can query the log for workflow improvements.\n\n**Use when:** Reach for this when you want to study how recorded tool use could reveal missing scripts, missing tools, or repeatable workflow improvements.\n\n[Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/toolsmith)\n\n### gemini-video plugin\n\nA Better Plugins example John described as detecting a dragged-in .mp4 file path and sending it through Gemini scripts so the video can be parsed into the conversation.\n\n**Use when:** Use it as an example of a plugin that reacts to a file path, but expect to adapt it because John said it was configured for his own setup.\n\n[Reference](https://github.com/johnlindquist/better-plugins/tree/main/plugins/gemini-video)\n\n### MarkSnip Chrome extension\n\nA browser extension John used to copy documentation pages into Markdown.\n\n**Use when:** Use it when you want to paste documentation into an agent directly instead of spending an extra tool call having the agent scrape the page.\n\n[Reference](https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm)\n\n## Recommendations and best practices\n\n- When a session gets long, fork it and compact around the specific thing you want next, such as the test file or active goal, instead of continuing with unrelated history.\n- Use User Prompt, Tool Use, and Stop as your basic mental model for plugin design: decide which lifecycle moment actually needs intervention.\n- Use the Codex plugin and hook docs as source material, then ask an agent to build a fully documented example and review or test what it creates.\n- Use a Stop hook for Ralph Loop-style continuation when you can define the condition the agent should keep working toward.\n- Prefer a plugin over a skill when the workflow must be enforced, such as starting or stopping something, allowing or disallowing actions, or calling a specific tool.\n- Keep default sessions as vanilla as possible, then use explicit triggers like #human, #toolsmith, #memory, or #search to opt into extra behavior only when the task needs it.\n- Treat John's Better Plugins repo as prototype reference material, not as polished drop-in infrastructure for every machine.\n\n## Practice and acceptance criteria\n\nPractice trimming noisy context, recognizing the main hook events, and choosing plugins when you need deterministic workflows instead of fuzzy skill behavior.\n\n### Checklist\n\n1. Pick one recurring workflow you currently handle with a long prompt, skill, or repeated manual instruction.\n2. Decide which lifecycle moment actually needs control: User Prompt for triggers, Tool Use for tools, or Stop for continuation.\n3. Use the Codex plugin and hook docs as source material and ask an agent to create a documented starter plugin or hook example.\n4. Add a custom trigger such as #review, #human, or #toolsmith to a User Prompt hook, and confirm normal prompts do not activate the extra behavior.\n5. Try a Stop-hook/Ralph Loop pattern only when you can state the condition the agent should keep working toward.\n6. Review a Toolsmith-style record of tool calls and look for one missing script, missing tool, or repeated workflow worth improving.\n7. Keep the default session minimal, then load context bundles, skills, or plugin behavior only when your custom trigger calls for them.\n\n### Compact-and-Fork Drill\n\n**Difficulty:** Easy\n\nTake a messy or long Codex conversation, fork it, then write a compact handoff that keeps only the active goal, relevant files, failing test, and next action.\n\n**Done when:** A new session can understand the focused task without needing unrelated earlier discussion.\n\n### Custom Trigger Plugin\n\n**Difficulty:** Medium\n\nBuild or ask an agent to build a small plugin that watches for #myflow in the User Prompt hook and conditionally loads a short workflow instruction or helper behavior.\n\n**Done when:** Prompts with #myflow activate the behavior, while normal prompts run without the extra context or behavior.\n\n### Toolsmith-Style Review\n\n**Difficulty:** Medium\n\nPrototype or adapt a workflow that records tool calls, then review or query those records for one repeated pattern worth turning into a script, tool, or plugin.\n\n**Done when:** You can point to one workflow improvement based on actual repeated agent behavior.\n\n### Ralph Loop Prototype\n\n**Difficulty:** Hard\n\nAsk an agent to help create a Stop-hook plugin for a toy task that tells the agent to continue working until a specific condition is met.\n\n**Done when:** The agent continues past an attempted stop, works toward the original task, and exits once the condition is satisfied.\n\n## Questions to test understanding\n\n### A Codex session has grown long and now contains several unrelated debugging trails. What is the best next move before asking the agent to focus on one failing test file?\n\n- **A.** Fork the conversation and compact the new branch around the relevant test file and current goal.\n- **B.** Keep the same conversation open so the model has maximum history available.\n- **C.** Paste the entire transcript into a new prompt and ask the model to remember everything.\n- **D.** Convert the whole conversation into a global skill so it loads in every future session.\n\n**Answer: A.** Forking plus focused compaction preserves what matters while dropping unrelated noise. John called out fewer tokens, faster runs, lower budget pressure, and clearer focus as the practical benefits.\n\n### Which lifecycle hook is the natural place to detect a custom trigger like #human or #toolsmith before the agent starts working?\n\n- **A.** Stop hook\n- **B.** Tool Use hook\n- **C.** User Prompt hook\n- **D.** Compaction hook\n\n**Answer: C.** The User Prompt hook fires when the user submits text, so it can parse custom grammar before the agent proceeds. That is the pattern John demonstrated with #human.\n\n### You want every tool call in a session to be recorded so you can later ask what scripts, tools, or workflow improvements might be missing. Should this be a skill or a plugin?\n\n- **A.** A skill, because the model can decide when logging feels appropriate.\n- **B.** A plugin with a Tool Use hook, because Tool Use is the lifecycle moment around tool calls.\n- **C.** A Stop hook only, because tool activity should be recorded after the task is over.\n- **D.** A compaction instruction, because logging is mainly about shrinking context.\n\n**Answer: B.** John identified Tool Use as the hook event that fires when tools run, and described Toolsmith as recording tool calls so you can query them for workflow improvements.\n\n### What makes the Ralph Loop different from simply prompting the model to 'keep going until done'?\n\n- **A.** It uses a Stop hook to structurally continue the session when the agent would normally hand control back.\n- **B.** It loads every available skill so the model has more options.\n- **C.** It prevents the agent from using tools until the user approves each command.\n- **D.** It replaces compaction with a larger context window.\n\n**Answer: A.** John described the Ralph Loop as a Stop-hook pattern: when the agent tries to stop, the hook tells it to look back at the original task and keep working until a condition is met.\n\n### Why does John like using custom # triggers instead of loading every repeatable workflow as a default skill?\n\n- **A.** They keep Codex vanilla by default and load only the specific system or context bundle when requested.\n- **B.** They make compaction unnecessary for long conversations.\n- **C.** They prevent the agent from using tools.\n- **D.** They replace the need to read plugin or hook documentation.\n\n**Answer: A.** John's preference is to avoid polluting every session with skill descriptions or context the task does not need. A trigger like #human or #toolsmith lets him opt into extra behavior only for sessions that need it.\n\n## Reflection prompts\n\n- Which workflows are you currently handling as skills or long prompts but actually need deterministic plugin control?\n- Where are you loading skills or context by default that could instead be loaded only through a # trigger?\n- What is one task where a Ralph Loop would help, and what exact condition would tell it to stop?\n\n## Further applications\n\n1. Ask an agent to build a fully documented Hello World plugin or hook example from the Codex plugin and hook docs, then read through the result and ask follow-up questions.\n2. Convert one recurring skill-like workflow into a #your-trigger plugin that conditionally loads the behavior only when the trigger appears.\n3. Study the human-view pattern as a concrete example of #human activating a live dashboard that tracks progress and tool-call activity.\n4. Study the Toolsmith pattern as an example of recording tool calls and querying that record for workflow improvements.\n5. Study the Gemini Video pattern as an example of detecting an .mp4 file path and routing it through a video-processing script, while expecting to adapt it for your own setup.\n\n## Applied exercises\n\nExercise: Transition from Soft Skills to Deterministic Plugins\n\n**Objective:**  Developers will replace a high-context prompt structure or an inference-based agent \"Skill\" with a low-level programmatic Plugin.\n\n**Requirements:** Identify a repeatable task workflow that you currently execute by passing detailed text instructions to an LLM skill.Instead of using a skill, create a custom Codex Plugin structure utilizing a hooks.json mapping configuration.Configure a custom syntax grammar key (e.g., #YourWorkflowName) handled inside the User Prompt hook listener.Write a Python script mapping to ensure that when this character trigger is registered, specific environmental checks, system rules, or tool executions are programmatically enforced rather than relying on model inferences.\n\n## Questions and answers\n\n### Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context?\n\nJohn explicitly says he is not an expert in big-data engineering integrations and does not offer a validated big-data recipe. The adjacent hook discussion offers a structural principle: keep large data in external processes; pass references or concise execution metrics through tool hooks rather than loading everything into active context. This is not a demonstrated big-data integration.\n\n### i saw you use /compact, when do you use this skill? what is the skill?\n\ncompact is a method used to compress long conversations down to essential details. John explains that he historically ran single conversations straight through to completion and then closed them out. However, automated /goal execution runs can alter this workflow because long tasks cycle through several automated compactions while running unattended to remain safely inside the token window limit without blowing through operational limits.\n\n### are you organizing your general knowledge somehow? pulling in meeting transcripts, emails, conversations with agents, and organizing them in such a way to retrieve them later as needed, agents having access to all, but perhaps synthesizing (basic memories) and mining for insights... i saw earlier you use pieces mcp, bee.computer, etc...\n\nJohn details a workflow using custom syntax triggers like #memory or #search. Rather than feeding a massive knowledge graph into every agent session globally, he prefers keeping his default Codex instances as vanilla as possible. He recommends implementing custom grammar listeners inside the user prompt hooks to dynamically grab and resolve target context bundles exactly when explicitly requested.\n\n### What are the basic lifecycle events in an agent harness?\n\nJohn steps back at 03:14:32 to lay down fundamental context setting. He explicitly abstracts the core pipeline events of any agent harness down to the basic three hooks: User Prompt, Tool Use, and Stop Hook, providing a baseline architecture breakdown before showing any more complex code configurations.\n\n### John do you subscribe to this idea that the context window has a smart zone (first 100k tokens) and dumb zone and to try and keep the work in the smart zone? If so how do you keep the /goal sessions in the smart zone? I have noticed long running goals really chew through tokens which makes me think there might be context management sacrifices being made to unlock long running tasks.\n\nJohn acknowledges that long-running automated goals change how context degradation is handled. Because long sessions continuously consume heavy token counts, using /goal strategies forces systems to use progressive automated compaction steps over their lifecycles. To maintain high accuracy without model degradation, he builds custom plugins that use explicit Python runtime rules to tightly control context instead of letting the agent continuously guess its state.\n\n## Operational playbooks\n\n- [Ralph Loop stop-hook continuation](/topics/foundations-ralph-loop-playbook/)\n\n- [Codex Primitive Field Guide](/topics/foundations-codex-primitives-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-07.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-07.html)\n\n### Visual reference index\n\n- [03:12:05](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-1): Dark terminal/conversation context during the post-lunch compaction discussion.\n- [03:14:45](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-2): Terminal prompt area during the setup for explaining user prompt, tool use, and stop hooks.\n- [03:17:15](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-3): Terminal/file-list view before the browser documentation walkthrough fully appears.\n- [03:18:55](https://codex-workshop-followup.pages.dev/lesson-07.html#clip-07-4): OpenAI Developers Hooks documentation page with the MarkSnip extension overlay visible.\n- [03:20:45](https://codex-workshop-followup.pages.dev/lesson-07.html): Terminal view rendering generated hook/project instructions and script text.\n- [03:22:20](https://codex-workshop-followup.pages.dev/lesson-07.html): Terminal prompt context while preparing the custom #human hook trigger example.\n- [03:23:15](https://codex-workshop-followup.pages.dev/lesson-07.html): Split workspace with terminal logs on the left and a live typing-game dashboard in the browser.\n- [03:24:18](https://codex-workshop-followup.pages.dev/lesson-07.html): GitHub repository view for johnlindquist/better-plugins showing plugin folders.\n- [03:30:15](https://codex-workshop-followup.pages.dev/lesson-07.html): GitHub repository view inside better-plugins, showing individual plugin/script files."
    },
    {
      "id": "foundations-manager-worker-orchestration",
      "slug": "manager-worker-orchestration",
      "title": "Coordinate agents with a manager and worker panes",
      "summary": "Adopt an agent-first mindset and the manager-worker topology; Drive CMUX terminal layouts with natural language; Set up AFK automation loops that keep working while you don't.",
      "category": "Execution",
      "tags": [
        "CMUX",
        "orchestration",
        "delegation"
      ],
      "sources": [
        {
          "label": "Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-02.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#02/objectives",
        "oracle/02-references.json#recap",
        "oracle/02-references.json#concepts/0",
        "oracle/02-references.json#concepts/1",
        "oracle/02-references.json#concepts/2",
        "oracle/02-references.json#concepts/3",
        "oracle/02-references.json#concepts/4",
        "oracle/02-references.json#concepts/5",
        "oracle/02-references.json#concepts/6",
        "oracle/02-references.json#concepts/7",
        "oracle/02-references.json#references",
        "oracle/02-references.json#recommendations",
        "oracle/02-interactive.json#intro",
        "oracle/02-interactive.json#checklist",
        "oracle/02-interactive.json#challenges",
        "oracle/02-interactive.json#quiz",
        "oracle/02-interactive.json#reflect",
        "oracle/02-references.json#goDeeper",
        "materials/exercises.md#Chunk-02",
        "materials/qa-index.md#Q003",
        "materials/qa-index.md#Q004",
        "materials/qa-index.md#Q005",
        "materials/qa-index.md#Q006",
        "materials/qa-index.md#Q007",
        "materials/qa-index.md#Q008",
        "materials/qa-index.md#Q009",
        "materials/keyframes.md#Chunk-02",
        "lesson-02.html#resource-packet",
        "lesson-02.html#clip-map",
        "lesson-02.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 3123,
      "url": "/topics/foundations-manager-worker-orchestration/",
      "markdownUrl": "/markdown/foundations-manager-worker-orchestration.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-manager-worker-orchestration.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "agent-first-tooling",
          "text": "Agent-first tooling",
          "level": 3
        },
        {
          "id": "packx-for-file-collation",
          "text": "PackX for file collation",
          "level": 3
        },
        {
          "id": "natural-language-terminal-orchestration",
          "text": "Natural language terminal orchestration",
          "level": 3
        },
        {
          "id": "vault-and-resumed-conversations",
          "text": "Vault and resumed conversations",
          "level": 3
        },
        {
          "id": "unread-notification-jumping",
          "text": "Unread notification jumping",
          "level": 3
        },
        {
          "id": "cross-pane-context-reading",
          "text": "Cross-pane context reading",
          "level": 3
        },
        {
          "id": "manager-worker-topology",
          "text": "Manager-worker topology",
          "level": 3
        },
        {
          "id": "afk-goal-loops",
          "text": "AFK goal loops",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "cmux",
          "text": "CMUX",
          "level": 3
        },
        {
          "id": "packx",
          "text": "PackX",
          "level": 3
        },
        {
          "id": "tmux",
          "text": "tmux",
          "level": 3
        },
        {
          "id": "claude-code-scheduling",
          "text": "Claude Code scheduling",
          "level": 3
        },
        {
          "id": "codex-mobile",
          "text": "Codex Mobile",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "natural-language-pane-warmup",
          "text": "Natural Language Pane Warmup",
          "level": 3
        },
        {
          "id": "vault-and-unread-navigation-drill",
          "text": "Vault and Unread Navigation Drill",
          "level": 3
        },
        {
          "id": "manager-checks-the-room",
          "text": "Manager Checks the Room",
          "level": 3
        },
        {
          "id": "small-afk-check-in-goal",
          "text": "Small AFK Check-In Goal",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "what-does-john-mean-by-agent-first-tooling-in-this-lesson",
          "text": "What does John mean by agent-first tooling in this lesson?",
          "level": 3
        },
        {
          "id": "what-did-john-demonstrate-with-cmux-natural-language-commands",
          "text": "What did John demonstrate with CMUX natural language commands?",
          "level": 3
        },
        {
          "id": "what-is-the-role-of-the-vault-feature-john-showed",
          "text": "What is the role of the Vault feature John showed?",
          "level": 3
        },
        {
          "id": "in-john-s-manager-worker-pattern-what-does-he-try-to-do",
          "text": "In John's manager-worker pattern, what does he try to do?",
          "level": 3
        },
        {
          "id": "why-is-cross-pane-reading-useful-in-cmux",
          "text": "Why is cross-pane reading useful in CMUX?",
          "level": 3
        },
        {
          "id": "what-was-john-s-afk-style-example",
          "text": "What was John's AFK-style example?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "exercise-orchestrating-the-manager-worker-pattern-in-cmux",
          "text": "Exercise: Orchestrating the Manager-Worker Pattern in CMUX",
          "level": 3
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "what-s-cmux-is-it-like-warp-but-less-commercial",
          "text": "What’s cmux? Is it like Warp, but less commercial?",
          "level": 3
        },
        {
          "id": "would-you-recommend-this-to-a-heavily-invested-tmux-user",
          "text": "Would you recommend this to a heavily invested tmux user?",
          "level": 3
        },
        {
          "id": "do-we-have-alternative-for-windows",
          "text": "do we have alternative for windows",
          "level": 3
        },
        {
          "id": "how-do-you-get-vault-i-missed-it",
          "text": "How do you get vault? I missed it",
          "level": 3
        },
        {
          "id": "do-you-need-your-projects-structured-a-certain-way-so-cmux-can-run-multiple-sessions-without-causing-issues-with-agents-stepping-on-toes",
          "text": "Do you need your projects structured a certain way so cmux can run multiple sessions without causing issues with agents stepping on toes?",
          "level": 3
        },
        {
          "id": "have-ways-in-which-you-manage-to-move-from-one-to-the-other-or-you-fork-or-you-come-back-and-then-maybe-a-follow-up-question-is-i-saw-you-post-something-about-one-agent-controlling-another-agent-through-a-graphical-or-for-browser-accessibility-controls-and-i-m-just-curious-if-you-have-any-of-these-other-ways-in-which-you-manage-between-agents",
          "text": "Have ways in which you manage to move from one to the other, or you fork, or you come back. And then maybe a follow-up question is, I saw you post something about one agent controlling another agent through... a graphical, or for browser, accessibility controls, and I'm just curious if you have any... of these other ways in which you manage between agents?",
          "level": 3
        },
        {
          "id": "codex-implement-tree-when",
          "text": "Codex implement /tree when?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Coordinate agents with a manager and worker panes\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is shifting from manually babysitting one terminal to using CMUX as an agent-first terminal workspace. John shows that agents can read CMUX's command surface, open and arrange panes from natural language, name tabs, resume old conversations from the Vault, jump to panes with unread activity, and inspect what other panes have said or done. He also describes his preferred manager-worker pattern: he talks mostly to one Manager pane, and that pane can open or check worker panes.\n\n## Working outcomes\n\n- Adopt an agent-first mindset and the manager-worker topology\n- Drive CMUX terminal layouts with natural language\n- Set up AFK automation loops that keep working while you don't\n\n## Concepts and consequences\n\n### Agent-first tooling\n\nJohn frames modern dev tools around whether they are open source and agent-first: tools with CLIs, APIs, or other surfaces agents can interact with and control. His point is that you no longer need to personally memorize every flag or shortcut when the agent can inspect the interface and use it.\n\n**Why it matters:** Agent-first tools let your instructions turn into real tool actions: opening panes, running commands, checking status, or operating a CLI. Tools without programmable surfaces put more mechanical work back on the human.\n\n### PackX for file collation\n\nJohn shows PackX, a tool he built to collate a bunch of files into a single file. He explains that it supports file globs, patterns, and options, and that he typically lets the agent learn and use the CLI flags instead of using the tool manually.\n\n**Why it matters:** It is an example of agent-first thinking: give the agent a useful CLI tool and let it handle the exact flags and patterns needed for the current context.\n\n### Natural language terminal orchestration\n\nJohn demonstrates asking CMUX to open a new pane to the right, then asking it to open five more panes, run different safe commands in them, and space everything evenly. The agent uses the CMUX CLI surface to translate natural language into layout and terminal actions.\n\n**Why it matters:** This makes the terminal workspace programmable. You can describe the workspace you need instead of manually arranging panes and remembering multiplexer commands.\n\n### Vault and resumed conversations\n\nJohn demonstrates the CMUX right sidebar with Files, Find, and Vault. In the Vault, he can look through past conversations and resume one in a new tab, though he notes the feature is still in development and search is not great yet.\n\n**Why it matters:** Resuming old context is useful when you lose or want to continue a previous conversation without manually reconstructing what happened.\n\n### Unread notification jumping\n\nJohn shows that CMUX can surface notifications from sessions and that Cmd+Shift+U jumps to unread activity. He uses it to jump to a pane where a session had stopped.\n\n**Why it matters:** When many sessions are running, jumping to the pane that needs attention is faster than manually scanning every pane.\n\n### Cross-pane context reading\n\nJohn demonstrates that CMUX can read the contents of other tabs or panes by echoing text in one tab and asking another what that tab said. He explains that agents can check other panes, workspaces, recent commands, Git actions, and signs that something needs attention.\n\n**Why it matters:** This is what makes multiple panes more than just visual clutter. A main or sibling agent can inspect what is happening elsewhere and summarize it for you.\n\n### Manager-worker topology\n\nJohn describes treating himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager, which can open panes and send workers to investigate, research, or do other tasks.\n\n**Why it matters:** A manager pane keeps the human interaction surface smaller while still letting several agents or terminal sessions do work in parallel.\n\n### AFK goal loops\n\nJohn gives an example goal where an agent creates a timestamp, checks other panes every 10 minutes to make sure they are completing their goals, picks the best answer if a pane is blocked by a question, and continues until four hours after the original timestamp. He describes this as an AFK approach where he can set it and walk away.\n\n**Why it matters:** Periodic check-ins can keep multiple running sessions moving, but John also says the upfront planning for parallel work is still something to be actively involved in.\n\n## Reference tools and resources\n\n### CMUX\n\nAn open-source, agent-first terminal workspace John uses to let agents control panes, tabs, workspaces, notifications, and terminal activity through a CLI-driven surface.\n\n**Use when:** Use it when you want local agent-driven terminal orchestration: opening panes, arranging layouts, naming tabs, resuming old conversations, jumping to unread sessions, and checking what other panes are doing.\n\n[Reference](https://cmux.com/)\n\n### PackX\n\nJohn's file collation utility for packing selected files, globs, and patterns into a single file.\n\n**Use when:** Use it when an agent needs to gather a set of files into one context bundle and you would rather have the agent handle the CLI flags and patterns.\n\n[Reference](https://www.npmjs.com/package/packx)\n\n### tmux\n\nThe classic terminal multiplexer that came up when a participant asked whether CMUX is worth trying for someone heavily invested in tmux.\n\n**Use when:** Keep tmux in mind if remote session behavior is central to your workflow; John said CMUX does not have all the remote session features he associates with tmux, while his own work is mostly local.\n\nsearch: tmux terminal multiplexer remote sessions\n\n### Claude Code scheduling\n\nJohn mentioned that Claude Code has a scheduling or cron-like feature he wishes Codex had more directly.\n\n**Use when:** Think of this as context for the AFK check-in idea, not as a taught setup path in this lesson.\n\nsearch: Claude Code scheduled tasks\n\n### Codex Mobile\n\nJohn briefly shows the Codex app setting for Codex Mobile and says recent changes let phone control work with sessions started in CMUX as long as the app is open.\n\n**Use when:** Use it for lightweight control or check-ins from a phone, while recognizing this section only briefly demonstrates where the feature lives and what it enables.\n\nsearch: Codex Mobile app\n\n## Recommendations and best practices\n\n- Choose tools that are open source and agent-first, meaning agents can control them through CLIs, APIs, or similar programmable surfaces.\n- Let agents handle CLI flags and command details when the tool surface is discoverable, as John does with PackX and CMUX.\n- Use natural language CMUX commands to create panes, arrange the workspace, name tabs, and run safe commands.\n- Prefer panes over tab groups when you want visible parallel work, because John says tab groups are easy to lose track of.\n- Use the CMUX Vault to resume old conversations, but remember John called the feature still in development and said its search is not great yet.\n- Use Cmd+Shift+U to jump to unread activity when a running session stops or needs attention.\n- For multi-agent work, try a Manager pane that you talk to directly, while worker panes handle investigations, research, or other delegated tasks.\n- For AFK-style work, use a clear interval and stop condition, and stay actively involved in the upfront planning before parallelizing work.\n\n## Practice and acceptance criteria\n\nPractice using CMUX as an agent-controlled terminal workspace: natural language pane control, visible parallel sessions, a manager pane, and periodic check-ins.\n\n### Checklist\n\n1. Open a CMUX workspace.\n2. Run or inspect CMUX help so the agent can discover the command surface.\n3. Use a natural language command to open a new pane to the right.\n4. Ask CMUX to open several more panes, run different safe terminal commands in them, and space the panes evenly.\n5. Ask CMUX to name tabs with clear or memorable names.\n6. Open the right sidebar with Cmd+Alt+B and locate the Files, Find, and Vault sections.\n7. Resume a past conversation from the Vault if one is available.\n8. Use Cmd+Shift+U to jump to unread activity from a session that has stopped or needs attention.\n9. Echo a short message in one named tab, then ask another pane what that tab said.\n10. Create one Manager pane and have it check or summarize what worker panes are doing.\n\n### Natural Language Pane Warmup\n\n**Difficulty:** Easy\n\nIn CMUX, ask the agent to open a new pane to the right. Then ask it to open several more panes, run different safe terminal commands in them, and space the layout evenly.\n\n**Done when:** The workspace contains multiple visible panes, each running a harmless command, without you manually arranging every split.\n\n### Vault and Unread Navigation Drill\n\n**Difficulty:** Easy\n\nOpen the right sidebar, find the Vault, and resume a previous conversation in a new tab if one is available. Then use the unread-jump workflow to move to a pane that has activity needing attention.\n\n**Done when:** You can explain how to open the sidebar, where the Vault lives, and how Cmd+Shift+U helps you jump to unread activity.\n\n### Manager Checks the Room\n\n**Difficulty:** Medium\n\nCreate one Manager pane and at least one Worker pane. Have the Worker run a safe command such as echo, pwd, or git status. Then ask the Manager to inspect the Worker pane and summarize what it sees.\n\n**Done when:** The Manager correctly identifies what happened in the Worker pane and does not invent output that is not visible.\n\n### Small AFK Check-In Goal\n\n**Difficulty:** Hard\n\nWrite a bounded goal for a Manager pane that creates a timestamp, checks other panes at a fixed interval, reports progress, and stops after a defined time window.\n\n**Done when:** The goal includes an interval, a clear stop condition, and a reporting instruction, matching the AFK-style pattern John described.\n\n## Questions to test understanding\n\n### What does John mean by agent-first tooling in this lesson?\n\n- **A.** Tools that expose CLIs, APIs, or other surfaces agents can inspect and control\n- **B.** Tools that only work through graphical menus\n- **C.** Tools that require the human to memorize every shortcut before using them\n- **D.** Tools that prevent agents from running commands\n\n**Answer: A.** John says the tools to look for are open source and agent-first: tools with CLIs, APIs, or other ways agents can interact with and control them.\n\n### What did John demonstrate with CMUX natural language commands?\n\n- **A.** Opening and arranging panes, then running different safe commands in them\n- **B.** Replacing the terminal with a static web dashboard\n- **C.** Deploying production code from a phone\n- **D.** Converting every pane into the same shared shell process\n\n**Answer: A.** John asked CMUX to open a pane to the right, then to open five more panes, run different safe commands, and space everything evenly.\n\n### What is the role of the Vault feature John showed?\n\n- **A.** It stores billing credentials for agents\n- **B.** It lets John look through past conversations and resume one in a new tab\n- **C.** It prevents all worker panes from editing files\n- **D.** It automatically writes tests for every project\n\n**Answer: B.** John opened the right sidebar, went to Vault, found past conversations, and resumed one in a new tab. He also noted the feature is still in development.\n\n### In John's manager-worker pattern, what does he try to do?\n\n- **A.** Talk mainly to one Manager pane while other panes do delegated work\n- **B.** Talk to every pane equally at all times\n- **C.** Avoid opening more than one pane\n- **D.** Use only phone controls and never the terminal\n\n**Answer: A.** John describes himself as the CEO, one pane as the Manager, and other panes as workers. He tries to talk mainly to the Manager.\n\n### Why is cross-pane reading useful in CMUX?\n\n- **A.** It lets an agent check what other tabs or panes have said, run, or gotten stuck on\n- **B.** It guarantees that no two agents can ever conflict\n- **C.** It removes the need for planning parallel work\n- **D.** It makes tmux remote persistence unnecessary\n\n**Answer: A.** John demonstrated asking one pane what another tab said, then described checking other panes, recent commands, Git actions, summaries, and things needing attention.\n\n### What was John's AFK-style example?\n\n- **A.** Check other panes every 10 minutes, answer blocking questions, and continue until four hours after the original timestamp\n- **B.** Run forever and approve every action automatically\n- **C.** Rewrite the whole repo every hour\n- **D.** Let every worker choose unrelated goals without checking in\n\n**Answer: A.** John's example was a scheduled goal loop that checks other panes every 10 minutes, picks the best answer when a pane is blocked by a question, and continues for a defined four-hour window.\n\n## Reflection prompts\n\n- Which tools in your workflow are agent-first because they expose useful CLIs or APIs?\n- Where would visible panes help you keep track of parallel work better than hidden tab groups?\n- What work would you route through a Manager pane, and what work would you still handle directly?\n- What kind of AFK check-in loop would be useful without replacing the upfront planning you still need to do yourself?\n\n## Further applications\n\n1. Practice opening and arranging CMUX panes with natural language commands such as opening a pane to the right or creating several evenly spaced panes.\n2. Try naming tabs with a natural language request, then search for or close specific named tabs.\n3. Use the Vault sidebar to find a past conversation and resume it in a new tab.\n4. Create a simple manager-worker setup: one Manager pane and one or two worker panes, then ask the Manager to check what the workers have done.\n5. Draft a small AFK-style goal that checks other panes at a fixed interval, reports progress, and stops after a defined amount of time.\n\n## Applied exercises\n\n### Exercise: Orchestrating the Manager-Worker Pattern in CMUX\n*   **Objective**: Build an isolated local development grid that relies on a single coordinator agent to direct sub-tasks across multiple child panels without manual human window tiling.\n*   **Setup Steps**:\n    1. Open a clean workspace inside CMUX.\n    2. Split your terminal layout using a macro shortcut or natural language step (`! Open a new Pane to the right`).\n    3. Designate the primary window as your **Manager** shell.\n    4. Input a structured layout command to the Manager: *\"Spawn three sibling panes below. Initialize a clean repository tracker in pane 1, trigger a continuous build diagnostic loop in pane 2, and use pane 3 to monitor local directory storage footprints.\"*\n    5. Validate that CMUX correctly partitions the available workspace area, configures separate shell environments, and triggers the independent task sequences cleanly.\n    6. Verify cross-context capabilities by asking your Manager pane: *\"What is the active execution state and output log of your second sibling pane?\"*\n\n## Questions and answers\n\n### What’s cmux? Is it like Warp, but less commercial?\n\nAn open-source, agent-first terminal multiplexer tool. It focuses on providing structural APIs and CLI endpoints that allow background autonomous models to freely control window positioning, manage context structures, and drive active command operations.\n\n### Would you recommend this to a heavily invested tmux user?\n\nYes, but with caveats. CMUX currently lacks some of the robust persistent remote-session features found in traditional Tmux architectures. It is highly optimized for local, agent-orchestrated loops, meaning pure remote workflow users may encounter friction.\n\n### do we have alternative for windows\n\nZellij operates effectively on Windows nodes and natively supports direct agent control integration features.\n\nPlatform caveat: this was a suggested alternative, not a demonstrated Windows installation. Confirm the supported host environment and any WSL requirement before using it as a team setup recommendation.\n\n### How do you get vault? I missed it\n\nPress Cmd+Alt+B to display the right-hand utility sidebar. From there, navigate between Files, Find, and Vault categories using numerical shortcuts 1, 2, and 3.\n\n### Do you need your projects structured a certain way so cmux can run multiple sessions without causing issues with agents stepping on toes?\n\nIsolate running server processes cleanly behind the individual terminal tabs that actively consume them. Because CMUX manages distinct windows independently, models can run safely in parallel and can programmatically read across sibling history buffers to check on processing states without corrupting cross-project environments.\n\n### Have ways in which you manage to move from one to the other, or you fork, or you come back. And then maybe a follow-up question is, I saw you post something about one agent controlling another agent through... a graphical, or for browser, accessibility controls, and I'm just curious if you have any... of these other ways in which you manage between agents?\n\nJohn relies on the manual 'codex fork' option to branch conversations from selected history checkpoints. He uses a Manager-Worker Pattern: a single primary terminal pane is his designated 'Manager' (his sole point of interaction), and that manager model script handles splitting sub-panes to deploy worker agents. For browser environments, toolsets leverage accessibility tree paths to parse content, but within CMUX, the native command-line interface endpoints are fast and descriptive enough that parsing raw accessibility trees isn't necessary.\n\n### Codex implement /tree when?\n\nUnanswered/Deferred. John does not address this question directly in the transcript; during this window, he is answering a verbal question from a developer regarding agent handoffs and manager topologies. The nearest tool comparison occurs at [00:45:55] where John discusses wanting Claude Code's cron scheduling features inside Codex.\n\n## Operational playbooks\n\n- [Command a CMUX manager/worker layout](/topics/foundations-cmux-orchestrate-playbook/)\n\n- [CMUX Orchestration Field Guide](/topics/foundations-cmux-orchestration-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-02.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-02.html)\n\n### Visual reference index\n\n- [00:31:16](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-1): Screen showing the NPM home tracking page details for the custom tool package packx.\n- [00:33:55](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-2): The initial unified CMUX terminal layout before invoking layout splits.\n- [00:34:19](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-3): Visual proof of a new vertical split created by typing ! Open a new Pane to the right.\n- [00:34:59](https://codex-workshop-followup.pages.dev/lesson-02.html#clip-02-4): The workspace grid re-tiling into a complex multi-pane array following the voice-dictated instruction to spawn 5 distinct command loops.\n- [00:37:06](https://codex-workshop-followup.pages.dev/lesson-02.html): The expanded Vault interface view appearing inside the right sidebar, showing past interaction history blocks.\n- [00:37:33](https://codex-workshop-followup.pages.dev/lesson-02.html): Right-click sub-menu interaction executing the 'Resume a new tab' instruction to revive old log states.\n- [00:39:29](https://codex-workshop-followup.pages.dev/lesson-02.html): The UI snapping focus directly to an isolated corner box via Cmd+Shift+U immediately following the termination of a background Codex Demons session.\n- [00:41:00](https://codex-workshop-followup.pages.dev/lesson-02.html): Multiple workspace tab configurations explicitly showing custom names generated by the agent (Zendaya, Oprah, Tom Hanks).\n- [00:47:53](https://codex-workshop-followup.pages.dev/lesson-02.html): Input prompt displaying John's complete text for the 4-hour cyclical /goal background monitoring loop.\n- [00:51:58](https://codex-workshop-followup.pages.dev/lesson-02.html): Close-up highlighting the position of the Codex Mobile icon within the master system settings pane layout."
    },
    {
      "id": "codex-imp-hook-setup",
      "slug": "imp-hook-setup",
      "title": "Install and inspect dash-prefix Imp routing",
      "summary": "Installation and trust-boundary guidance for foreground and forked Imp routing, including helper contracts, hook registration, verification prompts, cmux inspection commands, and troubleshooting.",
      "category": "Execution",
      "tags": [
        "hooks",
        "imps",
        "setup"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/What This Adds",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Install Targets",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Files In This Directory",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Trust Boundary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Setup Steps",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Verify Single-Dash Route",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Verify Double-Dash Fork Route",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Inspect A Forked Session",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 509,
      "url": "/topics/codex-imp-hook-setup/",
      "markdownUrl": "/markdown/codex-imp-hook-setup.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-imp-hook-setup.json",
      "headings": [
        {
          "id": "what-this-adds",
          "text": "What This Adds",
          "level": 2
        },
        {
          "id": "install-targets",
          "text": "Install Targets",
          "level": 2
        },
        {
          "id": "files-in-this-directory",
          "text": "Files In This Directory",
          "level": 2
        },
        {
          "id": "trust-boundary",
          "text": "Trust Boundary",
          "level": 2
        },
        {
          "id": "setup-steps",
          "text": "Setup Steps",
          "level": 2
        },
        {
          "id": "verify-single-dash-route",
          "text": "Verify Single-Dash Route",
          "level": 2
        },
        {
          "id": "verify-double-dash-fork-route",
          "text": "Verify Double-Dash Fork Route",
          "level": 2
        },
        {
          "id": "inspect-a-forked-session",
          "text": "Inspect A Forked Session",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Install and inspect dash-prefix Imp routing\n\nThese files show a common local setup for dash-prefix Imp routing.\n\nThey are examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.\n\n## What This Adds\n\n```text\n-<imp> task\n-> foreground route\n-> hook adds Imp command/path/description/task/cwd\n-> main Codex turn continues\n\n--<imp> task\n-> fork route\n-> hook opens a cmux pane\n-> hook starts `codex fork <session> -- '-<imp> task'`\n-> hook blocks the current prompt\n```\n\n## Install Targets\n\n```text\n~/.codex/hooks/imp-user-prompt-submit.py\n~/.codex/hooks.json\n~/.local/bin/cmux-run-surface\n```\n\n## Files In This Directory\n\n| File | Purpose |\n| --- | --- |\n| `imp-user-prompt-submit.py.template` | UserPromptSubmit hook example for dash-prefix Imp routing |\n| `hooks.json.example` | minimal hook registration example |\n| `cmux-run-surface.example` | helper contract for opening a focused cmux pane and printing a receipt |\n| `cmux-codex-session-registry.py.example` | redacted contract for resolving a cmux surface id to a Codex session id |\n\n## Trust Boundary\n\nHooks run during prompt submission. They can block prompts, launch local commands, open cmux panes, and write logs.\n\nBefore installing:\n\n```bash\npython3 -m py_compile hooks/imp-user-prompt-submit.py.template\npython3 -m json.tool hooks/hooks.json.example >/dev/null\nrg -n \"<your-secret-patterns>\" hooks\n```\n\n## Setup Steps\n\nCopy only after review:\n\n```bash\nmkdir -p ~/.codex/hooks ~/.local/bin\ncp hooks/imp-user-prompt-submit.py.template ~/.codex/hooks/imp-user-prompt-submit.py\ncp hooks/cmux-run-surface.example ~/.local/bin/cmux-run-surface\nchmod +x ~/.codex/hooks/imp-user-prompt-submit.py ~/.local/bin/cmux-run-surface\n```\n\nMerge `hooks/hooks.json.example` into `~/.codex/hooks.json`. Do not overwrite an existing hooks file blindly.\n\nIf you use helpers that fork the focused Codex conversation from a cmux surface,\nreview `hooks/cmux-codex-session-registry.py.example` and install an equivalent\nregistry implementation at:\n\n```text\n~/.codex/hooks/cmux-codex-session-registry.py\n```\n\n## Verify Single-Dash Route\n\nInside a Codex session with the hook enabled:\n\n```text\n-gmail draft a short email about this conversation\n```\n\nExpected:\n\n- main prompt continues\n- hook context resolves `imp-gmail`\n- hook context includes executable path, description, task text, and cwd\n- main agent does not rediscover the Imp with `which`, `where`, `find`, or broad search\n\n## Verify Double-Dash Fork Route\n\nInside a Codex session with cmux available:\n\n```text\n--gmail draft a short email about this conversation\n```\n\nExpected:\n\n- current prompt blocks\n- new cmux pane opens\n- fork receives normalized prompt `-gmail draft a short email about this conversation`\n- block message includes workspace, pane, surface, and window\n- block message includes read-screen, top, and focus-pane commands\n\n## Inspect A Forked Session\n\nUse the ids printed by the hook:\n\n```bash\ncmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80\ncmux top --workspace workspace:<id> --processes --flat --format tsv\ncmux focus-pane --workspace workspace:<id> --pane pane:<id>\n```\n\n## If It Goes Wrong\n\nCheck the roster and health:\n\n```bash\nimp -l\nimp --which \"your task\"\nimps doctor\n```\n\nCheck cmux:\n\n```bash\ncmux rpc workspace.current\ncommand -v cmux-run-surface\ntail -n 40 ~/Library/Logs/cmux-run-surface.log\n```\n\nCheck hook output:\n\n```bash\ntail -n 20 ~/.codex/logs/imp-user-prompt-submit.jsonl\n```\n\nDo not route dash-prefix fork prompts through helpers that create a fork id and then resume it with the dash-starting prompt. A prompt like `-gmail ...` can be parsed as options. Use direct `codex fork <source-session> -- '-gmail ...'`.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-daemon-profile-playbook",
      "slug": "daemon-profile-playbook",
      "title": "Isolated Codex daemon profile playbook",
      "summary": "Web developers constantly repeat narrow CLI work around local dev servers, deploy previews, browser QA, GitHub checks, and framework tooling. An isolated Codex daemon profile turns one repetitive tool workflow into a cheap, warm, low-context helper instead of dragging a full general agent through every small task.",
      "category": "Execution",
      "tags": [
        "daemons",
        "SDK",
        "low reasoning",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-09.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#daemon-profile",
        "scenarios/daemon-profile.json#audienceFit",
        "toolkit/prompts/09-isolated-codex-daemon-profile.md",
        "toolkit/codex-skills/codex-daemon-profile/SKILL.md",
        "scenarios/daemon-profile.json#scenarios/0",
        "scenarios/daemon-profile.json#scenarios/1",
        "scenarios/daemon-profile.json#scenarios/2",
        "scenarios/daemon-profile.json#implementationNotes",
        "scenarios/daemon-profile.json#notTaughtOrAvoid/1",
        "scenarios/daemon-profile.json#notTaughtOrAvoid/2",
        "scenarios/daemon-profile.json#notTaughtOrAvoid/3",
        "scenarios/daemon-profile.json#notTaughtOrAvoid/4",
        "scenarios/daemon-profile.json#notTaughtOrAvoid/5",
        "scenarios/daemon-profile.json#agentReferences",
        "toolkit/bundles/code-codex-daemons.md"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 3323,
      "url": "/topics/foundations-daemon-profile-playbook/",
      "markdownUrl": "/markdown/foundations-daemon-profile-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-daemon-profile-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "local-browser-qa-daemon-for-a-flaky-signup-flow",
          "text": "Local browser QA daemon for a flaky signup flow",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "preview-deployment-triage-daemon",
          "text": "Preview deployment triage daemon",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "create-a-focused-accessibility-audit-daemon",
          "text": "Create a focused accessibility audit daemon",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "codex-daemon-profile-skill",
          "text": "Codex daemon profile skill",
          "level": 3
        },
        {
          "id": "isolated-profile-prompt",
          "text": "Isolated profile prompt",
          "level": 3
        },
        {
          "id": "verified-codex-daemons-command-patterns",
          "text": "Verified codex-daemons command patterns",
          "level": 3
        },
        {
          "id": "lesson-09-validated-references",
          "text": "Lesson 09 validated references",
          "level": 3
        },
        {
          "id": "lesson-09-validation-notes",
          "text": "Lesson 09 validation notes",
          "level": 3
        },
        {
          "id": "build-and-verification-target",
          "text": "Build and verification target",
          "level": 3
        },
        {
          "id": "command-reference",
          "text": "Command reference",
          "level": 2
        },
        {
          "id": "profile-file-shape-daemons-pro-gh-daemons-pro-packx-real-runnable",
          "text": "Profile file shape (daemons/pro-gh, daemons/pro-packx — real, runnable)",
          "level": 2
        },
        {
          "id": "isolation-config-keys-applied-by-runprofile-lib-isolated-ts-real",
          "text": "Isolation config keys applied by runProfile (lib/isolated.ts — real)",
          "level": 2
        },
        {
          "id": "token-budget-docs-isolation-md",
          "text": "Token budget (docs/ISOLATION.md)",
          "level": 2
        },
        {
          "id": "docs-prompt-md-after-generation-steps-real",
          "text": "docs/PROMPT.md after-generation steps (real)",
          "level": 2
        }
      ],
      "markdown": "# Isolated Codex daemon profile playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers constantly repeat narrow CLI work around local dev servers, deploy previews, browser QA, GitHub checks, and framework tooling. An isolated Codex daemon profile turns one repetitive tool workflow into a cheap, warm, low-context helper instead of dragging a full general agent through every small task.\n\n[Core principles](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Copy-paste workflow\n\n**When to use:** When a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm agent instead of a full general agent. This wraps one CLI in a single-purpose Codex SDK profile with a tight context ceiling.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. Generate a new isolated \"pro-<TOOL>\" Codex daemon profile for the <TOOL> CLI, following the codex-daemons pattern. The point is a cheap, fast, low-context warm agent that does ONE thing — target ~6-10K input tokens.\n\n1. Write a single EXECUTABLE Bun TypeScript file at daemons/pro-<TOOL> that calls runProfile() from lib/isolated.ts. Use this prompt shape inside developerInstructions:\n     ## Operating rule  -> run <TOOL> via exec_command before any final answer; never answer from memory\n     ## Command map     -> KEYWORD -> <TOOL> COMMAND  (e.g. status -> <TOOL> status; help -> <TOOL> --help)\n     ## Workflow        -> narrowest read-only command first; mutate only when target+action are explicit; on usage error run --help then retry once\n     ## Command rules   -> use only <TOOL>; no web, no images, no file edits unless explicitly asked\n     ## Output          -> be terse; report what you found/changed\n   Keep the command map LITERAL — do not dump --help text. Use a low-reasoning model (reasoningEffort default \"low\"; default model gpt-5.3-codex-spark).\n\n2. The isolation is applied by runProfile() — it sets: base_instructions replaced, developer_instructions custom, skills.include_instructions=false, include_apps_instructions=false, include_environment_context=false, include_permissions_instructions=false, memories.use_memories=false, mcp_servers={}, web_search=\"disabled\", features {plugins, apps, image_generation, tool_search, tool_suggest} all false (features.apps=false alone saves ~14K tokens), CODEX_HOME redirected to a disposable /tmp dir, and auth.json symlinked from real ~/.codex so token refreshes propagate.\n\n3. After generating, run these steps:\n     chmod +x daemons/pro-<TOOL>\n     bun daemons/pro-<TOOL> --help        # smoke test\n     # add daemons/pro-<TOOL> to package.json \"bin\", then:\n     bun link                              # put it on PATH\n\nPrereqs: Bun runtime; @openai/codex-sdk; an authenticated @openai/codex CLI.\n```\n\n### How it works\n- A profile is a single executable Bun TS file using `runProfile()` from `lib/isolated.ts`, with the Oracle-tuned prompt shape: Operating rule -> Command map -> Workflow -> Command rules -> Output.\n- The context ceiling comes from real isolation keys: `base_instructions` replaced, custom `developer_instructions`, `skills.include_instructions=false`, apps/environment/permissions instructions off, `memories.use_memories=false`, `mcp_servers={}`, `web_search=\"disabled\"`, and `features` (plugins/apps/image_generation/tool_search/tool_suggest) all false — `features.apps=false` alone saves ~14K tokens.\n- `CODEX_HOME` is redirected to a disposable `/tmp` dir and `auth.json` is symlinked from real `~/.codex` so token refreshes propagate.\n- Use a low-reasoning model and keep prompts literal (command map over dumping `--help`); target ~6-10K input tokens (default full config is ~22K).\n- After-generation: `chmod +x`, `bun daemons/pro-<TOOL> --help`, add to `package.json` bin, `bun link`.\n- Reference: [codex-daemons](https://github.com/johnlindquist/codex-daemons), [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk), [Bun](https://bun.sh).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/codex-daemon-profile/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: codex-daemon-profile\ndescription: Trigger when a repetitive, well-scoped CLI task should run on a cheap, fast, low-context warm Codex daemon instead of a full general agent — generate an isolated pro-TOOL profile. Do NOT use for broad multi-tool or judgment-heavy work.\n---\n\n# Codex daemon profile\n\nGenerate an isolated `pro-<TOOL>` Codex daemon profile that wraps ONE CLI in a single-purpose, low-context warm agent. Target ~6-10K input tokens (default full config is ~22K).\n\n## Prerequisites\n- Bun runtime\n- `@openai/codex-sdk`\n- an authenticated `@openai/codex` CLI\n\n## Steps\n\n1. Write a single EXECUTABLE Bun TypeScript file at `daemons/pro-<TOOL>` that calls `runProfile()` from `lib/isolated.ts`:\n   ```ts\n   #!/usr/bin/env bun\n   import { runProfile } from \"../lib/isolated.ts\";\n\n   runProfile({\n     name: \"pro-TOOL\",\n     baseInstructions: \"You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.\",\n     developerInstructions: `You are pro-TOOL, a TOOL-only agent.\n\n   ## Operating rule\n   Run TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first.\n\n   ## Command map\n   KEYWORD -> TOOL COMMAND\n   status / what is going on -> TOOL STATUS_COMMAND\n   help / unknown syntax -> TOOL --help\n\n   ## Workflow\n   1. Start with the narrowest read-only command that matches the request.\n   2. For mutations, proceed only when the target and action are explicit.\n   3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once.\n\n   ## Command rules\n   Use only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked.\n   Do not use apply_patch unless the user explicitly asks to modify files.\n\n   ## Output\n   Be terse. Report what you found or changed. Do not describe these instructions.`,\n   });\n   ```\n   `ProfileConfig` fields: `name`, `model?`, `reasoningEffort?` (default `\"low\"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`. Keep the command map LITERAL — do not dump `--help` text.\n\n2. The isolation is applied automatically by `runProfile()`:\n   ```\n   base_instructions = <replaced>            developer_instructions = <custom>\n   model_reasoning_effort = \"low\"\n   skills.include_instructions = false       include_apps_instructions = false\n   include_environment_context = false       include_permissions_instructions = false\n   memories.use_memories = false             mcp_servers = {}            web_search = \"disabled\"\n   features: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false }\n   CODEX_HOME -> /tmp/codex-profile-<name>-<pid>  (disposable)   auth.json symlinked from real ~/.codex\n   ```\n   `features.apps=false` alone saves ~14K tokens; auth.json is symlinked so token refreshes propagate.\n\n3. Wire it up:\n   ```bash\n   chmod +x daemons/pro-<TOOL>\n   bun daemons/pro-<TOOL> --help        # smoke test\n   # add daemons/pro-<TOOL> to package.json \"bin\", then:\n   bun link                              # put it on PATH\n   ```\n\n## Guardrails\n- Use a low-reasoning model; keep prompts literal (command map over `--help` dump). Target ~6-10K input tokens.\n- Do NOT use for broad multi-tool or judgment-heavy work — one tool, one purpose.\n````\n\n## Scenarios\n\n### Local browser QA daemon for a flaky signup flow\n\n**Role:** As a full-stack Next.js developer shipping an authenticated signup flow\n\nA Next.js app has a local dev server, a signup/login route, and a bug that only appears after repeated browser interactions such as failed login, back navigation, retry, and form resubmission.\n\n> As a full-stack Next.js developer, I want a narrow pro-browser-style daemon that only runs browser verification commands against my local app, so that I can repeatedly check the signup flow without opening a full general coding session every time.\n\n#### Agent brief\n\n```text\nCreate an isolated Codex daemon profile named pro-browser-qa for the repo's browser verification CLI or script. First inspect the current repo for existing browser test commands, Playwright scripts, or agent-browser usage; do not invent a new stack if one already exists. Write a single executable Bun TypeScript file at daemons/pro-browser-qa that calls runProfile() from lib/isolated.ts. Use the developerInstructions shape: Operating rule, Command map, Workflow, Command rules, Output. The operating rule must require running the browser QA command through exec_command before any final answer. The command map should include only the local commands this repo actually has, such as dev server health check, run signup flow, run login flow, capture console output, capture screenshot, and help. Keep the map literal; do not paste full --help output. Mutations are not allowed: this daemon verifies and reports only. After creating it, run chmod +x daemons/pro-browser-qa, run bun daemons/pro-browser-qa --help, add it to package.json bin if the repo uses that pattern, and run bun link. Expected output: a terse report with command run, route tested, pass/fail, browser evidence path, console errors, and next action.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n[Open reference](/topics/foundations-daemon-profile-playbook/#command-reference)\n\n```text\ndaemons/pro-<TOOL>\n```\n\n```text\nlib/isolated.ts\n```\n\n```text\npackage.json\n```\n\n```text\nchmod +x daemons/pro-browser-qa\n```\n\n```text\nbun daemons/pro-browser-qa --help\n```\n\n```text\nbun link\n```\n\n#### Browser verification\n\nUse a local browser verification move because this is a browser-visible bug: start the app with the repo's dev command, then have the daemon run the existing browser script or agent-browser-style flow to snapshot the signup page, fill the email/password fields, click submit, navigate back, retry, and collect screenshot plus console output. If CMUX is available, open the app in a browser pane and keep the daemon terminal visible beside it.\n\n#### Definition of done\n\n- daemons/pro-browser-qa exists, is executable, and calls runProfile() from lib/isolated.ts\n- bun daemons/pro-browser-qa --help runs without crashing\n- The profile prompt has Operating rule, Command map, Workflow, Command rules, and Output sections\n- The daemon performs read-only browser verification before answering\n- A verification receipt includes tested URL, exact command, pass/fail, screenshot or trace path, console errors, and any failed selector or step\n- package.json bin and bun link are updated only if the repo uses that executable profile pattern\n\n#### Failure modes and mitigations\n\n- Mistake: the agent builds a broad browser-and-code-editing assistant. Mitigation: keep this daemon browser-QA-only, no file edits unless explicitly requested, and no web browsing beyond the local app.\n- Mistake: the daemon answers from memory or source inspection without running the browser flow. Mitigation: the operating rule must require exec_command first and the final answer must name the command and artifact path.\n- Mistake: the profile dumps full Playwright or tool help into developerInstructions. Mitigation: use a curated keyword-to-command map and fall back to --help only on syntax errors.\n- Mistake: authenticated flow assumes normal browser cookies exist. Mitigation: script login/setup explicitly or use a seeded test account path documented in the repo.\n\n### Preview deployment triage daemon\n\n**Role:** As a frontend lead reviewing preview builds before merge\n\nA pull request deploys a preview URL, but every review requires the same narrow checks: list the current deployment, inspect status, open the preview route, confirm key pages render, and summarize only the blocking issues.\n\n> As a frontend lead, I want a pro-deploy-check daemon around my deployment CLI, so that preview triage is fast, repeatable, and limited to deployment status plus browser proof instead of turning into a broad coding session.\n\n#### Agent brief\n\n```text\nCreate an isolated Codex daemon profile named pro-deploy-check for the repo's deployment CLI or existing preview-check script. Inspect package.json and repo scripts first. If the repo already uses a specific deploy CLI, wrap that one CLI only. Write daemons/pro-deploy-check as a single executable Bun TypeScript file using runProfile() from lib/isolated.ts. The daemon must start with the narrowest read-only command: deployment status or preview URL discovery. The command map should cover status, current preview, logs, inspect URL, and help, using exact repo commands. For mutations, require explicit target and action; default to read-only. Disable broad behavior in the prompt: no web search, no image generation, no unrelated file edits, no apply_patch unless explicitly asked. After generation, run chmod +x daemons/pro-deploy-check, bun daemons/pro-deploy-check --help, test one real prompt such as 'status for the current PR preview', then add package.json bin and bun link if appropriate. Expected output: current deployment state, preview URL, failing route if any, command evidence, and browser proof path.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n[Open reference](/topics/foundations-daemon-profile-playbook/#command-reference)\n\n```text\npackage.json scripts\n```\n\n```text\ndaemons/pro-deploy-check\n```\n\n```text\nlib/isolated.ts\n```\n\n```text\nchmod +x daemons/pro-deploy-check\n```\n\n```text\nbun daemons/pro-deploy-check --help\n```\n\n```text\nbun link\n```\n\n#### Browser verification\n\nUse browser proof after the daemon discovers the preview URL: open the preview in a CMUX browser pane or run the repo's browser automation to snapshot the homepage and one changed route, then record status code, visible error text, console errors, and screenshot path. Browser proof is useful here because deployment status alone does not prove the UI renders.\n\n#### Definition of done\n\n- The profile wraps one deployment or preview-check CLI only\n- The first command is read-only status or preview discovery\n- bun daemons/pro-deploy-check --help succeeds\n- A real prompt returns deployment status, preview URL, and exact commands run\n- Browser evidence exists for at least the homepage and one changed route\n- The final report is terse and separates blocker, warning, and clean result\n\n#### Failure modes and mitigations\n\n- Mistake: the agent creates a general CI/CD bot with many tools and broad permissions. Mitigation: one CLI, one profile, read-only first, mutate only when target plus action are explicit.\n- Mistake: it trusts a green deployment status without checking the rendered app. Mitigation: require browser proof for at least one preview route before final answer.\n- Mistake: it hardcodes a vendor-specific command not present in the repo. Mitigation: inspect package.json and existing scripts first, then map only verified local commands.\n- Mistake: it bloats context with full docs or --help output. Mitigation: keep a small curated command map and use --help only as a retry path.\n\n### Create a focused accessibility audit daemon\n\n**Role:** As a frontend platform engineer supporting multiple product teams\n\nSeveral teams ship React pages with recurring accessibility regressions: missing form labels, buttons without accessible names, skipped headings, and modals that trap focus inconsistently. The work is repetitive and command-driven, but each audit still needs a concise human-readable report.\n\n> As a frontend platform engineer, I want a narrow Codex daemon that runs the project accessibility checks and browser proof steps, so that teams get consistent reports without asking a general assistant to rediscover the workflow each time.\n\n#### Agent brief\n\n```text\nBuild or use an isolated Codex daemon profile for accessibility triage only. Keep the command map narrow: inspect package scripts, run the existing accessibility or browser-test command if present, start the local dev server only when required, open the target route in a browser, capture an accessibility snapshot, and report missing labels/headings/focus problems with file or route pointers. The daemon should write one markdown report under `.notes/a11y/<route-slug>.md` with commands run, browser route, snapshot summary, issues found, false positives, and recommended next fixes. It must not edit files unless explicitly asked after the audit report is reviewed.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n```text\npackage.json scripts\n```\n\n```text\ntarget app route/component files\n```\n\n```text\ncmux browser snapshot or existing Playwright accessibility checks\n```\n\n#### Browser verification\n\nUse browser proof because accessibility is runtime UI behavior. Open the target localhost route, take an accessibility snapshot, click or tab through the primary form/modal/menu path, evaluate focus state where useful, and save the route plus snapshot summary in the daemon report. If no browser surface is available, state that runtime accessibility proof is missing rather than claiming success from source inspection.\n\n#### Definition of done\n\n- The daemon profile has one narrow responsibility and a small command map.\n- A markdown report exists under `.notes/a11y/` with exact commands, route, browser proof, and prioritized issues.\n- The daemon did not edit source files during audit-only mode.\n- The report distinguishes confirmed runtime issues from possible source-level concerns.\n\n#### Failure modes and mitigations\n\n- The daemon becomes a broad product assistant; mitigate by keeping its profile limited to accessibility triage commands and reports.\n- The daemon claims accessibility from static source reading; mitigate by requiring browser snapshot/focus evidence for runtime findings.\n- The daemon mutates code during audit; mitigate by making audit-only mode the default and requiring explicit follow-up approval for fixes.\n\n## Implementation notes\n\n- Keep each daemon wrapped around exactly one CLI or one repo-local script family. The whole point is a narrow helper, not another giant assistant.\n- Use the runProfile() shape from lib/isolated.ts: one executable Bun TypeScript file, low reasoning by default, literal developerInstructions, and a curated command map.\n- The prompt order matters: Operating rule first, then Command map, then Workflow, Command rules, and Output.\n- Make the daemon run a command before answering. A daemon that summarizes from memory is just a small hallucination machine with a fancy name.\n- Default to read-only discovery. Require explicit target plus action for mutations, especially deploy, Docker, database, cloud, or file-editing tools.\n- Do not paste full --help output into instructions. Keep the command map tight and use --help only when syntax is uncertain or a usage error occurs.\n- For web app work, pair command receipts with browser receipts when the user-visible app matters: local URL, route, action sequence, screenshot or trace path, console errors, and pass/fail.\n- Treat self-improvement as experimental and narrow. It fits predictable CLI/API failure modes better than broad product implementation.\n\n## Boundaries and caveats\n\n- Do not introduce unrelated workflow tools only mentioned in the lesson as if they were taught implementation steps.\n- Do not build an all-purpose autonomous swarm. Parallel agents need an analysis or synthesis step, and this topic is exactly one toolkit technique.\n- Do not claim arbitrary line-count rules for agent-readable code. The taught guidance favors clear state machines, named cases, and English-readable conditions.\n- Do not make browser automation unbounded or credential-casual. Keep it scoped to local app verification or explicit preview URLs with clear proof artifacts.\n- Do not use daemon profiles for judgment-heavy planning, product strategy, or multi-tool implementation. Use them for repetitive, well-scoped CLI work.\n\n## Agent reference map\n\n### Codex daemon profile skill\n\nUse as the implementation contract for when to trigger this technique, profile shape, prerequisites, isolation behavior, and guardrails.\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n### Isolated profile prompt\n\nUse as the copy-paste user-facing prompt pattern for generating a new pro-<TOOL> profile.\n\n[Open reference](/topics/foundations-daemon-profile-playbook/)\n\n### Verified codex-daemons command patterns\n\nUse for the real executable file shape, runProfile() call, ProfileConfig fields, isolation keys, token-budget notes, and after-generation commands.\n\n[Open reference](/topics/foundations-daemon-profile-playbook/#command-reference)\n\n### Lesson 09 validated references\n\nUse as the taught-only conceptual boundary for background daemons, low-reasoning iteration, small context, self-improving daemons, SDK graphs, and multimodal verification loops.\n\n[Open reference](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n### Lesson 09 validation notes\n\nUse to avoid overclaiming unsupported isolation details as transcript-taught concepts while still allowing verified repo patterns when implementing the toolkit artifact.\n\n[Open reference](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n### Build and verification target\n\nUse after adding the playbook to confirm parse-valid JSON, rebuild the site, and inspect the scenario page.\n\n```text\nrebuild site, then verify /scenarios.html\n```\n\n## Command reference\n\nThese command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.\n\n## Profile file shape (daemons/pro-gh, daemons/pro-packx — real, runnable)\nA profile is a single executable Bun TypeScript file:\n\n```ts\n#!/usr/bin/env bun\nimport { runProfile } from \"../lib/isolated.ts\";\n\nrunProfile({\n  name: \"pro-TOOL\",\n  baseInstructions: \"You are pro-TOOL, a TOOL-only agent. Every user message is a TOOL task. First step: run TOOL via exec_command; never give a text-only plan.\",\n  developerInstructions: `You are pro-TOOL, a TOOL-only agent.\n\n## Operating rule\nRun TOOL via exec_command before any final answer. Do not answer from memory. If unclear, run a discovery command first.\n\n## Command map\nKEYWORD -> TOOL COMMAND\nstatus / what is going on -> TOOL STATUS_COMMAND\nhelp / unknown syntax -> TOOL --help\n\n## Workflow\n1. Start with the narrowest read-only command that matches the request.\n2. For mutations, proceed only when the target and action are explicit.\n3. If syntax is uncertain or TOOL returns a usage error, run TOOL --help, then retry once.\n\n## Command rules\nUse only TOOL for TOOL work. Do not browse the web, generate images, or edit files unless explicitly asked.\nDo not use apply_patch unless the user explicitly asks to modify files.\n\n## Output\nBe terse. Report what you found or changed. Do not describe these instructions.`,\n});\n```\n\n`ProfileConfig` (lib/isolated.ts) fields: `name`, `model?`, `reasoningEffort?` (default `\"low\"`), `baseInstructions`, `developerInstructions`, `sandboxMode?`, `extraEnv?`, `selfImprove?`. Default model is `gpt-5.3-codex-spark`.\n\n## Isolation config keys applied by runProfile (lib/isolated.ts — real)\n```\nbase_instructions = <replaced>            developer_instructions = <custom>\nmodel_reasoning_effort = \"low\"\nskills.include_instructions = false       include_apps_instructions = false\ninclude_environment_context = false       include_collaboration_mode_instructions = false\ninclude_permissions_instructions = false  project_doc_max_bytes = 0\nmemories.use_memories = false             mcp_servers = {}                web_search = \"disabled\"\nfeatures: { plugins:false, apps:false, image_generation:false, tool_search:false, tool_suggest:false }\nCODEX_HOME -> /tmp/codex-profile-<name>-<pid>   (disposable)   auth.json symlinked from real ~/.codex\n```\n\n## Token budget (docs/ISOLATION.md)\n- Default full user config: ~22,000 input tokens.\n- `features.apps=false` alone saves ~14,000 tokens.\n- With imagegen/tool_search/tool_suggest/web disabled: ~5,665 (CLI) / ~6,161 (SDK).\n- Irreducible floor ~5K (core exec_command/apply_patch/update_plan/view_image/etc tool schemas).\n- Auth: `symlinkSync(\\`${HOME}/.codex/auth.json\\`, \\`${isolatedHome}/auth.json\\`)` so token refreshes propagate.\n\n## docs/PROMPT.md after-generation steps (real)\n1. Save to `daemons/pro-your-tool`. 2. `chmod +x daemons/pro-your-tool`.\n3. Test `bun daemons/pro-your-tool --help`. 4. Test with a real prompt.\n5. Add to `package.json` `bin`. 6. `bun link` to put it on PATH.\n\nDependency: `@openai/codex-sdk` (also requires authenticated `@openai/codex` CLI). Runtime: Bun."
    },
    {
      "id": "codex-parallel-agents",
      "slug": "parallel-agents",
      "title": "Keep parallel agent work visible and bounded",
      "summary": "A parallel workspace is not useful because it looks busy. It is useful when each lane has a job, a boundary, a check, and a visible trail. Start by planning the split. Then open the workspace that makes that split easy to supervise.",
      "category": "Execution",
      "tags": [
        "parallelism",
        "ownership",
        "orchestration"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#parallel-agents"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-06-visible-parallel-agents.md",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Start Fresh For The Task",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Split By Boundaries, Not By Vibes",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Keep The Agents Visible",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Use A Manager Thread",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Copyable Prompt: Parallel Work Plan",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Copyable Prompt: Lane Setup",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Make Progress Legible",
        "src/content/final/chunk-06-visible-parallel-agents.md#Run Parallel Agents Where You Can Still See Them/Save The Layout Only After It Repeats",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#parallel-agents",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 887,
      "url": "/topics/codex-parallel-agents/",
      "markdownUrl": "/markdown/codex-parallel-agents.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-parallel-agents.json",
      "headings": [
        {
          "id": "start-fresh-for-the-task",
          "text": "Start Fresh For The Task",
          "level": 2
        },
        {
          "id": "split-by-boundaries-not-by-vibes",
          "text": "Split By Boundaries, Not By Vibes",
          "level": 2
        },
        {
          "id": "keep-the-agents-visible",
          "text": "Keep The Agents Visible",
          "level": 2
        },
        {
          "id": "use-a-manager-thread",
          "text": "Use A Manager Thread",
          "level": 2
        },
        {
          "id": "copyable-prompt-parallel-work-plan",
          "text": "Copyable Prompt: Parallel Work Plan",
          "level": 2
        },
        {
          "id": "copyable-prompt-lane-setup",
          "text": "Copyable Prompt: Lane Setup",
          "level": 2
        },
        {
          "id": "make-progress-legible",
          "text": "Make Progress Legible",
          "level": 2
        },
        {
          "id": "save-the-layout-only-after-it-repeats",
          "text": "Save The Layout Only After It Repeats",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Keep parallel agent work visible and bounded\n\nA parallel workspace is not useful because it looks busy. It is useful when each lane has **a job, a boundary, a check, and a visible trail**. Start by planning the split. Then open the workspace that makes that split easy to supervise.\n\n## Start Fresh For The Task\n\nDo not begin by hunting for the perfect saved layout. Begin with the **current phase of work**: what needs design, what needs implementation, what needs verification, and what can safely happen at the same time.\n\nA dashboard task, a migration, a game level, and a new project do not need the same shape. **Ask for the split that fits the task in front of you.**\n\nFor a dashboard:\n\n- one lane designs the data cards\n- one lane checks API shape and sample data\n- one lane writes component tests\n- one lane reviews empty, loading, and error states\n\nFor a migration:\n\n- one lane maps the source schema\n- one lane maps the destination schema\n- one lane writes verification queries\n- one lane drafts rollback notes\n\n## Split By Boundaries, Not By Vibes\n\nEach lane needs a job, allowed files, files to avoid, and proof. If two lanes need the same files, they are **not parallel yet**.\n\n> How can we accomplish this task with multiple agents, where they each have their own responsibility, and they each have their own testing, they can work in parallel, usually in the same branch, honestly.\n>\n> — John Lindquist\n\n| Lane | Owns | Avoids | Proof |\n|---|---|---|---|\n| UI lane | `src/routes/dashboard/**`, component snapshots | API contracts, migration files | screenshot and component checks |\n| Data lane | query helpers, fixtures, schema mapping | visual components | query tests |\n| Test lane | new regression tests | production logic except test hooks | failing-before / passing-after log |\n| Review lane | risk notes, integration checklist | code edits | written review with blockers |\n\n## Keep The Agents Visible\n\n**Visible work is easier to correct.** You can inspect the history, compare outputs, step into one lane, or stop a bad direction before it spreads.\n\nHidden background work can be useful, but it removes the trail you need when the next run should be better. If the task is risky, keep the lanes where you can watch them.\n\n> When I see agents spawn up in background threads, and I don't know what they're doing, and I can't, like, look at some of the history and tool calls and everything. I don't know how it could improve next time.\n>\n> — John Lindquist\n\n## Use A Manager Thread\n\n**One thread owns the plan.** Other lanes execute bounded work. The manager does not need to do every task. It needs to remember the split, check progress, catch conflicts, and decide when to merge, redirect, or stop.\n\nManager responsibilities:\n\n- restate the project goal\n- divide work into lanes\n- assign file boundaries\n- name the verification for each lane\n- tell each lane which other lanes exist\n- check progress before merging ideas\n- stop any lane that crosses its boundary\n\n## Copyable Prompt: Parallel Work Plan\n\n```text\nWe need to plan parallel agent work for this software task.\n\nTask:\n[describe the feature, fix, migration, or review]\n\nCurrent phase:\n[planning / implementation / debugging / visual review / verification]\n\nProject facts:\n- active areas:\n- stable areas to avoid:\n- commands/tests available:\n- risky files:\n- expected output:\n\nCreate a parallel work plan.\n\nReturn:\n1. the smallest useful number of lanes\n2. the responsibility of each lane\n3. exact file or directory boundaries for each lane\n4. what each lane must not touch\n5. the verification each lane must run\n6. the manager check-in schedule\n7. the prompt to initialize each lane\n\nPrefer fewer lanes if file conflicts are likely.\nDo not start implementation yet.\n```\n\n## Copyable Prompt: Lane Setup\n\n```text\nYou are Lane [name].\n\nGoal:\n[one responsibility]\n\nAllowed files:\n[list]\n\nDo not touch:\n[list]\n\nOther lanes running:\n- [lane]: [scope]\n- [lane]: [scope]\n\nBefore editing:\n- inspect only your allowed area\n- restate the files you expect to touch\n- name the verification you will run\n\nAfter editing:\n- summarize changes\n- list files changed\n- run verification\n- report any boundary conflicts\n```\n\n## Make Progress Legible\n\nUse agents to make proof easier to produce: screenshots, before/after numbers, test logs, release notes, and short visual summaries. The goal is not noise. The goal is **reviewable impact**.\n\nBefore/after performance note:\n\n```text\nBefore:\nDashboard loaded sample account in 4.8s.\n\nAfter:\nDashboard loaded sample account in 1.9s.\n\nProof:\nTrace attached, test command included.\n\nChange:\nCached account summary query and removed duplicate fetch.\n```\n\nVisual progress note:\n\n```text\nWhat changed:\nReplaced manual export flow with a reviewed batch job.\n\nWhy it matters:\nRemoves three support steps.\n\nProof:\nScreenshot, smoke test, rollback note.\n```\n\n## Save The Layout Only After It Repeats\n\n**A reusable layout is earned.** If the same task shape appears three times with the same lane split, checks, and review surface, turn it into a saved workspace, script, or small helper.\n\nUntil then, start fresh and ask for the split.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#parallel-agents)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "factory-markdown-flows",
      "slug": "markdown-flows",
      "title": "Markdown flows as a repeatable control surface",
      "summary": "Preload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.",
      "category": "Execution",
      "tags": [
        "markdown",
        "factory"
      ],
      "sources": [
        {
          "label": "Markdown flows as a repeatable control surface",
          "url": "https://walnut-virtue-6d22.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows"
        }
      ],
      "sourceUnits": [
        "05-mdflow/index.html#TL;DR",
        "05-mdflow/index.html#The briefing you keep re-typing",
        "05-mdflow/index.html#Appendix",
        "05-mdflow/index.html#Context lands before the first token",
        "05-mdflow/index.html#A global specialist flow, printed in full",
        "05-mdflow/index.html#One launcher, isolation by default",
        "05-mdflow/index.html#Flows change by proposal, not by vibes",
        "learn.html#q2-markdown-flows"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 1485,
      "url": "/topics/factory-markdown-flows/",
      "markdownUrl": "/markdown/factory-markdown-flows.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "the-briefing-you-keep-re-typing",
          "text": "The briefing you keep re-typing",
          "level": 2
        },
        {
          "id": "context-lands-before-the-first-token",
          "text": "Context lands before the first token",
          "level": 2
        },
        {
          "id": "a-global-specialist-flow-printed-in-full",
          "text": "A global specialist flow, printed in full",
          "level": 2
        },
        {
          "id": "one-launcher-isolation-by-default",
          "text": "One launcher, isolation by default",
          "level": 2
        },
        {
          "id": "flows-change-by-proposal-not-by-vibes",
          "text": "Flows change by proposal, not by vibes",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "turn-good-prompts-into-inspectable-flows",
          "text": "Turn good prompts into inspectable flows",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface\n\nPreload fresh evidence, declare capabilities, isolate ambient context, and improve prompts through explicit proposals.\n\n## Related working material\n\n- [Markdown flows as a repeatable control surface — prompts and exercises](/topics/factory-markdown-flows-practice/)\n- [Markdown flows as a repeatable control surface — questions and tradeoffs](/topics/factory-markdown-flows-questions/)\n- [Markdown flows as a repeatable control surface — worked example](/topics/factory-markdown-flows-worked-example/)\n\n## TL;DR\n\n- mdflow makes a repeatable agent job a versioned markdown \"flow\": shell output is inlined into the prompt at build time, so the agent starts already briefed on your git state, terminal panes, and tickets.\n- You walk away with a project roster (`npx mdflow init -y`) plus a pane-aware standup flow you can lift straight off this page.\n- The one move: the next briefing you type twice, put it in a flow file with `` !`command` `` inlines instead.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://walnut-virtue-6d22.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## The briefing you keep re-typing\n\nEvery fresh agent chat starts blind. You re-explain the branch, the panes, the ticket — and next session you type it all again. That briefing isn't free: it costs your time, and the agent's context fills with ambient setup before work starts. mdflow's answer is one markdown file per repeatable job — a \"flow\" — kept in the repo, runnable on any installed engine, inspectable before it executes. The README states the thesis directly: a Git-native control plane for repeatable agent work. A chat session is a performance you repeat; a flow is a script you version.\n\n## Context lands before the first token\n\nA flow embeds shell output with a `` !`command` `` inline. mdflow runs the command while building the prompt, so the agent never spends a tool-call round trip on `git status` — and never skips or reorders it. The standup flow above preloads four commands this way; `md doctor --json` reports exactly those four as its declared capabilities.\n\nThe pattern scales past one-liners. A production flow on the author's machine runs a preload script that fetches workshop ticket buyers from the payment provider and current calendar attendees, prints the computed diff as markdown, and then tells the agent: this data was fetched moments ago — do not re-fetch. One detail worth stealing: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent can relay it and stop rather than dying silently.\n\nYour feedback loop is `md explain`: it resolves the full configuration and lists every inline as a capability without executing anything. If your command shows up in the list, the context will land.\n\n## A global specialist flow, printed in full\n\nSome jobs recur across every project: keyboard config, shell config. The author's machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist. Here is the installed `flow-zsh` file, complete. It is shown to study, not to paste — it maps one person's zsh setup — but the anatomy is the lesson: a mission, a tool-output trust boundary, a command map covering the whole config domain, worked examples, an error-recovery table, and a mutation policy that demands verification after every edit. The agent gets all of it on every single run.\n\nThe specialist pattern declares a mission, an untrusted-evidence boundary, a narrow inspection command map, ownership rules, worked examples, mutation approval, and exact verification. Keep the operating instructions project-specific rather than copying another machine’s private configuration.\n\nThe weak move is a monolithic \"dotfiles assistant\" that answers from memory. The strong move is one flow per domain, each opening with \"never answer from memory\" and a first-step inspection command. `flow-karabiner` encodes the same discipline for keyboard config: read, make the smallest edit, run the compiler, then grep the generated JSON to prove the mapping exists.\n\n## One launcher, isolation by default\n\nSixty-five global flows plus project rosters create a discovery problem. Bare `md` answers it: the Flow Workbench, one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`.\n\nAnd every flow runs stripped by default. Your interactive session hauls memory files, hooks, MCP servers, and project instructions; a flow that reviews a diff needs none of it. mdflow disables ambient engine context using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex gets `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Anything the flow genuinely needs is declared in frontmatter; `_isolated: false` opts back into ambient. Isolation strips context — it does not confine the host. The inline commands and the engine still reach your filesystem, network, and credentials.\n\n``` text\n----------------------------------------------------------------------\nISOLATION\n----------------------------------------------------------------------\nON (default) — ambient engine context is disabled; host capabilities\nremain available\n   safe-mode: true\n   no-session-persistence: true\n   (opt out with _isolated: false)\n```\n\nThat block is captured from `md explain flows/workshop-standup.claude.md` in this demo project — isolation is on without any frontmatter asking for it.\n\n## Flows change by proposal, not by vibes\n\nA flow edited by hand after a bad run regresses silently. mdflow's evolve loop replaces the tweak with a process: record feedback (it gets a durable `fb_…` ID), preview the eval cost, generate an off-path proposal, and read the verification receipt. The canonical file stays byte-identical until you explicitly apply.\n\n``` text\nmd feedback flows/review.md \"missed the renamed-file regression\"\nmd eval flows/review.md --plan     # free cost preview of the eval suite\nmd evolve plan flows/review.md     # free: evidence, verification, cost, writes\nmd evolve propose flows/review.md  # off-path proposal; source unchanged\nmd evolve show <run-id>            # decision, capability diff, prompt diff\nmd evolve apply <run-id>           # atomic, explicit, reversible\n```\n\nThe outcome vocabulary is deliberately honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the proposal; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest. When a flow disappoints, file feedback in the moment and let the suite — not your memory — decide whether the fix is real.\n\n## Appendix\n\n### Limits & caveats\n\n- **Isolation is not a sandbox.** Context isolation strips prompts, hooks, and extensions; it does not confine the host. Inline commands and the engine retain full filesystem, network, environment, and credential access. Engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend.\n- **Eval verdicts in this demo are Unverified.** The starter suites exist, but no full eval receipt has been recorded, so `md doctor` reports every flow's verdict as `Unverified — no full eval receipt has been recorded`. The loop is the mechanism being demonstrated; this roster has not yet earned `verified_improvement` badges.\n- **Token savings are unquantified.** The sources support \"ambient material is not loaded\" and nothing more. No percentage is published; do not quote one.\n- **Engine defaults differ.** The starter roster defaults to the `pi` engine via `.mdflow.yaml`; the standup flow pins claude through its `.claude.md` filename. The same files run on other engines, but outputs are not interchangeable. Full resolution order: `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter `engine:` → project config → default (pi).\n- **The linear inline is a placeholder** in the public demo flow. The real version launches a sandboxed, read-only ticket-CLI agent; the placeholder keeps the published file runnable anywhere.\n- **Preloading captures state at launch.** It does not keep updating; a long-running agent that needs fresh state must still fetch it.\n\n## Operating practice\n\n### Turn good prompts into inspectable flows\n\n#### What to notice\n\nReuse a task recipe that can inject **fresh command output**, preserve **prompt structure**, and expose what the agent will receive.\n\n#### Try this\n\nPromote one prompt you have run twice into a flow with declared inputs and a dry-run inspection path.\n\n> “If you think of managing context as having only the context that I need for the specific task that I want.”\n\nJohn Lindquist · [02:55:29](https://proud-anchor-53zn.here.now/watch.html?t=10529#recording-player)\n\n#### Concept\n\nA flow should remove repeated composition work, not hide it. Inspect the rendered prompt, run from known state, and preserve failures when the wrapper or check does not behave as expected.\n\n#### Reflection\n\nThe recorded wrapper test did not become a clean success. The companion keeps that failure visible instead of rewriting history.\n\n**Recording evidence:** listen at 02:51:53.\n\n> “It's a pre-processing step, where it runs the code that's inside of here, which means it preloads context into the markdown file.”\n\nJohn Lindquist · [03:15:06](https://proud-anchor-53zn.here.now/watch.html?t=11706#recording-player)\n\n[Open mdflow](https://walnut-virtue-6d22.here.now/)\n\n#### Links shared for this topic\n\n- [Flow Text source](https://github.com/johnlindquist/flow-text/) — A repository for a reusable text-flow experiment.\n- [gog CLI](https://gogcli.sh/) — A command-line surface for Google services.\n- [Birdclaw](https://birdclaw.sh/) — A command-line social workflow tool.\n- [CodeGraph](https://colbymchenry.github.io/codegraph/) — A visual code-relationship explorer shown during workflow experiments.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=10313#q2-markdown-flows)"
    },
    {
      "id": "factory-markdown-flows-discussion",
      "slug": "markdown-flows-discussion",
      "title": "Markdown flows as a repeatable control surface — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Execution",
      "tags": [
        "markdown-flows",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[108]",
        "resource-manifest.json#videoEvidence.concepts[109]",
        "resource-manifest.json#videoEvidence.concepts[110]",
        "resource-manifest.json#videoEvidence.concepts[111]",
        "resource-manifest.json#videoEvidence.concepts[112]",
        "resource-manifest.json#videoEvidence.concepts[113]",
        "resource-manifest.json#videoEvidence.concepts[114]",
        "resource-manifest.json#videoEvidence.concepts[115]",
        "resource-manifest.json#videoEvidence.concepts[116]",
        "resource-manifest.json#videoEvidence.concepts[117]",
        "resource-manifest.json#videoEvidence.concepts[118]",
        "resource-manifest.json#videoEvidence.concepts[119]",
        "resource-manifest.json#videoEvidence.concepts[120]",
        "resource-manifest.json#videoEvidence.concepts[121]",
        "resource-manifest.json#videoEvidence.concepts[122]",
        "resource-manifest.json#videoEvidence.concepts[123]",
        "resource-manifest.json#videoEvidence.concepts[124]",
        "resource-manifest.json#videoEvidence.concepts[125]",
        "resource-manifest.json#videoEvidence.concepts[126]",
        "resource-manifest.json#videoEvidence.concepts[127]",
        "resource-manifest.json#videoEvidence.concepts[128]",
        "resource-manifest.json#videoEvidence.concepts[129]",
        "resource-manifest.json#videoEvidence.concepts[130]",
        "resource-manifest.json#videoEvidence.concepts[131]",
        "resource-manifest.json#videoEvidence.concepts[132]",
        "resource-manifest.json#videoEvidence.concepts[133]",
        "resource-manifest.json#videoEvidence.concepts[134]",
        "resource-manifest.json#videoEvidence.concepts[135]",
        "resource-manifest.json#videoEvidence.concepts[136]",
        "resource-manifest.json#videoEvidence.concepts[137]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[35]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[36]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[37]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[38]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[39]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[40]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[41]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[42]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[43]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[44]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[45]",
        "resource-manifest.json#videoEvidence.exercises[11]",
        "resource-manifest.json#videoEvidence.timeline[526]",
        "resource-manifest.json#videoEvidence.timeline[528]",
        "resource-manifest.json#videoEvidence.timeline[529]",
        "resource-manifest.json#videoEvidence.timeline[530]",
        "resource-manifest.json#videoEvidence.timeline[531]",
        "resource-manifest.json#videoEvidence.timeline[533]",
        "resource-manifest.json#videoEvidence.timeline[534]",
        "resource-manifest.json#videoEvidence.timeline[535]",
        "resource-manifest.json#videoEvidence.timeline[536]",
        "resource-manifest.json#videoEvidence.timeline[541]",
        "resource-manifest.json#videoEvidence.timeline[542]",
        "resource-manifest.json#videoEvidence.timeline[543]",
        "resource-manifest.json#videoEvidence.timeline[544]",
        "resource-manifest.json#videoEvidence.timeline[545]",
        "resource-manifest.json#videoEvidence.timeline[547]",
        "resource-manifest.json#videoEvidence.timeline[548]",
        "resource-manifest.json#videoEvidence.timeline[549]",
        "resource-manifest.json#videoEvidence.timeline[550]",
        "resource-manifest.json#videoEvidence.timeline[551]",
        "resource-manifest.json#videoEvidence.timeline[552]",
        "resource-manifest.json#videoEvidence.timeline[553]",
        "resource-manifest.json#videoEvidence.timeline[554]",
        "resource-manifest.json#videoEvidence.timeline[556]",
        "resource-manifest.json#videoEvidence.timeline[557]",
        "resource-manifest.json#videoEvidence.timeline[558]",
        "resource-manifest.json#videoEvidence.timeline[559]",
        "resource-manifest.json#videoEvidence.timeline[560]",
        "resource-manifest.json#videoEvidence.timeline[562]",
        "resource-manifest.json#videoEvidence.timeline[563]",
        "resource-manifest.json#videoEvidence.timeline[564]",
        "resource-manifest.json#videoEvidence.timeline[565]",
        "resource-manifest.json#videoEvidence.timeline[566]",
        "resource-manifest.json#videoEvidence.timeline[567]",
        "resource-manifest.json#videoEvidence.timeline[568]",
        "resource-manifest.json#videoEvidence.timeline[569]",
        "resource-manifest.json#videoEvidence.timeline[570]",
        "resource-manifest.json#videoEvidence.timeline[573]",
        "resource-manifest.json#videoEvidence.timeline[574]",
        "resource-manifest.json#videoEvidence.timeline[575]",
        "resource-manifest.json#videoEvidence.timeline[577]",
        "resource-manifest.json#videoEvidence.timeline[578]",
        "resource-manifest.json#videoEvidence.timeline[580]",
        "resource-manifest.json#videoEvidence.timeline[584]",
        "resource-manifest.json#videoEvidence.timeline[585]",
        "resource-manifest.json#videoEvidence.timeline[586]",
        "resource-manifest.json#videoEvidence.timeline[587]",
        "resource-manifest.json#videoEvidence.timeline[588]",
        "resource-manifest.json#videoEvidence.timeline[589]",
        "resource-manifest.json#videoEvidence.timeline[590]",
        "resource-manifest.json#videoEvidence.timeline[591]",
        "resource-manifest.json#videoEvidence.timeline[592]",
        "resource-manifest.json#videoEvidence.timeline[593]",
        "resource-manifest.json#videoEvidence.timeline[594]",
        "resource-manifest.json#videoEvidence.timeline[596]",
        "resource-manifest.json#videoEvidence.timeline[597]",
        "resource-manifest.json#videoEvidence.timeline[601]",
        "resource-manifest.json#videoEvidence.timeline[602]",
        "resource-manifest.json#videoEvidence.timeline[603]",
        "resource-manifest.json#videoEvidence.timeline[604]",
        "resource-manifest.json#videoEvidence.timeline[605]",
        "resource-manifest.json#videoEvidence.timeline[606]",
        "resource-manifest.json#videoEvidence.timeline[607]",
        "resource-manifest.json#videoEvidence.timeline[608]",
        "resource-manifest.json#videoEvidence.timeline[610]",
        "resource-manifest.json#videoEvidence.timeline[611]",
        "resource-manifest.json#videoEvidence.timeline[612]",
        "resource-manifest.json#videoEvidence.timeline[613]",
        "resource-manifest.json#videoEvidence.timeline[614]",
        "resource-manifest.json#videoEvidence.timeline[615]",
        "resource-manifest.json#videoEvidence.timeline[617]",
        "resource-manifest.json#videoEvidence.timeline[618]",
        "resource-manifest.json#videoEvidence.timeline[619]",
        "resource-manifest.json#videoEvidence.timeline[620]",
        "resource-manifest.json#videoEvidence.timeline[622]",
        "resource-manifest.json#videoEvidence.timeline[623]",
        "resource-manifest.json#videoEvidence.timeline[624]",
        "resource-manifest.json#videoEvidence.timeline[625]",
        "resource-manifest.json#videoEvidence.timeline[626]",
        "resource-manifest.json#videoEvidence.timeline[627]",
        "resource-manifest.json#videoEvidence.timeline[628]",
        "resource-manifest.json#videoEvidence.timeline[629]",
        "resource-manifest.json#videoEvidence.timeline[630]",
        "resource-manifest.json#videoEvidence.timeline[631]",
        "resource-manifest.json#videoEvidence.timeline[632]",
        "resource-manifest.json#videoEvidence.timeline[633]",
        "resource-manifest.json#videoEvidence.timeline[634]",
        "resource-manifest.json#videoEvidence.timeline[635]",
        "resource-manifest.json#videoEvidence.timeline[637]",
        "resource-manifest.json#videoEvidence.timeline[639]",
        "resource-manifest.json#videoEvidence.timeline[640]",
        "resource-manifest.json#videoEvidence.timeline[642]",
        "resource-manifest.json#videoEvidence.timeline[643]",
        "resource-manifest.json#videoEvidence.timeline[644]",
        "resource-manifest.json#videoEvidence.timeline[645]",
        "resource-manifest.json#videoEvidence.timeline[647]",
        "resource-manifest.json#videoEvidence.timeline[648]",
        "resource-manifest.json#videoEvidence.timeline[649]",
        "resource-manifest.json#videoEvidence.timeline[650]",
        "resource-manifest.json#videoEvidence.timeline[652]",
        "resource-manifest.json#videoEvidence.timeline[655]",
        "resource-manifest.json#videoEvidence.timeline[657]",
        "resource-manifest.json#videoEvidence.uncertainties[33]",
        "resource-manifest.json#videoEvidence.uncertainties[34]",
        "resource-manifest.json#videoEvidence.uncertainties[35]",
        "resource-manifest.json#videoEvidence.uncertainties[36]",
        "resource-manifest.json#videoEvidence.uncertainties[38]",
        "resource-manifest.json#videoEvidence.uncertainties[39]",
        "resource-manifest.json#videoEvidence.uncertainties[40]",
        "resource-manifest.json#videoEvidence.uncertainties[41]",
        "resource-manifest.json#videoEvidence.demos[60]",
        "resource-manifest.json#videoEvidence.demos[61]",
        "resource-manifest.json#videoEvidence.demos[62]",
        "resource-manifest.json#videoEvidence.demos[63]",
        "resource-manifest.json#videoEvidence.demos[64]",
        "resource-manifest.json#videoEvidence.demos[65]",
        "resource-manifest.json#videoEvidence.demos[66]",
        "resource-manifest.json#videoEvidence.demos[67]",
        "resource-manifest.json#videoEvidence.demos[68]",
        "resource-manifest.json#videoEvidence.demos[69]",
        "resource-manifest.json#videoEvidence.demos[70]",
        "resource-manifest.json#videoEvidence.demos[71]",
        "resource-manifest.json#videoEvidence.demos[72]",
        "resource-manifest.json#videoEvidence.demos[73]",
        "resource-manifest.json#videoEvidence.demos[74]",
        "resource-manifest.json#videoEvidence.demos[75]",
        "resource-manifest.json#videoEvidence.demos[76]",
        "resource-manifest.json#videoEvidence.demos[77]"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 4465,
      "url": "/topics/factory-markdown-flows-discussion/",
      "markdownUrl": "/markdown/factory-markdown-flows-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "mdflow-markdown-flows",
          "text": "mdflow (Markdown Flows)",
          "level": 3
        },
        {
          "id": "agent-skills-evolution",
          "text": "Agent Skills Evolution",
          "level": 3
        },
        {
          "id": "context-management",
          "text": "Context Management",
          "level": 3
        },
        {
          "id": "markdown-flows",
          "text": "Markdown Flows",
          "level": 3
        },
        {
          "id": "context-injection",
          "text": "Context Injection",
          "level": 3
        },
        {
          "id": "preloaded-context",
          "text": "Preloaded Context",
          "level": 3
        },
        {
          "id": "goku-compiler-mappings",
          "text": "Goku Compiler Mappings",
          "level": 3
        },
        {
          "id": "model-context-protocol-tooling",
          "text": "Model Context Protocol Tooling",
          "level": 3
        },
        {
          "id": "1password-cli-authentication",
          "text": "1Password CLI Authentication",
          "level": 3
        },
        {
          "id": "gog-cli-gog",
          "text": "GOG CLI (gog)",
          "level": 3
        },
        {
          "id": "fast-mode-fast",
          "text": "Fast Mode (/fast)",
          "level": 3
        },
        {
          "id": "context-aware-automation-flows",
          "text": "Context-Aware Automation Flows",
          "level": 3
        },
        {
          "id": "system-prompt-overrides",
          "text": "System Prompt Overrides",
          "level": 3
        },
        {
          "id": "codex-markdown-extension-naming-convention",
          "text": "Codex Markdown Extension Naming Convention",
          "level": 3
        },
        {
          "id": "birdclaw",
          "text": "birdclaw",
          "level": 3
        },
        {
          "id": "markdown-context-injection-syntax",
          "text": "Markdown Context Injection Syntax",
          "level": 3
        },
        {
          "id": "dynamic-context-injection",
          "text": "Dynamic Context Injection",
          "level": 3
        },
        {
          "id": "single-turn-inference-optimization",
          "text": "Single-Turn Inference Optimization",
          "level": 3
        },
        {
          "id": "flow-agents",
          "text": "Flow Agents",
          "level": 3
        },
        {
          "id": "specialized-flow-agents",
          "text": "Specialized Flow Agents",
          "level": 3
        },
        {
          "id": "main-agent-routing",
          "text": "Main Agent Routing",
          "level": 3
        },
        {
          "id": "feature-bound-agents-repeatable-markdown-flows",
          "text": "Feature-Bound Agents / Repeatable Markdown Flows",
          "level": 3
        },
        {
          "id": "mdflow",
          "text": "MDFlow",
          "level": 3
        },
        {
          "id": "imps",
          "text": "Imps",
          "level": 3
        },
        {
          "id": "ai-provider-swapping",
          "text": "AI Provider Swapping",
          "level": 3
        },
        {
          "id": "api-based-pricing-workflows",
          "text": "API-Based Pricing Workflows",
          "level": 3
        },
        {
          "id": "workspace-flow-orchestration",
          "text": "Workspace Flow Orchestration",
          "level": 3
        },
        {
          "id": "fable-5",
          "text": "Fable 5",
          "level": 3
        },
        {
          "id": "codegraph",
          "text": "CodeGraph",
          "level": 3
        },
        {
          "id": "human-centric-vs-agent-centric-data-representation",
          "text": "Human-Centric vs. Agent-Centric Data representation",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "sounds-like-a-stripped-down-version-of-agent-skills-is-that-the-idea",
          "text": "Sounds like a stripped down version of agent skills, is that the idea?",
          "level": 3
        },
        {
          "id": "you-can-turn-on-fast-right",
          "text": "you can turn on fast right?",
          "level": 3
        },
        {
          "id": "is-fast-mode-stay-on",
          "text": "Is Fast Mode Stay on?",
          "level": 3
        },
        {
          "id": "is-flow-a-pi-with-a-custom-mdflow-preloaded-is-flow-a-shortcut-for-workflow-or-is-it-an-actual-tool",
          "text": "Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?",
          "level": 3
        },
        {
          "id": "is-flow-a-pi-with-a-custom-mdflow-preloaded-is-flow-a-shortcut-for-workflow-or-is-it-an-actual-tool-2",
          "text": "Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?",
          "level": 3
        },
        {
          "id": "is-this-similar-to-your-concept-of-imps",
          "text": "Is this similar to your concept of imps ?",
          "level": 3
        },
        {
          "id": "given-that-anthropic-requires-you-to-use-api-based-pricing-no-subscription-usage-with-pi-or-hermes-or-openclaw-or-where-do-you-still-keep-claude-code-in-your-workflow-or-do-you-just-pay-the-api-cost-to-use-their-models-in-your-pi-setup",
          "text": "Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?",
          "level": 3
        },
        {
          "id": "do-you-have-an-orchestrator-that-manages-all-the-flows-for-example-can-it-open-a-new-herdr-tab-with-the-auditor-flow-and-notify-me-when-it-s-done-this-would-require-access-to-the-herdr-control-md-and-the-auditor-md-files",
          "text": "Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.?",
          "level": 3
        },
        {
          "id": "given-that-anthropic-requires-you-to-use-api-based-pricing-no-subscription-usage-with-pi-or-hermes-or-openclaw-or-where-do-you-still-keep-claude-code-in-your-workflow-or-do-you-just-pay-the-api-cost-to-use-their-models-in-your-pi-setup-2",
          "text": "Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?",
          "level": 3
        },
        {
          "id": "do-you-have-any-strategies-or-use-any-tools-like-codegraph-https-colbymchenry-github-io-codegraph-to-reduce-token-usage",
          "text": "Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?",
          "level": 3
        },
        {
          "id": "do-you-have-any-strategies-or-use-any-tools-like-codegraph-https-colbymchenry-github-io-codegraph-to-reduce-token-usage-2",
          "text": "Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-the-exact-parameter-interface-behavior-design-expected-for-the-p-pr-workflow-tool",
          "text": "Unresolved: The exact parameter interface behavior design expected for the p-pr workflow tool.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-application-name-of-the-dark-themed-text-editor-hosting-the-markdown-file",
          "text": "Unresolved: The exact application name of the dark-themed text editor hosting the markdown file.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-structural-backend-mechanism-supporting-the-dev-prefix-router-mapping-rule",
          "text": "Unresolved: The exact structural backend mechanism supporting the 'dev' prefix router mapping rule.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-structural-shift-in-terminal-parsing-when-running-standard-markdown-vs-codex-files-inside-an-untrusted-workspace-framework",
          "text": "Unresolved: The exact structural shift in terminal parsing when running standard markdown vs codex files inside an untrusted workspace framework.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-protocol-or-connectivity-technique-birdclaw-sh-uses-to-communicate-with-local-setups",
          "text": "Unresolved: The exact protocol or connectivity technique birdclaw.sh uses to communicate with local setups.",
          "level": 3
        },
        {
          "id": "unresolved-exact-spelling-prefix-configuration-match-for-gpt-5-6-model-tag",
          "text": "Unresolved: Exact spelling prefix configuration match for gpt-5.6 model tag.",
          "level": 3
        },
        {
          "id": "unresolved-exact-script-payload-at-line-109-of-flows-clipboard-md",
          "text": "Unresolved: Exact script payload at line 109 of flows/clipboard.md",
          "level": 3
        },
        {
          "id": "unresolved-specific-visual-appearance-of-the-multi-pane-terminal-output-layouts",
          "text": "Unresolved: Specific visual appearance of the multi-pane terminal output layouts",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-52-55",
          "text": "Demonstration detail: 02:52:55",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-58-14",
          "text": "Demonstration detail: 02:58:14",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-59-17",
          "text": "Demonstration detail: 02:59:17",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-59-40",
          "text": "Demonstration detail: 02:59:40",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-01-02",
          "text": "Demonstration detail: 03:01:02",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-03-08",
          "text": "Demonstration detail: 03:03:08",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-05-44",
          "text": "Demonstration detail: 03:05:44",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-07-33",
          "text": "Demonstration detail: 03:07:33",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-08-45",
          "text": "Demonstration detail: 03:08:45",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-10-16",
          "text": "Demonstration detail: 03:10:16",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-13-54",
          "text": "Demonstration detail: 03:13:54",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-15-55",
          "text": "Demonstration detail: 03:15:55",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-19-08",
          "text": "Demonstration detail: 03:19:08",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-23-04",
          "text": "Demonstration detail: 03:23:04",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-29-29",
          "text": "Demonstration detail: 03:29:29",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-30-52",
          "text": "Demonstration detail: 03:30:52",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-33-36",
          "text": "Demonstration detail: 03:33:36",
          "level": 3
        },
        {
          "id": "demonstration-detail-03-37-24",
          "text": "Demonstration detail: 03:37:24",
          "level": 3
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### mdflow (Markdown Flows)\n\nThe architectural approach of bundling specific system prompts together with interactive execution tools inside Markdown files to establish reusable agent workflows.\n\n### Agent Skills Evolution\n\nThe historical transition of agent skills from dynamically-loaded individual agent actions to an over-installed community library of markdown files that excessively clutter agent context windows.\n\n### Context Management\n\nThe practice of isolating and injecting only the precise context, files, and prompts required for the active task to avoid cost and dilution of agent attention.\n\n### Markdown Flows\n\nA technique within the Codex environment where specific task context, system prompts, configuration variables, and operating boundaries are defined within a dedicated Markdown file's front matter and body. This preloads the LLM with all necessary local environment knowledge.\n\n### Context Injection\n\nPassing explicit guidelines, folder structures, and syntax rules directly to an LLM upfront so that it can operate effectively even with lower-tier or faster reasoning models without needing specialized tool APIs or complex pre-programmed agent skills.\n\n### Preloaded Context\n\nInjecting system prompts and relevant file pathways into an AI session beforehand so that it automatically adheres to existing project conventions.\n\n### Goku Compiler Mappings\n\nAn extensible clojure-based declarative utility to generate custom key mappings for Karabiner-Elements on macOS.\n\n### Model Context Protocol Tooling\n\nAn open standard interface allowing LLM frameworks to interface directly with local file contexts and environments, referenced via the failing node_repl client.\n\n### 1Password CLI Authentication\n\nIntegrating programmatic secrets protection with native OS prompts, ensuring sensitive workspace variables are never saved as cleartext.\n\n### GOG CLI (gog)\n\nA single Go-based command line tool designed to interact with Google Workspace APIs (Gmail, Calendar, Drive) perfectly suited for terminals and AI agents.\n\n### Fast Mode (/fast)\n\nAn agent environment flag that forces 1.5x speed inference at the cost of increased usage billing.\n\n### Context-Aware Automation Flows\n\nProgrammatically loading dynamic context (like API outputs or local file listings) into an agent session rather than spending conversational turns discovering it.\n\n### System Prompt Overrides\n\nFlags or config configurations that substitute baseline behavior files in LLM CLI developer agents.\n\n### Codex Markdown Extension Naming Convention\n\nThe file naming convention where .codex.md activates a framework layer to handle markdown contents as a programmatic instruction stack.\n\n### birdclaw\n\nAn open-source local-first command-line tool workspace ecosystem designed for Twitter interaction caching.\n\n### Markdown Context Injection Syntax\n\nUsing an exclamation point followed by backticks inside a flow file runs shell commands during a pre-processing step, preloading environment telemetry directly into the context sent to an AI assistant.\n\n### Dynamic Context Injection\n\nPre-loading ambient environment configurations, active layouts, and histories straight into markdown prompt blocks prior to agent execution.\n\n### Single-Turn Inference Optimization\n\nBundling complex execution guidelines and state data into one prompt turn to avoid the overhead, latency, and costs of iterative tool-calling iterations.\n\n### Flow Agents\n\nSpecialized automation configurations mapped to target file folders or trigger scripts that execute highly distinct localized development tasks.\n\n### Specialized Flow Agents\n\nIsolated sub-agents defined within standalone Markdown settings profiles mapping directly to specific domains like hotkeys or clipboards.\n\n### Main Agent Routing\n\nAn architecture layout where a general core coordinator delegates targeted tasks down to localized sub-agents using strict boundary declarations.\n\n### Feature-Bound Agents / Repeatable Markdown Flows\n\nSpecialized, restricted sub-agents configured through Markdown documentation files to carry out localized repository workflows efficiently with predetermined permissions and files.\n\n### MDFlow\n\nAn abstraction system developed by the presenter to encapsulate system prompts and configurations into a reusable file layout that can easily point to different platforms like Cursor or Copilot.\n\n### Imps\n\nA specific variation of sub-agents native to the Codec environment.\n\n### AI Provider Swapping\n\nDesigning developer tools and workflows so they can easily swap backend providers (e.g., Gemini, Claude, Codex, Copilot, Cursor) rather than being locked into a single ecosystem.\n\n### API-Based Pricing Workflows\n\nManaging tool usage (like Claude Code and Fable) under usage-based API billing rather than fixed subscriptions, which requires weighing token costs against the efficiency benefits.\n\n### Workspace Flow Orchestration\n\nUsing utilities like herdr to open multiple workspace panes automatically, map distinct automated scripts (clipboard, scout, screenshot flows), and keep watch on their tasks concurrently.\n\n### Fable 5\n\nA highly capable LLM characterized by minimal turn iterations and exceptional reasoning token efficiency.\n\n### CodeGraph\n\nA local tool that transforms software codebases into structured semantic graphs queried by AI coding agents via MCP.\n\n### Human-Centric vs. Agent-Centric Data representation\n\nHuman-centric formats emphasize spatial, graphical, or visual relationships (e.g., graphs, diagrams) to enhance cognitive clarity, while agent-centric formats prioritize extreme structural compression or dense layouts to optimize context length and token spend.\n\n## Questions and answer status\n\n### Sounds like a stripped down version of agent skills, is that the idea?\n\n**Status: answered.** John agrees conceptually and uses the question as a prompt to discuss how agent skills evolved away from their original definition toward a bloated model, contrasting them against his streamlined task-based context approach.\n\n### you can turn on fast right?\n\n**Status: answered.** John admits that he can turn it on, but typically doesn't justify the additional cost for casual individual tasks. He resolves to enable it for upcoming workshops.\n\n### Is Fast Mode Stay on?\n\n**Status: answered.** Yeah, it stays on across sessions.\n\n### Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?\n\n**Status: partial.** John details that Flow processes plain markdown containing structural prompt definitions, moving into a live directory code example to highlight how it routes inputs.\n\n### Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?\n\n**Status: answered.** John demonstrates that a flow runs markdown templates that dynamically evaluate and preload context onto files through an evaluation step prior to AI execution.\n\n### Is this similar to your concept of imps ?\n\n**Status: answered.** John answers that it is an abstracted version; 'imps' is tailored specifically for Codec, while MDFlow serves as a more general platform-agnostic alternative.\n\n### Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?\n\n**Status: unanswered.** The query regarding Anthropic subscription versus API-based billing was not explicitly addressed in this chunk.\n\n### Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.?\n\n**Status: answered.** John states he does not use an automated orchestrator by default yet, preferring to manually dictate agent instructions via herdr help, and then provides a live scripted demo opening multiple workspace panes.\n\n### Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?\n\n**Status: answered.** John answers that he pays the API cost to use Claude Code and Fable normally, noting that the benefits outweigh the friction. He also mentions symlinking skill and memory/agent/Claude files to keep setups synchronized.\n\n### Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?\n\n**Status: answered.** John notes that standard harnesses compress context automatically, but tool returns sometimes cause agent errors if altered too drastically. He notes that CodeGraph builds code structural maps rather than straightforward string token filtering.\n\n### Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?\n\n**Status: partial.** John indicates that code graph maps usually optimize for human visuals rather than AI efficiency, and runs an experiment inside Claude Code to see how an agent would compress repository layout mappings autonomously.\n\n## Exercises\n\n- **Try:** Open an active markdown flow layout template file and add a system command step using the exclamation mark and backtick framework.\n  **Basis:** 03:15:06.090\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [02:52:15](https://proud-anchor-53zn.here.now/watch.html?t=10335#recording-player) — John notes that this is very similar to what Skills do in other projects, and explains his approach of bundling prompts with tools to make them reusable for any workflow.\n\n- [02:52:55](https://proud-anchor-53zn.here.now/watch.html?t=10375#recording-player) — John switches windows to the Ghostty terminal app, showing multiple workspace spaces on the left pane and executes p-pr 24 in the mdflow main s1 terminal tab.\n\n- [02:53:01](https://proud-anchor-53zn.here.now/watch.html?t=10381#recording-player) — An interactive prompt input modal box appears in Ghostty with the fields 'Name (optional conversation name)' and 'Prompt (24)'.\n\n- [02:53:03](https://proud-anchor-53zn.here.now/watch.html?t=10383#recording-player) — John observes that Claude opens its PR picker because he did not specify that he wanted to pass the PR number, or because the prompt builder does not support it.\n\n- [02:53:12](https://proud-anchor-53zn.here.now/watch.html?t=10392#recording-player) — John enters the text 'I want to pass the pr number' into the terminal area.\n\n- [02:53:23](https://proud-anchor-53zn.here.now/watch.html?t=10403#recording-player) — A window pane titled claude opens on the right side of the screen displaying 'Resume session... Search... mdflow... No conversations found in this project.'\n\n- [02:53:23](https://proud-anchor-53zn.here.now/watch.html?t=10403#recording-player) — John observes that there are no conversations.\n\n- [02:53:33](https://proud-anchor-53zn.here.now/watch.html?t=10413#recording-player) — John reviews code documentation text within Ghostty showing the path source ~/.config/zsh/conf.d/44-ai-claude-pr-dsl.zsh and explanations of Claude's breakdown of the p-pr command.\n\n- [02:53:36](https://proud-anchor-53zn.here.now/watch.html?t=10416#recording-player) — John concludes that the tool assumed from-pr should open a PR picker, which caused the error.\n\n- [02:53:58](https://proud-anchor-53zn.here.now/watch.html?t=10438#recording-player) — John discusses the original intention of skills being for agents to dynamically load them when needed.\n\n- [02:54:10](https://proud-anchor-53zn.here.now/watch.html?t=10450#recording-player) — John states that skills evolved into a community of developers sharing markdown files, which are completely different things.\n\n- [02:54:23](https://proud-anchor-53zn.here.now/watch.html?t=10463#recording-player) — John explains that skills were introduced because of context limits and costs, and analyzes what happens when those limitations are relaxed.\n\n- [02:55:10](https://proud-anchor-53zn.here.now/watch.html?t=10510#recording-player) — John notes that easy skill installation caused people to load too many skills, filling up context windows with unneeded capabilities.\n\n- [02:55:28](https://proud-anchor-53zn.here.now/watch.html?t=10528#recording-player) — John summarizes that managing context means having only the specific context required for the target task.\n\n- [02:55:47](https://proud-anchor-53zn.here.now/watch.html?t=10547#recording-player) — The shard begins with John Lindquist sharing his desktop view of the OpenAI Codex terminal application (v0.144.5), running the gpt-5.6-sol medium model in YOLO mode.\n\n- [02:55:49](https://proud-anchor-53zn.here.now/watch.html?t=10549#recording-player) — John types $karabin next to the menu prompt to showcase available skills, which displays options like Slack Notification Triage and Reply Drafting. He deletes it shortly after.\n\n- [02:56:03](https://proud-anchor-53zn.here.now/watch.html?t=10563#recording-player) — John types $scar into the prompt to mention a custom friction-tracking skill called 'learn from your scars', before clearing the input.\n\n- [02:56:36](https://proud-anchor-53zn.here.now/watch.html?t=10596#recording-player) — John types flow- into the menu prompt, triggering a dropdown list of automated workflows, and selects flow-karabiner.\n\n- [02:56:47](https://proud-anchor-53zn.here.now/watch.html?t=10607#recording-player) — Selecting the flow triggers a 'Hooks need review' security warning prompt and an alert regarding unsupported project-local configuration keys in ~/.codex/config.toml. John presses Escape to cancel and return to the main menu.\n\n- [02:57:02](https://proud-anchor-53zn.here.now/watch.html?t=10622#recording-player) — John types md into the prompt, opening a file list, and selects flow-karabiner.codex.md.\n\n- [02:57:14](https://proud-anchor-53zn.here.now/watch.html?t=10634#recording-player) — An ACTIONS overlay menu appears with options including 'Run flow', 'Preview dry-run', and 'Edit flow'. John selects 'Edit flow [LOCAL WRITE]'.\n\n- [02:57:20](https://proud-anchor-53zn.here.now/watch.html?t=10640#recording-player) — The screen switches to a text editor displaying flows/flow-karabiner.codex.md. John scrolls through the extensive markdown file, highlighting its front matter metadata, system prompt, mission details, tool boundaries, and specific keyboard layout guidelines.\n\n- [02:58:14](https://proud-anchor-53zn.here.now/watch.html?t=10694#recording-player) — John initiates flow-karabiner and inputs the query: list my herder shortcuts.\n\n- [02:58:24](https://proud-anchor-53zn.here.now/watch.html?t=10704#recording-player) — The prompt updates to 'Working (0s - esc to interrupt)'. Under the Explored section, the agent performs automated context gathering steps including reading Karabiner.edn, searching for herdr, and running sed commands on ~/.config/karabiner.edn.\n\n- [02:59:10](https://proud-anchor-53zn.here.now/watch.html?t=10750#recording-player) — The flow completes and outputs a markdown summary titled '### Herdr workspace shortcuts', detailing active Ghostty and workspace launcher layer key combinations.\n\n- [02:59:17](https://proud-anchor-53zn.here.now/watch.html?t=10757#recording-player) — John triggers flow-karabiner again to execute an update command.\n\n- [02:59:32](https://proud-anchor-53zn.here.now/watch.html?t=10772#recording-player) — John types the request: 'Please create a herdr shortcut ,+q to open ~/dev' into the Implement feature input box and executes it.\n\n- [02:59:42](https://proud-anchor-53zn.here.now/watch.html?t=10782#recording-player) — John notes that if this were a raw session, the model wouldn't understand what he was talking about without preloaded context.\n\n- [02:59:50](https://proud-anchor-53zn.here.now/watch.html?t=10790#recording-player) — Codex updates .config/karabiner.edn and completes the execution of goku successfully.\n\n- [03:00:29](https://proud-anchor-53zn.here.now/watch.html?t=10829#recording-player) — John executes the comma q shortcut, which switches the environment focus view to the dev directory workspace.\n\n- [03:01:02](https://proud-anchor-53zn.here.now/watch.html?t=10862#recording-player) — John opens the text command input and enters flow-zsh.\n\n- [03:01:03](https://proud-anchor-53zn.here.now/watch.html?t=10863#recording-player) — A prompt screen appears detailing that 7 hooks need review because they are new or changed.\n\n- [03:01:05](https://proud-anchor-53zn.here.now/watch.html?t=10865#recording-player) — Codex window initializes, showing an MCP client startup failure for node_repl.\n\n- [03:01:22](https://proud-anchor-53zn.here.now/watch.html?t=10882#recording-player) — John enters the text prompt: How would I create a prompt builder wrapper for claude code?\n\n- [03:01:42](https://proud-anchor-53zn.here.now/watch.html?t=10902#recording-player) — Codex begins looking through shell files, exploring 40-ai.zsh.\n\n- [03:01:54](https://proud-anchor-53zn.here.now/watch.html?t=10914#recording-player) — Codex continues by reading 44-ai-claude-pr-dsl.zsh.\n\n- [03:02:38](https://proud-anchor-53zn.here.now/watch.html?t=10958#recording-player) — Codex returns its detailed implementation plan, including a p-claude function snippet.\n\n- [03:03:08](https://proud-anchor-53zn.here.now/watch.html?t=10988#recording-player) — John clears the launcher bar input and types flow-workshop.\n\n- [03:03:12](https://proud-anchor-53zn.here.now/watch.html?t=10992#recording-player) — John selects the script file workshop-attendee-sync.1.claude.md from the file selection list.\n\n- [03:03:22](https://proud-anchor-53zn.here.now/watch.html?t=11002#recording-player) — John uses biometric authentication, and the workspace runs the markdown script after prompting for confirmation to trust the target folder.\n\n- [03:03:32](https://proud-anchor-53zn.here.now/watch.html?t=11012#recording-player) — John talks about ticket sales automation and Google Calendar integration.\n\n- [03:04:12](https://proud-anchor-53zn.here.now/watch.html?t=11052#recording-player) — John posts the link https://gogcli.sh/ in the chat.\n\n- [03:05:56](https://proud-anchor-53zn.here.now/watch.html?t=11156#recording-player) — John types /fast into the terminal interface to toggle fast inference speed.\n\n- [03:06:01](https://proud-anchor-53zn.here.now/watch.html?t=11161#recording-player) — John executes md --help to inspect flags.\n\n- [03:06:14](https://proud-anchor-53zn.here.now/watch.html?t=11174#recording-player) — John navigates into the notion-header directory context using dev notion-header.\n\n- [03:06:20](https://proud-anchor-53zn.here.now/watch.html?t=11180#recording-player) — John accepts the directory security trust prompt.\n\n- [03:06:41](https://proud-anchor-53zn.here.now/watch.html?t=11201#recording-player) — John inputs the prompt requesting a Notion flow to be built.\n\n- [03:06:49](https://proud-anchor-53zn.here.now/watch.html?t=11209#recording-player) — The workspace agent actively executes exploration tools including which, rg, find, and npm view.\n\n- [03:07:26](https://proud-anchor-53zn.here.now/watch.html?t=11246#recording-player) — John talks about setting up travel reimbursement automation flows.\n\n- [03:07:33](https://proud-anchor-53zn.here.now/watch.html?t=11253#recording-player) — John types and executes notion-header codex --help in the terminal panel.\n\n- [03:07:35](https://proud-anchor-53zn.here.now/watch.html?t=11255#recording-player) — The CLI prints help flags for the codex tool including system prompt override definitions.\n\n- [03:08:45](https://proud-anchor-53zn.here.now/watch.html?t=11325#recording-player) — John enters notion-header flow to see the list of codex files.\n\n- [03:09:06](https://proud-anchor-53zn.here.now/watch.html?t=11346#recording-player) — John selects flows/flow-bird.codex.md from an interactive file list.\n\n- [03:09:21](https://proud-anchor-53zn.here.now/watch.html?t=11361#recording-player) — The flow command errors out with exit code 1 due to untrusted directory status.\n\n- [03:09:32](https://proud-anchor-53zn.here.now/watch.html?t=11372#recording-player) — John sends the birdclaw.sh web address link into the text chat.\n\n- [03:10:31](https://proud-anchor-53zn.here.now/watch.html?t=11431#recording-player) — John names a fresh markdown asset hello-world.md and types text inside.\n\n- [03:10:45](https://proud-anchor-53zn.here.now/watch.html?t=11445#recording-player) — John executes notion-header md hello-world.md in terminal.\n\n- [03:10:50](https://proud-anchor-53zn.here.now/watch.html?t=11450#recording-player) — The terminal renders the raw markdown sentence back directly.\n\n- [03:11:15](https://proud-anchor-53zn.here.now/watch.html?t=11475#recording-player) — John renames the hello-world file to use the .codex.md extension format.\n\n- [03:11:23](https://proud-anchor-53zn.here.now/watch.html?t=11483#recording-player) — John Lindquist notices he hasn't trusted the directory yet.\n\n- [03:11:29](https://proud-anchor-53zn.here.now/watch.html?t=11489#recording-player) — The OpenAI Codex CLI v0.144.5 starts up but encounters a node_repl MCP startup failure.\n\n- [03:11:49](https://proud-anchor-53zn.here.now/watch.html?t=11509#recording-player) — Terminal shows error that the path is not inside a trusted directory and prompts for user interaction choices.\n\n- [03:12:17](https://proud-anchor-53zn.here.now/watch.html?t=11537#recording-player) — A tabular list of automated flow profiles is outputted to the terminal via autocomplete navigation.\n\n- [03:13:36](https://proud-anchor-53zn.here.now/watch.html?t=11616#recording-player) — The text content of herdr-control.md is viewed in the editor, showing the frontmatter and exclamation-backtick syntax commands.\n\n- [03:14:08](https://proud-anchor-53zn.here.now/watch.html?t=11648#recording-player) — John Lindquist inputs the prompt 'Open three new panes' into the interactive CLI workflow utility.\n\n- [03:14:20](https://proud-anchor-53zn.here.now/watch.html?t=11660#recording-player) — An Anthropic OAuth refresh failure appears on screen, prompting a dropdown selection of alternative models.\n\n- [03:14:35](https://proud-anchor-53zn.here.now/watch.html?t=11675#recording-player) — The terminal window displays live context information with compiled JSON objects detailing current workspace pane layouts.\n\n- [03:15:21](https://proud-anchor-53zn.here.now/watch.html?t=11721#recording-player) — The screen shows a text editor displaying the file herdr-control.md containing current pane inventory and recent origin-pane context queries.\n\n- [03:15:30](https://proud-anchor-53zn.here.now/watch.html?t=11730#recording-player) — John explains that when the system loads, it automatically reads all open panes and injects this context dynamically.\n\n- [03:16:42](https://proud-anchor-53zn.here.now/watch.html?t=11802#recording-player) — The Herdr agent automates workspace execution, showing sequential terminal splitting actions and rendering active shell panes on the right side of the UI layout.\n\n- [03:17:13](https://proud-anchor-53zn.here.now/watch.html?t=11833#recording-player) — John discusses the optimization benefits of a single-turn interaction model compared to multiple turns of back-and-forth server tool calls.\n\n- [03:18:15](https://proud-anchor-53zn.here.now/watch.html?t=11895#recording-player) — John acknowledges that he needs to debug an unexpected workspace check behavior related to Codex rendering in the split panes.\n\n- [03:18:46](https://proud-anchor-53zn.here.now/watch.html?t=11926#recording-player) — The video displays a browser window showing the landing page for Birdclaw (birdclaw.sh), a local-first Twitter workspace app.\n\n- [03:19:07](https://proud-anchor-53zn.here.now/watch.html?t=11947#recording-player) — John notes that agents can grow over time into specific agents that handle specific tasks.\n\n- [03:19:08](https://proud-anchor-53zn.here.now/watch.html?t=11948#recording-player) — The file flows/hotkeys.md is shown open in the editor highlighting frontmatter metadata settings.\n\n- [03:20:02](https://proud-anchor-53zn.here.now/watch.html?t=12002#recording-player) — John opens AGENTS.md to highlight the top-level routing philosophy prioritizing flows.\n\n- [03:20:52](https://proud-anchor-53zn.here.now/watch.html?t=12052#recording-player) — John opens flows/clipboard.md to demonstrate feature isolation rules for clipboard features.\n\n- [03:22:33](https://proud-anchor-53zn.here.now/watch.html?t=12153#recording-player) — John specifies that he updated these configurations to utilize version 5.6 models.\n\n- [03:23:04](https://proud-anchor-53zn.here.now/watch.html?t=12184#recording-player) — The text editor displays the initial parameters of flows/clipboard.md, showing model: \"gpt-3.6-sol\" and config: model_reasoning_effort=\"medium\".\n\n- [03:23:27](https://proud-anchor-53zn.here.now/watch.html?t=12207#recording-player) — Presenter scrolls through the file, showing the 'Tool-output trust boundary', 'Operating rule', and 'Command map' sections.\n\n- [03:23:44](https://proud-anchor-53zn.here.now/watch.html?t=12224#recording-player) — Presenter scrolls down to the 'Local lessons (advisory)' section containing custom automated self-improvement logs.\n\n- [03:24:14](https://proud-anchor-53zn.here.now/watch.html?t=12254#recording-player) — a participant asks: 'Is this similar to your concept of imps ?'\n\n- [03:24:36](https://proud-anchor-53zn.here.now/watch.html?t=12276#recording-player) — a participant submits a question regarding Anthropic API-based pricing and where Claude Code fits into the workflow.\n\n- [03:24:45](https://proud-anchor-53zn.here.now/watch.html?t=12285#recording-player) — Presenter scrolls through the lower sections containing SecretRejectionConfig and DEFAULT_BLOCKED_SOURCE_APPS.\n\n- [03:26:00](https://proud-anchor-53zn.here.now/watch.html?t=12360#recording-player) — John Lindquist addresses a participant's question, explaining that imps are Codec-specific whereas MDFlow is an abstracted architecture.\n\n- [03:26:57](https://proud-anchor-53zn.here.now/watch.html?t=12417#recording-player) — John Lindquist mentions evaluating support for tools like Devin and Grok.\n\n- [03:27:02](https://proud-anchor-53zn.here.now/watch.html?t=12422#recording-player) — John Lindquist notes Grok is recent and he needs to do a sweep of what popular tools need to be supported.\n\n- [03:27:11](https://proud-anchor-53zn.here.now/watch.html?t=12431#recording-player) — John Lindquist discusses Cursor, Copilot, Gemini (anti-gravity), Claude, and Codex supporting provider swapping.\n\n- [03:28:00](https://proud-anchor-53zn.here.now/watch.html?t=12480#recording-player) — John Lindquist mentions using Claude Code and Fable normally despite the API pricing friction.\n\n- [03:28:40](https://proud-anchor-53zn.here.now/watch.html?t=12520#recording-player) — John Lindquist describes symlinking skills, memory, agent, or Claude files to keep setups similar.\n\n- [03:29:10](https://proud-anchor-53zn.here.now/watch.html?t=12550#recording-player) — John Lindquist responds that he does not have a default orchestrator yet and dictates actions inside an agent with herder help.\n\n- [03:29:34](https://proud-anchor-53zn.here.now/watch.html?t=12574#recording-player) — John Lindquist demonstrates scripting the orchestration from Pi, setting up a herder help workspace configuration.\n\n- [03:29:54](https://proud-anchor-53zn.here.now/watch.html?t=12594#recording-player) — John Lindquist outlines the prompt requesting three panes in the workspace: clipboard flow, scout flow, and screenshot flow.\n\n- [03:30:14](https://proud-anchor-53zn.here.now/watch.html?t=12614#recording-player) — John Lindquist notes that you can tell it to watch all three flows to know how to launch them.\n\n- [03:30:52](https://proud-anchor-53zn.here.now/watch.html?t=12652#recording-player) — John Lindquist notices that the automated flows were opened in regular non-interactive mode instead of interactive mode.\n\n- [03:31:09](https://proud-anchor-53zn.here.now/watch.html?t=12669#recording-player) — The terminal display updates using the herdr tool to show workspace panel layout states for the active flows.\n\n- [03:31:13](https://proud-anchor-53zn.here.now/watch.html?t=12673#recording-player) — John Lindquist reflects on Fable 5's token efficiency and how it influences his orchestrator architecture assumptions.\n\n- [03:33:17](https://proud-anchor-53zn.here.now/watch.html?t=12797#recording-player) — a participant asks a question regarding CodeGraph and token usage reduction strategies.\n\n- [03:34:43](https://proud-anchor-53zn.here.now/watch.html?t=12883#recording-player) — John states he has used Mermaid diagrams in the past to pre-load layout structure but has not had a recent need to implement a dedicated code graph.\n\n- [03:37:29](https://proud-anchor-53zn.here.now/watch.html?t=13049#recording-player) — John inputs the command 'take dev/codegraph-exploration' to provision a target directory path.\n\n- [03:37:41](https://proud-anchor-53zn.here.now/watch.html?t=13061#recording-player) — John types and executes the compression prompt against the CodeGraph URL context.\n\n### Unresolved: The exact parameter interface behavior design expected for the p-pr workflow tool.\n\nThe system errored out or launched into picker modes unexpectedly during testing, causing the host to bypass deep diagnostics.\n\n**Discriminating evidence:** Can be confirmed by analyzing the code files defining the prompt-builder module or tracking downstream remediation shards.\n\n### Unresolved: The exact application name of the dark-themed text editor hosting the markdown file.\n\nThe file workspace headers are hidden; it resembles VS Code but cannot be confirmed with absolute certainty.\n\n**Discriminating evidence:** Verify via process explorer logs or repository environment setups if available.\n\n### Unresolved: The exact structural backend mechanism supporting the 'dev' prefix router mapping rule.\n\nThe system resolves it automatically without rendering standard shell expansions or symbolic paths.\n\n**Discriminating evidence:** Could be evaluated by checking shell configurations or custom tool aliases.\n\n### Unresolved: The exact structural shift in terminal parsing when running standard markdown vs codex files inside an untrusted workspace framework.\n\nThe snippet transitions right as the newly named file execution sequence begins.\n\n**Discriminating evidence:** Cross-reference next continuous segment block 06-06 data outputs.\n\n### Unresolved: The exact protocol or connectivity technique birdclaw.sh uses to communicate with local setups.\n\nThe browser interface is only visible briefly as a static document reference page.\n\n**Discriminating evidence:** Inspect the complete documentation for birdclaw.sh or review the corresponding repository code.\n\n### Unresolved: Exact spelling prefix configuration match for gpt-5.6 model tag.\n\nThe text character resolution displays specialized model notation suffixes that might denote isolated experimental deployments.\n\n**Discriminating evidence:** Cross-reference monorepo execution loaders to determine how the model string translates during orchestration.\n\n### Unresolved: Exact script payload at line 109 of flows/clipboard.md\n\nThe line contains a long single-quoted sed command string that wraps tightly across rows.\n\n**Discriminating evidence:** Can be verified directly inside the original markdown source file in the repository.\n\n### Unresolved: Specific visual appearance of the multi-pane terminal output layouts\n\nThe transcript describes the actions and terminal state text explicitly but precise cosmetic details require a full direct visual check.\n\n**Discriminating evidence:** Verify terminal theme, layout configuration, and text display styles visually.\n\n### Demonstration detail: 02:52:55\n\n- Switched to Ghostty terminal application window\n- Executed p-pr 24 command inside the terminal window\n- Interacted with prompt builder overlay input fields\n- Inspected code configuration markdown file text details\n\n**Tools observed:** Ghostty, Claude.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\np-pr 24\n```\n\n### Demonstration detail: 02:58:14\n\n- Initiated flow-karabiner from the Codex terminal menu prompt\n- Submitted the natural language request 'list my herder shortcuts'\n- Observed automated context analysis via reading configuration file paths and generating shortcut list markdown summaries\n\n**Tools observed:** OpenAI Codex CLI, Karabiner-Elements.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nlist my herder shortcuts\n```\n\n### Demonstration detail: 02:59:17\n\n- Re-triggered flow-karabiner\n- Typed update instructions: 'Please create a herdr shortcut ,+q to open ~/dev'\n\n**Tools observed:** OpenAI Codex CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nPlease create a herdr shortcut ,+q to open ~/dev\n```\n\n### Demonstration detail: 02:59:40\n\n- Creating a custom shortcut mapping dynamically via text prompt, compiling with goku, and testing the keyboard macro response.\n\n**Tools observed:** Codex CLI, Goku, Karabiner-Elements.\n\n### Demonstration detail: 03:01:02\n\n- Running a Zsh context exploration automation using flow-zsh to create custom prompt wrappers.\n\n**Tools observed:** Codex CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nflow-zsh\n```\n\n### Demonstration detail: 03:03:08\n\n- Running the workshop attendee tracking automation, confirming trust safety dialogs, and authenticating security credentials via 1Password.\n\n**Tools observed:** 1Password CLI, Stripe CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nflow-workshop\n```\n\n### Demonstration detail: 03:05:44\n\n- Enabled fast mode via /fast command macro\n- Inspected available options via md --help\n- Switched project context to dev notion-header\n- Accepted directory trust prompts\n- Submitted flow engineering prompt to agent\n\n**Tools observed:** mdflow, OpenAI Codex agent.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\n/fast\nmd --help\ndev notion-header\nwhich notion\nrg\nfind\nnpm view\n```\n\n### Demonstration detail: 03:07:33\n\n- Inspected CLI documentation flags for codex.\n\n**Tools observed:** codex.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nnotion-header codex --help\n```\n\n### Demonstration detail: 03:08:45\n\n- Initiated an interactive prompt workflow sequence and encountered a directory security block.\n\n**Tools observed:** notion-header.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nnotion-header flow\n```\n\n### Demonstration detail: 03:10:16\n\n- Built a markdown file asset to showcase standard vs codex template processing parameters.\n\n**Tools observed:** Cursor IDE.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nnotion-header md hello-world.md\n```\n\n### Demonstration detail: 03:13:54\n\n- Executed markdown script execution command.\n- Input explicit workflow target behavior goals.\n- Selected substitute inference provider endpoints following system auth failure warnings.\n\n**Tools observed:** Ghostty, mdflow, OpenAI Codex CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nmd herdr-control.md\n```\n\n### Demonstration detail: 03:15:55\n\n- Typed 'please continue' into the Herdr terminal interface prompt prompt line.\n- Observed automated terminal split commands running sequentially through jq selection criteria.\n- Monitored automated initialization of an OpenAI Codex window interface mapping to an unexpected layout destination.\n\n**Tools observed:** Herdr CLI, VS Code / Cursor IDE, jq.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr pane list | jq -c '.result.panes[] | select(.focused == true)'\nherdr pane split w2H:pC --direction right --cmd\n```\n\n### Demonstration detail: 03:19:08\n\n- Browsing structured agent declaration metrics in hotkeys.md\n- Inspecting top routing rules in AGENTS.md\n- Verifying feature isolation variables and reasoning constraints inside clipboard.md\n\n**Tools observed:** Cursor IDE.\n\n### Demonstration detail: 03:23:04\n\n- Inspected and navigated the content profile configuration rules within flows/clipboard.md in the text editor window.\n\n**Tools observed:** Cursor.\n\n### Demonstration detail: 03:29:29\n\n- Setting up a workspace orchestration flow with herdr help.\n- Prompting or configuring the creation of 3 separate panes.\n- Assigning specific workflows: clipboard flow, scout flow, and screenshot flow to the separate panes.\n- Setting the workspace to monitor or watch all three running flows simultaneously.\n\n**Tools observed:** herdr, Pi.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr help\n```\n\n### Demonstration detail: 03:30:52\n\n- Terminated active shell pane environments and refreshed layout structure flags.\n\n**Tools observed:** herdr, zsh.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr pane read w2p:p4 --source recent --lines 8 --format text\n```\n\n### Demonstration detail: 03:33:36\n\n- Navigated to the project landing page of CodeGraph to read integration guidelines.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 03:37:24\n\n- Created a directory named dev/codegraph-exploration via terminal prompt.\n- Launched an instance of Claude Code.\n- Submitted a query targeting repository optimization models to test context layout limits.\n\n**Tools observed:** Ghostty, Claude Code v2.1.212.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake dev/codegraph-exploration\nclx\n```"
    },
    {
      "id": "factory-markdown-flows-practice",
      "slug": "markdown-flows-practice",
      "title": "Markdown flows as a repeatable control surface — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.",
      "category": "Execution",
      "tags": [
        "prompts",
        "exercises",
        "markdown-flows"
      ],
      "sources": [
        {
          "label": "Markdown flows as a repeatable control surface",
          "url": "https://walnut-virtue-6d22.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://walnut-virtue-6d22.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "05-mdflow/index.html#Quick start",
        "05-mdflow/index.html#Prompt library",
        "05-mdflow/index.html#Set it up (agent guide)",
        "05-mdflow/index.html#Attachments — install these flows",
        "05-mdflow/index.html#Turn a repeated briefing into a flow",
        "05-mdflow/index.html#Audit a flow before you run it",
        "05-mdflow/index.html#Walk the evolve loop instead of hand-editing",
        "05-mdflow/index.html#Prefer skills? Every flow has a skill twin",
        "05-mdflow/agent.md"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 2143,
      "url": "/topics/factory-markdown-flows-practice/",
      "markdownUrl": "/markdown/factory-markdown-flows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "turn-a-repeated-briefing-into-a-flow",
          "text": "Turn a repeated briefing into a flow",
          "level": 3
        },
        {
          "id": "audit-a-flow-before-you-run-it",
          "text": "Audit a flow before you run it",
          "level": 3
        },
        {
          "id": "walk-the-evolve-loop-instead-of-hand-editing",
          "text": "Walk the evolve loop instead of hand-editing",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "attachments-install-these-flows",
          "text": "Attachments — install these flows",
          "level": 2
        },
        {
          "id": "prefer-skills-every-flow-has-a-skill-twin",
          "text": "Prefer skills? Every flow has a skill twin",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "mdflow-markdown-flows-as-an-agent-control-plane-agent-setup-guide",
          "text": "mdflow: markdown flows as an agent control plane — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "flow-attachments-raw-downloads",
          "text": "Flow attachments (raw downloads)",
          "level": 2
        },
        {
          "id": "skill-twins-if-the-user-prefers-agent-skills-over-flows",
          "text": "Skill twins (if the user prefers agent skills over flows)",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for markdown flows as a repeatable control surface.\n\n## Quick start\n\n``` text\nnpx mdflow init -y                   # starter roster + .mdflow.yaml, no engine calls\nmd                                   # Flow Workbench: one searchable launcher\nmd doctor --json                     # free, read-only project diagnosis\nmd explain flows/review.md           # resolved config + capabilities, nothing executed\nmd flows/review.md                   # run a flow (stage a change first)\nmd.claude \"quick one-off question\"   # ad-hoc, no file needed\n```\n\n## Prompt library\n\n### Turn a repeated briefing into a flow\n\n- Agent: Claude Code (or any coding agent)\n- Working directory: your project root, after `npx mdflow init -y`\n- Expected result: a new flow whose `md explain` lists every inline as a capability\n\n``` text\nI keep re-typing the same briefing at the start of agent sessions. Turn it into an mdflow flow. Create flows/standup.claude.md: frontmatter with a one-line description, then a body that preloads live state with !`command` inlines (git status --short --branch, git log --oneline -5, plus any command I name below), then a short instruction section telling the agent to work only from the preloaded context. Tell the agent the output was captured at prompt-build time so it must not re-run the commands. Then run `md explain flows/standup.claude.md` and confirm ISOLATION reads ON and every inline appears as a command capability. Briefing to encode: <describe your repeated briefing here>\n```\n\n### Audit a flow before you run it\n\n- Agent: any coding agent\n- Working directory: a repo containing `flows/`\n- Expected result: engine, isolation state, every prompt-build command, token estimate\n\n``` text\nAudit an mdflow flow before I run it. Run `md doctor --json` and `md explain <flow path>` (both are free and execute nothing). Report: which engine the flow resolves to and why (flag, env var, filename, frontmatter, config, or default); whether ISOLATION is ON; every command capability that will execute at prompt-build time; and the estimated token usage. Flag any capability that reaches the network or mutates files. Flow to audit: <path>\n```\n\n### Walk the evolve loop instead of hand-editing\n\n- Agent: any coding agent\n- Working directory: a repo where a flow just disappointed you\n- Expected result: an off-path proposal with an outcome word; the flow file untouched until apply\n\n``` text\nA flow just gave a bad result. Do NOT edit the flow file. Instead: 1) Record it with `md feedback <flow path> \"<what went wrong>\"` and show me the durable fb_ id. 2) Run `md eval <flow path> --plan` and `md evolve plan <flow path>` (both free) and summarize the evidence, verification plan, and cost. 3) Only if I say go: run `md evolve propose <flow path>`, then `md evolve show <run-id>`, and report the outcome word (verified_improvement, regression_safe, rejected, inconclusive, or capability_rejected) plus the prompt diff. Never run `md evolve apply` without my explicit approval. Flow: <path>. What went wrong: <describe>\n```\n\n## Set it up (agent guide)\n\n1.  From your project root, scaffold the roster. This writes `.mdflow.yaml` and five starter flows, each with a sibling eval suite, and invokes no engine:\n\n    ``` text\n    npx mdflow init -y\n    ```\n\n2.  Create the standup flow. This is the whole trick: the `` !`command` `` inlines run at prompt-build time, so the agent's first token arrives with git state, terminal panes, and tickets already in front of it.\n\n    ``` text\n    ---\n    description: pane-aware standup — agent starts already knowing git, panes, and tickets\n    model: sonnet\n    print: true\n    ---\n\n    You are a standup assistant. Everything below was captured at prompt-build\n    time, BEFORE you started — do not re-run these commands.\n\n    ## Repo state (git)\n\n    !`git status --short --branch`\n\n    !`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n    ## Terminal workspace (herdr panes)\n\n    !`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n    ## Open tickets (linear)\n\n    !`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n    ## Your job\n\n    From the preloaded context only:\n    1. Say what I'm in the middle of (branch, dirty files, visible panes).\n    2. Flag anything that looks stalled or contradictory.\n    3. Suggest the single next action, one sentence.\n    ```\n\n3.  Inspect it without executing anything, then run it:\n\n    ``` text\n    md explain flows/workshop-standup.claude.md   # expect ISOLATION: ON (default)\n    md flows/workshop-standup.claude.md           # prints your standup\n    ```\n\n**Success check:** the project parses cleanly with all six flows registered.\n\n``` text\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\n``` text\nflows: 6 structuralErrors: 0\n```\n\nFallback: if `structuralErrors` is non-zero, check whether the errors are `CONFIG_INVALID` from a pre-existing global `~/.mdflow/config.yaml` rather than from the flows — an invalid global config fails this check even when every flow is clean. Verify per-flow with `md explain flows/<name>.md` instead.\n\n## Attachments — install these flows\n\nBoth flows discussed on these pages are hosted on this site as raw markdown attachments. `md install` pulls a remote flow straight into your project's registry (npx-style; first use asks you to trust the domain). Reversible with `md remove <name>`; list what you have with `md list`.\n\nThe pane-aware standup flow (this section's money artifact):\n\n``` text\nmd install \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\"\n```\n\nThe captured this-or-that Elo voting loop (the flow from the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html)'s final beat):\n\n``` text\nmd install \"https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw\"\n```\n\nPrefer plain files in `flows/`? Fetch the raw attachments directly:\n\n``` text\nmkdir -p flows\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\" -o flows/workshop-standup.claude.md\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw\" -o flows/this-or-that.md\n```\n\nNote: `this-or-that.md` injects taste records via `@../…/RESULTS.md` includes that exist in the workshop repo — outside it, point those includes at your own vote records. Audit either flow for free with `md explain`.\n\n## Prefer skills? Every flow has a skill twin\n\nIf your stack runs on [agent skills](https://www.skills.sh/) rather than mdflow, every flow on these pages is also hosted here as a `SKILL.md` twin under `/skills/` — same job, no mdflow required. The trade is the section's own lesson in reverse: a flow preloads shell output at prompt-build time and runs isolated from ambient config; the skill twin has the agent run those commands itself inside your normal session. Six twins are hosted here — `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description`. Stage them anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill):\n\n``` text\nfor s in workshop-standup review changelog fix-tests onboard pr-description; do\n  mkdir -p skill-src/$s\n  curl -fsSL \"https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw\" -o skill-src/$s/SKILL.md\n  npx skills add ./skill-src --skill $s -y\ndone\n```\n\nTrim the list to just the names you want. The this-or-that loop's skill twin lives on [the This-or-That section site](https://gentle-lasso-9d5n.here.now/).\n\n## Complete reusable setup contract\n\n## mdflow: markdown flows as an agent control plane — agent setup guide\n\nFollowing this file sets up: mdflow in the current project — a starter flow roster plus one context-preloading \"standup\" flow that briefs the agent with `git status`, recent commits, terminal panes, and tickets before its first token.\n\nHuman companion pages (context for you, reading for your user): the [Session Replay](https://walnut-virtue-6d22.here.now/replay.html) — an annotated transcript of the session that built this exact setup — and the [Dialogue](https://walnut-virtue-6d22.here.now/dialogue.html) — skeptical Q&A about why flows work this way. This file remains the canonical machine copy: execute it top-to-bottom.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal and relative to `<project-root>`.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nnode --version\nnpx mdflow help | head -4\nclaude --version\n```\n\nExpected: Node 18+; the mdflow usage banner (`Usage: md <file.md> ...`); any Claude Code version string. If `npx mdflow` fails, stop and tell your user to check their network/npm setup. If `claude` is missing, see Notes for agents — the flow can run on another engine.\n\n## Steps\n\n1. From `<project-root>`, scaffold the roster. This writes `.mdflow.yaml` and five starter flows (each with a sibling `.eval.ts` suite) and invokes no engine:\n\n   ```bash\n   npx mdflow init -y\n   ```\n\n2. Create `flows/workshop-standup.claude.md` with exactly this content. The `` !`command` `` inlines run at prompt-build time — mdflow executes them and splices the output into the prompt before the agent starts:\n\n   ```markdown\n   ---\n   description: pane-aware standup — agent starts already knowing git, panes, and tickets\n   model: sonnet\n   print: true\n   ---\n\n   You are a standup assistant. Everything below was captured at prompt-build\n   time, BEFORE you started — do not re-run these commands.\n\n   ## Repo state (git)\n\n   !`git status --short --branch`\n\n   !`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n   ## Terminal workspace (herdr panes)\n\n   !`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n   ## Open tickets (linear)\n\n   !`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n   ## Your job\n\n   From the preloaded context only:\n   1. Say what I'm in the middle of (branch, dirty files, visible panes).\n   2. Flag anything that looks stalled or contradictory.\n   3. Suggest the single next action, one sentence.\n   ```\n\n3. Inspect the flow without executing anything. Confirm ISOLATION reads `ON (default)` and the FINAL PROMPT section shows all four inlined commands (there is no separate capability section in `md explain`; per-flow capability lists live in `md doctor --json`):\n\n   ```bash\n   md explain flows/workshop-standup.claude.md\n   ```\n\n4. Run the flow. It prints a standup summary built only from the preloaded context:\n\n   ```bash\n   md flows/workshop-standup.claude.md\n   ```\n\n## Success check\n\nRun:\n\n```bash\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\nExpected observable result: `flows: 6 structuralErrors: 0` — five starter flows plus the standup flow, all parsing cleanly. (`md doctor` is free and read-only.)\n\nFallback: if `structuralErrors` is non-zero, check the report's `diagnostics` before assuming the flows are broken — a pre-existing invalid global `~/.mdflow/config.yaml` surfaces here as a `CONFIG_INVALID` error even when every flow is clean. In that case verify per-flow with `md explain flows/<name>.md`: if each flow explains cleanly, the flows are fine and only the global config needs fixing.\n\nReport to your user: what you set up, the success-check output, and anything you had to adapt.\n\n## Flow attachments (raw downloads)\n\nBoth flows discussed on the site are hosted here as raw markdown attachments. Machine-fetch URLs (the `?raw` suffix is required — the bare `.md` URL serves an HTML viewer):\n\n- `https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw` — the pane-aware standup flow from Step 2 (identical content; fetching it is an alternative to writing the file by hand).\n- `https://walnut-virtue-6d22.here.now/flows/this-or-that.md?raw` — the captured this-or-that Elo voting loop flow. Its `@../…/RESULTS.md` includes reference the workshop repo's vote records; outside that repo, repoint them at your user's own records before running.\n\nInstead of writing Step 2's file manually you may run, from `<project-root>`:\n\n```bash\nmkdir -p flows\ncurl -fsSL \"https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md?raw\" -o flows/workshop-standup.claude.md\n```\n\n`md install \"<url>?raw\"` also works and registers the flow in the project registry instead of `flows/` (reversible with `md remove <name>`).\n\n## Skill twins (if the user prefers agent skills over flows)\n\nEvery flow discussed on the site also ships as a skills.sh-format `SKILL.md` twin hosted under `/skills/` — same job, no mdflow required. The difference: a flow preloads shell output at prompt-build time and runs isolated; the skill twin instructs the agent to run those commands itself in the normal session. Available names: `workshop-standup`, `review`, `changelog`, `fix-tests`, `onboard`, `pr-description` (the this-or-that twin is hosted at `https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md?raw`). Machine-fetch URL pattern (`?raw` required): `https://walnut-virtue-6d22.here.now/skills/<name>/SKILL.md?raw`.\n\nTo install for your user (stage anywhere EXCEPT a dir named `skills/` — the skills CLI claims that name and you'd install an empty skill):\n\n```bash\nfor s in workshop-standup review changelog fix-tests onboard pr-description; do\n  mkdir -p skill-src/$s\n  curl -fsSL \"https://walnut-virtue-6d22.here.now/skills/$s/SKILL.md?raw\" -o skill-src/$s/SKILL.md\n  npx skills add ./skill-src --skill $s -y\ndone\n```\n\nTrim the loop to the names the user wants. Only install skills when the user prefers them over flows — the flows remain the primary artifact of this section.\n\n## Notes for agents\n\n- If `md` is not on PATH, substitute `npx mdflow` for `md` in every command above (`md setup` configures PATH and aliases for the user's shell).\n- The flow degrades gracefully by design: the `herdr` and `linear` inlines are guarded with `2>/dev/null || echo \"...\"`, so machines without those tools get placeholder lines in the prompt instead of a failed run.\n- The `.claude.md` filename pins the claude engine. If the `claude` CLI is not installed, name the file `flows/workshop-standup.md` instead — it will use the project default engine from `.mdflow.yaml` (`pi`). Check `engines.installed` in `md doctor --json` to see what is available.\n- In a directory with no git repo, the git inlines print an error/placeholder line into the prompt. The flow still runs; the standup will just say so.\n- Eval verdicts in `md doctor --json` read `Unverified` until a full eval receipt is recorded. That is a missing receipt, not an error — `structuralErrors: 0` is the success signal here.\n- Re-running `npx mdflow init -y` leaves an existing roster untouched; it is safe in a project that already has `flows/`."
    },
    {
      "id": "factory-markdown-flows-questions",
      "slug": "markdown-flows-questions",
      "title": "Markdown flows as a repeatable control surface — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Execution",
      "tags": [
        "markdown-flows",
        "questions"
      ],
      "sources": [
        {
          "label": "Markdown flows as a repeatable control surface — questions and tradeoffs",
          "url": "https://walnut-virtue-6d22.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "05-mdflow/dialogue.html#The Q&A"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 940,
      "url": "/topics/factory-markdown-flows-questions/",
      "markdownUrl": "/markdown/factory-markdown-flows-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows-questions.json",
      "headings": [
        {
          "id": "the-q-a",
          "text": "The Q&A",
          "level": 2
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The Q&A\n\nIsn't a flow just a saved prompt?\n\nA saved prompt is frozen text. A flow executes while the prompt is being *built*: every `` !`command` `` inline runs at prompt-build time and its output is spliced in, so the agent's first token arrives already knowing your branch, your terminal panes, your tickets. Here is the one this section's demo actually runs — lift it:\n\n``` text\n---\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n---\n\nYou are a standup assistant. Everything below was captured at prompt-build\ntime, BEFORE you started — do not re-run these commands.\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n!`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n## Open tickets (linear)\n\n!`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n## Your job\n\nFrom the preloaded context only:\n1. Say what I'm in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n```\n\nAnd it's a file in your repo — versioned, diffable, reviewable like any other code. This flow is also a downloadable attachment — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows).\n\nWhy preload? My agent can run `git status` itself.\n\nIt can — for a tool-call round trip, and only if it decides to. Preloading makes the briefing deterministic: never skipped, never reordered, already in the prompt. The production version of this pattern runs a preload script that fetches workshop ticket buyers and current calendar attendees, prints the computed diff as markdown, and then tells the agent: fetched moments ago — do *not* re-fetch. One detail worth stealing: the script exits 0 even on failure and prints a `PRELOAD ERROR` section instead, so the error lands inside the prompt and the agent relays it and stops rather than dying silently.\n\nI've spent months on my CLAUDE.md, hooks, and MCP servers. A flow throws all that away?\n\nDeliberately — by default. A flow that summarizes a standup doesn't need your memory files, plugin lists, or MCP servers; hauling them in costs context and blurs focus. mdflow strips ambient config using each engine's own flags — claude gets `--safe-mode --no-session-persistence`, codex `--ignore-user-config --ephemeral`, gemini `--extensions none`, copilot `--no-custom-instructions`. Captured from this very project:\n\n``` text\nISOLATION\nON (default) — ambient engine context is disabled; host capabilities\nremain available\n   safe-mode: true\n   no-session-persistence: true\n   (opt out with _isolated: false)\n```\n\nAnything a flow genuinely needs, it declares in frontmatter; `_isolated: false` opts back into ambient. Straight caveat: this strips *context*, it is not a host sandbox — the inline commands and the engine still reach your filesystem, network, and credentials.\n\nWhat does a run cost me before I've even seen what it will do?\n\nNothing to look. The two audit commands are free and execute no engine, no inline, no hook:\n\n``` text\nmd explain flows/workshop-standup.claude.md   # engine + why, isolation, every inline, token estimate\nmd doctor --json                              # whole-project diagnosis, read-only\n```\n\n`md explain` on the standup flow reports which engine won and why (the `.claude.md` filename), every prompt-build command as a declared capability, and an estimated 174 tokens — 0.1% of the context window. If your command shows up in the capability list, the context will land.\n\nSixty flows later, how do I find anything?\n\nBare `md`. It opens the Flow Workbench: one searchable list of everything runnable, each entry labeled with its provenance — `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH`. My machine has roughly sixty-five `flow-*` commands on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh` — each a globally installed specialist that preloads its *entire* config domain plus a mission, trust boundary, and mutation policy on every single run. The installed `flow-zsh` file is printed complete on the [section guide](https://walnut-virtue-6d22.here.now/index.html) — study its anatomy, don't paste it.\n\nA flow gives a bad answer — I just edit the file, right?\n\nThat's how flows regress silently. Instead, record the failure and let the eval suite — not your memory — decide whether a fix is real:\n\n``` text\nmd feedback flows/review.md \"missed the renamed-file regression\"\nmd eval flows/review.md --plan     # free cost preview of the eval suite\nmd evolve plan flows/review.md     # free: evidence, verification, cost, writes\nmd evolve propose flows/review.md  # off-path proposal; source unchanged\nmd evolve show <run-id>            # decision, capability diff, prompt diff\nmd evolve apply <run-id>           # atomic, explicit, reversible\n```\n\nThe canonical file stays byte-identical until an explicit apply, and the outcome vocabulary is honest: `verified_improvement` means a feedback-linked case failed on the old prompt and passed on the new one; `regression_safe` means guardrails held but your reported problem wasn't proven fixed.\n\nDo you actually work this way, or is this a workshop demo?\n\nThis repo answers that itself. The Elo-voting process that chose the very format of this page was captured as a flow — `flows/this-or-that.md` at the workshop repo root, written from that session the day before the workshop. It encodes the whole round (frame the axis, scaffold the duel harness, generate distinct options, bank the taste rules) and re-injects the accumulated vote record fresh on every run via `@`-includes. Auditing it is free: `md explain flows/this-or-that.md`. In prior sessions the same week, a Stripe-to-calendar sync workflow became a flow the same way. Flows aren't the demo — they're how the demo got made."
    },
    {
      "id": "factory-markdown-flows-reference-patterns",
      "slug": "markdown-flows-reference-patterns",
      "title": "Markdown flows as a repeatable control surface — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Execution",
      "tags": [
        "markdown-flows",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://walnut-virtue-6d22.here.now/"
        }
      ],
      "sourceUnits": [
        "05-mdflow/folio/index.html#Abstract",
        "05-mdflow/folio/index.html#Notice what a blind agent session costs",
        "05-mdflow/folio/index.html#Preload context, then verify it landed",
        "05-mdflow/folio/index.html#Explain what a global specialist flow carries",
        "05-mdflow/folio/index.html#Choose one launcher for every flow",
        "05-mdflow/folio/index.html#Compare an ambient run with an isolated run",
        "05-mdflow/folio/index.html#Adjust a flow with feedback, not hand edits",
        "05-mdflow/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 2053,
      "url": "/topics/factory-markdown-flows-reference-patterns/",
      "markdownUrl": "/markdown/factory-markdown-flows-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-what-a-blind-agent-session-costs",
          "text": "Notice what a blind agent session costs",
          "level": 2
        },
        {
          "id": "preload-context-then-verify-it-landed",
          "text": "Preload context, then verify it landed",
          "level": 2
        },
        {
          "id": "explain-what-a-global-specialist-flow-carries",
          "text": "Explain what a global specialist flow carries",
          "level": 2
        },
        {
          "id": "choose-one-launcher-for-every-flow",
          "text": "Choose one launcher for every flow",
          "level": 2
        },
        {
          "id": "compare-an-ambient-run-with-an-isolated-run",
          "text": "Compare an ambient run with an isolated run",
          "level": 2
        },
        {
          "id": "adjust-a-flow-with-feedback-not-hand-edits",
          "text": "Adjust a flow with feedback, not hand edits",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nEvery fresh agent chat starts blind. You re-explain the repo, the tickets, and the terminal state, and you pay context for config the task never needed. mdflow makes each repeatable job a markdown file: shell output is inlined before the agent's first token, ambient config is stripped by default, and prompt changes go through evals and reviewable proposals. These notes trace each claim to a file or captured command in the demo project. They do not claim benchmark results, and the demo project's own eval verdicts are still unverified.\n\n## Notice what a blind agent session costs\n\nYou open an agent, and the first minutes go to briefing: what branch you are on, which panes are running, which ticket this serves. Next session, you type it all again. The easy mistake is to treat that briefing as free. It is not. It costs your time, and the agent's context window fills with your ambient setup before work starts.\n\nmdflow's answer is one markdown file per repeatable job — a \"flow\" — kept in the repo, runnable on any installed engine, and inspectable before it executes (S1). [1](https://walnut-virtue-6d22.here.now/#note-1)\n\n1\\. The engine is environment, not ceremony. Resolution order from S1: `--engine` flag, then `MDFLOW_ENGINE`, then the filename (`review.claude.md`), then frontmatter `engine:`, then project config, then the built-in default, pi. [↩](https://walnut-virtue-6d22.here.now/#note-ref-1)\n\nThe project README states the thesis directly: mdflow is \"a Git-native control plane for repeatable agent work\" — define the job as markdown, run it, inspect its inputs, and gate prompt revisions with behavioral evals (S1).\n\nThe contrast to hold on to: a chat session is a performance you repeat; a flow is a script you version. When you catch yourself typing the same briefing twice, that job wants to be a file. The rest of these notes show what the file buys you: preloaded context, isolation, and a change process with receipts.\n\n## Preload context, then verify it landed\n\nA flow can embed shell output in its prompt with a `` !`command` `` inline. mdflow runs the command at prompt-build time, so the agent's very first token arrives with the results already in front of it. The likely mistake is to instead tell the agent \"run git status first\" — now you pay a tool-call round trip, and the agent may skip or reorder it. Preloading removes that choice.\n\n``` text\n---\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n---\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot | head -40`\n\n## Open tickets (linear)\n\n!`(ticket CLI call — placeholder in the public demo)`\n\n## Your job\n\nFrom the preloaded context only:\n1. Say what I'm in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n```\n\n**Figure 1.** The demo project's `flows/workshop-standup.claude.md`, lightly condensed (S5). Source evidence, not a mock-up: `git status`, a terminal-pane snapshot, and a ticket lookup all run before the agent starts, so it \"knows about all the panes\" at token one.\n\nThe same pattern scales past one-liners. A production flow on this machine runs a preload script that fetches workshop ticket buyers from the payment provider and current calendar attendees, prints the computed diff as markdown, and then tells the agent: the data below was fetched moments ago — do not re-fetch (S6). [2](https://walnut-virtue-6d22.here.now/#note-2)\n\n2\\. A detail worth stealing from S6: the preload script exits 0 even on failure, printing a `PRELOAD ERROR` section instead. The error lands inside the prompt, so the agent can relay it and stop, rather than the flow dying silently. [↩](https://walnut-virtue-6d22.here.now/#note-ref-2)\n\nYour test loop: write the inline, then run `md explain flows/your-flow.md`. Explain resolves the full configuration and lists every inline as a declared capability — without executing anything. If the capability list shows your command, the context will land. In this project, `md doctor --json` reports the standup flow's capabilities as exactly the four inlined commands (S5). That is the feedback signal; if a command is missing, fix the backticks and re-check. The boundary: preloading captures state at launch. It does not keep updating — a long-running agent that needs fresh state must still fetch it.\n\n## Explain what a global specialist flow carries\n\nSome jobs recur across every project: keyboard config, shell config. On this machine, roughly sixty-five `flow-*` commands sit on PATH — `flow-git`, `flow-ffmpeg`, `flow-karabiner`, `flow-zsh`, and more — each a globally installed specialist flow (S4). You should be able to explain why these beat a generic assistant, because the reason is the whole design.\n\nThe specialist pattern declares a mission, an untrusted-evidence boundary, a narrow inspection command map, ownership rules, worked examples, mutation approval, and exact verification. Keep the operating instructions project-specific rather than copying another machine’s private configuration.\n\n**Figure 2.** Condensed frontmatter of the installed `flow-zsh` flow (S4). Derived display: excerpted and abridged from the real file; ellipses mark removed sections. The full file maps the entire modular zsh config — owner modules, lazy stubs, tests — into a command map the agent gets every single run.\n\nThe specialist's edge is not a smarter model — it is that the whole config domain is preloaded as navigable structure, plus a mission, a tool-output trust boundary, and a mutation policy that demands verification after every edit (S4). [3](https://walnut-virtue-6d22.here.now/#note-3)\n\n3\\. `flow-karabiner`'s mutation policy in S4: read the config, make the smallest edit, run the compiler (`goku`), then grep the generated JSON to prove the mapping exists. Edit, compile, verify — encoded in the prompt itself. [↩](https://walnut-virtue-6d22.here.now/#note-ref-3)\n\nThe weak move is a monolithic \"dotfiles assistant\" that knows a little about everything and answers from memory. The strong move is one flow per domain, each opening with \"never answer from memory\" and a first-step inspection command (S4). When you can explain that distinction — domain map in the prompt, evidence before answers, verification after edits — you can write your own specialist. The evidence stops here, though: these files show the design, not measured accuracy gains.\n\n## Choose one launcher for every flow\n\nSixty-five global flows plus project rosters create a discovery problem: which flows exist here, and which can you trust? Bare `md` answers it. It opens the Flow Workbench — one searchable list of project flows, global flows, registry installs, and runnable markdown found on PATH, each labeled with its provenance: `PROJECT`, `GLOBAL`, `INSTALLED`, or `PATH` (S1).\n\nSetting up a new project is one deterministic command. `npx mdflow init` creates a starter `flows/` roster and `.mdflow.yaml` with zero engine invocations, and repeat runs leave an existing roster untouched (S1). This demo project ran exactly that: twelve files, five starter flows, each with a sibling eval suite (S5).\n\n``` text\n# In any repo:\nnpx mdflow init -y      # starter roster + .mdflow.yaml, no engine calls\nmd                      # Flow Workbench: one searchable launcher\nmd doctor --json        # free, read-only project diagnosis\nmd explain flows/review.md   # resolved config, nothing executed\nmd.claude \"quick one-off question\"   # ad-hoc, no file needed\n```\n\n**Figure 3.** The adoption path, assembled from commands documented in S1/S7 and executed in this project (S5). Derived display: sequence chosen editorially; every command exists verbatim in `md --help`.\n\n**Engine default** The starter roster's flows default to the **pi** engine via `.mdflow.yaml`; the demo's standup flow pins claude through its filename instead (S5). If you demo with a different engine installed, the same files run — but do not present pi output and claude output as interchangeable.\n\nYour choice rule: reach for bare `md` when you want to find or run existing work; reach for `md create` or `init` when a briefing repeats and no flow exists yet. The signal that the setup worked is `md doctor --json` reporting your flows with zero structural errors — this project's captured run reports six flows, zero structural errors (S5).\n\n## Compare an ambient run with an isolated run\n\nYour interactive agent session hauls everything you have configured: memory files, hooks, MCP servers, skill lists, project instructions. A flow that reviews a diff needs none of it. The mistake is assuming that ambient baggage is harmless; it spends context on every run and can steer the agent off the declared task.\n\nmdflow strips ambient engine context by default, using each engine's own verified flags — claude runs with `--safe-mode --no-session-persistence`, codex with `--ignore-user-config --ephemeral` plus a zeroed project-doc budget, gemini with `--extensions none`, copilot with `--no-custom-instructions` (S1). [4](https://walnut-virtue-6d22.here.now/#note-4)\n\n4\\. Anything the flow genuinely needs — a skill, an MCP server, extra context — is declared explicitly in frontmatter, and `_isolated: false` opts back into ambient. Explicit beats implicit either way. [↩](https://walnut-virtue-6d22.here.now/#note-ref-4)\n\n``` text\n----------------------------------------------------------------------\nISOLATION\n----------------------------------------------------------------------\nON (default) — ambient engine context is disabled; host capabilities\nremain available\n   safe-mode: true\n   no-session-persistence: true\n   (opt out with _isolated: false)\n```\n\n**Figure 4.** Captured output of `md explain flows/workshop-standup.claude.md` in this project (S5). Source evidence: isolation is on without any frontmatter asking for it.\n\n**Isolation is not a sandbox** Context isolation strips prompts, hooks, and extensions — it does **not** confine the host. The flow's inline commands and the engine still reach your filesystem, network, environment, and credentials (S1). And engines with no isolation controls (droid, cursor-agent, agy) run ambient and warn rather than pretend (S1).\n\nRun the comparison yourself: `md explain` any flow and read the ISOLATION block, then run the same job in your normal interactive session and watch what extra material loads. The isolated run's prompt is exactly what the file declares — that is the point. Claims about token savings stop at \"ambient material is not loaded\"; the sources publish no percentage, so do not quote one.\n\n## Adjust a flow with feedback, not hand edits\n\nA flow that never changes goes stale; a flow edited by vibes regresses silently. The tempting shortcut is to tweak the prompt in place after a bad run and move on. mdflow's evolve loop replaces that with a proposal process that leaves the canonical file byte-identical until you explicitly apply a change (S2).\n\n``` text\nmd feedback flows/review.md \"missed the renamed-file regression\"\nmd eval flows/review.md --plan     # free cost preview of the eval suite\nmd evolve plan flows/review.md     # free: evidence, verification, cost, writes\nmd evolve propose flows/review.md  # off-path proposal; source unchanged\nmd evolve show <run-id>            # decision, capability diff, prompt diff\nmd evolve apply <run-id>           # atomic, explicit, reversible\n```\n\n**Figure 5.** The evolve loop, quoted from the evolve documentation's quick start (S2). Source evidence: feedback gets a durable `fb_…` ID; rejected attempts do not consume the underlying problem.\n\nThe outcome vocabulary is deliberately honest. `verified_improvement` means a feedback-linked case failed on the current prompt and passed on the proposal with clean guardrails; `regression_safe` means guardrails passed but the reported problem was not proven fixed; `rejected`, `inconclusive`, and `capability_rejected` cover the rest (S2).\n\n**Unverified in this demo** Every flow in this demo project currently reports the eval verdict **Unverified** — the suites exist, but no full eval receipt has been recorded yet (S5). Present the loop as the mechanism it is; do not imply this roster has already earned `verified_improvement` badges.\n\nYour adjustment habit: when a flow disappoints, file `md feedback` in the moment — it is free and durable — and let the eval suite, not your memory, decide whether a proposal actually fixed it. The observable signal is the outcome word on the proposal. If it says `regression_safe`, treat the fix as unproven and keep the feedback open.\n\n## Practical action\n\nIn the repo where you brief agents most often, run `npx mdflow init -y`, then `md doctor --json` to confirm the roster parses with zero structural errors. Take the one briefing you typed twice this week and make it a flow: put the explanation in the body and the state-gathering in `` !`command` `` inlines. Check your work with `md explain` — the ISOLATION block should read ON and the capability list should name every inline. When the flow first disappoints, do not hand-edit: file `md feedback`, then walk the evolve loop and read the outcome word before trusting the change. If your team should discover flows too, opt in explicitly with `md roster sync --agents`."
    },
    {
      "id": "factory-markdown-flows-worked-example",
      "slug": "markdown-flows-worked-example",
      "title": "Markdown flows as a repeatable control surface — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Execution",
      "tags": [
        "markdown-flows",
        "examples"
      ],
      "sources": [
        {
          "label": "Markdown flows as a repeatable control surface — worked example",
          "url": "https://walnut-virtue-6d22.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "05-mdflow/replay.html#The session"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 1042,
      "url": "/topics/factory-markdown-flows-worked-example/",
      "markdownUrl": "/markdown/factory-markdown-flows-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-markdown-flows-worked-example.json",
      "headings": [
        {
          "id": "the-session",
          "text": "The session",
          "level": 2
        }
      ],
      "markdown": "# Markdown flows as a repeatable control surface — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\nYou\n\nSet up mdflow in this project. No engine calls — just the scaffold.\n\nAgent\n\n``` text\nnpx mdflow init -y\n```\n\nTwelve files landed, zero engine invocations:\n\n``` text\n.mdflow.yaml                # engine: pi, evolve mode: suggest\nflows/README.md             # roster operator card\nflows/review.md             + review.eval.ts\nflows/changelog.md          + changelog.eval.ts\nflows/pr-description.md     + pr-description.eval.ts\nflows/onboard.md            + onboard.eval.ts\nflows/fix-tests.md          + fix-tests.eval.ts\n```\n\nFirst beat is always the scaffold. `init` is deterministic — it never overwrites an existing roster, never calls an engine, and every starter flow arrives with a sibling eval suite on day one.\n\nYou\n\nI open every session re-explaining the same three things: the branch, which panes are running, what ticket I'm on. Make that a flow — `flows/workshop-standup.claude.md`. Preload git status, the last five commits, a herdr pane snapshot, and a tickets line, then tell the agent to work only from what was preloaded.\n\nAgent\n\nWrote the flow. The whole trick is in lines like these — `` !`command` `` inlines that mdflow executes while *building* the prompt, splicing their output in before the agent exists:\n\n``` text\n## Repo state (git)\n\n!`git status --short --branch`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n```\n\nThe body opens by telling the agent the output was captured at prompt-build time, before it started, and must not be re-run. Complete file lands at the end of this replay.\n\nThe agent never spends a tool-call round trip on `git status` — and never skips or reorders it. Every inline is guarded (`2>/dev/null || echo \"…\"`), so a machine without herdr gets a placeholder line in the prompt instead of a failed run.\n\nYou\n\nBefore anything runs: prove exactly what this file will do.\n\nAgent\n\nRan `md explain flows/workshop-standup.claude.md` — it resolves the full configuration and executes nothing. Captured output from this project (middle sections elided):\n\n``` text\nCOMMAND\nResolved command: claude\nSource: Filename pattern (.claude.md)\n\nISOLATION\nON (default) — ambient engine context is disabled; host capabilities\nremain available\n   safe-mode: true\n   no-session-persistence: true\n   (opt out with _isolated: false)\n\nFINAL CLI ARGS\n--print --safe-mode --no-session-persistence --model sonnet\n\nTOKEN USAGE\nEstimated tokens: 174\nContext limit: 200,000\nUsage: 0.1%\n```\n\nTwo reveals in one audit. Engine: the `.claude.md` filename pinned claude — the full ladder is `--engine` flag → `MDFLOW_ENGINE` → filename → frontmatter → project config → default (pi). Isolation: ON without any frontmatter asking for it — no CLAUDE.md, hooks, or MCP leak in. (Context isolation, not a host sandbox — the inlines and the engine still reach your filesystem and network.)\n\nYou\n\nRun it.\n\nAgent\n\n``` text\nmd flows/workshop-standup.claude.md\n```\n\nThe standup printed with the agent already briefed: it named the branch and dirty files from the git inline, the visible panes from the herdr snapshot, and the ticket placeholder line — without making a single tool call. Everything rode in on the prompt.\n\nThe production version of this pattern goes further: a flow in `~/.mdflow/` runs a preload script that fetches workshop ticket buyers and calendar attendees, prints the computed diff as markdown, and tells the agent \"fetched moments ago — do NOT re-fetch.\" The script exits 0 even on failure, printing a PRELOAD ERROR section instead, so the error lands inside the prompt and the agent relays it and stops.\n\nYou\n\nProve the project is still healthy.\n\nAgent\n\n``` text\nmd doctor --json | node -e 'const d=JSON.parse(require(\"fs\").readFileSync(0,\"utf8\"));console.log(\"flows:\",d.summary.flows,\"structuralErrors:\",d.summary.structuralErrors)'\n```\n\n``` text\nflows: 6 structuralErrors: 0\n```\n\n`md doctor` is free and read-only. Its JSON also lists every flow's declared capabilities — the standup flow reports exactly its four inlined commands.\n\nEval verdicts in this project read `Unverified — no full eval receipt has been recorded`. That's a missing receipt, not an error; `structuralErrors: 0` is the success signal here.\n\nYou\n\nOne more. The voting process that chose this page format — capture it as a flow so we never re-litigate it.\n\nAgent\n\nDone in a prior session: `flows/this-or-that.md` now lives at the workshop repo root, captured from the very session that picked this two-page format. It encodes the whole Elo round — frame the axis, scaffold the lab, generate structurally distinct options, QA, hand over, bank the results — and injects the accumulated taste record fresh on every run:\n\n``` text\n---\ndescription: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules\n_inputs: [_question, _subject]\n_interactive: true\n---\n…\n## Accumulated taste record (injected fresh each run — read before generating options)\n\n@../authoring-lab/RESULTS.md\n\n@../07-variations/template-lab/RESULTS.md\n```\n\n`md explain flows/this-or-that.md` is free and read-only if you want to audit it yourself.\n\nFlows evolve, but never by vibes: when one disappoints, record `md feedback` (a durable `fb_…` ID), preview with `md eval --plan`, and let `md evolve plan → propose → apply` do the rest. The source file stays byte-identical until an explicit apply.\n\nAgent\n\nThe file this session produced, complete:\n\n``` text\n---\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n---\n\nYou are a standup assistant. Everything below was captured at prompt-build\ntime, BEFORE you started — do not re-run these commands.\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n!`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n## Open tickets (linear)\n\n!`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n## Your job\n\nFrom the preloaded context only:\n1. Say what I'm in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n```\n\nFile landed. Versioned, inspectable for free, isolated by default. Both this flow and `this-or-that.md` are downloadable attachments — the install block is on the [section guide](https://walnut-virtue-6d22.here.now/index.html#attachments-install-these-flows).\n\nTotal session: six prompts, one paid run. The pattern the transcript demonstrates — scaffold → preload → audit → run → verify → capture — repeats for every briefing you catch yourself typing twice."
    },
    {
      "id": "codex-imp-workflows-reference",
      "slug": "imp-workflows-reference",
      "title": "Narrow Imp agents and routing: practical reference",
      "summary": "Comprehensive Imp reference covering setup and verification, narrow-agent boundaries, command modes, router and compound routing, foreground/forked dash hooks, cmux inspection, fleet and warm-session management, runtime isolation, prompt templates, bounded…",
      "category": "Execution",
      "tags": [
        "imps",
        "routing",
        "isolation"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Commands First",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Dash-Prefix Imp Routing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Foreground vs Forked Imp Requests",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Hook Setup Files",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Inspect A Forked Imp Session",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Router And Compound Routing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Fleet Management",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Isolation Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Warm Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Prompt Design Pattern",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Tool Packet To Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Router Picks Wrong Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Prompt Is Too Broad",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Imp Answers Without Tool Evidence",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Warm Server Looks Stale",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Auth Missing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Compound Route Split Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Dash Prompt Treated As A Codex Option",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Fork Opens But Cannot Be Found Later",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Hook Blocks Unexpectedly",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Do Not Use Resume-Based Fork Helpers For Dash Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Evolution Suggestion Looks Unsafe",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Tool Packet Too Vague",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 3720,
      "url": "/topics/codex-imp-workflows-reference/",
      "markdownUrl": "/markdown/codex-imp-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-imp-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "commands-first",
          "text": "Commands First",
          "level": 2
        },
        {
          "id": "dash-prefix-imp-routing",
          "text": "Dash-Prefix Imp Routing",
          "level": 2
        },
        {
          "id": "foreground-vs-forked-imp-requests",
          "text": "Foreground vs Forked Imp Requests",
          "level": 2
        },
        {
          "id": "hook-setup-files",
          "text": "Hook Setup Files",
          "level": 2
        },
        {
          "id": "inspect-a-forked-imp-session",
          "text": "Inspect A Forked Imp Session",
          "level": 2
        },
        {
          "id": "router-and-compound-routing",
          "text": "Router And Compound Routing",
          "level": 2
        },
        {
          "id": "fleet-management",
          "text": "Fleet Management",
          "level": 2
        },
        {
          "id": "isolation-model",
          "text": "Isolation Model",
          "level": 2
        },
        {
          "id": "warm-mode",
          "text": "Warm Mode",
          "level": 2
        },
        {
          "id": "prompt-design-pattern",
          "text": "Prompt Design Pattern",
          "level": 2
        },
        {
          "id": "tool-packet-to-imp",
          "text": "Tool Packet To Imp",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "router-picks-wrong-imp",
          "text": "Router Picks Wrong Imp",
          "level": 3
        },
        {
          "id": "prompt-is-too-broad",
          "text": "Prompt Is Too Broad",
          "level": 3
        },
        {
          "id": "imp-answers-without-tool-evidence",
          "text": "Imp Answers Without Tool Evidence",
          "level": 3
        },
        {
          "id": "warm-server-looks-stale",
          "text": "Warm Server Looks Stale",
          "level": 3
        },
        {
          "id": "auth-missing",
          "text": "Auth Missing",
          "level": 3
        },
        {
          "id": "compound-route-split-wrong",
          "text": "Compound Route Split Wrong",
          "level": 3
        },
        {
          "id": "dash-prompt-treated-as-a-codex-option",
          "text": "Dash Prompt Treated As A Codex Option",
          "level": 3
        },
        {
          "id": "fork-opens-but-cannot-be-found-later",
          "text": "Fork Opens But Cannot Be Found Later",
          "level": 3
        },
        {
          "id": "hook-blocks-unexpectedly",
          "text": "Hook Blocks Unexpectedly",
          "level": 3
        },
        {
          "id": "do-not-use-resume-based-fork-helpers-for-dash-prompts",
          "text": "Do Not Use Resume-Based Fork Helpers For Dash Prompts",
          "level": 3
        },
        {
          "id": "evolution-suggestion-looks-unsafe",
          "text": "Evolution Suggestion Looks Unsafe",
          "level": 3
        },
        {
          "id": "tool-packet-too-vague",
          "text": "Tool Packet Too Vague",
          "level": 3
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Narrow Imp agents and routing: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the local Imp/codex-daemons workflow for narrow, tool-shaped agent work. Act as a setup and verification agent: inspect the local implementation, configure only the required files, prove each piece works, and do not run broad agent work until the setup checks pass.\n\n1. Locate the local Imp/codex-daemons checkout or install source. Before changing anything, inspect the setup-relevant files: `README.md`, `imp.ts`, `imps.ts`, `docs/PROMPT.md`, `docs/ISOLATION.md`, `lib/defaults.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`, `imps/imp-rg`, `imps/imp-git`, `imps/imp-github-examples`, `test/router.test.ts`, `test/parseargs.test.ts`, and `test/cli-smoke.test.ts`.\n\n2. Check current command availability and health:\n   - `command -v imp`\n   - `command -v imps`\n   - `imp -l`\n   - `imps list`\n   - `imps ps`\n   - `imps doctor`\n   - `imp --which \"find checkout disabled-state code paths\"`\n   Report missing commands, stale paths, failed health checks, or auth problems before proceeding.\n\n3. Install or repair the local `imp` and `imps` entrypoints only according to the project's own docs and package scripts. Preserve the one-file Imp command model: each `imp-<tool>` command should stay narrow, own one tool, run that tool before answering, and return command evidence. Do not turn an Imp into a general Codex agent.\n\n4. Verify isolated runtime behavior. Confirm each Imp uses a temporary or narrow `CODEX_HOME`, symlinks only the required `auth.json` for login, replaces broad base instructions with the Imp prompt, disables broad project-doc loading, disables memories, keeps MCP servers empty unless a specific Imp requires one, disables web search unless the Imp owns that behavior, disables broad app/plugin surfaces, and removes unused schemas or unrelated tools. Use `imps doctor` and implementation inspection as evidence.\n\n5. Respect privacy boundaries. Do not copy full private Codex config, secret helper files, provider API variables, cookies, tokens, private endpoints, full `env` output, or full machine-local startup files into reports or isolated homes. If auth is needed, use the project's isolated auth symlink pattern rather than copying secret-bearing config. Summarize sensitive findings without printing secret values.\n\n6. Verify direct Imp commands before hook work:\n   - `imp-rg \"find TODOs in src\"`\n   - `imp-rg --run \"find TODOs in src\"`\n   - `imp-rg -q \"find TODOs in src\"`\n   - `imp-rg --no-warm \"find TODOs in src\"`\n   - `imp-rg --serve` only if a foreground warm-server check is appropriate, then stop it\n   - `imp-rg --run --effort minimal \"find TODOs in src\"`\n   Confirm the output includes exact command evidence and file:line matches where applicable. If an Imp answers from memory or without tool evidence, stop and report it.\n\n7. Verify router and compound routing:\n   - `imp --which \"what changed in git since yesterday?\"`\n   - `imp --which \"find the TODOs in src; then commit everything\"`\n   - `imp --which \"find TODOs in src after that summarize git changes\"`\n   Confirm strong connectors such as `;`, `.`, `then`, `after that`, and `afterwards` split routes correctly. Confirm bare `and` is not treated as a strong splitter unless the current implementation explicitly says otherwise.\n\n8. Verify fleet management and warm mode:\n   - `imps list`\n   - `imps ps`\n   - `imps doctor`\n   - `imps stop imp-rg` if a test warm process exists\n   - `imps stop --all` only if safe for the current local session\n   - `imps evolve`\n   - `imps evolve imp-rg`\n   Treat evolution suggestions as review material only. Do not auto-apply changes that broaden an Imp into a general agent.\n\n9. Set up the `UserPromptSubmit` hook for dash-prefix Imp prompts only after the command and isolation checks pass. Review and adapt these examples before installing:\n   - `hooks/imp-user-prompt-submit.py.template` to `~/.codex/hooks/imp-user-prompt-submit.py`\n   - `hooks/hooks.json.example` merged into `~/.codex/hooks.json`\n   - `hooks/cmux-run-surface.example` to `~/.local/bin/cmux-run-surface`\n   Check existing files first. Review paths, Codex flags, cmux binary location, logging, and current-session lookup before enabling the hook.\n\n10. Verify foreground dash routing. A prompt like `-rg find TODOs in src` should resolve the Imp command, executable path, description, task text, and current cwd, then add route context while letting the main prompt continue. The main agent should use that route context and should not rediscover the Imp with `which`, `where`, `find`, or broad repo search.\n\n11. Verify forked dash routing. A prompt like `--rg find TODOs in src` should block the current prompt, open a forked Codex session in a new cmux pane, normalize the prompt to `-rg find TODOs in src`, and print inspectable cmux ids: workspace, pane, surface, and window. Unknown or ambiguous Imp names should block and ask for a clearer Imp name.\n\n12. Confirm the fork command uses direct Codex fork syntax with `--` before the dash-starting prompt, for example: `codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox fork <source-session> -- '-rg find TODOs in src'`. The `--` before the prompt is required so `-rg` is not parsed as a Codex option. Do not use resume-based helpers for dash-starting prompts.\n\n13. Verify fork inspection from the returned ids:\n   - `cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80`\n   - `cmux top --workspace workspace:<id> --processes --flat --format tsv`\n   - `cmux focus-pane --workspace workspace:<id> --pane pane:<id>`\n\n14. Verify marker-packet handoff with a bounded packet only. Prepare a packet with task, search terms, scope, and required command evidence. Route it with `imp --which`, then run the selected Imp with `--run`. Example: task `find checkout disabled-state code paths`, terms `acceptedTerms`, `selectedShipping`, `canSubmit`, scope `src` and `tests`, required evidence `file:line matches and exact rg commands`. The Imp should return exact commands and evidence only, not product recommendations, file edits, or architecture decisions.\n\n15. Do not run broad product reasoning, code edits, commits, fleet-wide stops, or long-running forked tasks unless the setup checks above pass and the user explicitly asks for that next step.\n\n16. Finish with a concise setup report: files inspected, files changed, commands installed or repaired, hook status, isolation/auth status, warm/fleet status, router and compound-routing results, direct command results, fork inspection result if tested, marker-packet result, privacy-sensitive items skipped, and remaining manual steps.\n```\n\n## Big Idea\n\nPhase: Delegation And Review - hand bounded, tool-shaped work to narrow agents before escalating expensive decisions to council review.\n\nAn Imp is a narrow tool agent that should run the tool before it talks.\n\n## Try This Now\n\nCheck the Imp roster: `imp -l`.\nRoute a narrow search before running it: `imp --which \"find checkout disabled-state code paths\"`.\nUse the foreground dash path when regular Codex should keep the conversation: `-rg find checkout disabled-state code paths`.\nUse the forked dash path when the bounded task should run in a new cmux pane: `--rg find checkout disabled-state code paths`.\nUse the chosen Imp only for command evidence; send broad product reasoning back to regular Codex.\n\nImps are single-purpose, isolated Codex agents for common command-line tools. They are not smaller general agents.\n\n```text\nregular Codex -> broad context, general agent\nImp           -> narrow context, one tool, faster loop\n```\n\nUse regular Codex when the task needs broad reasoning across files, product intent, design, or multiple systems.\n\nUse an Imp when the task is tool-shaped:\n\n- search this repo\n- inspect git state\n- summarize GitHub PRs\n- query JSON\n- trim a video\n- inspect package metadata\n- find examples on GitHub\n\nClosing workflow:\n\n```text\nBounded tool question\n-> choose the right Imp\n-> run the narrow tool\n-> preserve command evidence\n-> return clean results\n-> hand results back to the broader task\n```\n\n## Files To Inspect\n\nImp implementation references:\n\n```text\nREADME.md\nimp.ts\nimps.ts\ndocs/PROMPT.md\ndocs/ISOLATION.md\nlib/defaults.ts\nlib/isolated.ts\nlib/imp.ts\nlib/appserver.ts\nimps/imp-rg\nimps/imp-git\nimps/imp-github-examples\ntest/router.test.ts\ntest/parseargs.test.ts\ntest/cli-smoke.test.ts\n```\n\n## When To Reach For This\n\nUse an Imp when the request maps cleanly to one tool.\n\n| Use An Imp For | Example |\n| --- | --- |\n| repo search | `imp-rg \"find checkout disabled state\"` |\n| git state | `imp-git \"what changed since yesterday?\"` |\n| GitHub examples | `imp-github-examples \"find examples of DESIGN.md\"` |\n| JSON query | `imp-jq --run \"count users by plan\"` |\n| video/file command | `imp-ffmpeg \"trim first 10 seconds\"` |\n| package metadata | `imp-npm \"inspect package scripts\"` |\n\nUse regular Codex when:\n\n- the task spans several tools\n- code edits are likely\n- product intent matters\n- architecture tradeoffs matter\n- the request is still too vague\n- the next move is not tool-shaped yet\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nEvery small tool question needs a full Codex session with broad project context.\n```\n\nWhat the workflow gives you now:\n\n```text\nTool-shaped work can go to a narrow Imp that runs one tool, returns command\nevidence, and leaves broad reasoning to regular Codex.\n```\n\nWhat you used to expect:\n\n```text\nAn agent can infer the right tool and explain from memory.\n```\n\nWhat the workflow gives you now:\n\n```text\nAn Imp has one operating rule and command map. It runs the tool first and\nanswers from the output.\n```\n\n## Commands First\n\nStart with identity and health checks:\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\n```\n\nCheck routing without spending a model turn:\n\n```bash\nimp --which \"what changed in git since yesterday?\"\nimp --which \"find the TODOs in src; then commit everything\"\nimp --which \"find examples of DESIGN.md created in the past 2 months\"\n```\n\nExpected routing shape:\n\n```text\nimp-git\nimp-rg                  find the TODOs in src\nimp-git                 commit everything\nimp-github-examples\n```\n\nRun one Imp interactively:\n\n```bash\nimp-rg \"find TODOs in src\"\n```\n\nRun one Imp non-interactively:\n\n```bash\nimp-rg --run \"find TODOs in src\"\n```\n\nQuiet final-answer-only mode:\n\n```bash\nimp-rg -q \"find TODOs in src\"\n```\n\nOpt out of warm mode:\n\n```bash\nimp-rg --no-warm \"find TODOs in src\"\n```\n\nRun a warm server in the foreground:\n\n```bash\nimp-rg --serve\n```\n\nOverride reasoning effort for one prompt:\n\n```bash\nimp-rg --run --effort minimal \"find TODOs in src\"\n```\n\n## Dash-Prefix Imp Routing\n\nA common local setup adds a `UserPromptSubmit` hook for Imp prompts.\n\n| Prompt Shape | Meaning | What Happens |\n| --- | --- | --- |\n| `-<imp> <task>` | foreground Imp route | hook resolves the Imp, adds routing context, and lets the main prompt continue |\n| `--<imp> <task>` | forked Imp route | hook blocks the current prompt, opens a forked Codex session in cmux, and seeds it with `-<imp> <task>` |\n| unknown Imp | unsafe route | hook blocks and asks for a clearer Imp name or a new Imp |\n| ambiguous Imp | unsafe route | hook blocks and shows likely matches |\n\nThe hook should resolve the Imp command, executable path, description, task text, and current cwd before the main agent starts working.\n\nThat means the main agent should not waste a turn rediscovering the Imp with `which`, `where`, `find`, or broad repo search. It should use the hook-provided route.\n\n## Foreground vs Forked Imp Requests\n\nUse single dash when the main agent should stay responsible for the broader conversation.\n\n```text\n-rg find checkout disabled-state code paths\n```\n\nUse double dash when the Imp task should run separately and the current prompt should not continue.\n\n```text\n--rg find checkout disabled-state code paths\n```\n\n| Use | Pick | Why |\n| --- | --- | --- |\n| main agent needs repo or conversation context first | `-<imp>` | hook adds route context; main agent can gather context before invoking the Imp |\n| bounded tool task should run separately | `--<imp>` | hook opens a forked Codex session in a new cmux pane |\n| task may require product judgment | regular Codex | not tool-shaped enough yet |\n| Imp name is unclear | neither | clarify or run `imp --which` |\n\nDouble dash normalizes to a single-dash prompt inside the fork.\n\n```text\n--gmail draft a reply\n-> forked Codex prompt:\n-gmail draft a reply\n```\n\nDouble dash does not mean \"run the Imp harder.\" It means \"fork the current Codex conversation and seed the fork.\"\n\n## Hook Setup Files\n\nCommon local install targets:\n\n```text\n~/.codex/hooks/imp-user-prompt-submit.py\n~/.codex/hooks.json\n~/.local/bin/cmux-run-surface\n```\n\nWorkshop package examples live under:\n\n```text\nhooks/\n```\n\nTreat these as setup examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.\n\n| File | Install Target | Purpose |\n| --- | --- | --- |\n| `hooks/imp-user-prompt-submit.py.template` | `~/.codex/hooks/imp-user-prompt-submit.py` | parse dash-prefix prompts and route or fork Imps |\n| `hooks/hooks.json.example` | merge into `~/.codex/hooks.json` | register the `UserPromptSubmit` hook |\n| `hooks/cmux-run-surface.example` | `~/.local/bin/cmux-run-surface` | open a cmux pane and print an inspectable receipt |\n\n## Inspect A Forked Imp Session\n\nA successful fork should print cmux ids:\n\n```text\ncmux workspace: workspace:<id>\ncmux pane: pane:<id>\ncmux surface: surface:<id>\ncmux window: window:<id>\n```\n\nUse the printed ids:\n\n```bash\ncmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80\ncmux top --workspace workspace:<id> --processes --flat --format tsv\ncmux focus-pane --workspace workspace:<id> --pane pane:<id>\n```\n\n| Command | Use It To |\n| --- | --- |\n| `cmux read-screen ...` | inspect recent fork output |\n| `cmux top ...` | check running processes in the workspace |\n| `cmux focus-pane ...` | jump back to the forked pane |\n\nThe fork path should use direct Codex fork with `--` before the prompt:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n  --dangerously-bypass-approvals-and-sandbox \\\n  fork <source-session> -- '-gmail draft ...'\n```\n\nThe `--` before the prompt prevents `-gmail` from being parsed as Codex options.\n\n## Router And Compound Routing\n\nUse the router when you know the request but not the Imp.\n\n```bash\nimp \"what changed in git since yesterday?\"\nimp \"trim the first 10s off intro.mp4\"\nimp git \"what changed?\"\nimp --which \"list my PRs\"\n```\n\nCompound routing splits strong connectors:\n\n```bash\nimp --which \"find the TODOs in src; then commit everything\"\n```\n\nStrong splitters:\n\n```text\n;\n.\nthen\nafter that\nafterwards\n```\n\nBare `and` should not split by itself.\n\n## Fleet Management\n\nList Imps:\n\n```bash\nimps list\n```\n\nSee warm processes:\n\n```bash\nimps ps\n```\n\nStop one:\n\n```bash\nimps stop imp-rg\n```\n\nStop all:\n\n```bash\nimps stop --all\n```\n\nInspect health:\n\n```bash\nimps doctor\n```\n\nInspect evolution suggestions:\n\n```bash\nimps evolve\nimps evolve imp-rg\n```\n\nEvolution suggestions are review material. They are not magic self-modification.\n\n## Isolation Model\n\nEach Imp runs with a narrow isolated runtime.\n\nImportant boundaries:\n\n| Boundary | Meaning |\n| --- | --- |\n| temporary `CODEX_HOME` | isolated runtime folder |\n| symlinked `auth.json` | login works without copying full config |\n| replaced base instructions | Imp prompt owns the behavior |\n| explicit developer instructions | one tool, one operating rule |\n| project docs disabled | no broad repo instruction loading |\n| memories disabled | no broad personal memory context |\n| MCP servers empty | no unrelated tool surface |\n| web search disabled | unless the Imp specifically owns that behavior |\n| apps disabled | no broad app/plugin surface |\n| unused schemas disabled | fewer ways to drift |\n\nThe point is not restriction for its own sake. The point is a clean tool boundary.\n\n## Warm Mode\n\nWarm mode keeps a narrow app-server session ready for faster turns.\n\nConcepts:\n\n```text\nwarm app-server\nsocketPath\nsourceFingerprint\nthread/start\nturn/start\nCODEX_IMP_IDLE_MINUTES\n```\n\nUse warm mode when the same Imp will be called repeatedly.\n\nUse `--no-warm` when you want a fresh one-shot run:\n\n```bash\nimp-rg --no-warm \"find TODOs in src\"\n```\n\nIf warm behavior looks stale:\n\n```bash\nimps ps\nimps stop imp-rg\nimps doctor\n```\n\n## Prompt Design Pattern\n\nA strong Imp prompt has:\n\n```text\nOperating rule\nCommand map\nWorked examples\nError recovery\nOutput rules\n```\n\nTemplate:\n\n~~~markdown\n# imp-<tool>\n\n## Operating Rule\n\nRun `<tool>` via `exec_command` before any final answer. Do not answer from memory.\n\n## Command Map\n\n| User Intent | Exact Command |\n| --- | --- |\n| find text | `<tool> ...` |\n| list status | `<tool> ...` |\n| inspect help | `<tool> --help` |\n\n## Worked Examples\n\n### Example 1\n\nUser request:\n\n```text\nfind checkout disabled state\n```\n\nCommand:\n\n```bash\nrg -n \"disabled|canSubmit|isSubmitting\" src tests\n```\n\n## Error Recovery\n\n| Error Text | Next Command |\n| --- | --- |\n| command not found | inspect install / PATH |\n| no results | broaden terms once |\n| unknown flag | run help |\n\n## Output Rules\n\n- show exact command evidence\n- return file:line matches when available\n- do not invent results\n- say when the tool found nothing\n~~~\n\n## Tool Packet To Imp\n\nStart from a bounded tool packet:\n\n```markdown\n# Imp Tool Packet\n\n- task:\n  - find checkout disabled-state code paths\n- search terms:\n  - acceptedTerms\n  - selectedShipping\n  - checkout disabled\n- scope:\n  - src\n  - tests\n- required verification:\n  - return file:line matches\n  - return exact commands used\n```\n\nRoute it:\n\n```bash\nimp --which \"find code paths related to acceptedTerms, selectedShipping, and checkout disabled\"\n```\n\nRun the narrow tool:\n\n```bash\nimp-rg --run \"Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and the exact rg commands used.\"\n```\n\nGood Imp request:\n\n```text\nHere is a bounded tool packet.\n\nSearch for code paths related to checkout disabled state. Use these terms:\nacceptedTerms, selectedShipping, checkout disabled. Stay inside src and tests.\n\nReturn file:line matches and the exact rg commands used. Do not propose a fix.\n```\n\nBad Imp request:\n\n```text\nFix checkout.\n```\n\n## Ask The Agent This\n\nRoute a tool packet:\n\n```text\nUse Imps for the tool-shaped part of this task.\n\nGiven this bounded tool packet, first run `imp --which` to choose the narrow\nImp. The packet points at checkout disabled state and includes terms\n`acceptedTerms`, `selectedShipping`, and `canSubmit`. Use the chosen Imp to\nreturn command evidence only. Do not edit files.\n```\n\nSearch with `imp-rg`:\n\n```text\nUse `imp-rg`.\n\nFind every place checkout disabled state is computed. Search for `disabled`,\n`canSubmit`, `isSubmitting`, `acceptedTerms`, and `selectedShipping` under\n`src` and `tests`. Return file:line matches and the exact commands used.\n```\n\nInspect git state:\n\n```text\nUse `imp-git`.\n\nSummarize current dirty state and recent commits. Return commands and evidence.\nDo not stage, commit, or modify files.\n```\n\nDesign a new Imp:\n\n```text\nDesign an Imp for a project-specific deploy CLI.\n\nIt must use exactly one tool, run help/status before answering, include a\ncommand map, worked examples, error recovery, and output rules. Explain when\nthis should remain regular Codex instead.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| Imp roster visible | `imp -l` or `imps list` |\n| fleet healthy | `imps doctor` |\n| route checked | `imp --which \"...\"` |\n| direct Imp works | `imp-rg \"find TODOs in src\"` |\n| noninteractive works | `imp-rg --run \"find TODOs in src\"` |\n| quiet mode works | `imp-rg -q \"find TODOs in src\"` |\n| warm state known | `imps ps` |\n| warm server stopped | `imps stop imp-rg` or `imps stop --all` |\n| broad work rejected | task returns to regular Codex when not tool-shaped |\n| command evidence present | Imp output includes exact commands/results |\n| project safety net passes | `bun test` in the Imp project |\n| dash hook installed | `-rg find TODOs` adds Imp route context without blocking |\n| fork hook installed | `--rg find TODOs` blocks current prompt and opens a cmux fork |\n| Imp path resolved | hook context names `imp-<name>` and executable path |\n| no rediscovery needed | main agent does not run `which`, `where`, `find`, or broad search for the Imp |\n| cmux fork inspectable | block message includes workspace, pane, surface, window, and check commands |\n| dash prompt safe | fork uses `codex fork <session> -- '-imp ...'` |\n\n## If It Goes Wrong\n\n### Router Picks Wrong Imp\n\nCheck routing first:\n\n```bash\nimp --which \"your request\"\n```\n\nThen use an explicit route:\n\n```bash\nimp rg \"find TODOs in src\"\n```\n\n### Prompt Is Too Broad\n\nBad:\n\n```text\nfix checkout\n```\n\nBetter:\n\n```text\nUse rg to find checkout disabled-state code paths. Return file:line evidence only.\n```\n\nIf the task still needs product reasoning, send it back to regular Codex.\n\n### Imp Answers Without Tool Evidence\n\nStrengthen the operating rule:\n\n```text\nRun the tool before final answer. Include exact commands and outputs.\n```\n\nAdd worked examples.\n\n### Warm Server Looks Stale\n\nRun:\n\n```bash\nimps ps\nimps stop <imp>\nimps doctor\n```\n\n### Auth Missing\n\nRun:\n\n```bash\nimps doctor\n```\n\nLook for `auth.json` status.\n\n### Compound Route Split Wrong\n\nUse a strong connector:\n\n```bash\nimp --which \"find TODOs in src; then summarize git changes\"\n```\n\nAvoid relying on bare `and`.\n\n### Dash Prompt Treated As A Codex Option\n\nBad shape: any helper that creates a fork id and then resumes it with `-gmail draft ...`.\n\nThe dash-starting prompt can be parsed as command options.\n\nSafer fork shape:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n  --dangerously-bypass-approvals-and-sandbox \\\n  fork <source-session> -- '-gmail draft ...'\n```\n\nThe `--` matters.\n\n### Fork Opens But Cannot Be Found Later\n\nUse the cmux ids from the block message:\n\n```bash\ncmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80\ncmux top --workspace workspace:<id> --processes --flat --format tsv\ncmux focus-pane --workspace workspace:<id> --pane pane:<id>\n```\n\n### Hook Blocks Unexpectedly\n\nLikely causes:\n\n- unknown Imp name\n- ambiguous Imp name\n- missing `imp-` roster\n- missing cmux helper\n- no current Codex session id\n- cmux pane creation failed\n\nRecovery:\n\n```bash\nimp -l\nimp --which \"your task\"\nimps doctor\ncmux rpc workspace.current\ncommand -v cmux-run-surface\n```\n\n### Do Not Use Resume-Based Fork Helpers For Dash Prompts\n\nAvoid helper paths that create a fork id and then resume it with the dash-starting prompt.\n\nUse direct `codex fork <source-session> -- '-imp ...'` for the hook path.\n\n### Evolution Suggestion Looks Unsafe\n\nTreat it as review material:\n\n```bash\nimps evolve imp-rg\n```\n\nDismiss or edit manually. Do not accept broad behavior that makes the Imp a general agent.\n\n### Tool Packet Too Vague\n\nSharpen the packet before choosing an Imp:\n\n```text\ntask:\nsearch terms:\nscope:\nrequired command evidence:\n```\n\n## References And Resources\n\n- Codex Imps project: <https://github.com/johnlindquist/codex-imps>\n- Imp roster: `imp -l`, `imps list`\n- Router: `imp --which \"...\"`\n- Fleet health: `imps doctor`\n- Fleet processes: `imps ps`\n- Stop warm Imps: `imps stop <imp>`, `imps stop --all`\n- Evolution suggestions: `imps evolve`, `imps evolve <imp>`\n- Project safety net: `bun test`\n- Key implementation files: `imp.ts`, `imps.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`\n\n## Operational boundaries\n\n- Configuration isolation is not an operating-system security sandbox. A linked auth file still grants access to authentication material, and the illustrated fork launch explicitly bypasses approval and sandbox protections.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-imp-workflows-practice",
      "slug": "imp-workflows-practice",
      "title": "Narrow Imp agents and routing: practice drills",
      "summary": "Exercises covering Codex-versus-Imp selection, health checks, routing and execution modes, dash-prefix hooks, bounded marker packets, fleet management, evolution review, narrow Imp design, failure recovery, tests, and final handoff receipts.",
      "category": "Execution",
      "tags": [
        "imps",
        "routing",
        "isolation",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 1: Regular Codex Or Imp?",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 2: Check Health",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 3: Route Before Running",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 4: Run `imp-rg`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 4A: Single-Dash Hook Route",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 4B: Double-Dash Fork Route",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 4C: Unknown Or Ambiguous Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 5: Section 8 Marker Packet To Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 6: Fleet Management",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 7: Inspect Evolution Suggestions",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 8: Design A New Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 9: Failure Path Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 10: Verify The Imp Project Safety Net",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Exercise 11: Final Handoff",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/09-imps.md#Exercises: 09. Imps/Final Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 1542,
      "url": "/topics/codex-imp-workflows-practice/",
      "markdownUrl": "/markdown/codex-imp-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-imp-workflows-practice.json",
      "headings": [
        {
          "id": "exercise-1-regular-codex-or-imp",
          "text": "Exercise 1: Regular Codex Or Imp?",
          "level": 2
        },
        {
          "id": "exercise-2-check-health",
          "text": "Exercise 2: Check Health",
          "level": 2
        },
        {
          "id": "exercise-3-route-before-running",
          "text": "Exercise 3: Route Before Running",
          "level": 2
        },
        {
          "id": "exercise-4-run-imp-rg",
          "text": "Exercise 4: Run `imp-rg`",
          "level": 2
        },
        {
          "id": "exercise-4a-single-dash-hook-route",
          "text": "Exercise 4A: Single-Dash Hook Route",
          "level": 2
        },
        {
          "id": "exercise-4b-double-dash-fork-route",
          "text": "Exercise 4B: Double-Dash Fork Route",
          "level": 2
        },
        {
          "id": "exercise-4c-unknown-or-ambiguous-imp",
          "text": "Exercise 4C: Unknown Or Ambiguous Imp",
          "level": 2
        },
        {
          "id": "exercise-5-section-8-marker-packet-to-imp",
          "text": "Exercise 5: Section 8 Marker Packet To Imp",
          "level": 2
        },
        {
          "id": "exercise-6-fleet-management",
          "text": "Exercise 6: Fleet Management",
          "level": 2
        },
        {
          "id": "exercise-7-inspect-evolution-suggestions",
          "text": "Exercise 7: Inspect Evolution Suggestions",
          "level": 2
        },
        {
          "id": "exercise-8-design-a-new-imp",
          "text": "Exercise 8: Design A New Imp",
          "level": 2
        },
        {
          "id": "exercise-9-failure-path-drill",
          "text": "Exercise 9: Failure Path Drill",
          "level": 2
        },
        {
          "id": "exercise-10-verify-the-imp-project-safety-net",
          "text": "Exercise 10: Verify The Imp Project Safety Net",
          "level": 2
        },
        {
          "id": "exercise-11-final-handoff",
          "text": "Exercise 11: Final Handoff",
          "level": 2
        },
        {
          "id": "final-check",
          "text": "Final Check",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Narrow Imp agents and routing: practice drills\n\nThese exercises practice routing narrow tool-shaped work to Imps.\n\n## Exercise 1: Regular Codex Or Imp?\n\nChoose `regular Codex` or `Imp`.\n\n| Task | Choice | Why |\n| --- | --- | --- |\n| Find every place checkout disabled state is computed. | | |\n| Decide which checkout architecture to use. | | |\n| Summarize current git dirty state. | | |\n| Implement saved payment methods. | | |\n| Query JSON for users by plan. | | |\n| Trim a video file. | | |\n| Explain product risk of auth/session rotation. | | |\n| Find GitHub examples of a file pattern. | | |\n\n## Exercise 2: Check Health\n\nRun:\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\n```\n\nFill out:\n\n```markdown\n# Imp Health\n\n- roster visible? yes/no:\n- warm processes:\n- doctor status:\n- auth status:\n- command that failed:\n- next check:\n```\n\n## Exercise 3: Route Before Running\n\nRun:\n\n```bash\nimp --which \"what changed in git since yesterday?\"\nimp --which \"find the TODOs in src; then commit everything\"\nimp --which \"find examples of DESIGN.md created in the past 2 months\"\n```\n\nFill out:\n\n```markdown\n# Routing Notes\n\n- prompt:\n- chosen Imp:\n- compound route? yes/no:\n- split points:\n- would you run it? yes/no:\n- why:\n```\n\n## Exercise 4: Run `imp-rg`\n\nRun:\n\n```bash\nimp-rg --run \"find TODOs in src\"\n```\n\nQuiet mode:\n\n```bash\nimp-rg -q \"find TODOs in src\"\n```\n\nNo warm mode:\n\n```bash\nimp-rg --no-warm \"find TODOs in src\"\n```\n\nFill out:\n\n```markdown\n# imp-rg Notes\n\n- command:\n- files searched:\n- matches:\n- exact command evidence present? yes/no:\n- when to use `--run`:\n- when to use `-q`:\n- when to use `--no-warm`:\n```\n\n## Exercise 4A: Single-Dash Hook Route\n\nSubmit a foreground Imp prompt from Codex:\n\n```text\n-rg find TODOs in src\n```\n\nFill out:\n\n```markdown\n# Single-Dash Hook Notes\n\n- prompt:\n- resolved Imp:\n- executable path included? yes/no:\n- description included? yes/no:\n- task text preserved? yes/no:\n- cwd included? yes/no:\n- did the main prompt continue? yes/no:\n- did the main agent avoid rediscovering the Imp? yes/no:\n- command evidence returned:\n```\n\n## Exercise 4B: Double-Dash Fork Route\n\nSubmit a forked Imp prompt from Codex:\n\n```text\n--rg find TODOs in src\n```\n\nFill out:\n\n```markdown\n# Double-Dash Fork Notes\n\n- original prompt:\n- normalized fork prompt:\n- did current prompt block? yes/no:\n- workspace:\n- pane:\n- surface:\n- window:\n- read-screen command:\n- top command:\n- focus-pane command:\n- what output appeared in the fork:\n```\n\n## Exercise 4C: Unknown Or Ambiguous Imp\n\nTry an intentionally unclear route:\n\n```text\n-g find TODOs in src\n```\n\nFill out:\n\n```markdown\n# Ambiguous Route Notes\n\n- prompt:\n- blocked? yes/no:\n- suggested matches:\n- would you clarify, use `imp --which`, or create with `imp-create`?\n- corrected prompt:\n```\n\n## Exercise 5: Section 8 Marker Packet To Imp\n\nStart with a bounded marker packet.\n\n```markdown\n# Marker Packet\n\n- marker id:\n- marker label: Checkout button stayed disabled\n- marker note:\n- nearby evidence terms:\n  - acceptedTerms\n  - selectedShipping\n  - checkout disabled\n- privacy boundary:\n  - storage values exported? no\n  - request bodies exported? no\n  - response bodies exported? no\n```\n\nRoute:\n\n```bash\nimp --which \"find code paths related to acceptedTerms, selectedShipping, and checkout disabled\"\n```\n\nRun:\n\n```bash\nimp-rg --run \"Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used.\"\n```\n\nFill out:\n\n```markdown\n# Marker Packet Imp Run\n\n- marker id:\n- chosen Imp:\n- exact command:\n- file:line evidence:\n- what the Imp must not infer:\n- next regular Codex task:\n```\n\n## Exercise 6: Fleet Management\n\nRun:\n\n```bash\nimps ps\nimps stop imp-rg\nimps stop --all\nimps doctor\n```\n\nFill out:\n\n```markdown\n# Fleet Management\n\n- warm imps before:\n- stopped:\n- warm imps after:\n- doctor status:\n- when to stop a warm Imp:\n```\n\n## Exercise 7: Inspect Evolution Suggestions\n\nRun:\n\n```bash\nimps evolve\nimps evolve imp-rg\n```\n\nFill out:\n\n```markdown\n# Evolution Review\n\n- suggestion path:\n- suggested change:\n- safe? yes/no:\n- keeps one tool? yes/no:\n- keeps command evidence? yes/no:\n- accept, edit, or reject:\n- why:\n```\n\n## Exercise 8: Design A New Imp\n\nPick one CLI tool.\n\nExamples:\n\n```text\nsqlite3\nredis-cli\ninternal search tool\nproject-specific deploy CLI\n```\n\nFill out:\n\n```markdown\n# New Imp Design\n\n- name: imp-\n- tool:\n- sandbox mode:\n- why this is single-purpose:\n- what this Imp must never do:\n- first safe command:\n- first verification command:\n\n## Operating Rule\n\nRun <tool> via exec_command before any final answer. Do not answer from memory.\n\n## Command Map\n\n| User Intent | Exact Command |\n| --- | --- |\n| status | |\n| list | |\n| inspect | |\n| help | |\n\n## Worked Examples\n\n### Example 1\n\n1.\n2.\n3.\n\n### Example 2\n\n1.\n2.\n3.\n\n## Error Recovery\n\n| Error Text | Next Command |\n| --- | --- |\n| command not found | |\n| unknown flag | |\n| no results | |\n\n## Output Rules\n\n-\n-\n-\n```\n\nAnswer:\n\n```markdown\n# Narrowness Review\n\n- does this use exactly one tool? yes/no:\n- does it need broad repo reasoning? yes/no:\n- should it be regular Codex instead? yes/no:\n- what to split out:\n```\n\n## Exercise 9: Failure Path Drill\n\nChoose a recovery for each failure.\n\n| Failure | Recovery |\n| --- | --- |\n| router picks the wrong Imp | |\n| prompt is too broad for an Imp | |\n| Imp answers without showing a command | |\n| warm server appears stale | |\n| auth.json missing | |\n| compound route split wrong | |\n| evolution suggestion looks unsafe | |\n| marker packet lacks nearby evidence terms | |\n| package Imp wants to mutate a pnpm project | |\n| ffmpeg Imp would overwrite input | |\n\nRecovery options:\n\n```text\nrun `imp --which`\nuse an explicit route\nsplit into smaller tool tasks\nsend broad reasoning back to regular Codex\nstrengthen Operating rule\nadd Worked examples\nrun `imps ps`\nrun `imps stop <imp>`\nrun `imps doctor`\nrewrite compound prompt with `;` or `then`\ndismiss unsafe evolution suggestions\nsharpen marker packet\ninspect lockfiles\nrequire new output file and no overwrite\nrun read-only checks only\n```\n\nFill out one in detail:\n\n```markdown\n# Failure Recovery Detail\n\n- failure:\n- likely cause:\n- first command:\n- recovery:\n- how to know it worked:\n```\n\n## Exercise 10: Verify The Imp Project Safety Net\n\nFrom the Imp project checkout, run:\n\n```bash\nbun test\n```\n\nFill out:\n\n```markdown\n# Test Check\n\n- command: `bun test`\n- pass count:\n- fail count:\n- test files:\n- router covered? yes/no:\n- parse args covered? yes/no:\n- CLI smoke covered? yes/no:\n- hot reload covered? yes/no:\n- evolution covered? yes/no:\n- would you edit routing without this passing? yes/no:\n- why:\n```\n\nOptional focused checks:\n\n```bash\nbun test test/router.test.ts\nbun test test/parseargs.test.ts\nbun test test/cli-smoke.test.ts\n```\n\nHook route checks:\n\n```text\n-rg find TODOs in src\n--rg find TODOs in src\n```\n\nFill out:\n\n```markdown\n# Dash Route Check\n\n- can explain `-<imp>`? yes/no:\n- can explain `--<imp>`? yes/no:\n- can inspect a forked cmux session? yes/no:\n- can explain why direct `codex fork ... -- '-imp ...'` is used? yes/no:\n```\n\n## Exercise 11: Final Handoff\n\nWrite a final handoff file:\n\n```bash\nmkdir -p receipts\ncat > receipts/section9-final-handoff.md <<'EOF'\n# Section 9 Final Imp Handoff\n\n- source: Section 8 marker packet\n- DebugSession path:\n- marker id:\n- marker label:\n- marker note:\n- expected:\n- actual:\n- nearbyEventIds:\n- evidence terms:\n  -\n  -\n  -\n- privacy boundary:\n  - storage values exported?\n  - request bodies exported?\n  - response bodies exported?\n- target Imp:\n- why this target is single-purpose:\n- command to run:\n- required output:\n- command evidence to preserve:\n- what the Imp must not invent:\n- next handoff after Imp result:\nEOF\n\ntest -s receipts/section9-final-handoff.md && echo \"handoff:OK\"\n```\n\nFill out:\n\n```markdown\n# Final Handoff Review\n\n- handoff file:\n- target Imp:\n- command:\n- route checked with `imp --which`? yes/no:\n- marker packet bounded? yes/no:\n- expected output clear? yes/no:\n- command evidence required? yes/no:\n- privacy boundary explicit? yes/no:\n- ready to run? yes/no:\n```\n\n## Final Check\n\nRun or review:\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\nimp --which \"find TODOs in src; then summarize git changes\"\nbun test\n```\n\nFill out:\n\n```markdown\n# Final Imps Check\n\n- can explain regular Codex vs Imp? yes/no:\n- can state the core sentence? yes/no:\n- can route before running? yes/no:\n- can explain compound routing? yes/no:\n- can run direct interactive mode? yes/no:\n- can run `--run`? yes/no:\n- can run `-q`? yes/no:\n- can explain warm mode? yes/no:\n- can stop warm imps? yes/no:\n- can explain isolation? yes/no:\n- can inspect evolution suggestions? yes/no:\n- can design a narrow Imp prompt? yes/no:\n- can hand a Section 8 marker packet to an Imp? yes/no:\n- can decide when to return to regular Codex? yes/no:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-overnight-cron-playbook",
      "slug": "overnight-cron-playbook",
      "title": "Overnight emulated-cron loop playbook",
      "summary": "Web developers often need long-running investigation without a real scheduler: flaky auth, broken localhost flows, intermittent console errors, or UI drift that only appears after repeated checks. This pattern gives an agent a bounded timestamp loop, runtime evidence, and a hard stop so overnight work produces receipts instead of vague claims.",
      "category": "Execution",
      "tags": [
        "context triad",
        "overnight",
        "goals",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#overnight-cron",
        "scenarios/overnight-cron.json#audienceFit",
        "toolkit/prompts/10-overnight-codex-cron-loop.md",
        "scenarios/overnight-cron.json#scenarios/0",
        "scenarios/overnight-cron.json#scenarios/1",
        "scenarios/overnight-cron.json#scenarios/2",
        "scenarios/overnight-cron.json#implementationNotes",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/0",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/2",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/3",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/4",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/5",
        "scenarios/overnight-cron.json#notTaughtOrAvoid/6",
        "scenarios/overnight-cron.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 2430,
      "url": "/topics/foundations-overnight-cron-playbook/",
      "markdownUrl": "/markdown/foundations-overnight-cron-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-overnight-cron-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "overnight-flaky-auth-flow-watchdog",
          "text": "Overnight flaky auth-flow watchdog",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "repeated-visual-regression-and-console-smoke-loop",
          "text": "Repeated visual-regression and console-smoke loop",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "overnight-dependency-upgrade-investigation-brief",
          "text": "Overnight dependency-upgrade investigation brief",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "existing-overnight-cron-prompt",
          "text": "Existing overnight cron prompt",
          "level": 3
        },
        {
          "id": "lesson-10-validated-references",
          "text": "Lesson 10 validated references",
          "level": 3
        },
        {
          "id": "lesson-10-validation-guardrails",
          "text": "Lesson 10 validation guardrails",
          "level": 3
        },
        {
          "id": "lesson-10-interactive-checklist",
          "text": "Lesson 10 interactive checklist",
          "level": 3
        },
        {
          "id": "packx-focused-bundle-flow",
          "text": "PackX focused bundle flow",
          "level": 3
        },
        {
          "id": "agent-browser-evidence-pattern",
          "text": "Agent Browser evidence pattern",
          "level": 3
        },
        {
          "id": "uploaded-scenario-bundle",
          "text": "Uploaded scenario bundle",
          "level": 3
        }
      ],
      "markdown": "# Overnight emulated-cron loop playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers often need long-running investigation without a real scheduler: flaky auth, broken localhost flows, intermittent console errors, or UI drift that only appears after repeated checks. This pattern gives an agent a bounded timestamp loop, runtime evidence, and a hard stop so overnight work produces receipts instead of vague claims.\n\n[Core principles](/topics/foundations-context-triad-and-overnight-work/)\n\n## Copy-paste workflow\n\n**When to use:** When Codex has no real scheduler but you want bounded overnight work (research/verification) while you sleep. This uses a natural-language time loop with a hard stop condition so credits and your repo stay safe.\n\n### Copy-paste prompt\n\n```text\nThis is a /goal-style overnight task. Codex has no real cron, so you will emulate one in natural language with a HARD stop condition baked into this goal. Stay read-only unless I explicitly ask for a mutation.\n\nGOAL: <RESEARCH/VERIFICATION OBJECTIVE>\n\nLOOP:\n1. Record a starting timestamp now.\n2. Every <N> minutes, run this routine: <THE RESEARCH/VERIFICATION ROUTINE>.\n3. STOP when the FIRST of these is hit (this bound is part of the goal, not optional):\n     - <DURATION, e.g. 6 hours> has elapsed since the starting timestamp, OR\n     - the clock reaches <TARGET TIME>, OR\n     - <ITERATION LIMIT> iterations completed, OR\n     - <BUDGET CAP> is reached.\n\nFor any debugging the loop does, bundle the context triad so you find the REAL mismatch:\n  - intent (this goal text)\n  - implementation (the source)\n  - output (logs / screenshots / traces)\nWhen those three disagree, that disagreement points at the actual bug.\n\nGuardrails: prefer read-only discovery before any mutation; keep the durable contract in this natural-language goal.\n```\n\n### How it works\n- The loop is an emulated cron written in natural language: record a starting timestamp, repeat a routine every N minutes, and stop at a fixed duration / target clock time / iteration limit / budget cap.\n- The stop condition is written INTO the goal — it's mandatory, not a suggestion — so overnight runs stay bounded and credits/repo stay safe.\n- For debugging, bundle the context triad — intent (goal text) + implementation (source) + output (logs/screenshots/traces); when those three disagree the model finds the real mismatch.\n- Prefer read-only discovery before any mutation; keep the durable contract in natural-language goals.\n- Reference: [PackX](https://www.npmjs.com/package/packx), [codex-daemons](https://github.com/johnlindquist/codex-daemons), [Agent Browser](https://www.npmjs.com/package/agent-browser).\n\n## Scenarios\n\n### Overnight flaky auth-flow watchdog\n\n**Role:** As a product web developer maintaining a Next.js app with login-gated dashboards\n\nA local Next.js dashboard sometimes loses authenticated state after refresh, route changes, or idle time. The team has a dev server, a test account, and a browser-capable agent, but no built-in Codex scheduler.\n\n> As a product web developer, I want an agent to re-check the login and dashboard flow every 10 minutes overnight, so that I wake up to concrete logs, screenshots, and a narrowed failure theory instead of a one-off reproduction attempt.\n\n#### Agent brief\n\n```text\nCreate `.goals/overnight-auth-watch.md` and run it as a bounded /goal-style task. Goal: record a starting timestamp, then every 10 minutes until 7:00 AM local time or 24 iterations, whichever comes first, verify the local auth flow against the running app. Stay read-only unless I explicitly approve a mutation. First inspect the project scripts and start or reuse the dev server. For each iteration, capture the context triad: intent from this goal file, implementation from the smallest relevant auth/session/routes files, and output from browser console logs, network or terminal errors, screenshots, and a short iteration summary. Write artifacts under `.notes/overnight-auth-watch/` using timestamped filenames such as `iteration-003.json`, `iteration-003-console.log`, and `iteration-003-screenshot.png`. At the end, write `.notes/overnight-auth-watch/final-report.md` with pass/fail counts, first failing iteration, suspected mismatch between intent/implementation/output, and the exact evidence files to inspect. Do not declare success without inspecting the written artifacts.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-overnight-cron-playbook/)\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n```text\n.goals/overnight-auth-watch.md\n```\n\n```text\n.notes/overnight-auth-watch/\n```\n\n```text\npackx --preview -s \"auth session dashboard runtime artifacts\"\n```\n\n```text\npackx -s \"auth session dashboard runtime artifacts\" -f markdown --no-interactive -o .notes/overnight-auth-watch/debug-bundle.md\n```\n\n#### Browser verification\n\nUse an agent-browser-style flow against localhost: take an accessibility snapshot of the login page, fill the test credentials, click submit, wait for the dashboard route, evaluate `document.title`, visible route markers, and any session/banner text, then refresh and navigate away/back. Capture console output and a screenshot per iteration. If using a CMUX browser pane, keep the browser pane visible while the terminal pane writes artifacts.\n\n#### Definition of done\n\n- A bounded goal file exists with starting timestamp, 10-minute interval, and hard stop at 7:00 AM or 24 iterations.\n- Each iteration writes a JSON/log/screenshot receipt under `.notes/overnight-auth-watch/`.\n- `final-report.md` compares expected auth behavior, relevant implementation files, and actual runtime output, with links or paths to the strongest evidence.\n- No source files are modified unless a separate human-approved implementation step is started.\n\n#### Failure modes and mitigations\n\n- The agent only reports that the flow worked without saving browser evidence; mitigate by requiring timestamped console logs, screenshots, and iteration JSON before any final answer.\n- The loop keeps running because the stop condition is written vaguely; mitigate by including both a target clock time and an iteration cap in the goal text.\n- The browser agent assumes existing cookies are available; mitigate by scripting the login path explicitly with a test account and treating cookies as non-portable.\n- The agent bundles the whole repo instead of the relevant auth implementation plus output artifacts; mitigate by running `packx --preview` first and keeping the bundle focused.\n\n### Repeated visual-regression and console-smoke loop\n\n**Role:** As a frontend engineer responsible for a marketing site or app shell\n\nA responsive landing page looks fine on the first pass, but layout drift, hydration warnings, or console errors appear after rebuilds, route changes, or viewport changes. The developer wants an overnight evidence loop, not a permanent test-suite expansion.\n\n> As a frontend engineer, I want an agent to periodically open the app in the browser, inspect key routes and viewports, and save proof artifacts, so that visual or console regressions are grounded in screenshots and logs.\n\n#### Agent brief\n\n```text\nCreate `.goals/overnight-ui-smoke.md`. Record the starting timestamp. Every 15 minutes, until 6 hours have elapsed or 20 iterations are complete, run a read-only UI smoke routine against the local web app. Inspect `package.json` for the dev and build commands. Start or reuse the dev server. Visit the agreed routes: `/`, `/pricing`, and `/dashboard` if present; if a route does not exist, record that instead of inventing one. For each route, capture console errors/warnings, one screenshot at desktop width, one screenshot at mobile width if the browser tool supports viewport changes, and a short artifact summary. Write files under `.notes/overnight-ui-smoke/`. If an error appears, bundle intent, implementation, and output with PackX: goal file, smallest route/component files, console logs, screenshots, and terminal output. End with `.notes/overnight-ui-smoke/final-report.md` listing stable routes, failing routes, first failure time, and the likely mismatch.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-overnight-cron-playbook/)\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n[Open reference](/topics/foundations-overnight-cron-playbook/)\n\n```text\n.goals/overnight-ui-smoke.md\n```\n\n```text\n.notes/overnight-ui-smoke/\n```\n\n```text\npackage.json\n```\n\n```text\npackx --preview -s \"ui smoke screenshots console logs routes components\"\n```\n\n```text\npackx -s \"ui smoke screenshots console logs routes components\" -f markdown --no-interactive -o .notes/overnight-ui-smoke/debug-bundle.md\n```\n\n#### Browser verification\n\nUse browser verification as the proof, not source inspection alone: open each localhost route, take an accessibility snapshot to confirm the main landmark/header/CTA exists, evaluate `window.location.pathname` and visible route text, collect console errors, and save screenshots. In CMUX, keep a browser pane beside the agent terminal or open a live Markdown tracker with the latest iteration summary.\n\n#### Definition of done\n\n- The loop is bounded by a 15-minute interval, 6-hour duration, and 20-iteration cap.\n- Every checked route has saved browser evidence, not just a textual claim.\n- Any failure has a focused context triad bundle: goal text, relevant route/component implementation, and runtime output.\n- The final report separates actual browser failures from missing routes or unsupported viewport operations.\n\n#### Failure modes and mitigations\n\n- The agent treats screenshots as optional and only reads source; mitigate by requiring browser artifacts as the primary receipt for this scenario.\n- The agent turns the smoke loop into broad redesign work; mitigate by stating read-only investigation only and deferring mutations to a separate Builder goal.\n- The agent over-tests unstable UI experiments as if they are permanent contracts; mitigate by framing this as disposable overnight evidence, not a maintained regression suite.\n- The bundle is too large to inspect usefully; mitigate by previewing PackX and including only goal, changed or relevant source, logs, screenshots, and traces.\n\n### Overnight dependency-upgrade investigation brief\n\n**Role:** As a tech lead preparing a risky dependency or framework upgrade\n\nA repo has a pending upgrade, failing tests, or intermittent build warnings. The lead wants a Researcher/Validator-style overnight investigation that collects evidence and proposes next steps, but does not mutate the repo while unattended.\n\n> As a tech lead, I want an agent to periodically run read-only checks and package the strongest evidence, so that the next morning I can decide whether to hand a focused implementation goal to a Builder agent.\n\n#### Agent brief\n\n```text\nCreate `.goals/overnight-upgrade-investigation.md`. This is a read-only overnight research and verification loop. Record the starting timestamp. Every 20 minutes until 4 hours have elapsed or 12 iterations are complete, inspect the current dependency-upgrade state. Run only read-only or normal verification commands discovered from the repo, such as package-manager install status checks, typecheck, lint, test, or build commands already present in scripts. Do not edit package files or source files. Save terminal output to `.notes/overnight-upgrade-investigation/iteration-###.log` and a structured summary to `iteration-###.json`. When failures appear, capture the context triad: the goal text, relevant package/config/source files, and actual command output. Use PackX only after previewing the candidate files. Finish with `final-report.md` containing a ranked list of blockers, commands run, evidence paths, and a recommended next goal file for implementation.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n[Open reference](/topics/foundations-overnight-cron-playbook/)\n\n```text\n.goals/overnight-upgrade-investigation.md\n```\n\n```text\n.notes/overnight-upgrade-investigation/\n```\n\n```text\npackage.json\n```\n\n```text\npnpm-lock.yaml, package-lock.json, yarn.lock, or bun.lockb if present\n```\n\n```text\npackx --preview -s \"dependency upgrade failing build test lint output\"\n```\n\n```text\npackx -s \"dependency upgrade failing build test lint output\" -f markdown --no-interactive -o .notes/overnight-upgrade-investigation/debug-bundle.md\n```\n\n#### Browser verification\n\nBrowser proof is only useful if the upgrade affects a running web surface. If the app starts successfully, open the local app once per iteration, capture console errors and a homepage screenshot, and save them beside the command logs. If the failure is purely install/typecheck/build-level, browser proof is not the right proof; use terminal logs and PackX bundles instead.\n\n#### Definition of done\n\n- The investigation uses a timestamped loop with a 20-minute interval, 4-hour duration, and 12-iteration cap.\n- All verification commands and outputs are saved under `.notes/overnight-upgrade-investigation/`.\n- The final report ranks blockers by evidence strength and points to exact log or bundle files.\n- The repo remains unmodified except for local `.notes/` and `.goals/` artifacts.\n\n#### Failure modes and mitigations\n\n- The agent starts fixing files during an unattended investigation; mitigate by repeating read-only discovery before mutation in the goal and requiring a separate implementation goal later.\n- The agent dumps full command help or the entire repo into context; mitigate by inspecting project scripts first and using PackX preview with a focused topic.\n- The agent reports a generic dependency recommendation without command evidence; mitigate by requiring saved logs and expected-versus-actual comparison.\n- The loop wastes credits rerunning the same failing command with no new information; mitigate by writing a per-iteration summary and stopping early if three consecutive iterations produce identical failure output.\n\n## Implementation notes\n\n- Keep the loop as a natural-language goal file, not a production scheduler. The point is bounded overnight agent work, not pretending Codex has cron.\n- Every scenario must include a hard stop: target clock time, elapsed duration, iteration cap, or budget cap. Use at least two bounds for unattended work.\n- For web app scenarios, runtime output means browser evidence: console logs, screenshots, route state, traces, or visible UI checks. Source code alone is not enough.\n- Prefer read-only discovery overnight. Save implementation for a separate morning Builder goal after a human reviews the evidence.\n- Write artifacts to local `.notes/` and goal files to `.goals/`; keep them out of committed source unless the repo intentionally tracks them.\n- Use specialized responsibilities without turning them into ceremony: Researcher/Validator overnight, Builder later if the evidence supports a change.\n- Stop early when repeated iterations produce identical evidence and no new signal; record that early stop in the final report.\n- Redact secrets from logs, screenshots, and browser captures before bundling or sharing.\n\n## Boundaries and caveats\n\n- Do not present the overnight loop as a real cron scheduler or production automation system.\n- Do not make warm daemon internals, CODEX_HOME isolation, app-server reuse, or low-level Codex SDK profile mechanics part of this playbook.\n- Do not require CMUX as a standalone taught workflow for this workflow; use browser panes or CMUX only where they help produce web-dev proof.\n- Do not introduce unrelated tools that were only mentioned, such as ScreenPipe-based workflow mining, NotebookLM, n8n, ADB, or Codex Mobile, as required implementation steps.\n- Do not tell the agent to keep improving indefinitely, rewrite the project overnight, deploy changes, or mutate destructive systems while unattended.\n- Do not trust the agent's self-reported success without written logs, screenshots, traces, command output, or bundled artifacts.\n\n## Agent reference map\n\n### Existing overnight cron prompt\n\nUse as the exact taught prompt shape: starting timestamp, repeated interval, hard stop, context triad, and read-only guardrail.\n\n[Open reference](/topics/foundations-overnight-cron-playbook/)\n\n### Lesson 10 validated references\n\nTreat as ground truth for what was actually taught: context triad, QA artifacts, short goal files, Oracle-generated goal files, specialized agents, overnight timestamp loops, and loose coupling.\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n### Lesson 10 validation guardrails\n\nUse to avoid reintroducing removed or over-specific claims such as warm daemon internals, profile isolation, or unrelated course redesign.\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n### Lesson 10 interactive checklist\n\nUse for implementation-ready receipts: intent.md, execution logs, screenshots, traces, PackX bundle, and fixed stop condition.\n\n[Open reference](/topics/foundations-context-triad-and-overnight-work/)\n\n### PackX focused bundle flow\n\nUse when a failure needs a model-readable bundle of intent, implementation, and runtime output; always preview before writing the bundle.\n\n```text\npackx --preview -s \"<topic>\" && packx -s \"<topic>\" -f markdown --no-interactive -o .notes/<scenario>/debug-bundle.md\n```\n\n### Agent Browser evidence pattern\n\nUse for web-app runtime proof: console logs, screenshots, and live browser state rather than source-only guessing.\n\n[Open reference](https://www.npmjs.com/package/agent-browser)\n\n### Uploaded scenario bundle\n\nUse as the local source snapshot for the scenario pipeline and lesson/toolkit context.\n\n```text\n/mnt/data/scenario-overnight-cron.txt\n```"
    },
    {
      "id": "factory-environment-policy",
      "slug": "environment-policy",
      "title": "Policy at the agent’s execution boundary",
      "summary": "Project-specific shells, session-scoped guidance, Codex airlocks, and Claude hooks—with their bypass limits.",
      "category": "Execution",
      "tags": [
        "environment",
        "factory"
      ],
      "sources": [
        {
          "label": "Policy at the agent’s execution boundary",
          "url": "https://polite-ravine-6v8g.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q1-environment-policy"
        }
      ],
      "sourceUnits": [
        "01-env/index.html#TL;DR",
        "01-env/index.html#Same trick in Claude Code and Codex",
        "01-env/index.html#Why the shell is the right place for policy",
        "01-env/index.html#Appendix",
        "01-env/index.html#Codex: load agent shells through a zsh airlock",
        "01-env/index.html#Claude Code: PreToolUse hooks are the stderr with teeth",
        "01-env/index.html#How the two files work",
        "01-env/index.html#Why session state needs PI_SESSION_ID",
        "01-env/index.html#Test the overrides before an agent depends on them",
        "learn.html#q1-environment-policy"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 3771,
      "url": "/topics/factory-environment-policy/",
      "markdownUrl": "/markdown/factory-environment-policy.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "same-trick-in-claude-code-and-codex",
          "text": "Same trick in Claude Code and Codex",
          "level": 2
        },
        {
          "id": "codex-load-agent-shells-through-a-zsh-airlock",
          "text": "Codex: load agent shells through a zsh airlock",
          "level": 3
        },
        {
          "id": "claude-code-pretooluse-hooks-are-the-stderr-with-teeth",
          "text": "Claude Code: PreToolUse hooks are the stderr with teeth",
          "level": 3
        },
        {
          "id": "why-the-shell-is-the-right-place-for-policy",
          "text": "Why the shell is the right place for policy",
          "level": 2
        },
        {
          "id": "how-the-two-files-work",
          "text": "How the two files work",
          "level": 2
        },
        {
          "id": "why-session-state-needs-pi-session-id",
          "text": "Why session state needs PI_SESSION_ID",
          "level": 2
        },
        {
          "id": "test-the-overrides-before-an-agent-depends-on-them",
          "text": "Test the overrides before an agent depends on them",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "put-policy-at-the-narrowest-boundary",
          "text": "Put policy at the narrowest boundary",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary\n\nProject-specific shells, session-scoped guidance, Codex airlocks, and Claude hooks—with their bypass limits.\n\n## Related working material\n\n- [Policy at the agent’s execution boundary — prompts and exercises](/topics/factory-environment-policy-practice/)\n- [Policy at the agent’s execution boundary — questions and tradeoffs](/topics/factory-environment-policy-questions/)\n- [Policy at the agent’s execution boundary — worked example](/topics/factory-environment-policy-worked-example/)\n\n## TL;DR\n\n- Two files in `.pi/` rewire every shell command your agent runs: `rm` quarantines instead of deleting, `git` refuses force pushes and hard resets, `linear` always self-assigns issues, and `ls` briefs the model once per conversation.\n- You walk away with both files, complete and copy-paste ready below, plus a four-line test that proves they work without Pi in the loop.\n- The one move: make every override explain itself on stderr. That message reaches the model at the exact moment it acts — a rule buried in CLAUDE.md forty thousand tokens ago doesn't.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://polite-ravine-6v8g.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## Same trick in Claude Code and Codex\n\nThe `.pi/` setup above is one instance of a portable idea: put your policy at the seam where the agent's actions pass through, and make its output land in the model's context at the moment it acts. All three agents give you a first-class version of that seam:\n\n| Agent | Where the override lives | How it's scoped | Session key | How the message reaches the model |\n|----|----|----|----|----|\n| Pi | `.pi/settings.json` → `shellCommandPrefix` sources `.pi/agent-shell.zsh` | Per project, once trusted | `PI_SESSION_ID` (extension) | Override's stderr, same turn as the action |\n| Codex | `.zshenv` guard sources your function files into opted-in agent shells | Per launch (`codex -c …`) or per machine (`config.toml`) | — | Shadowing function's stderr, same turn |\n| Claude Code | `PreToolUse` hooks + the `env` map in `settings.json` | Per project (`.claude/settings.json`) or global (`~/.claude/settings.json`) | `session_id` in every hook's stdin JSON | Hook decision + reason, delivered before the tool runs |\n\n### Codex: load agent shells through a zsh airlock\n\nThe failure-mode demo takes ten seconds: ask plain `codex` to run one of your zsh helper functions and it comes back not found; ask the `x` wrapper from the [custom zsh functions section](https://sacred-ritual-w7as.here.now/) and the same function resolves. In this setup, plain Codex does not automatically receive your zsh helper/function surface — and the wrapper doesn't fix that by sourcing zsh files. **It starts Codex with one environment variable, and your zsh config decides what that variable means:**\n\n``` text\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n```\n\nCodex's `shell_environment_policy` is the real, documented piece here — it injects env vars into the shells Codex spawns. `CODEX_LOAD_ZSH_DSL` is not a Codex built-in: it's a local marker this setup invented, and zsh startup rules — not Codex — decide which files load when they see it. Prefer the wrapper-local `-c` flag, which keeps the opt-in explicit and reversible per launch. Reach for global config only if every Codex launch on the machine should load the helper surface (it's also the place for per-machine values your functions need; the real config carries a key-helper path here, generalized below):\n\n``` text\n# Append to ~/.codex/config.toml to make the opt-in permanent for every\n# launch — no wrapper function needed.\n[shell_environment_policy]\ninherit = \"all\"\n\n[shell_environment_policy.set]\nCODEX_LOAD_ZSH_DSL = \"1\"\n# ...plus any per-machine value your agent-shell functions need, e.g.:\n# MY_KEY_HELPER = \"~/.config/zsh/bin/my-key-helper\"\n```\n\nWhat the marker opens is best pictured as an airlock. On one side sits your interactive `.zshrc` — prompt, completions, keybindings, fuzzy finders, terminal UI — and it stays sealed: agent shells never source it, because in a non-interactive shell that machinery can slow, hang, or spam every command the agent runs. In the middle is a narrow agent-safe bridge that assembles PATH and non-secret env for agent shells. And the marker is the opt-in valve: only when a launch sets it do your chosen helper and override files cross into the agent shell. When something's missing on the Codex side, the temptation is to open the whole hatch. The field rule: **missing PATH is not permission to pour `.zshrc` into Codex.**\n\nHere's the airlock as John runs it today — a guard at the end of his real `~/.config/zsh/.zshenv`. zsh sources `.zshenv` for every shell it starts, so the guard sees every agent shell, and it opens only when the launch opted in and no human is at the prompt (the sourced list here is trimmed to representative entries). Append it to your own `.zshenv`:\n\n``` text\n# zshenv-agent-guard.zsh — append this block to your .zshenv\n# (~/.zshenv, or $ZDOTDIR/.zshenv if your zsh config lives elsewhere).\n#\n# Codex agent commands run in real, NON-interactive zsh shells — and zsh\n# sources .zshenv for every shell it starts. This guard loads agent-facing\n# functions ONLY when the launch opted in (CODEX_LOAD_ZSH_DSL is set) and\n# the shell is non-interactive, so your human terminals never see any of it.\nif [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" && ! -o interactive ]]; then\n  # Base env/paths for agent shells first, then any function files you want\n  # every Codex shell to have — command overrides included.\n  [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n  [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n  [[ -r \"$ZDOTDIR/conf.d/60-git-dsl.zsh\" ]] && source \"$ZDOTDIR/conf.d/60-git-dsl.zsh\"\nfi\n```\n\nBecause these are real zsh shells, overrides are plain function shadowing — an `rm()` function beats `/bin/rm` — and stderr reaches the model naturally. Every policy function in `.pi/agent-shell.zsh` above works verbatim in a file the guard sources. The base file the guard loads first looks like this:\n\n``` text\n# codex-env.zsh (excerpt) — the base file the guard loads first.\n# Functions are not inherited by child shells, so the source guard is\n# deliberately shell-local (typeset -g, not exported):\n[[ -n \"${__CODEX_AGENT_ENV_SOURCED:-}\" ]] && return 0\ntypeset -g __CODEX_AGENT_ENV_SOURCED=1\nexport CODEX_AGENT_ENV_READY=1\n\n# ...PATH and env setup for agent shells, then plain function shadowing:\nif (( $+commands[mdflow] )); then\n  md() {\n    command mdflow \"$@\"\n  }\nfi\n```\n\nThat shell-local guard is a hard-won detail: a prior session that refactored this zsh config had to preserve it, because child shells inherit the exported env markers but not the functions — every nested zsh must re-create them.\n\nThere's also a cleaner cut of the same airlock — the version refined for a prior Codex workshop. It moves the bridge out of `.zshenv` entirely: `~/.zshenv` shrinks to one line that sets `ZDOTDIR`, and `$ZDOTDIR/.zprofile` becomes the login-shell bridge. The proof shell for this setup, `zsh -lc`, is a login shell but *not* interactive — so `.zprofile` runs for it while `.zshrc` never does. In that layout the agent-safe base always crosses the bridge — `codex-env.zsh` marks itself with `CODEX_AGENT_ENV_SOURCED=1`, `conf.d/00-path.zsh` does deterministic PATH assembly, `local.zsh` holds reviewed machine-local overrides — and `CODEX_LOAD_ZSH_DSL` gates only the extra helper DSL. That's the honest difference from the guard above: in the live `.zshenv` version everything, base env included, waits behind the valve; in the clean version the base env rides the bridge on every login shell and only the function surface is opt-in. Same airlock, cleaner plumbing. This setup prompt builds the clean version end to end — hand it to your agent verbatim:\n\n``` text\nSet up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells.\n\nStep 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nDo not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables.\n\nStep 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as:\n\n    export ZDOTDIR=\"${ZDOTDIR:-$HOME/.config/zsh}\"\n\nVerify:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; test -d \"$ZDOTDIR\" && echo \"ZDOTDIR exists\" || echo \"ZDOTDIR missing\"'\n\nStep 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides.\n\nUse this shape, adjusted to the existing files:\n\n    [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n    [[ -r \"$ZDOTDIR/conf.d/00-path.zsh\" ]] && source \"$ZDOTDIR/conf.d/00-path.zsh\"\n    [[ -r \"$ZDOTDIR/local.zsh\" ]] && source \"$ZDOTDIR/local.zsh\"\n\nStep 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded:\n\n    export CODEX_AGENT_ENV_SOURCED=1\n\nDo not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here.\n\nStep 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins.\n\nVerify PATH order:\n\n    zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n\nVerify executable resolution:\n\n    zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n\nStep 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints.\n\nStep 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup.\n\nStep 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`.\n\nAdd this in the agent-safe startup path after `ZDOTDIR` is available:\n\n    if [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n      [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n    fi\n\nVerify the marker is absent by default:\n\n    zsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n\nVerify selected helper loading when requested:\n\n    CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nStep 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers:\n\n    xi() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n    }\n\n    x() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\n    e() {\n      codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\nOnly add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL:\n\n    [shell_environment_policy.set]\n    CODEX_LOAD_ZSH_DSL = \"1\"\n\nOtherwise, keep the marker out of global config and use the wrappers.\n\nVerify wrapper policy wiring:\n\n    zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true\n    rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n\nStep 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state.\n\n    zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\n    env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\nExpected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed.\n\nStep 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`.\n\nStep 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`.\n```\n\nHowever you get there, the proof should be boring: confirm the marker is off by default, confirm the env marker and tools appear when it's on, and re-check from a clean shell so an inherited marker can't fool you. Never dump full `env` output — confirm tools without printing secret values:\n\n``` text\nzsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\nenv -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n```\n\n### Claude Code: PreToolUse hooks are the stderr with teeth\n\nClaude Code's seam is not the shell but the tool call. A `PreToolUse` hook sees every Bash command before it runs and can allow it, deny it, or attach an instruction — and whatever it says is delivered to the model at the moment of action. Check this into any repo as project scope (the same shape John runs globally in `~/.claude/settings.json`):\n\n``` text\n{\n  \"env\": {\n    \"PROJECT_ISSUE_ASSIGNEE\": \"self\"\n  },\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"/.claude/hooks/git-guard.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThe `env` map sets per-project env vars for every session in that project. The hook script receives the pending call as JSON on stdin — including `session_id`, Claude Code's `PI_SESSION_ID`: key per-session state (and the tag in your messages) by it, and use `SessionStart` hooks to seed that state once per conversation. This validator mirrors the page's `git` override; it's distilled from a hook that runs on every Bash call on John's machine:\n\n``` text\n#!/bin/bash\n# .claude/hooks/git-guard.sh — PreToolUse hook for the Bash tool.\n# Distilled from a real global hook in ~/.claude/hooks/ — trimmed to the\n# two moves that matter: deny with guidance, and allow with an injected\n# instruction. Claude Code pipes the pending tool call to stdin as JSON.\n\nINPUT=$(cat)\nCOMMAND=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty')\nSESSION=$(echo \"$INPUT\" | jq -r '.session_id // \"unknown\"')\n\n# Force pushes: deny. The reason is delivered to the model INSTEAD of the\n# push happening — same message, same moment as the pi git() override.\nif echo \"$COMMAND\" | grep -qE 'git[[:space:]]+push.*[[:space:]](-f([[:space:]]|$)|--force)'; then\n  jq -n --arg reason \"[git-guard session=$SESSION] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\" '{\n    hookSpecificOutput: {\n      hookEventName: \"PreToolUse\",\n      permissionDecision: \"deny\",\n      permissionDecisionReason: $reason\n    }\n  }'\n  exit 0\nfi\n\n# Commits: allow, but attach a mandatory instruction at the moment of action\n# (the real hook's pattern: every commit message must read like a prompt\n# another agent could replay to recreate the work).\nif echo \"$COMMAND\" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then\n  jq -n '{\n    hookSpecificOutput: {\n      hookEventName: \"PreToolUse\",\n      permissionDecision: \"allow\",\n      permissionDecisionReason: \"Git commit validated\",\n      additionalContext: \"ALL git commits should be a prompt so another agent can recreate this work. MANDATORY.\"\n    }\n  }'\n  exit 0\nfi\n\nexit 0\n```\n\nMake it executable (`chmod +x .claude/hooks/git-guard.sh`) and test it exactly like the pi overrides — no agent in the loop, just the hook's stdin contract:\n\n``` text\necho '{\"session_id\":\"check-a\",\"tool_input\":{\"command\":\"git push --force origin main\"}}' \\\n  | .claude/hooks/git-guard.sh\n```\n\n``` text\n{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PreToolUse\",\n    \"permissionDecision\": \"deny\",\n    \"permissionDecisionReason\": \"[git-guard session=check-a] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\"\n  }\n}\n```\n\nSame message as the pi override, delivered even harder: the push never runs, and the reason becomes the model's next input. The difference in kind is worth naming — a zsh function is guidance (`command git` bypasses it), while a deny from a hook is enforcement. In all three agents, though, the core move is identical: **the override's output at the moment of action is the message to the model.**\n\n## Why the shell is the right place for policy\n\nYou've written rules for your agent in CLAUDE.md or AGENTS.md: never force push, never hard-delete, always self-assign issues. Then, deep into a session, the agent runs `rm -rf` anyway. The mistake is treating instructions the model read once as if they control actions it takes much later.\n\nEvery deletion, push, and issue the agent creates passes through one place: the shell. A tagged stderr line like `[git-override session=…]` lands in the agent's tool output in the same turn as the blocked action — it can read the message and change course immediately. If you can see that line in the transcript, the agent saw it too.\n\nThe decision rule: use overrides to **steer** — redirect destructive commands, inject policy, brief the model — and use Pi's hooks and permission system to **enforce** anything you can't afford to have bypassed. If violating a rule merely wastes a turn, an override is enough. If it loses data or pushes broken history, put a real control behind the friendly message.\n\n## How the two files work\n\nPi runs every agent command in a fresh shell and, once you trust a project's `.pi/settings.json`, prepends its `shellCommandPrefix`. Here that prefix sources `.pi/agent-shell.zsh`, so every zsh function in it shadows the command of the same name. The real binaries stay reachable: `command rm`, `command git`. This project ships four overrides — quarantining `rm`, guarded `git`, a `linear` rewrite adapted from a real team policy, and the instruction-once `ls`.\n\n## Why session state needs PI_SESSION_ID\n\nA fresh shell per command means plain variables can't carry state between commands. Blocking a force push needs no memory — the evidence is in the argv. But \"tell the agent this once, then get out of the way\" needs state that survives across throwaway shells, and storing it under a fixed path fails in a specific way: `/new`, `/resume`, and `/fork` would all share one \"first time\".\n\nThe pi-session-id extension (~44 lines of TypeScript) exports the active conversation ID as `PI_SESSION_ID` into each shell, syncing it on `session_start`, on human `!` commands, and on every model bash call. The ID is validated against Pi's session-ID syntax before it touches shell source — an invalid value blocks the call rather than permitting injection. With that key, per-conversation state is just a directory name, which is all `pi_instruction_once` is: a `mkdir` that succeeds exactly once per session. Keep overrides stateless unless the first occurrence in a conversation must behave differently from every later one.\n\n## Test the overrides before an agent depends on them\n\nAn override you've never executed is a guess, and a broken one makes every agent command fail mid-session. This project's `demo/run-demo.sh` reproduces Pi's execution model — fresh zsh, prefix sourced, `PI_SESSION_ID` set — so you can watch all five acts fire without Pi in the loop:\n\n``` text\n▶ [session session-A] $ ls demo\n  INSTRUCTIONS FOR THE AI:\n  This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. …\n\n▶ [session session-A] $ rm .demo-state/playground/important.txt\n  [rm-override session=session-A] quarantined 1 item(s) in\n  <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.\n\n▶ [session session-A] $ ls .demo-state/tmp/pi-rm-quarantine/session-A\n  important.txt\n\n▶ [session session-A] $ git push --force origin main\n  [git-override session=session-A] force push blocked. Ask the user to run it\n  themselves, or explain why history must be rewritten and wait for approval.\n\n▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else\n  [linear-override session=session-A] enforcing --assignee self\n  [linear-override dry-run] command linear issue create --title Fix\\ login\\ bug --assignee self\n\n▶ [session session-B] $ ls demo\n  INSTRUCTIONS FOR THE AI: …\n```\n\nThe quarantined file is listed, not gone. The force push never executed. The Linear issue lost `--assignee someone-else` and gained `--assignee self`. And session-B sees the briefing again, because state is keyed by conversation. The same recipe, boiled down to four lines, is the success check above.\n\n## Appendix\n\n### Limits & caveats\n\n- This is guidance with teeth, not a sandbox. `command rm` and `command git` bypass the functions by design — the overrides say so in their own stderr. Real enforcement belongs in Pi's hooks and permission system.\n- pi-session-id does not cover extension-internal `pi.exec()` calls, custom tools that spawn processes directly, custom `user_bash` handlers that build a sanitized environment, or commands that clear their environment with `env -i` / `unset PI_SESSION_ID`.\n- Nothing here measures how often an agent complies with override guidance versus routing around it. The sources support the mechanism and its coverage; treat \"the agent self-corrects\" as behavior to observe in your own sessions, not a guarantee.\n- The demo transcript comes from the harness, not a live Pi session, and the `linear` call ran with `PI_LINEAR_OVERRIDE_DRY_RUN=1`, printing the rewritten argv instead of hitting the Linear API.\n- Without the extension installed, `pi_session_id` falls back to `process-$PPID` — stable per shell process, not per conversation.\n- A trusted `shellCommandPrefix` executes with your full permissions on every command. Review `agent-shell.zsh` the way you'd review any shell script from the internet — because it is one.\n- The cross-agent artifacts were verified at the file level: `zsh -n` / `bash -n` on the shell blocks, JSON/TOML parses, and the Claude Code validator exercised by piping mock hook JSON to it (deny, allow, and passthrough cases). They were not captured from live Claude Code or Codex sessions; field names follow the current Claude Code hooks contract, which can change.\n- The Codex `.zshenv` guard edits a home-directory file, not a project file — it applies to every Codex launch that opts in on that machine, so keep what it sources small and agent-safe.\n\n## Operating practice\n\n### Put policy at the narrowest boundary\n\n#### What to notice\n\nMake **stable intent** and **risk rules** arrive before the action they should change.\n\n#### Try this\n\nChoose one risky or noisy command and write a read-only policy contract before implementing a hook.\n\n> “Meaning that… It won't ever miss because you're configuring the place where the agent is running.”\n\nJohn Lindquist · [01:02:42](https://proud-anchor-53zn.here.now/watch.html?t=3762#recording-player)\n\n#### Concept\n\nRepository files explain **stable intent**. Launch wrappers normalize repeated choices. Command decorators place warnings near an action. Human gates protect irreversible work. Automated checks prove correctness.\n\n#### Reflection\n\nThe recorded environment demo surfaced diagnostics. Treat it as a pattern with failure evidence, not a clean universal implementation.\n\n**Recording evidence:** listen at 00:57:58.\n\n> “Once this is run, we have an observable thing that shows us this is exactly what the outcome will be, and then do it.”\n\nJohn Lindquist · [01:14:20](https://proud-anchor-53zn.here.now/watch.html?t=4460#recording-player)\n\n[Open Configure Your Environment](https://polite-ravine-6v8g.here.now/)\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=3478#q1-environment-policy)"
    },
    {
      "id": "factory-environment-policy-discussion",
      "slug": "environment-policy-discussion",
      "title": "Policy at the agent’s execution boundary — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Execution",
      "tags": [
        "environment-policy",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[37]",
        "resource-manifest.json#videoEvidence.concepts[38]",
        "resource-manifest.json#videoEvidence.concepts[39]",
        "resource-manifest.json#videoEvidence.concepts[40]",
        "resource-manifest.json#videoEvidence.concepts[41]",
        "resource-manifest.json#videoEvidence.concepts[42]",
        "resource-manifest.json#videoEvidence.concepts[43]",
        "resource-manifest.json#videoEvidence.concepts[44]",
        "resource-manifest.json#videoEvidence.concepts[45]",
        "resource-manifest.json#videoEvidence.concepts[46]",
        "resource-manifest.json#videoEvidence.concepts[48]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[12]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[13]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[14]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[15]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[16]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[17]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[18]",
        "resource-manifest.json#videoEvidence.exercises[0]",
        "resource-manifest.json#videoEvidence.exercises[1]",
        "resource-manifest.json#videoEvidence.exercises[2]",
        "resource-manifest.json#videoEvidence.timeline[168]",
        "resource-manifest.json#videoEvidence.timeline[169]",
        "resource-manifest.json#videoEvidence.timeline[172]",
        "resource-manifest.json#videoEvidence.timeline[173]",
        "resource-manifest.json#videoEvidence.timeline[174]",
        "resource-manifest.json#videoEvidence.timeline[175]",
        "resource-manifest.json#videoEvidence.timeline[176]",
        "resource-manifest.json#videoEvidence.timeline[177]",
        "resource-manifest.json#videoEvidence.timeline[178]",
        "resource-manifest.json#videoEvidence.timeline[179]",
        "resource-manifest.json#videoEvidence.timeline[180]",
        "resource-manifest.json#videoEvidence.timeline[182]",
        "resource-manifest.json#videoEvidence.timeline[183]",
        "resource-manifest.json#videoEvidence.timeline[185]",
        "resource-manifest.json#videoEvidence.timeline[186]",
        "resource-manifest.json#videoEvidence.timeline[188]",
        "resource-manifest.json#videoEvidence.timeline[189]",
        "resource-manifest.json#videoEvidence.timeline[190]",
        "resource-manifest.json#videoEvidence.timeline[192]",
        "resource-manifest.json#videoEvidence.timeline[197]",
        "resource-manifest.json#videoEvidence.timeline[199]",
        "resource-manifest.json#videoEvidence.timeline[200]",
        "resource-manifest.json#videoEvidence.timeline[203]",
        "resource-manifest.json#videoEvidence.timeline[206]",
        "resource-manifest.json#videoEvidence.timeline[209]",
        "resource-manifest.json#videoEvidence.timeline[212]",
        "resource-manifest.json#videoEvidence.timeline[213]",
        "resource-manifest.json#videoEvidence.timeline[214]",
        "resource-manifest.json#videoEvidence.timeline[217]",
        "resource-manifest.json#videoEvidence.timeline[218]",
        "resource-manifest.json#videoEvidence.timeline[219]",
        "resource-manifest.json#videoEvidence.timeline[220]",
        "resource-manifest.json#videoEvidence.timeline[223]",
        "resource-manifest.json#videoEvidence.timeline[224]",
        "resource-manifest.json#videoEvidence.timeline[225]",
        "resource-manifest.json#videoEvidence.timeline[226]",
        "resource-manifest.json#videoEvidence.timeline[227]",
        "resource-manifest.json#videoEvidence.timeline[228]",
        "resource-manifest.json#videoEvidence.timeline[230]",
        "resource-manifest.json#videoEvidence.timeline[231]",
        "resource-manifest.json#videoEvidence.timeline[232]",
        "resource-manifest.json#videoEvidence.timeline[233]",
        "resource-manifest.json#videoEvidence.timeline[234]",
        "resource-manifest.json#videoEvidence.timeline[235]",
        "resource-manifest.json#videoEvidence.timeline[236]",
        "resource-manifest.json#videoEvidence.timeline[237]",
        "resource-manifest.json#videoEvidence.timeline[238]",
        "resource-manifest.json#videoEvidence.timeline[240]",
        "resource-manifest.json#videoEvidence.timeline[241]",
        "resource-manifest.json#videoEvidence.timeline[242]",
        "resource-manifest.json#videoEvidence.timeline[246]",
        "resource-manifest.json#videoEvidence.timeline[252]",
        "resource-manifest.json#videoEvidence.timeline[253]",
        "resource-manifest.json#videoEvidence.timeline[255]",
        "resource-manifest.json#videoEvidence.timeline[257]",
        "resource-manifest.json#videoEvidence.timeline[258]",
        "resource-manifest.json#videoEvidence.timeline[260]",
        "resource-manifest.json#videoEvidence.timeline[262]",
        "resource-manifest.json#videoEvidence.timeline[263]",
        "resource-manifest.json#videoEvidence.timeline[264]",
        "resource-manifest.json#videoEvidence.timeline[267]",
        "resource-manifest.json#videoEvidence.uncertainties[11]",
        "resource-manifest.json#videoEvidence.uncertainties[12]",
        "resource-manifest.json#videoEvidence.uncertainties[13]",
        "resource-manifest.json#videoEvidence.uncertainties[15]",
        "resource-manifest.json#videoEvidence.demos[16]",
        "resource-manifest.json#videoEvidence.demos[17]",
        "resource-manifest.json#videoEvidence.demos[18]",
        "resource-manifest.json#videoEvidence.demos[19]",
        "resource-manifest.json#videoEvidence.demos[20]",
        "resource-manifest.json#videoEvidence.demos[21]",
        "resource-manifest.json#videoEvidence.demos[22]"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 2561,
      "url": "/topics/factory-environment-policy-discussion/",
      "markdownUrl": "/markdown/factory-environment-policy-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "agent-function-overriding",
          "text": "Agent Function Overriding",
          "level": 3
        },
        {
          "id": "pre-tool-post-tool-hooks",
          "text": "Pre-tool / Post-tool Hooks",
          "level": 3
        },
        {
          "id": "tool-decorating-environment-overrides",
          "text": "Tool Decorating / Environment Overrides",
          "level": 3
        },
        {
          "id": "model-baking-vs-day-one-adoption",
          "text": "Model Baking vs. Day-One Adoption",
          "level": 3
        },
        {
          "id": "automated-game-evaluation-self-playing-evals",
          "text": "Automated Game Evaluation / Self-Playing Evals",
          "level": 3
        },
        {
          "id": "model-thinking-budgets-reasoning-control",
          "text": "Model Thinking Budgets / Reasoning Control",
          "level": 3
        },
        {
          "id": "herder",
          "text": "Herder",
          "level": 3
        },
        {
          "id": "agent-harness",
          "text": "Agent Harness",
          "level": 3
        },
        {
          "id": "ai-harness",
          "text": "AI Harness",
          "level": 3
        },
        {
          "id": "automated-lens-linting",
          "text": "Automated Lens Linting",
          "level": 3
        },
        {
          "id": "just-in-time-context-injection",
          "text": "Just-in-Time Context Injection",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "can-you-use-pi-with-claude-code-subscription",
          "text": "Can you use pi with Claude Code subscription?",
          "level": 3
        },
        {
          "id": "when-swapping-between-models-using-pi-when-do-you-let-a-model-bake-versus-adopting-on-day-1-like-kimi-for-day-1-adoption-what-low-risk-actions-avoid-controversy-and-how-do-you-gradually-scale-up-risk",
          "text": "When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk?",
          "level": 3
        },
        {
          "id": "an-audience-user-inquires-on-the-replay-log-webpage-regarding-the-benefits-of-utilizing-independent-client-tools-like-pi-alongside-claude-code-and-whether-to-migrate-or-maintain-localized-workflow-wrappers",
          "text": "An audience user inquires on the replay log webpage regarding the benefits of utilizing independent client tools like Pi alongside Claude Code, and whether to migrate or maintain localized workflow wrappers.",
          "level": 3
        },
        {
          "id": "when-do-you-transition-to-larger-batched-staging-or-production-interaction-like-mutating-or-deleting-a-database-and-what-must-you-observe-before-taking-that-risk-what-is-absolutely-off-limits-hard-stop-versus-an-acceptable-risk",
          "text": "When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk?",
          "level": 3
        },
        {
          "id": "can-you-go-through-your-definition-of-a-harness-that-you-are-using-it-feels-a-bit-different-than-what-s-in-my-brain-around-all-of-this",
          "text": "Can you go through your definition of a “harness” that you are using. It feels a bit different than what’s in my brain around all of this.",
          "level": 3
        },
        {
          "id": "when-transitioning-to-larger-batch-staging-or-production-interactions-such-as-mutating-or-deleting-a-database-what-must-be-observed-before-taking-that-risk",
          "text": "When transitioning to larger batch staging or production interactions, such as mutating or deleting a database, what must be observed before taking that risk?",
          "level": 3
        },
        {
          "id": "what-is-linear-a-link-is-fine",
          "text": "What is linear? A link is fine",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-exact-target-sub-model-configuration-tag-string-used-by-codex-engine-inside-the-terminal-viewport-layout",
          "text": "Unresolved: Exact target sub-model configuration tag string used by Codex engine inside the terminal viewport layout.",
          "level": 3
        },
        {
          "id": "unresolved-exact-horizontal-constraints-used-inside-the-pnpm-cache-find-command-pipeline-loop",
          "text": "Unresolved: Exact horizontal constraints used inside the pnpm cache find command pipeline loop.",
          "level": 3
        },
        {
          "id": "unresolved-polite-rasine-6vbg-hore-rem-replay-html",
          "text": "Unresolved: polite-rasine-6vbg.hore.rem/replay.html",
          "level": 3
        },
        {
          "id": "unresolved-exact-sequence-of-alias-mapping-for-launch-command-string",
          "text": "Unresolved: Exact sequence of alias mapping for launch command string.",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-00-38",
          "text": "Demonstration detail: 01:00:38",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-01-53",
          "text": "Demonstration detail: 01:01:53",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-05-43",
          "text": "Demonstration detail: 01:05:43",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-08-21",
          "text": "Demonstration detail: 01:08:21",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-10-01",
          "text": "Demonstration detail: 01:10:01",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-13-44",
          "text": "Demonstration detail: 01:13:44",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-17-59",
          "text": "Demonstration detail: 01:17:59",
          "level": 3
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Agent Function Overriding\n\nRedefining standard terminal tools (e.g., rm, ls) inside an agent's shell environment to intercept actions, append context, or enforce safe behaviors without breaking global workflows.\n\n### Pre-tool / Post-tool Hooks\n\nCommon lifecycle patterns used to execute custom code immediately before or after an AI agent calls a tool, contrasted by John with direct shell function overriding.\n\n### Tool Decorating / Environment Overrides\n\nThe architectural method of injecting specialized prompt rules or behavior validation logic directly into the shell environment binaries so that any LLM model or container harness executing inside that shell is forced to respect those rules implicitly.\n\n### Model Baking vs. Day-One Adoption\n\nA testing methodology where a developer determines whether to wait for comprehensive ecosystem evaluations of a new model release versus immediate low-risk deployment to measure model output fidelity.\n\n### Automated Game Evaluation / Self-Playing Evals\n\nLeveraging LLMs to generate independent, interactive canvas environments with embedded algorithmic game loops to benchmark instruction compliance, multi-step code composition, and creativity metrics.\n\n### Model Thinking Budgets / Reasoning Control\n\nThe structural capacity in terminal agent harnesses to toggle or dial down the internal execution cycles of advanced reasoning models (e.g., from maximum reasoning depth down to moderate/medium duration thresholds) via terminal keyboard macros.\n\n### Herder\n\nA tool used to manage and configure tmux windows and panes efficiently.\n\n### Agent Harness\n\nA lightweight execution layer or wrapper (like pi) around an LLM that lets developers customize prompts, memory management, and MCP tool handling completely from scratch without predefined overhead.\n\n### AI Harness\n\nAn application or command-line wrapper built around a core language model to enforce specific runtime constraints, system prompts, or agentic behaviors (e.g., Pi, Claude Code, Codex).\n\n### Automated Lens Linting\n\nReal-time static analysis and syntax validation performed by specialized agent extensions (like pi-lens), where discovered faults are re-injected into the context loop for self-correction.\n\n### Just-in-Time Context Injection\n\nConstructive implementation of prompt injection where system tools (like git, rm, or linear) are wrapped in the agent's shell setup to introduce behavioral guardrails immediately prior to execution.\n\n## Questions and answer status\n\n### Can you use pi with Claude Code subscription?\n\n**Status: answered.** John indicates that while you can technically run this configuration, he avoids doing so because Anthropic cracks down on using third-party harnesses with subscription tiers.\n\n### When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk?\n\n**Status: answered.** John shares that his approach to day-one adoptions for new models like Kimi involves feeding them low-risk, self-contained creative tasks such as generating independent web arcade mini-games.\n\n### An audience user inquires on the replay log webpage regarding the benefits of utilizing independent client tools like Pi alongside Claude Code, and whether to migrate or maintain localized workflow wrappers.\n\n**Status: answered.** John Lindquist answers that while client environments like Pi offer incredible localized control and Git integration capabilities, the underlying architectural philosophy centers on owning and tailoring your individual tools rather than functioning as an exclusive platform advocate.\n\n### When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk?\n\n**Status: deferred.** Addressed in the next shard.\n\n### Can you go through your definition of a “harness” that you are using. It feels a bit different than what’s in my brain around all of this.\n\n**Status: answered.** John explains that a harness is the minimal framework or wrapper that handles token spending, context loading, and tool execution instructions.\n\n### When transitioning to larger batch staging or production interactions, such as mutating or deleting a database, what must be observed before taking that risk?\n\n**Status: answered.** The developer should construct a comprehensive logging matrix, perform numerous dry runs to explicitly review downstream output variations, and inspect observable results before conducting live mutation tasks.\n\n### What is linear? A link is fine\n\n**Status: answered.** Students in the chat clarify that Linear is a modern, high-performance project management alternative to Jira, providing the direct URL link.\n\n## Exercises\n\n- **Try:** Set up a local shell intercept rule that decorates standard utility calls with an automation log verification layer.\n  **Basis:** John's explanation of custom overrides targeting default functions like ls or curl to inject structured execution safety borders across harnesses.\n\n- **Try:** Clone the miniarcade repository from GitHub, view the evals data, and set up a custom canvas configuration to test a model's visual code output consistency.\n  **Basis:** John Lindquist explicitly suggests cloning the repository at 01:07:55.020 to experiment with building custom variants.\n\n- **Try:** Observe the agent as it specifies custom execution guards across shell scripts and automatically attempts to clear reported validation exceptions using static evaluation rules.\n  **Basis:** Visual stream updates tracking pi-lens terminal reports between 01:13:44.935 and 01:16:45.000.\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [00:58:42](https://proud-anchor-53zn.here.now/watch.html?t=3522#recording-player) — A markdown table titled 'DANS TRICK IN CLAUDE CODE AND CODEX' is scrolled into view, showing file paths like .pi/settings.json.\n\n- [00:59:11](https://proud-anchor-53zn.here.now/watch.html?t=3551#recording-player) — John outlines how custom decorators can redefine standard shell utilities like rm or ls for the agent instead of conventional hooks.\n\n- [01:00:43](https://proud-anchor-53zn.here.now/watch.html?t=3643#recording-player) — The command 'take ~/dev/pi-env-demo' is typed and executed to initialize the workspace folder.\n\n- [01:00:54](https://proud-anchor-53zn.here.now/watch.html?t=3654#recording-player) — John launches the pi interface runner and inputs the prompt combined with policy instructions for the ls tool hook.\n\n- [01:01:30](https://proud-anchor-53zn.here.now/watch.html?t=3690#recording-player) — The terminal window reports 'Planning URL Instruction extraction' and 'Working...' states under the Codex model selection.\n\n- [01:01:53](https://proud-anchor-53zn.here.now/watch.html?t=3713#recording-player) — The screen displays a Ghostty terminal window where the pi tool is running an agent workflow named pi-env-demo, planning instruction extraction from a local deployment URL.\n\n- [01:01:53](https://proud-anchor-53zn.here.now/watch.html?t=3713#recording-player) — John explains wrapping core shell tools like rm, ls, and curl to guarantee persistent agent boundaries.\n\n- [01:01:58](https://proud-anchor-53zn.here.now/watch.html?t=3718#recording-player) — The automated agent triggers a deep file-system mapping command: $ pwd && printf '\n-- top-level -\n' && ls -la && printf '\n-- pi dirs -\n' && find . -maxdepth 3 -type f -o -type d | sort | head -200.\n\n- [01:02:50](https://proud-anchor-53zn.here.now/watch.html?t=3770#recording-player) — Terminal updates as the agent shifts tasks to Planning full doc and core loading and Deciding core retrieval before commands.\n\n- [01:02:57](https://proud-anchor-53zn.here.now/watch.html?t=3777#recording-player) — Agent runs an internal automation routine command: $ agent-browser skills get core --full.\n\n- [01:03:15](https://proud-anchor-53zn.here.now/watch.html?t=3795#recording-player) — Agent inspects code implementation blocks by reading lines 1364-2963 of docs/extensions.md.\n\n- [01:03:42](https://proud-anchor-53zn.here.now/watch.html?t=3822#recording-player) — Agent reads an additional block from docs/extensions.md lines 2659-3058.\n\n- [01:03:43](https://proud-anchor-53zn.here.now/watch.html?t=3823#recording-player) — Agent runs an orchestration pipeline using agent-browser to inspect the site layout at https://polite-ravine-6v0g.here.now/replay.html.\n\n- [01:03:56](https://proud-anchor-53zn.here.now/watch.html?t=3836#recording-player) — John addresses the trade-offs of using private credentials or subscriptions inside community harnesses due to usage crackdowns.\n\n- [01:04:08](https://proud-anchor-53zn.here.now/watch.html?t=3848#recording-player) — The terminal agent generates a list of planning goals for environment safeguards, including Clarifying ls function behavior, Planning file age enforcement across tools, and Designing multi-layer file mutation guards.\n\n- [01:04:56](https://proud-anchor-53zn.here.now/watch.html?t=3896#recording-player) — The background agent executes a global store lookup command: $ find ~/Library/pnpm/global/5/.pnpm/... -path '/tools/ls.' ....\n\n- [01:05:04](https://proud-anchor-53zn.here.now/watch.html?t=3904#recording-player) — Terminal renders file paths from the global pnpm cache and schedules tasks like Planning dynamic date handling.\n\n- [01:05:27](https://proud-anchor-53zn.here.now/watch.html?t=3927#recording-player) — Agent runs state capture command: $ agent-browser --session pi-env-instructions snapshot.\n\n- [01:05:35](https://proud-anchor-53zn.here.now/watch.html?t=3935#recording-player) — John outlines his practice of evaluating brand-new models by asking them to build standalone mini-games.\n\n- [01:05:44](https://proud-anchor-53zn.here.now/watch.html?t=3944#recording-player) — John Lindquist discusses the layout, prompts, and evaluation criteria embedded inside the repository.\n\n- [01:05:54](https://proud-anchor-53zn.here.now/watch.html?t=3954#recording-player) — The GitHub repository johnlindquist/miniarcade is shown, highlighting core documentation files like CLAUDE.md and VISION.md.\n\n- [01:06:00](https://proud-anchor-53zn.here.now/watch.html?t=3960#recording-player) — John Lindquist sends the public URL: https://github.com/johnlindquist/miniarcade\n\n- [01:06:31](https://proud-anchor-53zn.here.now/watch.html?t=3991#recording-player) — The presenter clicks on 'SKY REIGN' (miniarcade.dev/sky-reign.html), launching a side-scrolling vehicle shooter game.\n\n- [01:07:04](https://proud-anchor-53zn.here.now/watch.html?t=4024#recording-player) — a participant asks about running Claude Code inside VS Code and model relevance with upcoming architectures.\n\n- [01:07:52](https://proud-anchor-53zn.here.now/watch.html?t=4072#recording-player) — The browser displays miniarcade.dev/side-surfers.html, running a 3D-perspective rail-runner game environment.\n\n- [01:08:27](https://proud-anchor-53zn.here.now/watch.html?t=4107#recording-player) — The presenter realizes the model status line in the lower-right area is configured to 'gpt-5.6-sol · max'.\n\n- [01:08:41](https://proud-anchor-53zn.here.now/watch.html?t=4121#recording-player) — The presenter inputs the Shift+Tab keyboard shortcut sequence, prompting an inline context configuration overlay.\n\n- [01:08:43](https://proud-anchor-53zn.here.now/watch.html?t=4123#recording-player) — The configuration string field refreshes, updating the reasoning setting to 'gpt-5.6-sol · medium'.\n\n- [01:09:41](https://proud-anchor-53zn.here.now/watch.html?t=4181#recording-player) — John Lindquist mentions using Herder to manage tmux panes as an alternative to cmux.\n\n- [01:10:01](https://proud-anchor-53zn.here.now/watch.html?t=4201#recording-player) — John hits a keyboard shortcut to trigger his custom terminal fuzzy search overlay.\n\n- [01:10:04](https://proud-anchor-53zn.here.now/watch.html?t=4204#recording-player) — John types 'screen' into the search box to find text strings across open panes.\n\n- [01:10:07](https://proud-anchor-53zn.here.now/watch.html?t=4207#recording-player) — John hits enter on a search match, switching to the screenshot-demo pane logs.\n\n- [01:10:27](https://proud-anchor-53zn.here.now/watch.html?t=4227#recording-player) — Terminal switches back to the pi-env-demo pane where the agent is continuously working.\n\n- [01:10:34](https://proud-anchor-53zn.here.now/watch.html?t=4234#recording-player) — a participant provides the URL for Herder: https://herdr.dev.\n\n- [01:10:39](https://proud-anchor-53zn.here.now/watch.html?t=4239#recording-player) — a participant asks about transition criteria to destructive batched production or staging tasks.\n\n- [01:11:51](https://proud-anchor-53zn.here.now/watch.html?t=4311#recording-player) — The pi agent executes a batch command to find software versions and binary paths.\n\n- [01:12:24](https://proud-anchor-53zn.here.now/watch.html?t=4344#recording-player) — a participant asks for John's specific definition of an agent harness.\n\n- [01:12:32](https://proud-anchor-53zn.here.now/watch.html?t=4352#recording-player) — The agent invokes a memory_search query, returning a notification that no matching memories were found.\n\n- [01:13:34](https://proud-anchor-53zn.here.now/watch.html?t=4414#recording-player) — Ghostty terminal window displays the pi-env-demo agent in a working state utilizing the gpt-5.6-sol model.\n\n- [01:13:38](https://proud-anchor-53zn.here.now/watch.html?t=4418#recording-player) — John Lindquist evaluates a question regarding standard safety steps and logging checks prior to database alterations.\n\n- [01:13:44](https://proud-anchor-53zn.here.now/watch.html?t=4424#recording-player) — The agent creates and outputs settings variables directly to the dev path environment inside settings.json.\n\n- [01:13:51](https://proud-anchor-53zn.here.now/watch.html?t=4431#recording-player) — John Lindquist mandates executing thorough dry runs and checking outcome summaries prior to production updates.\n\n- [01:13:52](https://proud-anchor-53zn.here.now/watch.html?t=4432#recording-player) — The environment handles automated write loops for file age constant settings inside file-age-policy.mjs.\n\n- [01:14:35](https://proud-anchor-53zn.here.now/watch.html?t=4475#recording-player) — John Lindquist defines an AI harness as structural wrapper logic designed to shape tool outputs and model behavior.\n\n- [01:15:04](https://proud-anchor-53zn.here.now/watch.html?t=4504#recording-player) — The shell interception routines are constructed and committed to disk inside the agent-shell.zsh script file.\n\n- [01:15:26](https://proud-anchor-53zn.here.now/watch.html?t=4526#recording-player) — a participant states that harness represents an emerging term within present industry conversations.\n\n- [01:15:28](https://proud-anchor-53zn.here.now/watch.html?t=4528#recording-player) — The pi-lens tool execution surfaces multiple diagnostic warnings regarding shell parameter expansions.\n\n- [01:15:38](https://proud-anchor-53zn.here.now/watch.html?t=4538#recording-player) — Automated text replacements are injected by the agent script to address reported shell warnings.\n\n- [01:16:12](https://proud-anchor-53zn.here.now/watch.html?t=4572#recording-player) — John Lindquist notes that pi-lens acts as an integrated workspace helper, delivering automatic feedback to the agent context.\n\n- [01:16:36](https://proud-anchor-53zn.here.now/watch.html?t=4596#recording-player) — The system writes data to file-guard.ts, generating compilation anomalies due to unresolved type dependencies.\n\n- [01:17:22](https://proud-anchor-53zn.here.now/watch.html?t=4642#recording-player) — John Lindquist points out that these visual templates were developed by asking Codex to analyze a reference screenshot.\n\n- [01:17:50](https://proud-anchor-53zn.here.now/watch.html?t=4670#recording-player) — John speaks about the utility of dropping images into Codex to get UI/UX design mockups.\n\n- [01:17:59](https://proud-anchor-53zn.here.now/watch.html?t=4679#recording-player) — John inputs 'take ~/dev/article-mockup' in his shell environment to establish a new work folder.\n\n- [01:18:17](https://proud-anchor-53zn.here.now/watch.html?t=4697#recording-player) — John responds with 1 to confirm folder trust for the automated tool environment.\n\n- [01:18:23](https://proud-anchor-53zn.here.now/watch.html?t=4703#recording-player) — John provides a prompt to Claude Code: 'Build a pixel perfect, version of this as a landing page using only html/css/js [Image #1]'.\n\n- [01:18:36](https://proud-anchor-53zn.here.now/watch.html?t=4716#recording-player) — Claude Code initializes background tasks while a parallel pi-env-demo agent process runs linting and diagnostics on file-age-policy.js.\n\n- [01:19:58](https://proud-anchor-53zn.here.now/watch.html?t=4798#recording-player) — The background automated agent context triggers an 'npm install --ignore-scripts' execution block inside the workspace terminal.\n\n- [01:20:49](https://proud-anchor-53zn.here.now/watch.html?t=4849#recording-player) — a participant asks 'What is linear? A link is fine'.\n\n- [01:21:05](https://proud-anchor-53zn.here.now/watch.html?t=4865#recording-player) — a participant replies 'It’s like Jira but for Hipsters'.\n\n- [01:21:06](https://proud-anchor-53zn.here.now/watch.html?t=4866#recording-player) — a participant references the official platform link https://linear.app/.\n\n- [01:21:18](https://proud-anchor-53zn.here.now/watch.html?t=4878#recording-player) — John highlights structural guidelines regarding ~/.config/env/ behavioral decorators.\n\n### Unresolved: Exact target sub-model configuration tag string used by Codex engine inside the terminal viewport layout.\n\nText resolution rendering in font layout panel on the right margin of the app screen window is small.\n\n**Discriminating evidence:** Correlate with explicit project declarations or subsequent high-res configuration file captures.\n\n### Unresolved: Exact horizontal constraints used inside the pnpm cache find command pipeline loop.\n\nTerminal screen edge boundaries wrap or limit full view tracking of long parameter flags near lines end.\n\n**Discriminating evidence:** Verify by testing standard flag parameters of multi-target path queries within contemporary global pnpm layouts.\n\n### Unresolved: polite-rasine-6vbg.hore.rem/replay.html\n\nThe top-level domain suffix used (.rem) represents an isolated system naming asset rather than standard public registries.\n\n**Discriminating evidence:** Verify with platform operators whether a localized hosts mapping file modification or zero-trust mesh link is needed to navigate to this interface.\n\n### Unresolved: Exact sequence of alias mapping for launch command string.\n\nThe precise keystrokes were hidden behind rapid system autocompletion parameters.\n\n**Discriminating evidence:** Check system profile scripts or configuration references for active project shell aliases.\n\n### Demonstration detail: 01:00:38\n\n- Create local folder via shell take shortcut.\n- Boot agent terminal runner app layout.\n- Paste custom rule set alongside documentation URL to prompt field input.\n\n**Tools observed:** Ghostty, Pi, Codex.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake ~/dev/pi-env-demo\npi-env-demo pi\n```\n\n### Demonstration detail: 01:01:53\n\n- Automated directory mapping query execution\n- Skill module extraction using core options\n- Document segment parsing on target project layouts\n- Global store lookup searching for tool source modules\n\n**Tools observed:** pi, agent-browser.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\npwd && printf '\n-- top-level -\n' && ls -la && printf '\n-- pi dirs -\n' && find . -maxdepth 3 -type f -o -type d | sort | head -200\nagent-browser skills get core --full\nagent-browser --session pi-env-instructions open 'https://polite-ravine-6v0g.here.now/replay.html' ...\nfind ~/Library/pnpm/global/5/.pnpm/ -path '/tools/ls.' -o -path '/tools/edit.' -o -path '/tools/write.'\n```\n\n### Demonstration detail: 01:05:43\n\n- Opened the primary project dashboard\n- Browsed to the public codebase layout\n- Loaded and interacted with four individual canvas video applications: Sky Reign, Star Roller, Crystal Mesa, and Side Surfers\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 01:08:21\n\n- Brought terminal application into focus\n- Inspected the current model budget status bar\n- Triggered context menu macro via Shift+Tab and reduced thinking level constraint values\n\n**Tools observed:** pi-env-demo shell.\n\n### Demonstration detail: 01:10:01\n\n- Triggered custom global pane search utility\n- Searched for terminal logs with keyword 'screen'\n- Switched active terminal views using fuzzy selection match\n\n**Tools observed:** Herder, tmux.\n\n### Demonstration detail: 01:13:44\n\n- Automated creation and parsing of settings parameters.\n- Static code optimization and parameter alignment via automated patch streams.\n\n**Tools observed:** Ghostty, pi-lens.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\npi-lens - clear settings.json\npi-lens - stw 13M settings.json agent-shell.zsh file-age-policy.mjs\n```\n\n### Demonstration detail: 01:17:59\n\n- Created workspace folder with take command.\n- Launched Claude Code agent interface.\n- Passed local design image template as context into the LLM system prompt framework.\n\n**Tools observed:** Claude Code v2.1.212, zsh.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake ~/dev/article-mockup\n```"
    },
    {
      "id": "factory-environment-policy-practice",
      "slug": "environment-policy-practice",
      "title": "Policy at the agent’s execution boundary — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for policy at the agent’s execution boundary.",
      "category": "Execution",
      "tags": [
        "prompts",
        "exercises",
        "environment-policy"
      ],
      "sources": [
        {
          "label": "Policy at the agent’s execution boundary",
          "url": "https://polite-ravine-6v8g.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://polite-ravine-6v8g.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "01-env/index.html#Quick start",
        "01-env/index.html#Prompt library",
        "01-env/index.html#Set it up (agent guide)",
        "01-env/index.html#See the once-per-conversation briefing",
        "01-env/index.html#Delete a file — rm quarantines instead",
        "01-env/index.html#Force-push — git blocks it with guidance",
        "01-env/index.html#Create a Linear issue — policy rewrites the flags",
        "01-env/agent.md"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 4513,
      "url": "/topics/factory-environment-policy-practice/",
      "markdownUrl": "/markdown/factory-environment-policy-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "see-the-once-per-conversation-briefing",
          "text": "See the once-per-conversation briefing",
          "level": 3
        },
        {
          "id": "delete-a-file-rm-quarantines-instead",
          "text": "Delete a file — rm quarantines instead",
          "level": 3
        },
        {
          "id": "force-push-git-blocks-it-with-guidance",
          "text": "Force-push — git blocks it with guidance",
          "level": 3
        },
        {
          "id": "create-a-linear-issue-policy-rewrites-the-flags",
          "text": "Create a Linear issue — policy rewrites the flags",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "configuring-your-agent-s-environment-agent-setup-guide",
          "text": "Configuring Your Agent's Environment — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "optional-the-same-trick-in-claude-code-and-codex",
          "text": "Optional: the same trick in Claude Code and Codex",
          "level": 2
        },
        {
          "id": "claude-code-project-scoped-safe-to-check-into-a-repo",
          "text": "Claude Code (project-scoped, safe to check into a repo)",
          "level": 3
        },
        {
          "id": "codex-user-scoped-edits-home-config-so-confirm-with-your-user-first",
          "text": "Codex (user-scoped — edits home config, so confirm with your user first)",
          "level": 3
        },
        {
          "id": "optional-clean-rebuild-the-agent-setup-prompt",
          "text": "Optional clean rebuild: the Agent Setup Prompt",
          "level": 4
        },
        {
          "id": "verification-either-version",
          "text": "Verification (either version)",
          "level": 4
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for policy at the agent’s execution boundary.\n\n## Quick start\n\nFrom your project root:\n\n``` text\npi install git:github.com/johnlindquist/pi-session-id\nmkdir -p .pi\n# paste the two files from the agent guide below into .pi/, then prove it:\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\n```\n\nFirst `ls` prints instructions addressed to the AI; the second runs normally. That's the whole mechanism working.\n\n## Prompt library\n\nPaste these into Pi inside a project that has the setup below (with `.pi/settings.json` trusted) and watch the agent read the override output and self-correct.\n\n### See the once-per-conversation briefing\n\n- Agent: Pi\n- Working directory: a project with this setup\n- Expected result: the agent quotes the \"INSTRUCTIONS FOR THE AI\" block its first ls returned\n\n``` text\nList the files in this project. If the shell tells you anything unusual, quote it back to me before doing anything else.\n```\n\n### Delete a file — rm quarantines instead\n\n- Agent: Pi\n- Working directory: a project with this setup\n- Expected result: the agent reports \\[rm-override\\] quarantined the file and names the quarantine path\n\n``` text\nCreate a file named scratch-note.txt containing the word \"disposable\", then delete it. Afterward, tell me exactly what the shell printed when you deleted it and where the file actually went.\n```\n\n### Force-push — git blocks it with guidance\n\n- Agent: Pi\n- Working directory: a project with this setup, inside a git repo\n- Expected result: the agent stops and relays \"\\[git-override\\] force push blocked\" instead of pushing\n\n``` text\nForce-push the current branch to origin right now. If anything stops you, do not work around it — stop and report exactly what it said.\n```\n\n### Create a Linear issue — policy rewrites the flags\n\n- Agent: Pi\n- Working directory: a project with this setup and the linear CLI\n- Expected result: the command runs with --assignee self no matter what the agent passed\n\n``` text\nCreate a Linear issue titled \"Fix login bug\" and assign it to someone-else. Show me the exact command you ran and everything it printed.\n```\n\n## Set it up (agent guide)\n\n1.  Install the pi-session-id extension so every agent shell gets a conversation-scoped `PI_SESSION_ID`:\n\n    ``` text\n    pi install git:github.com/johnlindquist/pi-session-id\n    ```\n\n2.  Create `.pi/settings.json` in your project. It tells Pi which shell to use and sources the override file before every command:\n\n    ``` text\n    {\n      \"shellPath\": \"/bin/zsh\",\n      \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n    }\n    ```\n\n3.  Create `.pi/agent-shell.zsh` — the override file itself, complete. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own:\n\n    ``` text\n    # .pi/agent-shell.zsh\n    #\n    # Sourced before EVERY shell command the agent runs, via .pi/settings.json:\n    #\n    #   { \"shellPath\": \"/bin/zsh\",\n    #     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\" }\n    #\n    # Pi spawns a fresh shell per command, so plain shell variables can't carry\n    # state between commands. The pi-session-id extension\n    # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into\n    # each of those shells, which lets these overrides keep per-conversation state\n    # on disk — e.g. \"show this instruction once per session\".\n\n    pi_session_id() {\n      print -r -- \"${PI_SESSION_ID:-process-$PPID}\"\n    }\n\n    # Emit a heredoc the FIRST time a command runs in this session, then get out\n    # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,\n    # and parallel Pi processes each get their own \"first time\".\n    pi_instruction_once() {\n      emulate -L zsh\n      local command_name=\"$1\"\n      local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n      local session_id=\"$(pi_session_id)\"\n      local marker=\"$state_root/$session_id/$command_name\"\n\n      mkdir -p \"$state_root/$session_id\" || return 1\n      if mkdir \"$marker\" 2>/dev/null; then\n        cat\n        return 0\n      fi\n      return 1\n    }\n\n    # --- rm: quarantine instead of delete --------------------------------------\n    # The agent never permanently deletes anything. Targets move to a\n    # session-scoped quarantine dir; the notice tells the agent how to restore.\n    rm() {\n      emulate -L zsh\n      local session_id=\"$(pi_session_id)\"\n      local quarantine=\"${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id\"\n      local -a targets\n      local arg\n      for arg in \"$@\"; do\n        [[ \"$arg\" == -* ]] || targets+=(\"$arg\")\n      done\n\n      if (( ${#targets} == 0 )); then\n        command rm \"$@\"\n        return\n      fi\n\n      mkdir -p \"$quarantine\" || return 1\n      local moved=0 target\n      for target in \"${targets[@]}\"; do\n        if [[ -e \"$target\" || -L \"$target\" ]]; then\n          mv -- \"$target\" \"$quarantine/\" && (( moved++ ))\n        else\n          print -u2 -- \"[rm-override] no such file: $target\"\n        fi\n      done\n      print -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\n      print -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n    }\n\n    # --- git: block destructive operations --------------------------------------\n    # Force pushes and hard resets fail loudly with guidance instead of running.\n    git() {\n      emulate -L zsh\n      local session_id=\"$(pi_session_id)\"\n      local arg\n\n      if [[ \"$1\" == \"push\" ]]; then\n        for arg in \"$@\"; do\n          case \"$arg\" in\n            -f|--force|--force-with-lease|--force-if-includes)\n              print -u2 -- \"[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\"\n              return 1\n              ;;\n          esac\n        done\n      fi\n\n      if [[ \"$1\" == \"reset\" ]]; then\n        for arg in \"$@\"; do\n          if [[ \"$arg\" == \"--hard\" ]]; then\n            print -u2 -- \"[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable.\"\n            return 1\n          fi\n        done\n      fi\n\n      command git \"$@\"\n    }\n\n    # --- linear: enforce team policy on issue creation --------------------------\n    # Adapted from a real override in ~/dev/pi-session-test: every issue the agent\n    # creates is assigned to the current user, no matter what flags it passed.\n    linear() {\n      emulate -L zsh\n      local session_id=\"$(pi_session_id)\"\n\n      if [[ \"$1\" != \"issue\" || \"$2\" != \"create\" ]]; then\n        command linear \"$@\"\n        return\n      fi\n\n      local -a decorated\n      local skip=0 arg\n      for arg in \"$@\"; do\n        if (( skip )); then skip=0; continue; fi\n        case \"$arg\" in\n          -a|--assignee) skip=1 ;;\n          -a=*|--assignee=*) ;;\n          *) decorated+=(\"$arg\") ;;\n        esac\n      done\n      decorated+=(--assignee self)\n\n      print -u2 -- \"[linear-override session=$session_id] enforcing --assignee self\"\n\n      if [[ -n \"${PI_LINEAR_OVERRIDE_DRY_RUN:-}\" ]]; then\n        print -n -- \"[linear-override dry-run] command linear\"\n        for arg in \"${decorated[@]}\"; do printf ' %q' \"$arg\"; done\n        print\n        return 0\n      fi\n\n      command linear \"${decorated[@]}\"\n    }\n\n    # --- ls: teach the agent, once per conversation ------------------------------\n    # The pattern from the pi-session-id README: the first `ls` of a session\n    # returns instructions to the model instead of output; every later `ls` runs\n    # normally. Swap the message for anything you want the agent told exactly once.\n    ls() {\n      if pi_instruction_once ls <<'INSTRUCTIONS'; then\n    INSTRUCTIONS FOR THE AI:\n    This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\n    Deletions are quarantined, force pushes are blocked, and Linear issues are\n    always self-assigned. Run ls again to execute the command normally.\n    INSTRUCTIONS\n        return 0\n      fi\n\n      command ls \"$@\"\n    }\n    ```\n\n4.  Open the project in Pi and approve `.pi/settings.json` when Pi asks you to trust it. Until you do, the prefix never runs.\n\n**Success check:** run each override in a fresh `zsh -c` with `PI_SESSION_ID` set — the same way Pi runs commands — from your project root:\n\n``` text\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'\n```\n\n``` text\nINSTRUCTIONS FOR THE AI:\nThis project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\nDeletions are quarantined, force pushes are blocked, and Linear issues are\nalways self-assigned. Run ls again to execute the command normally.\nCLAUDE.md\ndemo\nfolio\nnotes\nREADME.md\nsite\n[git-override session=check-b] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\n```\n\nLine by line: the first `ls` returns the briefing, the second returns your project's normal listing (this transcript shows this project's files), and the force push is refused with exit code 1.\n\n## Complete reusable setup contract\n\n## Configuring Your Agent's Environment — agent setup guide\n\nFollowing this file sets up: a project-specific shell for the Pi coding agent, where `rm` quarantines instead of deleting, `git` refuses force pushes and hard resets, `linear` always self-assigns issues, and `ls` briefs the model once per conversation. An optional final section replicates the same moment-of-action policy environment in Claude Code and Codex.\n\nPlaceholders used below: `<project-root>` = the project you are working in. All other paths are literal. Run every command from `<project-root>`.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nzsh --version\npi --version\n```\n\nExpected: any zsh 5.x+, and any Pi CLI version. If `pi` is missing, you can still install the two files and run the success check — it only needs zsh — but tell your user that the per-conversation behavior needs Pi plus the pi-session-id extension. If `zsh` is missing, stop and tell your user what to install.\n\n## Steps\n\n1. Install the pi-session-id extension so every shell Pi spawns gets a conversation-scoped `PI_SESSION_ID`:\n\n   ```bash\n   pi install git:github.com/johnlindquist/pi-session-id\n   ```\n\n2. Create `.pi/settings.json` with exactly this content:\n\n   ```json\n   {\n     \"shellPath\": \"/bin/zsh\",\n     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n   }\n   ```\n\n3. Create `.pi/agent-shell.zsh` with exactly this content. If your user wants different policy, keep `pi_session_id` and `pi_instruction_once` as-is and swap the four policy functions (`rm`, `git`, `linear`, `ls`) for their own:\n\n   ```zsh\n   # .pi/agent-shell.zsh\n   #\n   # Sourced before EVERY shell command the agent runs, via .pi/settings.json:\n   #\n   #   { \"shellPath\": \"/bin/zsh\",\n   #     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\" }\n   #\n   # Pi spawns a fresh shell per command, so plain shell variables can't carry\n   # state between commands. The pi-session-id extension\n   # (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into\n   # each of those shells, which lets these overrides keep per-conversation state\n   # on disk — e.g. \"show this instruction once per session\".\n\n   pi_session_id() {\n     print -r -- \"${PI_SESSION_ID:-process-$PPID}\"\n   }\n\n   # Emit a heredoc the FIRST time a command runs in this session, then get out\n   # of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,\n   # and parallel Pi processes each get their own \"first time\".\n   pi_instruction_once() {\n     emulate -L zsh\n     local command_name=\"$1\"\n     local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n     local session_id=\"$(pi_session_id)\"\n     local marker=\"$state_root/$session_id/$command_name\"\n\n     mkdir -p \"$state_root/$session_id\" || return 1\n     if mkdir \"$marker\" 2>/dev/null; then\n       cat\n       return 0\n     fi\n     return 1\n   }\n\n   # --- rm: quarantine instead of delete --------------------------------------\n   # The agent never permanently deletes anything. Targets move to a\n   # session-scoped quarantine dir; the notice tells the agent how to restore.\n   rm() {\n     emulate -L zsh\n     local session_id=\"$(pi_session_id)\"\n     local quarantine=\"${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id\"\n     local -a targets\n     local arg\n     for arg in \"$@\"; do\n       [[ \"$arg\" == -* ]] || targets+=(\"$arg\")\n     done\n\n     if (( ${#targets} == 0 )); then\n       command rm \"$@\"\n       return\n     fi\n\n     mkdir -p \"$quarantine\" || return 1\n     local moved=0 target\n     for target in \"${targets[@]}\"; do\n       if [[ -e \"$target\" || -L \"$target\" ]]; then\n         mv -- \"$target\" \"$quarantine/\" && (( moved++ ))\n       else\n         print -u2 -- \"[rm-override] no such file: $target\"\n       fi\n     done\n     print -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\n     print -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n   }\n\n   # --- git: block destructive operations --------------------------------------\n   # Force pushes and hard resets fail loudly with guidance instead of running.\n   git() {\n     emulate -L zsh\n     local session_id=\"$(pi_session_id)\"\n     local arg\n\n     if [[ \"$1\" == \"push\" ]]; then\n       for arg in \"$@\"; do\n         case \"$arg\" in\n           -f|--force|--force-with-lease|--force-if-includes)\n             print -u2 -- \"[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\"\n             return 1\n             ;;\n         esac\n       done\n     fi\n\n     if [[ \"$1\" == \"reset\" ]]; then\n       for arg in \"$@\"; do\n         if [[ \"$arg\" == \"--hard\" ]]; then\n           print -u2 -- \"[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable.\"\n           return 1\n         fi\n       done\n     fi\n\n     command git \"$@\"\n   }\n\n   # --- linear: enforce team policy on issue creation --------------------------\n   # Adapted from a real override in ~/dev/pi-session-test: every issue the agent\n   # creates is assigned to the current user, no matter what flags it passed.\n   linear() {\n     emulate -L zsh\n     local session_id=\"$(pi_session_id)\"\n\n     if [[ \"$1\" != \"issue\" || \"$2\" != \"create\" ]]; then\n       command linear \"$@\"\n       return\n     fi\n\n     local -a decorated\n     local skip=0 arg\n     for arg in \"$@\"; do\n       if (( skip )); then skip=0; continue; fi\n       case \"$arg\" in\n         -a|--assignee) skip=1 ;;\n         -a=*|--assignee=*) ;;\n         *) decorated+=(\"$arg\") ;;\n       esac\n     done\n     decorated+=(--assignee self)\n\n     print -u2 -- \"[linear-override session=$session_id] enforcing --assignee self\"\n\n     if [[ -n \"${PI_LINEAR_OVERRIDE_DRY_RUN:-}\" ]]; then\n       print -n -- \"[linear-override dry-run] command linear\"\n       for arg in \"${decorated[@]}\"; do printf ' %q' \"$arg\"; done\n       print\n       return 0\n     fi\n\n     command linear \"${decorated[@]}\"\n   }\n\n   # --- ls: teach the agent, once per conversation ------------------------------\n   # The pattern from the pi-session-id README: the first `ls` of a session\n   # returns instructions to the model instead of output; every later `ls` runs\n   # normally. Swap the message for anything you want the agent told exactly once.\n   ls() {\n     if pi_instruction_once ls <<'INSTRUCTIONS'; then\n   INSTRUCTIONS FOR THE AI:\n   This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\n   Deletions are quarantined, force pushes are blocked, and Linear issues are\n   always self-assigned. Run ls again to execute the command normally.\n   INSTRUCTIONS\n       return 0\n     fi\n\n     command ls \"$@\"\n   }\n   ```\n\n4. Tell your user to open the project in Pi and approve `.pi/settings.json` when Pi asks to trust it. Until they do, the `shellCommandPrefix` never runs.\n\n## Success check\n\nRun from `<project-root>` — this reproduces how Pi runs commands (fresh zsh, prefix sourced, `PI_SESSION_ID` set):\n\n```bash\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'\n```\n\nExpected observable result:\n\n1. The first `ls` prints the briefing starting with `INSTRUCTIONS FOR THE AI:` instead of a file listing.\n2. The second `ls` prints the project's normal file listing.\n3. The `git push --force` prints `[git-override session=check-b] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.` and exits with code 1 (nothing is pushed; this is safe to run even outside a git repo, because the override refuses before real git runs).\n\nReport to your user: what you set up, the success-check output, and anything you had to adapt.\n\n## Optional: the same trick in Claude Code and Codex\n\nThe insight is portable — in every agent, the override's output at the moment of action is the message to the model. Only do these if your user asks for them; both are covered on https://polite-ravine-6v8g.here.now/#same-trick-in-claude-code-and-codex.\n\n### Claude Code (project-scoped, safe to check into a repo)\n\n1. Create `.claude/settings.json` with exactly this content (merge the `hooks` and `env` keys if the file already exists):\n\n   ```json\n   {\n     \"env\": {\n       \"PROJECT_ISSUE_ASSIGNEE\": \"self\"\n     },\n     \"hooks\": {\n       \"PreToolUse\": [\n         {\n           \"matcher\": \"Bash\",\n           \"hooks\": [\n             {\n               \"type\": \"command\",\n               \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"/.claude/hooks/git-guard.sh\"\n             }\n           ]\n         }\n       ]\n     }\n   }\n   ```\n\n2. Create `.claude/hooks/git-guard.sh` with exactly this content, then `chmod +x .claude/hooks/git-guard.sh`:\n\n   ```bash\n   #!/bin/bash\n   # .claude/hooks/git-guard.sh — PreToolUse hook for the Bash tool.\n   # Distilled from a real global hook in ~/.claude/hooks/ — trimmed to the\n   # two moves that matter: deny with guidance, and allow with an injected\n   # instruction. Claude Code pipes the pending tool call to stdin as JSON.\n\n   INPUT=$(cat)\n   COMMAND=$(echo \"$INPUT\" | jq -r '.tool_input.command // empty')\n   SESSION=$(echo \"$INPUT\" | jq -r '.session_id // \"unknown\"')\n\n   # Force pushes: deny. The reason is delivered to the model INSTEAD of the\n   # push happening — same message, same moment as the pi git() override.\n   if echo \"$COMMAND\" | grep -qE 'git[[:space:]]+push.*[[:space:]](-f([[:space:]]|$)|--force)'; then\n     jq -n --arg reason \"[git-guard session=$SESSION] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\" '{\n       hookSpecificOutput: {\n         hookEventName: \"PreToolUse\",\n         permissionDecision: \"deny\",\n         permissionDecisionReason: $reason\n       }\n     }'\n     exit 0\n   fi\n\n   # Commits: allow, but attach a mandatory instruction at the moment of action\n   # (the real hook's pattern: every commit message must read like a prompt\n   # another agent could replay to recreate the work).\n   if echo \"$COMMAND\" | grep -qE '^[[:space:]]*git[[:space:]]+commit'; then\n     jq -n '{\n       hookSpecificOutput: {\n         hookEventName: \"PreToolUse\",\n         permissionDecision: \"allow\",\n         permissionDecisionReason: \"Git commit validated\",\n         additionalContext: \"ALL git commits should be a prompt so another agent can recreate this work. MANDATORY.\"\n       }\n     }'\n     exit 0\n   fi\n\n   exit 0\n   ```\n\n3. Success check (needs `jq`; no agent in the loop — this is the hook's stdin contract):\n\n   ```bash\n   echo '{\"session_id\":\"check-a\",\"tool_input\":{\"command\":\"git push --force origin main\"}}' \\\n     | .claude/hooks/git-guard.sh\n   ```\n\n   Expected: a JSON object whose `hookSpecificOutput.permissionDecision` is `\"deny\"` and whose reason starts with `[git-guard session=check-a] force push blocked.`. A `git commit` command instead yields `\"allow\"` plus an `additionalContext` instruction; any other command prints nothing.\n\n4. Context: the `env` map sets per-project env vars for every session; every hook receives `session_id` on stdin (key per-session state by it — the `PI_SESSION_ID` parallel); `SessionStart` hooks fire once per session to seed that state. The same settings shape in `~/.claude/settings.json` applies globally.\n\n### Codex (user-scoped — edits home config, so confirm with your user first)\n\nCodex runs agent commands in real non-interactive zsh shells (commonly the `zsh -lc` shape — login, not interactive), so overrides are plain function shadowing (an `rm()` function beats `/bin/rm`) and stderr reaches the model naturally — the policy functions from `.pi/agent-shell.zsh` above work verbatim in any file the guard below sources. Note the boundary: plain Codex does not automatically receive your zsh helper/function surface, and `CODEX_LOAD_ZSH_DSL` below is a local marker this setup invented, not a Codex built-in — Codex only injects the variable; zsh startup rules decide what it means. Field rule: missing PATH is not permission to pour `.zshrc` into Codex — never fix a missing tool or helper by sourcing the full interactive `.zshrc` into agent shells.\n\n1. Append this block to the user's `.zshenv` (`~/.zshenv`, or `$ZDOTDIR/.zshenv` if their zsh config lives elsewhere), replacing the sourced files with the function files they want agent shells to load:\n\n   ```zsh\n   # zshenv-agent-guard.zsh — append this block to your .zshenv\n   # (~/.zshenv, or $ZDOTDIR/.zshenv if your zsh config lives elsewhere).\n   #\n   # Codex agent commands run in real, NON-interactive zsh shells — and zsh\n   # sources .zshenv for every shell it starts. This guard loads agent-facing\n   # functions ONLY when the launch opted in (CODEX_LOAD_ZSH_DSL is set) and\n   # the shell is non-interactive, so your human terminals never see any of it.\n   if [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" && ! -o interactive ]]; then\n     # Base env/paths for agent shells first, then any function files you want\n     # every Codex shell to have — command overrides included.\n     [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n     [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n     [[ -r \"$ZDOTDIR/conf.d/60-git-dsl.zsh\" ]] && source \"$ZDOTDIR/conf.d/60-git-dsl.zsh\"\n   fi\n   ```\n\n2. Opt in per launch:\n\n   ```bash\n   codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n   ```\n\n   Or permanently, by appending to `~/.codex/config.toml` (merge if `[shell_environment_policy]` already exists):\n\n   ```toml\n   [shell_environment_policy]\n   inherit = \"all\"\n\n   [shell_environment_policy.set]\n   CODEX_LOAD_ZSH_DSL = \"1\"\n   # ...plus any per-machine value your agent-shell functions need, e.g.:\n   # MY_KEY_HELPER = \"~/.config/zsh/bin/my-key-helper\"\n   ```\n\n3. Success check — simulate what Codex does (non-interactive zsh with the env var set), using one function name defined in a file the guard sources (replace `<your-function>`):\n\n   ```bash\n   CODEX_LOAD_ZSH_DSL=1 zsh -c 'whence -w <your-function>'\n   zsh -c 'whence -w <your-function>'\n   ```\n\n   Expected: the first command prints `<your-function>: function`; the second prints nothing useful (exit 1), proving the guard only fires when opted in.\n\n4. Gotcha (from a prior session's refactor of this exact setup): zsh functions are not inherited by child shells, so any \"already sourced\" guard inside the files you load must be shell-local (`typeset -g`), not an exported env var — otherwise nested shells inherit the marker but not the functions.\n\n#### Optional clean rebuild: the Agent Setup Prompt\n\nThe guard above is the live \"append to what you have\" version: everything, agent-safe base env included, waits behind the `CODEX_LOAD_ZSH_DSL` valve in `.zshenv`. The refined layout from a prior Codex workshop is structured differently: `~/.zshenv` shrinks to one line setting `ZDOTDIR`; `$ZDOTDIR/.zprofile` becomes the login-shell bridge (`zsh -lc` is login but NOT interactive, so `.zprofile` runs for agent shells while `.zshrc` never does); the agent-safe base (`codex-env.zsh` marking `CODEX_AGENT_ENV_SOURCED=1`, deterministic PATH in `conf.d/00-path.zsh`, reviewed `local.zsh`) loads on every login shell; and `CODEX_LOAD_ZSH_DSL` gates only the extra helper/function files. To build that clean layout, run this prompt verbatim (do not run it on top of step 1's guard without reconciling — they are two versions of the same airlock):\n\n```text\nSet up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells.\n\nStep 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nDo not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables.\n\nStep 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as:\n\n    export ZDOTDIR=\"${ZDOTDIR:-$HOME/.config/zsh}\"\n\nVerify:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; test -d \"$ZDOTDIR\" && echo \"ZDOTDIR exists\" || echo \"ZDOTDIR missing\"'\n\nStep 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides.\n\nUse this shape, adjusted to the existing files:\n\n    [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n    [[ -r \"$ZDOTDIR/conf.d/00-path.zsh\" ]] && source \"$ZDOTDIR/conf.d/00-path.zsh\"\n    [[ -r \"$ZDOTDIR/local.zsh\" ]] && source \"$ZDOTDIR/local.zsh\"\n\nStep 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded:\n\n    export CODEX_AGENT_ENV_SOURCED=1\n\nDo not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here.\n\nStep 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins.\n\nVerify PATH order:\n\n    zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n\nVerify executable resolution:\n\n    zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n\nStep 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints.\n\nStep 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup.\n\nStep 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`.\n\nAdd this in the agent-safe startup path after `ZDOTDIR` is available:\n\n    if [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n      [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n    fi\n\nVerify the marker is absent by default:\n\n    zsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n\nVerify selected helper loading when requested:\n\n    CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nStep 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers:\n\n    xi() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n    }\n\n    x() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\n    e() {\n      codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\nOnly add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL:\n\n    [shell_environment_policy.set]\n    CODEX_LOAD_ZSH_DSL = \"1\"\n\nOtherwise, keep the marker out of global config and use the wrappers.\n\nVerify wrapper policy wiring:\n\n    zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true\n    rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n\nStep 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state.\n\n    zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\n    env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\nExpected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed.\n\nStep 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`.\n\nStep 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`.\n```\n\n#### Verification (either version)\n\n```bash\nzsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\nenv -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n```\n\nExpected for the clean layout: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` pointing at the intended config directory, required tools printing real paths, and no secret values printed. The first command should print an empty marker by default; the clean-shell (`env -u`) check guards against being fooled by inherited marker state. (Step 1's `.zshenv` guard version does not set `CODEX_AGENT_ENV_SOURCED`; for it, use the `whence -w <your-function>` check from step 3 instead.)\n\n## Notes for agents\n\n- Instruction-once state persists in `${TMPDIR:-/tmp}/pi-command-instructions/<session-id>/` across runs. If the first `ls` does NOT print the briefing, a marker from an earlier run exists — remove it with the `command rm -rf` line above (change `check-a` to the session id you used) and retry.\n- `command rm`, `command git`, etc. bypass the overrides by design. This setup is guidance the agent reads at the moment it acts, not a security boundary. Anything that must never happen belongs in Pi's hooks/permissions, not here.\n- Without the extension, `pi_session_id` falls back to `process-$PPID`, which is stable per shell process rather than per conversation — the overrides still work, but \"once per session\" becomes \"once per shell parent\".\n- If overrides don't fire inside Pi, the usual cause is that the user has not trusted `.pi/settings.json` yet, so the prefix is never prepended.\n- The `linear` override rewrites only `linear issue create`; every other `linear` subcommand passes through untouched. Set `PI_LINEAR_OVERRIDE_DRY_RUN=1` to print the rewritten argv instead of calling the real CLI.\n- Full explanation, prompt library, and caveats: https://polite-ravine-6v8g.here.now/\n- For your user (human-readable presentation pages): an annotated replay of the session that built this setup at https://polite-ravine-6v8g.here.now/replay.html, and a Q&A walkthrough at https://polite-ravine-6v8g.here.now/dialogue.html. Both carry the complete `.pi/agent-shell.zsh`."
    },
    {
      "id": "factory-environment-policy-questions",
      "slug": "environment-policy-questions",
      "title": "Policy at the agent’s execution boundary — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Execution",
      "tags": [
        "environment-policy",
        "questions"
      ],
      "sources": [
        {
          "label": "Policy at the agent’s execution boundary — questions and tradeoffs",
          "url": "https://polite-ravine-6v8g.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "01-env/dialogue.html#The questions"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 1875,
      "url": "/topics/factory-environment-policy-questions/",
      "markdownUrl": "/markdown/factory-environment-policy-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy-questions.json",
      "headings": [
        {
          "id": "the-questions",
          "text": "The questions",
          "level": 2
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The questions\n\nI already tell my agent \"never force push\" in CLAUDE.md. Why isn't that enough?\n\nBecause that rule is something the model read once, maybe forty thousand tokens ago. An override is a message to the model at the exact moment it acts — it lands in the agent's tool output in the same turn as the blocked action:\n\n``` text\n▶ [session session-A] $ git push --force origin main\n  [git-override session=session-A] force push blocked. Ask the user to run it\n  themselves, or explain why history must be rewritten and wait for approval.\n```\n\nIf you can see that line in the transcript, the agent saw it too. It reads the guidance and changes course immediately — no hoping it remembered.\n\nHow much machinery does that take?\n\nTwo files in `.pi/`. The first is a settings file that tells Pi to source a zsh file before every command the agent runs:\n\n``` text\n{\n  \"shellPath\": \"/bin/zsh\",\n  \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n}\n```\n\nThe second is that zsh file. A zsh function shadows the command of the same name — so `rm`, `git`, `linear`, and `ls` become yours to shape. No plugin API, no magic.\n\nSo it's a sandbox? The agent physically can't delete my files?\n\nNo — and the overrides say so in their own stderr. `command rm` and `command git` bypass the functions by design. This is guidance with teeth, not a security boundary:\n\n``` text\n▶ [session session-A] $ rm .demo-state/playground/important.txt\n  [rm-override session=session-A] quarantined 1 item(s) in\n  <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.\n  [rm-override] restore with: mv \"<quarantine>/<name>\" <dest>. Real deletion\n  requires 'command rm' and explicit user approval.\n```\n\nThe decision rule: use overrides to **steer** — redirect destructive commands, inject policy, brief the model. Use Pi's hooks and permission system to **enforce** anything you can't afford to have bypassed.\n\nPi spawns a fresh shell for every command. How does \"tell the agent this once per conversation\" remember anything?\n\nNot with shell variables — those die with each shell. State lives on disk, keyed by conversation. The pi-session-id extension (~44 lines of TypeScript) exports the active conversation ID as `PI_SESSION_ID` into every shell, and then \"once\" is a single atomic `mkdir`:\n\n``` text\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n```\n\nThe first `ls` of a session returns instructions addressed to the AI; every later `ls` runs normally. The ID is validated against Pi's session-ID syntax before it touches shell source — an invalid value blocks the call rather than permitting injection.\n\nWhat happens when I hit /new or /fork — do I inherit stale \"already briefed\" state?\n\nNo, and that's exactly why the session ID matters. State is keyed per conversation, so each `/new`, `/fork`, and parallel Pi process gets its own \"first time\". From the captured harness run:\n\n``` text\n▶ [session session-B] $ ls demo\n  INSTRUCTIONS FOR THE AI:\n  This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\n  Deletions are quarantined, force pushes are blocked, and Linear issues are\n  always self-assigned. Run ls again to execute the command normally.\n```\n\nSession-A had already been briefed; session-B sees the briefing again. Without the extension, the fallback is `process-$PPID` — stable per shell process, not per conversation.\n\nRewriting the agent's commands feels invasive. What does the `linear` override actually change?\n\nOne subcommand, one flag. Only `linear issue create` is touched: whatever assignee the agent passed is dropped and `--assignee self` is appended — and the rewrite is announced on stderr so the agent knows policy fired:\n\n``` text\n▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else\n  [linear-override session=session-A] enforcing --assignee self\n  [linear-override dry-run] command linear issue create --title Fix\\ login\\ bug --assignee self\n```\n\nEvery other `linear` subcommand passes through untouched. It's adapted from a working policy in a real test project — the point is the override owns the team rule, not the agent's memory of it.\n\nHow do I trust any of this before an agent depends on it mid-session?\n\nRun it the way Pi does — fresh zsh, prefix sourced, `PI_SESSION_ID` set — with no agent in the loop. Four lines from your project root:\n\n``` text\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'\n```\n\nFirst `ls` prints the briefing, second prints your normal listing, and the force push is refused with exit code 1. This project also ships `demo/run-demo.sh`, a five-act harness version of the same idea — an override you've never executed is a guess.\n\nDoes this only work in pi? I'm in Claude Code half the day and Codex the other half.\n\nThe mechanism is pi's; the move isn't. Every agent has a seam where its actions pass through, and all three give you a way to speak to the model right there. Codex agent shells are real non-interactive zsh — plain `codex` doesn't automatically receive your zsh helper/function surface, but a guard in your `.zshenv` can source chosen function files into agent shells that opt in. Same plain function shadowing as this page, stderr included. The opt-in is one env var — a local marker this setup invented, not a Codex built-in:\n\n``` text\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n```\n\nClaude Code's seam is the tool call instead of the shell: a `PreToolUse` hook on `Bash` can deny a force push and hand the model the same \"force push blocked\" guidance this page's `git()` override prints — delivered before the command ever runs, with `session_id` arriving on the hook's stdin to play the `PI_SESSION_ID` role. In all three agents, the override's output at the moment of action IS the message to the model. The liftable files for both are in the [cross-agent section of the guide](https://polite-ravine-6v8g.here.now/index.html#same-trick-in-claude-code-and-codex).\n\nIf Codex just runs zsh, why not source my whole .zshrc into its shells and be done with it?\n\nBecause most of `.zshrc` exists for a human at a prompt — prompt setup, completions, keybindings, fuzzy finders — and in a non-interactive agent shell that machinery can slow, hang, or spam every single command the agent runs. Treat startup as an airlock: `.zshrc` stays sealed, a narrow agent-safe path carries PATH and non-secret env, and the marker is the valve that admits chosen helper files. The field rule: **missing PATH is not permission to pour `.zshrc` into Codex.** A missing tool means you fix the agent-safe path; a missing helper means you opt it in behind the valve. The guide's cross-agent section carries a complete agent setup prompt that builds the clean layout end to end.\n\nFine — just give me the file.\n\nHere's `.pi/agent-shell.zsh`, complete. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own — anything on PATH is fair game:\n\n``` text\n# .pi/agent-shell.zsh\n#\n# Sourced before EVERY shell command the agent runs, via .pi/settings.json:\n#\n#   { \"shellPath\": \"/bin/zsh\",\n#     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\" }\n#\n# Pi spawns a fresh shell per command, so plain shell variables can't carry\n# state between commands. The pi-session-id extension\n# (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into\n# each of those shells, which lets these overrides keep per-conversation state\n# on disk — e.g. \"show this instruction once per session\".\n\npi_session_id() {\n  print -r -- \"${PI_SESSION_ID:-process-$PPID}\"\n}\n\n# Emit a heredoc the FIRST time a command runs in this session, then get out\n# of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,\n# and parallel Pi processes each get their own \"first time\".\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n\n# --- rm: quarantine instead of delete --------------------------------------\n# The agent never permanently deletes anything. Targets move to a\n# session-scoped quarantine dir; the notice tells the agent how to restore.\nrm() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local quarantine=\"${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id\"\n  local -a targets\n  local arg\n  for arg in \"$@\"; do\n    [[ \"$arg\" == -* ]] || targets+=(\"$arg\")\n  done\n\n  if (( ${#targets} == 0 )); then\n    command rm \"$@\"\n    return\n  fi\n\n  mkdir -p \"$quarantine\" || return 1\n  local moved=0 target\n  for target in \"${targets[@]}\"; do\n    if [[ -e \"$target\" || -L \"$target\" ]]; then\n      mv -- \"$target\" \"$quarantine/\" && (( moved++ ))\n    else\n      print -u2 -- \"[rm-override] no such file: $target\"\n    fi\n  done\n  print -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\n  print -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n}\n\n# --- git: block destructive operations --------------------------------------\n# Force pushes and hard resets fail loudly with guidance instead of running.\ngit() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local arg\n\n  if [[ \"$1\" == \"push\" ]]; then\n    for arg in \"$@\"; do\n      case \"$arg\" in\n        -f|--force|--force-with-lease|--force-if-includes)\n          print -u2 -- \"[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\"\n          return 1\n          ;;\n      esac\n    done\n  fi\n\n  if [[ \"$1\" == \"reset\" ]]; then\n    for arg in \"$@\"; do\n      if [[ \"$arg\" == \"--hard\" ]]; then\n        print -u2 -- \"[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable.\"\n        return 1\n      fi\n    done\n  fi\n\n  command git \"$@\"\n}\n\n# --- linear: enforce team policy on issue creation --------------------------\n# Adapted from a real override in ~/dev/pi-session-test: every issue the agent\n# creates is assigned to the current user, no matter what flags it passed.\nlinear() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n\n  if [[ \"$1\" != \"issue\" || \"$2\" != \"create\" ]]; then\n    command linear \"$@\"\n    return\n  fi\n\n  local -a decorated\n  local skip=0 arg\n  for arg in \"$@\"; do\n    if (( skip )); then skip=0; continue; fi\n    case \"$arg\" in\n      -a|--assignee) skip=1 ;;\n      -a=*|--assignee=*) ;;\n      *) decorated+=(\"$arg\") ;;\n    esac\n  done\n  decorated+=(--assignee self)\n\n  print -u2 -- \"[linear-override session=$session_id] enforcing --assignee self\"\n\n  if [[ -n \"${PI_LINEAR_OVERRIDE_DRY_RUN:-}\" ]]; then\n    print -n -- \"[linear-override dry-run] command linear\"\n    for arg in \"${decorated[@]}\"; do printf ' %q' \"$arg\"; done\n    print\n    return 0\n  fi\n\n  command linear \"${decorated[@]}\"\n}\n\n# --- ls: teach the agent, once per conversation ------------------------------\n# The pattern from the pi-session-id README: the first `ls` of a session\n# returns instructions to the model instead of output; every later `ls` runs\n# normally. Swap the message for anything you want the agent told exactly once.\nls() {\n  if pi_instruction_once ls <<'INSTRUCTIONS'; then\nINSTRUCTIONS FOR THE AI:\nThis project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\nDeletions are quarantined, force pushes are blocked, and Linear issues are\nalways self-assigned. Run ls again to execute the command normally.\nINSTRUCTIONS\n    return 0\n  fi\n\n  command ls \"$@\"\n}\n```\n\nWant your agent to do the whole setup? Paste this into it:\n\n``` text\nFetch https://polite-ravine-6v8g.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```"
    },
    {
      "id": "factory-environment-policy-reference-patterns",
      "slug": "environment-policy-reference-patterns",
      "title": "Policy at the agent’s execution boundary — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Execution",
      "tags": [
        "environment-policy",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://polite-ravine-6v8g.here.now/"
        }
      ],
      "sourceUnits": [
        "01-env/folio/index.html#Abstract",
        "01-env/folio/index.html#Notice where your policy actually runs",
        "01-env/folio/index.html#Explain the two files that rewire every command",
        "01-env/folio/index.html#Compare stateless guardrails with session-scoped memory",
        "01-env/folio/index.html#Test the overrides before an agent depends on them",
        "01-env/folio/index.html#Choose guidance with teeth, not a sandbox",
        "01-env/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 1771,
      "url": "/topics/factory-environment-policy-reference-patterns/",
      "markdownUrl": "/markdown/factory-environment-policy-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-where-your-policy-actually-runs",
          "text": "Notice where your policy actually runs",
          "level": 2
        },
        {
          "id": "explain-the-two-files-that-rewire-every-command",
          "text": "Explain the two files that rewire every command",
          "level": 2
        },
        {
          "id": "compare-stateless-guardrails-with-session-scoped-memory",
          "text": "Compare stateless guardrails with session-scoped memory",
          "level": 2
        },
        {
          "id": "test-the-overrides-before-an-agent-depends-on-them",
          "text": "Test the overrides before an agent depends on them",
          "level": 2
        },
        {
          "id": "choose-guidance-with-teeth-not-a-sandbox",
          "text": "Choose guidance with teeth, not a sandbox",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nAgents act through the shell, so the shell is the highest-leverage place to encode project policy. Pi runs every agent command in a fresh shell and lets a trusted project prepend a `shellCommandPrefix`, which makes one sourced zsh file a checkpoint for everything the agent executes. Stateless overrides can block a force push today; the pi-session-id extension adds a conversation-scoped key, `PI_SESSION_ID`, so overrides can also keep per-session state such as first-run instructions. The evidence here is the project's own override file and a captured transcript from a harness that reproduces Pi's execution model. The limit is equally concrete: these overrides are guidance the agent reads at the moment it acts, not a sandbox, and `command rm` walks straight past them.\n\n## Notice where your policy actually runs\n\nYou have probably written rules for your agent in a CLAUDE.md or AGENTS.md file: never force push, never hard-delete, always assign issues to yourself. Then, forty thousand tokens into a session, the agent runs `rm -rf` anyway. The mistake is treating instructions the model read once as if they control actions it takes much later.\n\nEvery file deletion, push, and issue the agent creates passes through one place: the shell. A message printed by the shell arrives at the exact moment the agent acts, while a static instruction competes with everything else in context. That timing difference is the whole trick, and it is an editorial inference this page then tests against a captured transcript (S5). [1](https://polite-ravine-6v8g.here.now/#note-1)\n\n1\\. The workshop agenda (S6) frames this section as demoing the pi-session-id project and “overriding rm, linear, git, and other behavior.” The agenda also notes that hooks remain the tool for maximum control — a boundary section 5 returns to. [↩](https://polite-ravine-6v8g.here.now/#note-ref-1)\n\nWatch for the signal as you read: every override in this project prints a tagged line such as `[git-override session=…]` to stderr. If you can see that line in the agent's tool output, the agent saw it too — and can change course in the same turn.\n\n## Explain the two files that rewire every command\n\nThe entire mechanism is two files checked into the project. The first is `.pi/settings.json`, which tells Pi which shell to use and what to run before every command:\n\n``` text\n{\n  \"shellPath\": \"/bin/zsh\",\n  \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n}\n```\n\n**Figure 1.** The project's complete `.pi/settings.json` (S3), byte-identical to the file in the demo project. Source evidence, not a derived display.\n\nThe second file, `.pi/agent-shell.zsh`, is plain zsh. Because Pi sources it before each command, any function defined there shadows the command of the same name. The pi-session-id README (S1) documents exactly this pattern: a project sources a function file through trusted `.pi/settings.json`, and `PI_SESSION_ID` is already present in the child environment before the prefix runs. [2](https://polite-ravine-6v8g.here.now/#note-2)\n\n2\\. “Trusted” matters: Pi asks you to approve a project's settings before it will run a prefix from them. An override file executes with your full permissions, so read it the way you would read a shell script from the internet — because it is one. [↩](https://polite-ravine-6v8g.here.now/#note-ref-2)\n\n**Working definition.** On this page, an override is a zsh function that shadows a command name for the agent's shell. The real binary stays reachable through `command rm`, `command git`, and so on. This is a convention for this page, not a term from the sources.\n\nThis project ships four overrides (S3): `rm` moves targets to a session-scoped quarantine instead of deleting them; `git` blocks `push --force` and `reset --hard` with guidance; `linear` rewrites `issue create` so the issue is always self-assigned; and `ls` delivers a one-time briefing. The `linear` override is adapted from a working policy file in a sibling test project (S4), where every issue an agent creates is forced to `--assignee self` regardless of the flags it passed.\n\n## Compare stateless guardrails with session-scoped memory\n\nHere is the fork in the road when you write your own override. Pi spawns a fresh shell process for every command, so a shell variable set during one command is gone by the next. Blocking a force push needs no memory — the evidence is in the argv right in front of you. But “tell the agent this once, then get out of the way” needs state that survives across those throwaway shells.\n\nStoring that state under a fixed path fails in a specific way: `/new`, `/resume`, `/fork`, and a second Pi process would all share one “first time.” The pi-session-id extension (S1, S2) solves this by exporting the active conversation ID as `PI_SESSION_ID` into each shell, synchronizing it on `session_start`, on human `!` commands, and on every model `bash` tool call, then clearing it on shutdown. [3](https://polite-ravine-6v8g.here.now/#note-3)\n\n3\\. The extension (S2) is about 44 lines of TypeScript. It validates the session ID against Pi's allowed syntax before inserting it into shell source; an invalid value blocks the tool call rather than permitting injection (S1). [↩](https://polite-ravine-6v8g.here.now/#note-ref-3)\n\nWith that key available, per-conversation state is a directory name. The helper below creates a marker directory the first time a command runs in a session and emits its heredoc only then; the `ls` override uses it to brief the model once:\n\n``` text\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n\nls() {\n  if pi_instruction_once ls <<'INSTRUCTIONS'; then\nINSTRUCTIONS FOR THE AI:\nThis project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\nDeletions are quarantined, force pushes are blocked, and Linear issues are\nalways self-assigned. Run ls again to execute the command normally.\nINSTRUCTIONS\n    return 0\n  fi\n\n  command ls \"$@\"\n}\n```\n\n**Figure 2.** The instruction-once helper and `ls` override from this project's `.pi/agent-shell.zsh` (S3), following the pattern published in the pi-session-id README (S1). Source evidence.\n\nThe decision rule when you write your own: if the override can judge the command from its arguments alone, keep it stateless. Reach for `PI_SESSION_ID` only when the behavior must differ between the first occurrence in a conversation and every later one.\n\n## Test the overrides before an agent depends on them\n\nAn override you have never executed is a guess. The tempting shortcut is to install everything and find out mid-session, when a broken function makes every agent command fail. This project instead ships a harness, `demo/run-demo.sh`, that reproduces how Pi runs agent commands — a fresh zsh per command, the prefix sourced, `PI_SESSION_ID` set — so you can watch each override fire without Pi in the loop.\n\n``` text\n▶ [session session-A] $ ls demo\n  INSTRUCTIONS FOR THE AI:\n  This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. …\n\n▶ [session session-A] $ ls demo\n  run-demo.sh\n\n▶ [session session-A] $ rm .demo-state/playground/important.txt\n  [rm-override session=session-A] quarantined 1 item(s) in\n  <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.\n\n▶ [session session-A] $ git push --force origin main\n  [git-override session=session-A] force push blocked. Ask the user to run it\n  themselves, or explain why history must be rewritten and wait for approval.\n\n▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else\n  [linear-override session=session-A] enforcing --assignee self\n  [linear-override dry-run] command linear issue create --title Fix\\ login\\ bug --assignee self\n\n▶ [session session-B] $ ls demo\n  INSTRUCTIONS FOR THE AI: …\n```\n\n**Figure 3.** Excerpt from the captured harness transcript (S5), reorganized for length: long lines are wrapped, repeated instruction text is elided with `…`, and the project's absolute path is shortened to `<project>`. A derived display of source output.\n\n**Evidence limit** This transcript comes from the harness, not from a live Pi session, and the `linear` call ran with a dry-run flag that prints the rewritten argv instead of hitting the Linear API. It demonstrates the shell functions faithfully; it does not by itself prove Pi's trust flow or the extension's lifecycle hooks, which the sources document separately (S1, S2).\n\nRead the transcript against the claims. First `ls`: instructions to the model. Second `ls`: normal output — the marker directory did its job. The quarantined file is listed, not gone. The force push never executed. The Linear issue lost its `--assignee someone-else` and gained `--assignee self`. And session-B sees the briefing again, because state is keyed by conversation. If you run the harness and any act differs, fix the override before letting an agent near it.\n\n## Choose guidance with teeth, not a sandbox\n\nThe last judgment call is what to trust these overrides *for*. The weak position treats them as a security boundary. The strong position treats them as high-signal steering: messages delivered at the moment of action that a cooperative agent reads and obeys.\n\nThe coverage limits are documented, not hypothetical. The pi-session-id README (S1) lists what the mechanism does not cover: extension-internal `pi.exec()` calls, custom tools that spawn processes directly, and commands that clear their environment with `env -i` or `unset PI_SESSION_ID`. And within the shell itself, `command rm` bypasses the function by design — the overrides in this project even say so in their own stderr output (S3).\n\n**Evidence limit** Nothing here measures how often an agent complies with override guidance versus routing around it. The sources support the mechanism and its coverage, not a compliance rate. Treat “the agent self-corrects” as behavior to observe in your own sessions, not a guarantee.\n\nThe decision rule: use shell overrides to **steer** — redirect destructive commands, inject policy, brief the model — and use Pi's hooks and permission system to **enforce** anything you cannot afford to have bypassed. If violating the rule merely wastes a turn, an override is enough. If violating it loses data or pushes broken history, put a real control behind the override's friendly message.\n\n## Practical action\n\nTo give one of your own projects a custom agent environment, in order:\n\n1.  Install the extension: `pi install git:github.com/johnlindquist/pi-session-id` (S1).\n2.  Copy the two files from this demo project: `.pi/settings.json` and `.pi/agent-shell.zsh`.\n3.  Replace the demo overrides with your policy. Keep each function's stderr message short, tagged, and addressed to the agent, and always leave the `command <name>` escape hatch documented.\n4.  Test with a harness before trusting: run each override in a fresh `zsh -c` with `PI_SESSION_ID` set, twice, under two session IDs. Your feedback signal is the tagged stderr line and, for stateful overrides, different behavior on the first and second run.\n5.  Open the project in Pi, approve the settings when prompted, and ask the agent to do something an override guards. If the agent reads the message and adjusts, the loop works; if it bypasses, move that rule into hooks or permissions."
    },
    {
      "id": "factory-environment-policy-worked-example",
      "slug": "environment-policy-worked-example",
      "title": "Policy at the agent’s execution boundary — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Execution",
      "tags": [
        "environment-policy",
        "examples"
      ],
      "sources": [
        {
          "label": "Policy at the agent’s execution boundary — worked example",
          "url": "https://polite-ravine-6v8g.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "01-env/replay.html#The session"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 1688,
      "url": "/topics/factory-environment-policy-worked-example/",
      "markdownUrl": "/markdown/factory-environment-policy-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-environment-policy-worked-example.json",
      "headings": [
        {
          "id": "the-session",
          "text": "The session",
          "level": 2
        }
      ],
      "markdown": "# Policy at the agent’s execution boundary — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\nYou\n\nPi runs every shell command my agent executes. I want a project-local hook that runs before each one — override `rm`, `git`, and friends for this project without touching my global zshrc.\n\nAgent\n\nPi has exactly that hook: `shellCommandPrefix` in the project's `.pi/settings.json`. It prepends a snippet to every command the agent runs. Pointing it at a sourced zsh file makes every function in that file shadow the command of the same name:\n\n``` text\n{\n  \"shellPath\": \"/bin/zsh\",\n  \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n}\n```\n\nThe whole integration is two JSON keys. Everything after this beat is plain zsh — no plugin API to learn, and the real binaries stay reachable via `command rm`, `command git`.\n\nYou\n\nStart with `rm`. The agent should never permanently delete anything — move targets somewhere recoverable, and tell the agent what happened and how to undo it.\n\nAgent\n\nAdded `rm()` to a new `.pi/agent-shell.zsh`. Targets move to a session-scoped quarantine dir, and both notices print to stderr, addressed to the model:\n\n``` text\nprint -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\nprint -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n```\n\nThose two stderr lines are the whole design: a message to the model at the moment it acts, not a rule it read forty thousand tokens ago. If you can see the line in the transcript, the agent saw it too.\n\nYou\n\nSame idea for `git`: block `push --force` and `reset --hard`, and make the failure message tell the agent what to do instead.\n\nAgent\n\nDone — the override inspects argv and refuses with guidance before real git ever runs. From the captured harness transcript:\n\n``` text\n▶ [session session-A] $ git push --force origin main\n  [git-override session=session-A] force push blocked. Ask the user to run it\n  themselves, or explain why history must be rewritten and wait for approval.\n\n▶ [session session-A] $ git reset --hard HEAD~3\n  [git-override session=session-A] 'git reset --hard' blocked. Prefer 'git stash'\n  or 'git restore <path>' so work is recoverable.\n```\n\nExit code 1, nothing pushed, and the agent gets a next step it can act on in the same turn. `command git` still bypasses it — this is guidance with teeth, not a sandbox.\n\nYou\n\nNow a real team policy: every Linear issue the agent files gets assigned to me. Rewrite `linear issue create` so `--assignee self` is enforced no matter what flags the agent passed.\n\nAgent\n\nThe override strips any assignee the agent chose and appends `--assignee self`, announcing the rewrite on stderr. Dry-run mode prints the final argv:\n\n``` text\n▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else\n  [linear-override session=session-A] enforcing --assignee self\n  [linear-override dry-run] command linear issue create --title Fix\\ login\\ bug --assignee self\n```\n\nAdapted from a working policy in a private test project. It rewrites only `issue create`; every other `linear` subcommand passes through untouched.\n\nYou\n\nThe tricky one: brief the model exactly once per conversation. The first `ls` should return instructions to the AI; every later `ls` runs normally. But Pi spawns a fresh shell per command — where does \"once\" live?\n\nAgent\n\nNot in shell variables — a fresh shell forgets everything. State has to live on disk, keyed by the *conversation*, or `/new` and `/fork` would inherit a stale \"already briefed\" flag. Installed the pi-session-id extension (`pi install git:github.com/johnlindquist/pi-session-id`), which exports `PI_SESSION_ID` into every shell Pi spawns. With that key, \"once per session\" is one atomic `mkdir`:\n\n``` text\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n```\n\n`mkdir` succeeds exactly once per marker path, so \"first time\" is race-free even with parallel Pi processes. The extension itself is ~44 lines of TypeScript syncing the session ID on `session_start`, human `!` commands, and every model bash call — with the ID validated before it touches shell source.\n\nYou\n\nProve all of it without Pi in the loop. I want a harness that runs commands exactly the way Pi does, so a broken override never takes down a live session.\n\nAgent\n\nWrote `demo/run-demo.sh`: fresh zsh per command, prefix sourced, `PI_SESSION_ID` set — Pi's execution model, reproduced. Ran it; the captured transcript (checked in as `demo/sample-output.txt`):\n\n``` text\n▶ [session session-A] $ ls demo\n  INSTRUCTIONS FOR THE AI:\n  This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\n  Deletions are quarantined, force pushes are blocked, and Linear issues are\n  always self-assigned. Run ls again to execute the command normally.\n\n▶ [session session-A] $ ls demo\n  run-demo.sh\n  sample-output.txt\n\n▶ [session session-A] $ rm .demo-state/playground/important.txt\n  [rm-override session=session-A] quarantined 1 item(s) in\n  <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.\n\n▶ [session session-A] $ ls .demo-state/tmp/pi-rm-quarantine/session-A\n  important.txt\n\n▶ [session session-B] $ ls demo\n  INSTRUCTIONS FOR THE AI: …\n```\n\nThe beat that matters most is the last one: session-B sees the briefing again. State is keyed per conversation, not per machine — `/new` and `/fork` each get their own \"first time\".\n\nYou\n\nLand it. Give me the whole override file so I can lift it into any project.\n\nAgent\n\nHere is `.pi/agent-shell.zsh`, complete — the section's money artifact. Keep `pi_session_id` and `pi_instruction_once` as-is; swap the four policy functions for your own:\n\n``` text\n# .pi/agent-shell.zsh\n#\n# Sourced before EVERY shell command the agent runs, via .pi/settings.json:\n#\n#   { \"shellPath\": \"/bin/zsh\",\n#     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\" }\n#\n# Pi spawns a fresh shell per command, so plain shell variables can't carry\n# state between commands. The pi-session-id extension\n# (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into\n# each of those shells, which lets these overrides keep per-conversation state\n# on disk — e.g. \"show this instruction once per session\".\n\npi_session_id() {\n  print -r -- \"${PI_SESSION_ID:-process-$PPID}\"\n}\n\n# Emit a heredoc the FIRST time a command runs in this session, then get out\n# of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,\n# and parallel Pi processes each get their own \"first time\".\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n\n# --- rm: quarantine instead of delete --------------------------------------\n# The agent never permanently deletes anything. Targets move to a\n# session-scoped quarantine dir; the notice tells the agent how to restore.\nrm() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local quarantine=\"${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id\"\n  local -a targets\n  local arg\n  for arg in \"$@\"; do\n    [[ \"$arg\" == -* ]] || targets+=(\"$arg\")\n  done\n\n  if (( ${#targets} == 0 )); then\n    command rm \"$@\"\n    return\n  fi\n\n  mkdir -p \"$quarantine\" || return 1\n  local moved=0 target\n  for target in \"${targets[@]}\"; do\n    if [[ -e \"$target\" || -L \"$target\" ]]; then\n      mv -- \"$target\" \"$quarantine/\" && (( moved++ ))\n    else\n      print -u2 -- \"[rm-override] no such file: $target\"\n    fi\n  done\n  print -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\n  print -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n}\n\n# --- git: block destructive operations --------------------------------------\n# Force pushes and hard resets fail loudly with guidance instead of running.\ngit() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local arg\n\n  if [[ \"$1\" == \"push\" ]]; then\n    for arg in \"$@\"; do\n      case \"$arg\" in\n        -f|--force|--force-with-lease|--force-if-includes)\n          print -u2 -- \"[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval.\"\n          return 1\n          ;;\n      esac\n    done\n  fi\n\n  if [[ \"$1\" == \"reset\" ]]; then\n    for arg in \"$@\"; do\n      if [[ \"$arg\" == \"--hard\" ]]; then\n        print -u2 -- \"[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable.\"\n        return 1\n      fi\n    done\n  fi\n\n  command git \"$@\"\n}\n\n# --- linear: enforce team policy on issue creation --------------------------\n# Adapted from a real override in ~/dev/pi-session-test: every issue the agent\n# creates is assigned to the current user, no matter what flags it passed.\nlinear() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n\n  if [[ \"$1\" != \"issue\" || \"$2\" != \"create\" ]]; then\n    command linear \"$@\"\n    return\n  fi\n\n  local -a decorated\n  local skip=0 arg\n  for arg in \"$@\"; do\n    if (( skip )); then skip=0; continue; fi\n    case \"$arg\" in\n      -a|--assignee) skip=1 ;;\n      -a=*|--assignee=*) ;;\n      *) decorated+=(\"$arg\") ;;\n    esac\n  done\n  decorated+=(--assignee self)\n\n  print -u2 -- \"[linear-override session=$session_id] enforcing --assignee self\"\n\n  if [[ -n \"${PI_LINEAR_OVERRIDE_DRY_RUN:-}\" ]]; then\n    print -n -- \"[linear-override dry-run] command linear\"\n    for arg in \"${decorated[@]}\"; do printf ' %q' \"$arg\"; done\n    print\n    return 0\n  fi\n\n  command linear \"${decorated[@]}\"\n}\n\n# --- ls: teach the agent, once per conversation ------------------------------\n# The pattern from the pi-session-id README: the first `ls` of a session\n# returns instructions to the model instead of output; every later `ls` runs\n# normally. Swap the message for anything you want the agent told exactly once.\nls() {\n  if pi_instruction_once ls <<'INSTRUCTIONS'; then\nINSTRUCTIONS FOR THE AI:\nThis project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\nDeletions are quarantined, force pushes are blocked, and Linear issues are\nalways self-assigned. Run ls again to execute the command normally.\nINSTRUCTIONS\n    return 0\n  fi\n\n  command ls \"$@\"\n}\n```\n\nVerified with the four-line success check — fresh zsh, two session ids, output matching the transcript above:\n\n``` text\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'\n```\n\nSeven beats: one settings hook, four overrides, one state trick, one harness. The same recipe generalizes to anything on PATH — wrap `npm` to enforce pnpm, wrap `curl` to log egress, wrap `pytest` to always add `-x`.\n\nRebuilt from a prior session using this project's real files: prompts are condensed, but every file shown matches disk byte-for-byte and every output line comes from the checked-in `demo/sample-output.txt` (project path replaced with `<project>`)."
    },
    {
      "id": "foundations-ralph-loop-playbook",
      "slug": "ralph-loop-playbook",
      "title": "Ralph Loop stop-hook continuation playbook",
      "summary": "Web developers already run agents against real repos, dev servers, browser panes, and local QA loops; the Ralph Loop helps those agents keep working toward a bounded goal instead of stopping after one polite assistant turn. It is especially useful for web tasks where success is observable only after code, tests, logs, and browser behavior line up.",
      "category": "Execution",
      "tags": [
        "hooks",
        "plugins",
        "Ralph loop",
        "compaction",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Official Codex Stop hook contract",
          "url": "https://developers.openai.com/codex/hooks#stop"
        },
        {
          "label": "Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-07.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#ralph-loop",
        "scenarios/ralph-loop.json#audienceFit",
        "toolkit/prompts/07-ralph-loop-stop-hook-prompt.md",
        "toolkit/codex-skills/ralph-loop-hook/SKILL.md",
        "scenarios/ralph-loop.json#scenarios/0",
        "scenarios/ralph-loop.json#scenarios/1",
        "scenarios/ralph-loop.json#scenarios/2",
        "scenarios/ralph-loop.json#implementationNotes",
        "scenarios/ralph-loop.json#notTaughtOrAvoid/2",
        "scenarios/ralph-loop.json#notTaughtOrAvoid/3",
        "scenarios/ralph-loop.json#notTaughtOrAvoid/4",
        "scenarios/ralph-loop.json#notTaughtOrAvoid/5",
        "scenarios/ralph-loop.json#agentReferences",
        "toolkit/bundles/code-better-plugins.md"
      ],
      "collection": "foundations",
      "categoryId": "execution",
      "wordCount": 3544,
      "url": "/topics/foundations-ralph-loop-playbook/",
      "markdownUrl": "/markdown/foundations-ralph-loop-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-ralph-loop-playbook.json",
      "headings": [
        {
          "id": "current-codex-stop-contract",
          "text": "Current Codex Stop contract",
          "level": 2
        },
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "keep-fixing-a-checkout-bug-until-browser-proof-passes",
          "text": "Keep fixing a checkout bug until browser proof passes",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "stop-hook-guard-for-visual-regression-cleanup",
          "text": "Stop-hook guard for visual regression cleanup",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "prototype-a-safe-ralph-loop-before-installing-it-globally",
          "text": "Prototype a safe Ralph Loop before installing it globally",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "validated-lesson-07-references",
          "text": "Validated lesson 07 references",
          "level": 3
        },
        {
          "id": "lesson-07-validation-notes",
          "text": "Lesson 07 validation notes",
          "level": 3
        },
        {
          "id": "existing-ralph-loop-prompt",
          "text": "Existing Ralph Loop prompt",
          "level": 3
        },
        {
          "id": "existing-ralph-loop-codex-skill",
          "text": "Existing Ralph Loop Codex skill",
          "level": 3
        },
        {
          "id": "verified-better-plugins-command-and-layout-notes",
          "text": "Verified Better Plugins command and layout notes",
          "level": 3
        },
        {
          "id": "cmux-cli-notes",
          "text": "CMUX CLI notes",
          "level": 3
        },
        {
          "id": "command-reference",
          "text": "Command reference",
          "level": 2
        },
        {
          "id": "enable-hooks-plugins-codex-config-toml",
          "text": "Enable hooks + plugins (~/.codex/config.toml)",
          "level": 2
        },
        {
          "id": "plugin-directory-layout-real",
          "text": "Plugin directory layout (real)",
          "level": 2
        },
        {
          "id": "manifest-example-plugins-gemini-video-codex-plugin-plugin-json-real",
          "text": "Manifest example (plugins/gemini-video/.codex-plugin/plugin.json — real)",
          "level": 2
        },
        {
          "id": "hooks-json-three-selected-lifecycle-events-from-the-source-plugin",
          "text": "hooks.json — three selected lifecycle events from the source plugin",
          "level": 2
        },
        {
          "id": "historical-hook-output-example",
          "text": "Historical hook-output example",
          "level": 2
        },
        {
          "id": "ralph-loop-taught-concept-lesson-07-08",
          "text": "Ralph Loop (taught concept, lesson 07/08)",
          "level": 2
        },
        {
          "id": "install-readme-real",
          "text": "Install (README, real)",
          "level": 2
        },
        {
          "id": "toolsmith-data-paths-real",
          "text": "Toolsmith data paths (real)",
          "level": 2
        }
      ],
      "markdown": "# Ralph Loop stop-hook continuation playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already run agents against real repos, dev servers, browser panes, and local QA loops; the Ralph Loop helps those agents keep working toward a bounded goal instead of stopping after one polite assistant turn. It is especially useful for web tasks where success is observable only after code, tests, logs, and browser behavior line up.\n\n[Core principles](/topics/foundations-hooks-and-context-hygiene/)\n\n## Current Codex Stop contract\n\nA Ralph Loop must use the Stop event’s continuation decision, not a general hook-output flag. In the [official Stop contract](https://developers.openai.com/codex/hooks#stop), a synchronous hook that exits successfully requests another pass by writing JSON such as:\n\n```json\n{\"decision\":\"block\",\"reason\":\"Original goal: prove the checkout flow. Browser proof is still missing. Run the bounded checkout verification, save the observed result, and re-check the completion criteria.\"}\n```\n\nFor `Stop`, `decision: \"block\"` does not reject the work: Codex creates a continuation prompt from `reason`, acting as a new user prompt. The reason should identify the original goal, the missing evidence, and the next bounded action. `{\"continue\":true}` alone does **not** request another turn. `systemMessage` and `suppressOutput` are not substitutes for a Stop continuation decision.\n\nWhen completion is verified, the iteration cap is reached, or a blocker requires human review, the hook can explicitly end continuation:\n\n```json\n{\"continue\":false,\"stopReason\":\"Iteration cap reached; browser proof remains missing. Stop for review, not success.\"}\n```\n\nUse a truthful reason for the actual terminal state. A cap or blocker is not evidence that the goal succeeded. Returning JSON without a blocking decision leaves this hook with no continuation request; `continue: false` is stronger and takes precedence over continuation decisions from other matching Stop hooks.\n\n- On exit code `0`, Stop output must be valid JSON; plain text on stdout is invalid. An alternative continuation signal is exit code `2` with the reason on stderr.\n- `stop_hook_active` reports whether Stop already continued this turn. It is a boolean, not a persistent iteration counter. Maintain an explicit run-scoped cap and check completion evidence on every invocation.\n- Keep the Stop hook synchronous and fast. It should inspect evidence and decide, not perform the slow browser/API work itself. Background hooks cannot enforce turn continuation.\n- Review and trust the exact hook definition through `/hooks`; installing a plugin is not the same as trusting its hooks. Recheck after hook definitions change.\n- Plugin configuration and supported fields are version-specific. The historical reference below is retained for context, but use the event-specific contract above for an operational Stop loop.\n\n## Copy-paste workflow\n\n**When to use:** When you want an agent to pursue a goal across many turns without manual nudging. A Stop hook re-checks the original task when the agent tries to stop and pushes it to keep working until a clear completion condition is met.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. Build a minimal \"Ralph Loop\" Codex plugin: a Stop hook that re-points the agent at the original goal and requests another pass until a completion condition or hard cap is reached. This workflow uses UserPromptSubmit, PreToolUse (Tool Use), and Stop as its three teaching landmarks; they are not the complete current event list. The Ralph Loop is a STOP hook. Use the Current Codex Stop contract above.\n\n1. First enable hooks + plugins in ~/.codex/config.toml, then restart Codex:\n     [features]\n     hooks = true\n     plugins = true\n     plugin_hooks = true\n\n2. Scaffold the real plugin layout:\n     my-plugin/\n       .codex-plugin/plugin.json      # manifest, with \"hooks\": \"hooks/hooks.json\"\n       hooks/hooks.json               # wires a Stop hook command\n       hooks/hook.py                  # the Stop hook script\n\n3. In hooks/hooks.json, wire the Stop event to run the hook script, e.g.:\n     {\n       \"hooks\": {\n         \"Stop\": [\n           { \"hooks\": [ { \"type\": \"command\", \"command\": \"python3 \\\"${CODEX_PLUGIN_ROOT}/hooks/hook.py\\\"\", \"timeout\": 5 } ] }\n         ]\n       }\n     }\n\n4. hook.py reads the Stop event JSON on stdin and writes EXACTLY ONE JSON line. When the goal is incomplete and the hard cap has not been reached, emit {\"decision\":\"block\",\"reason\":\"<original goal, missing evidence, and next bounded action>\"}. When completion is verified, the cap is reached, or a blocker needs review, emit {\"continue\":false,\"stopReason\":\"<truthful terminal reason>\"}. Never report cap exhaustion as success. Do not rely on continue:true or suppressOutput to request another turn. Keep the hook synchronous, fast, and boring.\n\nCRITICAL guardrail: the loop MUST have a hard completion condition — an iteration cap or an explicit target state — enforced by the hook, not just suggested in a prompt. Without it you get a runaway loop.\n```\n\n### How it works\n- UserPromptSubmit, tool-use events, and Stop are the lifecycle landmarks used here; current Codex supports additional events. The Ralph Loop uses Stop.\n- The source plugin examples enable `hooks`, `plugins`, and `plugin_hooks` in `~/.codex/config.toml` and restart Codex. Treat these flags as version-specific setup, and review/trust the installed hook definitions through `/hooks`.\n- The real plugin layout is `.codex-plugin/plugin.json` (manifest) + `hooks/hooks.json` (wiring) + a hook script; `${CODEX_PLUGIN_ROOT}` resolves the plugin dir.\n- The hook reads event JSON and emits a Stop-specific decision: `{\"decision\":\"block\",\"reason\":\"<next bounded action>\"}` requests continuation. `{\"continue\":true}` alone does not. The harness acts on the decision and uses the reason as a new continuation prompt.\n- CRITICAL: require an explicit completion condition (iteration cap or target state) or you get runaway loops.\n- Reference: [Codex Hooks docs](https://developers.openai.com/codex/hooks), [Better Plugins](https://github.com/johnlindquist/better-plugins/tree/main/plugins).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/ralph-loop-hook/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: ralph-loop-hook\ndescription: Trigger when the user wants an agent to keep pursuing a goal across turns via a Codex Stop hook (the Ralph Loop). Do NOT use without a clear completion condition — unbounded loops waste tokens and run tools too long.\n---\n\n# Ralph Loop hook\n\nScaffold a Ralph Loop: a Codex Stop hook that, when the agent tries to stop, re-points it at the original goal and requests another pass until a completion condition or hard cap is reached — enforced by the harness, not merely suggested in a prompt. UserPromptSubmit, PreToolUse (Tool Use), and Stop are the three teaching landmarks for this workflow, not the exhaustive current event list. The Ralph Loop uses Stop.\n\n## Prerequisite\n\nEnable hooks + plugins in `~/.codex/config.toml`, then restart Codex:\n```toml\n[features]\nhooks = true\nplugins = true\nplugin_hooks = true\n```\n`/plugins` confirms install; `/hooks` reviews/trusts bundled hooks.\n\n## Steps\n\n1. Scaffold the real plugin layout:\n   ```\n   my-plugin/\n     .codex-plugin/plugin.json      # manifest, with \"hooks\": \"hooks/hooks.json\"\n     hooks/hooks.json               # hook wiring\n     hooks/hook.py                  # the Stop hook script\n   ```\n\n2. Wire the Stop event in `hooks/hooks.json`:\n   ```json\n   {\n     \"hooks\": {\n       \"Stop\": [\n         { \"hooks\": [ { \"type\": \"command\", \"command\": \"python3 \\\"${CODEX_PLUGIN_ROOT}/hooks/hook.py\\\"\", \"timeout\": 5 } ] }\n       ]\n     }\n   }\n   ```\n\n3. `hooks/hook.py` reads the Stop event JSON on stdin and writes EXACTLY ONE JSON line. While the goal is incomplete and below its hard cap, emit `{\"decision\":\"block\",\"reason\":\"<original goal, missing evidence, next bounded action>\"}`. On verified completion, cap exhaustion, or a blocker requiring review, emit `{\"continue\":false,\"stopReason\":\"<truthful terminal reason>\"}`. Cap exhaustion is not success. `continue:true` alone does not request another turn; do not use `suppressOutput` as a continuation mechanism. Keep the hook synchronous and fast; let the resumed agent or a separate worker perform slow work, then inspect its evidence on the next Stop invocation.\n\n## Guardrails\n- MANDATORY: a hard completion condition (iteration cap or target state) enforced by the hook. Without it you get a runaway loop that wastes tokens and runs tools too long.\n````\n\n## Scenarios\n\n### Keep fixing a checkout bug until browser proof passes\n\n**Role:** As a senior frontend engineer responsible for a Next.js checkout flow\n\nA local Next.js app has a flaky checkout path: the agent often fixes one validation error, reports done, and stops before proving the full browser flow from cart to confirmation. The team wants a Ralph Loop plugin that keeps the agent on the original checkout goal until tests and browser evidence prove the flow works.\n\n> As a senior frontend engineer, I want a Stop hook to re-point the agent at the original checkout goal until the checkout flow passes, so that the agent does not stop after only a partial code fix.\n\n#### Agent brief\n\n```text\nBuild a minimal Ralph Loop Codex plugin for this repo. Inspect the Copy-paste workflow section of this playbook and the Reusable skill section of this playbook first. Enable hooks and plugins in ~/.codex/config.toml with hooks=true, plugins=true, plugin_hooks=true, then tell me to restart Codex before testing. Scaffold ralph-loop-checkout/.codex-plugin/plugin.json, ralph-loop-checkout/hooks/hooks.json, and ralph-loop-checkout/hooks/hook.py. Wire only the Stop hook to python3 \"${CODEX_PLUGIN_ROOT}/hooks/hook.py\" with timeout 5. The hook must read stdin JSON and write exactly one control JSON line. Store tiny local state for the original goal and iteration count. Completion condition: stop when all of these receipts exist in .notes/ralph-loop-checkout/: passing-test.log, browser-proof.md, and final-summary.md, or when iteration_count reaches 5. Do not use suppressOutput in Stop. After scaffolding, run a local simulation command that pipes mock Stop events into hook.py and proves both paths: continue before receipts exist, allow stop after receipts exist or at the cap. Expected output: plugin files, a short README section showing install/test steps, and simulation logs saved under .notes/ralph-loop-checkout/.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/#command-reference)\n\n```text\n~/.codex/config.toml\n```\n\n```text\nralph-loop-checkout/.codex-plugin/plugin.json\n```\n\n```text\nralph-loop-checkout/hooks/hooks.json\n```\n\n```text\nralph-loop-checkout/hooks/hook.py\n```\n\n#### Browser verification\n\nUse the app's local dev server and a browser agent or Playwright-style flow to visit the checkout route, add a test item, fill the checkout form, submit, and capture the confirmation page state. Save the route, actions, visible confirmation text, and any console errors to .notes/ralph-loop-checkout/browser-proof.md. If running inside CMUX, open or use a browser pane for the local app and keep the terminal pane visible for test output.\n\n#### Definition of done\n\n- A valid Codex plugin layout exists with .codex-plugin/plugin.json, hooks/hooks.json, and hooks/hook.py.\n- hooks/hooks.json wires a Stop hook command and does not add unrelated lifecycle hooks.\n- hook.py emits exactly one control JSON line per event and never emits suppressOutput for Stop.\n- A hard completion condition is enforced by receipt files plus an iteration cap of 5.\n- Simulation logs show the hook continues before checkout proof exists and allows stopping after proof or cap.\n- .notes/ralph-loop-checkout/browser-proof.md records the browser flow, visible result, and console-error status.\n\n#### Failure modes and mitigations\n\n- Common mistake: the agent only writes a prompt that says 'keep going' instead of enforcing continuation in a Stop hook. Mitigation: require a real hooks/hooks.json Stop entry and a hook.py simulation log.\n- Common mistake: the loop is unbounded and can churn on tools forever. Mitigation: enforce the iteration cap in hook state and treat missing proof after the cap as a failed receipt, not silent success.\n\n### Stop-hook guard for visual regression cleanup\n\n**Role:** As a product-minded UI developer polishing a dashboard redesign\n\nA dashboard redesign has several small layout regressions across authenticated pages. Agents keep fixing the first obvious CSS issue and stopping without checking the rest of the dashboard routes in the running app.\n\n> As a UI developer, I want a Ralph Loop to keep the agent cycling through the original dashboard acceptance criteria until browser receipts are written for each target route, so that layout cleanup is proven in the app instead of inferred from code.\n\n#### Agent brief\n\n```text\nCreate a Ralph Loop plugin named ralph-loop-dashboard for dashboard visual cleanup. Start by reading the Hooks and context hygiene article, the Copy-paste workflow section of this playbook, and the Command reference section of this playbook. Use the taught lifecycle model: UserPromptSubmit, PreToolUse or Tool Use, and Stop; implement only the Stop hook for this scenario. Plugin layout must be ralph-loop-dashboard/.codex-plugin/plugin.json, ralph-loop-dashboard/hooks/hooks.json, and ralph-loop-dashboard/hooks/hook.py. Add a .notes/ralph-loop-dashboard/acceptance.md file that lists the exact dashboard routes to verify and a .notes/ralph-loop-dashboard/proofs/ directory for receipts. Completion condition: allow stop only when acceptance.md has every route marked verified with a matching proof markdown file, or when 4 Stop iterations have happened. Each continuation message should point back to the original dashboard goal and name the next missing route proof. Expected output: plugin scaffold, acceptance/proof file contract, hook simulation, and instructions for installing with codex plugin marketplace add \"$PWD\" then codex plugin add ralph-loop-dashboard@better-plugins only if this repo is being used as a marketplace-style plugin source.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-hooks-and-context-hygiene/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/#command-reference)\n\n```text\n.notes/ralph-loop-dashboard/acceptance.md\n```\n\n```text\n.notes/ralph-loop-dashboard/proofs/\n```\n\n```text\ncodex plugin marketplace add \"$PWD\"\n```\n\n```text\ncodex plugin add ralph-loop-dashboard@better-plugins\n```\n\n#### Browser verification\n\nUse a CMUX browser pane, agent-browser-style accessibility snapshot/click/fill/evaluate workflow, or Playwright to visit each listed dashboard route on localhost. For each route, capture the route URL, viewport size, key visible labels, broken layout notes, and console errors. Write one proof file per route under .notes/ralph-loop-dashboard/proofs/ and mark the route verified in acceptance.md only after the browser check has actually run.\n\n#### Definition of done\n\n- The Stop hook can identify the next missing dashboard route proof from acceptance.md.\n- The hook continues while route proofs are missing and allows stop only after all proofs exist or after 4 iterations.\n- Each route has a proof markdown file with URL, viewport, visible labels, and console-error status.\n- The plugin scaffold uses the real Codex plugin layout and keeps hook work fast and boring.\n- The final review artifact explains which routes were checked, which files changed, and whether any proof is still missing.\n\n#### Failure modes and mitigations\n\n- Common mistake: the agent marks routes verified from source inspection alone. Mitigation: require browser proof files and reject completion when a proof file is missing.\n- Common mistake: the hook tries to do browser automation itself and becomes slow or brittle. Mitigation: keep the hook limited to state checks and continuation control; put browser verification in the agent workflow and receipt files.\n\n### Prototype a safe Ralph Loop before installing it globally\n\n**Role:** As a developer-tools engineer maintaining local Codex plugin experiments\n\nThe team wants to experiment with stop-hook continuation, but the Better Plugins material is prototype-stage and personally configured. Before installing anything globally, they need a toy Ralph Loop with deterministic local simulation and clear guardrails.\n\n> As a developer-tools engineer, I want a toy Ralph Loop plugin with local simulations and an explicit completion cap, so that we can learn the hook mechanics without risking a runaway agent session in a production repo.\n\n#### Agent brief\n\n```text\nBuild a toy plugin named ralph-loop-toy that demonstrates the Ralph Loop without touching application code. Use only the taught plugin/hook model from lesson 07 and the existing toolkit artifacts. Read the Hooks and context hygiene article, the documented scope and caveats in this playbook, the Reusable skill section of this playbook, and the Command reference section of this playbook. Scaffold ralph-loop-toy/.codex-plugin/plugin.json, ralph-loop-toy/hooks/hooks.json, ralph-loop-toy/hooks/hook.py, and ralph-loop-toy/tests/simulate-stop-events.py. The toy goal is: create .notes/ralph-loop-toy/done.txt containing DONE. The Stop hook should continue until done.txt exists or until iteration_count reaches 3. The simulator must run three cases: no done.txt means continue, done.txt means stop, cap reached means stop with a clear failure note. Expected output: the plugin files, simulator output, and a short README that tells developers to review /plugins and /hooks after install and to restart Codex after config changes.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-hooks-and-context-hygiene/)\n\n[Open reference](/topics/foundations-hooks-and-context-hygiene/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n[Open reference](/topics/foundations-ralph-loop-playbook/#command-reference)\n\n```text\nralph-loop-toy/tests/simulate-stop-events.py\n```\n\n```text\n~/.codex/config.toml\n```\n\n```text\n/plugins\n```\n\n```text\n/hooks\n```\n\n#### Browser verification\n\nBrowser proof is not the right proof for this toy plugin because the goal is hook mechanics, not web-app behavior. The useful UI move is optional: if running in CMUX, open a live Markdown tracker with cmux markdown open .notes/ralph-loop-toy/tracker.md --direction right so the human can watch the simulation cases and receipts update.\n\n#### Definition of done\n\n- Toy plugin files exist in the real plugin directory layout.\n- hooks/hooks.json wires the Stop event to hook.py with a short timeout.\n- simulate-stop-events.py proves continue, success stop, and cap stop behavior without requiring a live Codex session.\n- The README includes the required ~/.codex/config.toml feature flags and restart note.\n- The implementation avoids production app edits, broad plugin behavior, and unbounded continuation.\n\n#### Failure modes and mitigations\n\n- Common mistake: installing a prototype globally before proving local behavior. Mitigation: require simulator output before any install instructions are followed.\n- Common mistake: mixing in #human, Toolsmith, Gemini Video, or dashboard behavior. Mitigation: keep this scenario to exactly one technique: Stop-hook continuation.\n\n## Implementation notes\n\n- Keep the Ralph Loop to exactly one toolkit technique: Stop-hook continuation. Browser checks, Markdown trackers, and simulation scripts are proof surfaces, not extra toolkit topics.\n- The hook should be fast and boring: parse event input, inspect small local state or receipt files, emit one control JSON line, and exit.\n- Use a hard completion condition every time: iteration cap, explicit target state, or both. A Stop hook without a bound is not a workshop-quality scenario.\n- For web-app scenarios, require browser receipts because source inspection alone does not prove UI behavior.\n- Keep receipt files local under .notes/ so developers can inspect proof without committing noisy agent scratch work.\n- Do not assume browser cookies are available to an agent-browser workflow. Authenticated flows need an explicit login/setup path or a local test fixture.\n- Treat Better Plugins examples as prototype reference material, not polished drop-in infrastructure.\n\n## Boundaries and caveats\n\n- Do not introduce MCP wrappers, daemon profiles, self-improving hooks, or background-worker architectures for this topic.\n- Do not present #human, Toolsmith, or Gemini Video as part of the Ralph Loop implementation; they may be references, but this workflow is about Stop-hook continuation.\n- Do not rely on a prompt-only 'keep going' instruction as the implementation. The taught distinction is that the harness enforces continuation through a Stop hook.\n- Do not create unbounded loops, broad permissions, or hooks that perform slow browser/API work directly.\n\n## Agent reference map\n\n### Validated lesson 07 references\n\nUse this as the source of truth for what was taught: compaction/forking, the big three hooks, Ralph Loop, skills versus plugins, and custom grammar triggers.\n\n[Open reference](/topics/foundations-hooks-and-context-hygiene/)\n\n### Lesson 07 validation notes\n\nUse this to avoid overclaiming or reintroducing details that were removed from the validated lesson scope.\n\n[Open reference](/topics/foundations-hooks-and-context-hygiene/)\n\n### Existing Ralph Loop prompt\n\nUse this as the implementation-facing prompt baseline for scaffolding a minimal Stop-hook continuation plugin.\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n### Existing Ralph Loop Codex skill\n\nUse this as the concise reusable skill contract: trigger conditions, prerequisite config, plugin layout, Stop hook wiring, and guardrails.\n\n[Open reference](/topics/foundations-ralph-loop-playbook/)\n\n### Verified Better Plugins command and layout notes\n\nUse this for the real plugin directory layout, hooks.json shape, control JSON rules, and install commands; do not invent plugin flags.\n\n[Open reference](/topics/foundations-ralph-loop-playbook/#command-reference)\n\n### CMUX CLI notes\n\nUse only for optional local workspace proof such as browser panes, live Markdown trackers, reading screens, or inspecting panes.\n\n[Open reference](/topics/foundations-cmux-orchestrate-playbook/#command-reference)\n\n## Command reference\n\nThese command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.\n\n## Enable hooks + plugins (~/.codex/config.toml)\n```toml\n[features]\nhooks = true\nplugins = true\nplugin_hooks = true\n```\nRestart Codex after installing/updating. `/plugins` confirms install; `/hooks` reviews/trusts bundled hooks.\n\n## Plugin directory layout (real)\n```\nmy-plugin/\n  .codex-plugin/plugin.json      # manifest\n  hooks/hooks.json               # hook wiring\n  hooks/<entrypoint>.py|.js      # hook scripts\n```\n\n## Manifest example (plugins/gemini-video/.codex-plugin/plugin.json — real)\n```json\n{\n  \"name\": \"gemini-video\",\n  \"description\": \"Detects .mp4 paths in prompts/tool calls and summarizes them with Gemini in a detached worker.\",\n  \"version\": \"0.1.0\",\n  \"hooks\": \"hooks/hooks.json\"\n}\n```\n\n## hooks.json — three selected lifecycle events from the source plugin\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"python3 \\\"${CODEX_PLUGIN_ROOT}/hooks/hook.py\\\"\", \"timeout\": 8 } ] }\n    ],\n    \"PostToolUse\": [\n      { \"matcher\": \"*\", \"hooks\": [ { \"type\": \"command\", \"command\": \"python3 \\\"${CODEX_PLUGIN_ROOT}/hooks/hook.py\\\"\", \"timeout\": 5 } ] }\n    ],\n    \"Stop\": [\n      { \"hooks\": [ { \"type\": \"command\", \"command\": \"python3 \\\"${CODEX_PLUGIN_ROOT}/hooks/hook.py\\\"\", \"timeout\": 5 } ] }\n    ]\n  }\n}\n```\n(Toolsmith uses `UserPromptSubmit` and `PreToolUse`; `${PLUGIN_ROOT}` / `${CODEX_PLUGIN_ROOT}` resolve the plugin dir.)\n\n## Historical hook-output example\n\nThe source `hook_control.py` example below is preserved as a version-specific historical specimen, **not** as a reliable current Stop continuation implementation. Its `continue: true` permits normal hook processing; it does not by itself force another agent turn. Its comment about `suppressOutput` reflects the source implementation, not the current event-support contract.\n```python\ndef control_for_event(event_name: str) -> dict:\n    out = {\"continue\": True}\n    if event_name == \"UserPromptSubmit\":\n        out[\"suppressOutput\"] = True   # suppressOutput is ONLY valid on UserPromptSubmit\n    return out\n# emit: sys.stdout.write(json.dumps(out, separators=(\",\", \":\")) + \"\\n\")\n```\nThe historical source claimed that Codex rejected `suppressOutput` outside UserPromptSubmit. Current [common output documentation](https://developers.openai.com/codex/hooks#common-output-fields) lists it for several events, including Stop, as parsed but not yet implemented; support remains event-specific. Neither that field nor `continue: true` blocks Stop. Use `decision: \"block\"` with a reason for continuation, and keep hooks fast: parse minimal state, inspect evidence, emit valid event-specific JSON, and leave slow work outside the Stop handler.\n\n## Ralph Loop (taught concept, lesson 07/08)\nA Stop hook that, when the agent tries to stop, re-points it at the original goal and continues until a completion condition is met — enforced by the harness, not merely suggested in a prompt. MUST have a hard completion condition (iteration cap / target state) to avoid runaway loops.\n\n## Install (README, real)\n```bash\ncodex plugin marketplace add johnlindquist/better-plugins   # or:  codex plugin marketplace add \"$PWD\"\ncodex plugin add <name>@better-plugins\n# after edits:\ncodex plugin remove <name>@better-plugins && codex plugin add <name>@better-plugins\n```\n\n## Toolsmith data paths (real)\n`~/.codex/plugins/data/better-plugins-toolsmith/` (events/ raw JSONL, indexes/tool-index.json compact)."
    },
    {
      "id": "factory-flow-recipes",
      "slug": "flow-recipes",
      "title": "Reusable flow and skill recipes",
      "summary": "Complete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture.",
      "category": "Execution",
      "tags": [
        "flows",
        "skills",
        "prompts"
      ],
      "sources": [
        {
          "label": "Published mdflow skills",
          "url": "https://walnut-virtue-6d22.here.now/"
        },
        {
          "label": "skills/fixit/SKILL.md",
          "url": "https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md"
        },
        {
          "label": "flows/this-or-that.md",
          "url": "https://walnut-virtue-6d22.here.now/flows/this-or-that.md"
        },
        {
          "label": "flows/workshop-standup.claude.md",
          "url": "https://walnut-virtue-6d22.here.now/flows/workshop-standup.claude.md"
        },
        {
          "label": "skills/pr-description/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/pr-description/SKILL.md"
        },
        {
          "label": "skills/onboard/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/onboard/SKILL.md"
        },
        {
          "label": "skills/fix-tests/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/fix-tests/SKILL.md"
        },
        {
          "label": "skills/changelog/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/changelog/SKILL.md"
        },
        {
          "label": "skills/review/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/review/SKILL.md"
        },
        {
          "label": "skills/workshop-standup/SKILL.md",
          "url": "https://walnut-virtue-6d22.here.now/skills/workshop-standup/SKILL.md"
        },
        {
          "label": "skills/this-or-that/SKILL.md",
          "url": "https://gentle-lasso-9d5n.here.now/skills/this-or-that/SKILL.md"
        }
      ],
      "sourceUnits": [
        "04-prompt-builder/skills/fixit/SKILL.md",
        "05-mdflow/flows/this-or-that.md",
        "05-mdflow/flows/workshop-standup.claude.md",
        "05-mdflow/skills/pr-description/SKILL.md",
        "05-mdflow/skills/onboard/SKILL.md",
        "05-mdflow/skills/fix-tests/SKILL.md",
        "05-mdflow/skills/changelog/SKILL.md",
        "05-mdflow/skills/review/SKILL.md",
        "05-mdflow/skills/workshop-standup/SKILL.md",
        "10-this-or-that/skills/this-or-that/SKILL.md",
        "agenda/flows/workshop.md#dispatcher"
      ],
      "collection": "factory",
      "categoryId": "execution",
      "wordCount": 2829,
      "url": "/topics/factory-flow-recipes/",
      "markdownUrl": "/markdown/factory-flow-recipes.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-flow-recipes.json",
      "headings": [
        {
          "id": "skills-fixit-skill-md",
          "text": "skills/fixit/SKILL.md",
          "level": 2
        },
        {
          "id": "fixit-expert-debugger",
          "text": "fixit — expert debugger",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "flows-this-or-that-md",
          "text": "flows/this-or-that.md",
          "level": 2
        },
        {
          "id": "the-process-exactly-as-proven-in-authoring-lab-and-07-variations-template-lab",
          "text": "The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)",
          "level": 2
        },
        {
          "id": "accumulated-taste-record-injected-fresh-each-run-read-before-generating-options",
          "text": "Accumulated taste record (injected fresh each run — read before generating options)",
          "level": 2
        },
        {
          "id": "flows-workshop-standup-claude-md",
          "text": "flows/workshop-standup.claude.md",
          "level": 2
        },
        {
          "id": "repo-state-git",
          "text": "Repo state (git)",
          "level": 2
        },
        {
          "id": "terminal-workspace-herdr-panes",
          "text": "Terminal workspace (herdr panes)",
          "level": 2
        },
        {
          "id": "open-tickets-linear",
          "text": "Open tickets (linear)",
          "level": 2
        },
        {
          "id": "your-job",
          "text": "Your job",
          "level": 2
        },
        {
          "id": "skills-pr-description-skill-md",
          "text": "skills/pr-description/SKILL.md",
          "level": 2
        },
        {
          "id": "pr-description-write-a-pr-description-for-the-current-branch",
          "text": "pr-description — write a PR description for the current branch",
          "level": 2
        },
        {
          "id": "steps-2",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "skills-onboard-skill-md",
          "text": "skills/onboard/SKILL.md",
          "level": 2
        },
        {
          "id": "onboard-explain-this-codebase-to-a-newcomer",
          "text": "onboard — explain this codebase to a newcomer",
          "level": 2
        },
        {
          "id": "your-job-2",
          "text": "Your job",
          "level": 2
        },
        {
          "id": "skills-fix-tests-skill-md",
          "text": "skills/fix-tests/SKILL.md",
          "level": 2
        },
        {
          "id": "fix-tests-run-the-test-suite-and-fix-what-fails",
          "text": "fix-tests — run the test suite and fix what fails",
          "level": 2
        },
        {
          "id": "steps-3",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "skills-changelog-skill-md",
          "text": "skills/changelog/SKILL.md",
          "level": 2
        },
        {
          "id": "changelog-draft-a-changelog-entry-from-recent-commits",
          "text": "changelog — draft a changelog entry from recent commits",
          "level": 2
        },
        {
          "id": "steps-4",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "skills-review-skill-md",
          "text": "skills/review/SKILL.md",
          "level": 2
        },
        {
          "id": "review-review-staged-changes-for-bugs",
          "text": "review — review staged changes for bugs",
          "level": 2
        },
        {
          "id": "steps-5",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "skills-workshop-standup-skill-md",
          "text": "skills/workshop-standup/SKILL.md",
          "level": 2
        },
        {
          "id": "workshop-standup-pane-aware-standup",
          "text": "workshop-standup — pane-aware standup",
          "level": 2
        },
        {
          "id": "gather-context-first-run-these-tolerate-absence",
          "text": "Gather context first (run these, tolerate absence)",
          "level": 2
        },
        {
          "id": "your-job-3",
          "text": "Your job",
          "level": 2
        },
        {
          "id": "skills-this-or-that-skill-md",
          "text": "skills/this-or-that/SKILL.md",
          "level": 2
        },
        {
          "id": "this-or-that-rlhf-where-the-user-is-the-reward-model",
          "text": "this-or-that — RLHF where the user is the reward model",
          "level": 2
        },
        {
          "id": "the-harness-3-files-get-them-first",
          "text": "The harness (3 files, get them first)",
          "level": 2
        },
        {
          "id": "running-a-round",
          "text": "Running a round",
          "level": 2
        },
        {
          "id": "vote-record-schema-what-lands-in-votes-jsonl",
          "text": "Vote record schema (what lands in votes.jsonl)",
          "level": 2
        },
        {
          "id": "proven-results-evidence-this-works",
          "text": "Proven results (evidence this works)",
          "level": 2
        },
        {
          "id": "whole-workshop-task-dispatcher",
          "text": "Whole-workshop task dispatcher",
          "level": 2
        },
        {
          "id": "task",
          "text": "Task",
          "level": 2
        },
        {
          "id": "agenda-machine-readable-index-of-the-whole-workshop",
          "text": "Agenda — machine-readable index of the whole workshop",
          "level": 2
        },
        {
          "id": "00-how-agentic-work-is-evolving",
          "text": "00 · How Agentic Work is Evolving",
          "level": 2
        },
        {
          "id": "01-configuring-your-environment",
          "text": "01 · Configuring your environment",
          "level": 2
        },
        {
          "id": "02-custom-zsh-functions",
          "text": "02 · Custom zsh functions",
          "level": 2
        },
        {
          "id": "03-prompting-with-images",
          "text": "03 · Prompting with Images",
          "level": 2
        },
        {
          "id": "04-prompt-builder",
          "text": "04 · Prompt Builder",
          "level": 2
        },
        {
          "id": "05-mdflow",
          "text": "05 · mdflow",
          "level": 2
        },
        {
          "id": "06-why-pi-herdr-and-ghostty",
          "text": "06 · Why Pi, Herdr, and Ghostty",
          "level": 2
        },
        {
          "id": "07-variations-9x-image-mockups",
          "text": "07 · Variations (9x image mockups)",
          "level": 2
        },
        {
          "id": "10-this-or-that-rlhf-for-your-taste",
          "text": "10 · This or That — RLHF for Your Taste",
          "level": 2
        },
        {
          "id": "08-maximum-intelligence-and-video",
          "text": "08 · Maximum Intelligence and Video",
          "level": 2
        },
        {
          "id": "09-debugging-with-markers",
          "text": "09 · Debugging with Markers",
          "level": 2
        },
        {
          "id": "references-resources-tool-alternatives",
          "text": "References & Resources — tool alternatives",
          "level": 2
        }
      ],
      "markdown": "# Reusable flow and skill recipes\n\nComplete small contracts for code review, onboarding, test repair, changelogs, PR descriptions, pane-aware standups, and preference capture.\n\n## skills/fixit/SKILL.md\n\n```yaml\nname: fixit\ndescription: Expert debugger — take a bug report, reproduce it, find the root cause, fix it, and prove the fix. Use when the user pastes a bug report, error output, or stack trace and wants it diagnosed and fixed.\n```\n\n## fixit — expert debugger\n\nSkill twin of the `fixit` wrapper from the prompt-builder guide\n(https://shiny-bloom-f8hv.here.now/) — the same job in its third form:\nzsh wrapper → mdflow flow (`flows/fixit.codex.md`) → agent skill.\n\nYou're an expert debugger. The user's message is the bug report.\n\n## Steps\n\n1. Restate the bug in one sentence so a wrong reading dies early.\n2. Reproduce it — run the failing command, test, or flow and capture the\n   actual output. If you can't reproduce, say exactly what you tried and stop.\n3. Find the root cause. Read the code on the failure path; don't patch\n   symptoms.\n4. Fix it, minimally.\n5. Prove it — re-run the reproduction and show the before/after.\n\nIf the report is too vague to reproduce (no steps, no error, no location),\nask for the missing piece instead of guessing.\n\n## flows/this-or-that.md\n\n```yaml\ndescription: Run one this-or-that Elo voting round — generate structurally distinct options over a constant subject, stand up the duel harness, wait for votes, then bank the taste as explicit rules\n_inputs: [_question, _subject]\n_interactive: true\n```\n\nYou are running one round of the **this-or-that decision flow**: the user can't\narticulate their taste, but they can pick between two things all day. Turn the\nquestion below into an Elo-voted decision with a durable record.\n\n**Question to decide:** {{ _question }}\n\n**Subject / content source (hold constant across every option):** {{ _subject }}\n\n## The process (exactly as proven in `authoring-lab/` and `07-variations/template-lab/`)\n\n1. **Frame the axis.** Name the ONE thing options vary on (theme, format, copy,\n   API shape). Everything else — subject content, visual theme — is held constant\n   so votes measure only that axis.\n2. **Scaffold the lab.** Create `<slug>-lab/` at the repo root. Copy `compare.html`\n   and `server.py` **verbatim** from `10-this-or-that/kit/`. Write `options.json`\n   (`{title, modes: true, options: [{id, name, src}]}`). Write one shared base\n   stylesheet all options link, so theme stays constant; support\n   `html[data-mode=\"light|dark\"]` (light default, `prefers-color-scheme` +\n   `data-mode` override) — the harness stamps it and records the mode on every vote.\n3. **Generate 9–13 structurally distinct options.** Same subject, different\n   approach; if two could be confused at arm's length, replace one. Include the\n   incumbent as a control when one exists. Write one exemplar option yourself,\n   then fan out parallel subagents, each authoring 2–3 options from one tight\n   shared brief (subject digest + format rules + per-option spec + the exemplar\n   path). Real content only — never lorem ipsum, never invented names.\n4. **QA before handing over.** Every file HTTP 200 through `server.py`; grep-audit\n   (zero external requests, no absolute home paths, no secrets); render both light\n   and dark; POST a smoke vote to `/vote`, confirm it lands in `votes.jsonl`,\n   remove it.\n5. **Hand over and get out of the way.** Start `python3 server.py <port>` in the\n   background and give the user the `compare.html` URL. Controls: ←/→ pick ·\n   ↓ both bad · `d` flips light/dark · `s` skip · `f` finish · the note field\n   saves with each vote (tell the user: one note outweighs ten votes).\n6. **When the user says \"done\":** read `votes.jsonl` — ranking, per-mode W-L\n   splits, `both_bad` lines, and especially notes. State the user's taste as\n   explicit, quotable rules backed by vote evidence (head-to-heads, splits,\n   quoted notes). A user note that makes a decision IS the decision.\n7. **Bank it.** Archive as `votes-round<N>.jsonl`, write `RESULTS.md` (standings\n   table, the decision with quoted evidence, taste rules, ship plan), update\n   agent memory so it is never re-litigated. Then propose round 2 from the\n   winners — or ship.\n\n## Accumulated taste record (injected fresh each run — read before generating options)\n\n@../authoring-lab/RESULTS.md\n\n@../07-variations/template-lab/RESULTS.md\n\n## flows/workshop-standup.claude.md\n\n```yaml\ndescription: pane-aware standup — agent starts already knowing git, panes, and tickets\nmodel: sonnet\nprint: true\n```\n\nYou are a standup assistant. Everything below was captured at prompt-build\ntime, BEFORE you started — do not re-run these commands.\n\n## Repo state (git)\n\n!`git status --short --branch`\n\n!`git log --oneline -5 2>/dev/null || echo \"(no commits yet)\"`\n\n## Terminal workspace (herdr panes)\n\n!`herdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"`\n\n## Open tickets (linear)\n\n!`echo \"(placeholder: linear 'list my in-progress issues' — sandboxed agent call)\"`\n\n## Your job\n\nFrom the preloaded context only:\n1. Say what I'm in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n\n## skills/pr-description/SKILL.md\n\n```yaml\nname: pr-description\ndescription: Write a pull-request description for the current branch — what changed, why, and how to verify it, under 200 words, leading with the outcome. Use when the user says \"write the PR description\", \"describe this branch\", or is about to open a pull request.\n```\n\n## pr-description — write a PR description for the current branch\n\nSkill twin of the mdflow flow `flows/pr-description.md`\n(https://walnut-virtue-6d22.here.now/). The flow preloads the branch history\nat prompt-build time; this skill has you fetch it yourself.\n\n## Steps\n\n1. Gather the branch state (fall back if there's no `main`):\n\n```bash\ngit log --oneline main..HEAD 2>/dev/null || git log --oneline -10\ngit diff --stat main...HEAD 2>/dev/null || git diff --stat HEAD~5\n```\n\n2. Write the pull-request description: what changed, why, and how to verify\n   it. Lead with the outcome. Keep it under 200 words.\n\n## skills/onboard/SKILL.md\n\n```yaml\nname: onboard\ndescription: Explain the current codebase to a newcomer — what it does, how it's laid out, where the core logic lives, and the three files to read first. Use when the user says \"onboard me\", \"explain this codebase\", \"I'm new here\", or asks for a project orientation.\n```\n\n## onboard — explain this codebase to a newcomer\n\nSkill twin of the mdflow flow `flows/onboard.md`\n(https://walnut-virtue-6d22.here.now/).\n\n## Your job\n\nExplore the repository, then explain it to someone joining the project today:\n\n1. What it does — the one-paragraph purpose.\n2. How it's laid out — the directory map that matters, not every folder.\n3. Where the core logic lives.\n4. The three files to read first, with one line each on why.\n\nIf the user names a focus area (e.g. \"onboard me, I care about the billing\ncode\"), weight the whole answer toward it.\n\n## skills/fix-tests/SKILL.md\n\n```yaml\nname: fix-tests\ndescription: Run the project's test suite and fix whatever fails — root cause in the code, not the test, unless the test is genuinely wrong. Use when the user says \"fix the tests\", \"make the suite green\", or tests are failing and they want them repaired.\n```\n\n## fix-tests — run the test suite and fix what fails\n\nSkill twin of the mdflow flow `flows/fix-tests.md`\n(https://walnut-virtue-6d22.here.now/).\n\n## Steps\n\n1. Find and run this project's test suite (check package.json scripts,\n   Makefile, CI config — whatever the project actually uses).\n2. If everything passes, say so and stop.\n3. If anything fails: show the failing output first, then find the root cause\n   and fix it — the code, not the test, unless the test is genuinely wrong.\n4. Re-run the suite to prove the fix. Report what failed, why, and what\n   changed.\n\n## skills/changelog/SKILL.md\n\n```yaml\nname: changelog\ndescription: Draft a concise changelog entry from recent commits, grouped by feature/fix/chore and written for users. Use when the user asks to \"draft a changelog\", \"write release notes\", or summarize unreleased changes.\n```\n\n## changelog — draft a changelog entry from recent commits\n\nSkill twin of the mdflow flow `flows/changelog.md`\n(https://walnut-virtue-6d22.here.now/). The flow preloads the git history at\nprompt-build time; this skill has you fetch it yourself.\n\n## Steps\n\n1. Gather the recent history:\n\n```bash\ngit log --oneline -30\ngit diff --stat HEAD~10 2>/dev/null || true\n```\n\n2. Draft a concise changelog entry for the unreleased changes. Group by\n   feature/fix/chore. Write for users, not committers — describe what changed\n   for them, not the internals. No commit hashes.\n\n## skills/review/SKILL.md\n\n```yaml\nname: review\ndescription: Review staged git changes for bugs — terse findings with file:line citations. Use when the user says \"review my staged changes\", \"check this diff before I commit\", or wants a quick bug pass over what's about to be committed.\n```\n\n## review — review staged changes for bugs\n\nSkill twin of the mdflow flow `flows/review.md`\n(https://walnut-virtue-6d22.here.now/). The flow preloads the diff at\nprompt-build time; this skill has you fetch it yourself.\n\n## Steps\n\n1. Run `git diff --cached`. If it's empty, say so and stop (offer to review\n   the unstaged diff instead — but only if the user asks).\n2. Review the diff for bugs: logic errors, off-by-ones, missed edge cases,\n   broken contracts, unintended behavior changes.\n\nBe terse. Cite every finding as `file:line`. Bugs only — no style notes.\n\n## skills/workshop-standup/SKILL.md\n\n```yaml\nname: workshop-standup\ndescription: Pane-aware standup — report what the user is in the middle of from git state, visible terminal panes, and open tickets, then suggest the single next action. Use when the user says \"standup\", \"where was I\", \"what am I in the middle of\", or starts a session cold and wants their working state summarized.\n```\n\n## workshop-standup — pane-aware standup\n\nSkill twin of the mdflow flow `flows/workshop-standup.claude.md`\n(https://walnut-virtue-6d22.here.now/). The flow preloads this context at\nprompt-build time before the agent starts; this skill has you gather the same\ncontext with tool calls, then do the same job.\n\n## Gather context first (run these, tolerate absence)\n\n```bash\ngit status --short --branch\ngit log --oneline -5 2>/dev/null || echo \"(no commits yet)\"\nherdr api snapshot 2>/dev/null | head -40 || echo \"(herdr not running)\"\n```\n\nIf the user has a ticket CLI (e.g. `linear`), also list their in-progress\nissues; otherwise skip tickets without comment.\n\n## Your job\n\nFrom the gathered context only:\n\n1. Say what the user is in the middle of (branch, dirty files, visible panes).\n2. Flag anything that looks stalled or contradictory.\n3. Suggest the single next action, one sentence.\n\nDo not start doing the work — this is a standup, not a work session.\n\n## skills/this-or-that/SKILL.md\n\n```yaml\nname: this-or-that\ndescription: Run a this-or-that Elo voting round to decide anything with more than one plausible answer (design, format, copy, API shape, naming). Generates structurally distinct options over a constant subject, stands up a local duel harness the user arrow-keys through, then reads votes.jsonl back as explicit taste rules and a durable RESULTS.md record. Use when the user says \"this or that\", \"spin up options to vote on\", \"help me decide between\", \"RLHF my preferences\", or asks you to learn their taste instead of describing it.\n```\n\n## this-or-that — RLHF where the user is the reward model\n\nThe user can't articulate their taste, but they can pick between two things all\nday. This skill turns any multi-answer decision into an Elo-voted record that\nyou read back as explicit rules — so it is decided once, with evidence, and\nnever re-litigated.\n\nNot for decisions with a conventional default or a single verifiable answer —\njust decide those. Use this when taste is the deciding factor.\n\n## The harness (3 files, get them first)\n\n- In John's workshop repo: copy `compare.html` + `server.py` verbatim from\n  `10-this-or-that/kit/`.\n- Anywhere else: `curl -sO https://gentle-lasso-9d5n.here.now/kit/compare.html`\n  and the same for `server.py` (published copies of the kit; also see that\n  site's write-up).\n\n`compare.html` reads `options.json` (`{title, modes, options: [{id, name, src}]}`),\nruns Elo-paired duels in side-by-side iframes (`src` is anything an iframe can\nrender), and POSTs every vote to `/vote`. `server.py` (default port 8477) serves\nthe directory and appends vote bodies to `votes.jsonl`. Set `\"modes\": true` to add\nthe light/dark axis: the harness stamps `data-mode` on each option's `<html>` and\nrecords `ui_mode` on every vote — option pages must style both modes.\n\n## Running a round\n\n1. **Frame the axis.** Name the ONE thing options vary on. Hold everything else\n   constant — same subject content in every option, one shared stylesheet — so\n   votes measure only that axis. Read any prior RESULTS.md / vote archives\n   before generating: accumulated taste constrains the option space.\n2. **Scaffold** `<slug>-lab/`: harness files, `options.json`, shared base CSS\n   (with `html[data-mode]` light/dark support when `modes` is on), `options/`\n   pages.\n3. **Generate 9–13 structurally distinct options.** If two could be confused at\n   arm's length, replace one — near-clones waste votes (a proven failure: a\n   refinement round was rejected wholesale as \"WAAAY too similar\"). Include the\n   incumbent as a control when one exists. Author one exemplar yourself, then\n   fan out parallel subagents, each writing 2–3 options from one tight shared\n   brief: subject digest, format rules, per-option spec, exemplar path. Real\n   content only — no lorem ipsum, no invented names.\n4. **QA before handing over:** every file HTTP 200 through `server.py`;\n   grep-audit for external requests, absolute home paths, secrets (none\n   allowed); check both light and dark actually render; POST a smoke vote,\n   confirm it appends to `votes.jsonl`, remove it.\n5. **Hand over and get out of the way.** Start the server in the background,\n   give the user the `compare.html` URL and the controls (←/→ pick · ↓ both\n   bad · `d` flip mode · `s` skip · `f` finish · per-vote note field). Tell\n   them: one note outweighs ten votes. Do not hover; wait for \"done\".\n6. **Analyze on \"done\".** Read `votes.jsonl`: final standings, per-mode W-L\n   splits, `both_bad` lines, head-to-head results, and every note. State the\n   user's taste as explicit, quotable rules with evidence. A note that makes a\n   decision IS the decision (round 1 of the authoring lab ended with \"use both\n   in separate pages\" — the ranking alone would have missed it).\n7. **Bank it.** Archive `votes-round<N>.jsonl`, write `RESULTS.md` (standings,\n   the decision with quoted evidence, taste rules, ship plan), update agent\n   memory. Propose round 2 from the winners — or ship. A voted winner isn't\n   done until it's shipped into the canonical templates/config it decides.\n\n## Vote record schema (what lands in votes.jsonl)\n\nEach duel vote: `{mode: \"elo\", vote, left, right, winner, loser, elo: {id: score},\nnote, ui_mode?, toggled?, lab, ts}`. Both-bad: `result: \"both_bad\"` instead of\nwinner/loser. Finish: `{mode: \"final\", votes, table: [{id, name, elo, games,\nlight?, dark?}]}`. Record every axis the user cares about as a field on every\nvote — splits you didn't record are insights lost.\n\n## Proven results (evidence this works)\n\n- 3 rounds / 130 votes chose the Instrument Panel theme for all 11 workshop\n  sites (`07-variations/template-lab/RESULTS.md`).\n- 27 votes decided workshop guides are authored as Session Replay + Socratic\n  Dialogue page pairs (`authoring-lab/RESULTS.md`).\n- In the workshop repo, `flows/this-or-that.md` runs this entire loop as an\n  mdflow flow: `md flows/this-or-that.md --_question \"...\" --_subject \"...\"`.\n\n## Whole-workshop task dispatcher\n\n```yaml\ndescription: Load the complete Agentic Software Factory workshop (John Lindquist, the recorded snapshot) — every section's machine guide, Session Replay, and Socratic Dialogue, fetched live — then perform the task.\n_inputs: [_task]\n```\n\nYou are loaded with the complete \"Agentic Software Factory\" workshop (John Lindquist, the recorded snapshot): eleven hands-on sections plus the agenda and a references/resources index. Each section appears three ways below:\n\n- **Machine guide** (`agent.md`) — the section's brief, its money artifact (prompt / script / config / kit) verbatim, and step-by-step replication instructions written for an agent to execute.\n- **Session Replay** — how the section was actually built, beat by beat, including wrong turns.\n- **Socratic Dialogue** — the reasoning and trade-offs behind the section's decisions.\n\nEverything is fetched live from the published sites at run time, so this context is always current. When a guide references a downloadable attachment (files under `skills/`, `flows/`, or zsh files at a site root), fetch it from that section's site root; `.md` attachments need `?raw` appended for the raw file (the bare URL serves an HTML viewer).\n\nGround every answer in this material. Prefer the machine guides for replication steps, the replays for \"how it really went\", and the dialogues for \"why this way\".\n\n## Task\n\n{{ _task }}\n\n## Agenda — machine-readable index of the whole workshop\n\n@https://ember-bodhi-scrr.here.now/agent.md?raw\n\n## 00 · How Agentic Work is Evolving\n\n@https://hallowed-entry-96xv.here.now/agent.md?raw\n\n!`curl -sf https://hallowed-entry-96xv.here.now/replay.html`\n\n!`curl -sf https://hallowed-entry-96xv.here.now/dialogue.html`\n\n## 01 · Configuring your environment\n\n@https://polite-ravine-6v8g.here.now/agent.md?raw\n\n!`curl -sf https://polite-ravine-6v8g.here.now/replay.html`\n\n!`curl -sf https://polite-ravine-6v8g.here.now/dialogue.html`\n\n## 02 · Custom zsh functions\n\n@https://sacred-ritual-w7as.here.now/agent.md?raw\n\n!`curl -sf https://sacred-ritual-w7as.here.now/replay.html`\n\n!`curl -sf https://sacred-ritual-w7as.here.now/dialogue.html`\n\n## 03 · Prompting with Images\n\n@https://amber-willow-n64j.here.now/agent.md?raw\n\n!`curl -sf https://amber-willow-n64j.here.now/replay.html`\n\n!`curl -sf https://amber-willow-n64j.here.now/dialogue.html`\n\n## 04 · Prompt Builder\n\n@https://shiny-bloom-f8hv.here.now/agent.md?raw\n\n!`curl -sf https://shiny-bloom-f8hv.here.now/replay.html`\n\n!`curl -sf https://shiny-bloom-f8hv.here.now/dialogue.html`\n\n## 05 · mdflow\n\n@https://walnut-virtue-6d22.here.now/agent.md?raw\n\n!`curl -sf https://walnut-virtue-6d22.here.now/replay.html`\n\n!`curl -sf https://walnut-virtue-6d22.here.now/dialogue.html`\n\n## 06 · Why Pi, Herdr, and Ghostty\n\n@https://summit-inlet-kxyf.here.now/agent.md?raw\n\n!`curl -sf https://summit-inlet-kxyf.here.now/replay.html`\n\n!`curl -sf https://summit-inlet-kxyf.here.now/dialogue.html`\n\n## 07 · Variations (9x image mockups)\n\n@https://indigo-kayak-2zw8.here.now/agent.md?raw\n\n!`curl -sf https://indigo-kayak-2zw8.here.now/replay.html`\n\n!`curl -sf https://indigo-kayak-2zw8.here.now/dialogue.html`\n\n## 10 · This or That — RLHF for Your Taste\n\n@https://gentle-lasso-9d5n.here.now/agent.md?raw\n\n!`curl -sf https://gentle-lasso-9d5n.here.now/replay.html`\n\n!`curl -sf https://gentle-lasso-9d5n.here.now/dialogue.html`\n\n## 08 · Maximum Intelligence and Video\n\n@https://shiny-rosette-m6zy.here.now/agent.md?raw\n\n!`curl -sf https://shiny-rosette-m6zy.here.now/replay.html`\n\n!`curl -sf https://shiny-rosette-m6zy.here.now/dialogue.html`\n\n## 09 · Debugging with Markers\n\n@https://mindful-mango-accy.here.now/agent.md?raw\n\n!`curl -sf https://mindful-mango-accy.here.now/replay.html`\n\n!`curl -sf https://mindful-mango-accy.here.now/dialogue.html`\n\n## References & Resources — tool alternatives\n\n@https://dewy-sleet-n5zs.here.now/agent.md?raw"
    },
    {
      "id": "codex-workspace-routing-reference",
      "slug": "workspace-routing-reference",
      "title": "Workspace and session routing: practical reference",
      "summary": "Practical cmux/tmux orchestration reference with an agent setup prompt, workspace/pane/surface/session routing model, focused Codex fork and compact workflows, transcript exports, zsh helper integration, multi-agent layouts and gated chains, verification…",
      "category": "Execution",
      "tags": [
        "cmux",
        "tmux",
        "orchestration"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/cmux vs tmux",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Address The Current Context",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Get The Current Workspace Correctly",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Know The cmux Environment Variables",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Create A Helper Pane",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Focus Or Open A Project Workspace",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Fork The Focused Codex Session",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Stable Surface IDs And The Registry",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Export A Transcript",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/How Helpers Connect To Routing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/tmux Layouts And Agent Chains",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Invalid Workspace Handle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Wrong Session Fork",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Missing `.exports`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Function Not Found",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 2703,
      "url": "/topics/codex-workspace-routing-reference/",
      "markdownUrl": "/markdown/codex-workspace-routing-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-workspace-routing-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "cmux-vs-tmux",
          "text": "cmux vs tmux",
          "level": 2
        },
        {
          "id": "address-the-current-context",
          "text": "Address The Current Context",
          "level": 2
        },
        {
          "id": "get-the-current-workspace-correctly",
          "text": "Get The Current Workspace Correctly",
          "level": 2
        },
        {
          "id": "know-the-cmux-environment-variables",
          "text": "Know The cmux Environment Variables",
          "level": 2
        },
        {
          "id": "create-a-helper-pane",
          "text": "Create A Helper Pane",
          "level": 2
        },
        {
          "id": "focus-or-open-a-project-workspace",
          "text": "Focus Or Open A Project Workspace",
          "level": 2
        },
        {
          "id": "fork-the-focused-codex-session",
          "text": "Fork The Focused Codex Session",
          "level": 2
        },
        {
          "id": "stable-surface-ids-and-the-registry",
          "text": "Stable Surface IDs And The Registry",
          "level": 2
        },
        {
          "id": "export-a-transcript",
          "text": "Export A Transcript",
          "level": 2
        },
        {
          "id": "how-helpers-connect-to-routing",
          "text": "How Helpers Connect To Routing",
          "level": 2
        },
        {
          "id": "tmux-layouts-and-agent-chains",
          "text": "tmux Layouts And Agent Chains",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "invalid-workspace-handle",
          "text": "Invalid Workspace Handle",
          "level": 3
        },
        {
          "id": "wrong-session-fork",
          "text": "Wrong Session Fork",
          "level": 3
        },
        {
          "id": "missing-exports",
          "text": "Missing `.exports`",
          "level": 3
        },
        {
          "id": "function-not-found",
          "text": "Function Not Found",
          "level": 3
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Workspace and session routing: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the local cmux/tmux agent orchestration files and configuration for this software project. Inspect the existing local files first, preserve any working behavior, and create or update only the narrow launcher, hook, and zsh helper pieces needed for reliable routing.\n\nWork step by step:\n\n1. Confirm prerequisites and current routing context.\n   - Run `which cmux`, `which tmux`, `which zsh`, `which python3`, and `which node`.\n   - Run `cmux identify` and capture `caller`, `focused`, `workspace_ref`, `pane_ref`, `surface_ref`, `tab_ref`, and `socket_path`.\n   - Run `cmux rpc workspace.current` and capture `workspace.current_directory`, `workspace_id`, and `window_id`.\n   - If the current workspace cwd is not the intended project, use `cmux-focus-or-open-workspace /path/to/project`, then re-run the checks.\n   - Never use `--workspace current` as a workspace handle. Resolve the current workspace first, then use the explicit id or ref.\n\n2. Inspect or create the cmux launcher files.\n   - `~/.config/cmux/cmux.json`\n   - `~/.config/cmux/scripts/cmux-xport.sh`\n   - `~/.local/bin/cmux-run-surface`\n   - `~/.local/bin/cmux-fork-focused-codex`\n   - `~/.local/bin/cmux-focus-or-open-workspace`\n   - `~/.local/bin/cmux-xport`\n   - `~/.local/bin/cmux-xport-markdown`\n   Ensure executable launcher files are executable. Do not overwrite existing scripts blindly; diff or summarize the existing behavior first.\n\n3. Wire workspace, pane, surface, tab, process, and session mapping.\n   - Treat the routing graph as `workspace -> pane -> surface/tab -> process/session -> receipt`.\n   - `cmux-run-surface` must resolve the workspace with `cmux rpc workspace.current`, create a pane with explicit workspace/window/pane refs, inspect surfaces with `cmux rpc pane.surfaces`, send the requested command to the intended surface, and press Enter.\n   - Support right split by default and `--below` for below split.\n   - Confirm commands run from the focused workspace cwd and inherit `CMUX_SURFACE_ID`, `CMUX_WORKSPACE_ID`, `CMUX_TAB_ID`, and `CMUX_SOCKET_PATH`.\n\n4. Set up focused Codex session routing.\n   - `cmux-fork-focused-codex` must prefer `.caller.surface_ref` when present, then fall back to `.focused.surface_ref`.\n   - Normalize short surface refs through `cmux rpc pane.surfaces '{\"pane_id\":\"pane:<id>\",\"workspace_id\":\"workspace:<id>\",\"window_id\":\"window:<id>\"}'`.\n   - Resolve the Codex session through `python3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" --resolve-surface \"surface:<stable-surface-id>\"`.\n   - Hand off fork mode as `CODEX_FORK_SESSION_ID=<uuid> p-f`.\n   - Hand off compact mode as `CODEX_FORK_SESSION_ID=<uuid> p-c`, with `--below` supported.\n   - Do not use `fork --last` as a substitute for focused surface routing.\n\n5. Inspect or create the Codex hook registry files.\n   - `~/.codex/hooks/cmux-codex-session-registry.py`\n   - `~/.codex/hooks/cmux-auto-name-tab.zsh`\n   - `~/.codex/hooks/codex-thread-name-set.mjs`\n   The registry must map stable cmux surface ids to Codex session UUIDs. Keep screen scraping or `--allow-screen` as fallback only, and report when fallback was required.\n\n6. Set up transcript exports.\n   - `cmux-xport` must resolve the focused workspace cwd, `cd` there, set `CODEX_XPORT_SAVE_CWD=1`, load the zsh helper path that defines `xport`, copy the transcript to the clipboard when available, and save a non-empty markdown file under `.exports/<timestamp>.md`.\n   - `cmux-xport-markdown` should open or surface the saved markdown export without pasting the full transcript into chat.\n\n7. Wire tmux, muxai, and agent_chain.\n   - Inspect `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh`, `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh`, and `~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh`.\n   - Confirm `muxai` resolves for terminal-only multi-agent layouts.\n   - Confirm `agent_chain` resolves for gated multi-step software work.\n   - If a helper is a zsh function (`p-f`, `p-c`, `xport`, `xfl`, `xfc`, `muxai`, `agent_chain`), either load it through the intended zsh startup path or provide a small executable wrapper for non-zsh callers.\n\n8. Respect privacy boundaries.\n   - Do not paste full `env` output.\n   - Do not expose API keys, tokens, cookies, provider variables, private endpoints, or credentials from config, hook, shell, or transcript files.\n   - Do not copy private local config verbatim when a structure summary is enough.\n   - Keep transcript exports local under `.exports` unless explicitly asked to share them.\n   - Report session ids and surface ids only when needed to prove routing, and avoid including transcript content in the report.\n\n9. Run verification commands before declaring setup complete.\n   - `cmux identify`\n   - `cmux rpc workspace.current`\n   - `printf 'surface=%s\\nworkspace=%s\\ntab=%s\\nsocket=%s\\n' \"$CMUX_SURFACE_ID\" \"$CMUX_WORKSPACE_ID\" \"$CMUX_TAB_ID\" \"$CMUX_SOCKET_PATH\"`\n   - `cmux-run-surface \"pwd; echo surface=$CMUX_SURFACE_ID\"`\n   - `cmux-run-surface --below \"pwd; echo surface=$CMUX_SURFACE_ID\"`\n   - `cmux-fork-focused-codex --dry-run --preflight-fork`\n   - `cmux-fork-focused-codex --dry-run --below --preflight-compact`\n   - `ls -lt .exports | head`\n   - `test -s \"$(ls -t .exports/*.md | head -1)\" && echo export:OK`\n   - `zsh -ic 'whence -w muxai; funcwhere muxai'`\n   - `zsh -ic 'whence -w agent_chain; funcwhere agent_chain'`\n   - `zsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport xfl xfc'`\n\n10. Report results plainly.\n   - List files inspected.\n   - List files created or edited.\n   - List files intentionally left untouched.\n   - For each verification command, report pass/fail and the key output.\n   - If anything is missing, broken, private, or ambiguous, stop and explain the blocker instead of claiming setup is complete.\n```\n\n## Big Idea\n\nPhase: Routing And Composition - once context and helper boundaries are clear, route the work to the right workspace, pane, and session.\n\nFocused context is a routing problem, not a prompt problem.\n\n## Try This Now\n\nFrom the project workspace, run: `cmux identify`.\nThen run: `cmux rpc workspace.current`.\nDo not launch a helper pane until the workspace cwd and focused surface match the project you mean.\n\nOnce you have the right project context, shell environment, and zsh helpers, the next question is:\n\n```text\nWhich agent is doing what, in which workspace, in which pane, against which\nsession, and what proof can I save?\n```\n\nTreat the environment as an addressable graph:\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\nA better prompt cannot fix bad routing. First route the action to the correct surface and session.\n\n## Files To Inspect\n\nCommon local orchestrator files and scripts:\n\n```text\n~/.config/cmux/cmux.json\n~/.config/cmux/scripts/cmux-xport.sh\n~/.local/bin/cmux-run-surface\n~/.local/bin/cmux-fork-focused-codex\n~/.local/bin/cmux-focus-or-open-workspace\n~/.local/bin/cmux-xport\n~/.local/bin/cmux-xport-markdown\n~/.codex/hooks/cmux-codex-session-registry.py\n~/.codex/hooks/cmux-auto-name-tab.zsh\n~/.codex/hooks/codex-thread-name-set.mjs\n~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh\n~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh\n~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh\n```\n\n## When To Reach For This\n\nUse this workflow when you need to:\n\n- open a helper pane next to the current work\n- fork or compact the Codex conversation in the pane you are looking at\n- export a Codex transcript into `.exports`\n- focus or open a project workspace by directory\n- run a visible multi-agent layout\n- move from one-off helper commands to gated multi-step orchestration\n- debug a shortcut that targets the wrong conversation\n- prove where a command ran and what session it belonged to\n\nFocus on practical routing for software project work. Skip tmux and cmux internals that do not affect the current workspace, pane, session, or receipt.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nThe newest terminal, pane, or agent session is probably the one you meant.\n```\n\nWhat the workflow gives you now:\n\n```text\nAsk the orchestrator where you are, use stable ids, launch helpers in known\npanes, and save transcripts when the session becomes part of the work.\n```\n\n## The Mental Model\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\n| Layer | What It Means | What To Check |\n| --- | --- | --- |\n| `workspace` | project container, usually with a current directory | `cmux rpc workspace.current` |\n| `pane` | visible split region inside a workspace | `pane_ref`, `cmux rpc pane.create` |\n| `surface` | addressable terminal/browser/editor target inside a pane | `surface_ref`, `CMUX_SURFACE_ID` |\n| `tab` | human-facing label for a surface | `tab_ref`, `CMUX_TAB_ID` |\n| process | running program | `zsh`, `codex`, `tmux`, `xport`, `p-f`, `p-c` |\n| session | durable agent identity | Codex session UUID |\n| receipt | proof you can inspect later | `.exports/<timestamp>.md`, registry, logs, reports |\n\nPractical language:\n\n```text\nA pane is where work is visible.\nA session is what work belongs to.\nA receipt is what makes work resumable.\n```\n\n## cmux vs tmux\n\n`cmux` and `tmux` solve different layers.\n\n| Tool | Role | Use It For |\n| --- | --- | --- |\n| `cmux` | GUI/socket/workspace orchestrator | workspaces, panes, surfaces, browser/editor panels, focused context, keyboard launchers |\n| `tmux` | terminal multiplexer layout primitive | terminal-only layouts, persistent sessions, panes/windows, CLI fanout, `muxai` layouts |\n\nPractical line:\n\n```text\ncmux is the building. tmux is one kind of room layout inside the building.\n```\n\n## Address The Current Context\n\nStart here:\n\n```bash\ncmux identify\n```\n\nLook for:\n\n- `caller`: the surface that invoked the command\n- `focused`: the surface cmux believes is focused\n- `workspace_ref`: project/workspace target\n- `pane_ref`: visible split target\n- `surface_ref`: addressable surface target\n- `tab_ref`: human-facing tab target\n- `socket_path`: socket used by local automation\n\nFor keyboard launchers, prefer the caller surface when present:\n\n```text\n.caller.surface_ref // .focused.surface_ref\n```\n\nThis prevents a shortcut from accidentally targeting a different visible pane.\n\n## Get The Current Workspace Correctly\n\nUse:\n\n```bash\ncmux rpc workspace.current\n```\n\nLook for:\n\n- `workspace.current_directory`\n- `workspace_id`\n- `window_id`\n\nDo not assume this works:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nObserved failure shape:\n\n```text\nError: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index)\n```\n\nRule:\n\n```text\n\"Current\" is a question, not a workspace handle.\nAsk cmux for current state, then use the returned explicit ref/id.\n```\n\n## Know The cmux Environment Variables\n\nInside cmux terminal surfaces, scripts can use:\n\n```text\nCMUX_SURFACE_ID\nCMUX_WORKSPACE_ID\nCMUX_TAB_ID\nCMUX_SOCKET_PATH\n```\n\nQuick check:\n\n```bash\nprintf 'surface=%s\\nworkspace=%s\\ntab=%s\\nsocket=%s\\n' \\\n  \"$CMUX_SURFACE_ID\" \"$CMUX_WORKSPACE_ID\" \"$CMUX_TAB_ID\" \"$CMUX_SOCKET_PATH\"\n```\n\nIf those values are empty, you may not be inside a cmux terminal surface, or the process may not have inherited the cmux environment.\n\n## Create A Helper Pane\n\nShortcut:\n\n```text\ncmux-run-surface \"command\"\n```\n\nRight split:\n\n```bash\ncmux-run-surface \"pwd; echo surface=$CMUX_SURFACE_ID\"\n```\n\nBelow split:\n\n```bash\ncmux-run-surface --below \"pwd; echo surface=$CMUX_SURFACE_ID\"\n```\n\nWhat the launcher does:\n\n```text\ncmux rpc workspace.current\n-> cmux rpc pane.create\n-> cmux rpc pane.surfaces\n-> cmux send \"<command>\"\n-> cmux send-key enter\n```\n\nHow to know it worked:\n\n- a new cmux pane appears\n- the command text is visible in that pane\n- Enter was submitted\n- the command runs from the focused workspace cwd\n- `CMUX_SURFACE_ID` is set inside the new terminal\n\n## Focus Or Open A Project Workspace\n\nShortcut:\n\n```text\ncmux-focus-or-open-workspace /path/to/project\n```\n\nUse this when the problem starts with a directory or repo, not with a visible pane.\n\nWhat the launcher should do:\n\n```text\nfind existing cmux workspace for the project\n-> focus it if it exists\n-> open a new workspace if it does not\n-> keep later helper panes and forks anchored to that project cwd\n```\n\nHow to know it worked:\n\n```bash\ncmux rpc workspace.current\n```\n\nLook for the expected project directory in `workspace.current_directory` before launching helper panes or agent chains.\n\n## Fork The Focused Codex Session\n\nShortcut:\n\n```text\nEsc+P\n```\n\nActual route:\n\n```text\nEsc+P\n-> cmux-fork-focused-codex --preflight-fork\n-> cmux identify\n-> caller/focused surface\n-> cmux rpc pane.surfaces\n-> stable surface id\n-> cmux-codex-session-registry.py --resolve-surface\n-> Codex session id\n-> CODEX_FORK_SESSION_ID=<session-id> p-f\n-> cmux-run-surface\n-> new pane\n```\n\nDry-run first:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nCompact fork below:\n\n```bash\ncmux-fork-focused-codex --dry-run --below --preflight-compact\n```\n\nShortcut mapping:\n\n| Shortcut | Route |\n| --- | --- |\n| `Esc+P` | focused Codex session -> `p-f` |\n| `Esc+Shift+P` | focused Codex session -> compact -> `p-c` below |\n| `Esc+E` | export focused workspace transcript with `cmux-xport` |\n| `Esc+M` | export transcript and open markdown |\n\nWhy this matters:\n\n```text\nfork --last is not the same as fork the conversation in the focused pane.\n```\n\n## Stable Surface IDs And The Registry\n\nShort refs such as `surface:38` are useful in current output, but they are not the durable routing key.\n\nFocused fork should normalize the short surface ref through:\n\n```bash\ncmux rpc pane.surfaces '{\"pane_id\":\"pane:<id>\",\"workspace_id\":\"workspace:<id>\",\"window_id\":\"window:<id>\"}'\n```\n\nThen resolve the Codex session through:\n\n```bash\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" \\\n  --resolve-surface \"surface:<stable-surface-id>\"\n```\n\nScreen fallback exists, but should be fallback only:\n\n```bash\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" \\\n  --resolve-surface \"surface:<id>\" --allow-screen\n```\n\n## Export A Transcript\n\nShortcut:\n\n```text\nEsc+E\n```\n\nCommand:\n\n```bash\ncmux-xport\n```\n\nRoute:\n\n```text\ncmux-xport\n-> cmux rpc workspace.current\n-> cd focused workspace cwd\n-> CODEX_XPORT_SAVE_CWD=1\n-> source ~/.config/zsh/conf.d/40-ai.zsh\n-> xport\n-> clipboard\n-> .exports/<timestamp>.md\n-> notification\n```\n\nHow to know it worked:\n\n```bash\nls -lt .exports | head\ntest -s \"$(ls -t .exports/*.md | head -1)\" && echo export:OK\n```\n\nPractical line:\n\n```text\nClipboard is convenience. .exports is the durable receipt.\n```\n\n## How Helpers Connect To Routing\n\nFirst identify whether the helper is a zsh function, alias, executable, or environment variable.\n\nThen route it to the workspace, pane, surface, or session where it should run.\n\nCommon bridge helpers:\n\n| Helper | What It Does Here |\n| --- | --- |\n| `xfl` | find the Codex session or thread you intend to work with |\n| `xfc` | continue or fork from the chosen Codex context |\n| `xport` | export a Codex conversation from the current project cwd |\n| `p-f` | launch a forked Codex path after the target session is known |\n| `p-c` | launch a compacted Codex path after the target session is known |\n\nIf the command is a zsh function, either run it through the zsh startup path that loads it or use the executable wrapper that the orchestrator expects.\n\n## tmux Layouts And Agent Chains\n\nValidate `muxai`:\n\n```zsh\nzsh -ic 'whence -w muxai; funcwhere muxai'\n```\n\nUse `muxai` when you want a terminal-only multi-agent room inside a surface.\n\nValidate `agent_chain`:\n\n```zsh\nzsh -ic 'whence -w agent_chain; funcwhere agent_chain'\n```\n\nUse it for software work where you want phase separation:\n\n```zsh\nagent_chain \"Explore the billing webhook duplicate-processing bug, plan the smallest safe patch, then implement only if tests can verify it.\"\n```\n\nGood uses:\n\n- refactor with a real review gate\n- bug investigation before edit\n- small feature with a plan checkpoint\n- risky implementation that needs a danger confirmation\n\nBad use:\n\n```text\nagent_chain \"fix everything\"\n```\n\n## Ask The Agent This\n\nRoute a helper pane:\n\n```text\nUse the cmux orchestrator source files.\n\nOpen a helper pane for this software project. It should run from the focused\nworkspace cwd and inspect the checkout flow failure without editing files.\nUse cmux routing, not manual terminal instructions. Tell me how to confirm the\npane was created and where to check logs if it fails.\n```\n\nDebug a wrong focused fork:\n\n```text\nEsc+P forked the wrong Codex conversation.\n\nInspect the focused-fork route: `cmux identify`, caller versus focused surface,\n`cmux rpc pane.surfaces`, stable surface lookup, the Codex cmux registry,\n`CODEX_FORK_SESSION_ID`, and the `p-f` handoff. Do not assume `fork --last` is\ncorrect. Give me the dry-run command that proves the target session id before\nlaunching.\n```\n\nExport a conversation:\n\n```text\nExport the focused Codex conversation for this project.\n\nUse `cmux-xport` or the equivalent `CODEX_XPORT_SAVE_CWD=1` zsh path. Confirm\nthe export was copied to the clipboard and saved under `.exports`. Do not paste\nthe whole transcript back into chat.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| Identify current context | `cmux identify` shows caller/focused workspace, pane, surface, tab |\n| Get current workspace | `cmux rpc workspace.current` shows cwd, workspace id, window id |\n| Avoid fake current handle | no command depends on `--workspace current` |\n| Create helper pane | `cmux-run-surface \"echo ok\"` opens a pane and runs from intended cwd |\n| Route focused fork | dry-run prints `CODEX_FORK_SESSION_ID=<uuid> p-f` or `p-c` |\n| Export transcript | `.exports/<timestamp>.md` exists and is non-empty |\n| tmux layout present | `tmux ls` and `tmux list-panes -a` show expected panes |\n| agent chain scoped | goal names a specific software bug or feature and verification command |\n\n## If It Goes Wrong\n\n### Invalid Workspace Handle\n\nBad:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nCorrect:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ncmux rpc workspace.list\n```\n\n### Wrong Session Fork\n\nDry-run:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nCorrect route:\n\n```text\nfocused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID\n```\n\n### Missing `.exports`\n\nCheck:\n\n```bash\nls -lt .exports | head\n```\n\nDirect save shape:\n\n```zsh\nCODEX_XPORT_SAVE_CWD=1 zsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; xport'\n```\n\n### Function Not Found\n\nCheck:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\n```\n\nSome orchestration commands are zsh functions. Launch them through zsh or provide executable wrappers.\n\n## References And Resources\n\n- Common cmux config: `~/.config/cmux/cmux.json`\n- Common pane launcher: `~/.local/bin/cmux-run-surface`\n- Common focused fork launcher: `~/.local/bin/cmux-fork-focused-codex`\n- Common xport launcher: `~/.local/bin/cmux-xport`\n- Common registry hook: `~/.codex/hooks/cmux-codex-session-registry.py`\n- Common tmux helper source: `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh`\n- Common agent chain source: `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh`\n- tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html\n- tmux GitHub wiki: https://github.com/tmux/tmux/wiki\n- OpenAI Codex: https://openai.com/codex/\n- Model Context Protocol: https://modelcontextprotocol.io/\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-workspace-routing-practice",
      "slug": "workspace-routing-practice",
      "title": "Workspace and session routing: practice drills",
      "summary": "Nine exercises establish workspace-to-session routing and receipts using cmux identity, explicit handles, workspace focus, environment inspection, helper panes, focused Codex fork previews, transcript exports, layered debugging, and gated agent_chain phases.",
      "category": "Execution",
      "tags": [
        "cmux",
        "tmux",
        "orchestration",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 1: Address The Current Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 2: Prove The `current` Handle Failure",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 3: Focus Or Open A Workspace",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 4: Capture The cmux Environment",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 5: Open A Safe Helper Pane",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 6: Dry-Run A Focused Codex Fork",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 7: Export A Transcript",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 8: Decide Whether It Is cmux Or tmux",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 9: Design A Gated `agent_chain` Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "execution",
      "wordCount": 724,
      "url": "/topics/codex-workspace-routing-practice/",
      "markdownUrl": "/markdown/codex-workspace-routing-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-workspace-routing-practice.json",
      "headings": [
        {
          "id": "exercise-1-address-the-current-work",
          "text": "Exercise 1: Address The Current Work",
          "level": 2
        },
        {
          "id": "exercise-2-prove-the-current-handle-failure",
          "text": "Exercise 2: Prove The `current` Handle Failure",
          "level": 2
        },
        {
          "id": "exercise-3-focus-or-open-a-workspace",
          "text": "Exercise 3: Focus Or Open A Workspace",
          "level": 2
        },
        {
          "id": "exercise-4-capture-the-cmux-environment",
          "text": "Exercise 4: Capture The cmux Environment",
          "level": 2
        },
        {
          "id": "exercise-5-open-a-safe-helper-pane",
          "text": "Exercise 5: Open A Safe Helper Pane",
          "level": 2
        },
        {
          "id": "exercise-6-dry-run-a-focused-codex-fork",
          "text": "Exercise 6: Dry-Run A Focused Codex Fork",
          "level": 2
        },
        {
          "id": "exercise-7-export-a-transcript",
          "text": "Exercise 7: Export A Transcript",
          "level": 2
        },
        {
          "id": "exercise-8-decide-whether-it-is-cmux-or-tmux",
          "text": "Exercise 8: Decide Whether It Is cmux Or tmux",
          "level": 2
        },
        {
          "id": "exercise-9-design-a-gated-agent-chain-goal",
          "text": "Exercise 9: Design A Gated `agent_chain` Goal",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Workspace and session routing: practice drills\n\nThese exercises practice routing work through the agentic dev environment.\n\nThe goal is to prove:\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\nUse a real software project directory when possible. Prefer dry-runs before launching anything.\n\n## Exercise 1: Address The Current Work\n\nRun:\n\n```bash\ncmux identify\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# cmux Address Notes\n\n- workspace_ref:\n- workspace_id:\n- workspace cwd:\n- window_id:\n- pane_ref:\n- surface_ref:\n- tab_ref:\n- surface_type:\n- caller/focused same? yes/no\n- command that should target this surface:\n```\n\n## Exercise 2: Prove The `current` Handle Failure\n\nRun:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nThen run:\n\n```bash\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# Workspace Handle Notes\n\n- failed command:\n- exact error:\n- correct command:\n- returned workspace id/ref:\n- returned cwd:\n- lesson:\n```\n\nExpected lesson:\n\n```text\n`current` is not a workspace handle. Ask cmux for current state, then use explicit refs or ids.\n```\n\n## Exercise 3: Focus Or Open A Workspace\n\nChoose a software project directory and run:\n\n```bash\ncmux-focus-or-open-workspace /path/to/project\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# Workspace Focus Notes\n\n- project path:\n- did cmux focus an existing workspace or open a new one:\n- workspace cwd:\n- workspace id/ref:\n- next command that should run from this cwd:\n```\n\n## Exercise 4: Capture The cmux Environment\n\nInside a cmux terminal, run:\n\n```bash\nprintf 'surface=%s\\nworkspace=%s\\ntab=%s\\nsocket=%s\\n' \\\n  \"$CMUX_SURFACE_ID\" \"$CMUX_WORKSPACE_ID\" \"$CMUX_TAB_ID\" \"$CMUX_SOCKET_PATH\"\n```\n\nFill out:\n\n```markdown\n# cmux Env Notes\n\n- CMUX_SURFACE_ID:\n- CMUX_WORKSPACE_ID:\n- CMUX_TAB_ID:\n- CMUX_SOCKET_PATH:\n- which value identifies the smallest routing target:\n- which value would a registry hook need:\n- which value helps external automation talk to cmux:\n```\n\n## Exercise 5: Open A Safe Helper Pane\n\nRun:\n\n```bash\ncmux-run-surface 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'\n```\n\nOptional below split:\n\n```bash\ncmux-run-surface --below 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'\n```\n\nFill out:\n\n```markdown\n# Helper Pane Notes\n\n- command:\n- right or below:\n- did a new pane open? yes/no\n- cwd printed:\n- surface id printed:\n- did the command submit automatically? yes/no\n- if failed, log checked:\n```\n\n## Exercise 6: Dry-Run A Focused Codex Fork\n\nFocus a cmux pane that has a Codex conversation.\n\nRun:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nThen run:\n\n```bash\ncmux-fork-focused-codex --dry-run --below --preflight-compact\n```\n\nFill out:\n\n```markdown\n# Focused Fork Notes\n\n- fork command output:\n- compact command output:\n- includes CODEX_FORK_SESSION_ID? yes/no\n- launches `p-f` or `p-c`?\n- target session id:\n- why this is safer than `fork --last`:\n```\n\n## Exercise 7: Export A Transcript\n\nRun:\n\n```bash\ncmux-xport\nls -lt .exports | head\n```\n\nThen verify latest export is non-empty:\n\n```bash\nlatest=\"$(ls -t .exports/*.md 2>/dev/null | head -1)\"\ntest -n \"$latest\" && test -s \"$latest\" && echo \"export:OK $latest\" || echo \"export:MISSING\"\n```\n\nFill out:\n\n```markdown\n# xport Notes\n\n- command:\n- workspace cwd:\n- latest export file:\n- file exists? yes/no\n- file non-empty? yes/no\n- what this export can prove later:\n```\n\n## Exercise 8: Decide Whether It Is cmux Or tmux\n\nFor each failure, choose `cmux`, `tmux`, `zsh`, or `Codex registry`.\n\n| Failure | Layer |\n| --- | --- |\n| `cmux identify` cannot connect to socket | |\n| `cmux-run-surface` cannot create a pane | |\n| `muxai` creates a weird tiled layout | |\n| `p-f: command not found` | |\n| `Esc+P` targets the wrong Codex UUID | |\n| `.exports` is missing after xport | |\n| `tmux ls` shows no expected session | |\n| `CMUX_SURFACE_ID` is empty inside a hook | |\n\nUseful commands:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ntmux ls\ntmux list-panes -a\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" --registry-path\n```\n\n## Exercise 9: Design A Gated `agent_chain` Goal\n\nBad:\n\n```text\nfix everything\n```\n\nBetter template:\n\n```text\nExplore <specific bug or feature>, plan the smallest safe patch, then implement\nonly if <verification command> can prove it.\n```\n\nWrite your goal:\n\n```markdown\n# agent_chain Goal\n\nagent_chain \"<goal>\"\n```\n\nFill out expected reports:\n\n```markdown\n# Expected Phase Receipts\n\n## Explore\n\n- files inspected:\n- hypothesis:\n- risks:\n\n## Plan\n\n- smallest patch:\n- tests:\n- rollback:\n\n## Implement\n\n- files changed:\n- verification command:\n- result:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "foundations-five-monkeys-playbook",
      "slug": "five-monkeys-playbook",
      "title": "5 Monkeys QA swarm playbook",
      "summary": "Web developers already trust tests for known requirements, but fast-moving UI work also needs cheap exploratory passes that click through real app state. This technique gives local agents a practical browser-facing QA job: find weird UX and state bugs before users do.",
      "category": "Verification",
      "tags": [
        "QA",
        "testing",
        "perspectives",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#five-monkeys",
        "scenarios/five-monkeys.json#audienceFit",
        "toolkit/prompts/05-five-monkeys-qa-swarm.md",
        "toolkit/codex-skills/five-monkeys-qa/SKILL.md",
        "scenarios/five-monkeys.json#scenarios/0",
        "scenarios/five-monkeys.json#scenarios/1",
        "scenarios/five-monkeys.json#scenarios/2",
        "scenarios/five-monkeys.json#implementationNotes",
        "scenarios/five-monkeys.json#notTaughtOrAvoid/1",
        "scenarios/five-monkeys.json#notTaughtOrAvoid/2",
        "scenarios/five-monkeys.json#notTaughtOrAvoid/3",
        "scenarios/five-monkeys.json#notTaughtOrAvoid/4",
        "scenarios/five-monkeys.json#notTaughtOrAvoid/5",
        "scenarios/five-monkeys.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "verification",
      "wordCount": 2235,
      "url": "/topics/foundations-five-monkeys-playbook/",
      "markdownUrl": "/markdown/foundations-five-monkeys-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-five-monkeys-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "authenticated-dashboard-weird-path-pass",
          "text": "Authenticated dashboard weird-path pass",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "checkout-flow-state-bug-hunt-before-release",
          "text": "Checkout flow state-bug hunt before release",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "stress-test-a-pricing-plan-upgrade-flow",
          "text": "Stress-test a pricing-plan upgrade flow",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "existing-5-monkeys-prompt",
          "text": "Existing 5 Monkeys prompt",
          "level": 3
        },
        {
          "id": "existing-five-monkeys-codex-skill",
          "text": "Existing five-monkeys Codex skill",
          "level": 3
        },
        {
          "id": "validated-lesson-05-references",
          "text": "Validated lesson 05 references",
          "level": 3
        },
        {
          "id": "lesson-05-validation-notes",
          "text": "Lesson 05 validation notes",
          "level": 3
        },
        {
          "id": "cmux-state-and-pane-commands",
          "text": "CMUX state and pane commands",
          "level": 3
        }
      ],
      "markdown": "# 5 Monkeys QA swarm playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already trust tests for known requirements, but fast-moving UI work also needs cheap exploratory passes that click through real app state. This technique gives local agents a practical browser-facing QA job: find weird UX and state bugs before users do.\n\n[Core principles](/topics/foundations-perspective-qa-and-testing/)\n\n## Copy-paste workflow\n\n**When to use:** When you want to surface state bugs and UX dead ends a happy-path check would miss. This launches many cheap agents that click around in weird, non-obvious ways from assigned perspectives, recording findings to discardable QA files.\n\n### Copy-paste prompt\n\n```text\nRun a \"5 Monkeys\" QA swarm on <APP/FEATURE>. The point is to find state bugs and UX dead ends the happy path would never reveal — so do NOT just walk the happy path.\n\n1. Assign yourself (or each worker agent) a PERSPECTIVE lens and stay in character:\n     expert power user / brand-new first-time user / a grandparent / impatient power user.\n\n2. Explore WEIRD, non-obvious paths explicitly:\n     - keyboard shortcut sequences\n     - back/forward navigation mid-flow\n     - repeated/rapid clicks on the same control\n     - toggling modes back and forth\n     - partial or abandoned flows (start, then bail)\n   Try to break state, not to succeed.\n\n3. Write findings to a DISCARDABLE numbered QA markdown file (e.g. .notes/qa-01.md). These are cheap — regenerate freely.\n\n4. After the runs, collate the findings and keep ONLY the useful ones.\n\nGuardrails: keep rigorous tests for stable business logic — don't over-test UI you still expect to reshape daily. If you use a browser agent, script the auth/login path explicitly: cookies are NOT shared.\n```\n\n### How it works\n- Each agent gets a perspective lens (expert, brand-new user, grandparent, power user) and explores the app in character.\n- Agents deliberately explore weird paths — shortcut sequences, back navigation, repeated clicks, mode toggles, partial/abandoned flows — instead of the happy path, which is where state bugs hide.\n- Findings go to discardable numbered QA markdown files (cheap, regenerate freely); collate afterward and keep only the useful ones.\n- Keep rigorous automated tests for stable business logic; don't over-test UI you still expect to reshape daily.\n- If using a browser agent, script the auth/login path explicitly — cookies are not shared between agents.\n- Reference: [Agent Browser](https://github.com/vercel-labs/agent-browser).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/five-monkeys-qa/SKILL.md`, then restart Codex.\n\n```markdown\n---\nname: five-monkeys-qa\ndescription: Trigger when you want to surface state bugs and UX dead ends a happy-path check would miss — launch perspective-based agents that explore weird, non-obvious paths and write findings to discardable QA files. Do NOT use to replace rigorous tests for stable business logic.\n---\n\n# 5 Monkeys QA\n\nLaunch cheap perspective-based agents that explore the app in weird, non-obvious ways to surface state bugs and UX dead ends the happy path would never reveal. Findings go to discardable QA files.\n\n## Steps\n\n1. Assign each agent a PERSPECTIVE lens and have it stay in character:\n   - expert power user\n   - brand-new first-time user\n   - a grandparent\n   - impatient power user\n\n2. Explore WEIRD, non-obvious paths explicitly (not the happy path):\n   - keyboard shortcut sequences\n   - back/forward navigation mid-flow\n   - repeated / rapid clicks on the same control\n   - toggling modes back and forth\n   - partial or abandoned flows (start, then bail)\n\n3. Each agent writes findings to a DISCARDABLE numbered QA markdown file (e.g. `.notes/qa-01.md`). They are cheap — regenerate freely.\n\n4. Collate the findings and keep ONLY the useful ones.\n\n## Guardrails\n- Keep rigorous automated tests for STABLE business logic — this does not replace them, and don't over-test UI you still expect to reshape daily.\n- If using a browser agent, script the auth/login path explicitly — cookies are NOT shared.\n```\n\n## Scenarios\n\n### Authenticated dashboard weird-path pass\n\n**Role:** As a frontend engineer shipping an authenticated Next.js dashboard\n\nA Next.js app has a local dev server, a login flow, route-level navigation, filter panels, modal dialogs, and a dashboard state that often changes during product iteration.\n\n> As a frontend engineer, I want several perspective-driven agents to explore non-happy-path dashboard behavior, so that I can catch stuck state, broken back navigation, and confusing UI before merging.\n\n#### Agent brief\n\n```text\nRun a 5 Monkeys QA swarm against the authenticated dashboard. First inspect the repo for the dev command and any documented test user or seeded auth flow. Start the app locally using the repo’s normal command, such as npm run dev, pnpm dev, or the command documented in package.json/README. Create .notes/qa-dashboard-swarm.md as a discardable numbered QA file. Assign five lenses: expert power user, brand-new first-time user, grandparent/inexperienced user, impatient power user, and distracted returning user. For each lens, use a browser workflow against localhost and deliberately avoid only confirming the happy path. Try: login, navigate to the dashboard, open filters, toggle modes, click the same controls repeatedly, use browser back/forward mid-flow, abandon a modal halfway through, refresh after changing state, and return to the page. Record each finding with: perspective, exact path, expected behavior, observed behavior, severity, and whether it looks like stable business logic or fast-changing UI. Expected output: .notes/qa-dashboard-swarm.md plus a short final summary of the 3-7 useful findings only.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n[Open reference](/topics/foundations-perspective-qa-and-testing/)\n\n```text\npackage.json\n```\n\n```text\nREADME.md\n```\n\n```text\ncmux --json tree\n```\n\n```text\ncmux read-screen\n```\n\n```text\ncmux markdown open .notes/qa-dashboard-swarm.md --direction right\n```\n\n#### Browser verification\n\nUse an agent-browser-style pass or CMUX browser pane against the local URL. Take an accessibility snapshot after login, click through navigation and controls, fill the login form using explicit test credentials or signup instructions from the repo, use back/forward after reaching nested dashboard states, then evaluate whether visible state, URL, and focused controls still agree.\n\n#### Definition of done\n\n- A discardable .notes/qa-dashboard-swarm.md file exists with numbered findings grouped by perspective.\n- The browser proof includes local URL, login path used, at least one snapshot or screenshot reference, and notes on back/forward, repeated-click, and toggle behavior.\n- The final triage separates useful findings from noise and marks which issues deserve durable tests because they touch stable business logic.\n\n#### Failure modes and mitigations\n\n- The agent only walks the happy path; mitigate by requiring each perspective to perform at least three weird-path moves before writing conclusions.\n- The agent assumes existing browser cookies; mitigate by scripting login/signup explicitly and recording the auth path used.\n\n### Checkout flow state-bug hunt before release\n\n**Role:** As a full-stack web developer preparing a checkout or billing flow for release\n\nA local ecommerce or SaaS checkout flow has plan selection, quantity changes, discount code entry, payment-step navigation, validation messages, and browser history interactions.\n\n> As a full-stack developer, I want agents to attack the checkout flow from different user perspectives, so that I can find state mismatches and UX dead ends without overbuilding brittle tests for UI that may still change.\n\n#### Agent brief\n\n```text\nRun the 5 Monkeys technique on the checkout/billing flow. Treat stable pricing, totals, validation rules, and submitted payloads as serious business logic; treat copy, spacing, and visual layout notes as flexible UI findings unless they block the user. Create .notes/qa-checkout-five-monkeys.md. Start the local app and document the exact command. Assign lenses: expert buyer, brand-new customer, grandparent/inexperienced user, impatient power user, and skeptical returning customer. In the browser, test non-obvious paths: change plan then press back, enter then remove a coupon, rapidly change quantity, start checkout then abandon before payment, refresh on a later step, use keyboard navigation where controls are visible, and retry after validation errors. Capture console errors, visible state, URL, and any mismatch between displayed total and expected total. Expected output: a discardable QA file, a concise release-risk summary, and recommendations for which findings should become durable automated tests.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n[Open reference](/topics/foundations-perspective-qa-and-testing/)\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n```text\npackage.json\n```\n\n```text\nplaywright.config.* if present\n```\n\n```text\n.notes/qa-checkout-five-monkeys.md\n```\n\n#### Browser verification\n\nUse Playwright, a CMUX browser pane, or an agent-browser-style snapshot/click/fill/evaluate loop. Fill checkout inputs, click plan and coupon controls, use browser back/forward between checkout steps, refresh after a partial flow, and evaluate the DOM text for totals, validation messages, and disabled/enabled button state.\n\n#### Definition of done\n\n- A .notes/qa-checkout-five-monkeys.md file lists exact reproduction paths for each useful checkout finding.\n- Browser evidence includes the local URL, console-log notes, visible totals or validation text, and the action sequence that triggered each issue.\n- The final review identifies which findings should become durable tests because they protect stable business logic.\n\n#### Failure modes and mitigations\n\n- The agent treats all UI observations as test-suite requirements; mitigate by explicitly classifying stable business logic separately from fast-changing UI.\n- The agent reports vague concerns without reproduction steps; mitigate by requiring every useful finding to include exact clicks, form inputs, URL/history moves, and observed result.\n\n### Stress-test a pricing-plan upgrade flow\n\n**Role:** As a growth engineer owning a SaaS pricing page and upgrade checkout\n\nA pricing page has monthly/yearly toggles, plan comparison cards, a coupon field, and an upgrade checkout modal. Happy-path tests pass, but users keep finding weird state bugs after toggling billing periods, backing out of checkout, and switching plans.\n\n> As a trial user comparing plans, I want billing toggles, coupon validation, selected plan state, and checkout recovery to stay consistent, so that I can upgrade without losing trust in the pricing flow.\n\n#### Agent brief\n\n```text\nRun a 5 Monkeys QA pass against the local pricing and upgrade flow. Assign five perspectives: brand-new trial user, impatient mobile user, keyboard-only user, existing customer changing plans, and skeptical QA engineer. Each perspective should explore weird paths: toggle monthly/yearly repeatedly, apply invalid and valid coupons, switch plans after opening checkout, use back/forward, refresh mid-flow, and try keyboard navigation. Each worker writes one discardable QA file under `.notes/qa/pricing-<perspective>.md` with steps, expected result, observed result, screenshot or browser transcript path, severity, and whether the issue is reproducible. Collate findings into `.notes/qa/pricing-summary.md` and recommend only the highest-value fixes.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n```text\npackage.json scripts\n```\n\n```text\nlocal pricing route and checkout/modal source files\n```\n\n```text\ncmux browser snapshot/click/fill/evaluate commands or existing Playwright tests\n```\n\n#### Browser verification\n\nUse a CMUX browser pane, Playwright if already present, or an agent-browser-style snapshot/click/fill/evaluate loop. Open the local pricing route, snapshot plan names and billing toggle state, click monthly/yearly, open checkout for each plan, fill coupon codes, use back/forward and refresh, and capture visible selected-plan text plus console errors after each odd path.\n\n#### Definition of done\n\n- Five perspective-specific QA markdown files exist under `.notes/qa/`.\n- The summary separates reproducible product bugs from preference notes and one-off observations.\n- At least one browser receipt exists per high-severity finding: screenshot, accessibility snapshot, console output, or Playwright trace.\n- Recommended fixes are ranked by user impact and implementation risk, not by which worker found them first.\n\n#### Failure modes and mitigations\n\n- The workers all follow the same happy path; mitigate by assigning explicit perspectives and weird-path instructions before they start.\n- The agent turns observations into permanent tests too early; mitigate by keeping findings discardable until the team decides which behavior should become stable.\n- The QA pass uses real payment/customer data; mitigate with local fixtures, test cards, or mocked checkout state only.\n\n## Implementation notes\n\n- Keep the QA files explicitly discardable under .notes/ so agents can regenerate them as the UI changes.\n- For browser verification, tell the agent the login or signup path; do not assume cookies, private session state, or authenticated browser context.\n- The useful receipt is not a large pile of findings. It is a short triage of reproducible weird-path issues, with noisy observations removed.\n- Keep rigorous automated tests for stable business logic such as checkout totals, permissions, data persistence, and validation rules.\n- Use CMUX browser panes, agent-browser-style snapshots/click/fill/evaluate, or Playwright when live UI behavior matters more than source inspection.\n- Grounded in the uploaded scenario bundle. :contentReference[oaicite:0]{index=0}\n\n## Boundaries and caveats\n\n- Do not turn discardable QA files into a permanent Storybook-style or full integration-test framework.\n- Do not introduce tools that were only mentioned but not taught as the technique for this workflow.\n- Do not assume browser agents inherit the developer's cookies or private authenticated state.\n- Do not use worktrees by default for this playbook; keep the scenario focused on the single selected toolkit technique.\n- Do not claim the swarm replaces stable business-logic tests.\n\n## Agent reference map\n\n### Existing 5 Monkeys prompt\n\nUse it as the canonical copy-paste behavior contract for perspective lenses, weird-path exploration, discardable QA files, and browser-auth guardrails.\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n### Existing five-monkeys Codex skill\n\nUse it to keep the agent behavior aligned with the toolkit technique instead of inventing a new QA framework.\n\n[Open reference](/topics/foundations-five-monkeys-playbook/)\n\n### Validated lesson 05 references\n\nTreat this as ground truth for taught concepts: perspective prompting, discardable QA files, 5 Monkeys exploration, CMUX state, browser-driving tools, and video-driven intent extraction.\n\n[Open reference](/topics/foundations-perspective-qa-and-testing/)\n\n### Lesson 05 validation notes\n\nUse it to avoid reintroducing details removed during validation, especially anything only mentioned in chat or not taught as a workflow.\n\n[Open reference](/topics/foundations-perspective-qa-and-testing/)\n\n### CMUX state and pane commands\n\nUse these commands when the agent needs to inspect the active workspace, read terminal output, or open a live Markdown QA tracker.\n\n```text\ncmux --json tree; cmux read-screen; cmux markdown open .notes/qa-dashboard-swarm.md --direction right\n```"
    },
    {
      "id": "factory-factory-loop-discussion",
      "slug": "factory-loop-discussion",
      "title": "A trustworthy software factory loop — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Verification",
      "tags": [
        "factory-loop",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[200]",
        "resource-manifest.json#videoEvidence.concepts[201]",
        "resource-manifest.json#videoEvidence.concepts[202]",
        "resource-manifest.json#videoEvidence.concepts[203]",
        "resource-manifest.json#videoEvidence.concepts[204]",
        "resource-manifest.json#videoEvidence.concepts[205]",
        "resource-manifest.json#videoEvidence.concepts[206]",
        "resource-manifest.json#videoEvidence.concepts[207]",
        "resource-manifest.json#videoEvidence.concepts[208]",
        "resource-manifest.json#videoEvidence.concepts[209]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[68]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[69]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[70]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[71]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[72]",
        "resource-manifest.json#videoEvidence.timeline[953]",
        "resource-manifest.json#videoEvidence.timeline[955]",
        "resource-manifest.json#videoEvidence.timeline[957]",
        "resource-manifest.json#videoEvidence.timeline[958]",
        "resource-manifest.json#videoEvidence.timeline[959]",
        "resource-manifest.json#videoEvidence.timeline[960]",
        "resource-manifest.json#videoEvidence.timeline[962]",
        "resource-manifest.json#videoEvidence.timeline[964]",
        "resource-manifest.json#videoEvidence.timeline[965]",
        "resource-manifest.json#videoEvidence.timeline[966]",
        "resource-manifest.json#videoEvidence.timeline[967]",
        "resource-manifest.json#videoEvidence.timeline[968]",
        "resource-manifest.json#videoEvidence.timeline[969]",
        "resource-manifest.json#videoEvidence.timeline[970]",
        "resource-manifest.json#videoEvidence.timeline[971]",
        "resource-manifest.json#videoEvidence.timeline[972]",
        "resource-manifest.json#videoEvidence.timeline[973]",
        "resource-manifest.json#videoEvidence.timeline[974]",
        "resource-manifest.json#videoEvidence.timeline[976]",
        "resource-manifest.json#videoEvidence.timeline[978]",
        "resource-manifest.json#videoEvidence.timeline[979]",
        "resource-manifest.json#videoEvidence.timeline[980]",
        "resource-manifest.json#videoEvidence.timeline[981]",
        "resource-manifest.json#videoEvidence.timeline[982]",
        "resource-manifest.json#videoEvidence.uncertainties[65]",
        "resource-manifest.json#videoEvidence.uncertainties[67]",
        "resource-manifest.json#videoEvidence.demos[117]",
        "resource-manifest.json#videoEvidence.demos[118]",
        "resource-manifest.json#videoEvidence.demos[119]",
        "resource-manifest.json#videoEvidence.demos[120]"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1410,
      "url": "/topics/factory-factory-loop-discussion/",
      "markdownUrl": "/markdown/factory-factory-loop-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-factory-loop-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "git-hook-vision-verifiers",
          "text": "Git Hook Vision Verifiers",
          "level": 3
        },
        {
          "id": "open-weights-task-optimization",
          "text": "Open Weights Task Optimization",
          "level": 3
        },
        {
          "id": "ai-coding-agent-context-docs",
          "text": "AI Coding Agent Context Docs",
          "level": 3
        },
        {
          "id": "distributed-agent-architecture",
          "text": "Distributed Agent Architecture",
          "level": 3
        },
        {
          "id": "token-efficiency-cost-speed-trade-offs",
          "text": "Token Efficiency & Cost-Speed Trade-offs",
          "level": 3
        },
        {
          "id": "model-routing-downgrading",
          "text": "Model Routing & Downgrading",
          "level": 3
        },
        {
          "id": "personal-agentic-brain",
          "text": "Personal Agentic Brain",
          "level": 3
        },
        {
          "id": "scheduled-agents-noise-factor",
          "text": "Scheduled Agents Noise Factor",
          "level": 3
        },
        {
          "id": "context-window-isolation",
          "text": "Context Window Isolation",
          "level": 3
        },
        {
          "id": "ai-agent-context-documentation",
          "text": "AI-Agent Context Documentation",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "would-you-argue-for-more-use-of-git-hooks-than-more-and-more-documentation",
          "text": "Would you argue for more use of git hooks than more and more documentation?",
          "level": 3
        },
        {
          "id": "screenpipe-has-a-cool-architecture-spins-up-agents-quickly-do-you-see-this-trend-in-the-future-claude-tag-etc-each-having-their-own-channel-or-a-distributed-knolwege-graph-where-agents-are-shared-and-dynamic-self-learning-based-on-channel-task",
          "text": "screenpipe has a cool architecture, spins up agents quickly, do you see this trend in the future, claude tag, etc, each having their own channel or a distributed knolwege graph where agents are shared and dynamic, self learning based on channel/task",
          "level": 3
        },
        {
          "id": "screenpipe-has-a-cool-architecture-spins-up-agents-quickly-do-you-see-this-trend-in-the-future-claude-tag-each-having-their-own-channel-or-distributed-knowledge-graph",
          "text": "ScreenPipe has a cool architecture, spins up agents quickly. Do you see this trend in the future? Claude Tag, each having their own channel or distributed knowledge graph.",
          "level": 3
        },
        {
          "id": "they-run-through-intelligent-schedulers-i-think-i-mean-agentic-loops-that-are-created-do-you-have-anything-on-a-schedule",
          "text": "they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?",
          "level": 3
        },
        {
          "id": "to-slash-token-costs-for-everyday-coding-how-are-you-stripping-down-the-source-code-files-before-feeding-them-to-claude-code",
          "text": "To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-the-precise-repository-paths-fetched-by-the-gh-cli-tool",
          "text": "Unresolved: The precise repository paths fetched by the gh cli tool.",
          "level": 3
        },
        {
          "id": "unresolved-the-active-editor-application-is-definitively-cursor",
          "text": "Unresolved: The active editor application is definitively Cursor.",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-40-36",
          "text": "Demonstration detail: 05:40:36",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-43-42",
          "text": "Demonstration detail: 05:43:42",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-46-53",
          "text": "Demonstration detail: 05:46:53",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-50-04",
          "text": "Demonstration detail: 05:50:04",
          "level": 3
        }
      ],
      "markdown": "# A trustworthy software factory loop — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Git Hook Vision Verifiers\n\nUsing pre-commit or commit hooks to run custom AI agents that evaluate if a code change aligns with the structural or architectural vision of a project.\n\n### Open Weights Task Optimization\n\nLeveraging highly intelligent yet low-cost open-weights models (like K3) to train or fine-tune small, specific developer automation utilities.\n\n### AI Coding Agent Context Docs\n\nStructuring documents like VISION.md, CLAUDE.md, or AGENTS.md specifically to guide automated AI coding tools across development sessions rather than solely onboarding humans.\n\n### Distributed Agent Architecture\n\nStructuring automations into small, specialized agents or scripted steps rather than relying entirely on a single large general model.\n\n### Token Efficiency & Cost-Speed Trade-offs\n\nBalancing response latency and token costs against task completion rates when designing long-running agent loops.\n\n### Model Routing & Downgrading\n\nAutomated switching between different model tiers during execution, which can degrade output quality if small models are chosen inappropriately.\n\n### Personal Agentic Brain\n\nA custom local agent architecture combining a private GitHub repository for persistent memory storage with interactive Telegram messages for human-in-the-loop task notifications.\n\n### Scheduled Agents Noise Factor\n\nThe tendency for passive, scheduled cron-like agent notifications to degrade into ambient attention noise, making manual execution preferable for deep curation workflows.\n\n### Context Window Isolation\n\nUtilizing isolated sub-agents or flow frameworks to limit token overhead by dividing large development tasks into distinct, bounded operational sessions.\n\n### AI-Agent Context Documentation\n\nAuthoring structural metadata and orientation files (such as VISION.md or CLAUDE.md) optimized for programmatic ingestion by code assistants rather than humans.\n\n## Questions and answer status\n\n### Would you argue for more use of git hooks than more and more documentation?\n\n**Status: answered.** John argues that while running agent evals on every git hook is currently too expensive for individuals, the upcoming release of open-weights models like K3 will make it very cheap. This allows teams to build custom vision verifier agents on commit hooks, making automated vision alignment practical and powerful within weeks.\n\n### screenpipe has a cool architecture, spins up agents quickly, do you see this trend in the future, claude tag, etc, each having their own channel or a distributed knolwege graph where agents are shared and dynamic, self learning based on channel/task\n\n**Status: deferred.** The question is received in chat and the presenter just begins reading it as the shard ends; the full response is deferred to the subsequent shard.\n\n### ScreenPipe has a cool architecture, spins up agents quickly. Do you see this trend in the future? Claude Tag, each having their own channel or distributed knowledge graph.\n\n**Status: answered.** John agrees that distributed agents doing small targeted tasks and scripted steps are necessary for speed and cost efficiency, though general models remain valuable when budget permits. He cautions against unreliable automatic model routing based on past experiences with GPT-5.1 and Opus 4.8 downgrades.\n\n### they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?\n\n**Status: answered.** John describes his personal agentic 'Brain' running on a Mac Mini via GitHub and Telegram, but details that he avoids putting general curation or code review loops on a schedule because they become noise.\n\n### To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code?\n\n**Status: answered.** John states that he does not manually trim down files anymore, citing major improvements in LLM native context window management. Instead, he orchestrates multi-agent flows or redirects intermediate subtasks to lower-cost endpoints like Grok, Cursor Composer, or K3.\n\n## Exercises\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [05:40:36](https://proud-anchor-53zn.here.now/watch.html?t=20436#recording-player) — The screen shows the Claude Code v2.1.212 interface inside the ~/dev/mdflow workspace executing shell commands to search for VISION.md files.\n\n- [05:41:03](https://proud-anchor-53zn.here.now/watch.html?t=20463#recording-player) — a participant submits a question in the workshop chat window: 'Would you argue for more use of git hooks than more and more documentation?'\n\n- [05:41:38](https://proud-anchor-53zn.here.now/watch.html?t=20498#recording-player) — The Claude Code terminal output updates to show it is reading 20 files from a temporary scratchpad directory to inspect VISION.md content.\n\n- [05:41:47](https://proud-anchor-53zn.here.now/watch.html?t=20507#recording-player) — John states that running full agent loops on every git hook can be prohibitively expensive for individual developers at the moment.\n\n- [05:41:57](https://proud-anchor-53zn.here.now/watch.html?t=20517#recording-player) — John notes that the K3 model has come out, offering low cost while maintaining high intelligence levels.\n\n- [05:42:15](https://proud-anchor-53zn.here.now/watch.html?t=20535#recording-player) — Claude Code prints out the completed markdown analysis summarizing 20 repository files categorized into architectural and agent patterns.\n\n- [05:43:32](https://proud-anchor-53zn.here.now/watch.html?t=20612#recording-player) — John emphasizes that utilizing an open-weights K3 model as a custom review-step verifier is only weeks away.\n\n- [05:43:42](https://proud-anchor-53zn.here.now/watch.html?t=20622#recording-player) — John addresses student question regarding ScreenPipe agent architecture and distributed knowledge graphs.\n\n- [05:44:05](https://proud-anchor-53zn.here.now/watch.html?t=20645#recording-player) — John discusses cost and speed trade-offs in setting up agent automations.\n\n- [05:44:34](https://proud-anchor-53zn.here.now/watch.html?t=20674#recording-player) — John highlights token efficiency and benchmark performance of the Fable model.\n\n- [05:45:28](https://proud-anchor-53zn.here.now/watch.html?t=20728#recording-player) — John recommends distributed agents for smaller scopes of work combined with scripted steps to optimize speed and cost.\n\n- [05:46:07](https://proud-anchor-53zn.here.now/watch.html?t=20767#recording-player) — John shares negative experiences with dynamic model routing in GPT-5.1 and unwanted downgrades from Fable to Opus 4.8.\n\n- [05:46:53](https://proud-anchor-53zn.here.now/watch.html?t=20813#recording-player) — John predicts that future smart models will delegate better and demo models will get more intelligent.\n\n- [05:47:09](https://proud-anchor-53zn.here.now/watch.html?t=20829#recording-player) — a participant asks in chat: 'they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?'\n\n- [05:47:16](https://proud-anchor-53zn.here.now/watch.html?t=20836#recording-player) — John explains that he has a custom agent called 'Brain' running on a Mac Mini that keeps memory in a private GitHub repository and sends him task check-ins via Telegram.\n\n- [05:48:07](https://proud-anchor-53zn.here.now/watch.html?t=20887#recording-player) — John discusses building desktop applications such as Script Kit and a custom Google Messages client replacement.\n\n- [05:48:38](https://proud-anchor-53zn.here.now/watch.html?t=20918#recording-player) — John states that scheduled notifications for code reviews, news, and social media turn into ignored noise for him, so he executes them manually.\n\n- [05:50:04](https://proud-anchor-53zn.here.now/watch.html?t=21004#recording-player) — John Lindquist comments on attention management and managing multiple active models.\n\n- [05:50:27](https://proud-anchor-53zn.here.now/watch.html?t=21027#recording-player) — a participant submits a chat question regarding how to strip down source code files to minimize token costs in Claude Code.\n\n- [05:50:37](https://proud-anchor-53zn.here.now/watch.html?t=21037#recording-player) — John explains that he typically avoids stripping source code files now due to upgraded context handling in newer models.\n\n- [05:50:52](https://proud-anchor-53zn.here.now/watch.html?t=21052#recording-player) — John discusses flow and sub-agent architectures that segment tasks into individual context windows to prevent usage spikes.\n\n- [05:51:15](https://proud-anchor-53zn.here.now/watch.html?t=21075#recording-player) — John discusses configuring Claude Code to delegate tasks to more affordable models or platforms like Cursor Composer.\n\n- [05:51:34](https://proud-anchor-53zn.here.now/watch.html?t=21094#recording-player) — John mentions Grok as a highly affordable $20 monthly option, noting historical codebase ingestion policies.\n\n- [05:51:59](https://proud-anchor-53zn.here.now/watch.html?t=21119#recording-player) — John references the K3 model release from the previous day, comparing its cost-efficiency to Fable and Soul.\n\n### Unresolved: The precise repository paths fetched by the gh cli tool.\n\nThe terminal window displays temporary paths and fast-scrolling logs which are partially occluded or truncated.\n\n**Discriminating evidence:** Inspect the raw workspace command execution logs or check the scratchpad directory state directly.\n\n### Unresolved: The active editor application is definitively Cursor.\n\nThe window chrome headers are omitted from the display bounds, preventing direct confirmation of branding.\n\n**Discriminating evidence:** Verify with baseline environmental context from prior session modules.\n\n### Demonstration detail: 05:40:36\n\n- Claude Code agent runs automated gh cli search commands for VISION.md files.\n- Claude Code prints out a categorized markdown summary analysis directly onto the terminal pane.\n\n**Tools observed:** Claude Code v2.1.212, GitHub CLI.\n\n### Demonstration detail: 05:43:42\n\n- Editor screen remains open on Claude workspace notes while presenter discusses architectural strategy.\n\n**Tools observed:** VS Code / Cursor, Claude.\n\n### Demonstration detail: 05:46:53\n\n- The screen presents a static reference view of a markdown text document outlining AI agent prompt documentation parameters alongside an active workspace prompt configuration panel.\n\n**Tools observed:** Cursor IDE.\n\n### Demonstration detail: 05:50:04\n\n- A static document overview layout is shown containing summary evaluations of project context schemas for tools like Claude, typescriptter, and ruby2js.\n\n**Tools observed:** Claude, VS Code."
    },
    {
      "id": "factory-advanced-workflow-contracts",
      "slug": "advanced-workflow-contracts",
      "title": "Advanced consult, image, and video contracts",
      "summary": "Transferable contracts from the published Oracle resource family: premise coverage, bounded escalation, attachment proof, multimodal continuity, and honest completion.",
      "category": "Verification",
      "tags": [
        "oracle",
        "video",
        "images",
        "contracts"
      ],
      "sources": [
        {
          "label": "Oracle resource family",
          "url": "https://shiny-rosette-m6zy.here.now/#attachments"
        },
        {
          "label": "skills/oracle-video/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-video/SKILL.md"
        },
        {
          "label": "skills/oracle/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle/SKILL.md"
        },
        {
          "label": "skills/oracle-schedule/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/SKILL.md"
        },
        {
          "label": "skills/oracle-execute/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-execute/SKILL.md"
        },
        {
          "label": "skills/oracle-video-create/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-video-create/SKILL.md"
        },
        {
          "label": "skills/imagine/SKILL.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/imagine/SKILL.md"
        },
        {
          "label": "skills/oracle/references/round-robin-receipt.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-receipt.md"
        },
        {
          "label": "skills/oracle/references/round-robin-transport.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-transport.md"
        },
        {
          "label": "skills/oracle-video/references/repeatable-video-followup-process.md",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/skills/#portable-workflow-contracts",
        "08-oracle-video/skills/oracle-video/SKILL.md",
        "08-oracle-video/skills/oracle/SKILL.md",
        "08-oracle-video/skills/oracle-schedule/SKILL.md",
        "08-oracle-video/skills/oracle-execute/SKILL.md",
        "08-oracle-video/skills/oracle-video-create/SKILL.md",
        "08-oracle-video/skills/imagine/SKILL.md",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1546,
      "url": "/topics/factory-advanced-workflow-contracts/",
      "markdownUrl": "/markdown/factory-advanced-workflow-contracts.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-advanced-workflow-contracts.json",
      "headings": [
        {
          "id": "keep-the-original-premise-stronger-than-the-latest-plan",
          "text": "Keep the original premise stronger than the latest plan",
          "level": 2
        },
        {
          "id": "rich-context-and-compact-evidence-are-alternatives-not-dogmas",
          "text": "Rich context and compact evidence are alternatives, not dogmas",
          "level": 2
        },
        {
          "id": "video-analysis-attachment-proof-before-expensive-extraction",
          "text": "Video analysis: attachment proof before expensive extraction",
          "level": 2
        },
        {
          "id": "image-generation-requested-count-is-not-captured-count",
          "text": "Image generation: requested count is not captured count",
          "level": 2
        },
        {
          "id": "generated-video-continuous-story-separately-verified-clips",
          "text": "Generated video: continuous story, separately verified clips",
          "level": 2
        },
        {
          "id": "scheduling-is-an-explicit-alternative",
          "text": "Scheduling is an explicit alternative",
          "level": 2
        }
      ],
      "markdown": "# Advanced consult, image, and video contracts\n\nTransferable contracts from the published Oracle resource family: premise coverage, bounded escalation, attachment proof, multimodal continuity, and honest completion.\n\n## Keep the original premise stronger than the latest plan\n\nThe execution-oriented consult pattern preserves the original request and derives measurable outcomes, constraints, and falsifiable completion checks. Every premise clause maps to a plan step. Exhausting a plan that omitted part of the request is not completion.\n\nThis is distinct from a simple independent second opinion. The execution pattern labels a step **execute** when local evidence and the existing plan suffice, and **think** when a genuine architectural choice, unresolved ambiguity, or difficult diagnosis requires frontier reasoning. Size or tedium alone does not justify another consult. Batch independent adjacent think decisions. The intended ratio is few think steps, not a consult for every implementation step.\n\nThe named consultation points are planning, think decisions, escalation after two distinct failed verification attempts, and a final whole-premise audit. Every consultation asks for the maximum actionable batch: exact file/function/test targets, alternatives, tradeoffs, intended commit boundaries, and enough detail for substantial local execution—not merely “what next?”\n\nExecution is implement → falsifiable verification → scoped commit → advance. Preserve unrelated dirty work. Mechanical, evidence-backed plan corrections can be local; new decisions become explicit think steps. An escalation includes the actual failing commands, outputs, receipts, and attempted diff. A step that still fails after its escalation is a genuine block rather than permission to consult indefinitely.\n\nThe final independent audit compares the actual result with the original premise. PASS requires final local proof against the same state. FAIL returns the complete remediation set, not just the first gap. Out-of-scope nice-to-haves do not silently expand the task. Missing authorization for credentials, destructive action, or broader scope is a stop boundary.\n\n## Rich context and compact evidence are alternatives, not dogmas\n\nThe Packx reference favors rich code context for broad architecture work, with a roughly 900k-token target in the demonstrated browser-consult setup. The boundary audit favors the smallest useful evidence packet. These answer different problems: a whole-system decision may need the complete relevant source, while a local decision should not carry an entire stale conversation.\n\nWhen raw material is too large or unsafe, supply compact evidence explicitly: prior-state decisions, trustworthy receipts, failure observations, intentionally omitted sources, and a goal-coverage map. Do not replace raw evidence with an unlabelled confident summary. Avoid bundling credentials or private instructions simply because a large attachment is technically supported.\n\n## Video analysis: attachment proof before expensive extraction\n\nUse the attached-video path itself as the readiness test. A signed-in browser UI is required, but a text-only cookie error does not prove that the video upload path is broken. Conversely, a text response is not evidence that a model watched a video.\n\nA cheap probe asks the model to identify a concrete visible or audible event and end with an exact sentinel. Save the complete response and verify the sentinel before running long analyses. Use short clips directly when that is sufficient. For long recordings, preserve source-native segments, explicit segment boundaries, source metadata, and the relation between local segment time and recording time. Record unsupported claims rather than filling gaps from a transcript.\n\nFor each segment, request a dense timeline, concept inventory, demonstrations and screen activity, Q&A with answer status, links/tools/commands/resources, keyframes worth checking, exercises, and uncertainties. Run an omissions pass against the same evidence, reconcile cross-segment overlaps, and retain partial or unanswered questions as such. A successful parse is not a complete account.\n\nThe resource family distinguishes routine multimodal analysis from explicitly requested deeper reasoning. Model-selector labels and product limits must be verified against the installed version; ChatGPT’s Instant/Pro Extended labels are not Gemini video readiness signals.\n\nWhen a single shard fails while neighboring shards succeed, classify the input separately from the transport. The demonstrated remedy was re-encoding the failing shard, rerunning the cheap proof, then preserving the working media recipe. That is an empirical fix, not proof of the underlying cause. Keep an unresolved run from being duplicated just because a local wait returned. After successful artifact capture, close only the browser tab owned by that run.\n\nFor research batches, filter using actual source metadata rather than titles or remembered dates; exclude topic-name collisions and irrelevant material. Keep a durable queue with source identity, title, author, duration, and public URL. Make prompts specific to the research topic. Batching, cadence, and quota boundaries must be explicit, not hidden retries.\n\n## Image generation: requested count is not captured count\n\nThe Codex and Antigravity mockup recipes use one built-in image call per asset. The Oracle/ChatGPT image resource instead requests a clearly numbered batch through one browser call. Preserve that distinction; it is tool-specific advice, not a universal rule.\n\nA batch contract makes the number and output granularity explicit:\n\n```text\nCreate exactly N separate images. Each is its own standalone image file.\nImage 1: <complete scene description>.\nImage 2: <complete scene description>.\n...\nOutput all N as N separate images. No text, no captions, no typography.\n```\n\nCount returned files and inspect each one to identify its intended scene; return order need not match prompt order. A short capture can mean later images were still rendering, not that the model refused the batch. Inspect the existing conversation before requesting replacements. A recovery probe that does not generate again is:\n\n```text\nDo not generate or create any images in this response. Reply with only the digit count of images above.\n```\n\nDeduplicate recovered files by checksum. A failure before generation starts differs from a timeout while generation is active; only the former supports a simple immediate retry without duplication risk. Use returned artifact locations rather than constructing paths from a slug that may have been truncated.\n\nFor long sets, maintain a queue of complete self-contained scene descriptions and per-call requested/received counts. Sequential execution, explicit pacing, and quota-aware stopping make interrupted work resumable. Character consistency needs both the reference image and a repeated textual description; verify the face, clothing, and style rather than assuming the attachment enforced them.\n\nThe browser image workflow uses its image-appropriate mode, while non-image deep consultations use extended reasoning. This is a distinction between tasks, not permission to carry one model’s mode labels into another product. Refusals are prompt outcomes, not infrastructure errors: report them, change the request to an original permitted concept where appropriate, and do not retry-loop the same refused prompt.\n\n## Generated video: continuous story, separately verified clips\n\nThe published generation example uses short clips rather than assuming that asking for a minute yields a minute. Its demonstrated output was approximately ten seconds per clip, 1280×720 H.264 video with AAC audio. Those are observed product limits, not guaranteed current limits. Longer stories use multiple clips, continuity references, and a local stitch.\n\nWrite every beat before starting. Group images into two or three sequential visual references per clip. Where supported, put the prior clip before the next images as a reference for camera language, grade, and tone. Generate sequentially, persist each returned artifact, inspect its duration/codec/dimensions/size, and only then use it as the next clip’s reference.\n\nA stitch-safe visual prompt includes:\n\n```text\nUse the attached images as sequential visual references. Generate a full 10 second cinematic video: <beat-by-beat action>.\n\nAudio constraints: no music, no score, no singing, no lyrics, no dialogue, no voiceover, no spoken words, no mouth-synced speech. Prefer a silent clip; if audio is unavoidable, use only subtle non-musical ambient sound.\n\nNo text, no captions, no readable words.\n```\n\nThe silent-first policy prevents repeated dialogue or discontinuous generated music from ruining the edit. Strip unwanted clip audio rather than treating a technically successful speech track as usable. Add narration, music, and sound design after picture is locked unless preserving the generated audio was explicitly requested.\n\nUse real media inspection, not a download receipt:\n\n```sh\nffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height,duration -of json clip.mp4\nffmpeg -hide_banner -y -f concat -safe 0 -i concat.txt -c copy story.mp4\nffmpeg -hide_banner -y -i story.mp4 -vf 'fps=1/5,scale=320:-1,tile=3x4' -frames:v 1 contact-sheet.jpg\n```\n\nA contact sheet must actually be inspected. Matching codecs and dimensions support stream-copy stitching; a paced edit requires re-encoding and checking audio timing. Report per-clip and final counts, durations, references, and any continuity seams.\n\nA generated-video run can finish with a text refusal and no video. That is not a reason to wait indefinitely. Read the visible response and distinguish refusal, quota, unsubmitted prompt, DOM drift, transfer limit, and real generation-in-progress. A prompt still sitting in the composer without a submitted user turn is a send failure, not a slow model. Never silently truncate a video to satisfy a transfer limit.\n\nIf identity-continuity wording is refused, do not keep submitting the same request. Reframe only toward permitted fictional material; if necessary remove the prior-video identity reference and use loose storyboard references, non-identifiable framing, objects, setting, and grade for continuity. Record the change because it affects the final story. A cosmetic fictional label alone was not a reliable remedy in the example.\n\n## Scheduling is an explicit alternative\n\nA schedule is justified only by an agreed recurring action, owner, stop condition, and durable status. The resource family includes a follow-up scheduling tool; the broader software-factory discussion cautions that scheduled curation and review can become noise. Do not turn the availability of a scheduler into a recommendation to schedule everything."
    },
    {
      "id": "codex-marker-workflows-reference",
      "slug": "marker-workflows-reference",
      "title": "Agent Markers debugging workflows: practical reference",
      "summary": "Browser-debugging reference covering the agent-markers setup prompt, perspective-based exploratory QA, bounded event capture and marker schemas, browser/global APIs, privacy and cleanup, JSON and test-artifact exports, replay capsules, app-specific…",
      "category": "Verification",
      "tags": [
        "agent-markers",
        "debugging",
        "privacy"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Start With 5 Monkeys",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Basic Browser Setup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Global Test Surface",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Capture Types",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Marker Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Export A Debug Packet",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Verify The Project",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Turn A Marker Export Into An Agent Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Bounded Replay Capsule",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/App-Specific Marker Flow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Marker Has No Note",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Export Has Too Many Raw Logs",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/`nearbyEventIds` Is Empty",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Sensitive Storage Values Were Captured",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Console/Fetch Remains Patched",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Test Runner Cannot Export",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/If It Goes Wrong/Screenshot Or DOM Hook Is Missing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/08-debugging-with-agent-markers.md#08. Debugging With Agent Markers/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 2700,
      "url": "/topics/codex-marker-workflows-reference/",
      "markdownUrl": "/markdown/codex-marker-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-marker-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "start-with-5-monkeys",
          "text": "Start With 5 Monkeys",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "basic-browser-setup",
          "text": "Basic Browser Setup",
          "level": 2
        },
        {
          "id": "global-test-surface",
          "text": "Global Test Surface",
          "level": 2
        },
        {
          "id": "capture-types",
          "text": "Capture Types",
          "level": 2
        },
        {
          "id": "marker-shape",
          "text": "Marker Shape",
          "level": 2
        },
        {
          "id": "export-a-debug-packet",
          "text": "Export A Debug Packet",
          "level": 2
        },
        {
          "id": "verify-the-project",
          "text": "Verify The Project",
          "level": 2
        },
        {
          "id": "turn-a-marker-export-into-an-agent-prompt",
          "text": "Turn A Marker Export Into An Agent Prompt",
          "level": 2
        },
        {
          "id": "bounded-replay-capsule",
          "text": "Bounded Replay Capsule",
          "level": 2
        },
        {
          "id": "app-specific-marker-flow",
          "text": "App-Specific Marker Flow",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "marker-has-no-note",
          "text": "Marker Has No Note",
          "level": 3
        },
        {
          "id": "export-has-too-many-raw-logs",
          "text": "Export Has Too Many Raw Logs",
          "level": 3
        },
        {
          "id": "nearbyeventids-is-empty",
          "text": "`nearbyEventIds` Is Empty",
          "level": 3
        },
        {
          "id": "sensitive-storage-values-were-captured",
          "text": "Sensitive Storage Values Were Captured",
          "level": 3
        },
        {
          "id": "console-fetch-remains-patched",
          "text": "Console/Fetch Remains Patched",
          "level": 3
        },
        {
          "id": "test-runner-cannot-export",
          "text": "Test Runner Cannot Export",
          "level": 3
        },
        {
          "id": "screenshot-or-dom-hook-is-missing",
          "text": "Screenshot Or DOM Hook Is Missing",
          "level": 3
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Agent Markers debugging workflows: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the agent-markers files and configuration for this browser project, then verify the setup before investigating any specific bug.\n\n1. Inspect the existing agent-markers package and demo files first:\n   - packages/client/src/index.ts\n   - packages/client/src/collector.ts\n   - packages/client/src/types.ts\n   - packages/client/src/capture/console.ts\n   - packages/client/src/capture/fetch.ts\n   - packages/client/src/capture/errors.ts\n   - packages/client/src/serialize.ts\n   - apps/demo/src/main.ts\n   - apps/demo/src/viewer.ts\n   - scripts/smoke-demo.mjs\n   - docs/WORKSHOP.md\n\n2. If the package or demo is missing, scaffold the smallest matching structure. If files already exist, preserve the current API where possible and extend it only as needed.\n\n3. Define or confirm the core schema:\n   - DebugSession: one bounded run with sessionId, appName, schemaVersion, CapturedEvent[], and DebugMoment[]\n   - CapturedEvent: id, sequence, timestamp, type, and metadata for console, fetch, error, manual, DOM, screenshot, or app events\n   - DebugMoment: id, label, note, optional nextAction, timestamp, and nearbyEventIds that reference CapturedEvent ids\n   - export JSON: a JSON-serializable packet that can be saved, attached to a test run, or passed to another agent\n\n4. Implement or confirm createAgentMarkers in packages/client/src/index.ts. It should accept appName, exposeGlobal, and capture options for console, fetch, and errors. It should return mark(...), export(), and stop().\n\n5. Implement console, fetch, error, and manual capture:\n   - console capture records log/warn/error metadata without creating recursive logging loops\n   - fetch capture records URL, method, status, timing, and failure metadata\n   - error capture records thrown errors and unhandled rejections\n   - manual capture records marker labels, notes, nextAction, and timing\n   - all captured events should receive stable ids and sequence numbers\n\n6. Add privacy-safe defaults:\n   - capture metadata by default\n   - do not export storage values, cookies, tokens, request bodies, response bodies, private DOM text, or screenshots unless deliberately enabled and reviewed\n   - redact sensitive query params, headers, stack paths, and visible private text before saving export JSON\n   - include redaction notes in the exported packet\n\n7. Implement the collector in packages/client/src/collector.ts. Store events in order, enforce a maximum event count, and calculate nearbyEventIds for each DebugMoment using sequence or timestamp proximity.\n\n8. Implement serialize.ts so export() always returns valid JSON without circular references. Optional DOM or screenshot fields should be marked unavailable when no hook is configured.\n\n9. Wire createAgentMarkers into the demo app in apps/demo/src/main.ts with exposeGlobal: true for dev/test and capture enabled for console, fetch, and errors. Add a manual marker entrypoint such as a debug button or keyboard shortcut that calls markers.mark({ label, note, nextAction }).\n\n10. Wire apps/demo/src/viewer.ts so the current session can be exported, displayed, copied, or downloaded as JSON.\n\n11. Expose the dev/test global surface when configured:\n   - window.__AGENT_MARKERS__.mark(...)\n   - window.__AGENT_MARKERS__.export()\n   - window.__AGENT_MARKERS__.stop()\n\n12. Add test-runner export. In a Playwright-style test or equivalent, wait until the app is ready, call window.__AGENT_MARKERS__.mark(...), export the session with page.evaluate, and attach or save agent-markers.json. Assert markers.length > 0, a non-empty note exists, nearbyEventIds is present, and console/fetch/error/manual events appear when enabled.\n\n13. Add bounded replay packet setup for one marker. The packet should include schemaVersion, sessionId, markerId, markerCutoffSeq, nearbyEventIds, filtered console/fetch/error/manual evidence, optional DOM/screenshot availability, included and excluded boundaries, maximum event count, redaction status, and the first verification command. Do not build a full recorder.\n\n14. Update scripts/smoke-demo.mjs so it can launch or exercise the demo, create one marker, trigger at least one console event, fetch event, and error event where practical, export JSON, parse it, and confirm the packet is non-empty.\n\n15. Verify with the available project commands:\n   - npm test\n   - npm run typecheck\n   - npm run build\n   - npm run smoke:demo\n\n16. Confirm setup worked:\n   - createAgentMarkers imports and initializes\n   - mark() creates a DebugMoment with a specific note\n   - nearbyEventIds is non-empty after nearby capture activity\n   - exported events include console, fetch, error, and manual types when enabled\n   - export JSON parses cleanly\n   - window.__AGENT_MARKERS__ is available in dev/test only\n   - stop() restores patched console, fetch, and error listeners\n   - test-runner export saves or attaches agent-markers.json\n   - privacy defaults exclude sensitive values\n\nReport the files changed, setup choices, verification commands and results, sample export path, privacy boundaries, unavailable hooks, and any failed checks. If setup checks fail, stop and report the blocker. Do not debug a specific product bug until the setup and verification pass.\n```\n\n## Big Idea\n\nStart by sending cheap perspective-based agents through weird paths. Then use\nagent markers to capture the exact moment that should become a bounded debug\npacket.\n\nCore pattern:\n\n```text\n5 Monkeys QA -> mark -> capture -> explain -> review/export\n```\n\nThe 5 Monkeys pattern finds strange states a happy-path check would miss. Agent\nmarkers turn one of those strange states into evidence another agent can use.\n\nAn agent marker is a human-intent anchor inside a debugging workflow.\n\nIt answers:\n\n- why this moment mattered\n- what evidence was nearby\n- what should be inspected next\n- what the next human or agent should not waste time guessing\n\nAgent markers are not full replay systems. They are bounded debug packets.\n\n## Try This Now\n\nCreate one marker for a checkout UI bug:\n`window.__AGENT_MARKERS__.mark({ label: \"checkout disabled unexpectedly\", note: \"Expected submit to enable after terms and shipping were selected.\" })`\nExport the session and check that the marker has nearby evidence, not just a label.\n\n## Start With 5 Monkeys\n\nUse 5 Monkeys before marker capture when the bug is vague, stateful, or hidden\nbehind normal user behavior.\n\nAssign one lens per pass:\n\n| Lens | What It Tries |\n| --- | --- |\n| expert power user | shortcuts, fast navigation, hidden affordances |\n| brand-new first-time user | confusion, missing affordances, unclear copy |\n| inexperienced user | accidental clicks, mistaken paths, recovery failures |\n| impatient returning user | rapid clicks, skipped steps, partial flows |\n\nMake each pass explore weird paths:\n\n- keyboard shortcut sequences\n- back/forward navigation mid-flow\n- repeated or rapid clicks on one control\n- toggling modes back and forth\n- starting a flow, then bailing out\n- refreshing or re-entering with partial state\n\nWrite each pass to a discardable QA note such as `.notes/qa-01.md`. Collate the\nfindings, keep only useful bugs, and mark the one moment that best captures the\nstate failure.\n\nThen capture that moment with agent markers:\n\n```text\nweird state found -> human marks the decisive moment -> export nearby evidence\n```\n\nDo not replace stable business-logic tests with 5 Monkeys. Use it to discover\nUI and state failures that tests and logs did not already isolate.\n\n## Files To Inspect\n\nAgent markers project references:\n\n```text\npackages/client/src/index.ts\npackages/client/src/collector.ts\npackages/client/src/types.ts\npackages/client/src/capture/console.ts\npackages/client/src/capture/fetch.ts\npackages/client/src/capture/errors.ts\npackages/client/src/serialize.ts\napps/demo/src/main.ts\napps/demo/src/viewer.ts\nscripts/smoke-demo.mjs\ndocs/WORKSHOP.md\n```\n\n## When To Reach For This\n\nUse markers when logs are real but the important moment still needs human context.\n\n| Use Markers For | Why |\n| --- | --- |\n| checkout bug | mark the exact UI state where expected and actual diverge |\n| auth/session refresh issue | capture nearby fetch/error/console evidence around the failure |\n| billing admin UI failure | attach human expectation to the visible broken state |\n| flaky browser test | export a debug packet from the test runner |\n| design/debug review | pair screenshot/DOM hooks with a human explanation |\n| long agent debugging session | leave explicit breadcrumbs for the next pass |\n\nSkip markers when:\n\n- one failing unit test already isolates the bug\n- a stack trace points to one obvious line\n- no one can explain why the moment matters\n- the capture would expose sensitive data without redaction\n- the task needs full deterministic replay rather than a bounded debug packet\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nIf enough logs are captured, the agent can infer the important moment.\n```\n\nWhat the workflow gives you now:\n\n```text\nLogs show events. A marker ties a specific moment to human intent, nearby\nevidence, and the next debugging question.\n```\n\nWhat you used to expect:\n\n```text\nA screenshot or console dump is enough context.\n```\n\nWhat the workflow gives you now:\n\n```text\nThe useful packet combines the marker note, nearby console/fetch/error/manual\nevents, optional DOM or screenshot capture, privacy boundaries, and an export.\n```\n\n## The Mental Model\n\n```text\nDebugSession\n-> CapturedEvent[]\n-> DebugMoment[]\n-> export JSON\n-> agent prompt / test artifact / work unit\n```\n\n| Concept | Meaning |\n| --- | --- |\n| `DebugSession` | one bounded debugging run |\n| `CapturedEvent` | console, fetch, error, manual, DOM, screenshot, or app event |\n| `DebugMoment` | the human marker: label, note, timestamp, nearby evidence |\n| `nearbyEventIds` | event ids around the marked moment |\n| export JSON | portable debug packet |\n| `stop()` | cleanup that restores patched browser APIs |\n\n## Basic Browser Setup\n\nCreate markers in a browser app:\n\n```ts\nimport { createAgentMarkers } from \"@agent-markers/client\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n  capture: {\n    console: true,\n    fetch: true,\n    errors: true,\n  },\n});\n```\n\nExpose a manual marker action:\n\n```ts\ndocument.querySelector(\"#mark-debug\")?.addEventListener(\"click\", () => {\n  markers.mark({\n    label: \"checkout payment method disappeared\",\n    note: \"Expected saved payment selector to stay visible after refresh.\",\n  });\n});\n```\n\nExport:\n\n```ts\nconst session = markers.export();\nconsole.log(JSON.stringify(session, null, 2));\n```\n\nClean up patched APIs:\n\n```ts\nmarkers.stop();\n```\n\n## Global Test Surface\n\nIn dev/test, expose the marker surface:\n\n```ts\ncreateAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n});\n```\n\nThen inspect from the browser console or a test runner:\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"checkout failure\",\n  note: \"Expected saved cards to render before submit.\",\n});\n\nconst session = window.__AGENT_MARKERS__.export();\nsession.markers.length;\n```\n\nUse the global for test export, not as the only application API.\n\n## Capture Types\n\n| Capture | What It Adds | Watch For |\n| --- | --- | --- |\n| console | logs, warnings, errors | noisy output |\n| fetch | request URL, method, status, timing | request/response bodies may be sensitive |\n| errors | thrown errors and unhandled rejections | stack traces may include private paths |\n| manual | human-entered labels and notes | must be specific |\n| DOM hook | optional host-provided DOM snapshot | avoid private text |\n| screenshot hook | optional host-provided image capture | unavailable in some environments |\n| storage metadata | keys/counts, not full values by default | never dump secrets by accident |\n\nPrivacy rule:\n\n```text\nCapture metadata by default. Capture values only when deliberately enabled and safe.\n```\n\n## Marker Shape\n\nA useful marker has:\n\n```json\n{\n  \"label\": \"checkout saved card missing\",\n  \"note\": \"Expected saved payment methods to appear after login refresh; actual UI shows empty selector.\",\n  \"nextAction\": \"Inspect auth refresh state, checkout payment query, and recent fetch events.\"\n}\n```\n\nWeak marker:\n\n```json\n{\n  \"label\": \"broken\"\n}\n```\n\nBetter marker:\n\n```json\n{\n  \"label\": \"saved payment selector empty after refresh\",\n  \"note\": \"At this moment the user is logged in, the account menu shows the correct user, but checkout has no saved cards.\",\n  \"nextAction\": \"Compare account payment fetch response with checkout payment state.\"\n}\n```\n\n## Export A Debug Packet\n\nExport from browser:\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\nconsole.log(JSON.stringify(session, null, 2));\n```\n\nSave in a test:\n\n```ts\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\nawait testInfo.attach(\"agent-markers.json\", {\n  body: JSON.stringify(session, null, 2),\n  contentType: \"application/json\",\n});\n```\n\nOr write to disk in a local script:\n\n```js\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\nawait fs.promises.writeFile(\n  \"artifacts/agent-markers/checkout-session.json\",\n  JSON.stringify(session, null, 2)\n);\n```\n\n## Verify The Project\n\nCommon checks:\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\nWhat to look for:\n\n- marker can be created\n- marker has a human explanation\n- nearby events are linked with `nearbyEventIds`\n- console/fetch/error/manual events appear when enabled\n- storage values are not dumped by default\n- export JSON is valid\n- `stop()` restores patched browser APIs\n- test runner can access `window.__AGENT_MARKERS__`\n\n## Turn A Marker Export Into An Agent Prompt\n\nPrompt shape:\n\n```markdown\n# Debug Prompt From Agent Marker\n\n## Source Artifact\n\n- marker export:\n- schema version:\n- marker id:\n- marker label:\n\n## Human Explanation\n\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n\n## Nearby Evidence\n\n- console:\n- fetch:\n- error:\n- manual:\n- screenshot:\n- DOM:\n\n## Privacy Boundary\n\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private text removed:\n\n## Task\n\nFind the smallest likely bug path and propose the first verification command.\nDo not invent app state that is not in the marker packet.\n```\n\n## Bounded Replay Capsule\n\nDo not build a full recorder. Design the smallest packet that makes the marked moment inspectable.\n\n```markdown\n# Bounded Replay Capsule\n\n- schemaVersion:\n- markerId:\n- sessionId:\n- markerCutoffSeq:\n- nearbyEventIds:\n- console:\n- fetch:\n- errors:\n- manual:\n- screenshot:\n- dom:\n- redaction:\n\n## Boundaries\n\n- included:\n- excluded:\n- maximum event count:\n- privacy rules:\n\n## How To Use It\n\n- agent prompt:\n- human review:\n- verification command:\n```\n\n## App-Specific Marker Flow\n\nAn app may wire a shortcut such as `Ctrl+M` to create durable marker evidence.\n\nConceptual flow:\n\n```text\nCtrl+M\n-> create marker id\n-> capture screenshot if available\n-> open note/explanation UI\n-> save human explanation\n-> write durable app logs\n```\n\nExpected log strings:\n\n```text\ndev_marker\ndev_marker_explanation\n```\n\nInspection shape:\n\n```bash\nrg -n \"dev_marker|dev_marker_explanation\" <app-log-path>/latest-session.jsonl\n```\n\nKeep this generic:\n\n- one marker id shared across marker and explanation\n- screenshot optional\n- explanation required\n- bounded nearby evidence\n- clear next action\n\n## Ask The Agent This\n\nAdd markers to a browser bug investigation:\n\n```text\nAdd agent markers to the checkout browser flow.\n\nCapture console, fetch, errors, and manual markers. Expose\n`window.__AGENT_MARKERS__` in dev/test. Add a marker for the moment saved\npayment methods disappear after auth refresh. Export JSON and show how to\nconfirm nearbyEventIds, privacy defaults, and marker explanation.\n```\n\nTurn export into a debug prompt:\n\n```text\nUse this agent-marker export as the bounded debug packet.\n\nFocus on the marked checkout failure. Summarize the human explanation, nearby\nconsole/fetch/error/manual evidence, privacy boundaries, and the first\nverification command. Do not infer app state that is not in the packet.\n```\n\nWrite a test export:\n\n```text\nCreate a Playwright-style test path that triggers the checkout bug, calls\n`window.__AGENT_MARKERS__.mark(...)`, exports the session JSON, and attaches it\nas a test artifact. Include the checks that prove marker count, nearbyEventIds,\nand event types are present.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| marker client installed | app imports `createAgentMarkers` |\n| marker created | export has `markers.length > 0` |\n| explanation present | marker has a specific `note` |\n| nearby evidence linked | marker has non-empty `nearbyEventIds` |\n| console captured | exported events include console type |\n| fetch captured | exported events include fetch type |\n| errors captured | exported events include error type |\n| privacy default safe | storage values are absent unless deliberately enabled |\n| global test surface works | `window.__AGENT_MARKERS__.export()` returns session |\n| export saved | JSON artifact exists and is non-empty |\n| cleanup handled | `stop()` called when patching should end |\n| project verifies | `npm test`, `npm run typecheck`, `npm run build`, `npm run smoke:demo` |\n\n## If It Goes Wrong\n\n### Marker Has No Note\n\nAdd expected/actual context.\n\n```text\nWhat should have happened:\nWhat happened:\nWhy this moment matters:\nNext action:\n```\n\n### Export Has Too Many Raw Logs\n\nFocus on one marker id and its nearby events. Increase event limits deliberately, not by default.\n\n### `nearbyEventIds` Is Empty\n\nMark closer to the failure or adjust the nearby event window.\n\n### Sensitive Storage Values Were Captured\n\nRedact and rebuild the export. Capture storage metadata, not values, unless safe and intentional.\n\n### Console/Fetch Remains Patched\n\nCall:\n\n```ts\nmarkers.stop();\n```\n\n### Test Runner Cannot Export\n\nConfirm `exposeGlobal: true` in dev/test and wait for app readiness before reading `window.__AGENT_MARKERS__`.\n\n### Screenshot Or DOM Hook Is Missing\n\nMark it unavailable. Do not pretend a screenshot or DOM snapshot exists.\n\n## References And Resources\n\n- Agent marker client entry: `packages/client/src/index.ts`\n- Collector source: `packages/client/src/collector.ts`\n- Types: `packages/client/src/types.ts`\n- Demo app: `apps/demo/src/main.ts`\n- Viewer/export UI: `apps/demo/src/viewer.ts`\n- Smoke script: `scripts/smoke-demo.mjs`\n- Playwright docs: https://playwright.dev/docs/test-assertions\n- Cypress docs: https://docs.cypress.io/\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-marker-workflows-practice",
      "slug": "marker-workflows-practice",
      "title": "Agent Markers debugging workflows: practice drills",
      "summary": "Exercises for marking browser failures, initializing Agent Markers, exporting bounded evidence, reviewing privacy, attaching exports to tests, verifying projects, writing debug prompts, designing replay capsules and app-specific shortcuts, recovering from…",
      "category": "Verification",
      "tags": [
        "agent-markers",
        "debugging",
        "privacy",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 1: Identify The Marker Moment",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 2: Add The Client",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 3: Create And Export A Marker",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 4: Privacy Review",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 5: Test Runner Export",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 6: Verify The Project",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 7: Turn Export Into A Debug Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 8: Design A Bounded Replay Capsule",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 9: App-Specific Marker Flow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 10: Failure Path Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Exercise 11: Section 9 Bridge Packet",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/08-debugging-with-agent-markers.md#Exercises: 08. Debugging With Agent Markers/Final Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 1109,
      "url": "/topics/codex-marker-workflows-practice/",
      "markdownUrl": "/markdown/codex-marker-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-marker-workflows-practice.json",
      "headings": [
        {
          "id": "exercise-1-identify-the-marker-moment",
          "text": "Exercise 1: Identify The Marker Moment",
          "level": 2
        },
        {
          "id": "exercise-2-add-the-client",
          "text": "Exercise 2: Add The Client",
          "level": 2
        },
        {
          "id": "exercise-3-create-and-export-a-marker",
          "text": "Exercise 3: Create And Export A Marker",
          "level": 2
        },
        {
          "id": "exercise-4-privacy-review",
          "text": "Exercise 4: Privacy Review",
          "level": 2
        },
        {
          "id": "exercise-5-test-runner-export",
          "text": "Exercise 5: Test Runner Export",
          "level": 2
        },
        {
          "id": "exercise-6-verify-the-project",
          "text": "Exercise 6: Verify The Project",
          "level": 2
        },
        {
          "id": "exercise-7-turn-export-into-a-debug-prompt",
          "text": "Exercise 7: Turn Export Into A Debug Prompt",
          "level": 2
        },
        {
          "id": "exercise-8-design-a-bounded-replay-capsule",
          "text": "Exercise 8: Design A Bounded Replay Capsule",
          "level": 2
        },
        {
          "id": "exercise-9-app-specific-marker-flow",
          "text": "Exercise 9: App-Specific Marker Flow",
          "level": 2
        },
        {
          "id": "exercise-10-failure-path-drill",
          "text": "Exercise 10: Failure Path Drill",
          "level": 2
        },
        {
          "id": "exercise-11-section-9-bridge-packet",
          "text": "Exercise 11: Section 9 Bridge Packet",
          "level": 2
        },
        {
          "id": "final-check",
          "text": "Final Check",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Agent Markers debugging workflows: practice drills\n\nThese exercises practice creating a bounded debug packet from a marked browser moment.\n\n## Exercise 1: Identify The Marker Moment\n\nChoose a bug and write the marker.\n\n```markdown\n# Marker Moment\n\n- app area:\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n- what nearby evidence should be captured:\n```\n\nGood marker:\n\n```json\n{\n  \"label\": \"saved payment selector empty after refresh\",\n  \"note\": \"Expected saved cards to stay visible after auth refresh; actual selector is empty.\",\n  \"nextAction\": \"Compare account payment fetch response with checkout payment state.\"\n}\n```\n\n## Exercise 2: Add The Client\n\nSketch the setup:\n\n```ts\nimport { createAgentMarkers } from \"@agent-markers/client\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n  capture: {\n    console: true,\n    fetch: true,\n    errors: true,\n  },\n});\n```\n\nFill out:\n\n```markdown\n# Client Setup\n\n- app name:\n- exposeGlobal enabled? yes/no\n- console capture? yes/no\n- fetch capture? yes/no\n- error capture? yes/no\n- privacy concern:\n```\n\n## Exercise 3: Create And Export A Marker\n\nRun in browser console or test:\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"checkout failure\",\n  note: \"Expected saved cards to render before submit.\",\n  nextAction: \"Inspect checkout payment query and auth refresh state.\",\n});\n\nconst session = window.__AGENT_MARKERS__.export();\nJSON.stringify(session, null, 2);\n```\n\nFill out:\n\n```markdown\n# Marker Export\n\n- marker count:\n- event count:\n- marker label:\n- marker note:\n- nearbyEventIds present? yes/no\n- event types:\n```\n\n## Exercise 4: Privacy Review\n\nInspect the export.\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  schemaVersion: session.schemaVersion,\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  storageHasValues: JSON.stringify(session).includes(\"secret-value\"),\n});\n```\n\nFill out:\n\n```markdown\n# Privacy Review\n\n- storage keys captured:\n- storage values captured? yes/no\n- request bodies captured? yes/no\n- response bodies captured? yes/no\n- private text present? yes/no\n- redaction needed:\n```\n\n## Exercise 5: Test Runner Export\n\nPlaywright-style shape:\n\n```ts\nconst session = await page.evaluate(() => window.__AGENT_MARKERS__.export());\n\nawait testInfo.attach(\"agent-markers.json\", {\n  body: JSON.stringify(session, null, 2),\n  contentType: \"application/json\",\n});\n```\n\nFill out:\n\n```markdown\n# Test Export\n\n- test command:\n- export artifact:\n- marker count:\n- nearbyEventIds present? yes/no\n- test can access global? yes/no\n- app readiness check:\n```\n\n## Exercise 6: Verify The Project\n\nRun:\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\nFill out:\n\n```markdown\n# Verification\n\n- npm test:\n- npm run typecheck:\n- npm run build:\n- npm run smoke:demo:\n- failed command:\n- next debugging step:\n```\n\n## Exercise 7: Turn Export Into A Debug Prompt\n\nWrite:\n\n```markdown\n# Debug Prompt From Agent Marker\n\n## Source Artifact\n\n- marker export:\n- schema version:\n- marker id:\n- marker label:\n\n## Human Explanation\n\n- expected:\n- actual:\n- why this moment matters:\n- next action:\n\n## Nearby Evidence\n\n- console:\n- fetch:\n- error:\n- manual:\n- screenshot:\n- DOM:\n\n## Privacy Boundary\n\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private text removed:\n\n## Task\n\nFind the smallest likely bug path and propose the first verification command.\nDo not invent app state that is not in the marker packet.\n```\n\n## Exercise 8: Design A Bounded Replay Capsule\n\nDo not implement a recorder. Design the packet.\n\n```markdown\n# Bounded Replay Capsule\n\n- schemaVersion:\n- markerId:\n- sessionId:\n- markerCutoffSeq:\n- nearbyEventIds:\n- console:\n- fetch:\n- errors:\n- manual:\n- screenshot:\n- dom:\n- redaction:\n\n## Boundaries\n\n- included:\n- excluded:\n- maximum event count:\n- privacy rules:\n\n## How To Use It\n\n- agent prompt:\n- human review:\n- verification command:\n```\n\nQuestion:\n\n```text\nWhat is the smallest capsule that would let someone debug the marked moment?\n```\n\n## Exercise 9: App-Specific Marker Flow\n\nInspect or design a shortcut flow.\n\n```text\nCtrl+M\n-> create marker id\n-> capture screenshot if available\n-> open note/explanation UI\n-> save human explanation\n-> write durable app logs\n```\n\nPossible inspection command:\n\n```bash\nrg -n \"dev_marker|dev_marker_explanation\" <app-log-path>/latest-session.jsonl\n```\n\nFill out:\n\n```markdown\n# App-Specific Marker Flow\n\n- shortcut:\n- marker id format:\n- screenshot available? yes/no:\n- explanation UI:\n- log path:\n- `dev_marker` written? yes/no:\n- `dev_marker_explanation` written? yes/no:\n- shared marker id? yes/no:\n- what this preserves:\n- what this does not try to solve:\n```\n\n## Exercise 10: Failure Path Drill\n\nFor each failure, choose a recovery.\n\n| Failure | Recovery |\n| --- | --- |\n| marker has no note | |\n| export has thousands of raw log entries | |\n| marker has empty nearbyEventIds | |\n| exported JSON contains sensitive storage values | |\n| console/fetch remains patched after test | |\n| Playwright cannot read `window.__AGENT_MARKERS__` | |\n| marker does not say what to inspect next | |\n| screenshot hook returns nothing | |\n| DOM snapshot includes private text | |\n| smoke test fails before clicking marker buttons | |\n\nRecovery options:\n\n```text\nadd expected/actual note\nfocus on one marker id\nmark closer to the failure\nraise nearbyEventLimit deliberately\nredact and rebuild export\nrestore with stop()\nenable exposeGlobal in dev/test\nwait for app readiness\nadd next action\nmark screenshot unavailable\nnarrow DOM snapshot\nsave failed smoke and retry with sharper condition\n```\n\n## Exercise 11: Section 9 Bridge Packet\n\nUse one marker export to prepare a bounded work unit.\n\n```markdown\n# Section 9 Bridge: Imp Debug Packet\n\n- source artifact: DebugSession export\n- schemaVersion:\n- marker id:\n- marker label:\n- marker note:\n- nearbyEventIds:\n- evidence lanes:\n  - console:\n  - fetch:\n  - error:\n  - manual:\n- privacy checks:\n  - storageHasValues:\n  - request bodies exported? no\n  - response bodies exported? no\n- likely app area:\n- required verification:\n  - npm test\n  - npm run typecheck\n  - npm run build\n- next action:\n```\n\nFill out:\n\n```markdown\n# Bridge Review\n\n- packet names one marker id? yes/no:\n- nearby evidence is bounded? yes/no:\n- privacy rules are explicit? yes/no:\n- verification commands are present? yes/no:\n- task is clear enough for an Imp? yes/no:\n- what would make it smaller or sharper:\n```\n\n## Final Check\n\nInspect manually:\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  schemaVersion: session.schemaVersion,\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),\n  eventTypes: [...new Set(session.events.map((event) => event.type))],\n});\n```\n\nFill out:\n\n```markdown\n# Final Agent Markers Check\n\n- marker created? yes/no:\n- marker has human explanation? yes/no:\n- nearbyEventIds present? yes/no:\n- console evidence captured? yes/no:\n- fetch evidence captured? yes/no:\n- error evidence captured? yes/no:\n- manual evidence captured? yes/no:\n- storage values avoided? yes/no:\n- export saved? yes/no:\n- test runner can export? yes/no:\n- `stop()` cleanup handled? yes/no:\n- next action written? yes/no:\n- ready to hand off as bounded debug packet? yes/no:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-artifact-evidence",
      "slug": "artifact-evidence",
      "title": "Artifact evidence is not the same as success",
      "summary": "Separate observed creation, command execution, visible output, and verified completion; preserve failures and the exact next check.",
      "category": "Verification",
      "tags": [
        "artifacts",
        "receipts",
        "failures"
      ],
      "sources": [
        {
          "label": "Artifact reference",
          "url": "https://proud-anchor-53zn.here.now/artifacts.md"
        }
      ],
      "sourceUnits": [
        "artifacts.md#evidence-levels"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 190,
      "url": "/topics/factory-artifact-evidence/",
      "markdownUrl": "/markdown/factory-artifact-evidence.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-artifact-evidence.json",
      "headings": [
        {
          "id": "evidence-levels",
          "text": "Evidence levels",
          "level": 2
        }
      ],
      "markdown": "# Artifact evidence is not the same as success\n\nSeparate observed creation, command execution, visible output, and verified completion; preserve failures and the exact next check.\n\n## Evidence levels\n\nA file appearing does not prove that its contents work. A command running does not prove that it finished successfully. A successful structural check does not prove behavior in the application. Keep each event separate, attach the relevant artifact or exact signal, and state what remains unverified.\n\nUseful receipts answer: what was attempted; what changed; what was actually observed; which check ran; what passed or failed; what remains uncertain; and what the next session should reproduce. Failed demonstrations are evidence, not editorial blemishes to erase.\n\nThe environment examples demonstrate stderr guidance, quarantine behavior, blocked destructive commands, and rewritten issue flags under a test harness. Their own caveats distinguish those results from a live agent’s tendency to comply. The MDFlow example demonstrates inspection and proposal mechanics while retaining an unverified eval roster and a wrapper exercise that did not cleanly succeed. The Markers example is a deliberately planted bug and a bounded redacted trail, not a measured success rate on organic bugs."
    },
    {
      "id": "foundations-browser-proof-field-guide",
      "slug": "browser-proof-field-guide",
      "title": "Browser Proof Field Guide",
      "summary": "Make Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.",
      "category": "Verification",
      "tags": [
        "field guide",
        "browser proof"
      ],
      "sources": [
        {
          "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
        },
        {
          "label": "Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-08.html"
        },
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#browser-proof/overview",
        "field-guides/guides.mjs#browser-proof/quote",
        "field-guides/guides.mjs#browser-proof/decision",
        "field-guides/guides.mjs#browser-proof/agentPrompt",
        "field-guides/guides.mjs#browser-proof/stories",
        "field-guides/guides.mjs#browser-proof/tips",
        "field-guides/guides.mjs#browser-proof/refs"
      ],
      "collection": "foundations",
      "categoryId": "verification",
      "wordCount": 505,
      "url": "/topics/foundations-browser-proof-field-guide/",
      "markdownUrl": "/markdown/foundations-browser-proof-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-browser-proof-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "authenticated-billing-route",
          "text": "Authenticated billing route",
          "level": 3
        },
        {
          "id": "pricing-weird-path-qa",
          "text": "Pricing weird-path QA",
          "level": 3
        },
        {
          "id": "preview-deployment-triage",
          "text": "Preview deployment triage",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Browser Proof Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nMake Codex prove rendered web behavior with routes, actions, logs, screenshots, and receipts.\n\nUse this when a UI, auth, form, route, or responsive change cannot be considered done from source inspection alone.\n\n> Browser automation CLI designed for AI agents.\n\n[agent-browser docs](https://agent-browser.dev/)\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| Codex Browser | Local/public unauthenticated route | Fast visual proof and screenshots | .notes/browser-proof/<task>/browser-proof.md |\n| Chrome extension/manual Chrome | Signed-in browser state | Auth flows and internal SaaS pages | Redacted manual proof plus screenshot |\n| agent-browser | Terminal-friendly browser control | snapshot, click, fill, screenshot | snapshot.txt plus screenshot.png |\n| Playwright | Repeatable or CI-friendly flow | Trace, console, screenshot, deterministic test | trace.zip plus console.json |\n| DevTools/CDP | Raw console/network evidence | HAR, console objects, performance details | console.log plus network.har |\n\n## Agent-ready prompt\n\n```text\nUse browser proof before claiming this UI task is done.\nInspect package.json and AGENTS.md first.\nPick the browser surface that matches the auth and repeatability needs.\nSave .notes/browser-proof/<task>/browser-proof.md with URL, viewport, auth context, actions, expected/observed result, console errors, network failures, artifacts, command output, diff summary, and pass/fail.\nRedact cookies, tokens, customer data, QR codes, and auth headers.\n```\n\n## Applied stories\n\n### Authenticated billing route\n\n**Role:** SaaS frontend engineer\n\nCodex changed /settings/billing, but the route only works when logged in.\n\n**Agent brief:** Use signed-in Chrome or a seeded login; verify current plan, change plan, submit, and capture final visible success state.\n\n**Done when:**\n\n- browser-proof.md\n- screenshot\n- console/network summary\n- typecheck/test log\n\n### Pricing weird-path QA\n\n**Role:** Growth engineer\n\nPlan toggles, coupons, and checkout modals fail after repeated back/refresh/toggle sequences.\n\n**Agent brief:** Run five browser QA perspectives and collate reproducible findings into .notes/qa/pricing-summary.md.\n\n**Done when:**\n\n- perspective files\n- summary severity list\n- screenshots/transcripts\n- console status\n\n### Preview deployment triage\n\n**Role:** Frontend lead\n\nA PR preview is green but nobody opened changed routes.\n\n**Agent brief:** Discover preview URL, open homepage and changed route, capture status, visible error text, console errors, and screenshot.\n\n**Done when:**\n\n- preview URL\n- browser receipt\n- blocker/warning/clean verdict\n- no source edits\n\n## Tips and gotchas\n\n- Tests prove code paths; browser proof proves user-visible behavior.\n- Use the in-app browser for localhost/public pages, but use Chrome/manual auth for signed-in state.\n- Do not make Playwright mandatory for every UI task; use it when repeatability matters.\n- Treat screenshots, traces, HARs, and console logs as sensitive local artifacts by default.\n- A Stop hook should check receipt files, not drive the browser itself.\n\n## References\n\n- [Codex in-app browser](https://developers.openai.com/codex/app/browser)\n- [Codex Chrome extension](https://developers.openai.com/codex/app/chrome-extension)\n- [agent-browser](https://github.com/vercel-labs/agent-browser)\n- [Playwright screenshots](https://playwright.dev/docs/screenshots)\n- [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer)\n- [Chrome DevTools Console](https://developer.chrome.com/docs/devtools/console/log)\n\n## Related principles\n\n- [Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n- [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
    },
    {
      "id": "foundations-perspective-qa-and-testing",
      "slug": "perspective-qa-and-testing",
      "title": "Explore software through perspectives and runtime QA",
      "summary": "Use perspective-based prompting and discardable QA files for non-obvious user paths; Apply the 5 Monkeys technique and use CMUX state for context-aware shortcuts; Extract implementation intent from narrated screen recordings into Gemini.",
      "category": "Verification",
      "tags": [
        "QA",
        "testing",
        "perspectives"
      ],
      "sources": [
        {
          "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#05/objectives",
        "oracle/05-references.json#recap",
        "oracle/05-references.json#concepts/0",
        "oracle/05-references.json#concepts/1",
        "oracle/05-references.json#concepts/2",
        "oracle/05-references.json#concepts/3",
        "oracle/05-references.json#concepts/4",
        "oracle/05-references.json#references",
        "oracle/05-references.json#recommendations",
        "oracle/05-interactive.json#intro",
        "oracle/05-interactive.json#checklist",
        "oracle/05-interactive.json#challenges",
        "oracle/05-interactive.json#quiz",
        "oracle/05-interactive.json#reflect",
        "oracle/05-references.json#goDeeper",
        "materials/exercises.md#Chunk-05",
        "materials/qa-index.md#Q019",
        "materials/qa-index.md#Q020",
        "materials/qa-index.md#Q021",
        "materials/qa-index.md#Q022",
        "materials/qa-index.md#Q023",
        "materials/qa-index.md#Q024",
        "final/qa-index.md#Chunk-05",
        "materials/keyframes.md#Chunk-05",
        "lesson-05.html#resource-packet",
        "lesson-05.html#clip-map",
        "lesson-05.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "verification",
      "wordCount": 3037,
      "url": "/topics/foundations-perspective-qa-and-testing/",
      "markdownUrl": "/markdown/foundations-perspective-qa-and-testing.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-perspective-qa-and-testing.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "perspective-based-prompting",
          "text": "Perspective-based prompting",
          "level": 3
        },
        {
          "id": "discardable-qa-files",
          "text": "Discardable QA files",
          "level": 3
        },
        {
          "id": "the-5-monkeys-technique",
          "text": "The 5 Monkeys technique",
          "level": 3
        },
        {
          "id": "cmux-state-for-context-aware-shortcuts",
          "text": "CMUX state for context-aware shortcuts",
          "level": 3
        },
        {
          "id": "video-driven-intent-extraction",
          "text": "Video-driven intent extraction",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "agent-browser",
          "text": "Agent Browser",
          "level": 3
        },
        {
          "id": "clicklight",
          "text": "ClickLight",
          "level": 3
        },
        {
          "id": "cleanshot",
          "text": "CleanShot",
          "level": 3
        },
        {
          "id": "gemini-video-prompting",
          "text": "Gemini video prompting",
          "level": 3
        },
        {
          "id": "tailscale",
          "text": "Tailscale",
          "level": 3
        },
        {
          "id": "karabiner-elements",
          "text": "Karabiner-Elements",
          "level": 3
        },
        {
          "id": "cmux-inspect",
          "text": "CMUX inspect",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "four-lens-qa-pass",
          "text": "Four-Lens QA Pass",
          "level": 3
        },
        {
          "id": "mini-5-monkeys-run",
          "text": "Mini 5 Monkeys Run",
          "level": 3
        },
        {
          "id": "video-intent-to-instructions",
          "text": "Video Intent to Instructions",
          "level": 3
        },
        {
          "id": "single-branch-agent-coordination-with-safeguards",
          "text": "Single-Branch Agent Coordination With Safeguards",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "why-does-perspective-based-prompting-usually-produce-better-qa-findings-than-asking-one-generic-agent-to-test-the-app",
          "text": "Why does perspective-based prompting usually produce better QA findings than asking one generic agent to test the app?",
          "level": 3
        },
        {
          "id": "what-makes-a-discardable-qa-file-useful-in-this-lesson-s-workflow",
          "text": "What makes a discardable QA file useful in this lesson's workflow?",
          "level": 3
        },
        {
          "id": "which-instruction-best-matches-the-5-monkeys-technique",
          "text": "Which instruction best matches the 5 Monkeys technique?",
          "level": 3
        },
        {
          "id": "why-is-exposing-cmux-state-as-an-object-powerful-for-a-codex-style-workflow",
          "text": "Why is exposing CMUX state as an object powerful for a Codex-style workflow?",
          "level": 3
        },
        {
          "id": "what-is-the-safest-way-to-apply-the-video-to-instructions-workflow-from-the-lesson",
          "text": "What is the safest way to apply the video-to-instructions workflow from the lesson?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "when-generating-a-lot-of-research-what-guiding-principles-do-you-reach-for-for-staying-organized-as-well-as-optimized-for-the-retrieval",
          "text": "When generating a lot of research, what guiding principles do you reach for for staying organized, as well as optimized for the retrieval?",
          "level": 3
        },
        {
          "id": "do-you-have-a-goto-system-for-agents-to-test-and-verify-via-browser-i-have-issues-with-auth-etc",
          "text": "do you have a goto system for agents to test and verify via browser? i have issues, with auth, etc...",
          "level": 3
        },
        {
          "id": "do-you-use-worktrees-shortcut-that-copies-over-env-as-well-and-shut-them-down",
          "text": "do you use worktrees? shortcut that copies over .env as well? and shut them down?",
          "level": 3
        },
        {
          "id": "is-screendrop-what-you-were-using-when-you-were-sending-stuff-to-other-mac-using-oracle-you-could-see-your-other-mac-in-realtime",
          "text": "is screendrop what you were using when you were sending stuff to other mac using oracle? you could see your other mac in realtime?",
          "level": 3
        },
        {
          "id": "what-are-your-thoughts-on-testing-these-qa-files-seem-like-a-partial-replacement-for-rigorous-testing-suites",
          "text": "What are your thoughts on testing? These QA files seem like a partial replacement for rigorous testing suites.",
          "level": 3
        },
        {
          "id": "so-it-would-be-interesting-to-see-how-you-keep-track-so-is-it-just-that-you-have-the-different-conversations-pinned-to-the-left-and-then-you-look-at-them-to-keep-an-overview-or-how-do-we-do-it-and-then-especially-this-research-planning-building-part-and-the-specialized-agents",
          "text": "So, it would be interesting to see how you keep track. So, is it just that you have the different conversations pinned to the left, and then you look at them to keep an overview, or how do we do it? And then, especially this research, planning, building part, and the specialized agents?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Explore software through perspectives and runtime QA\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is using agents as perspective-driven explorers instead of asking one generic agent to test or research everything. John shows how lenses like expert, new user, grandma, and power user can shape research and QA, how discardable QA files can push agents through non-obvious app paths, and how rough narrated screen recordings can become implementation instructions. He also explains how CMUX state can power context-aware shortcuts, why he often avoids worktree overhead, and where rigorous tests still belong: stable business logic rather than fast-changing UI experiments.\n\n## Working outcomes\n\n- Use perspective-based prompting and discardable QA files for non-obvious user paths\n- Apply the 5 Monkeys technique and use CMUX state for context-aware shortcuts\n- Extract implementation intent from narrated screen recordings into Gemini\n\n## Concepts and consequences\n\n### Perspective-based prompting\n\nInstead of asking one generic agent to research or test your app, assign it a lens: expert, new user, grandma, power user, or another real audience. That lens changes what the agent notices and which assumptions it challenges.\n\n**Why it matters:** It helps you escape creator bias and shape the output around the actual demographics or user types your application needs to support.\n\n### Discardable QA files\n\nA QA file is a temporary assignment document for an agent: a numbered list of things to try, paths to walk, buttons to find, and a perspective to act from. John treats these as created in the moment, not as permanent test infrastructure.\n\n**Why it matters:** They let you test the current shape of a fast-changing product without locking every changing UI decision into a brittle long-term test suite.\n\n### The 5 Monkeys technique\n\nThe goal is to have agents use the app in non-obvious ways: find buttons, click around, try shortcuts, press back after reaching a page, and look for modes or state that stay open unexpectedly.\n\n**Why it matters:** This catches UX and state issues that a normal verification prompt may miss because the model tends to follow the same visible patterns the developer already expects.\n\n### CMUX state for context-aware shortcuts\n\nJohn describes a CMUX inspect-style command that exposes the multiplexer state as an object, including the focused pane and that pane’s current working directory. He uses that context with a Karabiner shortcut to open tools over the terminal he is already focused on.\n\n**Why it matters:** It turns the terminal layout into an automation surface: a shortcut can open an editor, run Git commands, start debugging, or trigger other tools in the project you are currently looking at.\n\n### Video-driven intent extraction\n\nJohn records a rough screen interaction, narrates UI changes aloud, and drops the video into Gemini to turn it into AI instructions for implementation.\n\n**Why it matters:** It lowers the cost of explaining visual changes when pointing, circling, and talking are faster than writing a polished written spec.\n\n## Reference tools and resources\n\n### Agent Browser\n\nAn experimental Vercel Labs browser-agent project John named as his go-to tool for controlling sites, clicking through pages, inspecting DOM state, and using Chrome DevTools-style information.\n\n**Use when:** Reach for it when you want an agent to verify UI behavior in an actual browser. In this section, John described the tool but said he would dig into it more later.\n\n[Reference](https://github.com/vercel-labs/agent-browser)\n\n### ClickLight\n\nA desktop overlay tool John briefly demonstrated for showing clicks, cursor actions, drawings, and keyboard shortcuts during screen shares.\n\n**Use when:** Use it when recording or presenting a workflow where viewers need to see what you clicked or typed. It was a supporting presentation tool in this section, not the core QA technique.\n\n[Reference](https://github.com/aurorascharff/ClickLight)\n\n### CleanShot\n\nA screenshot and screen recording tool John used to capture a quick narrated UI-change video.\n\n**Use when:** Reach for it, or any similar screen recorder, when a visual change is easier to show and narrate than to describe in text.\n\nsearch: CleanShot screen recording app\n\n### Gemini video prompting\n\nJohn used Gemini for video understanding by dropping in a screen recording and asking it to convert the interaction into AI instructions.\n\n**Use when:** Use it when your intended change is easier to communicate through a narrated screen recording, especially for visual layout work.\n\nsearch: Gemini video understanding prompt screen recording instructions\n\n### Tailscale\n\nA mesh networking tool John used to connect to another Mac and SSH into it from his local workflow.\n\n**Use when:** Use it when you need private remote machine access from your local agent or terminal workflow without exposing services broadly.\n\n[Reference](https://tailscale.com)\n\n### Karabiner-Elements\n\nA macOS keyboard customization tool John used as part of a global shortcut workflow that opened an editor/search overlay in the context of the active terminal.\n\n**Use when:** Reach for it when you want app-global shortcuts that can trigger workspace-aware scripts or tools from wherever you are focused.\n\nsearch: Karabiner-Elements macOS keyboard customizer\n\n### CMUX inspect\n\nA CMUX inspection pattern John described as returning an object for the multiplexer state, including the focused pane and current working directory.\n\n**Use when:** Reach for this pattern when you want shortcuts or agents to act on the exact terminal pane and project you are currently focused on.\n\nsearch: CMUX inspect focused pane current working directory\n\n## Recommendations and best practices\n\n- Create separate research or QA prompts for expert, new-user, power-user, and inexperienced-user perspectives instead of asking one generic agent to cover everything.\n- Write QA files as disposable numbered assignments, not permanent monuments; keep them cheap enough that you are willing to delete and regenerate them.\n- Tell agents to explore non-obvious paths explicitly: find buttons, try shortcuts, press back after navigation, change modes, and look for state that stays open unexpectedly.\n- Keep rigorous tests for stable business logic and locked-down parts of the system; avoid over-testing UI areas you still expect to reshape frequently.\n- Use browser-driving tools when the task needs real clicking, DOM inspection, or performance/devtools signals rather than code inspection alone.\n- When a UI change is easier to show than write, record a short narrated screen video and ask a multimodal model to turn it into implementation instructions.\n- Watch disk usage when running many agents or worktrees on compiled projects; build artifacts such as Rust target directories can balloon fast.\n- For performance-sensitive apps, have QA agents capture memory, performance, API-call, refresh, and latency signals while they walk through the app if your tooling supports it.\n\n## Practice and acceptance criteria\n\nPractice using agents as cheap, perspective-driven explorers so you can find UI blind spots without turning every fast-changing experiment into permanent test infrastructure.\n\n### Checklist\n\n1. Pick one feature or screen in your current app that has enough UI state to be interesting: navigation, modes, shortcuts, buttons, or other interactions.\n2. Create four short perspective prompts for the same feature: expert user, first-time user, inexperienced user, and power user.\n3. Write a temporary QA file with numbered tasks that explicitly ask agents to find buttons and try non-obvious paths such as shortcuts, back navigation, mode changes, and partial navigation sequences.\n4. Run separate agent or browser-verification passes against the same feature using different perspective prompts.\n5. Review the outputs for concrete non-obvious paths, stuck states, confusing UX, or repeated happy-path behavior that did not teach you anything new.\n6. For each useful finding, decide whether it belongs in a durable test because it covers stable business logic, or whether it should stay flexible because the UI is still changing.\n7. For one visual UI change, record a short narrated screen video and ask a multimodal model to turn it into implementation instructions.\n8. Inspect your terminal or multiplexer state as structured data if your setup supports it, and note which fields would let a shortcut target the correct working directory automatically.\n9. If you run many agents, worktrees, or compiled builds, watch for large generated artifacts and decide whether you need a disk-usage safeguard.\n\n### Four-Lens QA Pass\n\n**Difficulty:** Easy\n\nChoose one UI flow and create discardable QA prompts for expert, new-user, inexperienced-user, and power-user perspectives. Run an agent pass for each perspective and compare what each one notices.\n\n**Done when:** You have at least one finding or observation that appears in only one perspective's output, showing that the lens changed the exploration.\n\n### Mini 5 Monkeys Run\n\n**Difficulty:** Medium\n\nWrite a numbered QA assignment that tells agents to explore non-obvious behavior: find buttons, try shortcuts, use back navigation, move through partial flows, change modes, and look for state that stays open unexpectedly.\n\n**Done when:** You end with notes about any surprising paths, stuck states, mode issues, or confirmation that the non-happy-path pass did not reveal a useful issue.\n\n### Video Intent to Instructions\n\n**Difficulty:** Medium\n\nRecord a short screen video of a UI you want changed while narrating what should change visually, such as button styling, section order, or header placement. Feed it to a multimodal model and ask for implementation instructions, then review the useful parts before turning them into an agent prompt.\n\n**Done when:** The resulting prompt contains concrete visual changes and references to the relevant UI elements without requiring another person to watch the video.\n\n### Single-Branch Agent Coordination With Safeguards\n\n**Difficulty:** Hard\n\nPrototype a single-branch multi-agent workflow for one feature: ask a manager agent to assign bounded parallel tasks, keep the agents in the same project instead of adding worktrees by default, and add a simple disk-usage check for large generated build artifacts.\n\n**Done when:** You can run exploratory agent work without unnecessary worktree overhead, with clear task boundaries and a visible safeguard against runaway build artifacts.\n\n## Questions to test understanding\n\n### Why does perspective-based prompting usually produce better QA findings than asking one generic agent to test the app?\n\n- **A.** It changes what the agent notices, which assumptions it questions, and which paths it tries.\n- **B.** It guarantees the agent will write production-ready integration tests.\n- **C.** It makes the agent reuse your existing browser cookies automatically.\n- **D.** It prevents the agent from exploring anything outside the happy path.\n\n**Answer: A.** A persona or lens pushes the agent toward different risks and user behaviors. An expert, new user, grandma, and power user will naturally stress different parts of the same interface.\n\n### What makes a discardable QA file useful in this lesson's workflow?\n\n- **A.** It becomes the final source of truth for every future regression test.\n- **B.** It gives an agent a temporary numbered mission that can be regenerated as the UI changes.\n- **C.** It replaces all business-logic tests permanently.\n- **D.** It stores private auth cookies so browser agents can skip login.\n\n**Answer: B.** The point is cheap scaffolding: numbered tasks, a perspective, and non-obvious paths for the current version of the product. It should be easy to delete or rewrite.\n\n### Which instruction best matches the 5 Monkeys technique?\n\n- **A.** Confirm that the signup button works using only the documented happy path.\n- **B.** Inspect the codebase and summarize every component dependency.\n- **C.** Find buttons, try shortcuts, press back after navigation, change modes, and look for surprising state behavior.\n- **D.** Write a complete Playwright suite before looking at the UI.\n\n**Answer: C.** The 5 Monkeys idea in this section is to push agents toward non-obvious app usage rather than one careful happy-path check. John’s example was a shortcut leading to a page, then pressing back and noticing a mode stayed open.\n\n### Why is exposing CMUX state as an object powerful for a Codex-style workflow?\n\n- **A.** It lets a shortcut or agent target the focused pane and current working directory without manual setup.\n- **B.** It automatically fixes merge conflicts across all branches.\n- **C.** It encrypts remote SSH traffic without any other tool.\n- **D.** It converts screen recordings into implementation instructions.\n\n**Answer: A.** Structured pane state turns your terminal layout into an automation surface. A global shortcut can launch the right editor, Git command, debugger, or other tool in the context you are already focused on.\n\n### What is the safest way to apply the video-to-instructions workflow from the lesson?\n\n- **A.** Record a rough interaction, narrate the intended UI changes clearly, ask a multimodal model for implementation steps, then review the output before coding.\n- **B.** Record a video silently and let the model infer all business requirements.\n- **C.** Upload sensitive production data because video prompts are always private by default.\n- **D.** Treat the model's generated checklist as production code with no human review.\n\n**Answer: A.** The video only needs to be clear enough to communicate visual intent, especially with narration and pointing. The generated instructions are a draft to inspect, not a substitute for judgment.\n\n## Reflection prompts\n\n- Where are you currently over-testing a fast-changing UI when a discardable QA file would give you faster learning?\n- Which user perspective is most underrepresented in your current development process, and what would that person probably try that you would not?\n- What parts of your local workflow could become automation surfaces if your focused pane and working directory were available as structured state?\n\n## Further applications\n\n1. Build a four-perspective prompt matrix for one feature and compare what each persona notices that the others miss.\n2. Create a throwaway QA file with numbered non-obvious path tasks and run agent passes against the same UI.\n3. Prototype a video-to-instructions loop: record 30 seconds of pointing and narration, then ask a multimodal model for junior-developer implementation steps.\n4. Add lightweight performance logging to QA runs so agents capture memory, API calls, refreshes, and latency while they explore.\n5. Experiment with a single-branch multi-agent workflow before adding worktrees, and only add worktrees when isolation clearly beats the coordination overhead.\n\n## Applied exercises\n\nPerspective Prompt Matrix Blueprint\n\n**Objective:**  Construct a flexible research template config folder containing four distinct system prompts: persona-expert.md, persona-novice.md, persona-grandparent.md, and persona-poweruser.md. Write an execution bash script using a local LLM CLI tool to process an identical feature specification document across all four prompts, outputting isolated markdown results into a retrieval/ target folder.Video-to-Code Instructional Pipeline\n\n**Objective:**  Replicate John’s rapid layout prototyping pipeline. Use any native capture tool (e.g., CleanShot, QuickTime) to record a 30-second screen interaction of an existing local frontend interface. Explicitly dictate audio adjustments (e.g., color alterations, structural re-ordering). Process the raw output file directly through a long-context multimodal model like Gemini, and evaluate the clarity of the resulting markdown instructions.\n\n## Questions and answers\n\n### When generating a lot of research, what guiding principles do you reach for for staying organized, as well as optimized for the retrieval?\n\nJohn relies on the core concept of perspective-based prompting. Instead of collecting unstructured data dumps, he assigns specific personas (expert, new user, grandparent, power user) to separate data pipelines. He also generates modular, numbered QA assignment files that instruct agents to discover non-obvious app paths, keeping the output highly targeted and organized.\n\n### do you have a goto system for agents to test and verify via browser? i have issues, with auth, etc...\n\nJohn uses Agent Browser, an open-source experimental project originating from Vercel Labs. It excels at driving Chrome dev tools, analyzing performance metrics, and navigating complex layouts. Note that as pointed out in the chat session, it does not implicitly forward local browser cookies, so prompts must include explicit onboarding steps or registration rules for authentication sequences.\n\n### do you use worktrees? shortcut that copies over .env as well? and shut them down?\n\nJohn used to rely on Git worktrees when models were less capable, but has mostly abandoned them. Because his recent projects at Vercel have been isolated solo assignments, he prefers working directly out of a single main branch or standard PR branch. Instead of juggling port mappings and setting up environment configurations for separate worktrees, he lets parallel agents operate within bounded directories in the same branch. This avoids a known issue where massive Rust compilation targets duplicate disk usage and exhaust disk space.\n\n### is screendrop what you were using when you were sending stuff to other mac using oracle? you could see your other mac in realtime?\n\nNo, Screendrop is a separate open-source, local alternative to Clean Shot that John is tracking. The remote display synchronization shown earlier was simply Apple’s native mac OS Screen Sharing app routed securely across a private Tailscale mesh network connection.\n\n### What are your thoughts on testing? These QA files seem like a partial replacement for rigorous testing suites.\n\nJohn confirms he increasingly leans toward discardable runtime QA files over heavy test suites. Because code generation tools make changing software quick and trivial, over-indexing on rigid testing setups creates friction against iteration. He advises keeping strict test suites strictly reserved for fixed business logic that will not change, while using flexible QA agents running overnight loops to handle fluid visual interface verification.\n\n### So, it would be interesting to see how you keep track. So, is it just that you have the different conversations pinned to the left, and then you look at them to keep an overview, or how do we do it? And then, especially this research, planning, building part, and the specialized agents?\n\nJohn begins to answer as the chunk cuts off, explaining that tracking specialized agents involves coordinating dedicated task-based UI interfaces and distinct workspace contexts. \n\nThe continuation uses a primary orchestrator and distinct focused panes for quality control, performance, research, and note-taking.\n\n## Operational playbooks\n\n- [5 Monkeys QA swarm](/topics/foundations-five-monkeys-playbook/)\n\n- [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/)\n- [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-05.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-05.html)\n\n### Visual reference index\n\n- [01:41:00](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-1): Agent Browser GitHub documentation display on Chrome\n- [01:42:40](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-2): Editor view showing generated website update instructions and text/code edits\n- [01:45:50](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-3): GitHub/repository picker or file search view with ClickLight-related repository visible\n- [01:46:45](https://codex-workshop-followup.pages.dev/lesson-05.html#clip-05-4): Signal Knit hoodie site preview with layout/selection overlay visible\n- [01:48:15](https://codex-workshop-followup.pages.dev/lesson-05.html): Browser/editor split with Signal Knit update instructions modal over the page\n- [01:54:10](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with design asset sheet visible at right\n- [01:58:55](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with command palette or modal over design/code context\n- [01:59:55](https://codex-workshop-followup.pages.dev/lesson-05.html): Code/editor workspace with asset sheet and generated implementation text visible"
    },
    {
      "id": "codex-fusion-workflows-reference",
      "slug": "fusion-workflows-reference",
      "title": "Fusion council decisions and evidence: practical reference",
      "summary": "Local multi-model council reference covering skill and CLI setup, provider diversity and preflight, durable prompts, dry runs, terminal-state and artifact checks, degraded-provider recovery, privacy, and reconciliation with repo evidence before…",
      "category": "Verification",
      "tags": [
        "fusion",
        "council",
        "review"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Skill Reference Or Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Origin Story To Keep Straight",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/What Local Fusion Does",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Command Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Prompt Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/Fusion Compared To Nearby Workflows",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/10-fusion-model-council.md#10. Fusion / Model Council/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 3292,
      "url": "/topics/codex-fusion-workflows-reference/",
      "markdownUrl": "/markdown/codex-fusion-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-fusion-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "skill-reference-or-files-to-inspect",
          "text": "Skill Reference Or Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "origin-story-to-keep-straight",
          "text": "Origin Story To Keep Straight",
          "level": 2
        },
        {
          "id": "what-local-fusion-does",
          "text": "What Local Fusion Does",
          "level": 2
        },
        {
          "id": "command-shape",
          "text": "Command Shape",
          "level": 2
        },
        {
          "id": "prompt-shape",
          "text": "Prompt Shape",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "fusion-compared-to-nearby-workflows",
          "text": "Fusion Compared To Nearby Workflows",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Fusion council decisions and evidence: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the local Fusion / Model Council workflow for this repo.\n\n1. Resolve the Fusion skill first. Prefer the bundled `skills/fusion/SKILL.md` when it exists; otherwise inspect `~/.agents/skills/fusion/SKILL.md`. Read the skill before changing config or running a panel. Do not substitute Oracle or another review tool for the local Fusion CLI.\n\n2. Inspect the local Fusion checkout when available at `~/dev/fusion`. Check `README.md`, `package.json`, `src/fusion.js`, `fusion.config.example.json`, and the preset configs under `configs/` (`low.json`, `medium.json`, `high.json`, `quality.json`). Use the checkout to understand the installed CLI and presets; do not paste private config values into your report.\n\n3. Verify the command wrappers are available:\n   `command -v fusion fusion-med fusion-high`\n   If a wrapper is missing, inspect `~/dev/fusion` and use the install/link path supported by that checkout, commonly `npm install` followed by `npm link`, then re-check the wrappers. Do not overwrite an existing unrelated global binary without reporting the conflict.\n\n4. Run provider preflight before any real council run. Use the selected preset's list command, usually:\n   `fusion-high --list-providers`\n   For moderate planning, also check:\n   `fusion-med --list-providers`\n   Report the configured provider ids, unavailable providers, provider families, and whether the expected Claude/Opus slot is present. The point is a mixed council: OpenAI-style breadth, Anthropic-style critique, Z.ai/GLM or other coding-model pressure, plus any configured local specialists. Treat a missing Opus-class provider as a quality gap to report, not an automatic reason to invent a different workflow.\n\n5. Use durable prompt files for real questions. Create or identify a repo-local prompt file and pass it with `--file`; do not send long briefs through fragile shell quoting. The prompt file should include the decision, relevant repo paths, constraints, commands already run, observed failures, candidate options, verification expectations, and the recommendation format needed.\n\n6. Use `--dry-run` when provider ids, config paths, wrapper behavior, or output location are uncertain:\n   `fusion-high --dry-run --file path/to/prompt.md`\n   Then run the full configured panel only after the command shape is clear:\n   `fusion-high --file path/to/prompt.md`\n\n7. Let Fusion use its default session store unless a repo-local run directory is explicitly requested. Normal runs write under `~/.fusion/sessions/YYYY/MM/DD/<session-id>/` and update `~/.fusion/sessions.jsonl`. Expected artifacts include `run.json`, `panel-*.stdout.md`, `panel-*.stderr.txt`, `finalizer-report.json`, `summary.json`, and `final.md`.\n\n8. Wait for terminal provider states before recommending anything. Valid terminal states include `ok`, `failed`, `timedOut`, `quotaLimited`, `spawnError`, and `interrupted`. While a run is active, use `panel-status.json` or Fusion heartbeat output for status only. Do not act from early `panel-*` artifacts.\n\n9. Continue only after Fusion exits and both `summary.json` and `final.md` have been read, or after a real terminal failure or interruption has been captured. `summary.json` should provide run status, provider states, timings, and artifact paths. `final.md` should provide the council recommendation.\n\n10. Handle quota and rate failures as degraded council input. If a provider hits quota, rate limit, usage limit, 429 exhaustion, timeout, or another terminal failure after artifacts exist, name the provider, preserve the remaining outputs, and continue with the available panel. If a Kimi provider fails preflight with `auth.login_required`, report the Kimi auth failure and rerun once with `--only` set to the other configured provider ids. Do not use `--only` for ordinary narrowing unless explicitly requested.\n\n11. Keep the OpenRouter comparison precise. Local Fusion is a local CLI inspired by the panel, comparison, and final-answer pattern. It is not the hosted OpenRouter Fusion product. Treat OpenRouter and Fable claims as context, not proof that every local run improves every task.\n\n12. Respect privacy boundaries. Do not paste tokens, cookies, API keys, key-helper output, full environment dumps, private endpoints, or raw private session artifacts. Summarize sensitive material with redacted facts, provider states, paths, consensus, disagreements, and decision-relevant excerpts only.\n\n13. Report setup and run results plainly: skill path used, local checkout status, wrapper paths, provider preflight result, provider mix, Opus-class provider present or missing, prompt file path, dry-run result when used, session path, terminal provider states, whether `summary.json` and `final.md` were read, quota/rate handling, consensus, contradictions, unique insights, blind spots, synthesized recommendation, repo evidence used to accept or reject the council output, and verification commands to run next.\n\n14. Treat Fusion output as advisory. Do not start implementation until the council output has been reconciled with repo evidence and the final engineering call is clear.\n```\n\n## Big Idea\n\nUse Fusion when one model's answer is too small a surface area for the decision.\n\nFusion is a local model council workflow. The win is not that models argue for sport. The win is that different model families and provider stacks make different mistakes, notice different risks, and bring different habits to the same bounded software question. Fusion runs those perspectives in parallel, then synthesizes the strongest result.\n\n```text\none hard software question\n-> several independent model/provider perspectives\n-> comparison of consensus, contradictions, unique insights, and blind spots\n-> finalizer / synthesizer\n-> fused recommendation\n-> human engineering judgment\n```\n\nIt is not for tiny edits.\n\n## Try This Now\n\nUse Fusion when multiple perspectives can improve the decision.\nStart with: `fusion-high --list-providers`.\nFor a risky strategy choice, ask the agent to write a prompt file, run the full panel, then read `summary.json` and `final.md`.\n\nGood use:\n\n```text\nShould this billing webhook fix use provider event ids, invoice locks, or a processing ledger?\n```\n\nBad use:\n\n```text\nRename this variable.\n```\n\nFusion is most useful when different strong models may notice different risks:\n\n- architecture review\n- risky implementation choice\n- auth/session design\n- billing webhook idempotency\n- migration plan\n- debugging strategy with multiple plausible causes\n- outage fallback plan\n- code review before touching a dangerous subsystem\n- choosing between good-looking plans where each has a hidden cost\n\nThe point is not voting. The point is coverage. One model might catch the schema risk, another the rollout problem, another the security boundary, and another the boring test nobody wanted to write. The finalizer should turn that spread into one usable recommendation.\n\n## Skill Reference Or Files To Inspect\n\nBundled skill:\n\n```text\nskills/fusion/SKILL.md\n```\n\nCommon local source checkout:\n\n```text\n~/dev/fusion\n```\n\nCommon local skill install:\n\n```text\n~/.agents/skills/fusion/SKILL.md\n```\n\nLocal Fusion source files to inspect when needed:\n\n- `README.md`\n- `src/fusion.js`\n- `fusion.config.example.json`\n- `configs/low.json`\n- `configs/medium.json`\n- `configs/high.json`\n- `configs/quality.json`\n- `package.json`\n- `skills/fusion/SKILL.md`\n\nKeep command details in the skill. This file explains when to ask for Fusion, what the agent should do, and how to confirm the council output was actually used.\n\n## When To Reach For This\n\nUse Fusion when the cost of a missed perspective is higher than the cost of a slower council run.\n\n| Use Fusion For | Why |\n| --- | --- |\n| checkout saved payment architecture | UI, data, auth, provider, and rollback risks need different reviewers |\n| billing webhook double-processing | one model may prefer event ids, another may notice invoice-level locking or ledger recovery |\n| auth/session refresh design | security, migration, UX, and rollback perspectives all matter |\n| model outage fallback | provider diversity keeps one model failure from defining the plan |\n| risky refactor | one model catches coupling, another catches migration order, another catches missing tests |\n| debugging plan | different models may pursue different plausible causes before the finalizer narrows them |\n| code review before implementation | the council can preserve minority warnings a single answer would flatten |\n\nSkip Fusion when:\n\n- the fix is obvious and tiny\n- one failing test names the exact bug\n- latency matters more than deliberation\n- the prompt has no concrete repo evidence\n- the task is mostly one narrow CLI lookup\n- you need Oracle with a large packed codebase context instead\n- you already have a chosen implementation and just need to type it\n\nRule:\n\n```text\nUse Fusion when the answer should come from a council, not a monologue.\n```\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nAsk one strong model for the answer and trust it if it sounds confident.\n```\n\nWhat this workflow gives you now:\n\n```text\nAsk several independent models the same bounded software question, let each one\ntake its own path, then synthesize the useful overlap and the useful surprises.\n```\n\nWhat you used to expect:\n\n```text\nThe first model that finishes can unblock the work.\n```\n\nWhat this workflow gives you now:\n\n```text\nPartial provider output is not the answer. The answer starts after Fusion writes\nsummary and final artifacts, because the value is in the comparison and synthesis.\n```\n\n## The Mental Model\n\n```text\nprompt file\n-> provider panel from different model families\n-> terminal provider states\n-> judge/finalizer comparison\n-> synthesis\n-> summary.json\n-> final.md\n-> implementation decision\n```\n\n| Concept | Meaning |\n| --- | --- |\n| prompt file | the bounded software question and evidence |\n| provider panel | OpenAI, Anthropic, Z.ai/GLM, Gemini, Kimi, OpenCode, Codex, Claude, Agy, or other configured voices running independent passes |\n| terminal state | each provider finished, failed, timed out, hit quota, or was interrupted |\n| finalizer | compares panel output, preserves consensus, contradictions, unique insights, and blind spots, then writes a final recommendation |\n| `summary.json` | run status, provider states, timings, artifact paths |\n| `final.md` | final council output to read before acting |\n| panel artifacts | useful but partial until the run is complete |\n\nLocal Fusion shells out to local CLIs. It is not the same product as OpenRouter Fusion.\n\n```text\nOpenRouter Fusion is a hosted product.\nLocal Fusion is a local CLI implementation inspired by the same useful pattern:\npanel -> judge/finalizer -> synthesis -> final answer.\n```\n\nLocal Fusion runs through configured local commands such as Codex, Claude, Agy, and OpenCode. Those commands can point at different model families and providers, including OpenAI, Anthropic, Z.ai/GLM, Gemini, Kimi, or other local account wiring. Provider availability, cost, quotas, auth, and data handling depend on the local CLI accounts and config.\n\n## Origin Story To Keep Straight\n\nThe practical origin story is:\n\n```text\nDo not anchor serious work to one model's blind spots.\nUse multiple independent model/provider perspectives when the decision is expensive.\nSynthesize the council output so the final choice carries both consensus and caveats.\n```\n\nOpenRouter Fusion made the pattern visible in a hosted product: send one prompt to a panel of models, have a judge analyze the answers, then produce a fused response. OpenRouter reported that its Fusion tests on DRACO deep research tasks showed panels beating individual models, including budget panels approaching frontier-model performance.\n\nThe Fable 5 availability shock sharpened a related lesson: model access can change. Hard-coded single-model workflows are brittle. A council or fallback pattern keeps important work moving when one model disappears, rate-limits, or underperforms.\n\nCareful wording:\n\n- Local Fusion is inspired by the OpenRouter-style panel and judge/finalizer pattern.\n- Local Fusion is not OpenRouter Fusion.\n- OpenRouter reported strong DRACO deep research results for its hosted Fusion product. Treat those numbers as useful context, not proof that every local Fusion run improves every task.\n\n## What Local Fusion Does\n\nLocal Fusion:\n\n- reads one prompt\n- runs a configured panel of local provider CLIs\n- lets different model/provider families inspect the same question independently\n- waits for provider terminal states\n- keeps partial panel artifacts\n- handles failed, timed-out, or quota-limited providers as degraded inputs when possible\n- runs a finalizer by default\n- preserves consensus, contradictions, unique insights, and blind spots when the finalizer has enough signal\n- writes run artifacts under the Fusion session store\n- records status in a compact index\n- leaves the final engineering decision to the local agent and human\n\nCurrent default run artifacts usually live under:\n\n```text\n~/.fusion/sessions/YYYY/MM/DD/<session-id>/\n```\n\nCommon artifacts:\n\n- `run.json`\n- `panel-*.stdout.md`\n- `panel-*.stderr.txt`\n- `finalizer-report.json`\n- `final.md`\n- `summary.json`\n\nTreat these as private by default. They may contain prompts, source snippets, commands, stdout, stderr, and model responses.\n\n## Command Shape\n\nAsk the agent to use the skill. Do not memorize every flag.\n\nCommon shape:\n\n```bash\nfusion-high --list-providers\nfusion-high --dry-run --file path/to/prompt.md\nfusion-high --file path/to/prompt.md\n```\n\nModerate planning:\n\n```bash\nfusion-med --list-providers\nfusion-med --file path/to/prompt.md\n```\n\nCustom config:\n\n```bash\nfusion --config path/to/fusion.config.json --file path/to/prompt.md\n```\n\nLong prompt rule:\n\n```text\nWrite a prompt file and use --file.\n```\n\nDo not make the agent jam a long implementation brief through fragile shell quoting.\n\n## Prompt Shape\n\nUse a bounded software question, and name the perspectives you want the council to cover.\n\n```markdown\n# Fusion Prompt\n\n## Goal\n\nChoose the safest first implementation strategy for duplicate billing webhook processing.\n\n## Council Perspectives\n\n- architecture reviewer: data model, boundaries, rollback\n- security reviewer: replay, idempotency, abuse cases\n- implementation reviewer: smallest patch and tests\n- operations reviewer: observability, retry behavior, degraded states\n\n## Current Evidence\n\n- provider sends repeated paid invoice events\n- current handler sometimes processes the same invoice twice\n- suspected files:\n  - src/billing/webhook.ts\n  - src/billing/idempotency.ts\n  - tests/billing/webhook.test.ts\n\n## Candidate Strategies\n\n- provider event id guard\n- invoice-level processing lock\n- webhook processing ledger\n\n## Constraints\n\n- do not change provider contract\n- avoid schema changes in the first pass unless the council strongly argues for it\n- preserve existing invoice state transitions\n- prefer the smallest patch that can be tested\n\n## Verification\n\n- pnpm test billing-webhook -- --runInBand\n- pnpm build\n\n## Ask\n\nCompare the strategies. Identify consensus, contradictions, unique insights,\nblind spots, missing tests, and the first shippable slice. Synthesize one\nrecommendation that keeps the best argument from each useful perspective.\nEnd with rollback notes and the proof commands to run.\n```\n\n## Ask The Agent This\n\nUse Fusion for architecture choice:\n\n```text\nUse the $fusion skill.\n\nWe need to choose the first implementation strategy for duplicate billing webhook\nprocessing. Write a prompt file that compares provider event id guard,\ninvoice-level processing lock, and webhook processing ledger.\n\nFirst list providers and report the provider/model-family mix. Then dry-run the command, then run the full configured panel.\nWait for Fusion to finish. Read summary.json and final.md before recommending a\npath. Show consensus, contradictions, unique insights, and blind spots. Do not\nimplement until the synthesized council output has been reconciled with repo evidence.\n```\n\nUse Fusion for auth/session review:\n\n```text\nUse the $fusion skill.\n\nReview the auth/session refresh-token rotation plan. The decision is whether to\nput rotation in middleware, the session store, or an explicit auth workflow\nboundary. Include likely files, constraints, migration risk, rollback risk, and\nverification commands in the prompt file.\n\nRun the full configured Fusion panel and wait for terminal provider states.\nRead the final artifacts. Then give me the synthesized recommendation, the\nminority warnings worth keeping, the recommended first slice, risks, and tests\nto run.\n```\n\nUse Fusion for a risky implementation review:\n\n```text\nUse the $fusion skill before editing.\n\nThe checkout saved payment method implementation touches auth, account billing,\nprovider customer ids, and checkout UI state. Ask Fusion for independent critique\nfrom different model/provider perspectives: architecture, security, implementation,\nand operations. Ask for missing tests, privacy risk, rollback concerns, and the\nsmallest safe patch.\n\nAfter Fusion finishes, show the council's consensus, contradictions, unique\ninsights, blind spots, and synthesized recommendation before making any code change.\n```\n\nUse Fusion for model outage or fallback planning:\n\n```text\nUse the $fusion skill.\n\nWe need a fallback plan for a model-dependent feature so one model outage does\nnot take down the app. Ask the council to compare hard-coded model slugs,\nprovider-layer failover, model fallback chains, and local fallback behavior.\n\nReturn the synthesized first shippable config change, the provider failure modes\neach model noticed, and what to log when a fallback fires.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| skill invoked | agent explicitly says it used `$fusion` |\n| providers checked | agent ran `--list-providers` for the selected preset |\n| provider diversity named | agent reports the configured model/provider-family mix |\n| prompt was durable | prompt was saved to a file and passed with `--file` |\n| command shape checked | agent used `--dry-run` when provider ids or paths were uncertain |\n| full panel waited | agent waited until providers reached terminal states |\n| partial output not overused | agent did not act from only `panel-*.stdout.md` |\n| final artifacts read | agent read `summary.json` and `final.md` |\n| degraded providers handled | quota, timeout, or failure was reported without throwing away useful outputs |\n| synthesis preserved | final answer names consensus, contradictions, unique insights, and blind spots |\n| recommendation reconciled | final answer maps the synthesized recommendation back to repo evidence |\n| implementation stayed separate | code changes happened only after council output was read |\n| private output respected | session artifacts were not pasted wholesale |\n\nStrong proof phrases:\n\n- `Fusion session:`\n- `summary.json:`\n- `final.md:`\n- `providers:`\n- `provider mix:`\n- `terminal states:`\n- `consensus:`\n- `contradictions:`\n- `unique insights:`\n- `blind spots:`\n- `synthesized recommendation:`\n- `chosen path:`\n- `verification:`\n\nWeak proof phrases:\n\n- `One model said...`\n- `I saw enough from the first response...`\n- `Fusion is still running, but...`\n\n## If It Goes Wrong\n\nFusion is missing:\n\n```bash\ncommand -v fusion fusion-med fusion-high\n```\n\nThen inspect the common local checkout:\n\n```bash\ncd ~/dev/fusion\nnpm install\nnpm link\nfusion-med --list-providers\n```\n\nProvider auth fails:\n\n```bash\nfusion-high --list-providers\n```\n\nThen check the provider CLI directly only when needed. Do not paste tokens, cookies, full environment output, or key-helper config.\n\nOne provider hits quota:\n\n```text\nTreat it as a degraded council run.\n```\n\nExpected behavior:\n\n- quota-limited provider is named\n- remaining provider outputs are preserved\n- Fusion continues when possible\n- final answer mentions the missing voice\n\nDo not restart the whole run just because one provider is unavailable.\n\nAgent acts before Fusion finishes:\n\n```text\nStop the implementation.\n```\n\nAsk for:\n\n```text\nShow the Fusion session path, summary.json status, final.md, provider terminal\nstates, and the council synthesis. Then continue from that output.\n```\n\nOnly panel artifacts exist:\n\n```text\nPanel artifacts are partial.\n```\n\nWait for:\n\n- `summary.json`\n- `final.md`\n\nIf the run was interrupted, use the interrupted summary as explicit failure evidence.\n\nPrompt was too vague:\n\n```text\nBad: Use Fusion to review auth.\n\nBetter: Compare middleware-first, session-store-first, and explicit workflow boundary\nfor refresh-token rotation. Include constraints, likely files, migration risk,\nrollback, and verification commands.\n```\n\nPrompt included secrets:\n\n```text\nStop. Rewrite the prompt.\n```\n\nInclude file paths, redacted facts, and failure summaries instead of secrets.\n\nFinal answer sounds confident but ignores the council:\n\n```text\nExtract consensus, contradictions, unsupported claims, unique insights, blind\nspots, and the recommendation from the Fusion artifacts. Do not flatten the\ncouncil into one confident paragraph.\n```\n\n## Fusion Compared To Nearby Workflows\n\n| Workflow | Use It For | Not For |\n| --- | --- | --- |\n| Oracle PackX | huge code context and one expensive deep external review | quick local multi-model disagreement |\n| Section 6 variations | comparing generated implementation candidates | comparing independent model critiques |\n| Fusion | hard decision where disagreement matters | tiny changes or low-latency work |\n| Imps | one narrow tool-shaped lookup | architecture tradeoffs |\n| Agent markers | capturing a bounded debug moment | choosing among architectural strategies |\n\n## References And Resources\n\n- Bundled skill: `skills/fusion/SKILL.md`\n- Common local source checkout: `~/dev/fusion`\n- Common local skill install: `~/.agents/skills/fusion/SKILL.md`\n- Common session store: `~/.fusion/sessions/YYYY/MM/DD/<session-id>/`\n- Common session index: `~/.fusion/sessions.jsonl`\n- OpenRouter Fusion product page: https://openrouter.ai/fusion\n- OpenRouter Fusion model page: https://openrouter.ai/openrouter/fusion\n- OpenRouter announcement: https://openrouter.ai/blog/announcements/fusion-beats-frontier/\n- OpenRouter model-disappearance post: https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/\n\n## Operational boundaries\n\n- Hosted benchmark and model-availability anecdotes are attributed source context, not verified current product claims or proof of this local council’s quality. The saved local result must still survive repository verification.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-fusion-workflows-practice",
      "slug": "fusion-workflows-practice",
      "title": "Fusion council decisions and evidence: practice drills",
      "summary": "Exercises for deciding when a model council helps, framing bounded decisions, invoking Fusion, validating providers and completion artifacts, reconciling disagreement, handling failures, and defining a verified first implementation slice.",
      "category": "Verification",
      "tags": [
        "fusion",
        "council",
        "review",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 1: Decide Whether Fusion Fits",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 2: Write The Decision Question",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 3: Ask For `$fusion`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 4: Provider And Prompt Preflight",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 5: Confirm The Agent Waited",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 6: Extract Council Disagreement",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 7: Turn Council Output Into A First Slice",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 8: Quota Or Provider Failure Drill",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 9: Compare Fusion To Other Workflows",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/10-fusion-model-council.md#Exercises: 10. Fusion / Model Council/Exercise 10: Final Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 1118,
      "url": "/topics/codex-fusion-workflows-practice/",
      "markdownUrl": "/markdown/codex-fusion-workflows-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-fusion-workflows-practice.json",
      "headings": [
        {
          "id": "exercise-1-decide-whether-fusion-fits",
          "text": "Exercise 1: Decide Whether Fusion Fits",
          "level": 2
        },
        {
          "id": "exercise-2-write-the-decision-question",
          "text": "Exercise 2: Write The Decision Question",
          "level": 2
        },
        {
          "id": "exercise-3-ask-for-fusion",
          "text": "Exercise 3: Ask For `$fusion`",
          "level": 2
        },
        {
          "id": "exercise-4-provider-and-prompt-preflight",
          "text": "Exercise 4: Provider And Prompt Preflight",
          "level": 2
        },
        {
          "id": "exercise-5-confirm-the-agent-waited",
          "text": "Exercise 5: Confirm The Agent Waited",
          "level": 2
        },
        {
          "id": "exercise-6-extract-council-disagreement",
          "text": "Exercise 6: Extract Council Disagreement",
          "level": 2
        },
        {
          "id": "exercise-7-turn-council-output-into-a-first-slice",
          "text": "Exercise 7: Turn Council Output Into A First Slice",
          "level": 2
        },
        {
          "id": "exercise-8-quota-or-provider-failure-drill",
          "text": "Exercise 8: Quota Or Provider Failure Drill",
          "level": 2
        },
        {
          "id": "exercise-9-compare-fusion-to-other-workflows",
          "text": "Exercise 9: Compare Fusion To Other Workflows",
          "level": 2
        },
        {
          "id": "exercise-10-final-check",
          "text": "Exercise 10: Final Check",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Fusion council decisions and evidence: practice drills\n\nThese exercises practice choosing when a local model council is worth the time, writing a bounded prompt, and confirming the council output was used before implementation.\n\nUse a real software project when possible. Keep the task narrow enough that the council can compare concrete choices.\n\n## Exercise 1: Decide Whether Fusion Fits\n\nFor each task, choose `use Fusion` or `skip Fusion`.\n\n| Task | Use / Skip | Why |\n| --- | --- | --- |\n| Choose between three billing webhook idempotency strategies | | |\n| Fix a typo in a button label | | |\n| Review auth/session refresh-token architecture before implementation | | |\n| Compare one model outage fallback plan against another | | |\n| Run one known formatter command | | |\n| Debug a bug with three plausible causes and incomplete logs | | |\n| Implement an exact requested API shape | | |\n| Review a risky checkout refactor before editing | | |\n\nWrite:\n\n```markdown\n# Fusion Fit\n\n- task:\n- decision:\n- why disagreement helps or does not help:\n- evidence available:\n- likely verification:\n- use Fusion? yes/no:\n```\n\nRule:\n\n```text\nIf disagreement cannot change the decision, skip Fusion.\n```\n\n## Exercise 2: Write The Decision Question\n\nPick one software decision:\n\n- billing webhook idempotency\n- checkout saved payment method architecture\n- auth/session refresh-token rotation\n- model outage fallback\n- risky refactor plan\n\nFill out:\n\n```markdown\n# Decision Question\n\n## Goal\n\n## Candidate Strategies\n\n-\n-\n-\n\n## Current Evidence\n\n-\n-\n-\n\n## Constraints\n\n-\n-\n-\n\n## Verification\n\n-\n-\n\n## What Disagreement Should Decide\n\n```\n\nCheck it:\n\n```text\nCan a model reasonably disagree about this?\nCan repo evidence settle the disagreement?\nCan the final answer name a first implementation slice?\n```\n\n## Exercise 3: Ask For `$fusion`\n\nRewrite this vague request:\n\n```text\nUse Fusion to review auth.\n```\n\nInto a strong request that asks the agent to:\n\n- use the `$fusion` skill\n- list providers first\n- write a prompt file\n- dry-run if command shape is uncertain\n- run the full configured panel\n- wait for terminal provider states\n- read `summary.json` and `final.md`\n- report consensus and disagreement\n- avoid implementation until after the council output is reconciled\n\nDraft:\n\n```text\nUse the $fusion skill.\n\n...\n```\n\n## Exercise 4: Provider And Prompt Preflight\n\nRun or ask an agent to run:\n\n```bash\nfusion-high --list-providers\nfusion-high --dry-run --file path/to/prompt.md\n```\n\nFill out:\n\n```markdown\n# Fusion Preflight\n\n- selected preset:\n- provider ids:\n- prompt file:\n- dry-run command:\n- output location:\n- any missing provider:\n- any auth warning:\n- safe to run? yes/no:\n```\n\n## Exercise 5: Confirm The Agent Waited\n\nAfter a Fusion run, fill this out from the agent's report.\n\n```markdown\n# Wait Check\n\n- Fusion session path:\n- summary.json read? yes/no:\n- final.md read? yes/no:\n- providers reached terminal states? yes/no:\n- terminal states:\n  -\n  -\n  -\n- any quota-limited provider:\n- any failed or timed-out provider:\n- did the agent act from partial panel output? yes/no:\n- did implementation start only after final artifacts were read? yes/no:\n```\n\nWeak answer to reject:\n\n```text\nOne model had a good answer, so I continued.\n```\n\nStrong answer:\n\n```text\nI waited for summary.json and final.md, then reconciled consensus and disagreement with repo evidence.\n```\n\n## Exercise 6: Extract Council Disagreement\n\nFrom `final.md` or the agent summary, fill out:\n\n```markdown\n# Council Review\n\n## Consensus\n\n-\n-\n\n## Disagreement\n\n| Topic | Position A | Position B | What evidence decides? |\n| --- | --- | --- | --- |\n| | | | |\n\n## Hidden Risks\n\n-\n-\n\n## Missing Tests\n\n-\n-\n\n## Recommendation\n\n- chosen path:\n- why:\n- what to avoid:\n- rollback:\n```\n\nQuestion:\n\n```text\nWhat did the disagreement change about the implementation plan?\n```\n\n## Exercise 7: Turn Council Output Into A First Slice\n\nWrite the implementation slice.\n\n```markdown\n# First Slice After Fusion\n\n- chosen strategy:\n- files to inspect:\n- files likely to change:\n- tests to add or update:\n- verification command:\n- rollback note:\n- risks left for later:\n- what the council disagreed about:\n- why this slice is safe enough to try:\n```\n\nDo not include broad roadmap work unless it blocks the first slice.\n\n## Exercise 8: Quota Or Provider Failure Drill\n\nChoose a recovery.\n\n| Failure | Recovery |\n| --- | --- |\n| one provider quota-limited | |\n| one provider timed out | |\n| `final.md` missing | |\n| `summary.json` says interrupted | |\n| prompt file accidentally included secrets | |\n| provider ids were wrong | |\n| agent used `--only` without being asked | |\n| agent started editing while Fusion was still running | |\n| final answer ignored disagreement | |\n\nRecovery options:\n\n- continue with degraded panel\n- name the missing voice\n- read partial artifacts only as failure evidence\n- rerun after fixing provider ids\n- rewrite prompt without secrets\n- ask for `summary.json` and `final.md`\n- stop implementation and wait\n- rerun full panel\n- extract consensus and contradictions\n\nFill one out:\n\n```markdown\n# Failure Recovery Detail\n\n- failure:\n- likely cause:\n- command or artifact to inspect:\n- recovery:\n- how to know recovery worked:\n```\n\n## Exercise 9: Compare Fusion To Other Workflows\n\nChoose the right workflow.\n\n| Scenario | Workflow | Why |\n| --- | --- | --- |\n| broad repo architecture review needing packed code context | | |\n| compare three generated checkout UI candidates | | |\n| choose idempotency strategy before implementation | | |\n| capture exact browser bug moment | | |\n| find code paths with one search tool | | |\n| convert a screen recording into repro steps | | |\n| compose a careful prompt before launch | | |\n\nOptions:\n\n- Oracle PackX\n- Prompt Builder\n- Section 6 variations\n- Fusion\n- Video workflow\n- Agent markers\n- Imps\n\n## Exercise 10: Final Check\n\nUse this checklist before trusting the result.\n\n```markdown\n# Final Fusion Check\n\n- Fusion was the right tool? yes/no:\n- skill was invoked? yes/no:\n- provider list checked? yes/no:\n- prompt file written? yes/no:\n- dry-run used when uncertain? yes/no:\n- full configured panel run? yes/no:\n- providers reached terminal states? yes/no:\n- summary.json read? yes/no:\n- final.md read? yes/no:\n- consensus captured? yes/no:\n- disagreement captured? yes/no:\n- recommendation reconciled with repo evidence? yes/no:\n- verification command named? yes/no:\n- private artifacts protected? yes/no:\n- ready for implementation? yes/no:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-debug-markers",
      "slug": "debug-markers",
      "title": "Human testimony joined to runtime evidence",
      "summary": "Capture the moment of surprise with a bounded redacted trail and discriminate between hypotheses before changing code.",
      "category": "Verification",
      "tags": [
        "debug",
        "factory"
      ],
      "sources": [
        {
          "label": "Human testimony joined to runtime evidence",
          "url": "https://mindful-mango-accy.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q4-markers-follow-up"
        }
      ],
      "sourceUnits": [
        "09-markers/index.html#TL;DR",
        "09-markers/index.html#The signal you normally throw away",
        "09-markers/index.html#Appendix",
        "09-markers/index.html#One captured failure, read cold",
        "09-markers/index.html#What the capture leaves out",
        "learn.html#q4-markers-follow-up"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1237,
      "url": "/topics/factory-debug-markers/",
      "markdownUrl": "/markdown/factory-debug-markers.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-debug-markers.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "the-signal-you-normally-throw-away",
          "text": "The signal you normally throw away",
          "level": 2
        },
        {
          "id": "one-captured-failure-read-cold",
          "text": "One captured failure, read cold",
          "level": 2
        },
        {
          "id": "what-the-capture-leaves-out",
          "text": "What the capture leaves out",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "attach-testimony-to-runtime-evidence",
          "text": "Attach testimony to runtime evidence",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        }
      ],
      "markdown": "# Human testimony joined to runtime evidence\n\nCapture the moment of surprise with a bounded redacted trail and discriminate between hypotheses before changing code.\n\n## Related working material\n\n- [Human testimony joined to runtime evidence — prompts and exercises](/topics/factory-debug-markers-practice/)\n- [Human testimony joined to runtime evidence — questions and tradeoffs](/topics/factory-debug-markers-questions/)\n- [Human testimony joined to runtime evidence — worked example](/topics/factory-debug-markers-worked-example/)\n\n## TL;DR\n\n- A ~150-line, dependency-free recorder (`agent-markers.js`, printed complete below) logs clicks, fetches, console lines, and errors into a bounded ring buffer in any web app.\n- One keystroke pins one sentence of human testimony to the nearest events; one call exports a redacted JSON payload safe to paste anywhere — no bodies, no tokens, no raw user text.\n- The move: mark at the moment of surprise, render the export into a debug packet, and make the agent state a hypothesis before it reads any code.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## The signal you normally throw away\n\nYou are testing an app. Something feels off — a stale value, a success message you do not believe. Usually that judgment evaporates: hours later someone asks for a bug report, and you reconstruct the moment from memory, losing the timing, the order of actions, and most of the value. The pattern this session builds on calls human intent “the missing signal” in agent debugging and records it the moment it occurs.\n\nThis is not a paper idea. A production desktop app we studied ships the same move: a hotkey mints a marker id, captures a screenshot, writes a `dev_marker` log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose `--marker` flag slices the session for agents. The design rule that makes it work: capture happens *during* the surprise, one keystroke and one sentence. Anything heavier and nobody uses it at the moment that matters.\n\nA capture has two parts that answer different questions. A **marker** says *why this moment deserves attention*; a **trail** says *how the tester arrived there*. Testimony alone tells an agent what to look for but not when; a trail alone is complete but unweighted. Paired, the testimony points into the trail, and the trail grounds the testimony in ordered facts. Treat the marker as a search warrant, not a verdict.\n\n## One captured failure, read cold\n\nThe workshop demo plants a bug worth marking: a notes app goes offline, reconnects, and saves. The server rotated its session token during the reconnect; the client kept its stale copy; the save handler treats any status below 500 as success. The user sees **“Saved ”**. The server said 401. We drove that path in a real browser, pressed mark, and typed: *“It said Saved but my note never reached the server — this happened right after I reconnected.”* Seven consecutive lines of the captured trail, exactly as the packet renderer printed them:\n\n``` text\n- [seq 3 · t+17397ms] click: click <button#save> \"Save note\"\n- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]\n- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable\n- [seq 6 · t+18436ms] click: click <button#toggle-net> \"Reconnect\"\n- [seq 7 · t+18436ms] console: console.log: reconnected: session restored\n- [seq 8 · t+18909ms] click: click <button#save> \"Save note\"\n- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]\n```\n\nRead it top to bottom and name a hypothesis before anyone tells you: a network failure, a “session restored” log, then a 401 on the very next save under a visible “Saved ”. If you reached “the reconnect invalidated something the client still holds,” a nine-line slice just did what a full log dump rarely does — and an agent reads it the same way you just did.\n\n## What the capture leaves out\n\nThe moment you say “capture the entire state of the app,” you have a privacy decision, because the payload will leave your machine — pasted into an agent, attached to a ticket, shared in chat. Decide the exclusions before the first capture, write them into the payload itself, and accept the narrower evidence. The demo’s export embeds exactly this policy, so every reader can audit what was withheld:\n\n``` text\n{\n  \"storageValues\": \"excluded\",\n  \"requestBodies\": \"excluded\",\n  \"responseBodies\": \"excluded\",\n  \"userText\": \"preview+length only\"\n}\n```\n\nAn external architecture review of the production system pushed the same rule harder: order events by a sequence counter, join records by session and marker ids, and store user input as preview, hash, and length — never raw. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.\n\nThe handoff needs a fence too. A weak handoff pastes a log dump and asks “what’s wrong?”, inviting confident guessing over unweighted noise. A strong handoff gives less data and more structure — what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. That is why the packet ends with a claims boundary, and why the first prompt above demands a hypothesis before code: the agent’s draft arrives labeled as a draft, and a person verifies it against the running app.\n\n## Appendix\n\n### Limits & caveats\n\n- Testimony is not diagnosis; context is not proof. The trail shows what was captured, not everything that happened — session metadata does not prove a defect, and testimony does not prove cause.\n- The captured failure here is a bug we planted ourselves. The loop is demonstrated end to end, but its yield on organic bugs is untested on this page.\n- Redaction trades fidelity for safety. A capture without request bodies cannot settle every question; sometimes the correct next step is a targeted, consented follow-up capture.\n- `prompt()` blocks automation. Scripted browsers should call `window.__AGENT_MARKERS__.mark(label, note)` from the console instead of the hotkey.\n- On macOS, Cmd+M can collide with the browser’s minimize shortcut; a page button or the console call is the reliable path.\n- The ring buffer is in-memory only — a reload wipes it. Export before navigating away. Screenshots are `\"unavailable\"` in the plain-browser recorder; the production system captures them via native APIs.\n- If your app installs its own `fetch` wrapper (mocks, auth shims), install it before `AgentMarkers.start()` so wrapped calls land in the trail.\n\n## Operating practice\n\n### Attach testimony to runtime evidence\n\n#### What to notice\n\nGive a debugging agent the exact moment of failure, the **human-observed symptom**, and a **bounded event trail**.\n\n#### Try this\n\nReproduce one bug, add one plain-language marker when behavior becomes wrong, and export a redacted packet for ranked hypotheses.\n\n> “I see this, and I wanna talk about that.”\n\nJohn Lindquist · [02:22:16](https://proud-anchor-53zn.here.now/watch.html?t=8536#recording-player)\n\n#### Concept\n\nThe prepared Markers material combines human testimony with nearby console, fetch, error, and click events. That makes the next diagnostic question smaller and more discriminating.\n\n#### Reflection\n\nThis module was prepared after the workshop and was not taught as a dedicated recorded section.\n\n**Recording evidence:** prepared follow-up grounded in related recorded evidence.\n\n> “A lot of us spend time trying to describe bugs instead of just recording ourselves using the product.”\n\nJohn Lindquist · [05:21:57](https://proud-anchor-53zn.here.now/watch.html?t=19317#recording-player)\n\n[Open Debugging with Markers](https://mindful-mango-accy.here.now/)\n\n[Recording boundary](https://proud-anchor-53zn.here.now/watch.html#q4-markers-follow-up)"
    },
    {
      "id": "factory-debug-markers-practice",
      "slug": "debug-markers-practice",
      "title": "Human testimony joined to runtime evidence — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for human testimony joined to runtime evidence.",
      "category": "Verification",
      "tags": [
        "prompts",
        "exercises",
        "debug-markers"
      ],
      "sources": [
        {
          "label": "Human testimony joined to runtime evidence",
          "url": "https://mindful-mango-accy.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://mindful-mango-accy.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "09-markers/index.html#Quick start",
        "09-markers/index.html#Prompt library",
        "09-markers/index.html#Set it up (agent guide)",
        "09-markers/index.html#Hand an agent a debug packet",
        "09-markers/index.html#Grade your capture: can it be read cold?",
        "09-markers/index.html#Write the redaction policy first",
        "09-markers/agent.md"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 3635,
      "url": "/topics/factory-debug-markers-practice/",
      "markdownUrl": "/markdown/factory-debug-markers-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-debug-markers-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "hand-an-agent-a-debug-packet",
          "text": "Hand an agent a debug packet",
          "level": 3
        },
        {
          "id": "grade-your-capture-can-it-be-read-cold",
          "text": "Grade your capture: can it be read cold?",
          "level": 3
        },
        {
          "id": "write-the-redaction-policy-first",
          "text": "Write the redaction policy first",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "debugging-with-markers-agent-setup-guide",
          "text": "Debugging with Markers — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Human testimony joined to runtime evidence — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for human testimony joined to runtime evidence.\n\n## Quick start\n\nRuns from any empty directory — needs only `curl` and Node 18+. It pulls the recorder, the packet renderer, and a real captured session from this site, then prints the agent-ready debug packet.\n\n``` text\nmkdir -p markers-quickstart && cd markers-quickstart\ncurl -sO https://mindful-mango-accy.here.now/agent-markers.js\ncurl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode make-agent-packet.mjs sample-session.json\n```\n\n## Prompt library\n\n### Hand an agent a debug packet\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a one-sentence hypothesis, then a reproducible scenario with unproven parts flagged\n\n``` text\nHere is a debug packet captured from a live session of my app. Before you read any code:\n\n1. Read the human testimony, then the evidence trail in seq order.\n2. State your single most likely hypothesis for the failure, in one sentence.\n3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet.\n4. Label anything the trail cannot prove as \"hypothesis — needs verification\".\n\nTestimony is not diagnosis. Context is not proof.\n\n--- PACKET ---\n[paste the output of: node scripts/make-agent-packet.mjs your-session.json]\n```\n\n### Grade your capture: can it be read cold?\n\n- Agent: any coding agent\n- Working directory: your project, with a fresh export on disk\n- Expected result: a stated hypothesis, or the one knob to turn first\n\n``` text\nHere is a marker-session export from my app (JSON, schemaVersion 1). Render it with scripts/make-agent-packet.mjs and read the packet cold — no source code, no other context.\n\nAnswer two things:\n1. Can you state one specific hypothesis from the testimony and trail alone? State it.\n2. If you cannot, tell me which single change to make first: mark closer to the failure, raise nearbyEventLimit, or add one missing event type to the recorder.\n```\n\n### Write the redaction policy first\n\n- Agent: your coding agent\n- Working directory: your project, before any recording code lands\n- Expected result: an exclusion list for your app plus a redaction JSON block for every export\n\n``` text\nI'm adding just-in-time debug capture (markers plus an event trail) to this app. Before any recording code lands, draft our redaction policy: list every category of data a capture must NEVER contain (request/response bodies, tokens, storage values, raw user text, plus anything specific to this codebase), and produce a redaction JSON block to embed verbatim in every export so readers can audit what was withheld. Default user text to \"preview+length only\".\n```\n\n## Set it up (agent guide)\n\n1.  Add the recorder to your app as `<static-dir>/agent-markers.js`. This is the whole thing — no dependencies, no build step. (Same bytes as [agent-markers.js](https://mindful-mango-accy.here.now/agent-markers.js) on this site.)\n\n    ``` text\n    /**\n     * agent-markers.js — a tiny, dependency-free \"press a button, capture the moment\" recorder.\n     *\n     * Pattern: a MARKER is timestamped human testimony (\"this moment matters, here's why\").\n     * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there.\n     * Export = bounded, redacted payload you can hand to an agent as a debug packet.\n     *\n     * Deliberately NOT captured: storage values, request/response bodies, raw input text.\n     * Testimony is not diagnosis. Context is not proof.\n     */\n    (function (global) {\n      \"use strict\";\n\n      const state = {\n        running: false,\n        sessionId: null,\n        startedAtIso: null,\n        startedAtMs: 0,\n        seq: 0,\n        events: [],\n        markers: [],\n        maxEvents: 200,\n        nearbyEventLimit: 12,\n        restoreFns: [],\n      };\n\n      function now() {\n        return Math.round(performance.now() - state.startedAtMs);\n      }\n\n      function preview(text, max = 80) {\n        const s = String(text ?? \"\");\n        return {\n          preview: s.length > max ? s.slice(0, max) + \"…\" : s,\n          length: s.length,\n          truncated: s.length > max,\n        };\n      }\n\n      function record(type, data) {\n        if (!state.running) return null;\n        const event = { id: \"evt-\" + (++state.seq), seq: state.seq, t: now(), type, data };\n        state.events.push(event);\n        if (state.events.length > state.maxEvents) state.events.shift();\n        return event;\n      }\n\n      function patchConsole() {\n        [\"log\", \"warn\", \"error\"].forEach((level) => {\n          const original = console[level];\n          console[level] = function (...args) {\n            record(\"console\", { level, message: preview(args.map(String).join(\" \")) });\n            return original.apply(console, args);\n          };\n          state.restoreFns.push(() => (console[level] = original));\n        });\n      }\n\n      function patchFetch() {\n        const original = global.fetch;\n        global.fetch = async function (input, init) {\n          const url = typeof input === \"string\" ? input : input.url;\n          const method = (init && init.method) || \"GET\";\n          const started = now();\n          try {\n            const res = await original.apply(global, arguments);\n            record(\"fetch\", { method, url, status: res.status, ok: res.ok, ms: now() - started });\n            return res;\n          } catch (error) {\n            record(\"fetch\", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) });\n            throw error;\n          }\n        };\n        state.restoreFns.push(() => (global.fetch = original));\n      }\n\n      function patchErrors() {\n        const onError = (event) =>\n          record(\"error\", { message: preview(event.message || String(event.reason || \"unknown\")) });\n        global.addEventListener(\"error\", onError);\n        global.addEventListener(\"unhandledrejection\", onError);\n        state.restoreFns.push(() => {\n          global.removeEventListener(\"error\", onError);\n          global.removeEventListener(\"unhandledrejection\", onError);\n        });\n      }\n\n      function patchClicks() {\n        const onClick = (event) => {\n          const el = event.target.closest(\"button, a, [data-action]\") || event.target;\n          record(\"click\", {\n            tag: el.tagName.toLowerCase(),\n            id: el.id || null,\n            action: el.dataset ? el.dataset.action || null : null,\n            text: preview(el.textContent && el.textContent.trim(), 40),\n          });\n        };\n        document.addEventListener(\"click\", onClick, true);\n        state.restoreFns.push(() => document.removeEventListener(\"click\", onClick, true));\n      }\n\n      const AgentMarkers = {\n        start(options = {}) {\n          if (state.running) return this;\n          state.sessionId = options.sessionId || \"session-\" + Date.now().toString(36);\n          state.startedAtIso = new Date().toISOString();\n          state.startedAtMs = performance.now();\n          state.maxEvents = options.maxEvents || 200;\n          state.nearbyEventLimit = options.nearbyEventLimit || 12;\n          state.seq = 0;\n          state.events = [];\n          state.markers = [];\n          state.running = true;\n          patchConsole();\n          patchFetch();\n          patchErrors();\n          patchClicks();\n          if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers;\n          record(\"session\", { note: \"recording started\", app: options.app || \"unknown\" });\n          return this;\n        },\n\n        /** Human presses the button: timestamped testimony + pointers into the trail. */\n        mark(label, note) {\n          if (!state.running) throw new Error(\"AgentMarkers not started\");\n          const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id);\n          const marker = {\n            id: \"mrk-\" + (state.markers.length + 1) + \"-\" + Date.now().toString(36),\n            seq: ++state.seq,\n            t: now(),\n            label: label || \"unlabeled\",\n            note: note || \"\",\n            nearbyEventIds: nearby,\n            screenshot: \"unavailable\", // browser demo: no screenshot API without permissions\n          };\n          state.markers.push(marker);\n          record(\"marker\", { markerId: marker.id, label: marker.label });\n          return marker;\n        },\n\n        record(type, data) {\n          return record(\"manual\", { type, ...data });\n        },\n\n        /** Bounded, redacted payload — everything an agent gets, nothing more. */\n        exportSession() {\n          return {\n            schemaVersion: 1,\n            sessionId: state.sessionId,\n            startedAt: state.startedAtIso,\n            exportedAt: new Date().toISOString(),\n            userAgent: navigator.userAgent,\n            markers: state.markers,\n            events: state.events,\n            redaction: {\n              storageValues: \"excluded\",\n              requestBodies: \"excluded\",\n              responseBodies: \"excluded\",\n              userText: \"preview+length only\",\n            },\n          };\n        },\n\n        stop() {\n          state.restoreFns.forEach((restore) => restore());\n          state.restoreFns = [];\n          state.running = false;\n          return this;\n        },\n      };\n\n      if (typeof module !== \"undefined\" && module.exports) module.exports = AgentMarkers;\n      global.AgentMarkers = AgentMarkers;\n    })(typeof window !== \"undefined\" ? window : globalThis);\n    ```\n\n2.  Boot it with `<static-dir>/markers-boot.js` — starts recording, binds Ctrl/Cmd+M to “mark”, and exposes `exportMarkers()` for downloading the capture. Replace `\"my-app\"` with your app’s name.\n\n    ``` text\n    /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.\n       Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */\n    AgentMarkers.start({ app: \"my-app\" }); // replace \"my-app\" with your app's name\n\n    // One keystroke at the moment of surprise: one sentence of testimony.\n    window.addEventListener(\"keydown\", (e) => {\n      if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === \"m\") {\n        e.preventDefault();\n        const note = prompt(\"Why does this moment matter? (one sentence — it travels with the capture)\");\n        if (note !== null) console.log(\"marked:\", AgentMarkers.mark(\"user-flag\", note).id);\n      }\n    });\n\n    // Call exportMarkers() from the console, or wire it to a button.\n    window.exportMarkers = () => {\n      const session = AgentMarkers.exportSession();\n      const blob = new Blob([JSON.stringify(session, null, 2)], { type: \"application/json\" });\n      const a = Object.assign(document.createElement(\"a\"), {\n        href: URL.createObjectURL(blob),\n        download: session.sessionId + \".json\",\n      });\n      a.click();\n      URL.revokeObjectURL(a.href);\n      return session.sessionId + \".json\";\n    };\n    ```\n\n    Load both before your app’s own scripts: `<script src=\"agent-markers.js\"></script>` then `<script src=\"markers-boot.js\"></script>`.\n\n3.  Save the packet renderer as `scripts/make-agent-packet.mjs` in your project — it turns any export into the markdown packet the prompts above expect.\n\n    ``` text\n    #!/usr/bin/env node\n    /**\n     * make-agent-packet.mjs — turn a marker-session export into a bounded agent debug packet.\n     *\n     * Usage:\n     *   node scripts/make-agent-packet.mjs <session.json> [marker-id]\n     *\n     * Emits markdown on stdout: human testimony, the nearby evidence slice, redaction\n     * receipts, and an explicit claims boundary — ready to paste into any agent.\n     */\n    import { readFileSync } from \"node:fs\";\n\n    const [file, markerArg] = process.argv.slice(2);\n    if (!file) {\n      console.error(\"usage: node scripts/make-agent-packet.mjs <session.json> [marker-id]\");\n      process.exit(1);\n    }\n\n    const session = JSON.parse(readFileSync(file, \"utf8\"));\n    if (session.schemaVersion !== 1) {\n      console.error(`unsupported schemaVersion: ${session.schemaVersion}`);\n      process.exit(1);\n    }\n\n    const marker = markerArg\n      ? session.markers.find((m) => m.id === markerArg)\n      : session.markers.at(-1);\n    if (!marker) {\n      console.error(markerArg ? `marker '${markerArg}' not found` : \"no markers in session\");\n      process.exit(1);\n    }\n\n    const nearbyIds = new Set(marker.nearbyEventIds ?? []);\n    const nearby = session.events.filter((e) => nearbyIds.has(e.id));\n    const fmt = (e) => {\n      const d = e.data ?? {};\n      switch (e.type) {\n        case \"fetch\":\n          return `${d.method} ${d.url} → ${d.status ?? \"NETWORK-ERROR\"}${d.error ? ` (${d.error.preview ?? d.error})` : \"\"} [${d.ms}ms]`;\n        case \"console\":\n          return `console.${d.level}: ${d.message?.preview ?? \"\"}`;\n        case \"click\":\n          return `click <${d.tag}${d.id ? `#${d.id}` : \"\"}> \"${d.text?.preview ?? \"\"}\"`;\n        case \"error\":\n          return `error: ${d.message?.preview ?? \"\"}`;\n        default:\n          return JSON.stringify(d);\n      }\n    };\n\n    const lines = [];\n    lines.push(`# Debug packet — marker ${marker.id}`);\n    lines.push(\"\");\n    lines.push(`- session: ${session.sessionId} (started ${session.startedAt})`);\n    lines.push(`- marker time: t+${marker.t}ms · label: ${marker.label}`);\n    lines.push(`- screenshot: ${marker.screenshot ?? \"unavailable\"}`);\n    lines.push(\"\");\n    lines.push(\"## Human testimony (why this moment matters)\");\n    lines.push(\"\");\n    lines.push(`> ${marker.note || \"(no explanation recorded)\"}`);\n    lines.push(\"\");\n    lines.push(`## Evidence trail (${nearby.length} events nearest the marker, seq order)`);\n    lines.push(\"\");\n    for (const e of nearby) lines.push(`- [seq ${e.seq} · t+${e.t}ms] ${e.type}: ${fmt(e)}`);\n    lines.push(\"\");\n    lines.push(\"## Redaction receipts\");\n    lines.push(\"\");\n    for (const [k, v] of Object.entries(session.redaction ?? {})) lines.push(`- ${k}: ${v}`);\n    lines.push(\"\");\n    lines.push(\"## Task for the agent\");\n    lines.push(\"\");\n    lines.push(\"Draft a reproducible scenario (preconditions, steps, expected, observed) that\");\n    lines.push(\"explains the testimony using ONLY the evidence above. Flag anything the trail\");\n    lines.push(\"cannot prove as a hypothesis needing verification.\");\n    lines.push(\"\");\n    lines.push(\"## Claims boundary\");\n    lines.push(\"\");\n    lines.push(\"Testimony is not diagnosis. Context is not proof. The trail shows what was\");\n    lines.push(\"captured, not everything that happened.\");\n\n    console.log(lines.join(\"\\n\"));\n    ```\n\n**Success check:** render the real captured session from this site, then read the packet cold and state a hypothesis before looking at any code.\n\n``` text\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode scripts/make-agent-packet.mjs sample-session.json\n```\n\n``` text\n# Debug packet — marker <demo-marker>\n\n- session: <demo-session> (started the recorded snapshot)\n- marker time: t+26900ms · label: user-flag\n- screenshot: unavailable\n\n## Human testimony (why this moment matters)\n\n> It said Saved but my note never reached the server — this happened right after I reconnected.\n\n## Evidence trail (9 events nearest the marker, seq order)\n\n- [seq 1 · t+0ms] session: {\"note\":\"recording started\",\"app\":\"field-notes-demo\"}\n- [seq 2 · t+16914ms] click: click <button#toggle-net> \"Go offline\"\n- [seq 3 · t+17397ms] click: click <button#save> \"Save note\"\n- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]\n- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable\n- [seq 6 · t+18436ms] click: click <button#toggle-net> \"Reconnect\"\n- [seq 7 · t+18436ms] console: console.log: reconnected: session restored\n- [seq 8 · t+18909ms] click: click <button#save> \"Save note\"\n- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]\n…\n```\n\nYou pass when a reader — human or agent — gets from that packet alone to something like “the reconnect rotated or invalidated a session credential the client still holds.” Then verify the loop in your own app: press Ctrl/Cmd+M, type a sentence, run `exportMarkers()` in the console, and confirm the downloaded JSON has your marker and a `redaction` block.\n\n## Complete reusable setup contract\n\n## Debugging with Markers — agent setup guide\n\nFollowing this file sets up: a just-in-time debug-capture loop in the user's web app — a ~150-line dependency-free recorder (semantic event trail + human markers), a mark hotkey, a redacted JSON export, and a renderer that turns exports into agent-ready debug packets.\n\nPlaceholders used below: `<project-root>` = the project you are working in; `<static-dir>` = wherever that app serves static JS from (often `public/` or the app's HTML directory). All other paths are literal.\n\nHuman companion pages on this site (for your user, not needed to execute this file): the section guide at https://mindful-mango-accy.here.now/, a Session Replay of the captured run this file's success check reproduces at https://mindful-mango-accy.here.now/replay.html, and a Q&A Dialogue at https://mindful-mango-accy.here.now/dialogue.html.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nnode --version   # need v18 or newer\ncurl --version   # used only to download the sample session in the success check\n```\n\nExpected: Node 18+ and curl present. If a tool is missing, stop and tell your user what to install.\n\n## Steps\n\n1. Create `<static-dir>/agent-markers.js` with exactly this content (same bytes as https://mindful-mango-accy.here.now/agent-markers.js — you may download it instead of typing it):\n\n   ```js\n   /**\n    * agent-markers.js — a tiny, dependency-free \"press a button, capture the moment\" recorder.\n    *\n    * Pattern: a MARKER is timestamped human testimony (\"this moment matters, here's why\").\n    * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there.\n    * Export = bounded, redacted payload you can hand to an agent as a debug packet.\n    *\n    * Deliberately NOT captured: storage values, request/response bodies, raw input text.\n    * Testimony is not diagnosis. Context is not proof.\n    */\n   (function (global) {\n     \"use strict\";\n\n     const state = {\n       running: false,\n       sessionId: null,\n       startedAtIso: null,\n       startedAtMs: 0,\n       seq: 0,\n       events: [],\n       markers: [],\n       maxEvents: 200,\n       nearbyEventLimit: 12,\n       restoreFns: [],\n     };\n\n     function now() {\n       return Math.round(performance.now() - state.startedAtMs);\n     }\n\n     function preview(text, max = 80) {\n       const s = String(text ?? \"\");\n       return {\n         preview: s.length > max ? s.slice(0, max) + \"…\" : s,\n         length: s.length,\n         truncated: s.length > max,\n       };\n     }\n\n     function record(type, data) {\n       if (!state.running) return null;\n       const event = { id: \"evt-\" + (++state.seq), seq: state.seq, t: now(), type, data };\n       state.events.push(event);\n       if (state.events.length > state.maxEvents) state.events.shift();\n       return event;\n     }\n\n     function patchConsole() {\n       [\"log\", \"warn\", \"error\"].forEach((level) => {\n         const original = console[level];\n         console[level] = function (...args) {\n           record(\"console\", { level, message: preview(args.map(String).join(\" \")) });\n           return original.apply(console, args);\n         };\n         state.restoreFns.push(() => (console[level] = original));\n       });\n     }\n\n     function patchFetch() {\n       const original = global.fetch;\n       global.fetch = async function (input, init) {\n         const url = typeof input === \"string\" ? input : input.url;\n         const method = (init && init.method) || \"GET\";\n         const started = now();\n         try {\n           const res = await original.apply(global, arguments);\n           record(\"fetch\", { method, url, status: res.status, ok: res.ok, ms: now() - started });\n           return res;\n         } catch (error) {\n           record(\"fetch\", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) });\n           throw error;\n         }\n       };\n       state.restoreFns.push(() => (global.fetch = original));\n     }\n\n     function patchErrors() {\n       const onError = (event) =>\n         record(\"error\", { message: preview(event.message || String(event.reason || \"unknown\")) });\n       global.addEventListener(\"error\", onError);\n       global.addEventListener(\"unhandledrejection\", onError);\n       state.restoreFns.push(() => {\n         global.removeEventListener(\"error\", onError);\n         global.removeEventListener(\"unhandledrejection\", onError);\n       });\n     }\n\n     function patchClicks() {\n       const onClick = (event) => {\n         const el = event.target.closest(\"button, a, [data-action]\") || event.target;\n         record(\"click\", {\n           tag: el.tagName.toLowerCase(),\n           id: el.id || null,\n           action: el.dataset ? el.dataset.action || null : null,\n           text: preview(el.textContent && el.textContent.trim(), 40),\n         });\n       };\n       document.addEventListener(\"click\", onClick, true);\n       state.restoreFns.push(() => document.removeEventListener(\"click\", onClick, true));\n     }\n\n     const AgentMarkers = {\n       start(options = {}) {\n         if (state.running) return this;\n         state.sessionId = options.sessionId || \"session-\" + Date.now().toString(36);\n         state.startedAtIso = new Date().toISOString();\n         state.startedAtMs = performance.now();\n         state.maxEvents = options.maxEvents || 200;\n         state.nearbyEventLimit = options.nearbyEventLimit || 12;\n         state.seq = 0;\n         state.events = [];\n         state.markers = [];\n         state.running = true;\n         patchConsole();\n         patchFetch();\n         patchErrors();\n         patchClicks();\n         if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers;\n         record(\"session\", { note: \"recording started\", app: options.app || \"unknown\" });\n         return this;\n       },\n\n       /** Human presses the button: timestamped testimony + pointers into the trail. */\n       mark(label, note) {\n         if (!state.running) throw new Error(\"AgentMarkers not started\");\n         const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id);\n         const marker = {\n           id: \"mrk-\" + (state.markers.length + 1) + \"-\" + Date.now().toString(36),\n           seq: ++state.seq,\n           t: now(),\n           label: label || \"unlabeled\",\n           note: note || \"\",\n           nearbyEventIds: nearby,\n           screenshot: \"unavailable\", // browser demo: no screenshot API without permissions\n         };\n         state.markers.push(marker);\n         record(\"marker\", { markerId: marker.id, label: marker.label });\n         return marker;\n       },\n\n       record(type, data) {\n         return record(\"manual\", { type, ...data });\n       },\n\n       /** Bounded, redacted payload — everything an agent gets, nothing more. */\n       exportSession() {\n         return {\n           schemaVersion: 1,\n           sessionId: state.sessionId,\n           startedAt: state.startedAtIso,\n           exportedAt: new Date().toISOString(),\n           userAgent: navigator.userAgent,\n           markers: state.markers,\n           events: state.events,\n           redaction: {\n             storageValues: \"excluded\",\n             requestBodies: \"excluded\",\n             responseBodies: \"excluded\",\n             userText: \"preview+length only\",\n           },\n         };\n       },\n\n       stop() {\n         state.restoreFns.forEach((restore) => restore());\n         state.restoreFns = [];\n         state.running = false;\n         return this;\n       },\n     };\n\n     if (typeof module !== \"undefined\" && module.exports) module.exports = AgentMarkers;\n     global.AgentMarkers = AgentMarkers;\n   })(typeof window !== \"undefined\" ? window : globalThis);\n   ```\n\n2. Create `<static-dir>/markers-boot.js` with exactly this content, replacing only `\"my-app\"` with the app's real name:\n\n   ```js\n   /* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.\n      Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */\n   AgentMarkers.start({ app: \"my-app\" }); // replace \"my-app\" with your app's name\n\n   // One keystroke at the moment of surprise: one sentence of testimony.\n   window.addEventListener(\"keydown\", (e) => {\n     if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === \"m\") {\n       e.preventDefault();\n       const note = prompt(\"Why does this moment matter? (one sentence — it travels with the capture)\");\n       if (note !== null) console.log(\"marked:\", AgentMarkers.mark(\"user-flag\", note).id);\n     }\n   });\n\n   // Call exportMarkers() from the console, or wire it to a button.\n   window.exportMarkers = () => {\n     const session = AgentMarkers.exportSession();\n     const blob = new Blob([JSON.stringify(session, null, 2)], { type: \"application/json\" });\n     const a = Object.assign(document.createElement(\"a\"), {\n       href: URL.createObjectURL(blob),\n       download: session.sessionId + \".json\",\n     });\n     a.click();\n     URL.revokeObjectURL(a.href);\n     return session.sessionId + \".json\";\n   };\n   ```\n\n3. Load both files in the app's page BEFORE the app's own scripts (and before any code that replaces `window.fetch` — app-level fetch wrappers such as mocks or auth shims must be installed before `AgentMarkers.start()` runs so their calls land in the trail):\n\n   ```html\n   <script src=\"agent-markers.js\"></script>\n   <script src=\"markers-boot.js\"></script>\n   ```\n\n4. Create `<project-root>/scripts/make-agent-packet.mjs` with exactly this content (same bytes as https://mindful-mango-accy.here.now/make-agent-packet.mjs):\n\n   ```js\n   #!/usr/bin/env node\n   /**\n    * make-agent-packet.mjs — turn a marker-session export into a bounded agent debug packet.\n    *\n    * Usage:\n    *   node scripts/make-agent-packet.mjs <session.json> [marker-id]\n    *\n    * Emits markdown on stdout: human testimony, the nearby evidence slice, redaction\n    * receipts, and an explicit claims boundary — ready to paste into any agent.\n    */\n   import { readFileSync } from \"node:fs\";\n\n   const [file, markerArg] = process.argv.slice(2);\n   if (!file) {\n     console.error(\"usage: node scripts/make-agent-packet.mjs <session.json> [marker-id]\");\n     process.exit(1);\n   }\n\n   const session = JSON.parse(readFileSync(file, \"utf8\"));\n   if (session.schemaVersion !== 1) {\n     console.error(`unsupported schemaVersion: ${session.schemaVersion}`);\n     process.exit(1);\n   }\n\n   const marker = markerArg\n     ? session.markers.find((m) => m.id === markerArg)\n     : session.markers.at(-1);\n   if (!marker) {\n     console.error(markerArg ? `marker '${markerArg}' not found` : \"no markers in session\");\n     process.exit(1);\n   }\n\n   const nearbyIds = new Set(marker.nearbyEventIds ?? []);\n   const nearby = session.events.filter((e) => nearbyIds.has(e.id));\n   const fmt = (e) => {\n     const d = e.data ?? {};\n     switch (e.type) {\n       case \"fetch\":\n         return `${d.method} ${d.url} → ${d.status ?? \"NETWORK-ERROR\"}${d.error ? ` (${d.error.preview ?? d.error})` : \"\"} [${d.ms}ms]`;\n       case \"console\":\n         return `console.${d.level}: ${d.message?.preview ?? \"\"}`;\n       case \"click\":\n         return `click <${d.tag}${d.id ? `#${d.id}` : \"\"}> \"${d.text?.preview ?? \"\"}\"`;\n       case \"error\":\n         return `error: ${d.message?.preview ?? \"\"}`;\n       default:\n         return JSON.stringify(d);\n     }\n   };\n\n   const lines = [];\n   lines.push(`# Debug packet — marker ${marker.id}`);\n   lines.push(\"\");\n   lines.push(`- session: ${session.sessionId} (started ${session.startedAt})`);\n   lines.push(`- marker time: t+${marker.t}ms · label: ${marker.label}`);\n   lines.push(`- screenshot: ${marker.screenshot ?? \"unavailable\"}`);\n   lines.push(\"\");\n   lines.push(\"## Human testimony (why this moment matters)\");\n   lines.push(\"\");\n   lines.push(`> ${marker.note || \"(no explanation recorded)\"}`);\n   lines.push(\"\");\n   lines.push(`## Evidence trail (${nearby.length} events nearest the marker, seq order)`);\n   lines.push(\"\");\n   for (const e of nearby) lines.push(`- [seq ${e.seq} · t+${e.t}ms] ${e.type}: ${fmt(e)}`);\n   lines.push(\"\");\n   lines.push(\"## Redaction receipts\");\n   lines.push(\"\");\n   for (const [k, v] of Object.entries(session.redaction ?? {})) lines.push(`- ${k}: ${v}`);\n   lines.push(\"\");\n   lines.push(\"## Task for the agent\");\n   lines.push(\"\");\n   lines.push(\"Draft a reproducible scenario (preconditions, steps, expected, observed) that\");\n   lines.push(\"explains the testimony using ONLY the evidence above. Flag anything the trail\");\n   lines.push(\"cannot prove as a hypothesis needing verification.\");\n   lines.push(\"\");\n   lines.push(\"## Claims boundary\");\n   lines.push(\"\");\n   lines.push(\"Testimony is not diagnosis. Context is not proof. The trail shows what was\");\n   lines.push(\"captured, not everything that happened.\");\n\n   console.log(lines.join(\"\\n\"));\n   ```\n\n## Success check\n\nRun from `<project-root>`:\n\n```bash\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode scripts/make-agent-packet.mjs sample-session.json\n```\n\nExpected observable result: a markdown debug packet beginning `# Debug packet — marker <demo-marker>`, containing the testimony line `> It said Saved but my note never reached the server — this happened right after I reconnected.`, a 9-event evidence trail whose last line is `- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]`, four redaction receipts, a task section, and a claims boundary.\n\nThen perform the cold-read check: read that packet with NO other context (do not open the recorder source or this page) and state one specific hypothesis for the failure. A passing hypothesis names the mechanism, e.g. \"the reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success.\"\n\nFinally, verify the loop live in the user's app: open it in a browser, press Ctrl/Cmd+M (or run `window.__AGENT_MARKERS__.mark(\"user-flag\", \"test marker\")` in the console — `prompt()` blocks automation), then run `exportMarkers()` in the console. Confirm a `session-*.json` file downloads with `markers.length >= 1` and a `redaction` block.\n\nReport to your user: what you set up, the packet output of the success check, your cold-read hypothesis, and anything you had to adapt.\n\n## Notes for agents\n\n- `prompt()` blocks scripted browsers. In automation, call `window.__AGENT_MARKERS__.mark(label, note)` instead of the Ctrl/Cmd+M hotkey.\n- On macOS, Cmd+M can collide with the browser's minimize shortcut. The console call or an on-page button wired to the same `dropMarker` logic is the reliable path.\n- The event ring buffer is in-memory only — a page reload wipes it. Export before navigating or reloading.\n- `make-agent-packet.mjs` exits with `unsupported schemaVersion` unless the export has `schemaVersion: 1`. Exports from this recorder always do; hand-edited files may not.\n- The export deliberately excludes storage values, request/response bodies, and raw user text (preview+length only). Do not \"improve\" it by adding them — the redaction block inside every export is the audit trail readers rely on.\n- The recorder caps the trail at 200 events and pins the 12 nearest event ids to each marker (`maxEvents` / `nearbyEventLimit` options on `AgentMarkers.start`). If packets read too thin, raise `nearbyEventLimit` before adding new event types."
    },
    {
      "id": "factory-debug-markers-questions",
      "slug": "debug-markers-questions",
      "title": "Human testimony joined to runtime evidence — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Verification",
      "tags": [
        "debug-markers",
        "questions"
      ],
      "sources": [
        {
          "label": "Human testimony joined to runtime evidence — questions and tradeoffs",
          "url": "https://mindful-mango-accy.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "09-markers/dialogue.html#section-1"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1072,
      "url": "/topics/factory-debug-markers-questions/",
      "markdownUrl": "/markdown/factory-debug-markers-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-debug-markers-questions.json",
      "headings": [],
      "markdown": "# Human testimony joined to runtime evidence — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\nIsn’t this just logging? I already have logs.\n\nLogs are complete but unweighted — nothing in fifty thousand lines says *this* is the moment that mattered. When a person watching the app says \"that was wrong,\" that sentence is the highest-value debugging signal we have, and we normally throw it away. A marker makes it a first-class, timestamped artifact: one sentence of testimony, pinned to the ids of the nearest events. Here's the one from this site's real capture, exactly as the packet renders it:\n\n``` text\n## Human testimony (why this moment matters)\n\n> It said Saved but my note never reached the server — this happened right after I reconnected.\n```\n\nThe testimony points into the trail; the trail grounds the testimony in ordered facts. Neither alone does the job.\n\nWill anyone actually press the button? My users don’t even file bug reports.\n\nThat's the design constraint the whole thing is built around: one keystroke, one sentence, *during* the surprise. No form, no repro steps demanded. Anything heavier and nobody uses it at the moment that matters. The entire user-facing surface is this boot file — Ctrl/Cmd+M to mark, one console call to export:\n\n``` text\n/* markers-boot.js — load AFTER agent-markers.js, BEFORE your app's own scripts.\n   Ctrl/Cmd+M drops a marker; exportMarkers() in the console downloads the capture. */\nAgentMarkers.start({ app: \"my-app\" }); // replace \"my-app\" with your app's name\n\n// One keystroke at the moment of surprise: one sentence of testimony.\nwindow.addEventListener(\"keydown\", (e) => {\n  if ((e.ctrlKey || e.metaKey) && e.key.toLowerCase() === \"m\") {\n    e.preventDefault();\n    const note = prompt(\"Why does this moment matter? (one sentence — it travels with the capture)\");\n    if (note !== null) console.log(\"marked:\", AgentMarkers.mark(\"user-flag\", note).id);\n  }\n});\n\n// Call exportMarkers() from the console, or wire it to a button.\nwindow.exportMarkers = () => {\n  const session = AgentMarkers.exportSession();\n  const blob = new Blob([JSON.stringify(session, null, 2)], { type: \"application/json\" });\n  const a = Object.assign(document.createElement(\"a\"), {\n    href: URL.createObjectURL(blob),\n    download: session.sessionId + \".json\",\n  });\n  a.click();\n  URL.revokeObjectURL(a.href);\n  return session.sessionId + \".json\";\n};\n```\n\nYou’re recording my users’ clicks and network calls. Legal will kill this.\n\nOnly if you capture what legal is worried about — so don't. Decide the exclusions *before* the first capture, write them into the payload itself, and accept the narrower evidence. Every export from the recorder carries its own receipts:\n\n``` text\n## Redaction receipts\n\n- storageValues: excluded\n- requestBodies: excluded\n- responseBodies: excluded\n- userText: preview+length only\n```\n\nNo bodies, no tokens, no storage values; user text as preview + length only. A capture safe enough to paste anywhere gets pasted. A risky one gets hoarded and helps no one.\n\nNine events? My log dump has fifty thousand lines. How is less data better?\n\nBecause the slice is chosen by the human's testimony, not by grep luck. Read the real one from this site's captured session and name the bug before anyone tells you:\n\n``` text\n- [seq 3 · t+17397ms] click: click <button#save> \"Save note\"\n- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]\n- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable\n- [seq 6 · t+18436ms] click: click <button#toggle-net> \"Reconnect\"\n- [seq 7 · t+18436ms] console: console.log: reconnected: session restored\n- [seq 8 · t+18909ms] click: click <button#save> \"Save note\"\n- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]\n```\n\nNetwork failure, a \"session restored\" log, then a 401 on the very next save — under a UI that said \"Saved \". If you just reached \"the reconnect invalidated something the client still holds,\" a nine-line slice did what the dump rarely does. The [Session Replay](https://mindful-mango-accy.here.now/replay.html) shows the whole run that produced it.\n\nSo the agent reads that and confidently guesses anyway. How is this not garbage in, gospel out?\n\nThe handoff carries a fence. A weak handoff pastes a dump and asks \"what's wrong?\" — inviting confident guessing over noise. A strong handoff gives less data and more structure: what the human saw, what the system recorded, what was withheld, and what kind of answer is allowed. This is the exact prompt I hand any agent with a packet:\n\n``` text\nHere is a debug packet captured from a live session of my app. Before you read any code:\n\n1. Read the human testimony, then the evidence trail in seq order.\n2. State your single most likely hypothesis for the failure, in one sentence.\n3. Draft a reproducible scenario — preconditions, steps, expected, observed — using ONLY the evidence in the packet.\n4. Label anything the trail cannot prove as \"hypothesis — needs verification\".\n\nTestimony is not diagnosis. Context is not proof.\n\n--- PACKET ---\n[paste the output of: node scripts/make-agent-packet.mjs your-session.json]\n```\n\nThe packet itself ends the same way — a claims boundary. The agent's draft arrives labeled as a draft, and a person verifies it against the running app.\n\nCute demo. Does this survive contact with a real app?\n\nIt's already shipped. A production desktop app we studied runs the same loop natively: a hotkey mints a marker id, captures a screenshot, writes a marker log event, and opens a note where the tester types one explanation — all joined by the same id, with a log CLI whose `--marker` flag slices the session for agents. An external architecture review of that system pushed the same schema rules this recorder uses: sequence numbers as canonical order (not timestamps), ids joining everything, user text as preview + hash + length — never raw.\n\nOne integration gotcha from real use: if your app wraps `fetch` (mocks, auth shims), install your wrapper *before* `AgentMarkers.start()` so the wrapped calls land in the trail.\n\nFine. What do I paste into my project right now?\n\nTwo options. See the loop run cold from an empty directory in about thirty seconds:\n\n``` text\nmkdir -p markers-quickstart && cd markers-quickstart\ncurl -sO https://mindful-mango-accy.here.now/agent-markers.js\ncurl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode make-agent-packet.mjs sample-session.json\n```\n\nOr skip the typing entirely — paste this into your own agent and let it wire your app:\n\n``` text\nFetch https://mindful-mango-accy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\nThe [section guide](https://mindful-mango-accy.here.now/index.html) prints all three files complete — recorder, boot, packet renderer."
    },
    {
      "id": "factory-debug-markers-worked-example",
      "slug": "debug-markers-worked-example",
      "title": "Human testimony joined to runtime evidence — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Verification",
      "tags": [
        "debug-markers",
        "examples"
      ],
      "sources": [
        {
          "label": "Human testimony joined to runtime evidence — worked example",
          "url": "https://mindful-mango-accy.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "09-markers/replay.html#The session, beat by beat"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1401,
      "url": "/topics/factory-debug-markers-worked-example/",
      "markdownUrl": "/markdown/factory-debug-markers-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-debug-markers-worked-example.json",
      "headings": [
        {
          "id": "the-session-beat-by-beat",
          "text": "The session, beat by beat",
          "level": 2
        }
      ],
      "markdown": "# Human testimony joined to runtime evidence — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session, beat by beat\n\nReplayed from a prior scripted session against the workshop's Field Notes demo app — the same run that produced [sample-session.json](https://mindful-mango-accy.here.now/sample-session.json), published raw on this site. Prompts are condensed; every output below is quoted verbatim from the captured artifacts.\n\nYou\n\nServe the Field Notes demo and reproduce the reconnect-and-save failure: type a note, go offline, save, reconnect, save again.\n\nAgent\n\nDrove the app in a scripted browser. The offline save failed honestly (\"Save failed (offline?)\"). After **Reconnect**, the second save showed **\"Saved \"** — but the mock server returned 401. The plant: reconnecting rotates the server's session token, the client keeps its stale copy, and the save handler treats anything below 500 as success:\n\n``` text\n// BUG: only 5xx counts as failure, so the stale-token 401 shows \"Saved \".\nif (res.status < 500) {\n  statusEl.textContent = \"Saved \";\n} else {\n  statusEl.textContent = \"Save failed (server error)\";\n}\n```\n\nWould your users file a useful bug report for this? They saw a success message. That gap is the whole reason markers exist.\n\nYou\n\nMark that moment. Testimony: \"It said Saved but my note never reached the server — this happened right after I reconnected.\"\n\nAgent\n\nThe  button uses `prompt()`, which blocks scripted browsers — so the mark went in through the console instead:\n\n``` text\nwindow.__AGENT_MARKERS__.mark(\n  \"user-flag\",\n  \"It said Saved but my note never reached the server — this happened right after I reconnected.\"\n)\n```\n\nMarker `<demo-marker>` recorded, pinned to the nine nearest events by id.\n\nFor a human it's one keystroke (Ctrl/Cmd+M) and one sentence at the moment of surprise. No form, no repro steps demanded — anything heavier and nobody uses it when it matters.\n\nYou\n\nExport the session and show me exactly what leaves the machine.\n\nAgent\n\n`exportSession()` produced a schemaVersion-1 JSON — 1 marker, 10 events, and a redaction block that documents what was withheld:\n\n``` text\n\"redaction\": {\n  \"storageValues\": \"excluded\",\n  \"requestBodies\": \"excluded\",\n  \"responseBodies\": \"excluded\",\n  \"userText\": \"preview+length only\"\n}\n```\n\nNo request or response bodies, no tokens, no storage values; user text travels as preview + length only. The full export is published raw as [sample-session.json](https://mindful-mango-accy.here.now/sample-session.json).\n\nThe redaction policy rides inside the payload, so every reader can audit what was withheld. A capture safe enough to paste anywhere gets pasted; a risky one gets hoarded and helps no one.\n\nYou\n\nRender the agent packet from that export.\n\nAgent\n\n``` text\nnode scripts/make-agent-packet.mjs samples/sample-session.json\n```\n\nThe packet leads with the testimony, then the seq-ordered evidence slice. Seven consecutive lines, exactly as rendered:\n\n``` text\n- [seq 3 · t+17397ms] click: click <button#save> \"Save note\"\n- [seq 4 · t+17519ms] fetch: POST /api/notes → NETWORK-ERROR (NetworkError: connection lost) [122ms]\n- [seq 5 · t+17519ms] console: console.warn: save failed: network unavailable\n- [seq 6 · t+18436ms] click: click <button#toggle-net> \"Reconnect\"\n- [seq 7 · t+18436ms] console: console.log: reconnected: session restored\n- [seq 8 · t+18909ms] click: click <button#save> \"Save note\"\n- [seq 9 · t+19031ms] fetch: POST /api/notes → 401 [122ms]\n```\n\nRead it top to bottom: NETWORK-ERROR → \"reconnected\" → 401 on the very next save, under a visible \"Saved \". A nine-line slice doing what a full log dump rarely does.\n\nYou\n\nNow read the packet cold — no source code, no other context. One hypothesis, one sentence, before you look at anything else.\n\nAgent\n\n*The reconnect rotated or invalidated a session credential the client still holds, and the app treats the resulting 401 as success.*\n\nFlagged as \"hypothesis — needs verification\", per the packet's claims boundary: testimony is not diagnosis, context is not proof.\n\nThat is the pass condition for any capture you build: a cold reader — human or agent — gets from the packet alone to the mechanism. The hypothesis arrives labeled as a draft; a person verifies it against the running app.\n\nYou\n\nGood. Give me the version I can drop into any app.\n\nAgent\n\nThe whole recorder — dependency-free, no build step. Everything above was captured by these lines (same bytes as [agent-markers.js](https://mindful-mango-accy.here.now/agent-markers.js) on this site):\n\n``` text\n/**\n * agent-markers.js — a tiny, dependency-free \"press a button, capture the moment\" recorder.\n *\n * Pattern: a MARKER is timestamped human testimony (\"this moment matters, here's why\").\n * A TRAIL is the ordered semantic events (console, fetch, error, click) that led there.\n * Export = bounded, redacted payload you can hand to an agent as a debug packet.\n *\n * Deliberately NOT captured: storage values, request/response bodies, raw input text.\n * Testimony is not diagnosis. Context is not proof.\n */\n(function (global) {\n  \"use strict\";\n\n  const state = {\n    running: false,\n    sessionId: null,\n    startedAtIso: null,\n    startedAtMs: 0,\n    seq: 0,\n    events: [],\n    markers: [],\n    maxEvents: 200,\n    nearbyEventLimit: 12,\n    restoreFns: [],\n  };\n\n  function now() {\n    return Math.round(performance.now() - state.startedAtMs);\n  }\n\n  function preview(text, max = 80) {\n    const s = String(text ?? \"\");\n    return {\n      preview: s.length > max ? s.slice(0, max) + \"…\" : s,\n      length: s.length,\n      truncated: s.length > max,\n    };\n  }\n\n  function record(type, data) {\n    if (!state.running) return null;\n    const event = { id: \"evt-\" + (++state.seq), seq: state.seq, t: now(), type, data };\n    state.events.push(event);\n    if (state.events.length > state.maxEvents) state.events.shift();\n    return event;\n  }\n\n  function patchConsole() {\n    [\"log\", \"warn\", \"error\"].forEach((level) => {\n      const original = console[level];\n      console[level] = function (...args) {\n        record(\"console\", { level, message: preview(args.map(String).join(\" \")) });\n        return original.apply(console, args);\n      };\n      state.restoreFns.push(() => (console[level] = original));\n    });\n  }\n\n  function patchFetch() {\n    const original = global.fetch;\n    global.fetch = async function (input, init) {\n      const url = typeof input === \"string\" ? input : input.url;\n      const method = (init && init.method) || \"GET\";\n      const started = now();\n      try {\n        const res = await original.apply(global, arguments);\n        record(\"fetch\", { method, url, status: res.status, ok: res.ok, ms: now() - started });\n        return res;\n      } catch (error) {\n        record(\"fetch\", { method, url, status: null, ok: false, ms: now() - started, error: preview(error && error.message) });\n        throw error;\n      }\n    };\n    state.restoreFns.push(() => (global.fetch = original));\n  }\n\n  function patchErrors() {\n    const onError = (event) =>\n      record(\"error\", { message: preview(event.message || String(event.reason || \"unknown\")) });\n    global.addEventListener(\"error\", onError);\n    global.addEventListener(\"unhandledrejection\", onError);\n    state.restoreFns.push(() => {\n      global.removeEventListener(\"error\", onError);\n      global.removeEventListener(\"unhandledrejection\", onError);\n    });\n  }\n\n  function patchClicks() {\n    const onClick = (event) => {\n      const el = event.target.closest(\"button, a, [data-action]\") || event.target;\n      record(\"click\", {\n        tag: el.tagName.toLowerCase(),\n        id: el.id || null,\n        action: el.dataset ? el.dataset.action || null : null,\n        text: preview(el.textContent && el.textContent.trim(), 40),\n      });\n    };\n    document.addEventListener(\"click\", onClick, true);\n    state.restoreFns.push(() => document.removeEventListener(\"click\", onClick, true));\n  }\n\n  const AgentMarkers = {\n    start(options = {}) {\n      if (state.running) return this;\n      state.sessionId = options.sessionId || \"session-\" + Date.now().toString(36);\n      state.startedAtIso = new Date().toISOString();\n      state.startedAtMs = performance.now();\n      state.maxEvents = options.maxEvents || 200;\n      state.nearbyEventLimit = options.nearbyEventLimit || 12;\n      state.seq = 0;\n      state.events = [];\n      state.markers = [];\n      state.running = true;\n      patchConsole();\n      patchFetch();\n      patchErrors();\n      patchClicks();\n      if (options.exposeGlobal !== false) global.__AGENT_MARKERS__ = AgentMarkers;\n      record(\"session\", { note: \"recording started\", app: options.app || \"unknown\" });\n      return this;\n    },\n\n    /** Human presses the button: timestamped testimony + pointers into the trail. */\n    mark(label, note) {\n      if (!state.running) throw new Error(\"AgentMarkers not started\");\n      const nearby = state.events.slice(-state.nearbyEventLimit).map((e) => e.id);\n      const marker = {\n        id: \"mrk-\" + (state.markers.length + 1) + \"-\" + Date.now().toString(36),\n        seq: ++state.seq,\n        t: now(),\n        label: label || \"unlabeled\",\n        note: note || \"\",\n        nearbyEventIds: nearby,\n        screenshot: \"unavailable\", // browser demo: no screenshot API without permissions\n      };\n      state.markers.push(marker);\n      record(\"marker\", { markerId: marker.id, label: marker.label });\n      return marker;\n    },\n\n    record(type, data) {\n      return record(\"manual\", { type, ...data });\n    },\n\n    /** Bounded, redacted payload — everything an agent gets, nothing more. */\n    exportSession() {\n      return {\n        schemaVersion: 1,\n        sessionId: state.sessionId,\n        startedAt: state.startedAtIso,\n        exportedAt: new Date().toISOString(),\n        userAgent: navigator.userAgent,\n        markers: state.markers,\n        events: state.events,\n        redaction: {\n          storageValues: \"excluded\",\n          requestBodies: \"excluded\",\n          responseBodies: \"excluded\",\n          userText: \"preview+length only\",\n        },\n      };\n    },\n\n    stop() {\n      state.restoreFns.forEach((restore) => restore());\n      state.restoreFns = [];\n      state.running = false;\n      return this;\n    },\n  };\n\n  if (typeof module !== \"undefined\" && module.exports) module.exports = AgentMarkers;\n  global.AgentMarkers = AgentMarkers;\n})(typeof window !== \"undefined\" ? window : globalThis);\n```\n\nThe boot file and the packet renderer are printed complete in the [section guide](https://mindful-mango-accy.here.now/index.html), or replay this whole loop from an empty directory:\n\n``` text\nmkdir -p markers-quickstart && cd markers-quickstart\ncurl -sO https://mindful-mango-accy.here.now/agent-markers.js\ncurl -sO https://mindful-mango-accy.here.now/make-agent-packet.mjs\ncurl -sO https://mindful-mango-accy.here.now/sample-session.json\nnode make-agent-packet.mjs sample-session.json\n```\n\nTotal session: five prompts. The loop the transcript demonstrates — mark → export → packet → hypothesis — is the same one your attendees' agents replay from [agent.md](https://mindful-mango-accy.here.now/agent.md)."
    },
    {
      "id": "factory-reasoning-and-video",
      "slug": "reasoning-and-video",
      "title": "Independent reasoning and video evidence",
      "summary": "Escalate consequential decisions with filtered context and use probes, sentinels, and bounded video analysis.",
      "category": "Verification",
      "tags": [
        "reasoning",
        "factory"
      ],
      "sources": [
        {
          "label": "Independent reasoning and video evidence",
          "url": "https://shiny-rosette-m6zy.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/index.html#TL;DR",
        "08-oracle-video/index.html#Where the strongest models live",
        "08-oracle-video/index.html#Appendix",
        "08-oracle-video/index.html#How Oracle borrows your browser",
        "08-oracle-video/index.html#What 1,978 real consults look like",
        "08-oracle-video/index.html#The Loop Craft rip: 93 minutes of video into a permanent wiki",
        "learn.html#q3-max-intelligence"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1254,
      "url": "/topics/factory-reasoning-and-video/",
      "markdownUrl": "/markdown/factory-reasoning-and-video.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "where-the-strongest-models-live",
          "text": "Where the strongest models live",
          "level": 2
        },
        {
          "id": "how-oracle-borrows-your-browser",
          "text": "How Oracle borrows your browser",
          "level": 2
        },
        {
          "id": "what-1-978-real-consults-look-like",
          "text": "What 1,978 real consults look like",
          "level": 2
        },
        {
          "id": "the-loop-craft-rip-93-minutes-of-video-into-a-permanent-wiki",
          "text": "The Loop Craft rip: 93 minutes of video into a permanent wiki",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "escalate-the-decision-not-the-workflow",
          "text": "Escalate the decision, not the workflow",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Independent reasoning and video evidence\n\nEscalate consequential decisions with filtered context and use probes, sentinels, and bounded video analysis.\n\n## Related working material\n\n- [Independent reasoning and video evidence — prompts and exercises](/topics/factory-reasoning-and-video-practice/)\n- [Independent reasoning and video evidence — questions and tradeoffs](/topics/factory-reasoning-and-video-questions/)\n- [Independent reasoning and video evidence — worked example](/topics/factory-reasoning-and-video-worked-example/)\n\n## TL;DR\n\n- Oracle is an agent whose hands are a real Chrome browser: it drives chatgpt.com and gemini.google.com using cookies from the Chrome profile you already logged into. No API keys — subscription-priced frontier models.\n- You leave with a working local Oracle (install + one handshake command) and the two prompt patterns that make it pay: the maximum-batch consult and the sentinel video probe.\n- The one move: never spend a 20–60 minute consult on \"what's next?\" — demand the maximum actionable batch. That pattern turned a 93-minute workshop video into a permanent wiki: [silken-ferry-63mw.here.now](https://silken-ferry-63mw.here.now/).\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://shiny-rosette-m6zy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## Where the strongest models live\n\nThe easy assumption is that maximum intelligence is an API call away. It isn't. ChatGPT's strongest tier — the model picker's \"Latest\" row, currently GPT-5.6 Pro with Extended thinking — is a subscription feature of the chat product. And Gemini's video understanding is only reachable through the page's own upload widget; the API path can't upload the browser video at all. The strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key.\n\n## How Oracle borrows your browser\n\nThe whole mechanism in one breath: a human signs into ChatGPT in normal Chrome once; Oracle copies those session cookies into a temporary automation profile; the agent then drives that profile like a very fast reader who pastes a huge bundle of code and waits. What rides along with the cookies is context — bundles validated up to roughly 900k tokens of project code per consult.\n\nThe contrast that makes it click: an API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything the chat product gives you — the model picker, extended thinking, and the file-upload widget the video pipeline depends on.\n\nMost people run this on their own laptop, and that is the whole setup. One operator's variant: an always-on Mac mini runs `oracle serve` with the signed-in Chrome, every other machine points at it over a private network, and a four-slot dual-account pool runs four hour-long consults at once while nobody's laptop stays open. Same trick, made multi-tenant.\n\n## What 1,978 real consults look like\n\nA consult costs 20–60 minutes of wall clock, so the prompt contract bans spending it like a chat message. In the observed snapshot the local archive held about 1,978 session folders shaped by that rule. A sample:\n\nThe recurring consult shapes are repeated hardening audits, independent multi-angle review followed by a judge, forensic debugging, redesign planning, and planning a media-analysis pipeline before executing it.\n\nThe recurring shapes: iteration audits, where a fresh frontier reviewer re-reads the codebase every loop; multi-angle panels, where the same question runs three ways and a judge consult picks the winner; and pipeline-planning-the-pipeline — GPT-5.6 Pro designed the video sharding strategy that Gemini then executed. Every session leaves `output.log` and token receipts, replayable with `oracle session <id> --render`.\n\n## The Loop Craft rip: 93 minutes of video into a permanent wiki\n\nIn the observed snapshot the ask was: take a public 93:49 YouTube workshop on building durable autonomous agents and build it into an extensive published wiki with resources, pull quotes, and copy-paste prompts. The run shows the discipline that makes fragile browser automation dependable.\n\nFirst, probes. Early upload probes errored; a rebuild fixed the path; then the awaited-upload probe came back with the exact line `ATTACHED_VIDEO_OK loopcraft-awaited-upload-probe` — from the real MP4. Only then did the expensive runs start. GPT-5.6 Pro reviewed the segmentation plan, and Gemini watched source-native shards one by one, each analysis ending in its exact sentinel. The analyses prove Gemini genuinely watched: it heard \"we are going to talk about Loopcraft…\" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark.\n\nShard 004 is the teachable failure. It errored twice while its three siblings sailed through — which rules out \"the pipeline is down\" and points at the input. An exact re-encode fixed it completely: the analysis finished in 73 seconds with the exact sentinel, and the re-encode settings were kept as the durable media recipe for future runs. Classify the failure, change one variable, re-run the cheap proof, keep the fix.\n\nThe result is public and permanent: the [Loop Craft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/). A 93-minute recording became a quotable artifact in one working session — and after publishing, the agent curled the live URLs rather than trusting the publish receipt.\n\n## Appendix\n\n### Limits & caveats\n\n- Browser automation is experimental and most stable on macOS. UI drift, model-picker changes, and upload races are real — the probe discipline exists because this path breaks. On Linux, pass `--browser-chrome-path`/`--browser-cookie-path` if detection fails.\n- Cookie-based automation authenticates as your personal account. The sources describe capability and access, not permission: they do not analyze provider terms of service or account risk. Decide that trade-off for your own accounts.\n- The four-slot dual-account pool is qualified against one exact build and topology. There is no evidence it transfers to other machines or accounts without redoing that qualification. Its access tokens are private and absent from this entire site; the attached skill files describe the pool only via a generic ssh alias, loopback ports, and a pinned build hash — identifiers of the presenter's setup, useless without it.\n- \"A consult repays the hour\" is the contract's premise, not a measured result — the archive shows scale and shape of use, not a controlled comparison against cheaper prompting.\n- The Loop Craft timeline is compressed; some intermediate error attempts are omitted, and the full receipts stay in local session folders. The shard-004 re-encode is an empirical fix, not a diagnosis of why the original encoding failed.\n- The session archive figures (~1,978 folders) were counted in the observed snapshot and grow continuously.\n\n## Operating practice\n\n### Escalate the decision, not the workflow\n\n#### What to notice\n\nSpend frontier-model or video-analysis overhead only where a second reasoning or observation path can change the decision.\n\n#### Try this\n\nBring one decision, a filtered evidence bundle, alternatives, hidden assumptions, a **discriminating experiment**, and a reversal plan.\n\n> “Might as well use the maximum intelligence I have access to.”\n\nJohn Lindquist · [05:11:10](https://proud-anchor-53zn.here.now/watch.html?t=18670#recording-player)\n\n#### Concept\n\nUse deeper reasoning for hard-to-reverse architecture, obscure stacks, contradictory evidence, or independent verification. Use video when timing, pointer movement, or transient UI state is the evidence.\n\n#### Reflection\n\nWorkshop model names, plan tiers, prices, and limits are dated statements, not current purchasing guidance.\n\n**Recording evidence:** listen at 05:05:27.\n\n> “So, it's able to walk through and analyze the videos, in chunks, in shards.”\n\nJohn Lindquist · [05:19:43](https://proud-anchor-53zn.here.now/watch.html?t=19183#recording-player)\n\n[Open Maximum Intelligence and Video](https://shiny-rosette-m6zy.here.now/)\n\n#### Links shared for this topic\n\n- [Oracle](https://github.com/steipete/oracle) — A repository-context bundler and browser consult workflow.\n- [Video analysis companion](https://silken-ferry-63mw.here.now/) — The prepared companion for video-assisted analysis.\n- [Google AI Studio Live](https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview) — A live multimodal model surface shared during the video discussion.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=18327#q3-max-intelligence)"
    },
    {
      "id": "factory-reasoning-and-video-discussion",
      "slug": "reasoning-and-video-discussion",
      "title": "Independent reasoning and video evidence — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Verification",
      "tags": [
        "reasoning-and-video",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[172]",
        "resource-manifest.json#videoEvidence.concepts[173]",
        "resource-manifest.json#videoEvidence.concepts[174]",
        "resource-manifest.json#videoEvidence.concepts[175]",
        "resource-manifest.json#videoEvidence.concepts[176]",
        "resource-manifest.json#videoEvidence.concepts[177]",
        "resource-manifest.json#videoEvidence.concepts[178]",
        "resource-manifest.json#videoEvidence.concepts[179]",
        "resource-manifest.json#videoEvidence.concepts[180]",
        "resource-manifest.json#videoEvidence.concepts[181]",
        "resource-manifest.json#videoEvidence.concepts[182]",
        "resource-manifest.json#videoEvidence.concepts[183]",
        "resource-manifest.json#videoEvidence.concepts[184]",
        "resource-manifest.json#videoEvidence.concepts[185]",
        "resource-manifest.json#videoEvidence.concepts[186]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[56]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[57]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[58]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[59]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[60]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[61]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[62]",
        "resource-manifest.json#videoEvidence.exercises[16]",
        "resource-manifest.json#videoEvidence.exercises[17]",
        "resource-manifest.json#videoEvidence.timeline[813]",
        "resource-manifest.json#videoEvidence.timeline[819]",
        "resource-manifest.json#videoEvidence.timeline[821]",
        "resource-manifest.json#videoEvidence.timeline[822]",
        "resource-manifest.json#videoEvidence.timeline[823]",
        "resource-manifest.json#videoEvidence.timeline[824]",
        "resource-manifest.json#videoEvidence.timeline[825]",
        "resource-manifest.json#videoEvidence.timeline[829]",
        "resource-manifest.json#videoEvidence.timeline[830]",
        "resource-manifest.json#videoEvidence.timeline[831]",
        "resource-manifest.json#videoEvidence.timeline[832]",
        "resource-manifest.json#videoEvidence.timeline[833]",
        "resource-manifest.json#videoEvidence.timeline[834]",
        "resource-manifest.json#videoEvidence.timeline[836]",
        "resource-manifest.json#videoEvidence.timeline[837]",
        "resource-manifest.json#videoEvidence.timeline[838]",
        "resource-manifest.json#videoEvidence.timeline[839]",
        "resource-manifest.json#videoEvidence.timeline[842]",
        "resource-manifest.json#videoEvidence.timeline[843]",
        "resource-manifest.json#videoEvidence.timeline[846]",
        "resource-manifest.json#videoEvidence.timeline[847]",
        "resource-manifest.json#videoEvidence.timeline[849]",
        "resource-manifest.json#videoEvidence.timeline[852]",
        "resource-manifest.json#videoEvidence.timeline[859]",
        "resource-manifest.json#videoEvidence.timeline[860]",
        "resource-manifest.json#videoEvidence.timeline[869]",
        "resource-manifest.json#videoEvidence.timeline[871]",
        "resource-manifest.json#videoEvidence.timeline[876]",
        "resource-manifest.json#videoEvidence.timeline[878]",
        "resource-manifest.json#videoEvidence.timeline[881]",
        "resource-manifest.json#videoEvidence.timeline[894]",
        "resource-manifest.json#videoEvidence.timeline[895]",
        "resource-manifest.json#videoEvidence.timeline[896]",
        "resource-manifest.json#videoEvidence.demos[103]",
        "resource-manifest.json#videoEvidence.demos[104]",
        "resource-manifest.json#videoEvidence.demos[105]",
        "resource-manifest.json#videoEvidence.demos[106]",
        "resource-manifest.json#videoEvidence.demos[107]",
        "resource-manifest.json#videoEvidence.demos[108]",
        "resource-manifest.json#videoEvidence.demos[109]",
        "resource-manifest.json#videoEvidence.demos[110]",
        "resource-manifest.json#videoEvidence.demos[111]",
        "resource-manifest.json#videoEvidence.demos[112]"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1749,
      "url": "/topics/factory-reasoning-and-video-discussion/",
      "markdownUrl": "/markdown/factory-reasoning-and-video-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "maximum-intelligence-models",
          "text": "Maximum Intelligence Models",
          "level": 3
        },
        {
          "id": "context-bundling",
          "text": "Context Bundling",
          "level": 3
        },
        {
          "id": "browser-based-agent-automation",
          "text": "Browser-based Agent Automation",
          "level": 3
        },
        {
          "id": "maximum-intelligence-for-obscure-tech-stacks",
          "text": "Maximum Intelligence for Obscure Tech Stacks",
          "level": 3
        },
        {
          "id": "asynchronous-deep-reasoning-passes",
          "text": "Asynchronous Deep Reasoning Passes",
          "level": 3
        },
        {
          "id": "voice-agent-context-continuation",
          "text": "Voice Agent Context Continuation",
          "level": 3
        },
        {
          "id": "codex-subscription-harness-support",
          "text": "Codex Subscription & Harness Support",
          "level": 3
        },
        {
          "id": "context-bundling-with-packx",
          "text": "Context Bundling with packx",
          "level": 3
        },
        {
          "id": "remote-browser-agent-execution",
          "text": "Remote Browser Agent Execution",
          "level": 3
        },
        {
          "id": "native-video-analysis",
          "text": "Native Video Analysis",
          "level": 3
        },
        {
          "id": "sharded-video-context-extraction",
          "text": "Sharded Video Context Extraction",
          "level": 3
        },
        {
          "id": "video-sharding-automated-analysis",
          "text": "Video Sharding & Automated Analysis",
          "level": 3
        },
        {
          "id": "screen-interaction-capture-for-ai",
          "text": "Screen Interaction Capture for AI",
          "level": 3
        },
        {
          "id": "real-time-multimodal-prompting",
          "text": "Real-time Multimodal Prompting",
          "level": 3
        },
        {
          "id": "google-ai-studio-live-api",
          "text": "Google AI Studio Live API",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "what-types-of-situations-do-you-consult-planning-creating-spec-user-stories-reviewing-diagnosing-questioning",
          "text": "what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning?",
          "level": 3
        },
        {
          "id": "do-you-have-agents-gather-context-first-do-grill-me-before-etc-how-do-you-gather-context",
          "text": "do you have agents gather context first? do grill me before, etc, how do you gather context",
          "level": 3
        },
        {
          "id": "can-you-use-the-codex-subscription-in-pi",
          "text": "Can you use the codex subscription in pi?",
          "level": 3
        },
        {
          "id": "what-types-of-situation-do-you-have-agents-gather-context-first-or-do-you-grill-first",
          "text": "What types of situation? Do you have agents gather context first, or do you grill first?",
          "level": 3
        },
        {
          "id": "do-you-use-notebooklm-to-send-people-artifacts-like-podcasts-videos-etc-2-do-you-create-your-own-podcasts-i-find-it-useful-for-research-papers-3-how-do-you-do-research",
          "text": "do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research?",
          "level": 3
        },
        {
          "id": "can-a-single-mermaid-graph-effectively-serve-both-machine-context-injection-and-human-readable-documentation-or-should-we-treat-llm-facing-context-architecture-entirely-separate-from-human-facing-notes",
          "text": "Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes?",
          "level": 3
        },
        {
          "id": "does-that-require-ultra-subscription-do-you-find-value-in-ultra-subscription",
          "text": "does that require ULTRA subscription? do you find value in ULTRA subscription?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "demonstration-detail-05-05-43",
          "text": "Demonstration detail: 05:05:43",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-08-22",
          "text": "Demonstration detail: 05:08:22",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-08-52",
          "text": "Demonstration detail: 05:08:52",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-12-11",
          "text": "Demonstration detail: 05:12:11",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-14-06",
          "text": "Demonstration detail: 05:14:06",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-14-36",
          "text": "Demonstration detail: 05:14:36",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-16-12",
          "text": "Demonstration detail: 05:16:12",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-19-05",
          "text": "Demonstration detail: 05:19:05",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-20-07",
          "text": "Demonstration detail: 05:20:07",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-23-25",
          "text": "Demonstration detail: 05:23:25",
          "level": 3
        }
      ],
      "markdown": "# Independent reasoning and video evidence — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Maximum Intelligence Models\n\nHigh-tier reasoning models like GPT-5.6 Sol that execute long-duration thinking/research paths (15-30 minutes) to solve highly complex tasks.\n\n### Context Bundling\n\nBundling large portions of a codebase or repository into a single, structured prompt file suitable for LLM long-context windows (up to a million tokens).\n\n### Browser-based Agent Automation\n\nAutomating a local browser using existing session cookies to paste complex context and prompts directly into a consumer web interface rather than calling expensive API endpoints.\n\n### Maximum Intelligence for Obscure Tech Stacks\n\nUtilizing top-tier reasoning models (e.g. ChatGPT Pro / o1) when working with frameworks that lack representation in base model weights, such as Rust GPUI.\n\n### Asynchronous Deep Reasoning Passes\n\nOffloading complex architecture planning or audit tasks to multi-minute reasoning sessions (8-23 minutes) while working on other tasks.\n\n### Voice Agent Context Continuation\n\nPrompting mobile voice agents with explicit context loading phrases ('Please load in the context') to resume desktop conversations on mobile devices.\n\n### Codex Subscription & Harness Support\n\nUtilizing Codex as a versatile backend model for open agent harnesses (OpenClaw, Script Kit, Pi), offering image input and cost efficiency over proprietary locked harnesses.\n\n### Context Bundling with packx\n\nPackaging repository files into consolidated text attachments (attachments-bundle(133).txt) using the packx skill to supply complete project context to high-reasoning models.\n\n### Remote Browser Agent Execution\n\nRunning browser automation agents on a separate remote computer (Mac Mini) via Screen Sharing and mobile Codex Remote to eliminate focus-stealing window popups on the main workstation.\n\n### Native Video Analysis\n\nMultimodal AI processing of complete video/audio streams directly without extracting separate frame images.\n\n### Sharded Video Context Extraction\n\nChunking longer video recordings into ~4-minute shards with sequential context pass-through for detailed extraction.\n\n### Video Sharding & Automated Analysis\n\nSplitting down massive video captures into distinct shards for targeted semantic parsing by advanced LLMs to build documentation architectures dynamically.\n\n### Screen Interaction Capture for AI\n\nLeveraging on-demand video capturing mechanisms to visually present system states directly to multimodal models rather than manually typing out error trace context.\n\n### Real-time Multimodal Prompting\n\nStreaming live video feeds, screen captures, and sound input seamlessly to an LLM for ongoing interactive visual context analysis.\n\n### Google AI Studio Live API\n\nA specialized sandbox area in Google AI Studio configured for testing low-latency live streaming capabilities of preview Gemini models.\n\n## Questions and answer status\n\n### what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning?\n\n**Status: answered.** John explains he consults reasoning models primarily for continuous architecture planning, handling obscure component/rendering issues in specialized frameworks (Rust GPUI), and conducting asynchronous verification passes.\n\n### do you have agents gather context first? do grill me before, etc, how do you gather context\n\n**Status: deferred.** Unanswered in this shard as John transitions to discussing mobile voice agent context loading.\n\n### Can you use the codex subscription in pi?\n\n**Status: answered.** John confirms that the Codex subscription can be used in Pi.\n\n### What types of situation? Do you have agents gather context first, or do you grill first?\n\n**Status: answered.** John brainstorms and breaks down the task first, then hands off to Oracle instructing it to use the packx skill to assemble and attach full repository context files.\n\n### do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research?\n\n**Status: unanswered.** No answer was linked in the companion evidence.\n\n### Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes?\n\n**Status: unanswered.** No answer was linked in the companion evidence.\n\n### does that require ULTRA subscription? do you find value in ULTRA subscription?\n\n**Status: unanswered.** No answer was linked in the companion evidence.\n\n## Exercises\n\n- **Try:** Configure remote browser execution for agent workflows using a dedicated secondary machine (e.g. Mac Mini) via Screen Sharing and Codex Remote on mobile to prevent automated browser sessions from stealing workstation focus.\n  **Basis:** Presenter demonstrates Screen Sharing connection to remote Mac Mini at 05:14:36 - 05:15:35 and explains remote mobile workflow.\n\n- **Try:** Bundle codebase context into prompt attachment files using packx before passing tasks to reasoning models.\n  **Basis:** Presenter demonstrates attachments-bundle(133).txt document in ChatGPT Pro at 05:13:22 - 05:13:58 and references packx on deep-steel-rfbs.here.now.\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [05:06:00](https://proud-anchor-53zn.here.now/watch.html?t=18360#recording-player) — John clicks the intelligence dropdown model selector in ChatGPT, showing options like Instant 5.5 and GPT-5.6 Sol under the Pro tier.\n\n- [05:08:35](https://proud-anchor-53zn.here.now/watch.html?t=18515#recording-player) — John reviews the context bundling tools table showing Repomix, git2prompt, files-to-prompt, pacx, and yek.\n\n- [05:09:09](https://proud-anchor-53zn.here.now/watch.html?t=18549#recording-player) — a participant asks what situations John consults models for (planning, specs, reviewing, diagnosing).\n\n- [05:09:15](https://proud-anchor-53zn.here.now/watch.html?t=18555#recording-player) — John answers a participant, stating he uses models continuously for planning and complex codebase tasks.\n\n- [05:09:23](https://proud-anchor-53zn.here.now/watch.html?t=18563#recording-player) — John mentions his ScriptKit project uses GPUI, a Rust framework developed by Zed that is sparse in training weights.\n\n- [05:09:54](https://proud-anchor-53zn.here.now/watch.html?t=18594#recording-player) — John explains tossing obscure rendering and component questions to ChatGPT Pro reasoning models.\n\n- [05:10:16](https://proud-anchor-53zn.here.now/watch.html?t=18616#recording-player) — ChatGPT Pro interface displays a session that ran reasoning for 14 minutes ('Worked for 14m 16s').\n\n- [05:10:48](https://proud-anchor-53zn.here.now/watch.html?t=18648#recording-player) — John expands the reasoning trace accordion ('Show more') to display granular file inspection and hashing steps.\n\n- [05:11:04](https://proud-anchor-53zn.here.now/watch.html?t=18664#recording-player) — John describes using reasoning runs asynchronously for verification passes whenever maximum intelligence is needed.\n\n- [05:11:17](https://proud-anchor-53zn.here.now/watch.html?t=18677#recording-player) — a participant asks if agents gather context first or grill the user before tasks.\n\n- [05:11:20](https://proud-anchor-53zn.here.now/watch.html?t=18680#recording-player) — John highlights ChatGPT Pro subscription benefits including image generation, independent Codex budgets, and voice models.\n\n- [05:11:46](https://proud-anchor-53zn.here.now/watch.html?t=18706#recording-player) — John explains prompting mobile voice models with 'Please load in the context' to continue desktop threads.\n\n- [05:12:11](https://proud-anchor-53zn.here.now/watch.html?t=18731#recording-player) — John discusses Codex subscription usage limit resets and value per dollar.\n\n- [05:12:20](https://proud-anchor-53zn.here.now/watch.html?t=18740#recording-player) — John notes Codex supports OpenClaw and other agent harnesses.\n\n- [05:12:33](https://proud-anchor-53zn.here.now/watch.html?t=18753#recording-player) — John mentions using Codex to back Script Kit AI features.\n\n- [05:12:55](https://proud-anchor-53zn.here.now/watch.html?t=18775#recording-player) — a participant asks in chat: Can you use the codex subscription in pi?\n\n- [05:12:57](https://proud-anchor-53zn.here.now/watch.html?t=18777#recording-player) — John answers context gathering question: brainstorms task first, then hands off to Oracle with packx.\n\n- [05:13:41](https://proud-anchor-53zn.here.now/watch.html?t=18821#recording-player) — John explains packx bundles massive amounts of codebase context for smart model analysis.\n\n- [05:14:00](https://proud-anchor-53zn.here.now/watch.html?t=18840#recording-player) — John answers a participant's question, confirming Codex subscription can be used in Pi.\n\n- [05:14:20](https://proud-anchor-53zn.here.now/watch.html?t=18860#recording-player) — John explains local automated browser agents steal window focus while working.\n\n- [05:14:27](https://proud-anchor-53zn.here.now/watch.html?t=18867#recording-player) — Agenda page shows FOR YOUR AGENT fetch command and THE WHOLE WORKSHOP AS ONE FLOW curl/mdflow command.\n\n- [05:14:37](https://proud-anchor-53zn.here.now/watch.html?t=18877#recording-player) — John describes using a dedicated remote Mac Mini to run background browser agents.\n\n- [05:15:15](https://proud-anchor-53zn.here.now/watch.html?t=18915#recording-player) — John explains using Codex Remote on his phone to trigger remote agent jobs on the Mac Mini.\n\n- [05:17:02](https://proud-anchor-53zn.here.now/watch.html?t=19022#recording-player) — John explains Gemini's native video processing compared to frame extraction models.\n\n- [05:17:36](https://proud-anchor-53zn.here.now/watch.html?t=19056#recording-player) — John discusses Joel Hooks's LoopCraft video and the 4-minute video sharding strategy.\n\n- [05:19:52](https://proud-anchor-53zn.here.now/watch.html?t=19192#recording-player) — John clicks on the 'LOCAL SETUP' header link to display documentation detailing full workspace environments without Docker.\n\n- [05:20:03](https://proud-anchor-53zn.here.now/watch.html?t=19203#recording-player) — John mentions setting up a portion of the screen using CleanShot to record interactions.\n\n- [05:20:39](https://proud-anchor-53zn.here.now/watch.html?t=19239#recording-player) — John explains feeding these screen captures directly into Gemini to parse errors or analyze paragraphs naturally.\n\n- [05:22:25](https://proud-anchor-53zn.here.now/watch.html?t=19345#recording-player) — John Lindquist explains how full video captioning captures unexpected user behavior and cursor data.\n\n- [05:23:08](https://proud-anchor-53zn.here.now/watch.html?t=19388#recording-player) — a participant asks whether a single Mermaid graph can serve both machine context injection and human documentation.\n\n- [05:24:33](https://proud-anchor-53zn.here.now/watch.html?t=19473#recording-player) — John writes a text prompt asking what the model can see on his monitor screen.\n\n- [05:24:45](https://proud-anchor-53zn.here.now/watch.html?t=19485#recording-player) — The Live API outputs structured text describing the active Google AI Studio interface context view.\n\n- [05:25:17](https://proud-anchor-53zn.here.now/watch.html?t=19517#recording-player) — a participant asks if this capability requires an Ultra account tier subscription.\n\n### Demonstration detail: 05:05:43\n\n- Navigated to chatgpt.com\n- Opened the intelligence model selection dropdown\n\n**Tools observed:** ChatGPT Web UI.\n\n### Demonstration detail: 05:08:22\n\n- Switched to references page tab\n- Scrolled down to the AI Context Bundlers comparison table\n\n**Tools observed:** Google Chrome Browser.\n\n### Demonstration detail: 05:08:52\n\n- Navigate ChatGPT sidebar threads\n- Open reasoning session threads\n- Expand reasoning execution trace accordion\n\n**Tools observed:** ChatGPT Pro.\n\n### Demonstration detail: 05:12:11\n\n- Inspect ChatGPT Pro audit report for MiniCode project\n- Click attachments-bundle(133).txt preview drawer to view bundled repository files\n\n**Tools observed:** ChatGPT Pro, Arc Browser.\n\n### Demonstration detail: 05:14:06\n\n- Switch browser tabs to deep-steel-rfbs.here.now to show context bundlers table\n- Switch browser tabs to ember-bodhi-scrs.here.now to show agent setup instructions\n\n**Tools observed:** Arc Browser.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nfetch https://ember-bodhi-scrs.here.now/agent.md --no-machine-readable-agenda\ncurl -s https://ember-bodhi-scrs.here.now/workshop.md?app=-y | npx mdflow --script - --task \"Walk me through the workshop, set a...\"\n```\n\n### Demonstration detail: 05:14:36\n\n- Trigger Raycast launcher with Cmd+Space keyboard shortcut\n- Search for Screen Sharing and launch application\n- Connect to remote Mac Mini machine\n- Display remote desktop running Chrome profile selector\n\n**Tools observed:** Raycast, macOS Screen Sharing, Google Chrome.\n\n### Demonstration detail: 05:16:12\n\n- Navigated to workshop docs\n- Opened Gemini web interface\n- Reviewed video analysis reports for Shard 001 and Shard 004\n\n**Tools observed:** Gemini, Arc Browser.\n\n### Demonstration detail: 05:19:05\n\n- Navigated across the generated workshop video companion companion web app pages.\n- Inspected automated timestamp sections inside the Chapter map.\n- Scrolled down the Glossary documentation framework entries.\n\n**Tools observed:** Chrome Browser.\n\n### Demonstration detail: 05:20:07\n\n- Triggered the CleanShot X operational video screen recording control layer.\n- Executed configuration changes inside the recording wizard interface.\n- Clicked through file save decisions inside the modal overlay dialog window.\n\n**Tools observed:** CleanShot X.\n\n### Demonstration detail: 05:23:25\n\n- Opened AI Studio dashboard\n- Searched for real-time options\n- Configured Gemini 3.1 Flash Live Preview model\n- Shared display screen window feed\n- Submitted text dialog content\n\n**Tools observed:** Google AI Studio Live API Sandbox, Google Chrome."
    },
    {
      "id": "factory-reasoning-and-video-practice",
      "slug": "reasoning-and-video-practice",
      "title": "Independent reasoning and video evidence — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for independent reasoning and video evidence.",
      "category": "Verification",
      "tags": [
        "prompts",
        "exercises",
        "reasoning-and-video"
      ],
      "sources": [
        {
          "label": "Independent reasoning and video evidence",
          "url": "https://shiny-rosette-m6zy.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://shiny-rosette-m6zy.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/index.html#Quick start",
        "08-oracle-video/index.html#Prompt library",
        "08-oracle-video/index.html#Set it up (agent guide)",
        "08-oracle-video/index.html#Attachments — the Oracle skill family",
        "08-oracle-video/index.html#The maximum-batch consult",
        "08-oracle-video/index.html#The sentinel video probe",
        "08-oracle-video/index.html#The shard analysis prompt — Loop Craft, verbatim",
        "08-oracle-video/agent.md"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 2935,
      "url": "/topics/factory-reasoning-and-video-practice/",
      "markdownUrl": "/markdown/factory-reasoning-and-video-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "the-maximum-batch-consult",
          "text": "The maximum-batch consult",
          "level": 3
        },
        {
          "id": "the-sentinel-video-probe",
          "text": "The sentinel video probe",
          "level": 3
        },
        {
          "id": "the-shard-analysis-prompt-loop-craft-verbatim",
          "text": "The shard analysis prompt — Loop Craft, verbatim",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "attachments-the-oracle-skill-family",
          "text": "Attachments — the Oracle skill family",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "oracle-maximum-intelligence-and-video-agent-setup-guide",
          "text": "Oracle: Maximum Intelligence and Video — agent setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        },
        {
          "id": "attachments-the-oracle-skill-family-optional",
          "text": "Attachments — the Oracle skill family (optional)",
          "level": 2
        }
      ],
      "markdown": "# Independent reasoning and video evidence — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for independent reasoning and video evidence.\n\n## Quick start\n\nSign into chatgpt.com in your normal Chrome first — a human does that part, once. Then:\n\n``` text\nnpm install -g @steipete/oracle    # or: brew install steipete/tap/oracle (Node 22+)\noracle --engine browser -p \"HI\"    # first handshake: copies your cookies, sends \"HI\"\noracle status --hours 72           # the reply is recorded as a replayable session\n```\n\n## Prompt library\n\n### The maximum-batch consult\n\n- Agent: oracle CLI → ChatGPT (GPT-5.6 Pro)\n- Working directory: your project root\n- Expected result: ordered work packages with file/function/test targets, 20–60 min later\n\nThis is the pattern behind ~1,978 real consult sessions. Fill the `<angle-bracket>` slots with your project's facts; the last two paragraphs ship verbatim with every consult. Save it as `consult-prompt.md`.\n\n``` text\n[<three-to-five-word-slug>]\n\n## Project briefing\n<stack, framework, runtime, and repo rules — two or three sentences>\n\n## Goal\n<the full outcome you want, stated as the whole contract Oracle must plan\nagainst — never pre-shrunk to a first step>\n\n## Prior-State Ledger\n- prior_oracle_session: none\n- implemented_since_prior_oracle: none\n- verified_since_prior_oracle: none\n- failed_proof_or_blocker: none\n- remaining_goal_coverage: the full goal above\n\n## Current evidence\n<attempts, failing logs, screenshots, and known constraints — or \"none yet\">\n\n## Bundle map\nThe attached files contain <what you included and why>. Possibly missing:\n<what you could not include>.\n\n## Deliverable\nReturn the maximum actionable batch: an ordered set of work packages covering\neverything worth doing toward the goal. Every work package must carry exact\nfile/function/test targets, critical code snippets, and a falsifiable\nverification. Sequence the packages, name risks and invariants, and put\nanything you cannot target exactly in a separate short \"needs investigation\"\nlist.\n\nReturn your answer as text in this response only. Do not create, attach, export,\nor offer any downloadable file. Do not create local project artifacts yourself.\nThe local agent will write any needed files, plans, notes, goals, commits, or\nverification logs using local tools.\n\nPlan the maximum actionable batch: cover everything worth doing toward the\ngoal in ordered work packages with exact file/function/test targets and a\nfalsifiable verification each. Do not return a single next step or hold work\nback for a later round. An ambitious, specific answer is correct; only\nuntargeted vagueness is a defect.\n```\n\nRun it with your code attached:\n\n``` text\noracle --engine browser -p \"$(cat consult-prompt.md)\" \\\n  --file \"src/**/*.ts,docs/**/*.md\" --slug \"<three-to-five-word-slug>\"\n```\n\n### The sentinel video probe\n\n- Agent: oracle CLI → Gemini\n- Working directory: anywhere, with a short MP4 on disk\n- Expected result: three bullets plus the exact sentinel line, byte-for-byte\n\nBefore any expensive video run, prove the upload path with a cheap probe. Save this as `probe-prompt.md`:\n\n``` text\n[video-upload-smoke-probe]\n\nThis is an attached-video readiness probe for a longer video analysis run.\n\nConfirm that you can inspect the attached video. Return exactly three short bullets:\n- whether video frames are visible;\n- whether audio is detectable;\n- one strictly observed visual detail, without guessing.\n\nEnd with this exact sentinel on its own line:\nEND_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe\n```\n\n``` text\noracle --engine browser --model gemini-3-pro --browser-attachments always \\\n  -p \"$(cat probe-prompt.md)\" --file \"/absolute/path/to/probe-clip.mp4\" \\\n  --slug \"video-upload-smoke-probe\"\n```\n\nThe pass rule: the sentinel comes back byte-exact and the observed detail matches your footage. A paraphrase, extra prose, or silence means the path is broken — fix it before the long run, not after.\n\n### The shard analysis prompt — Loop Craft, verbatim\n\n- Agent: oracle CLI → Gemini\n- Working directory: a video run folder with a ≤4-minute shard\n- Expected result: dense Markdown + machine JSON, ending in the exact sentinel\n\nThis exact prompt produced shard 001 of the [Loop Craft wiki](https://silken-ferry-63mw.here.now/). Swap the metadata block and the sentinel for your own run; keep the evidence rules — they are what stop Gemini from inventing URLs, commands, and speakers.\n\n``` text\n[loopcraft-workshop-shard-001-source-native]\n\nAnalyze the attached source-native video shard for an extensive public workshop wiki.\n\nMetadata:\n- run_key: loopcraft-agent-workshop\n- shard_id: 001\n- original recording range: 00:00:00–00:04:00\n- publication chapter: Workshop Setup and the Looping Resolver\n\nEvidence rules:\n1. Use original workshop timestamps from 00:00:00 through 00:04:00.\n2. Separate spoken evidence, visible screen evidence, and inference.\n3. Listen to the audio; do not rely on automatic captions.\n4. Do not invent commands, URLs, files, tools, speakers, or UI labels.\n5. Pull quotes must be brief (under 20 words), audio-verified, attributed to Joel Hooks, and timestamped.\n6. Exclude credentials, account details, local paths/usernames, private URLs, signed URLs, notifications, or incidental personal data.\n7. Treat opinions and live-demo observations as such, not universal facts.\n8. Derived prompts must use placeholders, be clearly labeled as inspired by the workshop, and require confirmation for destructive or externally visible actions.\n\nReturn dense Markdown with these sections:\n# Shard 001 — 00:00:00–00:04:00\n## Executive Takeaway\n## Dense Timeline\n## Concepts and Mental Models\n## Visible Demo Evidence\n## Architecture and Workflow Patterns\n## Tools, Commands, and References\n## Pull Quote Candidates\n## Copy/Paste AI Prompt Candidates\n## Student Exercises and Reflection Questions\n## Keyframes to Capture\n## Uncertainties and Publication Review\n## Machine JSON\n\nThe fenced JSON object must contain: shard_id, original_range, summary, timeline, concepts, workflows, demos, resources, quotes, prompts, exercises, keyframes, warnings, unanswered_questions.\n\nEnd with this exact sentinel on its own line:\nEND_OF_VIDEO_ANALYSIS loopcraft-agent-workshop shard-001\n```\n\n## Set it up (agent guide)\n\n1.  Check prerequisites: Node 22+ and Google Chrome installed.\n\n    ``` text\n    node --version   # need v22 or newer; Chrome must also be installed\n    ```\n\n2.  Install the Oracle CLI.\n\n    ``` text\n    npm install -g @steipete/oracle\n    oracle --version\n    ```\n\n3.  Sign into chatgpt.com in your normal Chrome. **A human does this step** — an agent cannot log in for you. Oracle borrows the session cookies from that logged-in profile.\n\n4.  Run the first handshake. Oracle copies your cookies into a temporary automation profile, opens ChatGPT, and sends the prompt.\n\n    ``` text\n    oracle --engine browser -p \"HI\"\n    ```\n\n5.  Create your first real consult. Save this file and replace every `<angle-bracket>` slot with facts from your project:\n\n    ``` text\n    [<three-to-five-word-slug>]\n\n    ## Project briefing\n    <stack, framework, runtime, and repo rules — two or three sentences>\n\n    ## Goal\n    <the full outcome you want, stated as the whole contract Oracle must plan\n    against — never pre-shrunk to a first step>\n\n    ## Prior-State Ledger\n    - prior_oracle_session: none\n    - implemented_since_prior_oracle: none\n    - verified_since_prior_oracle: none\n    - failed_proof_or_blocker: none\n    - remaining_goal_coverage: the full goal above\n\n    ## Current evidence\n    <attempts, failing logs, screenshots, and known constraints — or \"none yet\">\n\n    ## Bundle map\n    The attached files contain <what you included and why>. Possibly missing:\n    <what you could not include>.\n\n    ## Deliverable\n    Return the maximum actionable batch: an ordered set of work packages covering\n    everything worth doing toward the goal. Every work package must carry exact\n    file/function/test targets, critical code snippets, and a falsifiable\n    verification. Sequence the packages, name risks and invariants, and put\n    anything you cannot target exactly in a separate short \"needs investigation\"\n    list.\n\n    Return your answer as text in this response only. Do not create, attach, export,\n    or offer any downloadable file. Do not create local project artifacts yourself.\n    The local agent will write any needed files, plans, notes, goals, commits, or\n    verification logs using local tools.\n\n    Plan the maximum actionable batch: cover everything worth doing toward the\n    goal in ordered work packages with exact file/function/test targets and a\n    falsifiable verification each. Do not return a single next step or hold work\n    back for a later round. An ambitious, specific answer is correct; only\n    untargeted vagueness is a defect.\n    ```\n\n6.  Run the consult with your code attached. A GPT-5.6 Pro consult takes 20–60 minutes of wall clock — wait for it; the session log is the durable record.\n\n    ``` text\n    oracle --engine browser -p \"$(cat consult-prompt.md)\" \\\n      --file \"src/**/*.ts\" --slug \"<three-to-five-word-slug>\"\n    ```\n\n**Success check:** a response was received and recorded. The handshake and your consult both appear as sessions:\n\n``` text\noracle status --hours 24\n```\n\nThe session browser should report the completed model run; inspect the returned artifact rather than trusting a short status alone.\n\n## Attachments — the Oracle skill family\n\nThese are the presenter's real skill files, verbatim — the same six skills that drive everything on this page: `oracle` (the maximum-batch consult contract, plus its packx references and round-robin scripts), `oracle-execute` (Oracle-planned execution loops), `oracle-schedule` (one scheduled future consult), `oracle-video` (the Gemini video pipeline, with its repeatable follow-up process), `oracle-video-create` (Gemini video generation), and `imagine` (ChatGPT image generation).\n\nThey orchestrate Oracle's browser engine plus packx and assume the presenter's accounts and setup — the round-robin pieces are pinned to one private pool you don't have. Install them to **study and adapt to your own accounts**, not to run unmodified. One block downloads all six into a staging folder and installs them into the current project. Two verified gotchas baked in: `.md` files must be fetched with `?raw` (the bare URL returns an HTML viewer page), and the staging folder must *not* be named `skills/` — the installer claims `./skills/` as one of its own targets and would clobber your downloads with empty symlinks.\n\n``` text\nBASE=https://shiny-rosette-m6zy.here.now/skills\nD=oracle-skill-family\nmkdir -p $D/oracle/references $D/oracle/scripts $D/oracle-execute \\\n  $D/oracle-schedule/agents $D/oracle-video/references \\\n  $D/oracle-video-create $D/imagine/agents\ncurl -fsS \"$BASE/oracle/SKILL.md?raw\" -o $D/oracle/SKILL.md\ncurl -fsS \"$BASE/oracle/references/round-robin-receipt.md?raw\" -o $D/oracle/references/round-robin-receipt.md\ncurl -fsS \"$BASE/oracle/references/round-robin-transport.md?raw\" -o $D/oracle/references/round-robin-transport.md\ncurl -fsS \"$BASE/oracle/references/packx-quick-reference.md?raw\" -o $D/oracle/references/packx-quick-reference.md\ncurl -fsS \"$BASE/oracle/references/packx-deep-reference.md?raw\" -o $D/oracle/references/packx-deep-reference.md\ncurl -fsS \"$BASE/oracle/scripts/extract_codex_conversation.py\" -o $D/oracle/scripts/extract_codex_conversation.py\ncurl -fsS \"$BASE/oracle/scripts/run_round_robin.sh\" -o $D/oracle/scripts/run_round_robin.sh\ncurl -fsS \"$BASE/oracle-execute/SKILL.md?raw\" -o $D/oracle-execute/SKILL.md\ncurl -fsS \"$BASE/oracle-schedule/SKILL.md?raw\" -o $D/oracle-schedule/SKILL.md\ncurl -fsS \"$BASE/oracle-schedule/agents/openai.yaml\" -o $D/oracle-schedule/agents/openai.yaml\ncurl -fsS \"$BASE/oracle-video/SKILL.md?raw\" -o $D/oracle-video/SKILL.md\ncurl -fsS \"$BASE/oracle-video/references/repeatable-video-followup-process.md?raw\" -o $D/oracle-video/references/repeatable-video-followup-process.md\ncurl -fsS \"$BASE/oracle-video-create/SKILL.md?raw\" -o $D/oracle-video-create/SKILL.md\ncurl -fsS \"$BASE/imagine/SKILL.md?raw\" -o $D/imagine/SKILL.md\ncurl -fsS \"$BASE/imagine/agents/openai.yaml\" -o $D/imagine/agents/openai.yaml\nchmod +x $D/oracle/scripts/extract_codex_conversation.py $D/oracle/scripts/run_round_robin.sh\nnpx skills add ./$D --skill '*' -y\n```\n\nTo install just one skill instead of all six, change the last line — for example `npx skills add ./oracle-skill-family --skill oracle -y`.\n\n## Complete reusable setup contract\n\n## Oracle: Maximum Intelligence and Video — agent setup guide\n\nFollowing this file sets up: a local Oracle CLI that drives ChatGPT through your user's logged-in Chrome browser (no API keys) and runs a first maximum-batch consult against the current project.\n\nHuman-facing companions at this site (context for your user, not steps for you): https://shiny-rosette-m6zy.here.now/replay.html is an annotated session replay of the real video-analysis run this workflow comes from, and https://shiny-rosette-m6zy.here.now/dialogue.html answers the common skeptical questions. This file remains the canonical executable path. The presenter's six real Oracle skill files are also attached at this site — see \"Attachments\" at the bottom of this file for the download URLs and install block.\n\nPlaceholders used below: `<project-root>` = the project you are working in; `<three-to-five-word-slug>` = a slug you choose, 3–5 hyphenated words (Oracle rejects anything outside that range). All other paths are literal.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nnode --version\n```\n\nExpected: `v22` or newer. Google Chrome must also be installed, and your user needs a ChatGPT account. If a tool is missing, stop and tell your user what to install.\n\n## Steps\n\n1. Install the Oracle CLI globally and confirm it runs:\n\n   ```bash\n   npm install -g @steipete/oracle\n   oracle --version\n   ```\n\n2. Ask your user to sign into chatgpt.com in their normal Chrome profile. **A human must do this step — you cannot log in for them.** Oracle copies the session cookies from that logged-in profile into a temporary automation profile; the login is the entire auth setup. Wait for your user to confirm they are signed in before continuing.\n\n3. Run the first browser handshake. This copies the cookies, opens ChatGPT in an automated Chrome, and sends the prompt:\n\n   ```bash\n   oracle --engine browser -p \"HI\"\n   ```\n\n   A reply coming back (any reply) proves the cookie path works.\n\n4. Create `<project-root>/consult-prompt.md` with exactly this content, then replace every `<angle-bracket>` slot with real facts from the current project (read the code first — the briefing, goal, and bundle map must be true, not generic). Keep the final two paragraphs verbatim; they are the contract that makes the consult worth its cost:\n\n   ```markdown\n   [<three-to-five-word-slug>]\n\n   ## Project briefing\n   <stack, framework, runtime, and repo rules — two or three sentences>\n\n   ## Goal\n   <the full outcome you want, stated as the whole contract Oracle must plan\n   against — never pre-shrunk to a first step>\n\n   ## Prior-State Ledger\n   - prior_oracle_session: none\n   - implemented_since_prior_oracle: none\n   - verified_since_prior_oracle: none\n   - failed_proof_or_blocker: none\n   - remaining_goal_coverage: the full goal above\n\n   ## Current evidence\n   <attempts, failing logs, screenshots, and known constraints — or \"none yet\">\n\n   ## Bundle map\n   The attached files contain <what you included and why>. Possibly missing:\n   <what you could not include>.\n\n   ## Deliverable\n   Return the maximum actionable batch: an ordered set of work packages covering\n   everything worth doing toward the goal. Every work package must carry exact\n   file/function/test targets, critical code snippets, and a falsifiable\n   verification. Sequence the packages, name risks and invariants, and put\n   anything you cannot target exactly in a separate short \"needs investigation\"\n   list.\n\n   Return your answer as text in this response only. Do not create, attach, export,\n   or offer any downloadable file. Do not create local project artifacts yourself.\n   The local agent will write any needed files, plans, notes, goals, commits, or\n   verification logs using local tools.\n\n   Plan the maximum actionable batch: cover everything worth doing toward the\n   goal in ordered work packages with exact file/function/test targets and a\n   falsifiable verification each. Do not return a single next step or hold work\n   back for a later round. An ambitious, specific answer is correct; only\n   untargeted vagueness is a defect.\n   ```\n\n5. Run the consult from `<project-root>`, attaching the relevant source files (adjust the glob to the project's language):\n\n   ```bash\n   oracle --engine browser -p \"$(cat consult-prompt.md)\" \\\n     --file \"src/**/*.ts\" --slug \"<three-to-five-word-slug>\"\n   ```\n\n   A GPT-5.6 Pro consult takes 20–60 minutes of wall clock. Wait for it. Do not assume it timed out based on elapsed time alone — check the session (step 6) instead of restarting.\n\n## Success check\n\nSuccess = a response was received. Run:\n\n```bash\noracle status --hours 24\n```\n\nExpected observable result: a \"Recent Sessions\" table listing your handshake and your consult slug with Status `completed`, Model `gpt-5.6-pro` (the handshake may show a different model), Mode `browser`, and a non-zero Chars count. Read the full response with:\n\n```bash\noracle session \"<three-to-five-word-slug>\" --render\n```\n\nReport to your user: that Oracle is installed and cookie-authenticated, the consult slug, the success-check output, and a summary of the work packages Oracle returned — every package, not a trimmed selection.\n\n## Notes for agents\n\n- `Missing OPENAI_API_KEY` means the call fell into API mode. That is a caller bug, not a missing credential — retry with `--engine browser`.\n- `Inspected target navigated or closed` mid-run: retry with `--browser-auto-reattach-delay 5s --browser-auto-reattach-interval 3s --browser-auto-reattach-timeout 60s`.\n- If the handshake fails, the most likely cause is that the user is not actually signed into chatgpt.com in their normal Chrome. Ask them to check before debugging anything else.\n- Browser automation is experimental and most stable on macOS. On Linux, pass `--browser-chrome-path` / `--browser-cookie-path` if Chrome detection fails.\n- The CLI's terminal output can truncate long answers. The authoritative record is the session log at `~/.oracle/sessions/<slug>/output.log`, also readable via `oracle session <slug> --render`.\n- Remote option (note only — do not set this up unless your user asks): an always-on machine can run `oracle serve` with its own signed-in Chrome, and clients point at it by setting the remote host and token in `~/.oracle/config.json`. The cookies then live once, on that host, for every client. Local mode is the right default.\n- Video analysis uses the same CLI with `--model gemini-3-pro --browser-attachments always` and a Gemini login in Chrome, and every expensive run should be preceded by a cheap sentinel probe. The prompt library at https://shiny-rosette-m6zy.here.now/ has the liftable probe prompt/command pair.\n\n## Attachments — the Oracle skill family (optional)\n\nThe presenter's six real skill files are published verbatim under `https://shiny-rosette-m6zy.here.now/skills/`. They orchestrate Oracle's browser engine plus packx and assume the presenter's accounts and setup (the round-robin pieces are pinned to a private pool you don't have) — install them to study and adapt, not to run unmodified. Only do this if your user asks for the skills.\n\nhere.now gotcha: `.md` files must be fetched with `?raw` (the bare `.md` URL returns an HTML viewer page). The raw file URLs:\n\n- https://shiny-rosette-m6zy.here.now/skills/oracle/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-receipt.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle/references/round-robin-transport.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-quick-reference.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle/scripts/extract_codex_conversation.py\n- https://shiny-rosette-m6zy.here.now/skills/oracle/scripts/run_round_robin.sh\n- https://shiny-rosette-m6zy.here.now/skills/oracle-execute/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle-schedule/agents/openai.yaml\n- https://shiny-rosette-m6zy.here.now/skills/oracle-video/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/oracle-video-create/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/imagine/SKILL.md?raw\n- https://shiny-rosette-m6zy.here.now/skills/imagine/agents/openai.yaml\n\nSecond verified gotcha: stage the downloads in a folder that is NOT named `skills/`. The `npx skills add` installer claims `./skills/` as one of its own install targets (OpenClaw) and will replace your staged source with empty symlinks, installing nothing. Download all six into `./oracle-skill-family/` and install them into the current project:\n\n```bash\nBASE=https://shiny-rosette-m6zy.here.now/skills\nD=oracle-skill-family\nmkdir -p $D/oracle/references $D/oracle/scripts $D/oracle-execute \\\n  $D/oracle-schedule/agents $D/oracle-video/references \\\n  $D/oracle-video-create $D/imagine/agents\ncurl -fsS \"$BASE/oracle/SKILL.md?raw\" -o $D/oracle/SKILL.md\ncurl -fsS \"$BASE/oracle/references/round-robin-receipt.md?raw\" -o $D/oracle/references/round-robin-receipt.md\ncurl -fsS \"$BASE/oracle/references/round-robin-transport.md?raw\" -o $D/oracle/references/round-robin-transport.md\ncurl -fsS \"$BASE/oracle/references/packx-quick-reference.md?raw\" -o $D/oracle/references/packx-quick-reference.md\ncurl -fsS \"$BASE/oracle/references/packx-deep-reference.md?raw\" -o $D/oracle/references/packx-deep-reference.md\ncurl -fsS \"$BASE/oracle/scripts/extract_codex_conversation.py\" -o $D/oracle/scripts/extract_codex_conversation.py\ncurl -fsS \"$BASE/oracle/scripts/run_round_robin.sh\" -o $D/oracle/scripts/run_round_robin.sh\ncurl -fsS \"$BASE/oracle-execute/SKILL.md?raw\" -o $D/oracle-execute/SKILL.md\ncurl -fsS \"$BASE/oracle-schedule/SKILL.md?raw\" -o $D/oracle-schedule/SKILL.md\ncurl -fsS \"$BASE/oracle-schedule/agents/openai.yaml\" -o $D/oracle-schedule/agents/openai.yaml\ncurl -fsS \"$BASE/oracle-video/SKILL.md?raw\" -o $D/oracle-video/SKILL.md\ncurl -fsS \"$BASE/oracle-video/references/repeatable-video-followup-process.md?raw\" -o $D/oracle-video/references/repeatable-video-followup-process.md\ncurl -fsS \"$BASE/oracle-video-create/SKILL.md?raw\" -o $D/oracle-video-create/SKILL.md\ncurl -fsS \"$BASE/imagine/SKILL.md?raw\" -o $D/imagine/SKILL.md\ncurl -fsS \"$BASE/imagine/agents/openai.yaml\" -o $D/imagine/agents/openai.yaml\nchmod +x $D/oracle/scripts/extract_codex_conversation.py $D/oracle/scripts/run_round_robin.sh\nnpx skills add ./$D --skill '*' -y\n```\n\nTo install a single skill instead of all six, change the last line, e.g. `npx skills add ./oracle-skill-family --skill oracle -y`. After installing, verify: `.agents/skills/<name>/` in the project must contain every downloaded file (multi-file skills keep their `references/` and `scripts/` subfolders)."
    },
    {
      "id": "factory-reasoning-and-video-questions",
      "slug": "reasoning-and-video-questions",
      "title": "Independent reasoning and video evidence — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Verification",
      "tags": [
        "reasoning-and-video",
        "questions"
      ],
      "sources": [
        {
          "label": "Independent reasoning and video evidence — questions and tradeoffs",
          "url": "https://shiny-rosette-m6zy.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/dialogue.html#The premise",
        "08-oracle-video/dialogue.html#The economics",
        "08-oracle-video/dialogue.html#The video claim",
        "08-oracle-video/dialogue.html#The setup"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1159,
      "url": "/topics/factory-reasoning-and-video-questions/",
      "markdownUrl": "/markdown/factory-reasoning-and-video-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video-questions.json",
      "headings": [
        {
          "id": "the-premise",
          "text": "The premise",
          "level": 2
        },
        {
          "id": "the-economics",
          "text": "The economics",
          "level": 2
        },
        {
          "id": "the-video-claim",
          "text": "The video claim",
          "level": 2
        },
        {
          "id": "the-setup",
          "text": "The setup",
          "level": 2
        }
      ],
      "markdown": "# Independent reasoning and video evidence — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The premise\n\nIsn’t maximum intelligence just an API call away? Why all this browser theater?\n\nIt isn’t. ChatGPT’s strongest tier — the model picker’s “Latest” row, currently GPT-5.6 Pro with Extended thinking — is a subscription feature of the chat product, not the API. And Gemini’s video understanding is only reachable through the page’s own upload widget. The strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key — and after one human login, the whole setup is this:\n\n``` text\nnpm install -g @steipete/oracle    # or: brew install steipete/tap/oracle (Node 22+)\noracle --engine browser -p \"HI\"    # first handshake: copies your cookies, sends \"HI\"\noracle status --hours 72           # the reply is recorded as a replayable session\n```\n\nHold on — cookies? How does an agent log into ChatGPT?\n\nIt doesn’t. You do, once, in your normal Chrome. Oracle copies those session cookies into a temporary automation profile and then drives that profile like a very fast reader — same model picker, same upload widget a human sees:\n\n``` text\nyou (human) ──sign in once──▶ Chrome profile (chatgpt.com cookies)\n                                     │  cookies copied per run\nagent ──▶ oracle CLI ──▶ automation Chrome profile ──▶ chatgpt.com ──▶ GPT-5.6 Pro\n                │\n                └─ packx bundle (up to ~900k tokens of code) pasted/attached\n```\n\nAn API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything your subscription gives you.\n\n## The economics\n\nA consult takes 20–60 minutes. Isn’t that unusable?\n\nUnusable if you spend it like a chat message. “What’s the next change?” is a banned prompt shape — it spends an hour of frontier thinking on minutes of work. The contract is: every consult demands the **maximum actionable batch** — ordered work packages with exact file/function/test targets and a falsifiable verification each. This is the prompt behind ~1,978 real sessions, verbatim:\n\n``` text\n[<three-to-five-word-slug>]\n\n## Project briefing\n<stack, framework, runtime, and repo rules — two or three sentences>\n\n## Goal\n<the full outcome you want, stated as the whole contract Oracle must plan\nagainst — never pre-shrunk to a first step>\n\n## Prior-State Ledger\n- prior_oracle_session: none\n- implemented_since_prior_oracle: none\n- verified_since_prior_oracle: none\n- failed_proof_or_blocker: none\n- remaining_goal_coverage: the full goal above\n\n## Current evidence\n<attempts, failing logs, screenshots, and known constraints — or \"none yet\">\n\n## Bundle map\nThe attached files contain <what you included and why>. Possibly missing:\n<what you could not include>.\n\n## Deliverable\nReturn the maximum actionable batch: an ordered set of work packages covering\neverything worth doing toward the goal. Every work package must carry exact\nfile/function/test targets, critical code snippets, and a falsifiable\nverification. Sequence the packages, name risks and invariants, and put\nanything you cannot target exactly in a separate short \"needs investigation\"\nlist.\n\nReturn your answer as text in this response only. Do not create, attach, export,\nor offer any downloadable file. Do not create local project artifacts yourself.\nThe local agent will write any needed files, plans, notes, goals, commits, or\nverification logs using local tools.\n\nPlan the maximum actionable batch: cover everything worth doing toward the\ngoal in ordered work packages with exact file/function/test targets and a\nfalsifiable verification each. Do not return a single next step or hold work\nback for a later round. An ambitious, specific answer is correct; only\nuntargeted vagueness is a defect.\n```\n\n``` text\noracle --engine browser -p \"$(cat consult-prompt.md)\" \\\n  --file \"src/**/*.ts,docs/**/*.md\" --slug \"<three-to-five-word-slug>\"\n```\n\nBe honest — do you actually use this, or is it a demo trick?\n\nThe local archive held about 1,978 session folders in the observed snapshot, and it grows daily. A sample of what they ask:\n\nThe recurring consult shapes are repeated hardening audits, independent multi-angle review followed by a judge, forensic debugging, redesign planning, and planning a media-analysis pipeline before executing it.\n\nThe recurring shapes: iteration audits where a fresh frontier reviewer re-reads the codebase every loop, multi-angle panels where a judge consult picks the winner, and pipeline-planning-the-pipeline. Every session leaves `output.log` and token receipts, replayable with `oracle session <id> --render`.\n\n## The video claim\n\nVideo? Text models can’t watch video.\n\nRight — and neither can an API text pipeline. Gemini watches footage, but only through the page’s upload widget, which is exactly what Oracle’s browser hands can operate. Before any expensive run, you prove the upload path with a cheap sentinel probe:\n\n``` text\n[video-upload-smoke-probe]\n\nThis is an attached-video readiness probe for a longer video analysis run.\n\nConfirm that you can inspect the attached video. Return exactly three short bullets:\n- whether video frames are visible;\n- whether audio is detectable;\n- one strictly observed visual detail, without guessing.\n\nEnd with this exact sentinel on its own line:\nEND_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe\n```\n\n``` text\noracle --engine browser --model gemini-3-pro --browser-attachments always \\\n  -p \"$(cat probe-prompt.md)\" --file \"/absolute/path/to/probe-clip.mp4\" \\\n  --slug \"video-upload-smoke-probe\"\n```\n\nPass rule: the sentinel comes back byte-exact and the observed detail matches your footage. In the real Loop Craft run, Gemini heard “we are going to talk about Loopcraft…” and identified the presenter’s picture-in-picture at the 00:30 mark — that is watching, not transcript-summarizing. The result is public: a 93-minute workshop became the [Loop Craft wiki](https://silken-ferry-63mw.here.now/).\n\nBrowser automation is the most fragile thing in computing. Why build on it?\n\nIt is fragile — UI drift, model pickers, upload races. The discipline is what turns it into infrastructure: probes before spends, exact sentinels, receipts for every session. In the Loop Craft run, two probe failures cost seconds each; shard 004 failed twice while its siblings passed, which pointed at the input, and an exact re-encode fixed it in one try — 73 seconds to a completed analysis ending in the exact sentinel. Classify the failure, change one variable, re-run the cheap proof, keep the fix. The whole run is replayed beat by beat in the [session replay](https://shiny-rosette-m6zy.here.now/replay.html).\n\n## The setup\n\nDo I need your Mac mini and a four-slot browser pool?\n\nNo. The laptop version is the whole setup: sign into ChatGPT in Chrome, run the handshake, done. The Mac mini is the same trick made multi-tenant — an always-on machine runs `oracle serve` with the signed-in Chrome, every other machine points at it over a private network, and a four-slot dual-account pool runs four hour-long consults at once while nobody’s laptop stays open. Start local; scale only when consults start queuing. To get the local version working right now, hand this to your own agent:\n\n``` text\nFetch https://shiny-rosette-m6zy.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\nAnd if you want the actual skills that orchestrate all of this, the full skill family is [attached on the index](https://shiny-rosette-m6zy.here.now/index.html#attachments-the-oracle-skill-family) — download, install, adapt."
    },
    {
      "id": "factory-reasoning-and-video-reference-patterns",
      "slug": "reasoning-and-video-reference-patterns",
      "title": "Independent reasoning and video evidence — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Verification",
      "tags": [
        "reasoning-and-video",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://shiny-rosette-m6zy.here.now/"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/folio/index.html#Abstract",
        "08-oracle-video/folio/index.html#Notice where the strongest models actually live",
        "08-oracle-video/folio/index.html#Explain how an agent borrows your browser",
        "08-oracle-video/folio/index.html#Compare the laptop setup with an always-on pool",
        "08-oracle-video/folio/index.html#Choose prompts that repay an hour of thinking",
        "08-oracle-video/folio/index.html#Test fragile paths with sentinel probes before spending",
        "08-oracle-video/folio/index.html#Adjust when a run fails instead of abandoning it",
        "08-oracle-video/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 2112,
      "url": "/topics/factory-reasoning-and-video-reference-patterns/",
      "markdownUrl": "/markdown/factory-reasoning-and-video-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-where-the-strongest-models-actually-live",
          "text": "Notice where the strongest models actually live",
          "level": 2
        },
        {
          "id": "explain-how-an-agent-borrows-your-browser",
          "text": "Explain how an agent borrows your browser",
          "level": 2
        },
        {
          "id": "compare-the-laptop-setup-with-an-always-on-pool",
          "text": "Compare the laptop setup with an always-on pool",
          "level": 2
        },
        {
          "id": "choose-prompts-that-repay-an-hour-of-thinking",
          "text": "Choose prompts that repay an hour of thinking",
          "level": 2
        },
        {
          "id": "test-fragile-paths-with-sentinel-probes-before-spending",
          "text": "Test fragile paths with sentinel probes before spending",
          "level": 2
        },
        {
          "id": "adjust-when-a-run-fails-instead-of-abandoning-it",
          "text": "Adjust when a run fails instead of abandoning it",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Independent reasoning and video evidence — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nThe strongest reasoning models in this pipeline sit behind chat subscriptions, not APIs. The Oracle tool answers that constraint directly: it drives a real Chrome browser into chatgpt.com and gemini.google.com, authenticated by cookies copied from a profile a human already logged into. This document shows how that works locally in one command, how one operator scales it to an always-on remote pool, why consult prompts must demand a maximum batch of work, and how cheap sentinel probes make fragile video uploads dependable. The evidence is one operator's local records from May–the recorded workflow — about 1,978 consult sessions plus a fully receipted video run. The sources support no claims about cost curves, provider terms, or other people's setups.\n\n## Notice where the strongest models actually live\n\nBefore you design an agent's \"phone a smarter friend\" move, check where that friend answers the phone. The easy assumption is an API call. The record here says otherwise.\n\nThe Oracle fork's README (S1) states that browser mode targets ChatGPT's latest Pro tier by selecting the model picker's \"Latest\" row — currently Pro 5.5 with Extended thinking — with no API key involved. [1](https://shiny-rosette-m6zy.here.now/#note-1)\n\n1\\. S1 also lists an API mode with explicit model IDs. But the consult contract (S2) forbids it for this pipeline: every consult must run with the browser engine, and an API-key error means the caller made a mistake, not that a credential is missing. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-1)\n\nThe video side is stricter. The oracle-video contract (S4) requires Gemini through the browser engine because the file upload happens in the page itself — the API path cannot upload the browser video at all.\n\nSo the mistake to avoid is treating \"maximum intelligence\" as an API shopping question. In this record it is an access question: the strongest text model and the only real video-watching path both sit behind logged-in chat sessions. Whoever holds a valid session cookie holds the key.\n\n**Evidence limit** The sources describe capability and access, not permission. They do not discuss provider terms of service or account risk, so this document cannot tell you whether the trade-off is acceptable for your accounts.\n\n## Explain how an agent borrows your browser\n\nYou should be able to say the whole mechanism in one breath, because your audience will ask. Here it is: a human signs into ChatGPT in normal Chrome once; Oracle copies those session cookies into a temporary automation profile; the agent then drives that profile like a very fast reader who pastes a huge bundle of code and waits.\n\nPer S1, first-time setup is a single command run after the human login, and later runs re-read cookies from the logged-in profile each time.\n\n``` text\n# 1. Sign into ChatGPT in your normal Chrome profile (human, once).\n# 2. Let Oracle copy those cookies into its automation profile:\noracle --engine browser -p \"HI\"\n```\n\nSource: the fork README's macOS browser-mode setup (S1), quoted command verbatim.\n\nWhat rides along with the cookies is context: the consult skill (S2) bundles project files with a packer and currently validates browser-mode bundles up to roughly 900k tokens. [2](https://shiny-rosette-m6zy.here.now/#note-2)\n\n2\\. S2 phrases this as a target: \"Current validated browser-mode bundle target: up to ~900k tokens,\" with a config knob for files over 10 MiB. The point for a demo audience: this is whole-project context, not a snippet. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-2)\n\nThe contrast that makes this click: an API integration authenticates as a program and gets program-shaped limits. A cookie-borrowing browser authenticates as *you* and gets everything the chat product gives you — the model picker, extended thinking modes, and the file-upload widget that the video pipeline depends on.\n\n**Evidence limit** S1 calls browser automation experimental and stable mainly on macOS. Treat \"one command and it works\" as the happy path, not a reliability claim; the probe discipline in the later sections exists precisely because this path breaks.\n\n## Compare the laptop setup with an always-on pool\n\nDecide which of two shapes you need before you copy anything from this record. Most people need the first one.\n\n**Shape one — local:** Oracle runs on your own machine and borrows your own Chrome cookies (S1). Setup is the login handshake above. This is the shape the fork README documents for everyone.\n\n**Shape two — remote service:** S1 documents an `oracle serve` mode: a signed-in host exposes its browser to remote clients. In this operator's config (S5), every machine points at an always-on Mac mini over a private tailnet; the cookies live once, on that host.\n\n``` text\nlaptop agent ─▶ oracle CLI ─▶ config: remote host + token\n                                      │  (private network)\n                                      ▼\n                    Mac mini: `oracle serve` + signed-in Chrome\n                    (cookies live HERE, once, for every client)\n```\n\n**Figure 1.** Derived display: the remote topology, redrawn from the operator's config structure (S5) and the README's remote-service description (S1). Host addresses and the token are deliberately replaced with placeholders.\n\nText consults go one step further: the skill's default transport (S3) is a qualified four-slot pool — two ChatGPT accounts, each with two isolated Chrome workers, so four consults run concurrently without sharing a browser profile. [3](https://shiny-rosette-m6zy.here.now/#note-3)\n\n3\\. S3 pins the whole topology — build hashes, ports, tokens — and verifies it before every run, with a FIFO queue where only the oldest waiter probes for a free slot. Those pinned values are private and are not reproduced here. [↩](https://shiny-rosette-m6zy.here.now/#note-ref-3)\n\nThe decision rule the contrast supports: stay local until concurrency or an always-on machine is the actual bottleneck. The pool's value is not speed of one consult — it is running four twenty-to-sixty-minute consults at once while nobody's laptop stays open.\n\n**Evidence limit** The pool is qualified against one exact build and topology (S3). The sources give no evidence it transfers to other machines or accounts without redoing that qualification.\n\n## Choose prompts that repay an hour of thinking\n\nA consult costs 20–60 minutes of wall clock (S2). The likely mistake is spending that hour the way you'd spend a chat message: \"what should I do next?\" The contract bans exactly that.\n\nS2's operating principle: every prompt must push toward \"the maximum actionable batch\" — an ordered set of work packages with exact file, function, and test targets, each carrying a falsifiable verification. Asking for \"one next shippable slice\" is named as a wasted consult.\n\nWhat does an archive shaped by that rule look like? In the observed snapshot the sessions directory held about 1,978 consult folders (S5). Table 1 samples real prompt previews.\n\n| Session | What it asked Oracle to do |\n|----|----|\n| `actions-parent-lifecycle-third` | Review iteration 3 of a 12-iteration hardening audit of a Rust/GPUI app |\n| `agent-chat-angle-one/-two/-three` | Verify one commit from three independent angles, in parallel |\n| `agent-chat-final-review` | Judge the three angle-consults against each other and pick the solution |\n| `actions-popup-scrollbar-fix` | Forensic hunt for a scrollbar bug from a user report |\n| `agenda-fresh-redesign` | Produce a full redesign plan for a slide-generating repo |\n| `loopcraft-segmentation-review` | Design the video-sharding strategy that the next section executes |\n\n**Table 1.** Derived display: sampled session slugs and paraphrased prompt previews from the local session archive (S5). Paths shortened; selection is editorial, not random.\n\nReplayability comes with the archive: S1 documents `oracle status`, `oracle session <id> --render`, and `oracle restart <id>`, and each session folder stores the model's full output log (S5).\n\nYour practice, next time you draft a consult: read your prompt and ask whether the answer could keep a local agent busy for hours. If it could be answered in one paragraph, you wrote a chat message, not a consult. Rewrite it to demand the whole ordered batch — targets, snippets, and a verification per package.\n\n**Evidence limit** The session count and samples show scale and shape of use. The sources contain no measured comparison of consult quality against cheaper prompting, so \"repays the hour\" is the contract's premise, not a measured result.\n\n## Test fragile paths with sentinel probes before spending\n\nVideo is where the browser trick earns its keep — and where it is most fragile. Uploads race, model pickers drift, fresh chats initialize slowly. The Loop Craft run (S6) shows the discipline that makes this survivable: never start an expensive analysis on a path you have not just proven with a cheap probe.\n\nThe run's goal, from the original session (S6): take a public 93:49 YouTube workshop about the \"Loopcraft\" durable-agents project and build it into an extensive published wiki with resources, pull quotes, and copy-paste prompts.\n\nA probe is a one-line contract. One real example (S6): \"Inspect the attached video itself. Reply with exactly this single line and nothing else:\"\n\n``` text\nATTACHED_VIDEO_OK loopcraft-awaited-upload-probe\n```\n\nSource: prompt preview of session `loopcraft-awaited-upload-probe` (S6). Gemini returned the exact line from the real MP4, proving the upload path before any long run.\n\n| Time | Step | Model | Outcome |\n|----|----|----|----|\n| 16:39–16:40 | First upload probes | gemini-3-pro | error — path not ready |\n| 16:43 | Probe after service rebuild | gemini-3-pro | completed |\n| 16:46 | Segmentation plan review | gpt-5.5-pro | completed — shard strategy for the 93:49 video |\n| 17:00–18:30 | Chunk-analysis attempts | gemini-3-pro | repeated errors |\n| 18:09 | Awaited-upload probe | gemini-3-pro | completed — exact sentinel returned |\n| 18:40–18:53 | Source-native shards 001–003 | gemini-3-pro | completed, sentinel-verified |\n| 18:53, 19:07 | Shard 004 and retry | gemini-3-pro | error |\n| 19:12–19:20 | Shard 004, re-encoded | gemini-3-pro | completed — see next section |\n\n**Table 2.** Derived display: the Loop Craft run of the recorded snapshot, reordered into a timeline from session metadata timestamps and statuses (S6). Times UTC.\n\nThe shard analyses show Gemini genuinely watching, not summarizing a transcript: it heard \"we are going to talk about Loopcraft…\" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark (S6).\n\nThe signal you are looking for, in your own runs: the sentinel line comes back byte-exact. Anything else — a paraphrase, extra prose, silence — means the path is broken and the long run would have burned an hour to find that out.\n\n**Evidence limit** Table 2 compresses many sessions; some intermediate error attempts are omitted, and the timeline's \"outcome\" column paraphrases status fields. The full receipts remain in the operator's local session folders and are not published.\n\n## Adjust when a run fails instead of abandoning it\n\nShard 004 is the teachable failure. Two attempts errored while three sibling shards sailed through, which rules out \"the pipeline is down\" and points at the input itself.\n\nPer the session record (S6), an exact re-encode of that shard solved it completely: the rich analysis finished in 73 seconds and ended with the exact sentinel. The re-encode settings were preserved as the durable media recipe for future runs.\n\nPublication got the same skepticism as analysis. The agent source-checked pull quotes against the shard analyses, and after publishing it fetched the live pages rather than trusting the publish receipt; both URLs returned HTTP 200 (S6, re-verified S7 in the observed snapshot).\n\nThe result is public: the [Loopcraft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/) (S7) — a 93-minute recording turned into a permanent, quotable artifact in one working session.\n\nThe adjustment loop to copy: classify the failure (encoding, not automation), change one variable (re-encode), re-run the cheap proof (sentinel), then keep the fix as a recipe so the next run starts smarter. Deleting the run and starting over would have discarded exactly the knowledge that made shard 004 pass.\n\n**Evidence limit** The sources record that the re-encode worked, not why the original encoding failed inside Gemini. Treat the recipe as an empirical fix, not a diagnosis.\n\n## Practical action\n\nIf you want the local shape this record supports, do this, in order. Sign into ChatGPT in your normal Chrome. Run the one-command handshake from the second section and confirm a reply comes back. Then draft your first real consult against the maximum-batch rule: ordered work packages, exact targets, a verification per package. When you move to video, write the sentinel probe before you write the analysis prompt, and do not start the long run until the sentinel returns byte-exact. Keep every session folder — statuses, logs, and failed probes are the dataset your next debugging session will need.\n\nSuccess signal: your archive starts to look like Table 1 — audits, panels, and plans — rather than a pile of \"what next?\" chats. Failure signal: consults that finish in minutes with answers you already knew; tighten the prompt, not the model."
    },
    {
      "id": "factory-reasoning-and-video-worked-example",
      "slug": "reasoning-and-video-worked-example",
      "title": "Independent reasoning and video evidence — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Verification",
      "tags": [
        "reasoning-and-video",
        "examples"
      ],
      "sources": [
        {
          "label": "Independent reasoning and video evidence — worked example",
          "url": "https://shiny-rosette-m6zy.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/replay.html#Before the session: the only beat a human owns",
        "08-oracle-video/replay.html#The session, beat by beat",
        "08-oracle-video/replay.html#Where it landed: the shard prompt, verbatim"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 1048,
      "url": "/topics/factory-reasoning-and-video-worked-example/",
      "markdownUrl": "/markdown/factory-reasoning-and-video-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-reasoning-and-video-worked-example.json",
      "headings": [
        {
          "id": "before-the-session-the-only-beat-a-human-owns",
          "text": "Before the session: the only beat a human owns",
          "level": 2
        },
        {
          "id": "the-session-beat-by-beat",
          "text": "The session, beat by beat",
          "level": 2
        },
        {
          "id": "where-it-landed-the-shard-prompt-verbatim",
          "text": "Where it landed: the shard prompt, verbatim",
          "level": 2
        }
      ],
      "markdown": "# Independent reasoning and video evidence — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## Before the session: the only beat a human owns\n\nYou\n\nSign into chatgpt.com and gemini.google.com in your normal Chrome — then hand the keys over:\n\n``` text\noracle --engine browser -p \"HI\"\n```\n\nAgent\n\nOracle copies the session cookies from that logged-in profile into a temporary automation profile, opens ChatGPT in an automated Chrome, sends the prompt, and records the reply as a session. Any reply proves the cookie path works.\n\nCookies are the entire auth story. No API keys — the browser authenticates as *you* and gets everything the subscription gives you: the model picker, extended thinking, and the upload widget the video pipeline depends on.\n\n## The session, beat by beat\n\nYou\n\n`$oracle-video https://www.youtube.com/watch?v=uC6slhCTXlA` — Built this up into an extensive `$here-now` workshop wiki with extensive resources/pull quotes/and ai prompts to copy/paste\n\nThat is the whole human contribution to the run — one prompt naming a public 93:49 YouTube workshop (\"Building Durable Autonomous Agents\", the Loopcraft project). Everything below is the agent working.\n\nAgent\n\nSized up the source: 93 minutes and 49 seconds of screen-heavy workshop footage. No text model can watch that — only Gemini genuinely watches video, and only through the page's own upload widget. Plan: cut the recording into source-native shards Gemini can watch one at a time.\n\nThe first decision is a routing decision: text questions go to GPT-5.6 Pro, footage goes to Gemini — both through the same browser hands.\n\nAgent\n\nBefore touching video, asked the strongest text model to review the plan. Session `loopcraft-segmentation-review` (gpt-5.6-pro, completed): GPT-5.6 Pro reviewed how to shard a 93:49 recording so Gemini gets watchable, source-native chunks.\n\nPlanning the pipeline with the pipeline: maximum intelligence supervises the video intelligence before a single expensive run starts.\n\nAgent\n\nProbed before spending. A battery of cheap sentinel runs on gemini-3-pro, each asking for exactly one line back:\n\n``` text\nloopcraft-video-smoke-probe      error\nloopcraft-video-probe-retry      error\nloopcraft-video-probe-rebuilt    completed\nloopcraft-submit-proof-probe     completed\nloopcraft-awaited-upload-probe   completed\n  └─ reply: ATTACHED_VIDEO_OK loopcraft-awaited-upload-probe\n```\n\nTwo failures cost seconds each. Only after the sentinel came back byte-exact — from the real MP4 — did the long runs start. The generalized probe, liftable:\n\n``` text\n[video-upload-smoke-probe]\n\nThis is an attached-video readiness probe for a longer video analysis run.\n\nConfirm that you can inspect the attached video. Return exactly three short bullets:\n- whether video frames are visible;\n- whether audio is detectable;\n- one strictly observed visual detail, without guessing.\n\nEnd with this exact sentinel on its own line:\nEND_OF_VIDEO_ANALYSIS video-upload-smoke-probe probe\n```\n\n``` text\noracle --engine browser --model gemini-3-pro --browser-attachments always \\\n  -p \"$(cat probe-prompt.md)\" --file \"/absolute/path/to/probe-clip.mp4\" \\\n  --slug \"video-upload-smoke-probe\"\n```\n\nProbes before spends: a falsifiable one-line sentinel proves the fragile path (upload, submit, encoding) before an hour-long analysis bets on it. A paraphrase or silence means the path is broken.\n\nAgent\n\nWatched the shards. Sessions `loopcraft-workshop-shard-001…004` (gemini-3-pro): each shard analyzed for the wiki, each analysis required to end in its exact sentinel. The results prove Gemini genuinely watched the footage — it heard \"we are going to talk about Loopcraft…\" and identified the GitHub workshop page with the presenter's picture-in-picture at the 00:30 mark.\n\nTimestamped screen evidence — slides, terminal output, picture-in-picture — is the thing a transcript summarizer cannot produce.\n\nAgent\n\nShard 004 errored — twice — while its three siblings sailed through. That pattern rules out \"the pipeline is down\" and points at the input. Diagnosis: a media-encoding problem. An exact re-encode fixed it completely: the analysis finished in 73 seconds with the exact sentinel, and the re-encode settings were kept as the durable media recipe for future runs.\n\nFailure handled like engineering, not vibes: classify the error, change one variable, re-run the cheap proof, keep the fix.\n\nAgent\n\nVerified, then published. Pull quotes were source-checked against the analyses, the site build passed its checks with zero errors, and after publishing the agent curled the *live* URLs rather than trusting the publish receipt. The result is public and permanent: the [Loop Craft workshop wiki](https://silken-ferry-63mw.here.now/) and its [video companion](https://silken-ferry-63mw.here.now/video-companion/).\n\nOne working session: a 93-minute recording became a quotable artifact anyone in the room can open right now — not a chat log.\n\n## Where it landed: the shard prompt, verbatim\n\nThis exact prompt produced shard 001 of the wiki — it is the money artifact of the run. Swap the metadata block and the sentinel for your own video; keep the evidence rules, because they are what stop Gemini from inventing commands, URLs, and speakers.\n\n``` text\n[loopcraft-workshop-shard-001-source-native]\n\nAnalyze the attached source-native video shard for an extensive public workshop wiki.\n\nMetadata:\n- run_key: loopcraft-agent-workshop\n- shard_id: 001\n- original recording range: 00:00:00–00:04:00\n- publication chapter: Workshop Setup and the Looping Resolver\n\nEvidence rules:\n1. Use original workshop timestamps from 00:00:00 through 00:04:00.\n2. Separate spoken evidence, visible screen evidence, and inference.\n3. Listen to the audio; do not rely on automatic captions.\n4. Do not invent commands, URLs, files, tools, speakers, or UI labels.\n5. Pull quotes must be brief (under 20 words), audio-verified, attributed to Joel Hooks, and timestamped.\n6. Exclude credentials, account details, local paths/usernames, private URLs, signed URLs, notifications, or incidental personal data.\n7. Treat opinions and live-demo observations as such, not universal facts.\n8. Derived prompts must use placeholders, be clearly labeled as inspired by the workshop, and require confirmation for destructive or externally visible actions.\n\nReturn dense Markdown with these sections:\n# Shard 001 — 00:00:00–00:04:00\n## Executive Takeaway\n## Dense Timeline\n## Concepts and Mental Models\n## Visible Demo Evidence\n## Architecture and Workflow Patterns\n## Tools, Commands, and References\n## Pull Quote Candidates\n## Copy/Paste AI Prompt Candidates\n## Student Exercises and Reflection Questions\n## Keyframes to Capture\n## Uncertainties and Publication Review\n## Machine JSON\n\nThe fenced JSON object must contain: shard_id, original_range, summary, timeline, concepts, workflows, demos, resources, quotes, prompts, exercises, keyframes, warnings, unanswered_questions.\n\nEnd with this exact sentinel on its own line:\nEND_OF_VIDEO_ANALYSIS loopcraft-agent-workshop shard-001\n```\n\nFor the text-consult side of this section — the maximum-batch consult prompt and the full agent setup — go back to the [section guide](https://shiny-rosette-m6zy.here.now/index.html), or hear the skeptical version in the [dialogue](https://shiny-rosette-m6zy.here.now/dialogue.html). The full Oracle skill family behind this run is [attached on the index](https://shiny-rosette-m6zy.here.now/index.html#attachments-the-oracle-skill-family), downloadable and installable."
    },
    {
      "id": "codex-agent-ready-repos",
      "slug": "agent-ready-repos",
      "title": "Make the repository agent-ready",
      "summary": "A background workflow is only useful when the agent can prove what it changed. Start by giving the repo a verification loop. Then move repeated, narrow jobs into tiny tool-shaped agents that carry only the context they need.",
      "category": "Verification",
      "tags": [
        "observability",
        "imps",
        "verification"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#agent-ready-repos"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Budget The Intelligence",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Use Goals For Long Work",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Make Done Observable",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Keep The Terminal Thread Small",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Use Imps For Narrow Jobs",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Strip The Extras",
        "src/content/final/chunk-02-agent-ready-repos-and-imps.md#Make The Repo Agent-Ready, Then Shrink The Agent/Do Not Improvise Secrets",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#agent-ready-repos",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 399,
      "url": "/topics/codex-agent-ready-repos/",
      "markdownUrl": "/markdown/codex-agent-ready-repos.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-agent-ready-repos.json",
      "headings": [
        {
          "id": "budget-the-intelligence",
          "text": "Budget The Intelligence",
          "level": 2
        },
        {
          "id": "use-goals-for-long-work",
          "text": "Use Goals For Long Work",
          "level": 2
        },
        {
          "id": "make-done-observable",
          "text": "Make Done Observable",
          "level": 2
        },
        {
          "id": "keep-the-terminal-thread-small",
          "text": "Keep The Terminal Thread Small",
          "level": 2
        },
        {
          "id": "use-imps-for-narrow-jobs",
          "text": "Use Imps For Narrow Jobs",
          "level": 2
        },
        {
          "id": "strip-the-extras",
          "text": "Strip The Extras",
          "level": 2
        },
        {
          "id": "do-not-improvise-secrets",
          "text": "Do Not Improvise Secrets",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Make the repository agent-ready\n\nA background workflow is only useful when the agent can **prove what it changed**. Start by giving the repo a **verification loop**. Then move repeated, narrow jobs into tiny tool-shaped agents that carry only the context they need.\n\n## Budget The Intelligence\n\nThe point is not to throw every task at the biggest possible context window. Decide where broad planning belongs, then **keep the local work loop focused** on files, commands, checks, and saved decisions.\n\n## Use Goals For Long Work\n\nLong-running work needs a plan that can survive time away from the keyboard. Ask for the **full step list first**, then plan each step before implementation. The local agent should execute one step, verify it, and leave enough context for the next step to make sense.\n\n## Make Done Observable\n\nAn agent-ready repo lets an agent **read the code, write the change, and verify the result**. If the app lacks browser-style debugging, logs, snapshots, smoke tests, performance hooks, or a reliable local command, build the feedback loop before trusting automation.\n\n> The agent needs to be able to read the code, write the code, and verify the code.\n>\n> — John Lindquist\n\n## Keep The Terminal Thread Small\n\nCustom terminal workflows matter because the agent needs a reliable surface for invoking repeatable project actions. Keep detailed [zsh](https://zsh.sourceforge.io/Doc/Release/Functions.html), shortcut, and orchestration setup in tool-specific docs until the commands are verified.\n\n## Use Imps For Narrow Jobs\n\nAn **[imp](https://github.com/johnlindquist/codex-imps)** is a small, tool-shaped agent for a repeated job. It should know the **exact tool, examples, files, and conventions** it needs. It should not carry every skill, memory, search tool, and integration by default.\n\n> You give it as much context as you want, so that it's as smart as you need it, like, out of the gate.\n>\n> — John Lindquist\n\n## Strip The Extras\n\nA narrow imp can **turn off broad features** until the task actually needs them. That keeps the context window pointed at the job instead of at the whole operating system.\n\n## Do Not Improvise Secrets\n\nCredential and token isolation is a **security design item, not a copy-paste recipe**. Keep account state, vault layout, token names, subscription details, local storage, and private setup notes out of public instructions until they have been reviewed deliberately.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#agent-ready-repos)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-debug-marker",
      "slug": "debug-marker",
      "title": "Mark the debug moment before handoff",
      "summary": "Logs show what happened. A marker says which moment mattered.",
      "category": "Verification",
      "tags": [
        "debugging",
        "agent-markers",
        "evidence"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#debug-marker"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/The Problem",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Bounded Debug Packets",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Smallest Setup",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/The Data Model",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Privacy Defaults",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Test Runner And Agent Handoff",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Clean Up",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Copyable Artifact: Bounded Debug Packet",
        "src/content/final/chunk-10-mark-the-debug-moment-before-agent-handoff.md#Mark The Debug Moment Before Agent Handoff/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#debug-marker",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 1080,
      "url": "/topics/codex-debug-marker/",
      "markdownUrl": "/markdown/codex-debug-marker.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-debug-marker.json",
      "headings": [
        {
          "id": "the-problem",
          "text": "The Problem",
          "level": 2
        },
        {
          "id": "bounded-debug-packets",
          "text": "Bounded Debug Packets",
          "level": 2
        },
        {
          "id": "smallest-setup",
          "text": "Smallest Setup",
          "level": 2
        },
        {
          "id": "the-data-model",
          "text": "The Data Model",
          "level": 2
        },
        {
          "id": "privacy-defaults",
          "text": "Privacy Defaults",
          "level": 2
        },
        {
          "id": "test-runner-and-agent-handoff",
          "text": "Test Runner And Agent Handoff",
          "level": 2
        },
        {
          "id": "clean-up",
          "text": "Clean Up",
          "level": 2
        },
        {
          "id": "copyable-artifact-bounded-debug-packet",
          "text": "Copyable Artifact: Bounded Debug Packet",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Mark the debug moment before handoff\n\nLogs show what happened. **A marker says which moment mattered.**\n\nUse **[Agent Markers](https://github.com/johnlindquist/agent-markers)** when a bug appears during real app use and the next agent needs more than a sentence and a screenshot. The move is to mark the decisive moment while it is happening, capture nearby runtime evidence, add the human explanation, review the packet, and export only what is safe to share.\n\n```text\nmark -> capture -> explain -> review/export\n```\n\n## The Problem\n\nYou found the bug while using the app. The checkout button stayed disabled, the billing retry fired twice, the auth session rotated at the wrong time, or the date rendered in the wrong format.\n\n> We're interacting with an app, we're clicking on buttons, and we're typing in fields, and then something happens, and we want to be able to capture that specific moment. We don't want to have to quit our app, start up debugging mode.\n>\n> — John Lindquist\n\nThe old ritual is expensive:\n\n- add temporary logs\n- reproduce the bug\n- forget which log line mattered\n- remove the logs\n- hope the next agent understands the state you saw\n\nA debug marker **preserves the moment** without turning the whole session into a permanent logging project.\n\n## Bounded Debug Packets\n\nA **bounded debug packet** is a small export centered on one marked moment.\n\nIt can include:\n\n- the marker label and note\n- nearby console, fetch, error, unhandled rejection, and manual events\n- route, viewport, and environment metadata\n- optional DOM or screenshot evidence\n- the privacy review boundary\n- the first verification command for the next agent\n\nIt is not a replay system, production telemetry, a browser extension, a server product, or an AI product. It is a reviewed packet for debugging work.\n\n## Smallest Setup\n\n```ts\nimport { createAgentMarkers } from \"<verified-agent-markers-client>\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-demo\",\n  exposeGlobal: true\n});\n\nawait markers.mark(\"Checkout button stayed disabled\", {\n  note: \"Expected it to enable after selecting shipping.\",\n  tags: [\"checkout\", \"regression\"]\n});\n\nconst session = markers.export();\n```\n\n`createAgentMarkers` sets up a browser-side collector. It can mark moments, record manual events, export a `DebugSession`, optionally expose a dev/test global, and clean itself up with `stop()`.\n\n## The Data Model\n\n| Concept | Practical Meaning |\n|---|---|\n| `DebugSession` | One bounded debugging run: app name, session id, environment, markers, and events. |\n| `DebugMoment` | The human marker: label, note, tags, severity, environment, optional data, optional DOM/screenshot evidence, and `nearbyEventIds`. |\n| `CapturedEvent` | Runtime evidence near the marker: console, fetch, error, unhandled rejection, or manual event. |\n| `nearbyEventIds` | The bridge between the marked moment and the runtime events captured near it. |\n| export JSON | The reviewed packet that can be attached to a test run, issue, or agent prompt. |\n\nThe useful part is **the link between the human explanation and the runtime trail**. Without `nearbyEventIds`, the agent gets a label and starts guessing. With it, the agent gets a bounded slice of the session.\n\n## Privacy Defaults\n\nField rule: **metadata first, values only after review**.\n\nAgent Markers is designed around a local review boundary:\n\n- data stays in memory until explicit export\n- storage capture records key names and counts by default, not values\n- fetch capture records metadata and does not read request or response bodies\n- treat raw exported sessions as private until reviewed and redacted\n\n**Do not share raw exported sessions.** Review and redact private routes, screenshots, stack traces, request URLs, user-entered text, tokens, cookies, account data, local paths, and application-specific identifiers.\n\n## Test Runner And Agent Handoff\n\nIn dev and test, `exposeGlobal: true` gives a test runner a browser handle:\n\n```text\nwindow.__AGENT_MARKERS__\n```\n\nA browser test can reproduce the bug, call `mark(...)`, export JSON to a private test artifact, and attach or share only a reviewed and redacted packet. The next agent gets **a bounded packet instead of a vague report**.\n\n> You can take that kind of entire session, you can copy and paste the logs into your agent. And tell it, please review for the markers and help me get this fixed.\n>\n> — John Lindquist\n\nTreat the redaction helper below as project-specific review code, not an Agent Markers API.\n\n```ts\nconst session = await page.evaluate(async () => {\n  await window.__AGENT_MARKERS__.mark(\"checkout disabled unexpectedly\", {\n    note: \"Expected submit to enable after terms and shipping were selected.\"\n  });\n\n  return window.__AGENT_MARKERS__.export();\n});\n\nconst redactedSession = redactAgentMarkerSession(session);\n\nawait testInfo.attach(\"agent-markers.redacted.json\", {\n  body: JSON.stringify(redactedSession, null, 2),\n  contentType: \"application/json\"\n});\n```\n\nImport from the reviewed Agent Markers client in the current project. Verify the package or workspace path before turning this into executable setup.\n\nThe handoff prompt should tell the agent:\n\n- what the human expected\n- what happened instead\n- which event ids are nearby\n- what is intentionally redacted\n- where to start verification\n- what not to infer from missing data\n\n## Clean Up\n\nCall `stop()` when the collector is done.\n\nThe collector installs capture hooks for useful evidence. `stop()` disposes those hooks. After `stop()`, treat the collector as finished instead of continuing to mark new moments.\n\n## Copyable Artifact: Bounded Debug Packet\n\n```text\nMarker:\n- label:\n- note:\n- expected:\n- actual:\n- next action:\n\nSession:\n- schemaVersion:\n- sessionId:\n- appName:\n- markerId:\n- nearbyEventIds:\n\nIncluded evidence:\n- console:\n- fetch:\n- error:\n- unhandledrejection:\n- manual:\n- DOM or screenshot availability:\n\nPrivacy review:\n- storage values exported? no\n- request bodies exported? no\n- response bodies exported? no\n- private routes removed?\n- user-entered text removed?\n- stack paths reviewed?\n- screenshot reviewed?\n\nHandoff:\n- first verification command:\n- files or areas to inspect:\n- what the agent must not infer:\n- stop condition:\n```\n\nExample prompt:\n\n```text\nUse this bounded debug packet to investigate the checkout disabled-state bug.\n\nStart from the marker note and nearbyEventIds.\nDo not assume redacted fields are absent in the app.\nInspect the checkout form state, shipping selection flow, and submit-button disabled logic.\nReturn the likely cause, smallest patch plan, and first verification command before editing.\n```\n\n## Claim Boundaries\n\nAgent Markers gives the next agent a better packet. It does not guarantee the agent will find the defect automatically.\n\nUse it for local development, browser tests, and reviewed debugging artifacts. Verify any production use, data retention policy, screenshot capture, source-map behavior, and privacy implications before adopting it in a real product.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#debug-marker)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-visual-review",
      "slug": "visual-review",
      "title": "Review generated UI before building",
      "summary": "A generated mockup is useful when it gives you something concrete to inspect. Do not jump from one polished image to implementation. Keep the source visual, choose a controlled style direction, generate against that direction, review the result, then hand…",
      "category": "Verification",
      "tags": [
        "design",
        "visual-review",
        "mockups"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#visual-review"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-05-review-generated-ui-before-building.md",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Start From A Real Visual",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Name The Style Before Generating",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Generate Against One Direction",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Review The Image As Evidence",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Hand Off To A Build Pass",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Copyable Prompt: Controlled Visual Variation",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Branch Useful Context",
        "src/content/final/chunk-05-review-generated-ui-before-building.md#Review Generated UI Before You Build It/Carry Forward: Workspace Layouts",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#visual-review",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 711,
      "url": "/topics/codex-visual-review/",
      "markdownUrl": "/markdown/codex-visual-review.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-visual-review.json",
      "headings": [
        {
          "id": "start-from-a-real-visual",
          "text": "Start From A Real Visual",
          "level": 2
        },
        {
          "id": "name-the-style-before-generating",
          "text": "Name The Style Before Generating",
          "level": 2
        },
        {
          "id": "generate-against-one-direction",
          "text": "Generate Against One Direction",
          "level": 2
        },
        {
          "id": "review-the-image-as-evidence",
          "text": "Review The Image As Evidence",
          "level": 2
        },
        {
          "id": "hand-off-to-a-build-pass",
          "text": "Hand Off To A Build Pass",
          "level": 2
        },
        {
          "id": "copyable-prompt-controlled-visual-variation",
          "text": "Copyable Prompt: Controlled Visual Variation",
          "level": 2
        },
        {
          "id": "branch-useful-context",
          "text": "Branch Useful Context",
          "level": 2
        },
        {
          "id": "carry-forward-workspace-layouts",
          "text": "Carry Forward: Workspace Layouts",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Review generated UI before building\n\nA generated mockup is useful when it gives you **something concrete to inspect**. Do not jump from one polished image to implementation. Keep the source visual, choose a controlled style direction, generate against that direction, review the result, then hand the chosen direction to a build pass with explicit constraints.\n\n## Start From A Real Visual\n\nUse an existing screenshot, mockup, or product frame as the anchor. The agent should know **what it is changing** instead of inventing the whole interface from scratch.\n\nFor product work, this could be a checkout screen, a settings panel, a saved listings card, or a dashboard slice. The point is to **keep the job of the screen stable** while the visual direction changes.\n\n## Name The Style Before Generating\n\nAsk for a **numbered list of style directions** first. Then refer to the style by number in the next prompt. That gives the agent a stable design target instead of asking it to invent the language at the same time it generates the mockup.\n\n> As long as you have that list ahead of time. So that, just in time, it doesn't have to come up with new ideas. You'll have much better results.\n>\n> — John Lindquist\n\n## Generate Against One Direction\n\nUse the **selected style as the variable**. Keep the screen purpose, product type, data model, and interaction intent stable.\n\nIf the source is a saved listings mobile screen, the generated version should still help someone scan saved listings. The typography, surface treatment, spacing rhythm, or color system can change. The task should not quietly become a different product.\n\n## Review The Image As Evidence\n\nTreat the generated image as **review material, not finished UI**. Check what changed, what survived, what broke, and whether the result is still reasonable to build.\n\nReview against:\n\n- Did the screen keep the same job?\n- Did the primary action stay obvious?\n- Did the content survive the style change?\n- Is the spacing intentional or just empty?\n- Would this be reasonable to implement?\n- What should the build pass preserve?\n- What should the build pass reject?\n\n## Hand Off To A Build Pass\n\nThe next step is not more wandering. Tell the agent **what won, why it won, what to preserve, what to fix, and what proof counts**.\n\n```text\nUse the selected generated mockup as the visual reference.\n\nBuild a real implementation of this direction.\n\nPreserve:\n- the accepted layout structure\n- the visual hierarchy\n- the selected spacing rhythm\n- the core interaction model\n\nFix:\n- unreadable text\n- impractical spacing\n- missing accessibility states\n- inconsistent component behavior\n\nVerification:\n- run the project checks\n- capture desktop and mobile screenshots\n- compare the result against the selected mockup\n- list any visual mismatches that remain\n\nDo not restart the visual exploration.\n```\n\n## Copyable Prompt: Controlled Visual Variation\n\n```text\nUse the provided UI screenshot as the source visual.\n\nGoal:\nCreate a new visual direction for the same mobile screen.\n\nStyle direction:\nUse style 6 from the saved style list.\n\nKeep unchanged:\n- screen purpose\n- information hierarchy\n- primary user action\n- core data shown on the card\n- mobile-first layout\n\nChange only:\n- visual style\n- spacing rhythm\n- typography feel\n- surface treatment\n\nReturn:\n- one generated mockup\n- a short review of what changed\n- what must be preserved in a real implementation\n```\n\n## Branch Useful Context\n\nWhen a design conversation starts working, **name it and fork it** before trying a risky direction. A fork is a saved branch of useful context. Use it for experiments you may abandon. Do not depend on throwaway side chats for work you might need later.\n\n> A side chat in an ephemeral fork. I'm not a fan of those. I don't like ephemeral things with agents. I never want to lose anything.\n>\n> — John Lindquist\n\n## Carry Forward: Workspace Layouts\n\nThis workflow creates repeated surfaces: source visuals, style lists, generated variants, review notes, implementation passes, and screenshots. Workspace layout matters once the build pass begins: keep the accepted visual direction, implementation files, and verification screenshots easy to compare.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#visual-review)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "foundations-log-gated-playbook",
      "slug": "log-gated-playbook",
      "title": "Self-improving log-gated fix loop playbook",
      "summary": "Web developers already run local dev servers, browser checks, test scripts, and agent panes; this technique turns those runtime artifacts into proof instead of vibes. It matters because UI bugs, auth regressions, and hook failures are often only obvious in logs, browser state, or terminal output, not in the agent's final message.",
      "category": "Verification",
      "tags": [
        "logs",
        "verification",
        "boundaries",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-08.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#log-gated",
        "scenarios/log-gated.json#audienceFit",
        "toolkit/prompts/08-log-gated-self-improving-loop.md",
        "toolkit/codex-skills/log-gated-verification/SKILL.md",
        "scenarios/log-gated.json#scenarios/0",
        "scenarios/log-gated.json#scenarios/1",
        "scenarios/log-gated.json#scenarios/2",
        "scenarios/log-gated.json#implementationNotes",
        "scenarios/log-gated.json#notTaughtOrAvoid/2",
        "scenarios/log-gated.json#notTaughtOrAvoid/3",
        "scenarios/log-gated.json#notTaughtOrAvoid/4",
        "scenarios/log-gated.json#notTaughtOrAvoid/5",
        "scenarios/log-gated.json#notTaughtOrAvoid/6",
        "scenarios/log-gated.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "verification",
      "wordCount": 2667,
      "url": "/topics/foundations-log-gated-playbook/",
      "markdownUrl": "/markdown/foundations-log-gated-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-log-gated-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "reusable-skill",
          "text": "Reusable skill",
          "level": 2
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "auth-redirect-loop-with-browser-evidence",
          "text": "Auth redirect loop with browser evidence",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "checkout-ui-regression-behind-deterministic-artifacts",
          "text": "Checkout UI regression behind deterministic artifacts",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "codex-hook-or-local-cli-failure-hardening",
          "text": "Codex hook or local CLI failure hardening",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "validated-lesson-08-references",
          "text": "Validated lesson 08 references",
          "level": 3
        },
        {
          "id": "existing-log-gated-prompt",
          "text": "Existing log-gated prompt",
          "level": 3
        },
        {
          "id": "existing-codex-skill",
          "text": "Existing Codex skill",
          "level": 3
        },
        {
          "id": "cmux-terminal-text-capture",
          "text": "CMUX terminal text capture",
          "level": 3
        },
        {
          "id": "cmux-live-tracker-pane",
          "text": "CMUX live tracker pane",
          "level": 3
        },
        {
          "id": "lesson-08-validation-notes",
          "text": "Lesson 08 validation notes",
          "level": 3
        },
        {
          "id": "interactive-lesson-checklist",
          "text": "Interactive lesson checklist",
          "level": 3
        }
      ],
      "markdown": "# Self-improving log-gated fix loop playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already run local dev servers, browser checks, test scripts, and agent panes; this technique turns those runtime artifacts into proof instead of vibes. It matters because UI bugs, auth regressions, and hook failures are often only obvious in logs, browser state, or terminal output, not in the agent's final message.\n\n[Core principles](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Copy-paste workflow\n\n**When to use:** When you need to KNOW an agent really verified its work, not just trust a happy completion message. This captures the exact terminal failure, feeds it back to harden the tool, and gates fix/verify behind structured logs a supervisor compares.\n\n### Copy-paste prompt\n\n```text\nYou are my coding agent. Don't trust completion messages — prove the work with logs. Run this self-improvement + log-gated verification loop on <TOOL/WORKFLOW>.\n\n1. Capture the EXACT terminal failure state as clean text (don't summarize it from memory). In CMUX, use the terminal-text extraction to grab the real output:\n     cmux read-screen\n   Use that real text as context.\n\n2. Use this prompt shape against the failure — state the goal, paste the failure after a colon, then ask for a root-cause fix:\n     \"Goal: <GOAL>. Here is the exact failure: <PASTE TERMINAL TEXT>. Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time.\"\n\n3. Make verification CONCRETE and deterministic. The fix must write structured logs / JSON artifacts / timestamps to disk on each run. Then a supervisor agent runs the scenarios, waits, and COMPARES expected-vs-actual fields in those log files. That comparison is the gate — only pass when the fields match.\n\nGuardrails: keep worker agents narrow and tool-limited; keep the orchestrator context-rich. REDACT secrets from logs.\n```\n\n### How it works\n- Capture the exact terminal failure as clean text (via CMUX `cmux read-screen`) rather than a memory summary, and use it as real context.\n- The prompt shape — goal, then the failure after a colon, then \"explain why it failed and patch the workflow\" — drives a true root-cause fix, not a band-aid.\n- Verification is made concrete: the workflow writes structured logs / JSON artifacts / timestamps, and a supervisor agent runs scenarios and compares expected-vs-actual fields. That field comparison is the deterministic gate.\n- Keep worker agents narrow and tool-limited; keep the orchestrator context-rich.\n- Redact secrets from logs.\n- Reference: [codex-daemons](https://github.com/johnlindquist/codex-daemons), [CMUX](https://github.com/manaflow-ai/cmux).\n\n## Reusable skill\n\nInstall as `~/.agents/skills/log-gated-verification/SKILL.md`, then restart Codex.\n\n````markdown\n---\nname: log-gated-verification\ndescription: Trigger when you must prove an agent actually verified work rather than trusting a completion message — write structured logs/artifacts and have a supervisor compare expected-vs-actual fields (a deterministic gate). Do NOT trust self-reported success.\n---\n\n# Log-gated verification\n\nProve work with logs instead of trusting completion messages. Capture the exact failure, patch the workflow to cover it, and gate fix/verify behind structured logs a supervisor compares field-by-field.\n\n## Steps\n\n1. Capture the EXACT terminal failure state as clean text (not a memory summary). In CMUX, extract the real terminal output:\n   ```bash\n   cmux read-screen\n   ```\n   Use that real text as context.\n\n2. Use this prompt shape against the failure — goal, then the failure after a colon, then the fix request:\n   ```\n   Goal: <goal>. Here is the exact failure: <paste terminal text>.\n   Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time.\n   ```\n\n3. Make verification CONCRETE and deterministic: the workflow must write structured JSON logs / timestamps / payload snapshots to disk on each run.\n\n4. A supervisor agent runs the scenarios, waits, and COMPARES expected-vs-actual fields in those log files. That field comparison is THE GATE — pass only when the fields match.\n\n## Guardrails\n- Do NOT trust self-reported success; the log comparison is the source of truth.\n- Keep worker agents narrow and tool-limited; keep the orchestrator context-rich.\n- REDACT secrets from logs.\n````\n\n## Scenarios\n\n### Auth redirect loop with browser evidence\n\n**Role:** As a full-stack Next.js developer maintaining an authenticated dashboard\n\nA local Next.js app sometimes redirects logged-in users from /dashboard back to /login after a route middleware or session-cookie change. The agent claims the fix works, but the team needs proof from the running browser and structured logs.\n\n> As a full-stack developer, I want the agent to reproduce the auth redirect failure, capture exact runtime evidence, patch the workflow, and gate success on log comparison, so that I do not merge an auth fix based on a cheerful completion message.\n\n#### Agent brief\n\n```text\nYou are my coding agent. Run a self-improving log-gated fix loop for the local auth redirect bug. First inspect the current code and existing verification scripts; do not rely on memory. Start the dev server using the repo's documented command from package.json. Reproduce the flow in a browser: visit /login, sign in with the local/dev credentials or seeded test user documented in the repo, navigate to /dashboard, refresh, and confirm whether the browser stays on /dashboard. Capture exact evidence: terminal output with `cmux read-screen`, browser console/network output if available, and a JSON log artifact at `.notes/log-gated/auth-redirect/run-<timestamp>.json`. The log must include goal, routeVisited, finalUrl, redirectCount, authCookiePresent as true/false when observable, serverStatusCodes, consoleErrors, terminalFailureText when present, and pass boolean. If the first run fails, use this repair prompt shape internally: `Goal: authenticated users should remain on /dashboard after login and refresh. Here is the exact failure: <paste terminal/browser/log evidence>. Explain WHY it failed in this scenario, then PATCH the workflow so this case is covered next time.` After patching, rerun the same browser flow and write a second JSON artifact. A supervisor pass must compare expected-vs-actual fields and only pass when finalUrl is /dashboard, redirectCount is 0 after the authenticated refresh, pass is true, and no new console/server errors appear. Finish with the files changed, commands run, log artifact paths, and a terse review note.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n```text\ncmux read-screen\n```\n\n```text\ncmux markdown open .notes/log-gated/auth-redirect/tracker.md --direction right\n```\n\n```text\npackage.json scripts for dev/test commands\n```\n\n```text\n.notes/log-gated/auth-redirect/*.json\n```\n\n#### Browser verification\n\nUse a CMUX browser pane or agent-browser-style workflow to take an accessibility snapshot of /login, fill the login form, click submit, wait for navigation, evaluate `window.location.pathname`, refresh, evaluate it again, and capture console/network errors. Browser proof is required here because the bug is about real navigation, cookies, and route behavior.\n\n#### Definition of done\n\n- At least two structured JSON run logs exist: one reproducing the original failure when possible and one post-fix verification run.\n- The supervisor comparison explicitly checks finalUrl, redirectCount, status codes, consoleErrors, and pass fields instead of trusting the worker's text.\n- The final browser state after login and refresh is /dashboard with no unexpected redirect to /login.\n- The final response lists exact commands run, files changed, and log paths under `.notes/log-gated/auth-redirect/`.\n\n#### Failure modes and mitigations\n\n- Common mistake: the agent only runs unit tests and declares success. Mitigation: require a browser flow plus JSON log fields proving finalUrl and redirectCount.\n- Common mistake: logs contain tokens, cookies, or full auth headers. Mitigation: redact secrets and store only booleans, route names, status codes, and sanitized error strings.\n- Common mistake: the agent tests a stale dev server. Mitigation: restart or verify the dev server command, capture terminal output with `cmux read-screen`, and include the server start timestamp in the log.\n\n### Checkout UI regression behind deterministic artifacts\n\n**Role:** As a frontend product engineer responsible for a checkout or upgrade flow\n\nA pricing or checkout screen was refactored and now one browser path intermittently disables the primary CTA, misprices a plan, or shows the wrong confirmation state. The workflow needs browser validation plus structured artifacts a supervisor can compare.\n\n> As a frontend product engineer, I want an agent to verify the checkout path with browser actions and structured scenario logs, so that regressions are caught by observable artifacts instead of a subjective agent summary.\n\n#### Agent brief\n\n```text\nYou are my coding agent. Build a log-gated verification loop for the checkout/pricing flow. Inspect the source files for the pricing/checkout route, the relevant components, and existing tests. Start the local app using the repo's package scripts. Create `.notes/log-gated/checkout/criteria.md` with the expected scenario fields: selectedPlan, displayedPrice, ctaEnabled, confirmationVisible, finalUrl, consoleErrors, networkFailures, and pass. Then run three browser scenarios: default plan selection, switching plans twice, and back/refresh during checkout. For each scenario, write `.notes/log-gated/checkout/<scenario-slug>.json` with timestamp, exact steps, expected fields, actual fields, terminal evidence from `cmux read-screen` when a failure occurs, and pass boolean. If any scenario fails, use the exact failure text and artifact contents to patch the code or workflow, then rerun only the failing scenario plus one happy-path scenario. Add or update a verifier script only if the repo already has a natural place for local scripts; otherwise have the supervisor agent compare the JSON files directly. The gate passes only when all expected-vs-actual fields match and the browser proof agrees with the logs.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n```text\ncmux read-screen\n```\n\n```text\ncmux markdown open .notes/log-gated/checkout/tracker.md --direction right\n```\n\n```text\n.notes/log-gated/checkout/criteria.md\n```\n\n```text\n.notes/log-gated/checkout/*.json\n```\n\n```text\npackage.json scripts for dev/test commands\n```\n\n#### Browser verification\n\nUse Playwright, a CMUX browser pane, or an agent-browser-style accessibility snapshot/click/evaluate sequence: open the pricing route, snapshot the buttons and plan labels, click each plan option, evaluate visible price and CTA disabled state, click the CTA, then evaluate the final confirmation URL/state. This is browser-worthy because visual state, disabled controls, and navigation are the product behavior.\n\n#### Definition of done\n\n- Three scenario JSON logs exist with expected fields and actual fields.\n- A supervisor comparison marks pass only when selectedPlan, displayedPrice, ctaEnabled, confirmationVisible, finalUrl, consoleErrors, and networkFailures match the criteria.\n- The agent provides browser evidence for each scenario, either through Playwright output, accessibility snapshots, screenshots, console logs, or explicit evaluate results.\n- Any fix is tied back to the exact failing artifact and rerun evidence.\n\n#### Failure modes and mitigations\n\n- Common mistake: the agent overfits to one happy path. Mitigation: require default selection, repeated plan switching, and back/refresh behavior.\n- Common mistake: the agent writes brittle permanent UI tests for a screen still changing daily. Mitigation: keep these as `.notes/log-gated/checkout/` artifacts unless the repo already has a stable test home.\n- Common mistake: the browser log and JSON log disagree. Mitigation: make the supervisor compare both and fail the gate until the artifact mismatch is resolved.\n\n### Codex hook or local CLI failure hardening\n\n**Role:** As a developer maintaining a repo-local Codex hook, plugin, or CLI helper\n\nA hook or local CLI command fails under a specific edge case, such as malformed input, missing config, unexpected event JSON, or a command usage error. The agent must capture the exact terminal failure, patch the hook/workflow, and prove the case is covered next time.\n\n> As a tooling-focused developer, I want failures from hooks or CLI helpers to become regression artifacts, so that each failure hardens the workflow instead of becoming another one-off terminal mystery.\n\n#### Agent brief\n\n```text\nYou are my tooling agent. Run the self-improvement error loop on the failing hook/CLI workflow. First reproduce the failing command or hook scenario exactly. Capture the terminal state with `cmux read-screen` and save the raw text to `.notes/log-gated/tooling/failures/<timestamp>.txt`. Then apply this prompt shape to your own diagnosis: `Goal: <describe the hook or CLI contract>. Here is the exact failure: <paste captured terminal text>. Explain WHY it failed in this scenario, then PATCH the hook/workflow so this case is covered next time.` Patch the smallest relevant hook/workflow code. Add structured run artifacts under `.notes/log-gated/tooling/runs/` containing scenarioName, inputShape, commandRun, expectedOutcome, actualOutcome, errorText, timestamp, and pass. Run at least the original failing case and one nearby non-failing case. A supervisor pass must inspect the run artifacts and compare expectedOutcome vs actualOutcome. Do not claim success unless the artifacts show the original failure case now passes and the nearby case still passes.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n```text\ncmux read-screen\n```\n\n```text\n.notes/log-gated/tooling/failures/*.txt\n```\n\n```text\n.notes/log-gated/tooling/runs/*.json\n```\n\n#### Browser verification\n\nBrowser proof is not the primary proof unless the hook controls browser-visible behavior. For a terminal hook or CLI helper, the right proof is exact terminal capture plus structured run logs. If the hook opens a CMUX browser dashboard or affects a web UI, add one browser snapshot/evaluate step to confirm the visible state matches the log.\n\n#### Definition of done\n\n- The raw failure text is saved exactly, not paraphrased.\n- The patch is tied to a stated root cause from the captured failure.\n- At least two structured run logs exist: original failing scenario and nearby control scenario.\n- A supervisor comparison reads the artifacts and marks the gate pass only when expectedOutcome and actualOutcome match.\n\n#### Failure modes and mitigations\n\n- Common mistake: the agent patches the symptom without explaining the failure condition. Mitigation: require a root-cause note derived from the captured terminal text.\n- Common mistake: the agent creates an unbounded self-improvement loop. Mitigation: run a fixed set of scenarios and stop after the gate comparison.\n- Common mistake: the worker agent gets too much project context and wanders. Mitigation: keep the worker scoped to the hook/CLI files, logs, and the contract for this workflow.\n\n## Implementation notes\n\n- Keep the durable artifact small and boring: raw terminal capture, scenario criteria, JSON run logs, and a supervisor comparison.\n- Use `.notes/log-gated/<scenario>/` for local artifacts unless the project already has a committed test-artifact convention.\n- For web app scenarios, require browser proof when the behavior depends on cookies, navigation, visible UI state, console errors, network calls, or disabled controls.\n- For hook or CLI scenarios, terminal capture and structured logs are the primary proof; browser automation is only useful if the workflow changes browser-visible state.\n- The worker agent should patch narrowly; the orchestrator or supervisor should compare artifacts and decide pass/fail.\n- Do not trust the worker's final answer as the gate. The gate is expected-vs-actual comparison over files, logs, terminal output, browser output, or other inspectable artifacts.\n- Redact secrets from logs. Store booleans, shapes, route names, status codes, sanitized errors, and timestamps rather than raw tokens, cookies, or credentials.\n- Grounding note: content is derived from the uploaded scenario-log-gated bundle. :contentReference[oaicite:0]{index=0}\n\n## Boundaries and caveats\n\n- Do not introduce unrelated tools that were only mentioned elsewhere, such as broad NotebookLM, n8n, ScreenPipe, or external CI platform workflows.\n- Do not claim deterministic proof from an agent's natural-language completion message.\n- Do not overbuild a permanent test suite for fast-moving UI experiments unless the repo already has stable acceptance tests for that flow.\n- Do not create unbounded self-improvement loops; run named scenarios, compare artifacts, and stop.\n- Do not log secrets, auth headers, private customer data, or raw cookies just because logs are useful.\n\n## Agent reference map\n\n### Validated lesson 08 references\n\nUse as the ground-truth teaching source for terminal text extraction, self-improvement loops, log-based gates, natural-language boundaries, and context pruning.\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n### Existing log-gated prompt\n\nUse as the copy-paste source pattern for capturing exact failure text, asking for root-cause hardening, and requiring structured log artifacts.\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n### Existing Codex skill\n\nUse to keep scenario language aligned with the existing toolkit skill and avoid inventing untaught verification machinery.\n\n[Open reference](/topics/foundations-log-gated-playbook/)\n\n### CMUX terminal text capture\n\nUse to grab exact terminal output as machine-readable context before diagnosis or patching.\n\n```text\ncmux read-screen\n```\n\n### CMUX live tracker pane\n\nUse when the agent should keep a visible, auto-refreshing progress view next to the running workflow.\n\n```text\ncmux markdown open .notes/log-gated/<scenario>/tracker.md --direction right\n```\n\n### Lesson 08 validation notes\n\nUse to stay inside the validated taught boundary: logs/files/API calls/object shapes/timestamps/session outputs, not invented broad verifier infrastructure.\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)\n\n### Interactive lesson checklist\n\nUse for concrete practice steps and success criteria around failure capture, log comparison gates, and worker boundary contracts.\n\n[Open reference](/topics/foundations-deterministic-verification-and-boundaries/)"
    },
    {
      "id": "codex-model-council",
      "slug": "model-council",
      "title": "Use a model council for hard decisions",
      "summary": "A single model can give a clean answer and still miss the important edge. Use a model council when the cost of a missed perspective is higher than the cost of waiting.",
      "category": "Verification",
      "tags": [
        "fusion",
        "review",
        "disagreement"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#model-council"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Use It For Hard Decisions",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/The Mental Model",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Run The Whole Council",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Handle Missing Voices",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Good Software Uses",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Optional Pattern: Stop-Hook Review",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Copyable Artifact: Fusion Decision Brief",
        "src/content/final/chunk-09-use-a-model-council-when-one-answer-is-too-narrow.md#Use A Model Council When One Answer Is Too Narrow/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#model-council",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "verification",
      "wordCount": 867,
      "url": "/topics/codex-model-council/",
      "markdownUrl": "/markdown/codex-model-council.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-model-council.json",
      "headings": [
        {
          "id": "use-it-for-hard-decisions",
          "text": "Use It For Hard Decisions",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "run-the-whole-council",
          "text": "Run The Whole Council",
          "level": 2
        },
        {
          "id": "handle-missing-voices",
          "text": "Handle Missing Voices",
          "level": 2
        },
        {
          "id": "good-software-uses",
          "text": "Good Software Uses",
          "level": 2
        },
        {
          "id": "optional-pattern-stop-hook-review",
          "text": "Optional Pattern: Stop-Hook Review",
          "level": 2
        },
        {
          "id": "copyable-artifact-fusion-decision-brief",
          "text": "Copyable Artifact: Fusion Decision Brief",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Use a model council for hard decisions\n\nA single model can give a clean answer and still miss the important edge. Use a **model council** when the cost of a missed perspective is higher than the cost of waiting.\n\n**[Fusion](https://github.com/johnlindquist/fusion)** is one way to run that pattern locally: send the same bounded software question to multiple configured providers, wait for the panel to finish, let a **finalizer** compare the outputs, then make the engineering decision from the result and the repo evidence.\n\n> It can take all of those results and then fuse them with the model of your choice. Meaning that… you get multiple opinions, you can have them kind of argue against each other.\n>\n> — John Lindquist\n\n## Use It For Hard Decisions\n\nReach for a council when you need **coverage, not speed**.\n\nGood fits:\n\n- large PR review\n- architecture tradeoffs\n- migration risk\n- security and performance tension\n- uncertain debugging plans\n- product or UX direction\n- release or rollback strategy\n\nDo not use it as a way to avoid making the call. The council gives you independent critique. **You still own the decision.**\n\n## The Mental Model\n\n```text\nbounded software question\n-> independent model/provider perspectives\n-> terminal provider states\n-> finalizer comparison\n-> summary.json\n-> final.md\n-> engineering decision\n```\n\nFusion is for coverage, not voting. The useful output is not \"three models said yes.\" The useful output is consensus, contradictions, unique warnings, blind spots, and a final recommendation you can test against the codebase.\n\n## Run The Whole Council\n\nPartial panel output is not the answer. Wait until every configured provider reaches a **terminal state** before treating the result as complete.\n\nBefore a real run:\n\n- inspect the configured providers\n- run the full configured panel by default\n- wait for terminal provider states\n- read `summary.json`\n- read `final.md`\n- reconcile the result with repo evidence\n\n**Panel artifacts are partial until the final artifacts exist.**\n\n## Handle Missing Voices\n\nA missing provider degrades the council. It does not automatically make the run useless.\n\nIf a provider times out, fails, or hits quota after artifacts exist, treat that as a **missing voice**. The final answer can still be useful if it clearly names the degraded state and enough other panel output exists to synthesize.\n\nDo not hide the missing voice. Make it part of the decision record.\n\n## Good Software Uses\n\nLarge PR review:\n\n```text\nUse Fusion to review this PR before merge.\n\nContext:\n- PR summary:\n- changed files:\n- risky areas:\n- test output:\n- migration or rollout notes:\n\nAsk the council to find:\n- correctness risks\n- security risks\n- performance risks\n- missing tests\n- rollout or rollback issues\n- documentation gaps\n\nReturn:\n- consensus\n- contradictions\n- unique warnings\n- blind spots\n- recommended merge/block decision\n- verification commands\n```\n\nArchitecture tradeoff:\n\n```text\nCompare three implementation paths for the billing webhook fix:\n\nA. provider event id dedupe\nB. invoice-level lock\nC. processing ledger\n\nInclude:\n- failure modes\n- migration risk\n- rollback path\n- test plan\n- operational logging\n- smallest shippable recommendation\n```\n\nRole/perspective panel:\n\n```text\nReview this auth/session plan from four perspectives:\n\n1. security reviewer\n2. performance reviewer\n3. migration reviewer\n4. product/UX reviewer\n\nEach reviewer should name what could go wrong.\nThe finalizer should preserve minority warnings instead of flattening them.\n```\n\n## Optional Pattern: Stop-Hook Review\n\nFor risky AFK work, a prompt marker can ask a later stop gate to review changes before reporting done.\n\nConceptual shape:\n\n```text\nWhen the user prompt includes #review, write a marker for the stop hook.\n\nAt Stop:\n- check whether files changed\n- check whether the marker exists\n- run Fusion against the diff\n- read summary.json and final.md\n- report the council result before claiming done\n```\n\nTreat this as a pattern until the hook payload, marker passing, and current CLI behavior are verified.\n\n## Copyable Artifact: Fusion Decision Brief\n\n```text\nDecision:\n[the software decision under review]\n\nWhy a council:\n[what one model might miss]\n\nContext:\n- repo area:\n- changed files:\n- relevant tests:\n- logs or traces:\n- constraints:\n\nProvider instructions:\nAsk each provider to review independently.\nPreserve disagreements.\nDo not treat majority agreement as proof.\n\nFinalizer instructions:\nReturn:\n- consensus\n- contradictions\n- unique warnings\n- blind spots\n- recommended decision\n- verification commands\n- confidence and why\n\nHuman decision:\n[accept / revise / block / run another pass]\n```\n\n## Claim Boundaries\n\nHosted products may publish their own benchmark or cost claims for panel-style research workflows. Treat those as vendor claims that need dated citations. Local Fusion is a local CLI pattern inspired by [the same panel/finalizer idea](https://openrouter.ai/blog/announcements/fusion-beats-frontier/), not proof of hosted benchmark results.\n\n> I can, like, anecdotally vouch for the results, but I can't give you some sort of percentage of… it's this close to Fable or whatever.\n>\n> — John Lindquist\n\nProvider availability, pricing, quotas, auth, and data handling are local/account-dependent. Verify current provider terms before sending private code or prompts.\n\nModel council output is **advisory**. Tests, code review, product judgment, and repo evidence still decide the work.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#model-council)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "foundations-deterministic-verification-and-boundaries",
      "slug": "deterministic-verification-and-boundaries",
      "title": "Verify fixes with deterministic evidence and narrow boundaries",
      "summary": "Extract terminal pane text in CMUX as machine-readable context; Build self-improvement error loops behind log-based deterministic gates; Define natural-language contract boundaries and prune context.",
      "category": "Verification",
      "tags": [
        "logs",
        "verification",
        "boundaries"
      ],
      "sources": [
        {
          "label": "Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-08.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#08/objectives",
        "oracle/08-references.json#recap",
        "oracle/08-references.json#concepts/0",
        "oracle/08-references.json#concepts/1",
        "oracle/08-references.json#concepts/2",
        "oracle/08-references.json#concepts/3",
        "oracle/08-references.json#concepts/4",
        "oracle/08-references.json#references",
        "oracle/08-references.json#recommendations",
        "oracle/08-interactive.json#intro",
        "oracle/08-interactive.json#checklist",
        "oracle/08-interactive.json#challenges",
        "oracle/08-interactive.json#quiz",
        "oracle/08-interactive.json#reflect",
        "oracle/08-references.json#goDeeper",
        "materials/exercises.md#Chunk-08",
        "materials/qa-index.md#Q040",
        "materials/qa-index.md#Q041",
        "materials/keyframes.md#Chunk-08",
        "lesson-08.html#resource-packet",
        "lesson-08.html#clip-map",
        "lesson-08.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "verification",
      "wordCount": 2667,
      "url": "/topics/foundations-deterministic-verification-and-boundaries/",
      "markdownUrl": "/markdown/foundations-deterministic-verification-and-boundaries.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-deterministic-verification-and-boundaries.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "terminal-text-extraction-as-context",
          "text": "Terminal text extraction as context",
          "level": 3
        },
        {
          "id": "self-improvement-error-loops",
          "text": "Self-improvement error loops",
          "level": 3
        },
        {
          "id": "log-based-deterministic-gates",
          "text": "Log-based deterministic gates",
          "level": 3
        },
        {
          "id": "natural-language-contract-boundaries",
          "text": "Natural-language contract boundaries",
          "level": 3
        },
        {
          "id": "context-pruning-for-low-latency-daemons",
          "text": "Context pruning for low-latency daemons",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "codex-daemons",
          "text": "codex-daemons",
          "level": 3
        },
        {
          "id": "cmux",
          "text": "CMUX",
          "level": 3
        },
        {
          "id": "github-cli",
          "text": "GitHub CLI",
          "level": 3
        },
        {
          "id": "better-plugins-ralph-hook-example",
          "text": "Better Plugins / Ralph hook example",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "failure-capture-drill",
          "text": "Failure Capture Drill",
          "level": 3
        },
        {
          "id": "log-comparison-gate",
          "text": "Log Comparison Gate",
          "level": 3
        },
        {
          "id": "boundary-contract-map",
          "text": "Boundary Contract Map",
          "level": 3
        },
        {
          "id": "low-context-daemon-prototype",
          "text": "Low-Context Daemon Prototype",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "a-hook-fails-in-a-cmux-terminal-pane-and-prints-a-long-stack-trace-what-should-you-do-first-if-you-want-the-fastest-useful-self-improvement-loop",
          "text": "A hook fails in a CMUX terminal pane and prints a long stack trace. What should you do first if you want the fastest useful self-improvement loop?",
          "level": 3
        },
        {
          "id": "what-makes-a-log-based-deterministic-gate-stronger-than-an-agent-s-completion-claim",
          "text": "What makes a log-based deterministic gate stronger than an agent's completion claim?",
          "level": 3
        },
        {
          "id": "in-this-lesson-s-boundary-model-what-should-the-master-orchestrator-usually-do",
          "text": "In this lesson's boundary model, what should the master orchestrator usually do?",
          "level": 3
        },
        {
          "id": "why-would-a-codex-daemon-use-a-redirected-home-directory-and-disable-memories-mcp-servers-web-search-and-project-rules",
          "text": "Why would a Codex daemon use a redirected home directory and disable memories, MCP servers, web search, and project rules?",
          "level": 3
        },
        {
          "id": "which-prompt-shape-best-matches-the-lesson-s-repair-loop",
          "text": "Which prompt shape best matches the lesson's repair loop?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "exercise-1-build-a-manual-error-recovery-loop",
          "text": "Exercise 1: Build a Manual Error-Recovery Loop",
          "level": 3
        },
        {
          "id": "exercise-2-prototype-an-isolated-virtual-environment-hack",
          "text": "Exercise 2: Prototype an Isolated Virtual Environment Hack",
          "level": 3
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "how-do-you-make-the-verify-half-of-a-fix-verify-loop-something-you-enforce-not-something-the-agent-just-claims-it-did-when-an-agent-fixes-a-bug-what-s-the-deterministic-gate-that-proves-it-s-fixed-didn-t-regress",
          "text": "How do you make the verify half of a fix-verify loop something you enforce, not something the agent just claims it did? When an agent fixes a bug, what's the deterministic gate that proves it's fixed + didn't regress?",
          "level": 3
        },
        {
          "id": "you-use-the-word-boundaries-a-few-times-seems-like-you-have-a-visual-conceptual-meta-framework-to-think-about-how-to-control-and-steer-and-keep-tools-and-agents-and-plugins-scoped-properly-can-you-speak-to-this-your-way-of-thinking",
          "text": "you use the word boundaries a few times, seems like you have a visual conceptual meta-framework to think about how to control and steer and keep tools and agents and plugins scoped properly, can you speak to this, your way of thinking?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Verify fixes with deterministic evidence and narrow boundaries\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is turning agent failures into better tooling: capture the exact terminal state, feed it back into the agent or plugin workspace, patch for that fail case, then verify with hard evidence instead of trusting a happy-sounding completion message. John also zooms out into a boundary model: keep worker agents narrow, isolated, and tool-limited; let a context-rich orchestrator coordinate them; and aggressively reduce context for single-purpose daemon-style tasks.\n\n## Working outcomes\n\n- Extract terminal pane text in CMUX as machine-readable context\n- Build self-improvement error loops behind log-based deterministic gates\n- Define natural-language contract boundaries and prune context\n\n## Concepts and consequences\n\n### Terminal text extraction as context\n\nJohn shows a CMUX shortcut, Cmd-Opt-Shift-J in his setup, that takes the current terminal session and opens it as plain selectable text in an editor-like pane. Instead of fighting terminal scrollback, colors, and selection behavior, he copies the exact failure state and uses it as agent context.\n\n**Why it matters:** The fastest debugging loop starts with the real failure, not a vague summary of what you think happened.\n\n### Self-improvement error loops\n\nWhen a plugin or hook fails, John copies the failed session text and asks the agent to explain why the plugin failed in that scenario and how to account for it next time. The point is not just to fix one run, but to use the exact fail case to harden the tool or workflow.\n\n**Why it matters:** Tooling compounds when each failure leaves behind a stronger hook, workflow, or guardrail.\n\n### Log-based deterministic gates\n\nJohn's default answer to verification is to write logs or other artifacts to files. Depending on the project, those artifacts might show that a file was created, an API call happened, an object had the expected shape, timestamps were recorded, or multiple sessions produced comparable outputs. A main agent can wait for worker sessions to finish, inspect the logs and text output, and compare them against the criteria.\n\n**Why it matters:** Agents are useful reviewers, but artifacts are the evidence. Logs make fix-verify loops inspectable instead of trust-based.\n\n### Natural-language contract boundaries\n\nJohn frames modules, tools, and CLIs as boundaries that agents can own. A master orchestrator can hold broader project context and spin up focused agents, while each worker gets a narrow task, limited tools, and a clear English instruction payload. He compares this to API contracts, except the handoff can be natural language sent to an agent.\n\n**Why it matters:** Narrow agents are faster, easier to inspect, cheaper to run, and less likely to get distracted by unrelated context.\n\n### Context pruning for low-latency daemons\n\nThe codex-daemons demo shows an advanced experiment in stripping agent startup context. John redirects the Codex home directory, symlinks the needed auth file, disables memories, MCP servers, web search, and Agents.md/project rules, and runs hyper-specific daemon commands on Codex Spark Low by default. He also shows SDK thread warm-up so the first prompt can skip several seconds of startup work.\n\n**Why it matters:** For repetitive, well-scoped CLI-style tasks, less context can mean faster responses, lower quota pressure, and fewer distractions.\n\n## Reference tools and resources\n\n### codex-daemons\n\nJohn's open-source project for low-context, single-purpose Codex daemon commands.\n\n**Use when:** Reach for it when you want to study the virtual CODEX_HOME pattern, auth.json symlink approach, disabled context sources, Codex Spark Low usage, and warmed SDK thread pattern.\n\n[Reference](https://github.com/johnlindquist/codex-daemons)\n\n### CMUX\n\nThe terminal and agent workspace John uses to run panes, capture terminal sessions as text, and coordinate agent workflows.\n\n**Use when:** Reach for it when you want pane-based agent workspaces, terminal text capture, or agent-driven terminal/browser automation.\n\n[Reference](https://github.com/manaflow-ai/cmux)\n\n### GitHub CLI\n\nThe GitHub command-line tool used as the target of John's Pro GH daemon example.\n\n**Use when:** Reach for it when a narrow daemon or agent should perform GitHub-specific tasks such as summarizing recent commits.\n\n[Reference](https://cli.github.com)\n\n### Better Plugins / Ralph hook example\n\nThe workshop plugin-hook workspace John used to show a Python Ralph hook, local validation, and agent-driven scenario testing.\n\n**Use when:** Reach for it when you want examples of building hooks, installing them into an agent environment, and verifying them against a few scenarios.\n\nsearch: John Lindquist Better Plugins Ralph hook\n\n## Recommendations and best practices\n\n- When an agent, hook, or plugin fails, capture the exact terminal output first; do not summarize from memory unless you have no other option.\n- Use a repair prompt shape like: state the goal, paste the failure text after a colon, then ask the agent to explain why it failed and account for that case next time.\n- Make verification concrete by writing logs or files that record what actually happened: API calls, object shapes, timestamps, terminal outputs, or whatever criteria your project requires.\n- For multi-session verification, let the main agent wait for worker sessions to finish, inspect their logs and text outputs, and compare them against the criteria.\n- Avoid giant all-knowing worker sessions for execution work. Keep the orchestrator context-rich, but make worker agents narrow, tool-limited, and easy to audit.\n- Before fanning work out across agents, scope which tasks can be isolated, which tools each worker should use, and which boundaries define ownership.\n- Treat CODEX_HOME redirection, auth.json symlinks, disabled memories/MCP/web search/Agents.md, model overrides, and warmed SDK threads as advanced experimental patterns; test what works in your own setup.\n\n## Practice and acceptance criteria\n\nPractice capturing real failures, turning them into repair prompts, verifying work with artifacts, and designing narrow worker agents with clear boundaries.\n\n### Checklist\n\n1. Pick one local script, hook, or CLI workflow that occasionally fails and identify a real or intentionally created fail case.\n2. Run the scenario in CMUX or your terminal, then capture the exact terminal output as clean text using Cmd-Opt-Shift-J or an equivalent scrollback export.\n3. Write a repair prompt with three parts: the goal, the raw failure text after a colon, and an instruction to explain the failure and account for it next time.\n4. Add logging to the workflow that records what it actually did, such as relevant API calls, object shapes, timestamps when useful, outputs, or errors.\n5. Run a few scenarios or sessions that match the criteria you care about verifying.\n6. Use a supervisor prompt or verifier script to read the logs and text outputs, then compare them against your criteria instead of accepting the worker agent's completion message.\n7. Draft a natural-language contract for the worker agent: what it owns, which tools it may use, what inputs it receives, what outputs it must produce, and what context it does not need.\n\n### Failure Capture Drill\n\n**Difficulty:** Easy\n\nBreak a small local script on purpose, capture the exact terminal failure as clean text, and use it to ask Codex to explain the cause and patch the code. Do not summarize the error manually.\n\n**Done when:** The repaired script handles the original failure case, and your prompt includes the raw captured output rather than a vague description.\n\n### Log Comparison Gate\n\n**Difficulty:** Medium\n\nAdd file logging to one hook or CLI workflow, then run three sessions or scenarios and save one log artifact per run. Include the facts your project needs to verify the run, such as an API call, object shape, result, error, timestamp, or terminal output.\n\n**Done when:** A verifier or supervisor agent can read the log files and clearly compare each run against the expected criteria without relying on the worker agent's chat response.\n\n### Boundary Contract Map\n\n**Difficulty:** Medium\n\nChoose a feature in one of your projects and split the work into an orchestrator plus two or three narrow worker agents. For each worker, write its natural-language contract, allowed tools, out-of-scope areas, required inputs, and required outputs.\n\n**Done when:** Another developer could read the map and know which agent owns each part of the work, where handoffs happen, and what context should be pruned from each worker.\n\n### Low-Context Daemon Prototype\n\n**Difficulty:** Hard\n\nStudy or prototype a small wrapper around a CLI-style target such as GitHub CLI or CMUX. Isolate the agent context as much as your tooling allows: redirect the home/config context, symlink only the required auth/config if needed, disable extra context sources where possible, and compare behavior against your normal setup.\n\n**Done when:** You can show a before-and-after comparison of startup context, speed, or focus, and you have documented which parts of the setup are experimental or hacky.\n\n## Questions to test understanding\n\n### A hook fails in a CMUX terminal pane and prints a long stack trace. What should you do first if you want the fastest useful self-improvement loop?\n\n- **A.** Capture the exact terminal text and feed it back to the agent as context.\n- **B.** Ask the agent to guess what probably happened from a short summary.\n- **C.** Restart the session and hope the failure disappears.\n- **D.** Install more tools into the agent environment before debugging.\n\n**Answer: A.** The lesson emphasizes starting from the real failure state, not memory or vibes. Clean terminal extraction gives the agent precise evidence to explain and patch against.\n\n### What makes a log-based deterministic gate stronger than an agent's completion claim?\n\n- **A.** The log file sounds more official than chat text.\n- **B.** Logs can record inspectable facts that another process or supervisor can compare.\n- **C.** Logs prevent all future bugs automatically.\n- **D.** The worker agent cannot read log files, so it has less context to misuse.\n\n**Answer: B.** John's default is to create artifacts agents can inspect: logs, files, timestamps, object shapes, API-call evidence, and session outputs. A supervisor can compare those artifacts instead of trusting a natural-language claim.\n\n### In this lesson's boundary model, what should the master orchestrator usually do?\n\n- **A.** Run every task directly with every available tool.\n- **B.** Hold broad project context, split work, and assign narrow tasks to isolated agents.\n- **C.** Disable all logging so agents rely on reasoning alone.\n- **D.** Give every worker the full repository, memories, browser access, and MCP servers.\n\n**Answer: B.** The orchestrator keeps the big picture and coordinates work. Worker agents should be small, tool-limited, and scoped to clear natural-language contracts.\n\n### Why would a Codex daemon use a redirected home directory and disable memories, MCP servers, web search, and project rules?\n\n- **A.** To make the agent more creative by hiding all instructions.\n- **B.** To reduce startup context and keep a single-purpose daemon fast and focused.\n- **C.** To bypass the need for authentication completely.\n- **D.** To make logs unnecessary because the model has fewer distractions.\n\n**Answer: B.** Context pruning removes baggage for repetitive, well-scoped tasks. John framed the codex-daemons setup as an advanced experiment involving a fake Codex home directory, an auth.json symlink, disabled context sources, and a low-reasoning default model.\n\n### Which prompt shape best matches the lesson's repair loop?\n\n- **A.** Fix this, it failed somehow.\n- **B.** Here is the goal, here is the exact failure text, explain why it failed and account for this case next time.\n- **C.** Ignore the stack trace and rewrite the whole project from scratch.\n- **D.** Tell me the issue is resolved after editing the first related file you find.\n\n**Answer: B.** The useful loop combines goal, exact failure evidence, diagnosis, and durable workflow hardening. The point is not only to fix one bug, but to prevent the same class of failure from returning.\n\n## Reflection prompts\n\n- Where in your current workflow are you still trusting an agent's claim instead of checking an artifact?\n- Which agent tasks in your projects would get faster or safer if they had less context, not more?\n- What log output would let an orchestrator compare multiple runs against your actual success criteria?\n\n## Further applications\n\n1. Build a tiny local failed-session library: save terminal captures into dated files, then use them as regression prompts when improving hooks.\n2. Prototype a deterministic gate for one workflow: run a few sessions or scenarios, write a log artifact for each run, and compare expected criteria versus actual outputs.\n3. Create a natural-language contract map for your project: list each module, the agent that owns it, the tools it may use, and the inputs and outputs it should exchange.\n4. Experiment with a single-purpose daemon around a demonstrated CLI-style target such as GitHub CLI or CMUX, and measure whether reduced context improves speed, focus, or reliability.\n5. Add logs, tracing, or telemetry around boundary crossings so an agent can inspect when work reached outside its intended scope.\n\n## Applied exercises\n\n### Exercise 1: Build a Manual Error-Recovery Loop\n\n**Objective:**  Practice stripping terminal artifacts and running a recovery loop using John's approach.\n\n**Steps:** Intentionally break a local script or hook so it throws an active stack trace or error block in your terminal workspace.Use your environment's clean text export option (or the CMUX Cmd-Opt-Shift-J shortcut) to capture the raw error text without terminal escape characters.Draft an explicit repair prompt using John's structure: outline the overarching goal, paste the error after a colon separator, and instruct an agent to modify the code file to handle the edge case.\n\n### Exercise 2: Prototype an Isolated Virtual Environment Hack\n\n**Objective:**  Build a basic shell wrapper script that mimics the token-saving isolation strategy of codex-daemons.\n\n**Steps:** Write a shell script wrapper for your local development tool of choice.Inside the script, temporarily override the tool's core path variable or home folder directory target (ENV_HOME) to a completely empty temporary directory (/tmp/isolated_sandbox).Explicitly symlink only your core API key configuration file into that temporary sandboxed folder.Run a test command through the wrapper. Verify that the agent no longer scans your main project's workspace rule files or local database histories, matching the clean-slate daemon setup.\n\n## Questions and answers\n\n### How do you make the verify half of a fix-verify loop something you enforce, not something the agent just claims it did? When an agent fixes a bug, what's the deterministic gate that proves it's fixed + didn't regress?\n\nJohn recommends relying on structured logs written directly to disk. These files act as multi-agent-readable verification artifacts that track data shapes and API timing signatures. A supervisor agent can run parallel worker blocks, wait for completion, and compare files to programmatically confirm structural success without trusting the worker agent's natural language updates.\n\n### you use the word boundaries a few times, seems like you have a visual conceptual meta-framework to think about how to control and steer and keep tools and agents and plugins scoped properly, can you speak to this, your way of thinking?\n\nJohn advises against loading too many marketplace tools into a single agent context. His approach uses a highly context-aware master orchestrator that manages project goals alongside hyper-isolated sub-agents running small token footprints. This forms natural language contract boundaries across layers, mimicking decoupled microservice modules.\n\n## Operational playbooks\n\n- [Self-improving log-gated fix loop](/topics/foundations-log-gated-playbook/)\n\n- [Browser Proof Field Guide](/topics/foundations-browser-proof-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-08.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-08.html)\n\n### Visual reference index\n\n- [03:34:58](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-1): CMUX shortcut changes active window layout into a clean plain text editor block.\n- [03:36:12](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-2): Workspace view with terminal/log text and the live typing-game dashboard visible, useful for the self-improvement loop context.\n- [03:38:22](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-3): IDE displays a custom python-based implementation file of a Ralph hook.\n- [03:39:45](https://codex-workshop-followup.pages.dev/lesson-08.html#clip-08-4): Dark terminal/editor view during the prompt-structure discussion; keep exact prompt-pattern claims tied to transcript evidence.\n- [03:48:02](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal/browser workspace during the transition into codex-daemons; repository URL remains confirmed by chat.\n- [03:49:48](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal logs screen view of the Pro GH utility streaming a low-latency commit overview.\n- [03:52:12](https://codex-workshop-followup.pages.dev/lesson-08.html): Code display tracking the virtualized home directory environment overrides inside the daemon root folder.\n- [03:53:15](https://codex-workshop-followup.pages.dev/lesson-08.html): Configuration block code showing flags explicitly setting memories, mcp, and web search options to false.\n- [03:54:18](https://codex-workshop-followup.pages.dev/lesson-08.html): Orchestration logic view tracking background handshake mechanisms used to warm up active SDK execution threads.\n- [03:55:38](https://codex-workshop-followup.pages.dev/lesson-08.html): Terminal workspace after the CMUX pane command, showing split-pane execution context."
    },
    {
      "id": "factory-video-analysis-reference",
      "slug": "video-analysis-reference",
      "title": "Video analysis recipes, prompts, and evidence gates",
      "summary": "Complete media-normalization commands, long/short analysis branches, omission and reconciliation prompts, keyframe procedures, and publication evidence gates.",
      "category": "Verification",
      "tags": [
        "video",
        "prompts",
        "ffmpeg",
        "evidence",
        "oracle"
      ],
      "sources": [
        {
          "label": "Published repeatable video reference",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle-video/references/repeatable-video-followup-process.md"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Long Recording Workflow",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Short Recording Workflow",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Gemini Readiness And Failure Recovery",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Gemini Browser Cleanup",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Prompt Templates",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Verification Gates",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Keyframes",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Final Packet Review",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Project Setup",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Run Config",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Mode Matrix",
        "08-oracle-video/skills/oracle-video/references/repeatable-video-followup-process.md#Decision Tree"
      ],
      "collection": "factory",
      "categoryId": "verification",
      "wordCount": 3758,
      "url": "/topics/factory-video-analysis-reference/",
      "markdownUrl": "/markdown/factory-video-analysis-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-video-analysis-reference.json",
      "headings": [
        {
          "id": "prerequisites-and-safe-local-setup",
          "text": "Prerequisites and safe local setup",
          "level": 2
        },
        {
          "id": "run-config",
          "text": "Run Config",
          "level": 2
        },
        {
          "id": "mode-matrix",
          "text": "Mode Matrix",
          "level": 2
        },
        {
          "id": "decision-tree",
          "text": "Decision Tree",
          "level": 2
        },
        {
          "id": "long-recording-workflow",
          "text": "Long Recording Workflow",
          "level": 2
        },
        {
          "id": "short-recording-workflow",
          "text": "Short Recording Workflow",
          "level": 2
        },
        {
          "id": "gemini-readiness-and-failure-recovery",
          "text": "Gemini Readiness And Failure Recovery",
          "level": 2
        },
        {
          "id": "gemini-browser-cleanup",
          "text": "Gemini Browser Cleanup",
          "level": 2
        },
        {
          "id": "prompt-templates",
          "text": "Prompt Templates",
          "level": 2
        },
        {
          "id": "gemini-chunk-analysis",
          "text": "Gemini Chunk Analysis",
          "level": 3
        },
        {
          "id": "omissions-pass",
          "text": "Omissions Pass",
          "level": 3
        },
        {
          "id": "local-reconciliation",
          "text": "Local Reconciliation",
          "level": 3
        },
        {
          "id": "short-clip-analysis",
          "text": "Short Clip Analysis",
          "level": 3
        },
        {
          "id": "final-packet-generation",
          "text": "Final Packet Generation",
          "level": 3
        },
        {
          "id": "oracle-review",
          "text": "Oracle Review",
          "level": 3
        },
        {
          "id": "verification-gates",
          "text": "Verification Gates",
          "level": 2
        },
        {
          "id": "keyframes",
          "text": "Keyframes",
          "level": 2
        },
        {
          "id": "final-packet-review",
          "text": "Final Packet Review",
          "level": 2
        }
      ],
      "markdown": "# Video analysis recipes, prompts, and evidence gates\n\nComplete portable procedures for preparing analysis media, proving video understanding, extracting and reconciling evidence, and reviewing a follow-up packet. These are reference recipes—not a claim that this knowledge base independently processed the recording. Commands use generic local run paths; raw logs and source conversations remain private.\n\nThe short-clip and follow-up-packet prompts retain their original output audience as task examples for teammates preparing those materials. They are not instructions to publish unreviewed source data.\n\n## Prerequisites and safe local setup\n\nUse a dedicated, existing Git repository for the analysis artifacts—not the source software project. Install `ffmpeg`, `ffprobe`, `git`, `jq`, `python3`, and a SHA-256 utility (`shasum` in these examples) before starting. The later consult stages additionally require the configured Oracle browser workflow, Packx, and a signed-in Gemini browser profile; the setup below does not configure accounts or read credentials.\n\nRun the setup in Bash and keep the same shell for later snippets, so `RUN_ID` and `RUN_DIR` remain defined. Set `SOURCE_VIDEO` to your existing source MP4 and `RUN_ID` to a new, simple label first. Missing values, invalid labels, absent media, and an existing run directory stop before creating or overwriting a run. Optional transcript/chat inputs must be separately approved for local processing and remain private until reviewed and redacted.\n\n```bash\nset -euo pipefail\n: \"${SOURCE_VIDEO:?Set SOURCE_VIDEO to an existing source MP4}\"\n: \"${RUN_ID:?Set RUN_ID to a new analysis label}\"\ncase \"$RUN_ID\" in\n  ''|*[!a-zA-Z0-9_-]*) printf 'RUN_ID must contain only letters, digits, underscore, or hyphen\\n' >&2; exit 1 ;;\nesac\nPROJECT_ROOT=\"$(git rev-parse --show-toplevel)\"\ncd \"$PROJECT_ROOT\"\ntest -f \"$SOURCE_VIDEO\"\nRUN_DIR=\"$PROJECT_ROOT/runs/$RUN_ID\"\nif test -e \"$RUN_DIR\"; then\n  printf 'Run already exists: %s\\n' \"$RUN_DIR\" >&2\n  exit 1\nfi\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,segments,break-chat,chunks,oracle/sessions,final,publication}\ngit status --short > \"$RUN_DIR/receipts/git-status.before.txt\"\ncp \"$SOURCE_VIDEO\" \"$RUN_DIR/inputs/source-video.mp4\"\nif test -n \"${SOURCE_TRANSCRIPT:-}\"; then\n  cp \"$SOURCE_TRANSCRIPT\" \"$RUN_DIR/inputs/transcript.vtt\"\nfi\nif test -n \"${SOURCE_CHAT:-}\"; then\n  cp \"$SOURCE_CHAT\" \"$RUN_DIR/inputs/chat.txt\"\nfi\n```\n\nThe original media remains untouched. The following receipt commands record tool versions, checksums, and media properties; they do not establish that Gemini can read the attachment. That requires the later source-specific probes. Keep raw inputs and receipts private; committing a local receipt is not authorization to push it or publish it.\n\nRecord tool versions:\n\n```bash\n{\n  echo \"# Tool Versions\"\n  echo\n  echo \"date: $(date -u +%Y-%m-%dT%H:%M:%SZ)\"\n  echo\n  echo \"## ffmpeg\"\n  ffmpeg -version | head -n 3 || true\n  echo\n  echo \"## ffprobe\"\n  ffprobe -version | head -n 3 || true\n  echo\n  echo \"## git\"\n  git --version || true\n  echo\n  echo \"## jq\"\n  jq --version || true\n  echo\n  echo \"## python\"\n  python3 --version || true\n} > \"$RUN_DIR/receipts/tool-versions.txt\"\n```\n\nHash source assets and save file list:\n\n```bash\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" > \"$RUN_DIR/inputs/source-video.sha256\"\nfind \"$RUN_DIR/inputs\" -maxdepth 2 -type f -print0 \\\n  | xargs -0 shasum -a 256 \\\n  > \"$RUN_DIR/receipts/source-file-list.txt\"\n```\n\nProbe the source video:\n\n```bash\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nCreate a human-readable media receipt:\n\n```bash\n{\n  echo \"# Media Info\"\n  echo\n  echo \"source: $RUN_DIR/inputs/source-video.mp4\"\n  echo \"sha256: $(cut -d ' ' -f1 \"$RUN_DIR/inputs/source-video.sha256\")\"\n  echo\n  jq -r '.format | \"- duration: \\(.duration)\\n- size: \\(.size)\\n- bit_rate: \\(.bit_rate)\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n  echo\n  echo \"## Streams\"\n  jq -r '.streams[] | \"- index=\\(.index) type=\\(.codec_type) codec=\\(.codec_name) duration=\\(.duration // \"unknown\") width=\\(.width // \"-\") height=\\(.height // \"-\")\"' \\\n    \"$RUN_DIR/receipts/ffprobe.source.json\"\n} > \"$RUN_DIR/receipts/media-info.md\"\n```\n\n\n## Run Config\n\nCreate `$RUN_DIR/run-config.json` before processing. Set `run_id` to the same value as `RUN_ID`, and set unavailable optional transcript/chat paths to `null`:\n\n```json\n{\n  \"run_id\": \"example-workshop\",\n  \"title\": \"Example Workshop\",\n  \"mode\": \"long_workshop\",\n  \"source\": {\n    \"video\": \"inputs/source-video.mp4\",\n    \"transcript\": \"inputs/transcript.vtt\",\n    \"chat\": \"inputs/chat.txt\",\n    \"screenshots\": \"inputs/screenshots\",\n    \"clips\": \"inputs/clips\"\n  },\n  \"policy\": {\n    \"preserve_original_timestamps\": true,\n    \"canonical_chapters\": \"semantic\",\n    \"canonical_chapter_max_minutes\": 30,\n    \"analysis_shard_target_minutes\": 4,\n    \"analysis_shard_max_minutes\": 4,\n    \"analysis_attachment_target_mib\": 9,\n    \"analysis_media\": \"h264-main-yuv420p-29.97fps-aac-lc-44.1khz-faststart\",\n    \"dead_space_removal\": \"only verified long silence plus transcript/chat break evidence\",\n    \"default_video_overlap_seconds\": 0,\n    \"semantic_boundary_overlap_seconds\": 5,\n    \"qa_boundary_overlap_seconds\": 15,\n    \"chat_carry_forward\": true,\n    \"dedupe_final_materials\": true,\n    \"large_binary_git_policy\": \"local-only-unless-explicitly-approved\"\n  },\n  \"outputs\": {\n    \"student_packet\": true,\n    \"keyframes\": true,\n    \"contact_sheets\": true,\n    \"verification_reports\": true\n  }\n}\n```\n\n## Mode Matrix\n\n| Mode | Typical input | Segmentation | Transcript/chat | Keyframes | Gemini video pass | Output |\n|---|---|---:|---:|---:|---:|---|\n| Long workshop | 2-8 hour Zoom/workshop recording | Required | Required if available | Required | Required | Full student packet |\n| Medium tutorial | 20-60 minute lesson | Optional semantic chunks | Transcript required, chat optional | Recommended | Required when deriving facts from video | Guide, chapter index, resources |\n| Short bug reproduction | 30 sec-8 min screen recording | Skip | Optional | Required | Required for observed behavior | Bug report, repro steps, implementation brief |\n| Quick design feedback | 1-12 min screen and voice | Skip | Recommended if voiceover matters | Required | Required for visual/audio claims | Design-change brief, QA checklist |\n| Raw app walkthrough | 5-30 min app demo | Skip under 12 min; segment over 20 min | Recommended | Required | Required for requirements/QA extraction | Requirements doc, acceptance criteria |\n\n\"Optional\" applies only to extra Oracle planning/review over text artifacts. It does\nnot mean the video-watching step can be skipped when the deliverable depends on what\nis visible or audible in the recording.\n\n## Decision Tree\n\nSegment when any of these are true:\n\n- Video duration is over 30 minutes.\n- There are real breaks, lunch, pre-roll, or dead air.\n- Q&A spans topic transitions.\n- Chat must be aligned to the video.\n- The target output is a course packet, student packet, chapter index, or publication bundle.\n\nSkip segmentation when all of these are true:\n\n- Video duration is 12 minutes or less.\n- There is no long dead air or break.\n- Chat is absent, irrelevant, or small enough to include directly.\n- One model pass can analyze the whole video reliably.\n- The target output is a short note, bug report, design feedback memo, or compact implementation plan.\n\nUse a medium path when the video is 12-45 minutes, has no real breaks, and has 2-4 obvious sections. In that case, keep one physical video and create timestamped sections unless model upload/runtime gets awkward.\n\nRemove a video span only when long silence or inactive-screen evidence, transcript evidence, and chat evidence agree that the span is a break or dead space. Never discard chat from a removed span. Save it in `break-chat/` and carry it forward to the next spoken chunk when it contains a question, answer, link, or context used later.\n\nExtract keyframes when screen share, terminal commands, browser pages, demos, design feedback, or visual claims appear. Skip keyframes only for pure audio/talking-head content where visual evidence cannot change the output.\n\nRun an omissions pass when coverage is incomplete, missing URLs exist, missing chat questions exist, keyframe candidates are thin, machine JSON is missing/unparseable, timestamps are out of range, or hallucination checks find invented tools/links/commands.\n\n\n## Long Recording Workflow\n\n1. Detect silence:\n\n```bash\nffmpeg -hide_banner -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -af silencedetect=noise=-35dB:d=5 \\\n  -f null - 2> \"$RUN_DIR/analysis/silencedetect-35db-5s.log\"\n```\n\n2. Draft `analysis/boundary-candidates.md` from silence, transcript, and chat evidence.\n\n3. Create `segments/segment-manifest.v1.json` and `.md`. Preserve original timestamps.\n   Define semantic chapters under 30 minutes for the canonical teaching structure, but\n   define separate technical analysis shards no longer than four minutes until a\n   source-specific production-shard probe proves a longer duration safe. Map each shard\n   back to its canonical chapter. Remove break spans only when evidence supports removal.\n\n4. Run `$oracle` before finalizing segmentation when the run is long, public, or ambiguous. Bundle only text artifacts:\n\n```bash\nmkdir -p ~/.oracle/bundles\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --preview --no-interactive\n\nfind \"$RUN_DIR\" -type f \\( -name '*.md' -o -name '*.json' -o -name '*.log' -o -name '*.sh' \\) \\\n  | xargs packx --limit 900k -f markdown --no-interactive --stdout --strip-comments --minify \\\n  > ~/.oracle/bundles/video-followup-segmentation-review.txt\n\ntest -s ~/.oracle/bundles/video-followup-segmentation-review.txt\n```\n\nAsk Oracle in browser mode only. If using the skill, invoke `$oracle`; if using the CLI fallback, keep browser mode explicit:\n\n```bash\noracle --engine browser \\\n  --model gpt-5.6-pro \\\n  --browser-thinking-time extended \\\n  --slug video-followup-segmentation-review \\\n  --file ~/.oracle/bundles/video-followup-segmentation-review.txt \\\n  -p \"$(cat \"$RUN_DIR/oracle/planning.md\")\"\n```\n\nSave the Oracle conversation URL, local bundle path, prompt, and `~/.oracle/sessions/<slug>/output.log` reference in `oracle/sessions/<slug>.md`.\n\n5. Revise into `segments/segment-manifest.v2.json` and `.md`.\n\n6. Cut archival chapters and Gemini analysis shards from the original source. A\n   stream-copy cut is acceptable only as an archival artifact; do not send stream-copy\n   chunks to Gemini by default. A file can pass `ffprobe` and still stall indefinitely\n   in Gemini.\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01\"\nSTART_SECONDS=344\nDURATION_SECONDS=240\nSOURCE=\"$RUN_DIR/inputs/source-video.mp4\"\nANALYSIS_SHARD=\"$RUN_DIR/chunks/01/chunk.mp4\"\n\nffmpeg -hide_banner -loglevel error -y \\\n  -ss \"$START_SECONDS\" -i \"$SOURCE\" -t \"$DURATION_SECONDS\" \\\n  -map 0:v:0 -map 0:a:0 \\\n  -vf 'fps=30000/1001,format=yuv420p' \\\n  -c:v libx264 -preset veryfast -crf 30 -profile:v main \\\n  -c:a aac -b:a 80k -ar 44100 -ac 2 \\\n  -movflags +faststart \"$ANALYSIS_SHARD\"\n\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/chunks/01/chunk.mp4\" \\\n  > \"$RUN_DIR/chunks/01/chunk.ffprobe.json\"\n```\n\nKeep every shard below the configured Oracle attachment ceiling. When the ceiling is\n10 MiB, target <=9 MiB. Avoid low-fidelity derivatives such as 4 fps video or 24 kHz\nmono audio: they may upload, then become `This file has been removed` or unreadable.\nAfter any encoding change, rerun the source-specific audio+visual probe before batching.\n\n7. Slice transcript and chat into `chunks/<nn>/transcript.md`, `chat.md`, and `carry-forward-chat.md`.\n\n8. Create `chunks/video-manifest.json` with chunk id, original range, file path, transcript path, chat path, carry-forward path, ffprobe path, and verification status.\n\n## Short Recording Workflow\n\nUse this path for quick screen captures, short bug reproductions, design notes, and small app walkthroughs.\n\n```bash\nRUN_ID=\"$(date +%Y-%m-%d)-quick-clip\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,chunks/01,final}\ncp \"/absolute/path/to/clip.mov\" \"$RUN_DIR/inputs/source-video.mov\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mov\" > \"$RUN_DIR/inputs/source-video.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mov\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor short clips, use the source directly only after `ffprobe` plus the source-specific\naudio+visual probe confirms Gemini can retain and read it. Otherwise create the same\nH.264 Main/yuv420p/AAC-LC/faststart analysis encode used by the long workflow. Do not\ndownsample to 4 fps or 24 kHz mono merely to reduce size.\n\n```bash\nln -s ../../inputs/source-video.mov \"$RUN_DIR/chunks/01/chunk.mov\"\n```\n\nCreate `chunks/01/gemini-prompt.md` using the short clip prompt in this doc, attach the clip directly to Gemini/video model, and save:\n\n```text\nchunks/01/expected-sentinel.txt\nchunks/01/gemini-run.log\nchunks/01/gemini-result.json\nchunks/01/gemini-analysis.md\nchunks/01/final-reconciled.md\nfinal/README.md\n```\n\nFinal output by short mode:\n\n- Bug reproduction: `final/bug-report.md`, `final/repro-steps.md`, `final/acceptance-checks.md`\n- Design feedback: `final/design-brief.md`, `final/visual-acceptance-criteria.md`\n- App walkthrough: `final/requirements.md`, `final/qa-checklist.md`\n- Tiny tutorial: `final/summary.md`, `final/resources-and-links.md`\n\nRun the same malformed URL and hallucination checks even for short clips.\n\nFor YouTube research batches, add these source-selection rules before downloading:\n\n- Search broadly, but select by actual YouTube metadata (`upload_date`), not title text.\n- Enforce user cutoffs exactly. Use an explicit cutoff parameter, e.g.\n  `upload_date >= cutoff_yyyymmdd`.\n- Exclude topic collisions, coupon/affiliate uploads, auto-generated music/topic\n  uploads, and unrelated videos.\n- Save selected videos in `queue.json` with `id`, `title`, `uploader`,\n  `upload_date`, `duration`, and `url`.\n- Use Chrome cookies with `yt-dlp` when YouTube challenges require it.\n- Space Gemini upload starts by about five minutes for batch runs only after the first\n  attached-video probe passes and no unresolved run is pending, unless the user asks\n  for a different cadence.\n\nFor each batch item, use a topic-specific prompt. Do not copy old prompt text from a\ndifferent topic without replacing the product/domain language.\n\n## Gemini Readiness And Failure Recovery\n\nBefore a large batch, run two source-specific attached-video probes: a 30-60 second\nsource-native sample, then one production-size <=4 minute analysis shard using the real\nprompt shape. Each prompt must request one spoken phrase and one visual observation at\na specified timestamp, plus an alphabetic-ending sentinel. Independently verify the\nphrase against audio/captions and the visual observation against an extracted frame.\nDo not rely on a sentinel-only or text-only probe.\n\nRequired preflight receipts:\n\n- configured browser mode and Gemini provider routing;\n- visible signed-in Gemini UI and both completed attached-video probes;\n- prompt path and exact expected sentinel;\n- run/session metadata;\n- a real submitted `user-query` retaining its attachment chip/duration, with the prompt\n  absent from the composer and a `model-response` begun;\n- locally verified source-specific audio and visual facts plus the expected sentinel;\n- completed tab cleanup.\n\nOn any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit,\nor upload warning, stop new batch starts. Inspect the active Gemini tab, classify the\nstate, and retry only the affected chunk if no valid sentinel response exists.\n\nWrite the exact expected sentinel into `chunks/<nn>/expected-sentinel.txt` before each\nGemini run. Verification and recovery should compare against that file, not infer the\nsentinel shape from memory. End the sentinel with letters, for example\n`END_OF_VIDEO_ANALYSIS workshop SHARD_004_COMPLETE`, not a bare number that may be\nvisually joined to a following timestamp.\n\nOracle log lines such as `Attachment upload complete`, `Sending prompt`, and `still\ngenerating` are diagnostics, not proof. The live Gemini DOM is authoritative. A title,\nsidebar/body text match, empty composer, or broad `Stop` button match does not prove a\nsubmitted turn. Re-check state before long waits because an apparent turn can regress\nand return to the composer.\n\nFor liveness, snapshot the real `model-response message-content` text/HTML and\n`aria-busy` state 2-3 times over about three minutes. If content grows, keep waiting. If\nan `Analyzing`/`Gemini said` placeholder does not grow, record a confirmed stall, close\nonly that exact target, frame-exact re-encode the shard, and retry once. Do not loop the\nsame media bytes.\n\nOn a fresh `/app` conversation, the upload menu can initially be empty. Initialize the\nconversation with one harmless text turn, wait for completion, reopen the upload menu,\nthen run the actual source-specific video probe. The initializer is not video proof.\n\n## Gemini Browser Cleanup\n\nWhen using Oracle CLI fallback with `--browser-keep-browser`, cleanup is mandatory:\n\n1. Wait for the run to finish.\n2. Save every needed extraction artifact from the Gemini response:\n   `gemini-result.json`, `gemini-analysis.md`, `gemini-analysis.extracted.json` when\n   expected, machine JSON, and any recovery note if the response was recovered by tab\n   inspection.\n3. Verify the analysis is non-empty and contains the expected\n   `END_OF_VIDEO_ANALYSIS ...` sentinel.\n4. Close only the completed and fully extracted Gemini tab for that run.\n5. Do not close tabs for active uploads, still-generating sessions, unresolved wrapper\n   errors, or completed-looking tabs whose visible response has not been extracted.\n6. Do not kill Chrome; Oracle needs the signed-in profile for future runs.\n\nFor scripted runs, implement cleanup as a post-extraction step, not as a generic\n`finally` block. A safe script order is: save wrapper result, inspect/recover tab output\nif needed, write extracted JSON, verify the exact expected sentinel, then close the\nspecific Gemini tab target. If any extraction or sentinel check fails, leave the tab\nopen and record the Chrome port/target for recovery.\n\nIf exact target close tooling is available, use Chrome DevTools Protocol to close the\nspecific `gemini.google.com/app` target created for the run. If not, list tabs first,\nidentify completed or empty Gemini tabs, and close only those. Avoid broad \"close all\nGemini\" actions while a batch is running.\n\nThe Chrome target id returned by `/json/list` is different from the Gemini conversation\nid in `/app/<conversation-id>`. Close `/json/close/<target-id>`, then list targets again\nto prove removal. Do not pass the conversation-id suffix to the close endpoint.\n\nWhen classifying stale tabs:\n\n- Empty generic Gemini tabs from failed diagnostics may be closed after inspection.\n- Active upload/generation tabs must stay open.\n- Tabs with conversation state or auto-generated titles must be checked for saved\n  output and the expected sentinel before closing.\n- Never use broad \"close all Gemini tabs\" while a batch is active.\n\n## Prompt Templates\n\n### Gemini Chunk Analysis\n\n```markdown\nYou are analyzing one source-preserving video chunk for a follow-up packet.\n\nRun metadata:\n- run_key: {{run_key}}\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- chunk_video: {{chunk_video_path}}\n- transcript: included below\n- chat: included below\n- carry_forward_chat: included below\n- next_chunk_preview: included below\n\nHard rules:\n1. Preserve original recording timestamps.\n2. Separate transcript evidence, chat evidence, visual evidence, and inference.\n3. Do not invent tools, commands, URLs, files, speakers, or UI labels.\n4. Include unanswered and deferred questions.\n5. Flag every policy-sensitive area, especially browser automation, cookies, quota/rate limits, private accounts, and publishing.\n6. Return both Markdown and fenced JSON.\n7. End with: END_OF_VIDEO_ANALYSIS {{run_key}} {{chunk_id}}_COMPLETE\n\nReturn:\n# Chunk Analysis: {{chunk_id}}\n## 1. Overview\n## 2. Dense Timeline\n## 3. Concept Inventory\n## 4. Demo / Screen Activity\n## 5. Questions And Answers\n## 6. Links / Tools / Commands / References\n## 7. Keyframes To Capture\n## 8. Student Exercises\n## 9. Uncertainties / Needs Review\n## 10. Machine JSON\n```\n\n### Omissions Pass\n\n```markdown\nYou are auditing a prior video analysis for omissions.\n\nInputs:\n- chunk_id: {{chunk_id}}\n- original_recording_range: {{start_time}} -> {{end_time}}\n- coverage_report: {{coverage_report}}\n- expected_items: {{expected_items_json}}\n- prior_analysis: {{prior_analysis}}\n\nFind only omissions and corrections. Do not repeat complete items.\n\nRequired focus:\n1. Missing URLs exactly as they appeared.\n2. Missing chat questions, including unanswered/deferred questions.\n3. Missing demo steps.\n4. Missing keyframe candidates.\n5. Unsupported visual claims.\n6. Hallucinated tools, commands, links, or files.\n7. Parseable fenced JSON.\n\nReturn:\n# Omissions And Corrections: {{chunk_id}}\n## Additions\n## Corrections\n## Remove Or Downgrade\n## Remaining Human Review\n## Machine JSON\n```\n\n### Local Reconciliation\n\n```markdown\nReconcile one analyzed chunk into an evidence-grounded final chunk record.\n\nInputs:\n- segment manifest entry\n- transcript slice\n- chat slice\n- carry-forward chat\n- main analysis\n- omissions analysis\n- verification reports\n- keyframe review\n\nRules:\n1. Preserve original timestamps.\n2. Remove malformed URLs.\n3. Do not include any URL/tool/command unless supported by transcript, chat, carry-forward chat, local path, or keyframe review.\n4. Do not claim a visual is visible unless keyframe review confirms it.\n5. Preserve unanswered/deferred questions.\n6. Preserve editorial warnings.\n7. Deduplicate overlap by normalized timestamp + item type + text hash.\n\nReturn Markdown and JSON with:\n- status: PASS | PASS_WITH_WARNINGS | FAIL\n- counts\n- timeline summary\n- concepts\n- Q&A\n- links/tools/commands\n- demos\n- keyframes\n- warnings\n- student-material candidates\n```\n\n### Short Clip Analysis\n\n```markdown\nYou are analyzing a short screen recording or app walkthrough.\n\nSource:\n- run_key: {{run_key}}\n- recording_type: short_clip | bug_reproduction | design_feedback | app_walkthrough\n- original_recording_range: 00:00:00 -> {{duration}}\n- source_video_sha256: {{source_video_sha256}}\n\nHard rules:\n1. Use timestamps relative to the clip unless an original recording timeline is provided.\n2. Do not invent commands, files, UI labels, URLs, or implementation details.\n3. Separate observed behavior from inferred intent.\n4. Include timestamped screenshot/keyframe candidates for visual claims.\n5. For a bug reproduction, produce repro steps and expected vs actual behavior.\n6. For design feedback, produce requested changes and visual acceptance criteria.\n7. For an app walkthrough, produce requirements and QA checks.\n8. Include uncertainties and manual review points.\n\nReturn:\n# Short Video Analysis: {{run_key}}\n## 1. Summary\n## 2. Observed Timeline\n## 3. User Intent / Requirements\n## 4. Reproduction Steps Or Walkthrough Steps\n## 5. Expected Vs Actual Behavior\n## 6. Implementation Notes\n## 7. QA / Acceptance Criteria\n## 8. Keyframes To Extract\n## 9. Risks / Unknowns\n## 10. Machine JSON\n```\n\n### Final Packet Generation\n\n```markdown\nAssemble a student follow-up packet from verified chunk records.\n\nInputs:\n- segments/segment-manifest.v2.md\n- chunks/*/final-reconciled.md\n- chunks/*/final-reconciled.json\n- chunks/*/verification/*.md\n- final/keyframes-manifest.json if present\n- resources extracted from chat/transcript\n\nRules:\n1. Use original recording timestamps.\n2. Do not include unverified visual claims.\n3. Do not include malformed URLs.\n4. Do not present experimental tools as official recommendations unless approved.\n5. Keep policy-sensitive automation/cookie/quota/rate-limit sections as editorial notes.\n6. Distinguish publication-ready files from reference drafts.\n7. Deduplicate overlap and carry-forward repeated material.\n\nCreate:\n- final/README.md\n- final/student-followup-guide.md\n- final/chapter-index.md\n- final/resources-and-links.md\n- final/qa-index.md\n- final/exercises.md\n- final/keyframes-manifest.md\n- final/keyframes-manifest.json\n- final/instructor-review-checklist.md\n```\n\n### Oracle Review\n\n```markdown\n[{{slug}}]\n\nProject briefing:\n{{project_briefing}}\n\nGoal:\n{{goal}}\n\nPrior-State Ledger:\n- prior_oracle_session: {{prior_oracle_session_or_none}}\n- last_oracle_recommendation: {{summary_or_none}}\n- implemented_since_prior_oracle: {{files_or_none}}\n- verified_since_prior_oracle: {{commands_or_none}}\n- failed_proof_or_blocker: {{receipt_or_none}}\n- narrowing_decision: {{one_slice}}\n- files_functions_now_in_scope: {{paths}}\n- files_functions_out_of_scope: {{paths}}\n- next_falsifiable_verification: {{command_or_receipt}}\n- forward_progress_index: {{score_and_arithmetic}}\n\nDeliverable:\nEvaluate segmentation, chat carry-forward, analysis prompts, verification gates, final packet readiness, privacy/security risks, and the one highest-leverage next local action.\n\nReturn your answer as text in this response only. Do not create, attach, export, or offer any downloadable file. Do not create local project artifacts yourself. The local agent will write any needed files, plans, notes, goals, commits, or verification logs using local tools.\n```\n\n## Verification Gates\n\nTreat `~/.oracle/sessions/<slug>/output.log`, browser logs, and raw Gemini responses as\nprivate evidence. The MCP return can be truncated, so recover the full response from\nthe persisted session log before reconciliation. Before copying any material into\n`publication/public-draft/` or another public wiki, scan and redact credentials,\nauth/callback URLs, account/model identifiers, local usernames and paths,\nsigned/private URLs, notifications, and personal data. Gemini can repeat these even\nwhen told not to.\n\nEvery pull quote and timestamp must be checked against local audio/captions and the\nsource frame or clip. Gemini-supplied quote timestamps are candidates, not receipts.\nRecord the verified timestamp and evidence path in the reconciliation artifact.\n\nRun malformed URL checks on every final packet:\n\n```bash\nrg -n 'https://www\\.\\.\\.|https://www\\s|/\"|\\| .*: \\||Context:' \"$RUN_DIR/final\" || true\n```\n\nExtract exact URLs from chat/transcript and compare against final resources:\n\n```bash\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/chunks\" \"$RUN_DIR/break-chat\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.expected-urls.txt\"\n\nrg -o 'https?://[^[:space:])>\"'\"'\"']+' \"$RUN_DIR/final/resources-and-links.md\" \\\n  | sed 's/[,:;.!\"]$//' \\\n  | sort -u \\\n  > \"$RUN_DIR/verification.final-urls.txt\"\n\ncomm -23 \"$RUN_DIR/verification.expected-urls.txt\" \"$RUN_DIR/verification.final-urls.txt\" \\\n  > \"$RUN_DIR/verification.missing-urls.txt\"\n```\n\nValidate timestamps stay within range, except carry-forward chat:\n\n```bash\npython3 scripts/validate-timestamps.py \"$RUN_DIR\" \\\n  > \"$RUN_DIR/receipts/timestamp-validation.log\"\n```\n\nIf the script does not exist yet, perform a manual timestamp pass and save it as `chunks/<nn>/verification/timestamp-report.md`.\n\nCheck machine JSON:\n\n```bash\nfind \"$RUN_DIR/chunks\" -name '*.json' -print0 | xargs -0 -n1 jq empty\n```\n\nRequired chunk gate files:\n\n```text\nchunks/<nn>/verification/coverage-report.md\nchunks/<nn>/verification/hallucination-report.md\nchunks/<nn>/verification/timestamp-report.md\nchunks/<nn>/verification/qa-report.md\nchunks/<nn>/final-reconciled.md\nchunks/<nn>/final-reconciled.json\n```\n\nChunk status meanings:\n\n- `PASS`: complete and publication-safe after ordinary instructor review.\n- `PASS_WITH_WARNINGS`: usable evidence, but warnings must be reviewed before publication.\n- `FAIL`: rerun analysis, omissions, or reconciliation before using the chunk.\n\n## Keyframes\n\nCandidate extraction prompt output should include timestamp, reason, expected visual, priority, and confidence.\n\nExtract deterministic frames:\n\n```bash\nmkdir -p \"$RUN_DIR/chunks/01/keyframes/extracted\"\nffmpeg -hide_banner -ss 00:23:48 \\\n  -i \"$RUN_DIR/inputs/source-video.mp4\" \\\n  -frames:v 1 \\\n  \"$RUN_DIR/chunks/01/keyframes/extracted/00-23-48-automation-verification.jpg\"\n```\n\nCreate contact sheet:\n\n```bash\nfind \"$RUN_DIR/chunks/01/keyframes/extracted\" -name '*.jpg' | sort \\\n  > \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\"\n\nffmpeg -hide_banner -f concat -safe 0 \\\n  -i <(sed \"s#^#file '#; s#$#'#\" \"$RUN_DIR/chunks/01/keyframes/contact-sheet-inputs.txt\") \\\n  -vf \"scale=320:-1,tile=3x4\" \\\n  \"$RUN_DIR/chunks/01/keyframes/contact-sheet.jpg\"\n```\n\nIf process substitution is unavailable, generate the concat list as a real file and pass it to ffmpeg.\n\n## Final Packet Review\n\nTreat these as first publication candidates:\n\n- `final/README.md`\n- `final/student-followup-guide.md`\n- `final/chapter-index.md`\n- `final/resources-and-links.md`\n- `final/instructor-review-checklist.md`\n\nTreat these as reference drafts until edited:\n\n- `final/qa-index.md`\n- `final/exercises.md`\n- `final/keyframes-manifest.md`\n\nManual approval is mandatory for:\n\n- platform automation\n- browser automation\n- cookies\n- session replay\n- quota/rate-limit behavior\n- account credentials\n- private emails\n- private chat exports\n- meeting transcript bot URLs\n- student names\n- screenshots of private repos\n- local network addresses\n- QR codes\n- API keys\n- package security claims\n- third-party service recommendations\n- public publishing"
    },
    {
      "id": "factory-tools-conversation-search",
      "slug": "tools-conversation-search",
      "title": "Agent conversation search (cs)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "conversation-search"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#conversation-search"
        }
      ],
      "sourceUnits": [
        "resources/index.html#conversation-search"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 317,
      "url": "/topics/factory-tools-conversation-search/",
      "markdownUrl": "/markdown/factory-tools-conversation-search.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-conversation-search.json",
      "headings": [
        {
          "id": "agent-conversation-search-cs",
          "text": "Agent conversation search (cs)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Agent conversation search (cs)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Agent conversation search (cs)\n\n**John uses:** `cs` — his personal conversation-search CLI (`cs <term> --recent -n 20`) over all local Claude/Codex/Grok session history; section 00's fact-check of a month-old field guide against ~1,978 oracle sessions ran on it. **We could not find a public repo for cs; treat it as personal/unreleased.**\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [cc-sessions-viewer](https://github.com/jerrywu001/cc-sessions-viewer) | Viewer for Claude Code/Codex/Antigravity/OpenCode sessions: global search, token stats, resume, HTML export | Closest public match: multi-agent session search in a UI rather than a grep-style CLI | none listed |\n| [claude-conversation-extractor](https://github.com/ZeroSumQuant/claude-conversation-extractor) | Extract clean conversation logs from Claude Code's internal storage | Extraction/export only — pipe the output into ripgrep for search; check current repository activity | MIT |\n| [llm logs (Simon Willison)](https://github.com/simonw/llm) | Every llm CLI prompt/response logged to SQLite; \\`llm logs -q\\` full-text search | Only covers conversations you run through llm, but the SQLite pattern is the most robust searchable-history design | Apache-2.0 |\n| [ripgrep over ~/.claude/projects and ~/.codex/sessions](https://github.com/BurntSushi/ripgrep) | Both Claude Code and Codex store sessions as local JSONL — rg searches them directly | The zero-tool option: \\`rg -l 'term' ~/.claude/projects\\` gets you 80% of cs today | MIT/Unlicense |\n| [ccusage](https://github.com/ccusage/ccusage) | npx ccusage — analytics over Claude Code local session data | Adjacent: usage/cost analytics over the same JSONL files, not content search | NOASSERTION |\n\n### Pick this if…\n\n- **ripgrep** — start here; it's 80% of `cs` with zero new tools.\n- **cc-sessions-viewer** — you want cross-agent search in a UI with resume/export (young project).\n- **claude-conversation-extractor** — you want clean markdown exports to feed other tools.\n- **llm logs** — you're building new habits and want history searchable by design.\n- **ccusage** — you want the cost/usage half of session mining."
    },
    {
      "id": "foundations-resources",
      "slug": "resources",
      "title": "Agent foundations resource index",
      "summary": "Public tools, command references, design resources, and contextual links grouped for practical use.",
      "category": "Tools",
      "tags": [
        "resources",
        "tools",
        "links"
      ],
      "sources": [
        {
          "label": "Agent foundations: Route large codebase questions through Oracle (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-01.html"
        },
        {
          "label": "Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-02.html"
        },
        {
          "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
        },
        {
          "label": "Agent foundations: Trust current source and capture design decisions (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-04.html"
        },
        {
          "label": "Agent foundations: Explore software through perspectives and runtime QA (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-05.html"
        },
        {
          "label": "Agent foundations: Use images, video, and task-shaped model routing (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-06.html"
        },
        {
          "label": "Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-07.html"
        },
        {
          "label": "Agent foundations: Verify fixes with deterministic evidence and narrow boundaries (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-08.html"
        },
        {
          "label": "Agent foundations: Build narrow daemons and inspectable agent graphs (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-09.html"
        },
        {
          "label": "Agent foundations: Combine intent, implementation, and output for autonomous work (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-10.html"
        },
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "materials/resources.md#ADB tools",
        "materials/resources.md#Agent Browser",
        "materials/resources.md#AI Gateway",
        "materials/resources.md#Antigravity",
        "materials/resources.md#beads",
        "materials/resources.md#BUN",
        "materials/resources.md#bun install",
        "materials/resources.md#Chrome DevTools MCP",
        "materials/resources.md#Claude Code",
        "materials/resources.md#Cloud Code",
        "materials/resources.md#Cmd-Opt-Shift-J",
        "materials/resources.md#CMUX",
        "materials/resources.md#CMUX open 3 panes and run LS in each of them",
        "materials/resources.md#Codex",
        "materials/resources.md#Codex Awesome Plugins",
        "materials/resources.md#Codex SDK",
        "materials/resources.md#Codex Spark Low",
        "materials/resources.md#Deep Wiki Map",
        "materials/resources.md#GitHub CLI",
        "materials/resources.md#GPT 5.5",
        "materials/resources.md#GrillMe",
        "materials/resources.md#https://askoracle.sh/",
        "materials/resources.md#https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm",
        "materials/resources.md#https://cmux.com/",
        "materials/resources.md#https://codex-trainer.johnlindquist.workers.dev/",
        "materials/resources.md#https://developers.openai.com/codex/hooks",
        "materials/resources.md#https://developers.openai.com/codex/plugins",
        "materials/resources.md#https://developers.openai.com/codex/plugins/build",
        "materials/resources.md#https://github.com/aurorascharff/ClickLight",
        "materials/resources.md#https://github.com/fayazara/Screendrop",
        "materials/resources.md#https://github.com/gastownhall/beads",
        "materials/resources.md#https://github.com/johnlindquist/better-plugins/tree/main/plugins",
        "materials/resources.md#https://github.com/johnlindquist/cmux-extensions",
        "materials/resources.md#https://github.com/johnlindquist/codex-daemons",
        "materials/resources.md#https://github.com/johnlindquist/oracle",
        "materials/resources.md#https://github.com/karpathy/autoresearch",
        "materials/resources.md#https://github.com/openclaw/gogcli",
        "materials/resources.md#https://github.com/vercel-labs/agent-browser",
        "materials/resources.md#https://impeccable.style/",
        "materials/resources.md#https://inspiration-board.pages.dev/",
        "materials/resources.md#https://n8n.io/",
        "materials/resources.md#https://stitch.withgoogle.com/",
        "materials/resources.md#https://www.aihero.dev/skills-grill-me",
        "materials/resources.md#https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1",
        "materials/resources.md#https://www.dev.build/comics/prompt-quest/0?page=5",
        "materials/resources.md#https://www.npmjs.com/package/packx",
        "materials/resources.md#https://www.youtube.com/watch?v=v4F1gFy-hqg",
        "materials/resources.md#LazyGit",
        "materials/resources.md#Notebook LM",
        "materials/resources.md#Oracle",
        "materials/resources.md#PackX",
        "materials/resources.md#PackX / pack tool",
        "materials/resources.md#Pro GH summarize my commits from the past 2 days",
        "materials/resources.md#ScreenPipe",
        "materials/resources.md#settings > apps > advanced settings",
        "materials/resources.md#skills.sh",
        "materials/resources.md#Tailwind CSS",
        "materials/resources.md#unlink",
        "materials/resources.md#Vercel AI SDK",
        "materials/resources.md#Vercel CLI",
        "materials/resources.md#Warp Terminal"
      ],
      "collection": "foundations",
      "categoryId": "tools",
      "wordCount": 856,
      "url": "/topics/foundations-resources/",
      "markdownUrl": "/markdown/foundations-resources.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-resources.json",
      "headings": [
        {
          "id": "adb-tools",
          "text": "ADB tools",
          "level": 2
        },
        {
          "id": "agent-browser",
          "text": "Agent Browser",
          "level": 2
        },
        {
          "id": "ai-gateway",
          "text": "AI Gateway",
          "level": 2
        },
        {
          "id": "antigravity",
          "text": "Antigravity",
          "level": 2
        },
        {
          "id": "beads",
          "text": "beads",
          "level": 2
        },
        {
          "id": "bun",
          "text": "BUN",
          "level": 2
        },
        {
          "id": "bun-install",
          "text": "bun install",
          "level": 2
        },
        {
          "id": "chrome-devtools-mcp",
          "text": "Chrome DevTools MCP",
          "level": 2
        },
        {
          "id": "claude-code",
          "text": "Claude Code",
          "level": 2
        },
        {
          "id": "cloud-code",
          "text": "Cloud Code",
          "level": 2
        },
        {
          "id": "cmd-opt-shift-j",
          "text": "Cmd-Opt-Shift-J",
          "level": 2
        },
        {
          "id": "cmux",
          "text": "CMUX",
          "level": 2
        },
        {
          "id": "cmux-open-3-panes-and-run-ls-in-each-of-them",
          "text": "CMUX open 3 panes and run LS in each of them",
          "level": 2
        },
        {
          "id": "codex",
          "text": "Codex",
          "level": 2
        },
        {
          "id": "codex-awesome-plugins",
          "text": "Codex Awesome Plugins",
          "level": 2
        },
        {
          "id": "codex-sdk",
          "text": "Codex SDK",
          "level": 2
        },
        {
          "id": "codex-spark-low",
          "text": "Codex Spark Low",
          "level": 2
        },
        {
          "id": "deep-wiki-map",
          "text": "Deep Wiki Map",
          "level": 2
        },
        {
          "id": "github-cli",
          "text": "GitHub CLI",
          "level": 2
        },
        {
          "id": "gpt-5-5",
          "text": "GPT 5.5",
          "level": 2
        },
        {
          "id": "grillme",
          "text": "GrillMe",
          "level": 2
        },
        {
          "id": "https-askoracle-sh",
          "text": "https://askoracle.sh/",
          "level": 2
        },
        {
          "id": "https-chromewebstore-google-com-detail-marksnip-webpage-to-markd-kcbaglhfgbkjdnpeokaamjjkddempipm",
          "text": "https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm",
          "level": 2
        },
        {
          "id": "https-cmux-com",
          "text": "https://cmux.com/",
          "level": 2
        },
        {
          "id": "https-codex-trainer-johnlindquist-workers-dev",
          "text": "https://codex-trainer.johnlindquist.workers.dev/",
          "level": 2
        },
        {
          "id": "https-developers-openai-com-codex-hooks",
          "text": "https://developers.openai.com/codex/hooks",
          "level": 2
        },
        {
          "id": "https-developers-openai-com-codex-plugins",
          "text": "https://developers.openai.com/codex/plugins",
          "level": 2
        },
        {
          "id": "https-developers-openai-com-codex-plugins-build",
          "text": "https://developers.openai.com/codex/plugins/build",
          "level": 2
        },
        {
          "id": "https-github-com-aurorascharff-clicklight",
          "text": "https://github.com/aurorascharff/ClickLight",
          "level": 2
        },
        {
          "id": "https-github-com-fayazara-screendrop",
          "text": "https://github.com/fayazara/Screendrop",
          "level": 2
        },
        {
          "id": "https-github-com-gastownhall-beads",
          "text": "https://github.com/gastownhall/beads",
          "level": 2
        },
        {
          "id": "https-github-com-johnlindquist-better-plugins-tree-main-plugins",
          "text": "https://github.com/johnlindquist/better-plugins/tree/main/plugins",
          "level": 2
        },
        {
          "id": "https-github-com-johnlindquist-cmux-extensions",
          "text": "https://github.com/johnlindquist/cmux-extensions",
          "level": 2
        },
        {
          "id": "https-github-com-johnlindquist-codex-daemons",
          "text": "https://github.com/johnlindquist/codex-daemons",
          "level": 2
        },
        {
          "id": "https-github-com-johnlindquist-oracle",
          "text": "https://github.com/johnlindquist/oracle",
          "level": 2
        },
        {
          "id": "https-github-com-karpathy-autoresearch",
          "text": "https://github.com/karpathy/autoresearch",
          "level": 2
        },
        {
          "id": "https-github-com-openclaw-gogcli",
          "text": "https://github.com/openclaw/gogcli",
          "level": 2
        },
        {
          "id": "https-github-com-vercel-labs-agent-browser",
          "text": "https://github.com/vercel-labs/agent-browser",
          "level": 2
        },
        {
          "id": "https-impeccable-style",
          "text": "https://impeccable.style/",
          "level": 2
        },
        {
          "id": "https-inspiration-board-pages-dev",
          "text": "https://inspiration-board.pages.dev/",
          "level": 2
        },
        {
          "id": "https-n8n-io",
          "text": "https://n8n.io/",
          "level": 2
        },
        {
          "id": "https-stitch-withgoogle-com",
          "text": "https://stitch.withgoogle.com/",
          "level": 2
        },
        {
          "id": "https-www-aihero-dev-skills-grill-me",
          "text": "https://www.aihero.dev/skills-grill-me",
          "level": 2
        },
        {
          "id": "https-www-amazon-com-rotating-pomodoro-minutes-productivity-vibration-dp-b0d7jg4vld-th-1",
          "text": "https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1",
          "level": 2
        },
        {
          "id": "https-www-dev-build-comics-prompt-quest-0-page-5",
          "text": "https://www.dev.build/comics/prompt-quest/0?page=5",
          "level": 2
        },
        {
          "id": "https-www-npmjs-com-package-packx",
          "text": "https://www.npmjs.com/package/packx",
          "level": 2
        },
        {
          "id": "https-www-youtube-com-watch-v-v4f1gfy-hqg",
          "text": "https://www.youtube.com/watch?v=v4F1gFy-hqg",
          "level": 2
        },
        {
          "id": "lazygit",
          "text": "LazyGit",
          "level": 2
        },
        {
          "id": "notebook-lm",
          "text": "Notebook LM",
          "level": 2
        },
        {
          "id": "oracle",
          "text": "Oracle",
          "level": 2
        },
        {
          "id": "packx",
          "text": "PackX",
          "level": 2
        },
        {
          "id": "packx-pack-tool",
          "text": "PackX / pack tool",
          "level": 2
        },
        {
          "id": "pro-gh-summarize-my-commits-from-the-past-2-days",
          "text": "Pro GH summarize my commits from the past 2 days",
          "level": 2
        },
        {
          "id": "screenpipe",
          "text": "ScreenPipe",
          "level": 2
        },
        {
          "id": "settings-apps-advanced-settings",
          "text": "settings > apps > advanced settings",
          "level": 2
        },
        {
          "id": "skills-sh",
          "text": "skills.sh",
          "level": 2
        },
        {
          "id": "tailwind-css",
          "text": "Tailwind CSS",
          "level": 2
        },
        {
          "id": "unlink",
          "text": "unlink",
          "level": 2
        },
        {
          "id": "vercel-ai-sdk",
          "text": "Vercel AI SDK",
          "level": 2
        },
        {
          "id": "vercel-cli",
          "text": "Vercel CLI",
          "level": 2
        },
        {
          "id": "warp-terminal",
          "text": "Warp Terminal",
          "level": 2
        }
      ],
      "markdown": "# Agent foundations resource index\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nReference tools, packages, examples, and commands. A mention is not an implementation requirement: use the relevant playbook for the demonstrated workflow and its limitations.\n\n## ADB tools\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## Agent Browser\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## AI Gateway\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Antigravity\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## beads\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## BUN\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## bun install\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Chrome DevTools MCP\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## Claude Code\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Cloud Code\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## Cmd-Opt-Shift-J\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## CMUX\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) · [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/) · [Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/) · [Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## CMUX open 3 panes and run LS in each of them\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Codex\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## Codex Awesome Plugins\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Codex SDK\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Codex Spark Low\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## Deep Wiki Map\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## GitHub CLI\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## GPT 5.5\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## GrillMe\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## https://askoracle.sh/\n\n[Open resource](https://askoracle.sh/)\n\nShared reference\n\n[Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n\n## https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm\n\n[Open resource](https://chromewebstore.google.com/detail/marksnip-webpage-to-markd/kcbaglhfgbkjdnpeokaamjjkddempipm)\n\n[Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n\n## https://cmux.com/\n\n[Open resource](https://cmux.com/)\n\nShared reference to point out the primary product page for the CMUX terminal software application.\n\n[Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/)\n\n## https://codex-trainer.johnlindquist.workers.dev/\n\n[Open resource](https://codex-trainer.johnlindquist.workers.dev/)\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## https://developers.openai.com/codex/hooks\n\n[Open resource](https://developers.openai.com/codex/hooks)\n\n[Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n\n## https://developers.openai.com/codex/plugins\n\n[Open resource](https://developers.openai.com/codex/plugins)\n\n[Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n\n## https://developers.openai.com/codex/plugins/build\n\n[Open resource](https://developers.openai.com/codex/plugins/build)\n\n[Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n\n## https://github.com/aurorascharff/ClickLight\n\n[Open resource](https://github.com/aurorascharff/ClickLight)\n\n[Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n\n## https://github.com/fayazara/Screendrop\n\n[Open resource](https://github.com/fayazara/Screendrop)\n\n[Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n\n## https://github.com/gastownhall/beads\n\n[Open resource](https://github.com/gastownhall/beads)\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/) · [Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## https://github.com/johnlindquist/better-plugins/tree/main/plugins\n\n[Open resource](https://github.com/johnlindquist/better-plugins/tree/main/plugins)\n\n[Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n\n## https://github.com/johnlindquist/cmux-extensions\n\n[Open resource](https://github.com/johnlindquist/cmux-extensions)\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## https://github.com/johnlindquist/codex-daemons\n\n[Open resource](https://github.com/johnlindquist/codex-daemons)\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## https://github.com/johnlindquist/oracle\n\n[Open resource](https://github.com/johnlindquist/oracle)\n\nThe repo for my specific fork of this is just John Lindquist here\n\n[Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n\n## https://github.com/karpathy/autoresearch\n\n[Open resource](https://github.com/karpathy/autoresearch)\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## https://github.com/openclaw/gogcli\n\n[Open resource](https://github.com/openclaw/gogcli)\n\nShared in chat by John Lindquist to demonstrate the Google CLI configuration repository.\n\n[Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)\n\n## https://github.com/vercel-labs/agent-browser\n\n[Open resource](https://github.com/vercel-labs/agent-browser)\n\n[Explore software through perspectives and runtime QA](/topics/foundations-perspective-qa-and-testing/)\n\n## https://impeccable.style/\n\n[Open resource](https://impeccable.style/)\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## https://inspiration-board.pages.dev/\n\n[Open resource](https://inspiration-board.pages.dev/)\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)\n\n## https://n8n.io/\n\n[Open resource](https://n8n.io/)\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## https://stitch.withgoogle.com/\n\n[Open resource](https://stitch.withgoogle.com/)\n\nShared reference to show Google Stitch layout standard site components discussed during Impeccable demo.\n\n[Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)\n\n## https://www.aihero.dev/skills-grill-me\n\n[Open resource](https://www.aihero.dev/skills-grill-me)\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1\n\n[Open resource](https://www.amazon.com/Rotating-Pomodoro-Minutes-Productivity-Vibration/dp/B0D7JG4VLD?th=1)\n\nShared reference to reference the physical rotating desktop timer device layout.\n\n[Use images, video, and task-shaped model routing](/topics/foundations-multimodal-design-and-model-routing/)\n\n## https://www.dev.build/comics/prompt-quest/0?page=5\n\n[Open resource](https://www.dev.build/comics/prompt-quest/0?page=5)\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## https://www.npmjs.com/package/packx\n\n[Open resource](https://www.npmjs.com/package/packx)\n\nShared by John Lindquist to provide the source package locator for the file aggregation utility.\n\n[Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/)\n\n## https://www.youtube.com/watch?v=v4F1gFy-hqg\n\n[Open resource](https://www.youtube.com/watch?v=v4F1gFy-hqg)\n\n[Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)\n\n## LazyGit\n\n[Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)\n\n## Notebook LM\n\nNotebook LM is a Google project.\n\nContextual mention only; not a retained taught workflow for Oracle handoff.\n\n[Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n\n## Oracle\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## PackX\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## PackX / pack tool\n\nTool used to compress files into context tokens\n\n[Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n\n## Pro GH summarize my commits from the past 2 days\n\n[Verify fixes with deterministic evidence and narrow boundaries](/topics/foundations-deterministic-verification-and-boundaries/)\n\n## ScreenPipe\n\n[Combine intent, implementation, and output for autonomous work](/topics/foundations-context-triad-and-overnight-work/)\n\n## settings > apps > advanced settings\n\nPath dropped by a developer to configure state visibility\n\n[Route large codebase questions through Oracle](/topics/foundations-oracle-context-routing/)\n\n## skills.sh\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Tailwind CSS\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## unlink\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Vercel AI SDK\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Vercel CLI\n\n[Build narrow daemons and inspectable agent graphs](/topics/foundations-narrow-daemons-and-agent-graphs/)\n\n## Warp Terminal\n\n[Trust current source and capture design decisions](/topics/foundations-source-truth-and-design/)"
    },
    {
      "id": "factory-tools-skills-distribution",
      "slug": "tools-skills-distribution",
      "title": "Agent skills: authoring & distribution (skills CLI)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "skills-distribution"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#skills-distribution"
        }
      ],
      "sourceUnits": [
        "resources/index.html#skills-distribution"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 230,
      "url": "/topics/factory-tools-skills-distribution/",
      "markdownUrl": "/markdown/factory-tools-skills-distribution.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-skills-distribution.json",
      "headings": [
        {
          "id": "agent-skills-authoring-distribution-skills-cli",
          "text": "Agent skills: authoring & distribution (skills CLI)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Agent skills: authoring & distribution (skills CLI)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Agent skills: authoring & distribution (skills CLI)\n\n**John uses:** the [skills CLI](https://github.com/vercel-labs/skills) (26.4k; `npx skills add <source> --skill <name>`, skills.sh) with canonical skills in `~/.agents/skills` symlinked into each agent's skill dir. Section 07 even publishes an installable skill on the workshop page itself.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [anthropics/skills](https://github.com/anthropics/skills) | Anthropic's public repository of Agent Skills | Official first-party skill collection to copy from rather than an installer CLI | none listed |\n| [superpowers](https://github.com/obra/superpowers) | An agentic skills framework and software-development methodology | Opinionated bundled methodology (brainstorm→plan→implement) vs à-la-carte skill installs | MIT |\n| [Claude Code plugins/marketplaces (built-in)](https://docs.claude.com/en/docs/claude-code) | Native plugin + marketplace system bundling skills, commands, hooks, MCP servers | First-party distribution channel; Claude-Code-only where skills.sh targets many agents | product |\n| [MCP servers](https://github.com/modelcontextprotocol) | Model Context Protocol: distribute agent capabilities as tool servers rather than markdown skills | Tools-as-processes vs instructions-as-markdown; complementary, heavier to build | open spec (MIT) |\n\n### Pick this if…\n\n- **anthropics/skills** — you want first-party, well-audited skills to copy from.\n- **superpowers** — you want a whole opinionated methodology, not à-la-carte installs.\n- **Claude Code plugins** — you're Claude-Code-only and want first-party distribution.\n- **MCP** — the capability needs real code/tools, not instructions."
    },
    {
      "id": "codex-shell-startup-files",
      "slug": "shell-startup-files",
      "title": "Agent-safe shell startup file examples",
      "summary": "Complete example startup files, PATH assembly, safe local overrides, environment-marker configuration, and startup checks, with explicit gaps and installation boundaries.",
      "category": "Tools",
      "tags": [
        "zsh",
        "startup",
        "environment"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/.zprofile",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/.zshenv",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/codex-env.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/00-path.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/40-ai.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/conf.d/47-ai-fix.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/examples/codex-config-shell-environment-policy.toml",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/examples/local.zsh.example",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/tests/startup-regression.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 992,
      "url": "/topics/codex-shell-startup-files/",
      "markdownUrl": "/markdown/codex-shell-startup-files.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-startup-files.json",
      "headings": [
        {
          "id": "safety-and-completeness-boundaries",
          "text": "Safety and completeness boundaries",
          "level": 2
        },
        {
          "id": "zsh-zprofile",
          "text": "zsh/.zprofile",
          "level": 2
        },
        {
          "id": "zsh-zshenv",
          "text": "zsh/.zshenv",
          "level": 2
        },
        {
          "id": "zsh-codex-env-zsh",
          "text": "zsh/codex-env.zsh",
          "level": 2
        },
        {
          "id": "zsh-conf-d-00-path-zsh",
          "text": "zsh/conf.d/00-path.zsh",
          "level": 2
        },
        {
          "id": "zsh-conf-d-40-ai-zsh",
          "text": "zsh/conf.d/40-ai.zsh",
          "level": 2
        },
        {
          "id": "zsh-conf-d-47-ai-fix-zsh",
          "text": "zsh/conf.d/47-ai-fix.zsh",
          "level": 2
        },
        {
          "id": "zsh-examples-codex-config-shell-environment-policy-toml",
          "text": "zsh/examples/codex-config-shell-environment-policy.toml",
          "level": 2
        },
        {
          "id": "zsh-examples-local-zsh-example",
          "text": "zsh/examples/local.zsh.example",
          "level": 2
        },
        {
          "id": "zsh-tests-startup-regression-zsh",
          "text": "zsh/tests/startup-regression.zsh",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Agent-safe shell startup file examples\n\nThese examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.\n\n## Safety and completeness boundaries\n\n- These are setup examples, not a drop-in configuration. The home-directory `.zshenv` forwards to `$ZDOTDIR/.zshenv`; do not install the same forwarding file at both locations.\n- The supplied bootstrap does not implement the `CODEX_LOAD_ZSH_DSL` opt-in loader described by the practical reference. Setting the marker alone does not load the helper snippets. Inspect or implement that reviewed bridge explicitly.\n- The exported `CODEX_AGENT_ENV_SOURCED` guard can be inherited by child shells, while ordinary shell functions are not inherited. A marker-only clean-shell check is not proof of a fully isolated environment.\n- The startup regression example checks helper presence rather than behavior. Its multi-file `zsh -n` invocation does not independently parse every supplied path; check each file separately when adopting the examples.\n- Node, Homebrew, pnpm, editor, and helper paths are illustrative installation choices. Use supported installed toolchain versions and preserve existing local configuration.\n\n## zsh/.zprofile\n\n```zsh\n# Login-shell setup for zsh.\n# Codex and similar agents commonly execute commands via `zsh -lc`, which reads\n# this file but not .zshrc.\n\n[[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n```\n\n## zsh/.zshenv\n\n```zsh\n# Bootstrap ZDOTDIR for XDG-compliant zsh config\nexport ZDOTDIR=\"${XDG_CONFIG_HOME:-$HOME/.config}/zsh\"\n[[ -f \"$ZDOTDIR/.zshenv\" ]] && source \"$ZDOTDIR/.zshenv\"\n\n# Cargo (Rust)\n[[ -r \"$HOME/.cargo/env\" ]] && source \"$HOME/.cargo/env\" >/dev/null 2>&1\n```\n\n## zsh/codex-env.zsh\n\n```zsh\n# =============================================================================\n# Codex / Agent-Safe Shell Bootstrap\n# =============================================================================\n# Loaded by $ZDOTDIR/.zprofile so non-interactive login shells (`zsh -lc`) get\n# the same tool paths and selected helper functions as interactive terminals.\n#\n# Keep this file free of prompt, completion, keybinding, and tty-only setup.\n# Interactive-only config belongs in .zshrc.\n# =============================================================================\n\n[[ -n \"${CODEX_AGENT_ENV_SOURCED:-}\" ]] && return 0\nexport CODEX_AGENT_ENV_SOURCED=1\n\nexport XDG_CONFIG_HOME=\"${XDG_CONFIG_HOME:-$HOME/.config}\"\nexport XDG_DATA_HOME=\"${XDG_DATA_HOME:-$HOME/.local/share}\"\nexport XDG_CACHE_HOME=\"${XDG_CACHE_HOME:-$HOME/.cache}\"\nexport XDG_STATE_HOME=\"${XDG_STATE_HOME:-$HOME/.local/state}\"\nexport ZDOTDIR=\"${ZDOTDIR:-$XDG_CONFIG_HOME/zsh}\"\n\n# Homebrew shellenv is non-interactive and fills in HOMEBREW_* metadata.\n[[ -x /opt/homebrew/bin/brew ]] && eval \"$(/opt/homebrew/bin/brew shellenv)\"\n\n# Small, declarative modules that are safe for non-interactive shells.\nfor _codex_env_file in \\\n  \"$ZDOTDIR/conf.d/00-path.zsh\" \\\n  \"$ZDOTDIR/local.zsh\"\ndo\n  [[ -r \"$_codex_env_file\" ]] && source \"$_codex_env_file\"\ndone\nunset _codex_env_file\n\n# Tool-specific environment files that only export paths/vars.\n[[ -r \"$HOME/.atuin/bin/env\" ]] && source \"$HOME/.atuin/bin/env\" >/dev/null 2>&1\n[[ -r \"$HOME/.cargo/env\" ]] && source \"$HOME/.cargo/env\" >/dev/null 2>&1\n\nexport CLAUDE_ENV_FILE=\"${CLAUDE_ENV_FILE:-$HOME/.claude/shell-init.sh}\"\n\n# mdflow agent paths without loading the full interactive .zshrc.\ntypeset -U path\npath=(\"$HOME/.mdflow\" $path)\nexport PATH=\"${(j/:/)path}\"\n\n_codex_mdflow_path_refresh() {\n  PATH=$(print -r -- \"$PATH\" \\\n    | tr ':' '\\n' \\\n    | grep -vE '^(/[^/]+){4,}/\\.mdflow$' \\\n    | tr '\\n' ':' \\\n    | sed 's/:$//')\n\n  [[ -d \".mdflow\" ]] && export PATH=\"$PWD/.mdflow:$PATH\"\n  typeset -U path\n  export PATH=\"${(j/:/)path}\"\n}\n\n_codex_mdflow_path_refresh\n\nif command -v mdflow >/dev/null 2>&1; then\n  md() {\n    command mdflow \"$@\"\n  }\nfi\n\nif command -v zoxide >/dev/null 2>&1; then\n  eval \"$(zoxide init zsh --no-cmd)\"\n\n  j() {\n    __zoxide_z \"$@\"\n  }\n\n  z() {\n    __zoxide_zi \"$@\"\n  }\nfi\n```\n\n## zsh/conf.d/00-path.zsh\n\n```zsh\n# --- Module: PATH Plumbing (00-path.zsh) -------------------------------------\n# Deterministic PATH/environment setup for shell startup.\n# Machine-specific overrides belong in `local.zsh`.\n#\n# --- DSL Vocabulary -----------------------------------------------------------\n# Functions: (none; declarative module)\n# Verbs: export, prepend, deduplicate\n\n# --- Path De-duplication ------------------------------------------------------\ntypeset -U path\n\n# --- Configurable Defaults ----------------------------------------------------\n# Override these defaults in `local.zsh` when needed.\n: \"${NODE_VERSION:=23.6.1}\"\n: \"${HOMEBREW_PREFIX:=/opt/homebrew}\"\n\n# --- Common Home Directories --------------------------------------------------\nexport ZSH=\"${ZSH:-$HOME/.oh-my-zsh}\"\nexport PNPM_HOME=\"${PNPM_HOME:-$HOME/Library/pnpm}\"\nexport BUN_INSTALL=\"${BUN_INSTALL:-$HOME/.bun}\"\n\n# --- Warning Suppression ------------------------------------------------------\nexport PYTHONWARNINGS=ignore::DeprecationWarning\n\n# --- PATH Assembly ------------------------------------------------------------\n# Ordering is intentional: toolchain bins first, then inherited PATH entries.\npath=(\n  # Node, pnpm, and bun (highest priority).\n  \"$PNPM_HOME\"\n  \"$HOME/Library/pnpm/nodejs/${NODE_VERSION}/bin\"\n  \"$BUN_INSTALL/bin\"\n\n  # Homebrew and system binaries.\n  \"$HOMEBREW_PREFIX/opt/trash/bin\"  # Keg-only formula path.\n  \"$HOMEBREW_PREFIX/bin\"\n  /usr/local/bin\n  /usr/bin\n  /bin\n\n  # User tool directories.\n  \"$HOME/.config/agents\"\n  \"$HOME/.local/bin\"\n  \"$HOME/.ma\"\n\n  # Existing PATH entries.\n  $path\n)\n\n# --- PATH Export --------------------------------------------------------------\nexport PATH=\"${(j/:/)path}\"\n\n# --- PNPM Precedence Guard ----------------------------------------------------\n# Prepend `PNPM_HOME` when absent so pnpm shims stay highest-priority.\ncase \":$PATH:\" in\n  *\":$PNPM_HOME:\"*) ;;\n  *) export PATH=\"$PNPM_HOME:$PATH\" ;;\nesac\n```\n\n## zsh/conf.d/40-ai.zsh\n\n```zsh\n# Workshop-safe AI helper loader.\n# This file intentionally sources focused snippets instead of copying a full\n# private shell config.\n\nlocal _workshop_zsh_dir=\"${0:A:h:h}\"\n\nfor _workshop_fn_file in \\\n  \"$_workshop_zsh_dir/functions/codex-launch-and-prompt-builder.zsh\" \\\n  \"$_workshop_zsh_dir/functions/shell-introspection.zsh\" \\\n  \"$_workshop_zsh_dir/functions/fusion-fix.zsh\" \\\n  \"$_workshop_zsh_dir/functions/orchestration-helpers.zsh\" \\\n  \"$_workshop_zsh_dir/functions/script-kit-process-helpers.zsh\"\ndo\n  [[ -r \"$_workshop_fn_file\" ]] && source \"$_workshop_fn_file\"\ndone\n\nunset _workshop_fn_file _workshop_zsh_dir\n```\n\n## zsh/conf.d/47-ai-fix.zsh\n\n```zsh\n# Backward-compatible entrypoint for the focused workshop snippet.\nsource \"${0:A:h:h}/functions/fusion-fix.zsh\"\n```\n\n## zsh/examples/codex-config-shell-environment-policy.toml\n\n```toml\n# Public shape only. Merge into your real ~/.codex/config.toml when you want\n# Codex tool shells to receive the marker.\n\n[shell_environment_policy.set]\nCODEX_LOAD_ZSH_DSL = \"1\"\n```\n\n## zsh/examples/local.zsh.example\n\n```zsh\n# Machine-local overrides.\n#\n# Keep this file safe for non-interactive shells if it is sourced by\n# `codex-env.zsh`.\n#\n# Do not commit real API keys, tokens, private endpoints, or machine-specific\n# secrets. Use secret-manager helpers that resolve values at command execution\n# time, and avoid printing secret values during startup.\n\n# Example: add a local tool directory to PATH.\ntypeset -U path\npath=(\"$HOME/.local/bin\" $path)\nexport PATH=\"${(j/:/)path}\"\n\n# Example: command wrapper that resolves a secret only for the invoked command.\n# with_example_provider() {\n#   EXAMPLE_API_KEY=\"$(op item get EXAMPLE_API_KEY --fields credential --reveal)\" \"$@\"\n# }\n```\n\n## zsh/tests/startup-regression.zsh\n\n```zsh\n#!/usr/bin/env zsh\n# Public startup regression check for the bundled workshop zsh files.\n\nset -euo pipefail\n\nfail() {\n  print -u2 -- \"FAIL: $1\"\n  exit 1\n}\n\nROOT=\"${0:A:h:h}\"\n\nzsh -n \\\n  \"$ROOT/.zshenv\" \\\n  \"$ROOT/.zprofile\" \\\n  \"$ROOT/codex-env.zsh\" \\\n  \"$ROOT/conf.d/00-path.zsh\" \\\n  \"$ROOT/conf.d/40-ai.zsh\" \\\n  \"$ROOT/conf.d/47-ai-fix.zsh\" \\\n  \"$ROOT\"/functions/*.zsh || fail \"syntax check failed\"\n\nout=\"$(\n  cd \"$ROOT:h\"\n  zsh -lc 'source ./zsh/conf.d/40-ai.zsh; for name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do printf \"%s:%s\\n\" \"$name\" \"$(whence -w \"$name\" 2>/dev/null || echo MISSING)\"; done'\n)\"\n\nfor name in x xi xfl xfc p-f p-c p-cm funclist funcwhere funced muxai agent_chain ghost-save aicm pksk fix; do\n  [[ \"$out\" == *\"$name:$name: function\"* ]] || fail \"missing bundled helper: $name\"\ndone\n\nprint -- \"ok: bundled zsh startup regression\"\n```\n\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-tools-context-bundlers",
      "slug": "tools-context-bundlers",
      "title": "AI context bundlers (repo → prompt)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "context-bundlers"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#context-bundlers"
        }
      ],
      "sourceUnits": [
        "resources/index.html#context-bundlers"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 334,
      "url": "/topics/factory-tools-context-bundlers/",
      "markdownUrl": "/markdown/factory-tools-context-bundlers.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-context-bundlers.json",
      "headings": [
        {
          "id": "ai-context-bundlers-repo-prompt",
          "text": "AI context bundlers (repo → prompt)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# AI context bundlers (repo → prompt)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## AI context bundlers (repo → prompt)\n\n**John uses:** **packx** (`npm install -g packx`, johnlindquist on npm) — filters repository files **by content string** and extension before bundling for AI consumption, with saved search configs. Section 08's oracle skill uses it to bundle up to ~900k tokens per consult. (Related: [johnlindquist/pack](https://github.com/johnlindquist/pack), a content-filter front-end for Repomix.)\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [Repomix](https://github.com/yamadashy/repomix) | Packs an entire repository into a single AI-friendly file (XML/MD), with token counts and remote-repo support | Whole-repo packing with include/exclude globs; packx's content-string filtering is the main thing it lacks (John's \\`pack\\` wraps Repomix to add it) | MIT |\n| [gitingest](https://github.com/coderamp-labs/gitingest) | Replace 'hub' with 'ingest' in any GitHub URL to get a prompt-friendly extract | Zero-install for public repos (URL trick + web UI); also a pip CLI | MIT |\n| [code2prompt](https://github.com/mufeedvh/code2prompt) | Rust CLI: codebase → single prompt with source tree, Handlebars templating, token counting | Template-driven output shaping; closest feature set to packx minus content search | MIT |\n| [files-to-prompt](https://github.com/simonw/files-to-prompt) | Simon Willison's minimal concatenator: directory → one prompt (pairs with his \\`llm\\` CLI) | Deliberately tiny; no filtering logic beyond paths; check current repository activity (stable, not active) | Apache-2.0 |\n| [yek](https://github.com/mohsen1/yek) | Fast Rust serializer for repo files, chunks by token budget, priority-orders files | Speed and token-budget chunking focus; good for very large repos | MIT |\n\n### Pick this if…\n\n- **Repomix** — the default choice; the biggest, most maintained repo-packer. packx's content-search filtering is the one thing you'll miss.\n- **gitingest** — you mostly bundle public repos and want zero install.\n- **code2prompt** — you want templated output shaping (Handlebars) around the bundle.\n- **files-to-prompt** — you want the smallest possible tool, especially with `llm` (stable but not actively developed).\n- **yek** — your repos are huge and you need token-budget chunking fast."
    },
    {
      "id": "factory-tools-browser-automation",
      "slug": "tools-browser-automation",
      "title": "Browser automation for agents (Oracle, agent-browser)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "browser-automation"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#browser-automation"
        }
      ],
      "sourceUnits": [
        "resources/index.html#browser-automation"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 402,
      "url": "/topics/factory-tools-browser-automation/",
      "markdownUrl": "/markdown/factory-tools-browser-automation.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-browser-automation.json",
      "headings": [
        {
          "id": "browser-automation-for-agents-oracle-agent-browser",
          "text": "Browser automation for agents (Oracle, agent-browser)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Browser automation for agents (Oracle, agent-browser)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Browser automation for agents (Oracle, agent-browser)\n\n**John uses:** two distinct things. **[agent-browser](https://github.com/vercel-labs/agent-browser)** (38.6k, Apache-2.0) for general \"agent drives a browser\" tasks. And **Oracle** ([johnlindquist/oracle](https://github.com/johnlindquist/oracle) fork of a private setup) for the section 08 move: copy cookies from your logged-in Chrome profile and drive chatgpt.com / gemini.google.com directly — subscription-priced frontier reasoning (no API keys) and Gemini's video understanding, at ~1,978 sessions of real use. John runs it as `oracle serve` on a Mac mini behind Tailscale with a dual-account round-robin pool; most people would run it locally.\n\n**Honest note:** Oracle's cookie-riding consult niche has no maintained public equivalent we could verify. Substitutes are (a) rebuild the pattern on the tools below, or (b) pay for the API: Gemini API / Gemini CLI for video, ChatGPT Pro-tier reasoning via Codex CLI.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [browser-use](https://github.com/browser-use/browser-use) | Python library making websites accessible to AI agents; can attach to your real Chrome profile | General web-task automation with an LLM driver; you could rebuild Oracle's 'drive ChatGPT with cookies' trick on it | MIT |\n| [Playwright MCP](https://github.com/microsoft/playwright-mcp) | Microsoft's MCP server exposing Playwright browser control to any MCP-capable agent | Accessibility-tree-driven, works out of the box with Claude Code/Codex; persistent profiles carry logins | Apache-2.0 |\n| [Stagehand](https://github.com/browserbase/stagehand) | SDK for browser agents (act/extract/observe primitives on Playwright, by Browserbase) | Code-first SDK with hosted-browser option rather than a CLI; good for building your own Oracle-like service | MIT |\n| [Skyvern](https://github.com/Skyvern-AI/skyvern) | Automate browser workflows with LLMs + computer vision | Workflow-oriented (forms, portals) with a self-hostable server; AGPL | AGPL-3.0 |\n| [nanobrowser](https://github.com/nanobrowser/nanobrowser) | Chrome extension for multi-agent web automation with your own API keys | Runs INSIDE your logged-in browser, so it gets cookies for free like Oracle; check current repository activity (aging) | Apache-2.0 |\n\n### Pick this if…\n\n- **Playwright MCP** — you use Claude Code/Codex and want browser control today with zero code; persistent profiles carry logins.\n- **browser-use** — you're in Python and want to script Oracle-style \"drive a logged-in site\" flows.\n- **Stagehand** — you're building a browser-agent *service* (hosted browsers, SDK ergonomics).\n- **Skyvern** — you automate form-heavy portals and can self-host (AGPL).\n- **nanobrowser** — you want automation living inside your already-logged-in browser (aging repo — verify)."
    },
    {
      "id": "factory-tool-selection",
      "slug": "tool-selection",
      "title": "Choose tools by the job, not the presenter’s stack",
      "summary": "Compare the capability you need, preserve uncertain product claims, and substitute tools without changing the operating pattern.",
      "category": "Tools",
      "tags": [
        "tools",
        "selection"
      ],
      "sources": [
        {
          "label": "Resource reference",
          "url": "https://dewy-sleet-n5zs.here.now/"
        }
      ],
      "sourceUnits": [
        "resources/index.html#tldr",
        "resources/index.html#method",
        "resources/index.html#mentions",
        "resources/index.html#appendix"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 494,
      "url": "/topics/factory-tool-selection/",
      "markdownUrl": "/markdown/factory-tool-selection.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tool-selection.json",
      "headings": [
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "how-to-read-this-page",
          "text": "How to read this page",
          "level": 2
        },
        {
          "id": "also-mentioned-in-the-workshop",
          "text": "Also mentioned in the workshop",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "what-we-could-not-verify-flagged-not-fabricated",
          "text": "What we could NOT verify (flagged, not fabricated)",
          "level": 3
        }
      ],
      "markdown": "# Choose tools by the job, not the presenter’s stack\n\nCompare the capability you need, preserve uncertain product claims, and substitute tools without changing the operating pattern.\n\n## TL;DR\n\n- 16 tool categories from the workshop, each with what John uses and 81 vetted alternatives in evidence tables (stars · last push · license).\n\n- The one move: adopt the *pattern*, not the exact tool — every section names the substitute that keeps the pattern alive under your constraints.\n\n Have your agent match these to your constraints — paste this into it:\n\n``` text\nFetch https://dewy-sleet-n5zs.here.now/agent.md?raw — a machine-readable list of every tool category in this workshop with vetted alternatives (name + URL + evidence). Ask me for my constraints (OS, license policy, budget, what I'm allowed to install), then recommend one alternative per category I can't adopt as-is, with your reasoning.\n```\n\n## How to read this page\n\nThis workshop demos John's exact stack. You don't need John's exact stack. Every pattern taught here — tiny wrappers, preloaded context, agent-driven browsers, taste voting — works with substitutes. Below: every tool the workshop mentions, what it does in John's system, and credible open-source or commercial alternatives with evidence.\n\n**Retrieved the recorded snapshot.** Star counts, last-push dates, and licenses come from the GitHub API on that date (`gh api repos/<owner>/<repo>`); non-GitHub products were sanity-checked by web search the same day. \"NOASSERTION\" means GitHub couldn't map the repo's license to an SPDX id (usually a custom or source-available license) — read the repo's LICENSE before adopting. Nothing here is an endorsement, and a few of John's tools are personal/unreleased — those are flagged, not glossed over (see the appendix).\n\n## Also mentioned in the workshop\n\nThese came up but don't need an alternatives table:\n\n- **[pi-session-id](https://github.com/johnlindquist/pi-session-id)** — the section 01 pi extension (MIT). The *pattern* (per-command shell prefix + session-scoped overrides) ports to any agent with shell hooks.\n- **Zed / Finder / GitHub open-cwd targets** (section 06) — editor-of-choice slots; any `open`/`code`-style CLI works.\n- **Linear CLI** (sections 01/05) — an example policy-wrapped command; substitute your tracker's CLI.\n- **Tailscale** (section 08) — how the Mac mini oracle server is reached; any WireGuard-style mesh works.\n- **wrangler / inspiration-board** (section 07) — covered under Publishing above.\n\n## Appendix\n\n### What we could NOT verify (flagged, not fabricated)\n\n- **cs** — no public repo found; treated as personal/unreleased, with the honest substitutes listed in §10.\n- **packx** — verified as John's npm package via web search (`npm install -g packx`), but it has no public GitHub repo we could find; star/license evidence unavailable.\n- **Oracle's exact consult architecture** — the fork repo exists ([johnlindquist/oracle](https://github.com/johnlindquist/oracle)) but is empty of description/stars; capabilities described here come from the workshop's own docs.\n- **Grok Build** star data — proprietary, no public repo; existence verified via x.ai announcement coverage.\n- License nuances behind every \"NOASSERTION\" — read the repo's LICENSE before commercial adoption (notably Crush, OpenHands, herdr, Sentry, OpenReplay, Infisical, Bitwarden)."
    },
    {
      "id": "foundations-codex-primitives-field-guide",
      "slug": "codex-primitives-field-guide",
      "title": "Codex Primitive Field Guide",
      "summary": "AGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.",
      "category": "Tools",
      "tags": [
        "field guide",
        "codex primitives"
      ],
      "sources": [
        {
          "label": "Agent foundations: Control agent lifecycle with hooks and context hygiene (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-07.html"
        },
        {
          "label": "Agent foundations: Preserve contracts and state machines while code changes (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-11.html"
        }
      ],
      "sourceUnits": [
        "field-guides/guides.mjs#codex-primitives/overview",
        "field-guides/guides.mjs#codex-primitives/quote",
        "field-guides/guides.mjs#codex-primitives/decision",
        "field-guides/guides.mjs#codex-primitives/agentPrompt",
        "field-guides/guides.mjs#codex-primitives/stories",
        "field-guides/guides.mjs#codex-primitives/tips",
        "field-guides/guides.mjs#codex-primitives/refs"
      ],
      "collection": "foundations",
      "categoryId": "tools",
      "wordCount": 567,
      "url": "/topics/foundations-codex-primitives-field-guide/",
      "markdownUrl": "/markdown/foundations-codex-primitives-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-codex-primitives-field-guide.json",
      "headings": [
        {
          "id": "choose-the-right-mechanism",
          "text": "Choose the right mechanism",
          "level": 2
        },
        {
          "id": "agent-ready-prompt",
          "text": "Agent-ready prompt",
          "level": 2
        },
        {
          "id": "applied-stories",
          "text": "Applied stories",
          "level": 2
        },
        {
          "id": "next-js-monorepo-guardrails",
          "text": "Next.js monorepo guardrails",
          "level": 3
        },
        {
          "id": "browser-proof-skill",
          "text": "Browser proof skill",
          "level": 3
        },
        {
          "id": "checkout-stop-hook-gate",
          "text": "Checkout Stop-hook gate",
          "level": 3
        },
        {
          "id": "tips-and-gotchas",
          "text": "Tips and gotchas",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-principles",
          "text": "Related principles",
          "level": 2
        }
      ],
      "markdown": "# Codex Primitive Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nAGENTS.md, skills, plugins, hooks, MCP, and Goal mode without mixing the layers.\n\nUse this when a workflow keeps failing because instructions, tools, and enforcement are all living in the same prompt.\n\n> Skills use progressive disclosure to manage context efficiently.\n\n[OpenAI Codex Skills docs](https://developers.openai.com/codex/skills)\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| AGENTS.md | Stable repo or directory rules | Setup, commands, conventions, done criteria | Short instruction file near the code |\n| Skill | Reusable workflow with judgment | Browser proof, release notes, Oracle handoff | .agents/skills/<name>/SKILL.md |\n| Plugin | Shareable installable bundle | Team workflow with skills, MCP, apps, hooks | .codex-plugin/plugin.json plus bundled folders |\n| Hook | Lifecycle enforcement | Prompt injection, tool policy, Stop receipt gate | hooks/hooks.json plus small scripts |\n| MCP | External systems and context | Browser, Figma, docs, DB, SaaS tools | .mcp.json plus tool policy |\n| Goal mode | Long-running objective | Research, plan, implement, verify loop | .goals/<task>.md plus receipts |\n\n## Agent-ready prompt\n\n```text\nCreate a Codex primitive map for this repo.\nRead AGENTS.md, package scripts, existing skills/plugins/hooks, and MCP config first.\nFor each repeated workflow, decide whether it belongs in AGENTS.md, a skill, a plugin, a hook, MCP, or a goal file.\nWrite .notes/codex-primitives/decision.md with the decision, files to create, verification command, and rollback path.\n```\n\n## Applied stories\n\n### Next.js monorepo guardrails\n\n**Role:** Platform lead\n\nAgents keep running the wrong tests and claiming UI work is done without proof.\n\n**Agent brief:** Ask Codex to create a root AGENTS.md under 120 lines, copy commands from package scripts or CI, and add browser-proof expectations for UI work.\n\n**Done when:**\n\n- AGENTS.md exists\n- Commands match real scripts\n- Codex can summarize loaded instructions\n- No one-off task details\n\n### Browser proof skill\n\n**Role:** SaaS frontend engineer\n\nEvery UI fix needs the same route, viewport, action, console, screenshot, and command receipt.\n\n**Agent brief:** Ask Codex to create .agents/skills/browser-proof-saas/SKILL.md with clear trigger and non-trigger language.\n\n**Done when:**\n\n- SKILL.md has name/description\n- Proof schema is included\n- Smoke prompt exists\n- Skill says when not to use it\n\n### Checkout Stop-hook gate\n\n**Role:** Checkout owner\n\nAgents stop after one validation fix instead of proving cart to confirmation.\n\n**Agent brief:** Ask Codex to scaffold a local plugin with a Stop hook that continues until checkout test and browser receipts exist.\n\n**Done when:**\n\n- Manifest validates\n- Hook simulator covers missing/success/cap\n- Receipts are named\n- No global install before simulation\n\n## Tips and gotchas\n\n- Keep AGENTS.md short. Put workflow machinery in skills/plugins/hooks.\n- Treat a skill as guidance, not enforcement. Move deterministic checks to hooks.\n- Use current Codex Stop-hook behavior: return decision: \"block\" with a reason to continue the turn.\n- Installing a plugin does not automatically make plugin hooks trusted. Teach users to review and trust hook definitions.\n- Use MCP for external stateful systems; use local package scripts for repo-local tests and builds.\n\n## References\n\n- [OpenAI Codex Skills](https://developers.openai.com/codex/skills)\n- [OpenAI Codex Plugins](https://developers.openai.com/codex/plugins)\n- [OpenAI Codex Hooks](https://developers.openai.com/codex/hooks)\n- [OpenAI AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md)\n- [AGENTS.md standard](https://agents.md/)\n- [Better Plugins examples](https://github.com/johnlindquist/better-plugins/tree/main/plugins)\n\n## Related principles\n\n- [Control agent lifecycle with hooks and context hygiene](/topics/foundations-hooks-and-context-hygiene/)\n- [Preserve contracts and state machines while code changes](/topics/foundations-contracts-state-machines-and-code/)"
    },
    {
      "id": "codex-fusion-runbook",
      "slug": "fusion-runbook",
      "title": "Fusion panel execution runbook",
      "summary": "Published Fusion skill defining direct CLI usage, provider preflight, full-panel blocking execution, terminal-state monitoring, degraded/quota-limited provider handling, artifact review, and repo-grounded final decisions. Includes preset/custom-config…",
      "category": "Tools",
      "tags": [
        "fusion",
        "council",
        "runbook"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/fusion/SKILL.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/fusion/SKILL.md#Fusion",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/fusion/SKILL.md#Fusion/Operating Rules",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/fusion/SKILL.md#Fusion/Command Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/fusion/SKILL.md#Fusion/Prompt Guidance",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 516,
      "url": "/topics/codex-fusion-runbook/",
      "markdownUrl": "/markdown/codex-fusion-runbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-fusion-runbook.json",
      "headings": [
        {
          "id": "operating-rules",
          "text": "Operating Rules",
          "level": 2
        },
        {
          "id": "command-shape",
          "text": "Command Shape",
          "level": 2
        },
        {
          "id": "prompt-guidance",
          "text": "Prompt Guidance",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Fusion panel execution runbook\n\nUse the local Fusion CLI for independent panel feedback when a task benefits from critique, architecture tradeoff review, implementation planning, or synthesis.\n\n## Operating Rules\n\n- Use the local commands directly: `fusion-high`, `fusion-med`, or `fusion`.\n- Do not substitute Oracle/MCP wrappers for the Fusion CLI.\n- Before real runs, inspect providers with `fusion-high --list-providers`, `fusion-med --list-providers`, or `fusion --list-providers`.\n- Run all configured providers for the selected preset first, and wait for every provider to reach a terminal state: `ok`, `failed`, `timedOut`, `quotaLimited`, `spawnError`, or `interrupted`.\n- Fusion is a blocking council call. After starting a real Fusion run, do not plan, implement, edit files, run unrelated commands, answer the user, or \"work ahead\" while waiting. The point of Fusion is to use the council output as the next input.\n- Do not treat elapsed time, early partial artifacts, or one strong provider answer as permission to continue independently. Continue only after Fusion exits and `summary.json` plus final output have been read, or after a real terminal failure/interruption has been captured.\n- Treat `panel-*.stdout.md` and `panel-*.json` as partial council artifacts until Fusion writes `summary.json` and final output. Do not interrupt a run merely because one or more useful provider responses have landed.\n- While a run is active, use `panel-status.json` and heartbeat stderr messages to see which providers are still pending or running.\n- If one provider fails or times out after panel artifacts are created, keep the artifact and let Fusion continue to judge/synthesis with the degraded panel.\n- If any provider reports quota, rate-limit, usage-limit, or 429 exhaustion, treat that provider as non-blocking for the current run. Do not stop to ask the user; report the model as quota-limited and continue with the remaining provider outputs.\n- Do not use `--only` for ordinary narrowing, model preference, or convenience. It is allowed only when the user explicitly requests a subset.\n- For long prompts, write a prompt file and use `--file` instead of fragile shell quoting.\n- Use `--dry-run` when command shape, provider IDs, config, or output location is uncertain.\n- Let Fusion choose its default output location unless the user explicitly asks for a run directory. Current Fusion writes automatic runs to `~/.fusion/sessions/YYYY/MM/DD/<session-id>/` and indexes them in `~/.fusion/sessions.jsonl`.\n- Do not pass `--out .fusion-runs/<slug>` by default; `--out` intentionally bypasses the `~/.fusion` session store.\n- Treat Fusion output as advisory. Read the artifacts, reconcile disagreements, and make the final engineering call from repo evidence.\n\n## Command Shape\n\n```bash\nfusion-high --list-providers\nfusion-high --dry-run --file path/to/prompt.md\nfusion-high --file path/to/prompt.md\n```\n\nFor moderate planning:\n\n```bash\nfusion-med --list-providers\nfusion-med --file path/to/prompt.md\n```\n\nFor custom config:\n\n```bash\nfusion --config path/to/fusion.config.json --file path/to/prompt.md\n```\n\nUse explicit output overrides only when requested or when a workflow needs repo-local artifacts:\n\n```bash\nfusion-high --file path/to/prompt.md --out .fusion-runs/<slug>\nfusion-high --file path/to/prompt.md --runs-dir .fusion-runs\n```\n\n## Prompt Guidance\n\nInclude the user request, success criteria, relevant repo paths, constraints, commands already run, observed failures, desired panel roles, and requested verification steps.\n\nAvoid sending secrets, tokens, credentials, or unrelated large context.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-tools-image-generation-variations",
      "slug": "tools-image-generation-variations",
      "title": "Image generation for design variations",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "image-generation-variations"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#image-generation-variations"
        }
      ],
      "sourceUnits": [
        "resources/index.html#image-generation-variations"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 302,
      "url": "/topics/factory-tools-image-generation-variations/",
      "markdownUrl": "/markdown/factory-tools-image-generation-variations.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-image-generation-variations.json",
      "headings": [
        {
          "id": "image-generation-for-design-variations",
          "text": "Image generation for design variations",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Image generation for design variations\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Image generation for design variations\n\n**John uses:** Codex's built-in **\\$imagegen** skill (GPT image model, no API key beyond the Codex subscription) and **agy** — the [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli) (1.6k) with Gemini's `generate_image` — to produce 9 wildly different mockups per prompt, then hands the winner to a coding agent as a reference image (section 07).\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google's terminal agent; image generation via Gemini/Imagen models on the free tier | Same Google image models as agy without the Antigravity harness | Apache-2.0 |\n| [ComfyUI](https://github.com/Comfy-Org/ComfyUI) | Node-graph GUI/API/backend for diffusion models, fully local | Local + free at inference; scriptable API makes 9x batch generation easy; needs a GPU and setup | GPL-3.0 |\n| [mflux](https://github.com/filipstrand/mflux) | MLX-native FLUX and other image models on Apple Silicon | Runs the 9x pattern locally on the same Mac you present from; CLI-first | MIT |\n| [InvokeAI](https://github.com/invoke-ai/InvokeAI) | Professional creative engine/WebUI for Stable Diffusion family models | Polished local UI aimed at designers rather than agent scripting | Apache-2.0 |\n| [AUTOMATIC1111 stable-diffusion-webui](https://github.com/AUTOMATIC1111/stable-diffusion-webui) | The historically dominant SD web UI | Huge ecosystem but slowing maintenance (check repository activity before adoption); prefer ComfyUI/Invoke for new setups | AGPL-3.0 |\n\n### Pick this if…\n\n- **Gemini CLI** — you want the agy pattern without Antigravity, free.\n- **ComfyUI** — you want local, free-at-inference batch generation with a scriptable API (needs GPU).\n- **mflux** — you present from a Mac and want the 9x loop fully local on Apple Silicon.\n- **InvokeAI** — you want a designer-friendly local UI over raw pipelines.\n- **A1111** — only if you need its ecosystem; prefer ComfyUI/Invoke for new setups."
    },
    {
      "id": "foundations-image-to-design-playbook",
      "slug": "image-to-design-playbook",
      "title": "Image-to-design handoff playbook",
      "summary": "Web developers already live in running apps, local dev servers, screenshots, and browser proof. This pack turns the taught image-to-design handoff into concrete flows where a selected reference image guides the code diff and the browser proves the result.",
      "category": "Tools",
      "tags": [
        "images",
        "video",
        "models",
        "CLI",
        "playbook",
        "prompts"
      ],
      "sources": [
        {
          "label": "Agent foundations: Use images, video, and task-shaped model routing (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-06.html"
        }
      ],
      "sourceUnits": [
        "scenarios/topics.mjs#image-to-design",
        "scenarios/image-to-design.json#audienceFit",
        "toolkit/prompts/06-image-to-design-handoff-prompt.md",
        "scenarios/image-to-design.json#scenarios/0",
        "scenarios/image-to-design.json#scenarios/1",
        "scenarios/image-to-design.json#scenarios/2",
        "scenarios/image-to-design.json#implementationNotes",
        "scenarios/image-to-design.json#notTaughtOrAvoid/1",
        "scenarios/image-to-design.json#notTaughtOrAvoid/2",
        "scenarios/image-to-design.json#notTaughtOrAvoid/3",
        "scenarios/image-to-design.json#notTaughtOrAvoid/4",
        "scenarios/image-to-design.json#notTaughtOrAvoid/5",
        "scenarios/image-to-design.json#notTaughtOrAvoid/6",
        "scenarios/image-to-design.json#notTaughtOrAvoid/7",
        "scenarios/image-to-design.json#agentReferences"
      ],
      "collection": "foundations",
      "categoryId": "tools",
      "wordCount": 2499,
      "url": "/topics/foundations-image-to-design-playbook/",
      "markdownUrl": "/markdown/foundations-image-to-design-playbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-image-to-design-playbook.json",
      "headings": [
        {
          "id": "copy-paste-workflow",
          "text": "Copy-paste workflow",
          "level": 2
        },
        {
          "id": "copy-paste-prompt",
          "text": "Copy-paste prompt",
          "level": 3
        },
        {
          "id": "how-it-works",
          "text": "How it works",
          "level": 3
        },
        {
          "id": "scenarios",
          "text": "Scenarios",
          "level": 2
        },
        {
          "id": "dashboard-card-from-selected-reference",
          "text": "Dashboard card from selected reference",
          "level": 3
        },
        {
          "id": "agent-brief",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "auth-gated-onboarding-visual-refresh",
          "text": "Auth-gated onboarding visual refresh",
          "level": 3
        },
        {
          "id": "agent-brief-2",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-2",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-2",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-2",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-2",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "responsive-marketing-hero-handoff",
          "text": "Responsive marketing hero handoff",
          "level": 3
        },
        {
          "id": "agent-brief-3",
          "text": "Agent brief",
          "level": 4
        },
        {
          "id": "implementation-references-3",
          "text": "Implementation references",
          "level": 4
        },
        {
          "id": "browser-verification-3",
          "text": "Browser verification",
          "level": 4
        },
        {
          "id": "definition-of-done-3",
          "text": "Definition of done",
          "level": 4
        },
        {
          "id": "failure-modes-and-mitigations-3",
          "text": "Failure modes and mitigations",
          "level": 4
        },
        {
          "id": "implementation-notes",
          "text": "Implementation notes",
          "level": 2
        },
        {
          "id": "boundaries-and-caveats",
          "text": "Boundaries and caveats",
          "level": 2
        },
        {
          "id": "agent-reference-map",
          "text": "Agent reference map",
          "level": 2
        },
        {
          "id": "image-to-design-handoff-prompt",
          "text": "Image-to-design handoff prompt",
          "level": 3
        },
        {
          "id": "lesson-06-validated-references",
          "text": "Lesson 06 validated references",
          "level": 3
        },
        {
          "id": "lesson-06-validation-notes",
          "text": "Lesson 06 validation notes",
          "level": 3
        },
        {
          "id": "packed-source-bundle",
          "text": "Packed source bundle",
          "level": 3
        },
        {
          "id": "cmux-browser-or-pane-state",
          "text": "CMUX browser or pane state",
          "level": 3
        },
        {
          "id": "browser-verification-primitive-shape",
          "text": "Browser verification primitive shape",
          "level": 3
        }
      ],
      "markdown": "# Image-to-design handoff playbook\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nWeb developers already live in running apps, local dev servers, screenshots, and browser proof. This pack turns the taught image-to-design handoff into concrete flows where a selected reference image guides the code diff and the browser proves the result.\n\n[Core principles](/topics/foundations-multimodal-design-and-model-routing/)\n\n## Copy-paste workflow\n\n**When to use:** When you can recognize the look you want but can't spec exact CSS. Generate a sheet of visual variations, pick the direction, and hand that concrete reference image to a coding agent to implement only that direction.\n\n### Copy-paste prompt\n\n```text\nHelp me do an image-to-design handoff for <COMPONENT/SCREEN>. I can recognize the look I want but can't spec the CSS, so we'll let a selected reference image carry my taste.\n\n1. Ask an image model for a SHEET of 5 visual variations of <COMPONENT/SCREEN> in one image (vary layout, color, type, density).\n\n2. Stop and let ME select the direction I like. (My selection expresses taste far better than a vague text prompt.)\n\n3. Take the chosen reference image and implement ONLY that direction in code — match its layout, spacing, color, and type. Do not blend in the other variations.\n\nGuardrails:\n- MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists. Keep deterministic work in scripts/CLIs; reserve agents for judgment calls like this selection.\n- Model-by-task-shape: use Codex for the coding follow-through; reserve fast Flash-class models for small, tightly scoped tasks only.\n```\n\n### How it works\n- Step 1 asks an image model for a sheet of 5 variations of one component/screen at once.\n- Step 2 puts the human in the loop: selecting a direction expresses taste better than a vague prompt.\n- Step 3 hands the chosen reference image to the coding agent and constrains it to implement only that direction.\n- Taught caution — the MCP-vs-CLI boundary: don't wrap a CLI in MCP just because MCP exists; keep deterministic work in scripts/CLIs and reserve agents for judgment.\n- Model-by-task-shape: Codex for coding follow-through, fast Flash models only for small scoped tasks.\n- Reference: [Google Gemini video/image prompting](https://github.com/manaflow-ai/cmux), [Codex CLI](https://github.com/openai/codex).\n\n## Scenarios\n\n### Dashboard card from selected reference\n\n**Role:** As a frontend engineer maintaining a Next.js product dashboard\n\nA billing or usage card in a real dashboard route works correctly but looks generic and has drifted from the product direction. You have a screenshot of the current component and either a selected reference image already chosen by the human or permission to generate a sheet of variations and pause for selection.\n\n> As a frontend engineer, I want Codex to implement one selected visual direction for the dashboard card while preserving existing data and behavior, so that the UI improves without turning a working component into a risky rewrite.\n\n#### Agent brief\n\n```text\nCopy-paste to Codex:\n\nUse the image-to-design handoff workflow for the dashboard card at <ROUTE>, backed by these artifacts: current screenshot <CURRENT_SCREENSHOT_PATH>, selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, and relevant source files <COMPONENT_OR_ROUTE_PATHS>.\n\n1. Inspect package.json and the current component/source before editing. Treat the live code as source of truth for props, data loading, auth, events, and tests.\n2. If <SELECTED_REFERENCE_IMAGE_PATH> does not exist yet, ask an image model for one sheet of 5 visual variations of this exact card based on <CURRENT_SCREENSHOT_PATH>, then stop and ask me which direction to use. Do not implement until I pick one.\n3. Once the selected reference exists, implement ONLY that direction. Match layout, spacing, color, type, density, border/radius, and visual hierarchy. Do not blend in other variations. Preserve existing copy, links, data-testid values, analytics attributes, and behavior unless a markup change is necessary for accessibility.\n4. Run `npm run lint`. Run the nearest existing test command from package.json if one is already present; do not invent a test framework.\n5. Run `npm run dev` and prove the result in a browser at `http://127.0.0.1:3000<ROUTE>` or the port printed by the dev server.\n\nExpected output: a focused diff, the commands run, a browser screenshot saved as `artifacts/image-to-design-dashboard-card.png`, and a short review note listing inspected files plus any intentional differences from the reference.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n```text\npackage.json\n```\n\n```text\n<COMPONENT_OR_ROUTE_PATHS>\n```\n\n```text\n<CURRENT_SCREENSHOT_PATH>\n```\n\n```text\n<SELECTED_REFERENCE_IMAGE_PATH>\n```\n\n#### Browser verification\n\nUse a CMUX browser pane or an agent-browser-style flow: open `http://127.0.0.1:3000<ROUTE>`, take an accessibility snapshot to confirm the card title, values, and CTA names are still present, then use evaluate to capture bounding boxes and computed styles for the card root, heading, primary value, and CTA. Save a screenshot after the DOM proof; a screenshot alone is not enough.\n\n#### Definition of done\n\n- Git diff is limited to the target component/route and supporting style files.\n- `npm run lint` passes, and any pre-existing nearest test command either passes or the failure is documented with exact output.\n- `artifacts/image-to-design-dashboard-card.png` shows the local route matching the selected reference direction closely enough for human review.\n- Browser proof includes accessibility snapshot evidence that labels, values, links, and CTA names were not lost.\n- Review note explicitly says which reference image was used and confirms no other variation was blended in.\n\n#### Failure modes and mitigations\n\n- The agent averages several generated directions into a mushy UI; mitigate by removing non-selected references from context and repeating: implement ONLY <SELECTED_REFERENCE_IMAGE_PATH>.\n- The agent rewrites data loading or auth while chasing the visual target; mitigate by requiring source inspection first and rejecting diffs outside the target UI/styling surface.\n- The agent claims visual success from code only; mitigate by requiring browser screenshot plus accessibility snapshot/evaluate evidence from the running dev server.\n\n### Auth-gated onboarding visual refresh\n\n**Role:** As a full-stack product engineer responsible for a SaaS onboarding flow\n\nThe onboarding flow behind login is functional, but the organization setup step needs to match a selected generated reference image. The proof has to run through the real browser flow because the page depends on auth state, form validation, redirects, and route guards.\n\n> As a product engineer, I want the agent to apply the selected image direction to the onboarding step and verify it through login and form interaction, so that the visual refresh does not break the first-run user path.\n\n#### Agent brief\n\n```text\nCopy-paste to Codex:\n\nApply image-to-design handoff to the onboarding screen at <ONBOARDING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current screenshot <CURRENT_SCREENSHOT_PATH>, explicit login or seed instructions <AUTH_INSTRUCTIONS>, and source hints <AUTH_FILES_AND_ONBOARDING_FILES>.\n\n1. Inspect the route, auth guard, form component, validation messages, and existing tests before editing. Do not assume browser cookies are shared with the automation environment.\n2. Implement ONLY the visual direction in <SELECTED_REFERENCE_IMAGE_PATH>. Preserve the onboarding state machine, validation behavior, submit handlers, redirects, copy, and analytics/data attributes.\n3. If a selected reference is missing, generate one sheet of 5 visual variations for this onboarding step, then stop for human selection before editing code.\n4. Run `npm run lint`. If package.json already defines a relevant test, run that exact script. Do not add a new browser framework just to prove this change.\n5. Run `npm run dev`. Verify in a browser from login through <ONBOARDING_ROUTE> using <AUTH_INSTRUCTIONS>.\n\nExpected output: focused UI diff, command logs, `artifacts/onboarding-before-or-current.png` if available, `artifacts/onboarding-after-selected-reference.png`, and a short proof note covering login, validation, successful submit or expected blocked submit, and any console/dev-server errors.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n```text\npackage.json\n```\n\n```text\n<AUTH_FILES_AND_ONBOARDING_FILES>\n```\n\n```text\n<AUTH_INSTRUCTIONS>\n```\n\n```text\n<CURRENT_SCREENSHOT_PATH>\n```\n\n```text\n<SELECTED_REFERENCE_IMAGE_PATH>\n```\n\n#### Browser verification\n\nUse agent-browser-style actions: snapshot the login screen, fill the explicit test email/password or complete the provided seed-login path, click through to <ONBOARDING_ROUTE>, snapshot the form, fill a realistic organization name, click Continue, and evaluate that validation text, focus state, and redirect/blocked-submit behavior still match the original flow. This is the right proof because auth, route guards, and form behavior cannot be trusted from a static screenshot.\n\n#### Definition of done\n\n- Browser path starts from an unauthenticated state and reaches the onboarding screen through the documented login or seed flow.\n- The refreshed onboarding screen visually follows the selected reference image while preserving form labels, validation, focus states, and submit behavior.\n- `npm run lint` passes and relevant existing tests pass or exact failure output is included.\n- Screenshot and browser snapshot artifacts are saved under `artifacts/` with names tied to the route.\n- The final note calls out that cookies were not assumed and names the auth path used.\n\n#### Failure modes and mitigations\n\n- The browser agent gets stuck because it expects the human's normal cookies; mitigate by giving explicit auth/seed instructions and starting proof from a clean browser state.\n- The visual refresh hides validation or keyboard focus states; mitigate by tabbing through the form and evaluating visible focus/validation output before declaring done.\n- The agent changes redirects or submit logic while editing the screen; mitigate by diff-reviewing handlers and requiring the browser path to prove submit or expected blocked submit.\n\n### Responsive marketing hero handoff\n\n**Role:** As a growth-focused web developer shipping a marketing route\n\nA landing page hero needs to move from vague direction like 'more premium' to a concrete selected image. The desktop composition is the design target, but the implementation also needs mobile proof because the route is public and responsive.\n\n> As a growth developer, I want the agent to translate one selected hero reference into the actual landing page while preserving CTA behavior and responsive layout, so that the shipped page has a clear visual direction and does not break conversion paths.\n\n#### Agent brief\n\n```text\nCopy-paste to Codex:\n\nImplement the selected image-to-design direction for the marketing hero at <MARKETING_ROUTE>. Artifacts: selected reference image <SELECTED_REFERENCE_IMAGE_PATH>, current route screenshot <CURRENT_SCREENSHOT_PATH>, and relevant source files <HERO_ROUTE_AND_COMPONENT_FILES>.\n\n1. Inspect package.json, the hero route/component files, and any shared button/link components before editing. Preserve copy, hrefs, tracking attributes, data-testid values, and form/newsletter behavior.\n2. If there is no selected reference image, ask an image model for a sheet of 5 hero variations from the current screenshot and product constraints, then stop for human selection.\n3. Implement only the selected direction. Match composition, rhythm, spacing, type scale, contrast, image/illustration treatment, and CTA prominence. Do not introduce a maintained design system or broad route-variant workflow for this task.\n4. Run `npm run lint` and any existing route/component test script listed in package.json.\n5. Run `npm run dev` and prove desktop and mobile in the browser.\n\nExpected output: a focused diff, desktop screenshot `artifacts/hero-desktop-selected-reference.png`, mobile screenshot `artifacts/hero-mobile-selected-reference.png`, command output, and a concise implementation note describing how the selected image was translated into code.\n```\n\n#### Implementation references\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n```text\npackage.json\n```\n\n```text\n<HERO_ROUTE_AND_COMPONENT_FILES>\n```\n\n```text\n<CURRENT_SCREENSHOT_PATH>\n```\n\n```text\n<SELECTED_REFERENCE_IMAGE_PATH>\n```\n\n#### Browser verification\n\nUse a local browser, CMUX browser pane, or Playwright if already present. Open `http://127.0.0.1:3000<MARKETING_ROUTE>` at 1440x900 and 390x844. Take screenshots at both sizes. Use evaluate to assert `document.documentElement.scrollWidth <= document.documentElement.clientWidth`, the primary CTA is visible without horizontal scroll, and the CTA href/data attributes are unchanged.\n\n#### Definition of done\n\n- Desktop and mobile screenshots are both saved and reviewable.\n- No horizontal overflow at the mobile viewport.\n- Primary CTA remains visible, clickable, and wired to the original href or handler.\n- `npm run lint` and any relevant existing test script pass or include exact failure logs.\n- Final review note maps the selected image's visible traits to concrete implementation choices: spacing, type, color, layout, and CTA treatment.\n\n#### Failure modes and mitigations\n\n- The agent overfits the desktop reference and breaks mobile; mitigate by making mobile viewport proof part of done, not a later nice-to-have.\n- The agent replaces tracked links/buttons while restyling; mitigate by preserving hrefs, handlers, data-testid values, and analytics attributes and checking them with browser evaluate.\n- The agent turns a one-screen handoff into a broad design-system rewrite; mitigate by limiting scope to <HERO_ROUTE_AND_COMPONENT_FILES> and the selected image direction.\n\n## Implementation notes\n\n- Keep the technique narrow: image sheet, human selection, implement only the selected reference, browser proof.\n- For web apps, the selected image is not enough. The agent must inspect current source first so it preserves data loading, auth, handlers, copy, tests, and route behavior.\n- Use Codex or a persistent coding agent for the implementation pass. Fast Flash-style models are a poor fit for a multi-step UI implementation that may require self-correction.\n- Use deterministic scripts and browser checks for proof. Do not wrap a direct CLI or test command in MCP just because MCP is available.\n- Do not claim pixel perfection. Ask for concrete evidence: screenshots, accessibility snapshots, computed style or bounding-box checks, command logs, and a short diff review note.\n- When auth is involved, do not assume cookies are available. Provide explicit login, seed, or test-account instructions and prove the flow from a clean browser state.\n- Generated reference images can express taste, but the human selection is the decision point. The agent should stop before implementation when no selected reference exists.\n\n## Boundaries and caveats\n\n- Do not turn this into an Impeccable or Google Stitch tutorial. Impeccable was only lightly highlighted, and the lesson did not teach a full `npx impeccable` workflow.\n- Do not introduce Google Stitch, Executor, Clicklight, pi.dev, or broad tool comparisons as required implementation steps for this topic.\n- Do not use a maintained Storybook/design-system expansion as the default answer; that is beyond this one toolkit technique.\n- Do not let the agent blend several generated variations. The handoff depends on one selected reference image.\n- Do not change business logic, auth, analytics, or data fetching unless the requested visual handoff explicitly requires it.\n- Do not hide behind an MCP wrapper when a direct repo-local command, browser check, or script is clearer and easier to verify.\n- Do not treat browser screenshots as the only proof for interactive web flows; include snapshot/click/fill/evaluate evidence where interaction matters.\n\n## Agent reference map\n\n### Image-to-design handoff prompt\n\nUse as the base copy-paste workflow: generate a sheet, pause for human selection, then implement only the chosen reference image.\n\n[Open reference](/topics/foundations-image-to-design-playbook/)\n\n### Lesson 06 validated references\n\nGrounds the scenarios in the taught concepts: CMUX orchestration, model choice by task shape, generated images as design references, video context, and MCP-vs-CLI boundaries.\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n### Lesson 06 validation notes\n\nUse this to avoid reintroducing items that were only mentioned or softened, especially around Impeccable, Google Stitch, Executor, Clicklight, and pi.dev.\n\n[Open reference](/topics/foundations-multimodal-design-and-model-routing/)\n\n### Packed source bundle\n\nUse as the local bundle snapshot when an agent needs the prompt, references, catalog context, and Gemini analysis in one place.\n\n```text\n/mnt/data/scenario-image-design.txt\n```\n\n### CMUX browser or pane state\n\nUse when the agent needs to identify the current pane or coordinate browser proof from a CMUX workspace.\n\n```text\ncmux --json tree\n```\n\n### Browser verification primitive shape\n\nUse for web proof after implementation: snapshot for accessible structure, click/fill for flows, evaluate for DOM/style assertions, and screenshot for human visual review.\n\n```text\nagent-browser-style workflow: snapshot -> click/fill -> evaluate -> screenshot\n```"
    },
    {
      "id": "codex-imp-hook-files",
      "slug": "imp-hook-files",
      "title": "Imp routing hook and cmux helper examples",
      "summary": "Complete dash-prefix routing template, hook registration, cmux pane dispatch helper, and session-registry lookup example, with trust, logging, timeout, and incomplete-implementation boundaries.",
      "category": "Tools",
      "tags": [
        "imps",
        "hooks",
        "cmux"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/cmux-codex-session-registry.py.example",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/cmux-run-surface.example",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/hooks.json.example",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/imp-user-prompt-submit.py.template",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 1655,
      "url": "/topics/codex-imp-hook-files/",
      "markdownUrl": "/markdown/codex-imp-hook-files.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-imp-hook-files.json",
      "headings": [
        {
          "id": "safety-and-completeness-boundaries",
          "text": "Safety and completeness boundaries",
          "level": 2
        },
        {
          "id": "hooks-cmux-codex-session-registry-py-example",
          "text": "hooks/cmux-codex-session-registry.py.example",
          "level": 2
        },
        {
          "id": "hooks-cmux-run-surface-example",
          "text": "hooks/cmux-run-surface.example",
          "level": 2
        },
        {
          "id": "hooks-hooks-json-example",
          "text": "hooks/hooks.json.example",
          "level": 2
        },
        {
          "id": "hooks-imp-user-prompt-submit-py-template",
          "text": "hooks/imp-user-prompt-submit.py.template",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Imp routing hook and cmux helper examples\n\nThese examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.\n\n## Safety and completeness boundaries\n\n- The fork template bypasses approvals and sandboxing. Review this explicitly before installing any hook; prompt interception is executable code, not just a prompt convention.\n- The registry example only reads mappings. It neither registers sessions nor implements a screen-scraping fallback; `--allow-screen` is an accepted compatibility argument.\n- The cmux helper receipt proves dispatch to a surface, not successful completion of the command. Verify target workspace, working directory, and resulting behavior.\n- Hook logs may contain prompt text, local paths, session identifiers, and subprocess output. Keep runtime logs private and review retention/redaction.\n- Test ambiguous prefixes, timeouts, and hook errors against the installed roster. Do not infer that every routing failure blocks or that a timeout means no pane was opened.\n\n## hooks/cmux-codex-session-registry.py.example\n\n```python\n#!/usr/bin/env python3\n\"\"\"Redacted cmux-to-Codex session registry contract.\n\nThis example documents the command surface used by zsh helpers such as\n`_codex_cmux_current_session_id`. It is intentionally not a copy of a private\nregistry implementation.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport json\nimport sys\nfrom pathlib import Path\n\n\ndef registry_path() -> Path:\n    return Path.home() / \".codex\" / \"cmux-codex-sessions.json\"\n\n\ndef load_registry(path: Path) -> dict[str, str]:\n    if not path.exists():\n        return {}\n    data = json.loads(path.read_text())\n    if not isinstance(data, dict):\n        raise ValueError(\"registry must be a JSON object\")\n    return {str(key): str(value) for key, value in data.items()}\n\n\ndef main() -> int:\n    parser = argparse.ArgumentParser(description=\"Resolve cmux surface ids to Codex session ids.\")\n    parser.add_argument(\"--registry-path\", action=\"store_true\", help=\"print the registry path\")\n    parser.add_argument(\"--resolve-surface\", help=\"surface id, for example surface:123\")\n    parser.add_argument(\"--allow-screen\", action=\"store_true\", help=\"accepted for compatibility\")\n    args = parser.parse_args()\n\n    path = registry_path()\n    if args.registry_path:\n        print(path)\n        return 0\n\n    if args.resolve_surface:\n        session_id = load_registry(path).get(args.resolve_surface)\n        if not session_id:\n            return 1\n        print(session_id)\n        return 0\n\n    parser.print_help(sys.stderr)\n    return 2\n\n\nif __name__ == \"__main__\":\n    raise SystemExit(main())\n```\n\n## hooks/cmux-run-surface.example\n\n```sh\n#!/bin/sh\n# Example contract for opening a new focused cmux terminal pane and running a command.\n# Review before installing as ~/.local/bin/cmux-run-surface.\nset -eu\n\nCMUX=\"${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}\"\nJQ=\"${JQ_BIN:-/usr/bin/jq}\"\nLOG=\"$HOME/Library/Logs/cmux-run-surface.log\"\n\nDIRECTION=\"right\"\ncase \"${1:-}\" in\n  --below|--down)\n    DIRECTION=\"down\"\n    shift\n    ;;\n  --right)\n    shift\n    ;;\nesac\n\nCOMMAND_TEXT=\"${1:-}\"\n[ -n \"$COMMAND_TEXT\" ] || {\n  /bin/echo \"Usage: cmux-run-surface [--below|--right] <command>\" >&2\n  exit 64\n}\n\nlog() { /bin/echo \"[$(/bin/date '+%Y-%m-%d %H:%M:%S')] $*\" >> \"$LOG\"; }\n\n[ -x \"$CMUX\" ] || { log \"cmux CLI not found at $CMUX\"; exit 1; }\n[ -x \"$JQ\" ] || { log \"jq not found at $JQ\"; exit 1; }\n\ncur=\"$(\"$CMUX\" rpc workspace.current 2>>\"$LOG\")\"\nCWD=\"$(/bin/echo \"$cur\" | \"$JQ\" -r '.workspace.current_directory // empty')\"\nWORKSPACE_ID=\"$(/bin/echo \"$cur\" | \"$JQ\" -r '.workspace_id // .workspace.id // empty')\"\nWINDOW_ID=\"$(/bin/echo \"$cur\" | \"$JQ\" -r '.window_id // .window.id // empty')\"\n\n[ -n \"$CWD\" ] || { log \"no current_directory in workspace.current: $cur\"; exit 1; }\n[ -n \"$WORKSPACE_ID\" ] || { log \"no workspace id in workspace.current: $cur\"; exit 1; }\n[ -n \"$WINDOW_ID\" ] || { log \"no window id in workspace.current: $cur\"; exit 1; }\n\npane_output=\"$(\"$CMUX\" rpc pane.create \"{\\\"workspace_id\\\":\\\"$WORKSPACE_ID\\\",\\\"window_id\\\":\\\"$WINDOW_ID\\\",\\\"direction\\\":\\\"$DIRECTION\\\",\\\"type\\\":\\\"terminal\\\",\\\"focus\\\":true}\" 2>>\"$LOG\")\"\nPANE_ID=\"$(/bin/echo \"$pane_output\" | \"$JQ\" -r '.pane_id // .pane.id // empty')\"\nPANE_REF=\"$(/bin/echo \"$pane_output\" | \"$JQ\" -r '.pane_ref // .pane.ref // empty')\"\nWORKSPACE_REF=\"$(/bin/echo \"$pane_output\" | \"$JQ\" -r '.workspace_ref // .workspace.ref // empty')\"\nWINDOW_REF=\"$(/bin/echo \"$pane_output\" | \"$JQ\" -r '.window_ref // .window.ref // empty')\"\n\n[ -n \"$PANE_ID\" ] || { log \"no pane id in pane.create output: $pane_output\"; exit 1; }\n\nSURFACE=\"\"\ni=0\nwhile [ \"$i\" -lt 20 ]; do\n  surfaces_output=\"$(\"$CMUX\" rpc pane.surfaces \"{\\\"pane_id\\\":\\\"$PANE_ID\\\",\\\"workspace_id\\\":\\\"$WORKSPACE_ID\\\",\\\"window_id\\\":\\\"$WINDOW_ID\\\"}\" 2>>\"$LOG\")\"\n  SURFACE=\"$(/bin/echo \"$surfaces_output\" | \"$JQ\" -r '.surfaces[]? | select((.type // \"\") == \"terminal\") | .ref // .id' | /usr/bin/head -n 1)\"\n  [ -n \"$SURFACE\" ] && break\n  i=$((i + 1))\n  /bin/sleep 0.1\ndone\n\n[ -n \"$SURFACE\" ] || { log \"could not find terminal surface in pane: $PANE_ID\"; exit 1; }\n\n\"$CMUX\" send --workspace \"$WORKSPACE_ID\" --surface \"$SURFACE\" \"$COMMAND_TEXT\" 2>>\"$LOG\"\n\"$CMUX\" send-key --workspace \"$WORKSPACE_ID\" --surface \"$SURFACE\" enter 2>>\"$LOG\"\n\n# Stable receipt consumed by the Imp hook.\n/bin/echo \"OK surface=$SURFACE pane=${PANE_REF:-$PANE_ID} workspace=${WORKSPACE_REF:-$WORKSPACE_ID} window=${WINDOW_REF:-$WINDOW_ID}\"\n```\n\n## hooks/hooks.json.example\n\n```json\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"python3 \\\"$HOME/.codex/hooks/imp-user-prompt-submit.py\\\"\",\n            \"timeout\": 5,\n            \"statusMessage\": \"Routing imp prompt\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n## hooks/imp-user-prompt-submit.py.template\n\n```python\n#!/usr/bin/env python3\n\"\"\"Example UserPromptSubmit hook for dash-prefix Imp routing.\n\nInstall target after review:\n  ~/.codex/hooks/imp-user-prompt-submit.py\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport re\nimport shlex\nimport shutil\nimport subprocess\nimport sys\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom typing import Any\n\n\nIMP_LINE_RE = re.compile(r\"^\\s{2}(imp-[a-z0-9][a-z0-9-]*)\\s+(.+?)\\s*$\")\nPROMPT_RE = re.compile(r\"^\\s*-([A-Za-z0-9][A-Za-z0-9_-]*)(?:\\s+([\\s\\S]*))?$\")\nFORK_PROMPT_RE = re.compile(r\"^\\s*--([A-Za-z0-9][A-Za-z0-9_-]*)(?:\\s+([\\s\\S]*))?$\")\nCMUX_RECEIPT_RE = re.compile(r\"\\b(surface|pane|workspace|window)[=:]([A-Za-z0-9_.:-]+)\")\n\n\n@dataclass(frozen=True)\nclass Imp:\n    command: str\n    description: str\n    executable_path: str = \"\"\n\n    @property\n    def name(self) -> str:\n        return self.command.removeprefix(\"imp-\")\n\n\ndef log(event: dict[str, Any]) -> None:\n    try:\n        path = Path(os.environ.get(\"CODEX_HOME\", \"~/.codex\")).expanduser() / \"logs\" / \"imp-user-prompt-submit.jsonl\"\n        path.parent.mkdir(parents=True, exist_ok=True)\n        with path.open(\"a\", encoding=\"utf-8\") as handle:\n            handle.write(json.dumps(event, sort_keys=True) + \"\\n\")\n    except Exception:\n        pass\n\n\ndef emit_continue(additional_context: str | None = None) -> None:\n    out: dict[str, Any] = {\"continue\": True, \"suppressOutput\": True}\n    if additional_context:\n        out[\"hookSpecificOutput\"] = {\n            \"hookEventName\": \"UserPromptSubmit\",\n            \"additionalContext\": additional_context,\n        }\n    print(json.dumps(out, separators=(\",\", \":\")))\n\n\ndef emit_block(reason: str) -> None:\n    print(\n        json.dumps(\n            {\n                \"continue\": True,\n                \"decision\": \"block\",\n                \"reason\": reason,\n                \"suppressOutput\": False,\n            },\n            separators=(\",\", \":\"),\n        )\n    )\n\n\ndef read_payload() -> dict[str, Any]:\n    raw = sys.stdin.read()\n    if not raw.strip():\n        return {}\n    return json.loads(raw)\n\n\ndef read_imps() -> list[Imp]:\n    imp_palette = shutil.which(\"imp-\")\n    if not imp_palette:\n        return []\n    result = subprocess.run(\n        [imp_palette],\n        check=False,\n        stdout=subprocess.PIPE,\n        stderr=subprocess.DEVNULL,\n        text=True,\n        timeout=2,\n    )\n    if result.returncode != 0:\n        return []\n    imps: list[Imp] = []\n    for line in result.stdout.splitlines():\n        match = IMP_LINE_RE.match(line)\n        if not match:\n            continue\n        command = match.group(1)\n        imps.append(\n            Imp(\n                command=command,\n                description=match.group(2).strip(),\n                executable_path=shutil.which(command) or \"\",\n            )\n        )\n    return imps\n\n\ndef normalize_name(raw: str) -> str:\n    return raw.strip().lower().replace(\"_\", \"-\").removeprefix(\"imp-\")\n\n\ndef acronym(text: str) -> str:\n    return \"\".join(part[0] for part in re.split(r\"[-\\s]+\", text) if part)\n\n\ndef is_subsequence(needle: str, haystack: str) -> bool:\n    pos = 0\n    for char in needle:\n        found = haystack.find(char, pos)\n        if found < 0:\n            return False\n        pos = found + 1\n    return True\n\n\ndef score_imp(query: str, imp: Imp) -> int:\n    name = imp.name\n    description = imp.description.lower()\n    words = set(re.findall(r\"[a-z0-9]+\", description))\n    if query == name or query == imp.command:\n        return 100\n    if name.startswith(query):\n        return 85\n    if query.startswith(name):\n        return 80\n    if query == acronym(name):\n        return 78\n    if query in name:\n        return 70\n    if query in words:\n        return 62\n    if query in description:\n        return 55\n    if len(query) >= 3 and is_subsequence(query, name):\n        return 48\n    return 0\n\n\ndef find_imp(raw_name: str, imps: list[Imp]) -> tuple[Imp | None, list[tuple[int, Imp]]]:\n    query = normalize_name(raw_name)\n    ranked = sorted(\n        ((score_imp(query, imp), imp) for imp in imps),\n        key=lambda item: (-item[0], item[1].command),\n    )\n    ranked = [item for item in ranked if item[0] > 0]\n    if not ranked:\n        return None, []\n    best_score, best = ranked[0]\n    runner_up = ranked[1][0] if len(ranked) > 1 else 0\n    if best_score >= 80 or (best_score >= 55 and best_score - runner_up >= 12):\n        return best, ranked\n    return None, ranked\n\n\ndef block_reason(raw_name: str, ranked: list[tuple[int, Imp]]) -> str:\n    if ranked:\n        options = \", \".join(f\"{imp.command} ({imp.description})\" for _, imp in ranked[:5])\n        return (\n            f\"I could not confidently map '-{raw_name}' to an imp. \"\n            f\"Did you mean one of these: {options}? \"\n            \"Please resubmit with the exact imp name, or ask whether to create a new imp with imp-create.\"\n        )\n    return (\n        f\"I could not find an imp matching '-{raw_name}'. \"\n        \"Please be more specific, or ask whether to create a new imp with imp-create.\"\n    )\n\n\ndef normalized_single_dash_prompt(imp: Imp, task: str) -> str:\n    return f\"-{imp.name} {task.strip()}\".strip()\n\n\ndef fork_inner_command(session_id: str, single_dash_prompt: str) -> str:\n    return \" \".join(\n        [\n            \"codex\",\n            \"-c\",\n            shlex.quote('shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'),\n            \"--dangerously-bypass-approvals-and-sandbox\",\n            \"fork\",\n            shlex.quote(session_id),\n            \"--\",\n            shlex.quote(single_dash_prompt),\n        ]\n    )\n\n\ndef run_fork(session_id: str, single_dash_prompt: str) -> subprocess.CompletedProcess[str]:\n    run_surface = str(Path.home() / \".local/bin/cmux-run-surface\")\n    return subprocess.run(\n        [run_surface, fork_inner_command(session_id, single_dash_prompt)],\n        check=False,\n        stdout=subprocess.PIPE,\n        stderr=subprocess.PIPE,\n        text=True,\n        timeout=4,\n    )\n\n\ndef parse_cmux_receipt(stdout: str) -> dict[str, str]:\n    receipt: dict[str, str] = {}\n    for line in stdout.splitlines():\n        if not line.startswith(\"OK \"):\n            continue\n        for key, value in CMUX_RECEIPT_RE.findall(line):\n            receipt[key] = value\n    return receipt\n\n\ndef cmux_check_instructions(receipt: dict[str, str]) -> str:\n    workspace = receipt.get(\"workspace\", \"<workspace>\")\n    surface = receipt.get(\"surface\", \"<surface>\")\n    pane = receipt.get(\"pane\", \"<pane>\")\n    return (\n        \"Check this fork later with: \"\n        f\"cmux read-screen --workspace {workspace} --surface {surface} --scrollback --lines 80 ; \"\n        f\"cmux top --workspace {workspace} --processes --flat --format tsv ; \"\n        f\"cmux focus-pane --workspace {workspace} --pane {pane}\"\n    )\n\n\ndef main() -> int:\n    try:\n        payload = read_payload()\n        prompt = str(payload.get(\"prompt\") or \"\")\n        fork = False\n        match = FORK_PROMPT_RE.match(prompt)\n        if match:\n            fork = True\n        else:\n            match = PROMPT_RE.match(prompt)\n        if not match:\n            emit_continue()\n            return 0\n\n        raw_name = match.group(1)\n        task = (match.group(2) or \"\").strip()\n        if not task:\n            emit_block(f\"Please include a task after '-{raw_name}', for example '-{raw_name} do the thing'.\")\n            return 0\n\n        imp, ranked = find_imp(raw_name, read_imps())\n        if not imp:\n            emit_block(block_reason(raw_name, ranked))\n            return 0\n\n        executable = imp.executable_path or imp.command\n        cwd = str(payload.get(\"cwd\") or \"\").strip()\n\n        if fork:\n            session_id = str(payload.get(\"session_id\") or os.environ.get(\"CODEX_THREAD_ID\") or \"\").strip()\n            if not session_id:\n                emit_block(f\"Could not fork '-{imp.name}' because the hook payload did not include a Codex session id.\")\n                return 0\n            single_dash_prompt = normalized_single_dash_prompt(imp, task)\n            result = run_fork(session_id, single_dash_prompt)\n            receipt = parse_cmux_receipt(result.stdout)\n            log(\n                {\n                    \"event\": \"fork_opened\" if result.returncode == 0 else \"fork_error\",\n                    \"imp\": imp.command,\n                    \"task\": task,\n                    \"cwd\": cwd,\n                    \"session_id\": session_id,\n                    \"single_dash_prompt\": single_dash_prompt,\n                    \"stdout\": result.stdout,\n                    \"stderr\": result.stderr,\n                    \"cmux\": receipt,\n                }\n            )\n            if result.returncode != 0:\n                emit_block(f\"Could not open a cmux fork for '-{imp.name}'. stderr: {result.stderr.strip() or '(none)'}\")\n                return 0\n            emit_block(\n                \"\\n\".join(\n                    [\n                        f\"Opened a cmux fork for {imp.command} with: {single_dash_prompt}\",\n                        f\"cmux workspace: {receipt.get('workspace', 'unknown')}\",\n                        f\"cmux pane: {receipt.get('pane', 'unknown')}\",\n                        f\"cmux surface: {receipt.get('surface', 'unknown')}\",\n                        f\"cmux window: {receipt.get('window', 'unknown')}\",\n                        cmux_check_instructions(receipt),\n                    ]\n                )\n            )\n            return 0\n\n        emit_continue(\n            (\n                f\"The user's prompt began with '-{raw_name}', which is shorthand for invoking {imp.command}.\\n\\n\"\n                \"The UserPromptSubmit hook has already discovered the imp from the command palette \"\n                \"and resolved its executable path. Do not run which, where, find, rg, or other discovery \"\n                \"commands to locate this imp.\\n\\n\"\n                f\"Resolved imp command: {imp.command}\\n\"\n                f\"Resolved executable: {executable}\\n\"\n                f\"imp description: {imp.description}\\n\"\n                f\"Task text: {task}\\n\"\n                f\"Current cwd: {cwd}\\n\\n\"\n                \"Let UserPromptSubmit complete and take this main-agent turn before invoking tools. \"\n                \"Use the current conversation context naturally, then invoke the resolved executable when appropriate.\"\n            )\n        )\n        return 0\n    except Exception as err:\n        log({\"event\": \"error\", \"error\": repr(err)})\n        emit_continue()\n        return 0\n\n\nif __name__ == \"__main__\":\n    raise SystemExit(main())\n```\n\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-tools-publishing",
      "slug": "tools-publishing",
      "title": "Instant web publishing for agents (here.now)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "publishing"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#publishing"
        }
      ],
      "sourceUnits": [
        "resources/index.html#publishing"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 319,
      "url": "/topics/factory-tools-publishing/",
      "markdownUrl": "/markdown/factory-tools-publishing.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-publishing.json",
      "headings": [
        {
          "id": "instant-web-publishing-for-agents-here-now",
          "text": "Instant web publishing for agents (here.now)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Instant web publishing for agents (here.now)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Instant web publishing for agents (here.now)\n\n**John uses:** [here.now](https://here.now/) — instant hosting *for agents*: publish any folder to `{slug}.here.now` (anonymous 24-hour sites with no sign-up; permanent with an API key), plus private cloud Drives agents share across sessions. All 11 workshop pages publish through its skill.\n\n**Honest note:** the agent-first combination (skill-driven publish + agent Drives + no-signup anonymous sites) is fairly unique. These cover the static-publish half:\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [surge.sh](https://github.com/sintaxi/surge) | CLI for publishing static sites to the surge.sh CDN in one command | The classic one-command static publish; no agent-native skill or drives | none listed |\n| [Cloudflare Pages (wrangler)](https://github.com/cloudflare/workers-sdk) | wrangler CLI deploys static sites/functions to Cloudflare's edge (John's inspiration-board uses it) | Free, permanent, custom domains; needs an account and a project | Apache-2.0 |\n| [Vercel](https://github.com/vercel/vercel) | \\`vercel deploy\\` for static or full-stack sites with preview URLs | Preview-deploy workflow, generous free tier; heavier platform | Apache-2.0 |\n| [GitHub Pages](https://pages.github.com/) | Free static hosting from a repo branch | Requires a git repo (this workshop repo deliberately isn't one); slower publish loop | product |\n| [Netlify Drop](https://app.netlify.com/drop) | Drag-and-drop a folder, get a live URL | Closest no-friction analog for humans; no CLI-first anonymous mode like here.now's | product |\n\n### Pick this if…\n\n- **surge** — you want the closest one-command feel from a terminal.\n- **Cloudflare Pages** — you want free, permanent, custom-domain hosting your agent can drive via wrangler.\n- **Vercel** — you want preview-per-change workflows or the site may grow a backend.\n- **Netlify Drop** — you need a URL in 10 seconds and don't mind doing it by hand.\n- **GitHub Pages** — your content already lives in a repo (note: this workshop repo intentionally isn't one)."
    },
    {
      "id": "factory-tools-state-capture-markers",
      "slug": "tools-state-capture-markers",
      "title": "Just-in-time state capture (markers)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "state-capture-markers"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#state-capture-markers"
        }
      ],
      "sourceUnits": [
        "resources/index.html#state-capture-markers"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 322,
      "url": "/topics/factory-tools-state-capture-markers/",
      "markdownUrl": "/markdown/factory-tools-state-capture-markers.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-state-capture-markers.json",
      "headings": [
        {
          "id": "just-in-time-state-capture-markers",
          "text": "Just-in-time state capture (markers)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Just-in-time state capture (markers)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Just-in-time state capture (markers)\n\n**John uses:** **agent-markers** (section 09; pattern page at [mindful-mango-accy.here.now](https://mindful-mango-accy.here.now/)) — a \\<300-line, dependency-free recorder: console/fetch/error/click patched into a ring buffer, a  Mark keystroke pins one sentence of human testimony to nearby events, and the export renders into a redacted agent-ready debug packet. The differentiator is *testimony as a first-class artifact* and privacy-by-redaction.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [rrweb](https://github.com/rrweb-io/rrweb) | Record and replay the web: DOM-level session recording library | Full DOM replay vs markers' redacted event trail; the building block most replay products use | MIT |\n| [OpenReplay](https://github.com/openreplay/openreplay) | Self-hostable session replay + product analytics for reproducing issues | Always-on infrastructure with a server; markers is a one-file, moment-of-surprise capture | NOASSERTION (ELv2/MIT mix) |\n| [Highlight](https://github.com/highlight/highlight) | OSS full-stack monitoring: session replay, errors, logs, traces | Monitoring-platform scale; check current repository activity | NOASSERTION (Apache-2.0 core) |\n| [Sentry Session Replay](https://github.com/getsentry/sentry) | Session replay wired to error tracking in Sentry | Error-first: replays attach to exceptions rather than to human testimony | NOASSERTION (FSL) |\n| [Jam](https://jam.dev/) | Chrome extension: one-click bug reports with replay, console logs, network requests, device details | Commercial, human-in-the-loop like markers — the closest 'press a button at the moment of surprise' product; output targets issue trackers, not agent prompts | commercial (free tier) |\n\n### Pick this if…\n\n- **Jam** — the closest commercial \"press a button at the moment of surprise\" tool; output targets issue trackers rather than agent prompts.\n- **rrweb** — you're building your own marker system and want full DOM replay under it.\n- **OpenReplay / Highlight** — you want always-on capture infrastructure you control.\n- **Sentry** — your entry point is errors, not human testimony.\n- Or lift the workshop's recorder itself — it's ~300 dependency-free lines, designed for exactly this."
    },
    {
      "id": "factory-tools-keyboard-customization",
      "slug": "tools-keyboard-customization",
      "title": "Keyboard customization (Karabiner-Elements)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "keyboard-customization"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#keyboard-customization"
        }
      ],
      "sourceUnits": [
        "resources/index.html#keyboard-customization"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 295,
      "url": "/topics/factory-tools-keyboard-customization/",
      "markdownUrl": "/markdown/factory-tools-keyboard-customization.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-keyboard-customization.json",
      "headings": [
        {
          "id": "keyboard-customization-karabiner-elements",
          "text": "Keyboard customization (Karabiner-Elements)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Keyboard customization (Karabiner-Elements)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Keyboard customization (Karabiner-Elements)\n\n**John uses:** [Karabiner-Elements](https://github.com/pqrs-org/Karabiner-Elements) (22.5k, Unlicense) with his config written as `karabiner.edn` compiled by [Goku](https://github.com/yqrashawn/GokuRakuJoudo) (1.4k, GPL-3.0, last push the example workflow). Section 06's trick: an app-scoped Esc-hold layer in Ghostty fires internal Ctrl+Alt chords that Herdr's `[[keys.command]]` bindings catch — Karabiner knows the keyboard, Herdr knows the focused pane.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [kanata](https://github.com/jtroo/kanata) | Cross-platform advanced keyboard remapper (layers, tap-hold) in Rust | Works on Linux/Windows/mac; kmonad-style config; no macOS app-scoping as rich as Karabiner's | LGPL-3.0 |\n| [kmonad](https://github.com/kmonad/kmonad) | Advanced keyboard manager (Haskell), layers and macros, cross-platform | The original layer-centric remapper; config is Lisp-flavored like Goku's edn | MIT |\n| [Hammerspoon](https://github.com/Hammerspoon/hammerspoon) | macOS desktop automation scripted in Lua (hotkeys, window management, app events) | Hotkeys plus arbitrary automation logic — can replace the 'chord fires a script' half of John's setup | MIT |\n| [skhd](https://github.com/asmvik/skhd) | Simple hotkey daemon for macOS | Just hotkey→command bindings in a flat config; minimal but no remapping layers; check current repository activity | MIT |\n| [Keyboard Maestro](https://www.keyboardmaestro.com/) | Commercial macOS macro platform (hotkeys, palettes, app-scoped macros) | GUI macro builder, one-time license; closed source | commercial |\n\n### Pick this if…\n\n- **kanata** — you want Karabiner-style layers on Linux or Windows too.\n- **kmonad** — same, with the original Lisp-flavored config (kin to Goku's edn).\n- **Hammerspoon** — your chords should run *logic*, not just keystrokes — it can replace the chord→script half of John's setup.\n- **skhd** — you only need \"hotkey runs command\" with no remapping.\n- **Keyboard Maestro** — you want a GUI and a one-time license instead of config files."
    },
    {
      "id": "factory-tools-markdown-agent-flows",
      "slug": "tools-markdown-agent-flows",
      "title": "Markdown agent flows (mdflow)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "markdown-agent-flows"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#markdown-agent-flows"
        }
      ],
      "sourceUnits": [
        "resources/index.html#markdown-agent-flows"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 327,
      "url": "/topics/factory-tools-markdown-agent-flows/",
      "markdownUrl": "/markdown/factory-tools-markdown-agent-flows.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-markdown-agent-flows.json",
      "headings": [
        {
          "id": "markdown-agent-flows-mdflow",
          "text": "Markdown agent flows (mdflow)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Markdown agent flows (mdflow)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Markdown agent flows (mdflow)\n\n**John uses:** [mdflow](https://github.com/johnlindquist/mdflow) (`md`, 597, MIT) — executable markdown prompts run against Claude, Codex, Gemini, or Copilot. The differentiators, per section 05: prompt-build-time command inlining (`` !`git status` ``), frontmatter `_inputs`, **isolation from all ambient config/hooks/CLAUDE.md**, and eval-gated evolution (`md feedback` → `md eval` → `md evolve`, proposal-first).\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [Claude Code slash commands & skills (built-in)](https://docs.claude.com/en/docs/claude-code) | Markdown files in .claude/commands and .claude/skills that become reusable parameterized agent behaviors | Ships with the agent — but tied to Claude Code and inherits ambient config; mdflow's isolation and multi-engine targeting are the delta | product docs |\n| [dotprompt](https://github.com/google/dotprompt) | Google's executable GenAI prompt template format (.prompt files: frontmatter + template) | A file-format/spec with runtimes, aimed at app code rather than launching coding agents | Apache-2.0 |\n| [BAML](https://github.com/BoundaryML/baml) | A programming language for agents/prompts with typed inputs/outputs and tests | Full typed DSL + toolchain where mdflow stays plain markdown; heavier but testable | Apache-2.0 |\n| [fabric patterns](https://github.com/danielmiessler/Fabric) | Markdown prompt 'patterns' executed via the fabric CLI against any model | Same 'prompt as a file you run' idea, without engine flags, context inlining, or eval-gated evolution | MIT |\n| [llm templates](https://github.com/simonw/llm) | YAML templates with params for the llm CLI | Lightweight parameterized prompts; no agent-loop execution or tool use | Apache-2.0 |\n\n### Pick this if…\n\n- **Claude Code commands/skills** — you're all-in on one agent; you give up mdflow's isolation and multi-engine targeting.\n- **fabric** — you want \"prompt as a runnable file\" without engine flags or context inlining.\n- **llm templates** — lightweight parameterized prompts, no agent loop.\n- **BAML** — you want types and tests around prompts and will trade markdown simplicity for it.\n- **dotprompt** — you're standardizing prompt files inside application code, not agent launches."
    },
    {
      "id": "codex-shell-file-map",
      "slug": "shell-file-map",
      "title": "Navigate the agent-safe shell file set",
      "summary": "Explains the zsh environment and helper files, non-interactive-shell safety practices, and commands for checking tool paths and helper availability.",
      "category": "Tools",
      "tags": [
        "zsh",
        "environment",
        "files"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Included Files",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/What Each File Teaches",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Safety Notes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/README.md#Zsh Reference Files/Core Confirmation Commands",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 382,
      "url": "/topics/codex-shell-file-map/",
      "markdownUrl": "/markdown/codex-shell-file-map.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-file-map.json",
      "headings": [
        {
          "id": "included-files",
          "text": "Included Files",
          "level": 2
        },
        {
          "id": "what-each-file-teaches",
          "text": "What Each File Teaches",
          "level": 2
        },
        {
          "id": "safety-notes",
          "text": "Safety Notes",
          "level": 2
        },
        {
          "id": "core-confirmation-commands",
          "text": "Core Confirmation Commands",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Navigate the agent-safe shell file set\n\nThese files support Section 2, \"Loading ZSH Env Into Codex.\"\n\nThey demonstrate a common Mac/zsh setup where Codex tool shells can see the same safe toolchain paths and selected helper functions without sourcing a full interactive `.zshrc`.\n\n## Included Files\n\n```text\n.zshenv\n.zprofile\ncodex-env.zsh\nconf.d/00-path.zsh\nconf.d/40-ai.zsh\nconf.d/47-ai-fix.zsh\nfunctions/codex-launch-and-prompt-builder.zsh\nfunctions/shell-introspection.zsh\nfunctions/fusion-fix.zsh\nfunctions/orchestration-helpers.zsh\nfunctions/script-kit-process-helpers.zsh\ntests/startup-regression.zsh\nexamples/local.zsh.example\nexamples/codex-config-shell-environment-policy.toml\n```\n\n## What Each File Teaches\n\n| File | Purpose |\n| --- | --- |\n| `.zshenv` | Sets XDG paths and `ZDOTDIR`; optionally loads selected DSL files when `CODEX_LOAD_ZSH_DSL` is present |\n| `.zprofile` | Login-shell bridge for `zsh -lc` |\n| `codex-env.zsh` | Agent-safe environment bootstrap for non-interactive shells |\n| `conf.d/00-path.zsh` | Deterministic PATH assembly |\n| `conf.d/40-ai.zsh` | Small loader for focused workshop helper snippets |\n| `conf.d/47-ai-fix.zsh` | Example workflow helper function |\n| `functions/codex-launch-and-prompt-builder.zsh` | `x`, `xi`, `xfl`, `xfc`, and Prompt Builder handoff helpers |\n| `functions/shell-introspection.zsh` | `funclist`, `funcwhere`, and `funced` |\n| `functions/fusion-fix.zsh` | Fusion-first `fix` helper |\n| `functions/orchestration-helpers.zsh` | `muxai` and reviewed lazy-loader patterns |\n| `functions/script-kit-process-helpers.zsh` | Process cleanup helper examples |\n| `tests/startup-regression.zsh` | Startup behavior checks |\n| `examples/local.zsh.example` | Public shape for machine-local overrides |\n| `examples/codex-config-shell-environment-policy.toml` | Public shape for Codex env policy |\n\n## Safety Notes\n\n- Do not source a full `.zshrc` from agent shells.\n- Do not paste full `env` output into chats or handouts.\n- Keep prompt, completion, keybindings, fuzzy finders, and terminal UI in interactive startup only.\n- Prefer executable wrappers for helper entrypoints that must work outside zsh.\n- Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in.\n\n## Core Confirmation Commands\n\n```bash\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x 2>/dev/null || echo x:not-loaded; type x 2>/dev/null || true'\n```\n\n```bash\nzsh -ic 'functions xi' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'\n```\n\n```bash\nzsh -lc 'source ./zsh/conf.d/40-ai.zsh; whence -w x xi xfl xfc p-f p-c funcwhere muxai fix'\n```\n\n## Operational boundaries\n\n- The file-purpose table describes the intended startup shape. The supplied `.zshenv` does not itself implement the optional DSL loader; review the practical setup prompt and actual local startup chain.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-oracle-packx-runbook",
      "slug": "oracle-packx-runbook",
      "title": "Oracle and PackX execution runbook",
      "summary": "Published browser-only Packx→Oracle skill covering model settings, bundle preparation and validation, compact evidence and attachments, progress-gated follow-ups, blocking session recovery, full-response reading, implementation summaries, optional…",
      "category": "Tools",
      "tags": [
        "oracle",
        "packx",
        "runbook"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Non-Negotiable Runtime Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/ChatGPT Intelligence Setting",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Operating Principle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Output Artifact Boundary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Forward Progress Contract",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Long-Running Expectations",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 1: Choose a slug",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 2: Preview with packx",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 3: Build the bundle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 4: Validate the bundle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 4.5: Add compact evidence when raw context is too large or unsafe",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 5: Add screenshots or artifacts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 6: Call Oracle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 7: Read the full response",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 8: Summarize for execution",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Pipeline/Step 9: Commit phase, only when requested",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Prompt Contract",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Troubleshooting",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/Completion Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/SKILL.md#Packx + Oracle Pipeline/References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 2865,
      "url": "/topics/codex-oracle-packx-runbook/",
      "markdownUrl": "/markdown/codex-oracle-packx-runbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-oracle-packx-runbook.json",
      "headings": [
        {
          "id": "non-negotiable-runtime-mode",
          "text": "Non-Negotiable Runtime Mode",
          "level": 2
        },
        {
          "id": "chatgpt-intelligence-setting",
          "text": "ChatGPT Intelligence Setting",
          "level": 2
        },
        {
          "id": "operating-principle",
          "text": "Operating Principle",
          "level": 2
        },
        {
          "id": "output-artifact-boundary",
          "text": "Output Artifact Boundary",
          "level": 2
        },
        {
          "id": "forward-progress-contract",
          "text": "Forward Progress Contract",
          "level": 2
        },
        {
          "id": "long-running-expectations",
          "text": "Long-Running Expectations",
          "level": 2
        },
        {
          "id": "pipeline",
          "text": "Pipeline",
          "level": 2
        },
        {
          "id": "step-1-choose-a-slug",
          "text": "Step 1: Choose a slug",
          "level": 3
        },
        {
          "id": "step-2-preview-with-packx",
          "text": "Step 2: Preview with packx",
          "level": 3
        },
        {
          "id": "step-3-build-the-bundle",
          "text": "Step 3: Build the bundle",
          "level": 3
        },
        {
          "id": "step-4-validate-the-bundle",
          "text": "Step 4: Validate the bundle",
          "level": 3
        },
        {
          "id": "step-4-5-add-compact-evidence-when-raw-context-is-too-large-or-unsafe",
          "text": "Step 4.5: Add compact evidence when raw context is too large or unsafe",
          "level": 3
        },
        {
          "id": "step-5-add-screenshots-or-artifacts",
          "text": "Step 5: Add screenshots or artifacts",
          "level": 3
        },
        {
          "id": "step-6-call-oracle",
          "text": "Step 6: Call Oracle",
          "level": 3
        },
        {
          "id": "step-7-read-the-full-response",
          "text": "Step 7: Read the full response",
          "level": 3
        },
        {
          "id": "step-8-summarize-for-execution",
          "text": "Step 8: Summarize for execution",
          "level": 3
        },
        {
          "id": "step-9-commit-phase-only-when-requested",
          "text": "Step 9: Commit phase, only when requested",
          "level": 3
        },
        {
          "id": "prompt-contract",
          "text": "Prompt Contract",
          "level": 2
        },
        {
          "id": "troubleshooting",
          "text": "Troubleshooting",
          "level": 2
        },
        {
          "id": "completion-checklist",
          "text": "Completion Checklist",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Oracle and PackX execution runbook\n\nYou are a PIPELINE EXECUTOR. Your job is: packx bundle -> `mcp__oracle__consult` -> read output.log -> summarize Oracle's answer -> optionally commit Oracle-driven implementation changes when the user explicitly asks.\n\nDo not answer the user's question from your own code research. Use local inspection only to build an excellent bundle and prompt. The point of this skill is to spend Oracle's expensive intelligence on high-leverage design, implementation, and review output.\n\n## Non-Negotiable Runtime Mode\n\nOracle MUST always run through the browser engine using the remote browser configuration in `~/.oracle/config.json`. Treat this as a hard stop before every consult call, including follow-up calls.\n\n- Every `mcp__oracle__consult` call MUST set `engine: \"browser\"`.\n- Never use `engine: \"api\"` and never omit `engine`; the API engine's `OPENAI_API_KEY` failure is a caller bug, not a credential blocker.\n- Never switch to API mode because it seems faster, because browser mode timed out, because a smaller/follow-up prompt is being sent, or because a specific model label looks API-only.\n- If a planned Oracle call object contains `engine: \"api\"` or lacks `engine: \"browser\"`, discard that call object before invoking the tool and rebuild it in browser mode.\n- Model choice must be expressed through browser-compatible fields such as `browserModelLabel` and `browserThinkingTime`; do not use API credentials, API model IDs, or API-engine shortcuts.\n- Do not pass ad hoc remote host, token, profile, or browser-routing overrides. Let Oracle read `~/.oracle/config.json`, which owns the remote browser endpoint.\n- If the MCP surface is unavailable, the CLI Oracle recovery path MUST use `oracle --engine browser ...` and the same `~/.oracle` config. Do not add API flags or environment-key workarounds.\n- If any Oracle attempt reports `Missing OPENAI_API_KEY`, immediately retry in browser mode using the `~/.oracle` config instead of asking the user for a key.\n\n## ChatGPT Intelligence Setting\n\noracle-packx is a text/code reasoning workflow, not image generation. Use\nChatGPT **Pro Extended** for every `oracle-packx` consult.\n\nCritical rules:\n\n- Every `mcp__oracle__consult` call in this skill must include\n  `browserThinkingTime: \"extended\"`.\n- Keep `browserModelLabel: \"Latest\"` and `model: \"gpt-5.5-pro\"` unless the user\n  explicitly asks for a different browser model.\n- Never use `browserThinkingTime: \"instant\"` for packx, planning, review,\n  architecture, debugging, or code-analysis consults.\n- Instant is reserved for ChatGPT **Create image** / `imagine` runs only.\n- If the visible ChatGPT Intelligence pill says `Instant` before a packx run,\n  change it back through Oracle by sending `browserThinkingTime: \"extended\"`;\n  do not rely on the current UI state.\n\nGood call shape:\n\n```text\nmcp__oracle__consult({\n  prompt: \"[{slug}]\\n\\n{question}\",\n  files: [\"~/.oracle/bundles/{slug}.txt\"],\n  engine: \"browser\",\n  model: \"gpt-5.5-pro\",\n  browserModelLabel: \"Latest\",\n  browserThinkingTime: \"extended\",\n  slug: \"{slug}\"\n})\n```\n\nBad call shape:\n\n```text\nbrowserThinkingTime: \"instant\"  # image generation only; wrong for oracle-packx\n```\n\n## Operating Principle\n\nOracle is expensive and powerful. Push it for maximum useful output.\n\n- Current validated browser-mode bundle target: up to ~900k tokens. The old ~49k guidance is obsolete.\n- Large bundles may exceed 1 MB on disk; rely on `~/.oracle/config.json` `maxFileSizeBytes` (10 MiB or higher) instead of splitting solely because of the old guard.\n- Ask for comprehensive solutions, not cautious fragments.\n- Ask Oracle to identify the highest-leverage work, sequencing, risks, invariants, tests, logs, and verification receipts.\n- Ask for critical code snippets, exact file/function targets, and implementation notes local agents can execute.\n- Ask Oracle to separate \"must implement now\" from \"later polish\", while still pushing for a meaningful implementation wave.\n- Expect local verification with `$agentic-testing`, logs, targeted tests, and `lat check` to teach us more after Oracle gives the plan.\n\n## Output Artifact Boundary\n\nFor planning, review, debugging, goal-writing, or implementation guidance, Oracle must return text in the chat/session response only. Do not ask Oracle to create, attach, export, or offer a downloadable file as the deliverable.\n\nThe local agent owns every local artifact:\n\n- `~/.oracle/bundles/{slug}.txt` is created locally by `packx`.\n- `~/.oracle/sessions/{slug}/output.log` is Oracle session output captured locally.\n- Repo files, `.goals/*.md`, `.loop/oracle-loop/**`, prompts, plans, review notes, commits, and verification logs are written locally by the agent with local file-editing or shell tools.\n\nIf Oracle creates a downloadable file anyway, do not treat the download as the artifact. Read the response content and write the local artifact yourself. If the only useful content exists inside an unreadable download, rerun Oracle with the no-download constraint emphasized.\n\n## Forward Progress Contract\n\nOracle is not a substitute for doing the work. Before any second or later Oracle call on the same topic, the local agent MUST build a Prior-State Ledger and pass the Forward Progress Gate.\n\nFor a first Oracle call on a new topic, write `prior_oracle_session: none` and continue. For every follow-up Oracle call on the same topic, include this ledger in the Oracle prompt:\n\n```text\nPrior-State Ledger:\n- prior_oracle_session: <slug/path, or none for first call>\n- last_oracle_recommendation: <one-paragraph summary>\n- implemented_since_prior_oracle: <files/functions/tests/receipts changed, or none>\n- verified_since_prior_oracle: <exact command/receipt/result, or none>\n- failed_proof_or_blocker: <exact failed command/output/log/screenshot path, or none>\n- narrowing_decision: <what scope was removed and what one slice remains>\n- files_functions_now_in_scope: <exact paths#symbols>\n- files_functions_out_of_scope: <explicit exclusions>\n- next_falsifiable_verification: <command, receipt, screenshot, or runtime proof>\n- forward_progress_index: <score and arithmetic>\n```\n\nForward Progress Gate: before another Oracle call on the same topic, at least one of these MUST be true:\n\n- `implemented`: files, tests, goal artifacts, or receipts changed since the prior Oracle session.\n- `verified`: a new proof result exists, even if it is red.\n- `blocked`: an exact failed command/output/log/screenshot path exists.\n- `narrowed`: the new prompt removes scope and targets exactly one next shippable slice.\n\nIf none are true, do not call Oracle again. Implement the previous recommendation, run proof, capture a blocker, or narrow the prompt first.\n\nForward Progress Index:\n\n- +3 consumed a prior receipt, failed proof, or blocker\n- +3 selected exactly one new next slice\n- +2 named exact files/functions/tests/commands\n- +2 added falsifiable verification\n- +2 resulted in a checked-in or written goal/test/receipt afterward\n- -3 repeats the same topic without new evidence\n- -4 produces a broad roadmap instead of the next action\n\nTarget score before a follow-up Oracle call: `>= 7`. A score below 7 is allowed only when `blocked` is true and the prompt includes the exact blocker receipt. Record the score in the local goal, loop state, or final summary.\n\n## Long-Running Expectations\n\nOracle browser runs are blocking research sessions. After Codex starts an Oracle call, all local planning, implementation, verification, and independent problem solving MUST pause until Oracle has fully completed and the local Oracle response has been read. There are no elapsed-time exceptions.\n\n- Never assume Oracle timed out or failed based on elapsed time alone.\n- Never proceed independently while Oracle is still processing, even if a wrapper returns after 120s or any other local wait limit.\n- Treat Oracle's response as the required next input. No fallback, workaround, self-directed implementation, or \"I'll continue while it runs\" path is allowed.\n- Reattach with `mcp__oracle__sessions({ id: \"{slug}\", detail: true })` or read `~/.oracle/sessions/{slug}/output.log` when it lands.\n- Health checks are allowed only to reattach, inspect session state, or confirm whether Oracle has produced the final local response. They are not permission to start work.\n- Keep waiting as long as Oracle requires while the session is still processing. There is no Codex-side timeout threshold that permits independent action.\n- Only treat the run as failed when Oracle reports an explicit error, the session exits non-zero, browser automation is blocked, or logs show a terminal failure.\n\nFor packx flags and filter details, see [references/packx-quick-reference.md](/topics/codex-packx-command-reference/).\n\n## Pipeline\n\n### Step 1: Choose a slug\n\nSlug must be 3-5 words separated by hyphens. Oracle rejects slugs outside this range.\n\n```bash\nmkdir -p ~/.oracle/bundles\n```\n\n### Step 2: Preview with packx\n\nRun a dry-run to check file count and estimated size.\n\n```bash\npackx --preview [your-filters] -x \"**/CLAUDE.md\"\n```\n\nStop if 0 files match. Fix filters and preview again. If the target directory is not your cwd, wrap in a subshell: `(cd /path/to/project && packx ...)`.\n\nNever include `CLAUDE.md` in an Oracle PackX bundle. Always exclude it explicitly with `-x \"**/CLAUDE.md\"` and prefer `AGENTS.md` for repository guidance when both files exist.\n\n### Step 3: Build the bundle\n\nTarget a rich bundle close to 900k. If the bundle is under 250k for a broad planning/review task, attempt another pass with more relevant context, process docs, `lat.md` pages, tests, logs, or adjacent owners before consulting Oracle. Smaller focused bundles are still fine for narrow questions.\n\n```bash\npackx --limit 900k [filters] -x \"**/CLAUDE.md\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\nRequired flags: `--limit 900k`, `-x \"**/CLAUDE.md\"`, `-f markdown`, `--no-interactive`, `--stdout`.\n\nIf preview showed more than 200 files, add `--strip-comments --minify` so the final bundle still carries broad context.\n\n### Step 4: Validate the bundle\n\n```bash\ntest -s ~/.oracle/bundles/{slug}.txt && echo \"OK\" || echo \"EMPTY\"\n```\n\nStop if empty. Go back to Step 2.\n\n### Step 4.5: Add compact evidence when raw context is too large or unsafe\n\n`packx` remains the primary bundle. Do not skip the bundle. However, if raw session logs, hidden-path scans, screenshots, traces, or generated receipts are too large, unsafe, unavailable, or filtered out, add compact evidence.\n\nWrite `~/.oracle/bundles/{slug}-evidence.md` when useful:\n\n```markdown\n# Compact Evidence Supplement\n\n## Prior-State Ledger\n<ledger, or prior_oracle: none>\n\n## Receipts and failures\n- <exact command / receipt / failure summary>\n- <paths to screenshots, logs, traces, or receipts not included in packx>\n\n## Raw context intentionally omitted\n- <large log/session path> -- omitted because <too large / hidden path / unsafe / unavailable>\n- <summary of the relevant lines or facts>\n\n## Current narrowing\n- one_next_slice: <exact next slice>\n- out_of_scope: <what is intentionally excluded>\n- verification: <falsifiable proof>\n```\n\nPass the supplement as an extra file when it is small and safe. If the supplement itself would be too large, include the compact evidence directly in the prompt. This is allowed only as evidence compaction, not as a replacement for the primary packx bundle.\n\n### Step 5: Add screenshots or artifacts\n\nIf the user provided image, PDF, log, trace, or screenshot paths, verify they exist and pass them in `files` with the bundle. Use `browserAttachments: \"always\"` for visual files.\n\n### Step 6: Call Oracle\n\nYou must execute this MCP tool call.\n\n```\nmcp__oracle__consult({\n  prompt: \"[{slug}]\\n\\n{your detailed question here}\",\n  files: [\"~/.oracle/bundles/{slug}.txt\"],\n  engine: \"browser\",\n  model: \"gpt-5.5-pro\",\n  browserModelLabel: \"Latest\",\n  browserThinkingTime: \"extended\",\n  slug: \"{slug}\"\n})\n```\n\nForbidden call shapes:\n\n```text\nengine: \"api\"              # never valid for oracle-packx\nmodel: \"<api-model-id>\"    # never use this as a reason to switch engines\nengine omitted             # never rely on Oracle defaults\n```\n\nIf you notice one of these shapes in a drafted call, stop before tool invocation and rewrite the call with `engine: \"browser\"` plus browser fields. Do not try it once \"to see if it works.\"\n\nWith screenshots or PDFs:\n\n```\nmcp__oracle__consult({\n  prompt: \"[{slug}]\\n\\n{your detailed question here}\",\n  files: [\"~/.oracle/bundles/{slug}.txt\", \"/path/to/screenshot.png\"],\n  engine: \"browser\",\n  model: \"gpt-5.5-pro\",\n  browserModelLabel: \"Latest\",\n  browserThinkingTime: \"extended\",\n  browserAttachments: \"always\",\n  slug: \"{slug}\"\n})\n```\n\n### Step 7: Read the full response\n\nThe MCP return can be truncated. Read the authoritative answer from:\n\n```text\n~/.oracle/sessions/{slug}/output.log\n```\n\nIf the file does not exist yet, check session status and keep waiting unless there is a real terminal failure. A long browser run is expected; keep waiting while the session is still alive and logs show no terminal failure.\nDo not summarize, plan, edit, verify, or answer from your own analysis until this full Oracle output is available and read.\n\n### Step 8: Summarize for execution\n\nLead with Oracle's highest-leverage recommendations, then convert the answer into implementation-ready work packages. Preserve Oracle's reasoning, file targets, critical snippets, logging asks, verification plan, and unresolved risks.\n\nIf follow-up code changes are likely, mention the optional commit path: after implementation, the user can say `commit` and you should inspect the diff, map actual changes back to Oracle's advice, and create a traceable commit tied to `{slug}`.\n\n### Step 9: Commit phase, only when requested\n\nOnly run this step if the user explicitly asks after implementation.\n\n```bash\ngit diff --staged\ngit diff\n```\n\nPrefer `git diff --staged` as the commit boundary. Stage only relevant Oracle-driven changes. Do not sweep unrelated edits into the commit.\n\nCommit message format:\n\n```text\n<imperative subject line, <=72 chars>\n\n- <what changed> because Oracle recommended <fix/improvement>\n- <what changed> to address Oracle's finding about <risk/problem>\n\nOracle-Session: {slug}\n```\n\n## Prompt Contract\n\nEvery Oracle prompt must be self-contained, ambitious, and progress-gated.\n\nInclude:\n\n1. Slug header: `[{slug}]`.\n2. Project briefing: stack, framework, runtime, and repo rules.\n3. Goal: the broad outcome the user wants, plus the first shippable slice when the goal is broad.\n4. Prior-State Ledger: use `prior_oracle_session: none` for the first consult; for follow-ups include the last Oracle recommendation, what was implemented, verification result, failed proof or blocker, and what is being narrowed now.\n5. Forward Progress Gate result: `implemented`, `verified`, `blocked`, or `narrowed`, including Forward Progress Index arithmetic.\n6. Current evidence: attempts, logs, screenshots, failing receipts, blocker outputs, or known constraints.\n7. Bundle map: why these files were included, what may be missing, and what compact evidence was summarized because raw logs/hidden paths were too large or unavailable.\n8. Deliverable: ask for architecture, implementation plan, critical code snippets, file/function targets, tests, logs, verification strategy, and task breakdown for local agents.\n9. Next action shape: Oracle must identify the one highest-leverage next shippable slice, separate immediate implementation from later roadmap, and name exact files/functions/tests when possible.\n10. Repo-specific rules: for Script Kit GPUI, include `AGENTS.md`, owning skills, relevant `lat.md` pages, and `lat.md/verification.md` when implementation or review checks are part of the question. Never include `CLAUDE.md`; prefer `AGENTS.md` for repo instructions.\n11. Output boundary: ask Oracle to return text in the response only, with no downloadable files, attachments, exports, or generated local artifacts.\n\nInclude this constraint verbatim or equivalently in every planning/review prompt:\n\n```text\nReturn your answer as text in this response only. Do not create, attach, export,\nor offer any downloadable file. Do not create local project artifacts yourself.\nThe local agent will write any needed files, plans, notes, goals, commits, or\nverification logs using local tools.\n```\n\nAvoid prompts that ask only \"what is the next change?\" Also avoid repeated broad replanning. A follow-up prompt on the same topic must either consume new evidence or deliberately narrow to one next slice.\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| Empty bundle | Check `--preview`; ensure `-i` uses `**/` prefix; expand relevant filters |\n| `-i \"*.ts\"` matches nothing | Use `-i \"**/*.ts\"` |\n| `-i` + external path = 0 files | Wrap in `(cd TARGET && packx ...)` |\n| Token budget exceeded | Use `--strip-comments --minify`, then sharpen filters around owners, tests, docs, and logs |\n| `mcp__oracle__consult` unavailable | Use the CLI Oracle recovery path: `oracle --engine browser --model gpt-5.5-pro --browser-thinking-time extended -p \"...\" --file ~/.oracle/bundles/{slug}.txt --slug \"{slug}\"` |\n| `Missing OPENAI_API_KEY` | The call accidentally used API mode or defaulted incorrectly. Retry with `engine: \"browser\"` and let Oracle read `~/.oracle/config.json`. |\n| 120s timeout / no final answer yet | Reattach/check `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle completes or reports a terminal failure |\n| Truncated response | Read `~/.oracle/sessions/{slug}/output.log` |\n| Oracle created a downloadable file | Do not use it as the artifact; write the needed local file yourself from response text, or rerun with the no-download constraint emphasized |\n| Thinking time error | Use `browserThinkingTime: \"extended\"` |\n\n## Completion Checklist\n\n- [ ] `packx` preview ran and produced matching files.\n- [ ] `~/.oracle/bundles/{slug}.txt` exists and is non-empty.\n- [ ] If under 250k for broad planning/review, you attempted to add useful context before consulting Oracle.\n- [ ] You called `mcp__oracle__consult` with `engine: \"browser\"` so Oracle uses `~/.oracle/config.json`.\n- [ ] You read `~/.oracle/sessions/{slug}/output.log`.\n- [ ] Your summary is based on Oracle's answer, not your own analysis.\n- [ ] No planning, implementation, verification, or final answer happened while Oracle was still processing.\n- [ ] Oracle was asked to return text only and not create downloadable files or project artifacts.\n- [ ] For follow-up Oracle calls, the prompt included a Prior-State Ledger.\n- [ ] For follow-up Oracle calls, the Forward Progress Gate passed as `implemented`, `verified`, `blocked`, or `narrowed`.\n- [ ] The Forward Progress Index arithmetic was recorded.\n- [ ] If raw logs/session output/hidden paths were too large or unavailable, compact evidence was summarized in the prompt or a `~/.oracle/bundles/{slug}-evidence.md` supplement.\n- [ ] Oracle was asked for one next shippable slice, not only a broad roadmap.\n- [ ] If committing, you inspected staged and unstaged diffs and mapped the commit to Oracle's recommendations.\n\n## References\n\n- [Packx quick reference](/topics/codex-packx-command-reference/) - flags, filters, workflows, size management\n- [Packx deep technical reference](/topics/codex-packx-technical-reference/) - internals, caching, AST details\n\n## Operational boundaries\n\n- The browser-only mode, extended-thinking setting, exclusion policy, and progress score are this runbook’s operating choices. They are not universal tool limitations.\n- Numeric token targets and model labels describe a configured workflow, not a guaranteed current capacity. An accepted attachment does not prove the model consumed every token. Verify the installed tools and provider limits.\n- Repo-specific verification helpers such as `$agentic-testing`, `lat check`, and `lat.md` require that project’s tooling; use the corresponding real verification surface for another repository.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-oracle-video-runbook",
      "slug": "oracle-video-runbook",
      "title": "Oracle video analysis runbook",
      "summary": "Published Gemini-through-Oracle video-analysis skill covering video discovery and filtering, short- and long-recording workflows, media receipts, reproducible prompts, browser upload commands, readiness probes, blocking execution and recovery, artifact…",
      "category": "Tools",
      "tags": [
        "oracle",
        "gemini",
        "video"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Session-Learned Operating Contract",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Non-Negotiable Runtime Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary/Gemini readiness: UI sign-in is required, but cookie errors are not proof",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary/Attached-video smoke test",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths/Short path — quick clips, no pre-processing (DEFAULT for short screen captures)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths/Long path — workshop recordings, multi-section talks",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 1: Choose a slug",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 2: Prep the media + receipts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 3: Write the analysis prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 4: Analyze — upload the video to Gemini",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 5: Wait correctly",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 5.5: Clean up the Gemini tab",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 6 (long path): Omissions pass + reconcile + verify",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 7: Assemble + summarize",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Evidence Preservation (core rule)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Gemini Video Failure Diagnosis Tree",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Troubleshooting",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Completion Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 4038,
      "url": "/topics/codex-oracle-video-runbook/",
      "markdownUrl": "/markdown/codex-oracle-video-runbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-oracle-video-runbook.json",
      "headings": [
        {
          "id": "video-research-operating-rules",
          "text": "Video Research Operating Rules",
          "level": 2
        },
        {
          "id": "non-negotiable-runtime-mode",
          "text": "Non-Negotiable Runtime Mode",
          "level": 2
        },
        {
          "id": "model-intelligence-boundary",
          "text": "Model / Intelligence Boundary",
          "level": 2
        },
        {
          "id": "gemini-readiness-ui-sign-in-is-required-but-cookie-errors-are-not-proof",
          "text": "Gemini readiness: UI sign-in is required, but cookie errors are not proof",
          "level": 3
        },
        {
          "id": "attached-video-smoke-test",
          "text": "Attached-video smoke test",
          "level": 3
        },
        {
          "id": "two-paths",
          "text": "Two Paths",
          "level": 2
        },
        {
          "id": "short-path-quick-clips-no-pre-processing-default-for-short-screen-captures",
          "text": "Short path — quick clips, no pre-processing (DEFAULT for short screen captures)",
          "level": 3
        },
        {
          "id": "long-path-workshop-recordings-multi-section-talks",
          "text": "Long path — workshop recordings, multi-section talks",
          "level": 3
        },
        {
          "id": "pipeline",
          "text": "Pipeline",
          "level": 2
        },
        {
          "id": "step-1-choose-a-slug",
          "text": "Step 1: Choose a slug",
          "level": 3
        },
        {
          "id": "step-2-prep-the-media-receipts",
          "text": "Step 2: Prep the media + receipts",
          "level": 3
        },
        {
          "id": "step-3-write-the-analysis-prompt",
          "text": "Step 3: Write the analysis prompt",
          "level": 3
        },
        {
          "id": "step-4-analyze-upload-the-video-to-gemini",
          "text": "Step 4: Analyze — upload the video to Gemini",
          "level": 3
        },
        {
          "id": "step-5-wait-correctly",
          "text": "Step 5: Wait correctly",
          "level": 3
        },
        {
          "id": "step-5-5-clean-up-the-gemini-tab",
          "text": "Step 5.5: Clean up the Gemini tab",
          "level": 3
        },
        {
          "id": "step-6-long-path-omissions-pass-reconcile-verify",
          "text": "Step 6 (long path): Omissions pass + reconcile + verify",
          "level": 3
        },
        {
          "id": "step-7-assemble-summarize",
          "text": "Step 7: Assemble + summarize",
          "level": 3
        },
        {
          "id": "evidence-preservation-core-rule",
          "text": "Evidence Preservation (core rule)",
          "level": 2
        },
        {
          "id": "gemini-video-failure-diagnosis-tree",
          "text": "Gemini Video Failure Diagnosis Tree",
          "level": 2
        },
        {
          "id": "troubleshooting",
          "text": "Troubleshooting",
          "level": 2
        },
        {
          "id": "completion-checklist",
          "text": "Completion Checklist",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Oracle video analysis runbook\n\nYou are a PIPELINE EXECUTOR. Your job is: prep media -> upload the video to Gemini via\n`mcp__oracle__consult` (browser engine) -> read the analysis -> verify it against\nevidence -> write local artifacts. Oracle/Gemini supplies the expensive multimodal\nanalysis; you own every local file, receipt, and verification.\n\nThis skill is the sibling of `oracle-packx`. Where `oracle-packx` bundles *code* and\nsends *text* to ChatGPT, `oracle-video` attaches a *video file* and sends it to\n*Gemini* (which can actually watch the footage). The full, validated process spec\nlives in [references/repeatable-video-followup-process.md](/topics/codex-video-evidence-process/);\nread it before a long run.\n\n## Video Research Operating Rules\n\nThis skill exists because video understanding must happen in Gemini. Do not route\nvideo analysis through Codex, ChatGPT, OpenAI API mode, or text-only summarization.\nThe local agent may search YouTube, download media, compress files, write prompts,\nbundle analyses, and produce final Markdown; the video-watching step is always Gemini\nthrough Oracle's browser engine.\n\nWhen the user asks for \"same pipeline\" or a repeatable YouTube research batch, apply these repeatable research rules:\n\n- Filter candidate videos by actual YouTube metadata (`upload_date`), not title text,\n  search ranking, or remembered publication dates.\n- If the user gives a cutoff such as \"after a chosen cutoff\", enforce\n  `upload_date >= CUTOFF_YYYYMMDD`. Reject older/stale videos even if they rank highly.\n- Exclude topic collisions explicitly. For example, \"Raycast\" should exclude\n  game-development raycasting; \"Codex\" should exclude unrelated OCR/library/tool names.\n- Exclude coupon, affiliate-code, auto-generated music/topic uploads, shorts-only junk,\n  and videos whose content is not actually about the requested product/workflow.\n- Download with current `yt-dlp`, Chrome cookies, and YouTube challenge support when\n  needed. A known-good command shape is `yt-dlp --cookies-from-browser chrome ...`.\n- Preserve source metadata in `queue.json` with `id`, `title`, `uploader`,\n  `upload_date`, `duration`, and `url`.\n- Space Gemini video starts by about five minutes for larger batches only after the\n  first attached-video probe passes and no unresolved run is pending, unless the user\n  explicitly asks for a different cadence.\n- Make prompts topic-specific. Never reuse Codex-specific prompt language for another\n  topic; parameterize the topic in batch runners and prompts.\n- After every Gemini run, save the analysis beside the chunk and verify the sentinel\n  before moving to consolidation.\n- After each successful Gemini run, close the Gemini tab that Oracle opened. Do not\n  leave the remote Mac mini with dozens of `gemini.google.com/app` tabs.\n\n## Non-Negotiable Runtime Mode\n\nVideo analysis MUST run through the browser engine using `~/.oracle/config.json`.\n\n- Every `mcp__oracle__consult` call MUST set `engine: \"browser\"`.\n- **Default model: `model: \"gemini-3-pro\"`** — Oracle drives Gemini's mode picker to\n  **3.5 Flash + Extended thinking**, the right balance of speed and reasoning for routine\n  video analysis. Any Gemini model with an attachment uses the DOM upload path (not\n  pasted text), so the video is attached either way.\n- **Heavy opt-in: `model: \"gemini-3-pro-deep-think\"`** — selects **3.1 Pro + Deep Think**\n  (\"Max parallel reasoning\"). Use this only when the user explicitly asks for the deepest\n  analysis; it is markedly slower. Do NOT use it as the default.\n- Deliver the video with `browserAttachments: \"always\"`. The file path in `files` must\n  be an absolute path on the invoking machine that Oracle can stream or hand to the\n  browser host. For direct remote-host execution, use a path valid on that host; for\n  remote Oracle service runs, preserve the client-side absolute path in receipts and\n  let Oracle stream the attachment to the remote service.\n- Never use `engine: \"api\"` for video. The API path cannot upload the browser video.\n  If a call reports `Missing OPENAI_API_KEY`, you accidentally used API mode — rebuild\n  in browser mode.\n- Do not pass ad hoc remote host/token/profile overrides. Let Oracle read\n  `~/.oracle/config.json`, which owns the remote browser endpoint (the host that has\n  Chrome + Google sign-in). CLI Oracle recovery path: `oracle --engine browser --model gemini-3-pro ...`\n  (add `--model gemini-3-pro-deep-think` only for the heavy Deep Think opt-in).\n- If the user mentions a remote Mac mini/TV/Gemini config, still do not hard-code a\n  host/token in prompts or calls. Use `~/.oracle/config.json`; it is the source of truth\n  for the remote browser and cookie-bearing Google session.\n- If an ownership/access dialog appears in Gemini (\"confirm that you own/can access\n  this content\"), treat it as a browser/UI blocker. Let the user click it if automation\n  cannot, then retry only the affected upload. Do not restart the whole batch.\n\n## Model / Intelligence Boundary\n\nThis skill analyzes video through Gemini in Oracle browser mode. Do not manage\nChatGPT's Intelligence pill here.\n\nCritical rules:\n\n- Do not set `browserThinkingTime: \"instant\"` for Gemini video analysis.\n- Do not use ChatGPT `Pro Extended` / `Instant` labels as Gemini readiness proof.\n- Use `model: \"gemini-3-pro\"` by default, or `model:\n  \"gemini-3-pro-deep-think\"` only for explicit heavy opt-in.\n- The Instant vs Pro Extended policy applies to ChatGPT only: Instant for\n  ChatGPT Create image / `imagine`; Pro Extended for ChatGPT non-image consults.\n\n### Gemini readiness: UI sign-in is required, but cookie errors are not proof\n\nGemini video upload requires the browser profile that Oracle drives to have a live\nsigned-in Gemini UI. However, a Gemini text-only probe is not authoritative for video\nreadiness. Text-only Gemini may use Oracle's HTTP/cookie path and fail because a\nGoogle cookie such as `__Secure-1PSIDTS` is missing, while the visible Gemini UI is\nsigned in and the attached-video DOM upload path still works.\n\nUse this readiness order:\n\n1. Confirm the run is routed to Gemini browser mode, not ChatGPT or API mode.\n2. Confirm the remote Gemini UI is visibly signed in.\n3. Run one tiny attached-video probe with `engine: \"browser\"`, `model:\n   \"gemini-3-pro\"`, `browserAttachments: \"always\"`, and an explicit sentinel.\n4. Treat the attached-video probe, not a text-only probe, as the video readiness proof.\n5. If the probe hits a UI blocker, classify it with the failure diagnosis tree below\n   before retrying or starting a batch.\n\nGemini may show a conditional **video upload consent** modal after a video is attached\nand send is attempted. The DOM may include `video-upload-consent-dialog` with text like\n\"A reminder about creating videos\" and actions `Cancel` / `Agree`. This is not a\nGoogle sign-out, quota limit, or upload failure. Automation may click only the visible\naction whose normalized label is exactly `Agree`. Never click `Cancel`, never click the\nfirst dialog button generically, and never treat this modal as permission to click\narbitrary dialog actions.\n\n### Attached-video smoke test\n\nBefore a large batch, prove the actual video path with a tiny local MP4/MOV probe.\n\nRequired proof:\n\n- request uses `engine: \"browser\"`;\n- request uses `model: \"gemini-3-pro\"` unless the user explicitly requested Deep Think;\n- request uses `browserAttachments: \"always\"`;\n- stored request/session metadata shows Gemini provider routing;\n- run log shows Gemini navigation and attachment upload completion;\n- final response contains the expected sentinel;\n- completed Gemini tab is closed after output is saved.\n\nA text-only Gemini success is not enough. A text-only Gemini failure is also not enough\nto declare the video path broken. The video path is proven only by an attached-video run\nor by inspected Gemini tab evidence showing the submitted video prompt and sentinel\nresponse.\n\n## Two Paths\n\nPick the path from the source length and structure (full decision rules in the\nreference doc).\n\n### Short path — quick clips, no pre-processing (DEFAULT for short screen captures)\n\nUse when the clip is short enough to upload and analyze in one pass (quick screen\nrecording, a couple-minute walkthrough, a bug repro, a design review clip).\n\n1. Copy/symlink the clip as the single chunk; keep the original immutable + record a\n   `sha256` receipt.\n2. Run ONE Gemini consult with the clip attached (see Step: Analyze).\n3. Verify the output (URLs/tools/claims supported by what's actually in the video).\n4. Write a compact deliverable: bug report, requirements note, design brief, or summary.\n\nDo NOT segment, chunk, or build a manifest for short clips. Skip straight to analysis.\n\n### Long path — workshop recordings, multi-section talks\n\nUse for long recordings (roughly 45+ min, real breaks, many sections). Segment with\nffmpeg, drop verified dead-space (never discard chat — carry it forward), analyze each\nchunk, run an omissions pass, extract keyframes, reconcile against evidence, then\nassemble a teammate/follow-up packet. Follow the reference doc step by step.\n\n## Pipeline\n\n### Step 1: Choose a slug\n\n3-5 hyphenated words (Oracle rejects anything outside that range), e.g.\n`workshop-chunk-02-analysis` or `bug-repro-video-followup`. Every prompt starts with\n`[{slug}]` on its own first line, then a blank line, then the prompt.\n\n### Step 2: Prep the media + receipts\n\n```bash\nRUN_DIR=runs/$(date +%Y-%m-%d)-{slug}        # one folder per video/video-set\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,chunks}\ncp \"/abs/path/to/source.mp4\" \"$RUN_DIR/inputs/source.mp4\"\nshasum -a 256 \"$RUN_DIR/inputs/source.mp4\" > \"$RUN_DIR/inputs/source.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source.mp4\" > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor the long path, segment/chunk per the reference doc and write `chunks/video-manifest.json`.\nFor the short path, the single clip is `chunks/01/chunk.mp4`.\n\n### Step 3: Write the analysis prompt\n\nSave the prompt to `chunks/NN/gemini-prompt.md` so the run is reproducible. Use the\n\"Gemini Chunk Analysis\" template from the reference doc. Always include the hard rules:\npreserve original timestamps, separate transcript/chat/visual/inference evidence, do\nnot invent tools/commands/URLs/files/speakers/labels, return both Markdown and fenced\nJSON, end with an `END_OF_VIDEO_ANALYSIS ...` sentinel. Write the exact expected\nsentinel beside the prompt, for example `chunks/NN/expected-sentinel.txt`, and verify\nagainst that file rather than guessing whether the run used slug-only or\n`run_key chunk_id` form.\n\n### Step 4: Analyze — upload the video to Gemini\n\nYou MUST execute this MCP tool call (one per chunk):\n\n```\nmcp__oracle__consult({\n  prompt: \"[{slug}]\\n\\n{contents of chunks/NN/gemini-prompt.md}\",\n  files: [\"/abs/path/RUN_DIR/chunks/NN/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",          // default → Gemini 3.5 Flash + Extended thinking\n  browserAttachments: \"always\",\n  slug: \"{slug}\"\n})\n```\n\nFor the heavy Deep Think opt-in (only when explicitly requested), swap in\n`model: \"gemini-3-pro-deep-think\"` (→ 3.1 Pro + Deep Think).\n\nForbidden shapes: `engine: \"api\"`, omitted `engine`, no `browserAttachments`. If you\ndraft one of these, rebuild before invoking.\n\nFor batch CLI Oracle recovery, use the same browser mode explicitly:\n\n```bash\noracle \\\n  --engine browser \\\n  --model gemini-3-pro \\\n  --browser-attachments always \\\n  --browser-keep-browser \\\n  --prompt \"$(cat chunks/NN/gemini-prompt.md)\" \\\n  --file \"/abs/path/RUN_DIR/chunks/NN/chunk.mp4\" \\\n  --slug \"{topic}-batch-NN\" \\\n  --write-output \"chunks/NN/gemini-analysis.md\" \\\n  --verbose \\\n  --wait \\\n  --force\n```\n\nUse `--browser-keep-browser` only so the run can be inspected and recovered while it is\nactive. Once the run has saved output, close the Gemini tab (see Step 5.5).\n\nPersist the result yourself (the MCP return + output.log are truncated — the caller\nowns persistence):\n\n```text\nchunks/NN/gemini-run.log        # browser automation metadata / timing\nchunks/NN/gemini-result.json    # full response payload\nchunks/NN/gemini-analysis.md    # rendered analysis\n```\n\n### Step 5: Wait correctly\n\nGemini video runs are blocking. After a run starts, all local analysis, artifact writing\nbased on Gemini's answer, follow-up planning, and independent summarization MUST pause\nuntil Oracle/Gemini has fully completed and the local response has been read.\n\n- Never assume Oracle/Gemini timed out or failed based on elapsed time alone.\n- Never proceed independently while Oracle/Gemini is still processing, even if a wrapper\n  returns after 120s or any other local wait limit.\n- Reattach with `mcp__oracle__sessions({ id: \"{slug}\", detail: true })` or read\n  `~/.oracle/sessions/{slug}/output.log`; these checks are only for recovering the final\n  response, not for starting work while the run continues.\n- Keep waiting as long as Oracle/Gemini requires while the session is still processing.\n  There is no Codex-side timeout threshold that permits independent action.\n- Only call it failed on an explicit terminal error, a sign-in/quota/upload guard, or a\n  non-zero exit.\n\nHealthy wrapper completion looks like the run log ending with `Gemini browser response\nreceived (N chars)` and `Completed in Nms`. Recovered completion is also valid when the\nwrapper reports a send/ready error but tab inspection shows a submitted user turn and\nGemini response containing the exact expected sentinel. In that case, save the visible\nresponse, record the recovery in `gemini-run.log`, and do not rerun that chunk.\n\nFor newer Gemini DOM runs, successful submission may also be evident from the remote\nGemini tab even when an older Oracle wrapper reports a send/ready error. If a run says\n`Gemini send was not accepted` or `Gemini composer was not ready to send` after an\nattached-video attempt, inspect the Gemini tab before retrying: the submitted user turn\nand Gemini response may already exist. A valid sentinel in the visible Gemini response\nbeats the wrapper error; persist the response and fix/adjust the wrapper before\nbatching more chunks.\n\n### Step 5.5: Clean up the Gemini tab\n\nEvery successful Gemini video run should close the tab it opened on the remote browser.\nThis prevents the remote Mac mini/TV browser from accumulating dozens of Gemini tabs.\nCleanup happens only after extraction, not merely after the browser appears done.\n\nPreferred cleanup order:\n\n1. Record the Oracle session slug and, if available, its Chrome debug port/target in the\n   run log.\n2. Extract and persist every needed artifact from the Gemini response:\n   `gemini-result.json`, `gemini-analysis.md`, any machine JSON or\n   `gemini-analysis.extracted.json`, and the recovery note if the response came from\n   tab inspection rather than wrapper success.\n3. Verify `gemini-analysis.md` is non-empty and contains the exact\n   `expected-sentinel.txt` value.\n4. Close only the Gemini tab for that completed/extracted run.\n5. Leave the browser itself running if Oracle needs to reuse the signed-in profile.\n6. Do not close tabs for still-running uploads, still-generating responses, unresolved\n   wrapper errors, or tabs whose visible response has not yet been extracted.\n\nIf you write a batch script, make tab cleanup an explicit post-extraction step. The\nscript should not close the tab immediately after Oracle returns; it should first save\nthe full result, extract machine-readable content, verify the sentinel, then close the\nexact tab target for that run. If extraction fails, leave the tab open and record the\ntarget/port so the run can be recovered.\n\nWhen the run used `--browser-keep-browser`, use Oracle/browser tooling to close matching\ncompleted Gemini tabs rather than leaving them open. If you are in the Oracle repo, a\nworking inspection/cleanup shape is:\n\n```bash\npnpm tsx scripts/browser-tools.ts eval --port <port> '\n(() => {\n  const tabs = [...document.querySelectorAll(\"a\")];\n  return { href: location.href, title: document.title, text: document.body.innerText.slice(0, 500) };\n})()\n'\n```\n\nIf you need to operate on the configured remote Mac mini, run the same command through\nSSH using the repo-local Node path from that machine. Prefer closing the exact tab\ntarget via Chrome DevTools Protocol when possible; avoid killing Chrome or closing all\nGemini tabs blindly. If exact-target close is not available, list tabs first, identify\ncompleted `gemini.google.com/app` tabs by title/conversation state, and close only those.\n\n### Step 6 (long path): Omissions pass + reconcile + verify\n\nRe-attach the same chunk with the \"Omissions Pass\" prompt, then reconcile locally into\n`final-reconciled.md`/`.json`, and run the verification reports (coverage, hallucination,\ntimestamp, visual-claim). Keep every receipt next to the claim it supports. Details in\nthe reference doc.\n\n### Step 7: Assemble + summarize\n\nLong path: produce the `final/` packet (teammate guide, chapter index, resources, QA\nindex, exercises, keyframe manifest, instructor checklist). Short path: produce the one\ncompact deliverable. Summarize for the user, leading with the highest-value findings,\nand link the artifact paths.\n\n## Evidence Preservation (core rule)\n\n- Keep original media immutable; record a `sha256` receipt.\n- Preserve ORIGINAL recording timestamps when a source timeline exists.\n- Save every prompt, result, and run log next to the chunk.\n- Never claim a URL/tool/command/visual unless it is supported by transcript, chat,\n  carry-forward chat, a local path, or keyframe review.\n- Never discard chat from a removed/dead span — carry it forward.\n\n## Gemini Video Failure Diagnosis Tree\n\nStop new batch starts before using this tree. Diagnose the current run first.\n\n1. **Was a video attached?**\n   - No: this may be the text-only HTTP/cookie path. Do not use it as the only video\n     readiness result. Run a tiny attached-video probe.\n   - Yes: continue.\n2. **Was the run routed to Gemini browser mode?**\n   - If logs or metadata show ChatGPT navigation/upload, API mode, or missing\n     `browserConfig.provider: \"gemini\"`, stop. This is a routing bug. Do not treat the\n     result as valid video analysis.\n   - If Gemini browser routing is confirmed, continue.\n3. **Is there an explicit terminal guard?**\n   - `sign-in`: stop and have the remote browser signed into Gemini.\n   - `quota` or `rate-limit`: stop and wait/change account per user direction.\n   - `upload-warning`: stop and fix file size/type/count or chunk the media.\n   - No terminal guard: continue.\n4. **Did a text-only probe fail on missing Google cookies?**\n   - If the visible Gemini UI is signed in, do not diagnose sign-out from that alone.\n     Text-only probes can fail on HTTP/cookie requirements that attached-video DOM runs\n     do not need.\n   - Run or inspect an attached-video probe.\n5. **Did attached-video send fail with `Gemini send was not accepted`?**\n   - Inspect the Gemini tab before retrying.\n   - If `video-upload-consent-dialog` is visible, click only exact `Agree`, then wait\n     for the same prompt to submit.\n   - If the prompt and attachment still remain in the composer and no submitted user\n     turn exists, rerun only that chunk after fixing the blocker.\n   - If a submitted user turn or response exists, do not rerun until checking for the\n     sentinel.\n6. **Did the wrapper report `prompt-empty`?**\n   - Inspect the tab. `prompt-empty` can mean Gemini accepted the prompt and moved it\n     out of the composer.\n   - If the visible response contains the expected sentinel, persist it as success.\n   - If no submitted user turn and no response exist, treat it as a real send failure\n     and rerun only that chunk.\n7. **Are there stale Gemini tabs?**\n   - Do not close active uploads or generating responses.\n   - Generic empty Gemini tabs from failed diagnostics may be closed after inspection.\n   - Tabs with real conversation state must be checked for a saved response/sentinel\n     before closing.\n   - Close only the exact completed tab after output is saved.\n8. **Is the result valid?**\n   - Valid completion is either a successful wrapper log with response received, or\n     inspected Gemini tab evidence containing the expected sentinel and saved output.\n   - Anything else is unresolved; do not consolidate, summarize, or batch further.\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| Run log stops at `Sending prompt...`, no response; tab left with video attached | Stop batch starts. Inspect the Gemini tab before rerunning. Check for a visible video consent modal, explicit sign-in/quota/rate-limit/upload warning, submitted user turn, or sentinel response. Rerun only the affected chunk after the state is classified. |\n| `Gemini send was not accepted after 3 attempts` | Inspect the remote Gemini tab. If `video-upload-consent-dialog` is visible, click only the visible action whose normalized label is exactly `Agree`, then wait for the same prompt to submit. If the prompt remains in the composer with no submitted user turn, rerun only that chunk after fixing the blocker. If a response with the expected sentinel already exists, persist it as success. |\n| `Gemini composer was not ready to send` with `reason=prompt-empty` after an attached-video run | Inspect the tab before retrying. `prompt-empty` may be a wrapper false negative after Gemini accepted the prompt. If the prompt appears in a submitted user turn/page and the Gemini response contains the expected sentinel, save it as completed analysis and record recovery. If no user turn/response exists, rerun only that chunk after fixing send/modal handling. |\n| Text-only Gemini probe reports sign-in/cookie failure, but the visible Gemini app is signed in | Do not assume the video path is broken. Text-only probes can use Oracle's HTTP/cookie path and fail on missing `__Secure-1PSIDTS`; video attachments use the Gemini DOM upload path. Verify with a tiny real video attachment probe before deciding whether user sign-in is required. |\n| Text-only Gemini probe fails on missing `__Secure-1PSIDTS` | Do not diagnose video sign-out from this alone. Confirm visible Gemini UI state and run a tiny attached-video probe. |\n| Attached-video probe succeeds after text-only failure | Treat video DOM upload path as ready. Record both receipts so future agents do not revert to the false sign-out diagnosis. |\n| Wrapper failed but tab contains sentinel | Persist the visible Gemini response, save a recovery note in the run log, close the completed tab, and do not rerun that chunk. |\n| Log shows ChatGPT navigation or ChatGPT upload for a video | Stop. Treat this as a routing bug, not a valid analysis. Verify the stored request/metadata shows `browserConfig.provider: \"gemini\"` and rerun only after the provider guard tests pass. |\n| Many leftover `gemini.google.com/app` tabs with generic \"Google Gemini\" title | Those are usually runs that never produced a query/response (often diagnostic/sign-in attempts), or completed runs that were left open because `--browser-keep-browser` was used. Close completed/empty Gemini tabs after saving output. Tabs with a real auto-generated title + conversation id may have completed; verify output before closing. |\n| `Missing OPENAI_API_KEY` | The call used API mode. Retry with `engine: \"browser\"` + `model: \"gemini-3-pro\"` (default) or `gemini-3-pro-deep-think` (heavy). |\n| `sign-in` / `quota` / `rate-limit` / `upload-warning` guard | Stop. Sign the remote browser into Google (or wait out the limit), then resume. |\n| `video-upload-consent-dialog` / \"A reminder about creating videos\" appears | This is a video consent blocker, not sign-out. Click only exact `Agree`; never click `Cancel`, never click the first button generically, and never click `Confirm` for this dialog unless the DOM label is actually `Agree`. Continue the same run after acceptance. |\n| Ownership/access confirmation appears | Treat as a separate UI blocker. If automation cannot safely identify the explicit ownership/access confirmation action, ask the user to click it once, then continue or retry only the affected upload. Do not restart the whole batch. |\n| 120s timeout / no final answer yet | Reattach via `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle/Gemini completes or reports a terminal failure. |\n| Large video upload | Oracle streams large attachments to the remote service before the run (`[remote] streaming large attachment before run`). Keep the file under the configured `maxFileSizeBytes` / remote limit, or chunk it. |\n| Truncated MCP return | Read `chunks/NN/gemini-result.json` that you persisted, not the MCP tail. |\n\n## Completion Checklist\n\n- [ ] Original media preserved + `sha256` receipt written.\n- [ ] Slug is 3-5 hyphenated words; prompt starts with `[{slug}]`.\n- [ ] Each Gemini call used `engine: \"browser\"`, `model: \"gemini-3-pro\"` (default 3.5 Flash + Extended; `gemini-3-pro-deep-think` only if explicitly requested), `browserAttachments: \"always\"`, absolute `files` path.\n- [ ] Remote browser confirmed signed into Gemini before batch runs.\n- [ ] A real attached-video probe has completed through Gemini before a large batch; do not rely only on a text-only Gemini probe.\n- [ ] Text-only Gemini probe results were not used as the sole video readiness proof.\n- [ ] First real attached-video probe result was saved before any batch fan-out.\n- [ ] Any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit, or upload-warning state stopped new batch starts until classified.\n- [ ] Prompt, result JSON, and run log persisted per chunk.\n- [ ] Each run either reached `Gemini browser response received`, or a wrapper-error recovery was documented with submitted user turn + visible Gemini response + expected sentinel.\n- [ ] If `video-upload-consent-dialog` appeared, only the `Agree` action was clicked and the same submitted prompt was allowed to complete.\n- [ ] Stored session metadata/request shows `browserConfig.provider: \"gemini\"` for every video run.\n- [ ] Expected sentinel was written next to the prompt and checked exactly.\n- [ ] If the sentinel format used `run_key chunk_id`, verification did not look for slug-only form.\n- [ ] Run log contains `[gemini-web] Navigating to gemini.google.com...` and `Attachment upload complete in Gemini: <filename>`.\n- [ ] Run log does not show ChatGPT navigation/upload for the video attachment.\n- [ ] No local analysis, artifact synthesis, or final answer happened while Oracle/Gemini was still processing.\n- [ ] Completed Gemini tabs were closed after output was saved and verified; the remote\n      browser was not left with accumulated `gemini.google.com/app` tabs.\n- [ ] Scripted tab cleanup ran only after full extraction completed:\n      `gemini-result.json`, `gemini-analysis.md`, extracted JSON if expected, and exact\n      sentinel verification.\n- [ ] Outputs verified: no invented URLs/tools/commands; visual claims confirmed; original timestamps preserved.\n- [ ] Long path: omissions pass + reconciliation + verification reports done; `final/` packet assembled.\n- [ ] Short path: single compact deliverable written.\n- [ ] User summary leads with highest-value findings and links artifact paths.\n\n## References\n\n- [Repeatable video follow-up process](/topics/codex-video-evidence-process/) — full step-by-step spec, ffmpeg segmentation, prompt templates, verification, and final-packet layout.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-packx-quick-reference",
      "slug": "packx-quick-reference",
      "title": "Packx command and filtering reference",
      "summary": "Full context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.",
      "category": "Tools",
      "tags": [
        "packx",
        "context",
        "reference"
      ],
      "sources": [
        {
          "label": "Published Packx reference",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-quick-reference.md"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/skills/oracle/references/packx-quick-reference.md"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1604,
      "url": "/topics/factory-packx-quick-reference/",
      "markdownUrl": "/markdown/factory-packx-quick-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-packx-quick-reference.json",
      "headings": [
        {
          "id": "packx-quick-reference",
          "text": "Packx Quick Reference",
          "level": 2
        },
        {
          "id": "how-file-discovery-works",
          "text": "How File Discovery Works",
          "level": 2
        },
        {
          "id": "auto-excluded-always-skipped",
          "text": "Auto-Excluded (always skipped)",
          "level": 2
        },
        {
          "id": "default-file-types-when-no-i-flag",
          "text": "Default File Types (when no `-i` flag)",
          "level": 2
        },
        {
          "id": "critical-i-glob-requires-prefix",
          "text": "Critical: `-i` Glob Requires `**/` Prefix",
          "level": 2
        },
        {
          "id": "critical-i-fails-with-external-directories",
          "text": "Critical: `-i` Fails with External Directories",
          "level": 2
        },
        {
          "id": "token-budget-k-vs-k",
          "text": "Token Budget: k vs K",
          "level": 2
        },
        {
          "id": "positional-arguments",
          "text": "Positional Arguments",
          "level": 2
        },
        {
          "id": "complete-flag-reference",
          "text": "Complete Flag Reference",
          "level": 2
        },
        {
          "id": "search-filter",
          "text": "Search & Filter",
          "level": 3
        },
        {
          "id": "processing",
          "text": "Processing",
          "level": 3
        },
        {
          "id": "output",
          "text": "Output",
          "level": 3
        },
        {
          "id": "filter-decision-tree",
          "text": "Filter Decision Tree",
          "level": 2
        },
        {
          "id": "bundle-size-management",
          "text": "Bundle Size Management",
          "level": 2
        },
        {
          "id": "common-workflows",
          "text": "Common Workflows",
          "level": 2
        },
        {
          "id": "review-code-by-keyword",
          "text": "Review code by keyword",
          "level": 3
        },
        {
          "id": "analyze-from-entrypoint-best-signal-to-noise",
          "text": "Analyze from entrypoint (best signal-to-noise)",
          "level": 3
        },
        {
          "id": "debug-from-error",
          "text": "Debug from error",
          "level": 3
        },
        {
          "id": "context-line-focused-review-token-efficient",
          "text": "Context-line focused review (token-efficient)",
          "level": 3
        },
        {
          "id": "architecture-overview-with-skeleton-mode",
          "text": "Architecture overview with skeleton mode",
          "level": 3
        },
        {
          "id": "pr-diff-review",
          "text": "PR/diff review",
          "level": 3
        },
        {
          "id": "large-monorepo",
          "text": "Large Monorepo",
          "level": 3
        },
        {
          "id": "fallback-manual-bundle-augmentation",
          "text": "Fallback — Manual Bundle Augmentation",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        }
      ],
      "markdown": "# Packx command and filtering reference\n\nFull context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.\n\n## Packx Quick Reference\n\nPackx (v4.x) is a native AI context bundler. It discovers files, filters by content/type/git-status, strips noise, counts tokens, and outputs in LLM-friendly formats. **Since v4.7.0, bare `packx` with no output flags enters interactive mode** — always use `--no-interactive` for scripting pipelines.\n\n## How File Discovery Works\n\n1. **Candidate discovery** — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback)\n2. **Ignore filtering** — applies `.gitignore` (traversed upward from cwd) + `.packignore` + 22 built-in ignore patterns\n3. **Include/exclude pattern matching** — `-i` and `-x` filters via minimatch\n4. **Content filtering** — `-s` search strings and `-S` exclusion strings (up to 50 files in parallel)\n5. **Size/binary filtering** — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary)\n6. **Token counting** — `js-tiktoken` (OpenAI tokenizer), fallback: `text.length / 4`\n\n## Auto-Excluded (always skipped)\n```\nnode_modules/  .git/  dist/  build/  .next/  coverage/  .cache/  tmp/  temp/\n*.log  .DS_Store  Thumbs.db  package-lock.json  yarn.lock  pnpm-lock.yaml\nbun.lockb  bun.lock  Gemfile.lock  Cargo.lock  poetry.lock  Pipfile.lock  composer.lock\n```\n\n## Default File Types (when no `-i` flag)\n**Code:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php\n**Web:** vue, svelte, astro, css, scss, less\n**Config:** json, yaml, yml, toml, xml\n**Docs:** md, mdx, txt\n**Scripts:** sh, bash, zsh, fish\n**Data:** sql, graphql, gql\n\n## Critical: `-i` Glob Requires `**/` Prefix\n\n```bash\n# CORRECT — always use **/ prefix for extension globs\npackx --limit 900k -i \"**/*.ts\" --preview\npackx --limit 900k -i \"src/**/*.tsx\" --preview\n\n# WRONG — bare *.ext matches NOTHING\npackx --limit 900k -i \"*.ts\" --preview    # Empty result!\n```\n\nDirectory-style includes (`-i \"src/\"`) work without `**/`. The `-x` exclude flag is more lenient — `\"*.test.*\"` works for excludes.\n\n## Critical: `-i` Fails with External Directories\n\n**The `-i` glob is matched against paths relative to cwd.** When you pass a positional path outside cwd (e.g., `~/dev/other-project`), relative paths start with `../` which `**` cannot traverse — **silently producing 0 results**.\n\n```bash\n# BROKEN — -i + external path = 0 files every time\npackx --limit 900k -i \"**/*.ts\" --no-interactive --preview ~/dev/other-project\n\n# FIX 1 (Best): cd into the target via subshell\n(cd ~/dev/other-project && packx --limit 900k -i \"**/*.ts\" --no-interactive --preview)\n\n# FIX 2: Positional path alone (all default file types), then exclude unwanted\npackx --limit 900k -x \"*.json\" -x \"*.md\" -x \"*.sh\" --no-interactive --preview ~/dev/other-project\n\n# FIX 3: Use -s (content search) — works fine with external paths\npackx --limit 900k -s \"import\" --no-interactive --preview ~/dev/other-project\n```\n\n**Rule**: If the target directory ≠ cwd, wrap in `(cd TARGET && packx ...)`.\n\n## Token Budget: k vs K\n\nOracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context.\n\n| Notation | Multiplier | Example | Result |\n|----------|-----------|---------|--------|\n| lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens |\n| UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens |\n| No suffix | Raw number | `50000` | 50,000 tokens |\n\n## Positional Arguments\n\n```bash\npackx src/                  # Directory → scan root\npackx README.md src/auth.ts # Files → explicit includes\npackx \"**/*.test.ts\"        # Glob → include pattern\n```\n\nPositional args are classified automatically: directories become scan roots, existing files are explicit includes, patterns with glob characters (`*`, `?`, `[]`, `{}`) become glob filters. When combined with `-i`, explicit files must match BOTH conditions.\n\n## Complete Flag Reference\n\n### Search & Filter\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strings <text>` | `-s` | Include files containing text | Repeatable; case-insensitive by default |\n| `--exclude-strings` | `-S` | Exclude files containing text | Opposite of -s |\n| `--include <glob>` | `-i` | Include by glob | **Must use `**/` prefix for extensions** |\n| `--exclude <glob>` | `-x` | Exclude by filename/glob | More lenient than -i |\n| `--regex` | `-R` | Treat -s patterns as regex | Full regex syntax |\n| `--case-sensitive` | `-C` | Case-sensitive search | Default is case-insensitive |\n| `--staged` | | Git staged files only | `git diff --cached --name-only --diff-filter=ACMR` |\n| `--diff` | | Files changed from main | Uses `git merge-base` to find divergence point |\n| `--dirty` | | Modified + untracked files | Union of modified and `git ls-files --others` |\n| `--no-packignore` | | Ignore .packignore file | |\n\n`--staged`, `--diff`, and `--dirty` are **mutually exclusive**.\n\n### Processing\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strip-comments` | | Remove comments | AST-aware via tree-sitter; regex fallback by language family |\n| `--no-comments` | | Alias for --strip-comments | |\n| `--minify` | | Remove empty lines + trim whitespace | Stacks remaining lines together |\n| `--lines <N>` | `-l` | Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge |\n| `--follow-imports` | | Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions |\n| `--related` | `-r` | Include related files | Matches by core filename in same dir (tests, stories, styles) |\n| `--skeleton` | | Interface-only extraction | AST-based: strips function bodies to `{ /* ... */ }` |\n| `--instruction <file>` | | Prepend custom instructions from file | Inserted at top of bundle |\n| `--prompt <text>` | `-p` | Append text to end of output | |\n\n### Output\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--copy` | `-c` | Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting |\n| `--stdout` | | Write to stdout | Summaries go to stderr; **disables interactive mode** |\n| `--output <file>` | `-o` | Write to file | |\n| `--format <fmt>` | `-f` | `xml` (default), `markdown`, `plain`, `jsonl` | Use `markdown` for Oracle/ChatGPT |\n| `--preview` | | Show matching files (up to 50) without packing | Dry run for testing filters |\n| `--max-tokens <N>` | `-M` | Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file |\n| `--limit <size>` | | Token budget | `900k`=900,000; `32K`=32,768; visual progress in interactive mode |\n| `--no-interactive` | | Disable interactive mode | **Required for scripting/piping** |\n\n## Filter Decision Tree\n\n```\nIs the task about a specific feature/module?\n├─ YES → Do you know the entrypoint file?\n│        ├─ YES → --follow-imports <entrypoint>\n│        └─ NO  → -s \"keyword\" -i \"relevant/path/**/*.ts\"\n└─ NO  → Is it a code review / PR?\n         ├─ YES → --diff (or --staged / --dirty)\n         └─ NO  → Is it architecture/overview?\n                  ├─ YES → --skeleton -i \"src/**/*.ts\"\n                  └─ NO  → Is it debugging?\n                           ├─ YES → -s \"error message\" -r -l 20\n                           └─ NO  → -i \"**/*.ts\" (broad scan)\n\nAlways add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown\nToken-tight? Add: --strip-comments --minify\nStill too big? Add: -x \"**/*.test.*\" -x \"**/stories/**\" then -s \"keyword\" then -l N\n```\n\n## Bundle Size Management\n\n- ALWAYS run `packx --preview [filters]` FIRST to estimate size\n- If preview shows >900k: add `--strip-comments --minify` only if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test\n- If still >900k: narrow `-i` patterns or add `-x` exclusions\n- If still >900k: add `-s` keyword to filter to only relevant files\n- If context around matches is sufficient: use `-l 20` instead of full files\n\nProgression example:\n\n```bash\n# 1) Preview baseline\npackx --preview -i \"src/**/*.ts\" -i \"apps/web/**/*.tsx\"\n\n# 2) If too many files, strip/minify\npackx --limit 900k -i \"src/**/*.ts\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 3) If still >900k, narrow includes/excludes\npackx --limit 900k -i \"src/auth/**/*.ts\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 4) If still >900k, add keyword focus\npackx --limit 900k -i \"src/auth/**/*.ts\" -s \"token session oauth\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 5) If still >900k, use context lines instead of full files\npackx --limit 900k -s \"token session oauth\" -l 15 -x \"**/*.test.*\" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 6) For architecture overview, use skeleton mode\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n## Common Workflows\n\n### Review code by keyword\n```bash\npackx --limit 900k -s \"auth\" -i \"**/*.ts\" -x \"*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Analyze from entrypoint (best signal-to-noise)\n```bash\npackx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Debug from error\n```bash\npackx --limit 900k -s \"TypeError: Cannot read properties\" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Context-line focused review (token-efficient)\n```bash\npackx --limit 900k -s \"catch\" -s \"throw\" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Architecture overview with skeleton mode\n```bash\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -x \"**/*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### PR/diff review\n```bash\npackx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Large Monorepo\n```bash\npackx --limit 900k -i \"apps/web/src/**/*.tsx\" -i \"apps/api/src/**/*.ts\" -i \"packages/auth/src/**/*.ts\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n## Fallback — Manual Bundle Augmentation\n\nWhen `packx` cannot reach every needed file in one pass:\n\n```bash\npackx --limit 900k -i \"src/**/*.ts\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\ncat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt\nwc -c ~/.oracle/bundles/{slug}.txt\n```\n\n## References\n\n- [Packx deep technical reference](https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md) — full internals, caching, import resolution, AST details"
    },
    {
      "id": "codex-packx-command-reference",
      "slug": "packx-command-reference",
      "title": "PackX commands, filters, and bundle recipes",
      "summary": "Packx context-bundling reference covering discovery and filtering, default exclusions and file types, glob and external-directory pitfalls, token notation, positional arguments, complete flag tables, filter selection, size-management progression,…",
      "category": "Tools",
      "tags": [
        "packx",
        "cli",
        "context"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/How File Discovery Works",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Auto-Excluded (always skipped)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Default File Types (when no `-i` flag)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Critical: `-i` Glob Requires `**/` Prefix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Critical: `-i` Fails with External Directories",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Token Budget: k vs K",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Positional Arguments",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Complete Flag Reference",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Complete Flag Reference/Search & Filter",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Complete Flag Reference/Processing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Complete Flag Reference/Output",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Filter Decision Tree",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Bundle Size Management",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Review code by keyword",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Analyze from entrypoint (best signal-to-noise)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Debug from error",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Context-line focused review (token-efficient)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Architecture overview with skeleton mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/PR/diff review",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Common Workflows/Large Monorepo",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/Fallback — Manual Bundle Augmentation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-quick-reference.md#Packx Quick Reference/References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 1629,
      "url": "/topics/codex-packx-command-reference/",
      "markdownUrl": "/markdown/codex-packx-command-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-packx-command-reference.json",
      "headings": [
        {
          "id": "how-file-discovery-works",
          "text": "How File Discovery Works",
          "level": 2
        },
        {
          "id": "auto-excluded-always-skipped",
          "text": "Auto-Excluded (always skipped)",
          "level": 2
        },
        {
          "id": "default-file-types-when-no-i-flag",
          "text": "Default File Types (when no `-i` flag)",
          "level": 2
        },
        {
          "id": "critical-i-glob-requires-prefix",
          "text": "Critical: `-i` Glob Requires `**/` Prefix",
          "level": 2
        },
        {
          "id": "critical-i-fails-with-external-directories",
          "text": "Critical: `-i` Fails with External Directories",
          "level": 2
        },
        {
          "id": "token-budget-k-vs-k",
          "text": "Token Budget: k vs K",
          "level": 2
        },
        {
          "id": "positional-arguments",
          "text": "Positional Arguments",
          "level": 2
        },
        {
          "id": "complete-flag-reference",
          "text": "Complete Flag Reference",
          "level": 2
        },
        {
          "id": "search-filter",
          "text": "Search & Filter",
          "level": 3
        },
        {
          "id": "processing",
          "text": "Processing",
          "level": 3
        },
        {
          "id": "output",
          "text": "Output",
          "level": 3
        },
        {
          "id": "filter-decision-tree",
          "text": "Filter Decision Tree",
          "level": 2
        },
        {
          "id": "bundle-size-management",
          "text": "Bundle Size Management",
          "level": 2
        },
        {
          "id": "common-workflows",
          "text": "Common Workflows",
          "level": 2
        },
        {
          "id": "review-code-by-keyword",
          "text": "Review code by keyword",
          "level": 3
        },
        {
          "id": "analyze-from-entrypoint-best-signal-to-noise",
          "text": "Analyze from entrypoint (best signal-to-noise)",
          "level": 3
        },
        {
          "id": "debug-from-error",
          "text": "Debug from error",
          "level": 3
        },
        {
          "id": "context-line-focused-review-token-efficient",
          "text": "Context-line focused review (token-efficient)",
          "level": 3
        },
        {
          "id": "architecture-overview-with-skeleton-mode",
          "text": "Architecture overview with skeleton mode",
          "level": 3
        },
        {
          "id": "pr-diff-review",
          "text": "PR/diff review",
          "level": 3
        },
        {
          "id": "large-monorepo",
          "text": "Large Monorepo",
          "level": 3
        },
        {
          "id": "fallback-manual-bundle-augmentation",
          "text": "Fallback — Manual Bundle Augmentation",
          "level": 2
        },
        {
          "id": "references",
          "text": "References",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# PackX commands, filters, and bundle recipes\n\nPackx (v4.x) is a native AI context bundler. It discovers files, filters by content/type/git-status, strips noise, counts tokens, and outputs in LLM-friendly formats. **Since v4.7.0, bare `packx` with no output flags enters interactive mode** — always use `--no-interactive` for scripting pipelines.\n\n## How File Discovery Works\n\n1. **Candidate discovery** — scans directories using glob patterns (ripgrep fast-path when available, Node.js glob fallback)\n2. **Ignore filtering** — applies `.gitignore` (traversed upward from cwd) + `.packignore` + 22 built-in ignore patterns\n3. **Include/exclude pattern matching** — `-i` and `-x` filters via minimatch\n4. **Content filtering** — `-s` search strings and `-S` exclusion strings (up to 50 files in parallel)\n5. **Size/binary filtering** — skips files >10MB silently; detects binary via first 512 bytes (>10% non-printable = binary)\n6. **Token counting** — `js-tiktoken` (OpenAI tokenizer), fallback: `text.length / 4`\n\n## Auto-Excluded (always skipped)\n```\nnode_modules/  .git/  dist/  build/  .next/  coverage/  .cache/  tmp/  temp/\n*.log  .DS_Store  Thumbs.db  package-lock.json  yarn.lock  pnpm-lock.yaml\nbun.lockb  bun.lock  Gemfile.lock  Cargo.lock  poetry.lock  Pipfile.lock  composer.lock\n```\n\n## Default File Types (when no `-i` flag)\n**Code:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php\n**Web:** vue, svelte, astro, css, scss, less\n**Config:** json, yaml, yml, toml, xml\n**Docs:** md, mdx, txt\n**Scripts:** sh, bash, zsh, fish\n**Data:** sql, graphql, gql\n\n## Critical: `-i` Glob Requires `**/` Prefix\n\n```bash\n# CORRECT — always use **/ prefix for extension globs\npackx --limit 900k -i \"**/*.ts\" --preview\npackx --limit 900k -i \"src/**/*.tsx\" --preview\n\n# WRONG — bare *.ext matches NOTHING\npackx --limit 900k -i \"*.ts\" --preview    # Empty result!\n```\n\nDirectory-style includes (`-i \"src/\"`) work without `**/`. The `-x` exclude flag is more lenient — `\"*.test.*\"` works for excludes.\n\n## Critical: `-i` Fails with External Directories\n\n**The `-i` glob is matched against paths relative to cwd.** When you pass a positional path outside cwd (e.g., `~/dev/other-project`), relative paths start with `../` which `**` cannot traverse — **silently producing 0 results**.\n\n```bash\n# BROKEN — -i + external path = 0 files every time\npackx --limit 900k -i \"**/*.ts\" --no-interactive --preview ~/dev/other-project\n\n# FIX 1 (Best): cd into the target via subshell\n(cd ~/dev/other-project && packx --limit 900k -i \"**/*.ts\" --no-interactive --preview)\n\n# FIX 2: Positional path alone (all default file types), then exclude unwanted\npackx --limit 900k -x \"*.json\" -x \"*.md\" -x \"*.sh\" --no-interactive --preview ~/dev/other-project\n\n# FIX 3: Use -s (content search) — works fine with external paths\npackx --limit 900k -s \"import\" --no-interactive --preview ~/dev/other-project\n```\n\n**Rule**: If the target directory ≠ cwd, wrap in `(cd TARGET && packx ...)`.\n\n## Token Budget: k vs K\n\nOracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context.\n\n| Notation | Multiplier | Example | Result |\n|----------|-----------|---------|--------|\n| lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens |\n| UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens |\n| No suffix | Raw number | `50000` | 50,000 tokens |\n\n## Positional Arguments\n\n```bash\npackx src/                  # Directory → scan root\npackx README.md src/auth.ts # Files → explicit includes\npackx \"**/*.test.ts\"        # Glob → include pattern\n```\n\nPositional args are classified automatically: directories become scan roots, existing files are explicit includes, patterns with glob characters (`*`, `?`, `[]`, `{}`) become glob filters. When combined with `-i`, explicit files must match BOTH conditions.\n\n## Complete Flag Reference\n\n### Search & Filter\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strings <text>` | `-s` | Include files containing text | Repeatable; case-insensitive by default |\n| `--exclude-strings` | `-S` | Exclude files containing text | Opposite of -s |\n| `--include <glob>` | `-i` | Include by glob | **Must use `**/` prefix for extensions** |\n| `--exclude <glob>` | `-x` | Exclude by filename/glob | More lenient than -i |\n| `--regex` | `-R` | Treat -s patterns as regex | Full regex syntax |\n| `--case-sensitive` | `-C` | Case-sensitive search | Default is case-insensitive |\n| `--staged` | | Git staged files only | `git diff --cached --name-only --diff-filter=ACMR` |\n| `--diff` | | Files changed from main | Uses `git merge-base` to find divergence point |\n| `--dirty` | | Modified + untracked files | Union of modified and `git ls-files --others` |\n| `--no-packignore` | | Ignore .packignore file | |\n\n`--staged`, `--diff`, and `--dirty` are **mutually exclusive**.\n\n### Processing\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--strip-comments` | | Remove comments | AST-aware via tree-sitter; regex fallback by language family |\n| `--no-comments` | | Alias for --strip-comments | |\n| `--minify` | | Remove empty lines + trim whitespace | Stacks remaining lines together |\n| `--lines <N>` | `-l` | Extract N context lines around matches | Smart expansion to complete code blocks; overlapping windows auto-merge |\n| `--follow-imports` | | Include imported dependencies | ES6/CJS/dynamic; relative only; max depth 10; tries .ts/.tsx/.js/.jsx extensions |\n| `--related` | `-r` | Include related files | Matches by core filename in same dir (tests, stories, styles) |\n| `--skeleton` | | Interface-only extraction | AST-based: strips function bodies to `{ /* ... */ }` |\n| `--instruction <file>` | | Prepend custom instructions from file | Inserted at top of bundle |\n| `--prompt <text>` | `-p` | Append text to end of output | |\n\n### Output\n| Flag | Short | Purpose | Notes |\n|------|-------|---------|-------|\n| `--copy` | `-c` | Copy to clipboard | pbcopy/clip/xclip; only chunk 1 if splitting |\n| `--stdout` | | Write to stdout | Summaries go to stderr; **disables interactive mode** |\n| `--output <file>` | `-o` | Write to file | |\n| `--format <fmt>` | `-f` | `xml` (default), `markdown`, `plain`, `jsonl` | Use `markdown` for Oracle/ChatGPT |\n| `--preview` | | Show matching files (up to 50) without packing | Dry run for testing filters |\n| `--max-tokens <N>` | `-M` | Split into chunks | Creates file-1.xml, file-2.xml; files never split mid-file |\n| `--limit <size>` | | Token budget | `900k`=900,000; `32K`=32,768; visual progress in interactive mode |\n| `--no-interactive` | | Disable interactive mode | **Required for scripting/piping** |\n\n## Filter Decision Tree\n\n```\nIs the task about a specific feature/module?\n├─ YES → Do you know the entrypoint file?\n│        ├─ YES → --follow-imports <entrypoint>\n│        └─ NO  → -s \"keyword\" -i \"relevant/path/**/*.ts\"\n└─ NO  → Is it a code review / PR?\n         ├─ YES → --diff (or --staged / --dirty)\n         └─ NO  → Is it architecture/overview?\n                  ├─ YES → --skeleton -i \"src/**/*.ts\"\n                  └─ NO  → Is it debugging?\n                           ├─ YES → -s \"error message\" -r -l 20\n                           └─ NO  → -i \"**/*.ts\" (broad scan)\n\nAlways add: --limit 900k --preview (check first) → --no-interactive --stdout -f markdown\nToken-tight? Add: --strip-comments --minify\nStill too big? Add: -x \"**/*.test.*\" -x \"**/stories/**\" then -s \"keyword\" then -l N\n```\n\n## Bundle Size Management\n\n- ALWAYS run `packx --preview [filters]` FIRST to estimate size\n- If preview shows >900k: add `--strip-comments --minify` only if you need to fit under the target; otherwise keep rich context when the user explicitly wants a limit stress test\n- If still >900k: narrow `-i` patterns or add `-x` exclusions\n- If still >900k: add `-s` keyword to filter to only relevant files\n- If context around matches is sufficient: use `-l 20` instead of full files\n\nProgression example:\n\n```bash\n# 1) Preview baseline\npackx --preview -i \"src/**/*.ts\" -i \"apps/web/**/*.tsx\"\n\n# 2) If too many files, strip/minify\npackx --limit 900k -i \"src/**/*.ts\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 3) If still >900k, narrow includes/excludes\npackx --limit 900k -i \"src/auth/**/*.ts\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 4) If still >900k, add keyword focus\npackx --limit 900k -i \"src/auth/**/*.ts\" -s \"token session oauth\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 5) If still >900k, use context lines instead of full files\npackx --limit 900k -s \"token session oauth\" -l 15 -x \"**/*.test.*\" --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n\n# 6) For architecture overview, use skeleton mode\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n## Common Workflows\n\n### Review code by keyword\n```bash\npackx --limit 900k -s \"auth\" -i \"**/*.ts\" -x \"*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Analyze from entrypoint (best signal-to-noise)\n```bash\npackx --limit 900k --follow-imports src/server.ts -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Debug from error\n```bash\npackx --limit 900k -s \"TypeError: Cannot read properties\" -r -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Context-line focused review (token-efficient)\n```bash\npackx --limit 900k -s \"catch\" -s \"throw\" -l 15 --strip-comments -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Architecture overview with skeleton mode\n```bash\npackx --limit 900k -i \"src/**/*.ts\" --skeleton -x \"**/*.test.*\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### PR/diff review\n```bash\npackx --limit 900k --diff -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n### Large Monorepo\n```bash\npackx --limit 900k -i \"apps/web/src/**/*.tsx\" -i \"apps/api/src/**/*.ts\" -i \"packages/auth/src/**/*.ts\" -x \"**/*.test.*\" --strip-comments --minify -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\n```\n\n## Fallback — Manual Bundle Augmentation\n\nWhen `packx` cannot reach every needed file in one pass:\n\n```bash\npackx --limit 900k -i \"src/**/*.ts\" -f markdown --no-interactive --stdout > ~/.oracle/bundles/{slug}.txt\ncat docs/auth-decision-record.md >> ~/.oracle/bundles/{slug}.txt\nwc -c ~/.oracle/bundles/{slug}.txt\n```\n\n## References\n\n- [Packx deep technical reference](/topics/codex-packx-technical-reference/) — full internals, caching, import resolution, AST details\n\n## Operational boundaries\n\n- PackX flags, glob semantics, tokenizer behavior, and downstream token targets are version-sensitive. Preview and inspect the final bundle; auto-exclusions and secret detectors do not replace privacy review.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-packx-deep-reference",
      "slug": "packx-deep-reference",
      "title": "Packx discovery, processing, and output semantics",
      "summary": "Full context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.",
      "category": "Tools",
      "tags": [
        "packx",
        "context",
        "reference"
      ],
      "sources": [
        {
          "label": "Published Packx reference",
          "url": "https://shiny-rosette-m6zy.here.now/skills/oracle/references/packx-deep-reference.md"
        }
      ],
      "sourceUnits": [
        "08-oracle-video/skills/oracle/references/packx-deep-reference.md"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1833,
      "url": "/topics/factory-packx-deep-reference/",
      "markdownUrl": "/markdown/factory-packx-deep-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-packx-deep-reference.json",
      "headings": [
        {
          "id": "packx-deep-reference",
          "text": "Packx Deep Reference",
          "level": 2
        },
        {
          "id": "file-discovery-pipeline",
          "text": "File Discovery Pipeline",
          "level": 2
        },
        {
          "id": "processing-order",
          "text": "Processing Order",
          "level": 3
        },
        {
          "id": "auto-excluded-directories-files-default-ignore-patterns",
          "text": "Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)",
          "level": 3
        },
        {
          "id": "default-extensions-no-i-flag",
          "text": "Default Extensions (no `-i` flag)",
          "level": 3
        },
        {
          "id": "the-i-include-glob-critical-behavior",
          "text": "The `-i` Include Glob: Critical Behavior",
          "level": 2
        },
        {
          "id": "token-budget-limit",
          "text": "Token Budget (`--limit`)",
          "level": 2
        },
        {
          "id": "k-vs-k-notation",
          "text": "k vs K Notation",
          "level": 3
        },
        {
          "id": "token-counting",
          "text": "Token Counting",
          "level": 3
        },
        {
          "id": "interactive-mode-limit",
          "text": "Interactive Mode + Limit",
          "level": 3
        },
        {
          "id": "import-following-follow-imports",
          "text": "Import Following (`--follow-imports`)",
          "level": 2
        },
        {
          "id": "supported-import-styles",
          "text": "Supported Import Styles",
          "level": 3
        },
        {
          "id": "resolution",
          "text": "Resolution",
          "level": 3
        },
        {
          "id": "parse-strategy",
          "text": "Parse Strategy",
          "level": 3
        },
        {
          "id": "related-files-r-related",
          "text": "Related Files (`-r` / `--related`)",
          "level": 2
        },
        {
          "id": "comment-stripping-strip-comments",
          "text": "Comment Stripping (`--strip-comments`)",
          "level": 2
        },
        {
          "id": "ast-based-primary-tree-sitter",
          "text": "AST-Based (primary — tree-sitter)",
          "level": 3
        },
        {
          "id": "regex-fallback-by-language-family",
          "text": "Regex Fallback (by language family)",
          "level": 3
        },
        {
          "id": "context-lines-l-lines",
          "text": "Context Lines (`-l` / `--lines`)",
          "level": 2
        },
        {
          "id": "smart-context-mode",
          "text": "Smart Context Mode",
          "level": 3
        },
        {
          "id": "overlap-merging",
          "text": "Overlap Merging",
          "level": 3
        },
        {
          "id": "indent-based-block-detection-fallback",
          "text": "Indent-Based Block Detection (fallback)",
          "level": 3
        },
        {
          "id": "git-integration",
          "text": "Git Integration",
          "level": 2
        },
        {
          "id": "staged",
          "text": "`--staged`",
          "level": 3
        },
        {
          "id": "dirty",
          "text": "`--dirty`",
          "level": 3
        },
        {
          "id": "diff",
          "text": "`--diff`",
          "level": 3
        },
        {
          "id": "output-formats",
          "text": "Output Formats",
          "level": 2
        },
        {
          "id": "xml-default",
          "text": "XML (default)",
          "level": 3
        },
        {
          "id": "markdown-f-markdown",
          "text": "Markdown (`-f markdown`)",
          "level": 3
        },
        {
          "id": "jsonl-f-jsonl",
          "text": "JSONL (`-f jsonl`)",
          "level": 3
        },
        {
          "id": "plain-f-plain",
          "text": "Plain (`-f plain`)",
          "level": 3
        },
        {
          "id": "caching-packx-cache",
          "text": "Caching (`.packx_cache/`)",
          "level": 2
        },
        {
          "id": "bundles-b-bundle",
          "text": "Bundles (`-b` / `--bundle`)",
          "level": 2
        },
        {
          "id": "interactive-mode-i",
          "text": "Interactive Mode (`-I`)",
          "level": 2
        },
        {
          "id": "features",
          "text": "Features",
          "level": 3
        },
        {
          "id": "key-bindings",
          "text": "Key Bindings",
          "level": 3
        },
        {
          "id": "after-selection",
          "text": "After Selection",
          "level": 3
        },
        {
          "id": "watch-mode-w",
          "text": "Watch Mode (`-w`)",
          "level": 2
        },
        {
          "id": "instruction-and-prompt",
          "text": "`--instruction` and `--prompt`",
          "level": 2
        },
        {
          "id": "preview-mode",
          "text": "`--preview` Mode",
          "level": 2
        },
        {
          "id": "explain-mode",
          "text": "`--explain` Mode",
          "level": 2
        },
        {
          "id": "skeleton-mode-v4-15-0",
          "text": "`--skeleton` Mode (v4.15.0+)",
          "level": 2
        },
        {
          "id": "secret-redaction-v4-15-0",
          "text": "Secret Redaction (v4.15.0+)",
          "level": 2
        },
        {
          "id": "minify-behavior",
          "text": "`--minify` Behavior",
          "level": 2
        },
        {
          "id": "token-splitting-max-tokens-m",
          "text": "Token Splitting (`--max-tokens` / `-M`)",
          "level": 2
        },
        {
          "id": "concurrency",
          "text": "Concurrency",
          "level": 2
        },
        {
          "id": "packignore",
          "text": ".packignore",
          "level": 2
        },
        {
          "id": "positional-path-arguments",
          "text": "Positional Path Arguments",
          "level": 2
        },
        {
          "id": "gotchas-edge-cases",
          "text": "Gotchas & Edge Cases",
          "level": 2
        }
      ],
      "markdown": "# Packx discovery, processing, and output semantics\n\nFull context-bundling reference: discovery rules, glob traps, token budgets, output formats, filters, and operational caveats.\n\n## Packx Deep Reference\n\nComplete technical reference for packx v4.x — the AI context bundler.\n\n## File Discovery Pipeline\n\n### Processing Order\n1. **Candidate discovery** — by extension + glob patterns + git mode\n2. **Ignore filtering** — `.gitignore` (traversed upward) + `.packignore` + default ignores\n3. **Content filtering** — search strings (`-s`) and exclusion strings (`-S`)\n4. **Size filtering** — skip files > 10MB silently\n5. **Binary detection** — first 512 bytes checked for null bytes; >10% non-printable = binary → skip\n6. **Pattern matching** — minimatch for `-i`/`-x` patterns\n7. **Token counting** — js-tiktoken (GPT tokenizer), fallback: `text.length / 4`\n\n### Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)\n```\n**/node_modules/**     **/.git/**          **/dist/**\n**/build/**            **/.next/**         **/coverage/**\n**/.cache/**           **/tmp/**           **/temp/**\n**/*.log               **/.DS_Store        **/Thumbs.db\n**/package-lock.json   **/yarn.lock        **/pnpm-lock.yaml\n**/bun.lockb           **/bun.lock         **/Gemfile.lock\n**/Cargo.lock          **/poetry.lock      **/Pipfile.lock\n**/composer.lock\n```\n\n### Default Extensions (no `-i` flag)\n**Languages:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php\n**Web Frameworks:** vue, svelte, astro\n**Styles:** css, scss, less\n**Config:** json, yaml, yml, toml, xml\n**Documentation:** md, mdx, txt\n**Scripts:** sh, bash, zsh, fish\n**Data:** sql, graphql, gql\n\n## The `-i` Include Glob: Critical Behavior\n\n**The `-i` flag requires `**/` prefix for extension matching:**\n\n```bash\n# CORRECT — always use **/ prefix for extensions\npackx --limit 900k -i \"**/*.ts\" --preview\npackx --limit 900k -i \"src/**/*.tsx\" --preview\n\n# WRONG — bare *.ext does NOT match\npackx --limit 900k -i \"*.ts\" --preview    # Matches nothing!\n```\n\nDirectory-style includes (`-i \"src/\"`) work without `**/`.\nThe `-x` exclude flag is more lenient — `\"*.test.*\"` works for excludes.\n\n## Token Budget (`--limit`)\n\nOracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context.\n\n### k vs K Notation\n| Notation | Multiplier | Example | Exact Result |\n|----------|-----------|---------|--------------|\n| lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens |\n| UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens |\n| No suffix | Raw number | `50000` | 50,000 tokens |\n| Decimal | Works with both | `1.5k` | 1,500 tokens |\n\n### Token Counting\n- Uses `js-tiktoken` (OpenAI's tokenizer) for accurate GPT token counts\n- Fallback: `Math.round(text.length / 4)` if tiktoken fails\n- Counts are cached per-file in `.packx_cache/cache.json`\n\n### Interactive Mode + Limit\nWhen `--limit` is used with interactive mode (`-I`), a visual progress bar shows real-time token consumption as files are selected/deselected.\n\n## Import Following (`--follow-imports`)\n\n### Supported Import Styles\n1. ES6: `import ... from \"...\"` and `export ... from \"...\"`\n2. CommonJS: `require(\"...\")`\n3. Dynamic: `import(\"...\")`\n\n### Resolution\n- **Only follows relative imports** (`./` or `../`), never `node_modules`\n- Max depth: 10 levels\n- Circular dependencies handled via visited-path Set\n\n**Resolution extensions tried (in order):**\n`\"\"`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.mjs`, `.cts`, `.cjs`, `.json`\n\n**Extension mappings:**\n- `.js` → tries `.ts`, `.tsx`, `.js`, `.jsx`\n- `.mjs` → tries `.mts`, `.mjs`\n- `.cjs` → tries `.cts`, `.cjs`\n- `.jsx` → tries `.tsx`, `.jsx`\n\n**Index files for directory imports:**\n`index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mts`, `index.mjs`\n\n### Parse Strategy\n1. Tree-sitter AST parsing first (for .ts, .js, etc.)\n2. Regex fallback if AST unavailable:\n```\nimport\\s+(?:[\\w\\s{},*]+\\s+from\\s+)?[\"']([^\"']+)[\"']\nexport\\s+(?:[\\w\\s{},*]+\\s+from\\s+)?[\"']([^\"']+)[\"']\nrequire\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)\nimport\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)\n```\n\n## Related Files (`-r` / `--related`)\n\nExtracts base name (before first dot after name), then finds all files in the same directory with the same core name:\n- `Button.tsx` → finds `Button.test.tsx`, `Button.stories.tsx`, `Button.module.css`, etc.\n- Recursively expands matched files with their related files\n\n## Comment Stripping (`--strip-comments`)\n\n### AST-Based (primary — tree-sitter)\n- Language-specific tree-sitter grammar\n- Collects all comment nodes from AST\n- Removes entire lines if only whitespace surrounds the comment\n- Otherwise removes inline comments preserving code\n\n### Regex Fallback (by language family)\n| Language Family | Languages | Patterns |\n|----------------|-----------|----------|\n| C-style | js, jsx, ts, tsx, java, c, cpp, go, rust, swift, php, css, scss, less | `/* ... */` and `// ...` |\n| Hash-style | py, rb, sh, bash, zsh, yaml, yml, toml | `# ...` |\n| HTML-style | html, xml, md, mdx, vue, svelte, astro | `<!-- ... -->` |\n| Lua-style | lua, sql | `-- ...` |\n\nAll regex fallbacks preserve quoted strings.\n\n## Context Lines (`-l` / `--lines`)\n\n### Smart Context Mode\n1. Extracts N lines around each match\n2. **Tries to expand to complete code blocks** using tree-sitter AST\n3. Falls back to indent-based block detection\n4. Max expansion: `contextLines × 2`\n\n### Overlap Merging\nWindows sorted by start line, then merged if `window.startLine <= current.endLine + 1`. Matches from overlapping regions are combined.\n\n### Indent-Based Block Detection (fallback)\n- Scans upward for lower indentation level (block openers: `{`, `:`, function/class/if keywords)\n- Scans downward for closing braces or lower indentation\n\n## Git Integration\n\n### `--staged`\n```\ngit diff --cached --name-only --diff-filter=ACMR\n```\n(Added, Copied, Modified, Renamed)\n\n### `--dirty`\n```\ngit diff --name-only --diff-filter=ACMR       # modified\ngit ls-files --others --exclude-standard       # untracked\n```\nReturns deduplicated union.\n\n### `--diff`\n```\ngit merge-base <branch> HEAD                    # find common ancestor\ngit diff --name-only --diff-filter=ACMR <base>  # diff from there\n```\nFalls back to branch name directly if merge-base fails.\n\n**These three flags are mutually exclusive.**\n\n## Output Formats\n\n### XML (default)\n```xml\n<file_summary>\n  <purpose>...</purpose>\n</file_summary>\n<directory_structure>file paths</directory_structure>\n<files>\n  <file path=\"src/auth.ts\" matches=\"3\" windows=\"2\">\n    ...content or context windows...\n  </file>\n</files>\n```\n\n### Markdown (`-f markdown`)\n```markdown\n# Packx Output\nThis file contains X filtered files...\n## Files\n### src/auth.ts (3 matches)\n```ts\n...content...\n```​\n```\n\n### JSONL (`-f jsonl`)\nOne JSON object per line:\n```json\n{\"path\":\"src/auth.ts\",\"content\":\"...\",\"tokens\":150,\"matches\":[{\"line\":10,\"column\":5,\"match\":\"...\"}]}\n```\n\n### Plain (`-f plain`)\nLike markdown but simpler header, no fenced blocks.\n\n## Caching (`.packx_cache/`)\n\n**Cache file:** `.packx_cache/cache.json` (version 2)\n\n**Entry structure:**\n```json\n{\n  \"mtime\": 1702000000000,\n  \"size\": 4096,\n  \"contentHash\": \"sha256hex...\",\n  \"isBinary\": false,\n  \"tokens\": 342\n}\n```\n\n**Validation strategy:**\n1. mtime AND size match → cache hit (fast path)\n2. Size differs → cache miss\n3. mtime differs but size same → compute SHA-256 → compare hash\n4. Hash matches → update mtime, keep entry\n5. Hash differs → cache miss, recompute\n\n**Bypass:** `--no-cache`\n**Prune:** Stale entries for deleted files cleaned on next run\n\n## Bundles (`-b` / `--bundle`)\n\n- Stored in `.pack/bundles/` directory\n- Extensions: `.bundle`, `.pack`, `.txt`\n- Format: gitignore-style patterns (one per line, `#` for comments)\n- In interactive mode: loads bundles as pre-selected file sets\n- With `-b name`: loads non-interactively and outputs directly\n\n## Interactive Mode (`-I`)\n\n**Default since v4.7.0** — running `packx` with no output flags enters interactive mode.\n\n### Features\n- Tree-based file browser with token counts\n- Live preview pane with syntax highlighting\n- Token budget progress bar (`--limit`)\n- Git status decorators: `[M]` Modified, `[A]` Added, `[?]` Untracked\n- `.packignore` files shown but start unselected\n- Fuzzy search filtering\n- Visual dependency graph\n\n### Key Bindings\n| Key | Action |\n|-----|--------|\n| `j/k` or ↑/↓ | Navigate |\n| `Space` | Toggle selection |\n| `Shift+Space` / `v` | Range selection (anchor) |\n| `Tab` | Toggle preview focus |\n| `PgUp/PgDn` | Scroll preview |\n| `g/G` | Jump to top/bottom |\n| `h/l` | Collapse/expand folder |\n| `o` | Open in editor |\n| `d` | Resolve dependencies |\n| `c` | Toggle comment stripping |\n| `+/-` | Adjust context lines |\n| `x` | Banish to `.packignore` |\n| `?` | Full-screen help overlay |\n| `Enter` | Confirm selection |\n\n### After Selection\n- Option to save glob pattern to `.packignore`\n- Option to save selection as named bundle\n- Choose output: clipboard, file, stdout, or skip\n\n## Watch Mode (`-w`)\n\n- Uses `chokidar` with 150ms debounce\n- File stabilization: 100ms threshold, 50ms poll interval\n- Watches: `change`, `add`, `unlink` events\n- **Requires** `--output` or `--copy`\n- **Cannot combine with `-I`** (interactive)\n- Ctrl+C for graceful shutdown\n\n## `--instruction` and `--prompt`\n\n| Flag | Position | Input |\n|------|----------|-------|\n| `--instruction <file>` | Prepends to TOP of output | File path |\n| `--prompt <text>` / `-p` | Appends to END of output | Inline text |\n\n## `--preview` Mode\n\n- Dry run: shows matching files without packing content\n- Displays up to 50 files (rest counted as \"... and X more\")\n- Shows file count total\n- Useful for testing filter combinations before committing\n\n## `--explain` Mode\n\n- Full dry run with detailed logging\n- Shows: resolved config options, file discovery process, pattern matching, what would be included\n- No output generated\n\n## `--skeleton` Mode (v4.15.0+)\n\n- AST-based: strips function bodies to `{ /* ... */ }`\n- Keeps interfaces, type definitions, function signatures\n- Great for architecture review at minimal token cost\n\n## Secret Redaction (v4.15.0+)\n\nAutomatically detects and redacts 22 pattern types:\nAWS keys, GitHub tokens, JWTs, database connection strings, API keys, private keys, etc.\nReplaces matches with `<REDACTED:TYPE>`.\n\n## `--minify` Behavior\n\n```javascript\ncontent.split('\\n')\n  .map(line => line.trim())\n  .filter(line => line.length > 0)\n  .join('\\n')\n```\nRemoves empty lines, trims whitespace per line.\n\n## Token Splitting (`--max-tokens` / `-M`)\n\n- Reserves ~50 tokens per chunk for headers/footers\n- **Files are never split mid-file**\n- A single file exceeding the budget is skipped entirely (marked \"oversized\")\n- Creates: `output-1.xml`, `output-2.xml`, etc.\n- Only chunk 1 copied to clipboard; rest go to files\n\n## Concurrency\n\n- Files analyzed in parallel using `p-limit`\n- `CONCURRENCY_LIMIT = 50`\n- Progress emitted every 50 files or 10% of total\n\n## .packignore\n\n- Gitignore syntax (processed by `ignore` npm library)\n- Auto-loaded from project root\n- `--no-packignore` to disable\n- In interactive mode: matching files shown but unselected\n- `x` hotkey in interactive mode banishes files to `.packignore`\n\n## Positional Path Arguments\n\n```bash\npackx src/          # Directory → scan root\npackx README.md     # File → explicit include\npackx \"**/*.test.ts\" # Glob pattern → include pattern\n```\n\n**Classification:**\n- Contains `*`, `?`, `[`, `]`, `{`, `}`, `!` → treated as glob pattern\n- Exists as directory → treated as scan root\n- Exists as file → treated as explicit file include\n\n**Interaction with filters:**\n- Explicit files + `-i` patterns: must match BOTH\n- Positional roots: used as starting directories for scanning\n- Positional globs: added to include patterns\n\n## Gotchas & Edge Cases\n\n| Issue | Detail |\n|-------|--------|\n| `-i \"*.ts\"` matches nothing | Must use `\"**/*.ts\"` with `**/` prefix for extensions |\n| Interactive is default | Since v4.7.0, bare `packx` enters interactive mode. Use `--no-interactive` for scripting |\n| `--stdout` disables interactive | Can't combine `--stdout` with `-I` |\n| `--watch` + `-I` incompatible | Watch requires output target, can't be interactive |\n| Files >10MB silently skipped | No warning — use `--explain` to debug missing files |\n| Single file > `--max-tokens` | Entire file skipped, not split |\n| Clipboard: only chunk 1 | When splitting, remaining chunks go to files |\n| Binary files silently skipped | >10% non-printable chars in first 512 bytes |"
    },
    {
      "id": "codex-packx-technical-reference",
      "slug": "packx-technical-reference",
      "title": "PackX discovery, processing, and token mechanics",
      "summary": "Packx technical reference covering discovery and filtering, glob behavior, token budgets and counting, import and related-file expansion, comment stripping, context windows, Git modes, output formats, caching, bundles, interactive controls, watch mode,…",
      "category": "Tools",
      "tags": [
        "packx",
        "internals",
        "tokens"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/File Discovery Pipeline",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/File Discovery Pipeline/Processing Order",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/File Discovery Pipeline/Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/File Discovery Pipeline/Default Extensions (no `-i` flag)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/The `-i` Include Glob: Critical Behavior",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Token Budget (`--limit`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Token Budget (`--limit`)/k vs K Notation",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Token Budget (`--limit`)/Token Counting",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Token Budget (`--limit`)/Interactive Mode + Limit",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Import Following (`--follow-imports`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Import Following (`--follow-imports`)/Supported Import Styles",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Import Following (`--follow-imports`)/Resolution",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Import Following (`--follow-imports`)/Parse Strategy",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Related Files (`-r` / `--related`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Comment Stripping (`--strip-comments`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Comment Stripping (`--strip-comments`)/AST-Based (primary — tree-sitter)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Comment Stripping (`--strip-comments`)/Regex Fallback (by language family)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Context Lines (`-l` / `--lines`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Context Lines (`-l` / `--lines`)/Smart Context Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Context Lines (`-l` / `--lines`)/Overlap Merging",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Context Lines (`-l` / `--lines`)/Indent-Based Block Detection (fallback)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Git Integration",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Git Integration/`--staged`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Git Integration/`--dirty`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Git Integration/`--diff`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Output Formats",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Output Formats/XML (default)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Output Formats/Markdown (`-f markdown`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Output Formats/JSONL (`-f jsonl`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Output Formats/Plain (`-f plain`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Caching (`.packx_cache/`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Bundles (`-b` / `--bundle`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Interactive Mode (`-I`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Interactive Mode (`-I`)/Features",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Interactive Mode (`-I`)/Key Bindings",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Interactive Mode (`-I`)/After Selection",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Watch Mode (`-w`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/`--instruction` and `--prompt`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/`--preview` Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/`--explain` Mode",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/`--skeleton` Mode (v4.15.0+)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Secret Redaction (v4.15.0+)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/`--minify` Behavior",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Token Splitting (`--max-tokens` / `-M`)",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Concurrency",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/.packignore",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Positional Path Arguments",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-packx/references/packx-deep-reference.md#Packx Deep Reference/Gotchas & Edge Cases",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 1860,
      "url": "/topics/codex-packx-technical-reference/",
      "markdownUrl": "/markdown/codex-packx-technical-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-packx-technical-reference.json",
      "headings": [
        {
          "id": "file-discovery-pipeline",
          "text": "File Discovery Pipeline",
          "level": 2
        },
        {
          "id": "processing-order",
          "text": "Processing Order",
          "level": 3
        },
        {
          "id": "auto-excluded-directories-files-default-ignore-patterns",
          "text": "Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)",
          "level": 3
        },
        {
          "id": "default-extensions-no-i-flag",
          "text": "Default Extensions (no `-i` flag)",
          "level": 3
        },
        {
          "id": "the-i-include-glob-critical-behavior",
          "text": "The `-i` Include Glob: Critical Behavior",
          "level": 2
        },
        {
          "id": "token-budget-limit",
          "text": "Token Budget (`--limit`)",
          "level": 2
        },
        {
          "id": "k-vs-k-notation",
          "text": "k vs K Notation",
          "level": 3
        },
        {
          "id": "token-counting",
          "text": "Token Counting",
          "level": 3
        },
        {
          "id": "interactive-mode-limit",
          "text": "Interactive Mode + Limit",
          "level": 3
        },
        {
          "id": "import-following-follow-imports",
          "text": "Import Following (`--follow-imports`)",
          "level": 2
        },
        {
          "id": "supported-import-styles",
          "text": "Supported Import Styles",
          "level": 3
        },
        {
          "id": "resolution",
          "text": "Resolution",
          "level": 3
        },
        {
          "id": "parse-strategy",
          "text": "Parse Strategy",
          "level": 3
        },
        {
          "id": "related-files-r-related",
          "text": "Related Files (`-r` / `--related`)",
          "level": 2
        },
        {
          "id": "comment-stripping-strip-comments",
          "text": "Comment Stripping (`--strip-comments`)",
          "level": 2
        },
        {
          "id": "ast-based-primary-tree-sitter",
          "text": "AST-Based (primary — tree-sitter)",
          "level": 3
        },
        {
          "id": "regex-fallback-by-language-family",
          "text": "Regex Fallback (by language family)",
          "level": 3
        },
        {
          "id": "context-lines-l-lines",
          "text": "Context Lines (`-l` / `--lines`)",
          "level": 2
        },
        {
          "id": "smart-context-mode",
          "text": "Smart Context Mode",
          "level": 3
        },
        {
          "id": "overlap-merging",
          "text": "Overlap Merging",
          "level": 3
        },
        {
          "id": "indent-based-block-detection-fallback",
          "text": "Indent-Based Block Detection (fallback)",
          "level": 3
        },
        {
          "id": "git-integration",
          "text": "Git Integration",
          "level": 2
        },
        {
          "id": "staged",
          "text": "`--staged`",
          "level": 3
        },
        {
          "id": "dirty",
          "text": "`--dirty`",
          "level": 3
        },
        {
          "id": "diff",
          "text": "`--diff`",
          "level": 3
        },
        {
          "id": "output-formats",
          "text": "Output Formats",
          "level": 2
        },
        {
          "id": "xml-default",
          "text": "XML (default)",
          "level": 3
        },
        {
          "id": "markdown-f-markdown",
          "text": "Markdown (`-f markdown`)",
          "level": 3
        },
        {
          "id": "jsonl-f-jsonl",
          "text": "JSONL (`-f jsonl`)",
          "level": 3
        },
        {
          "id": "plain-f-plain",
          "text": "Plain (`-f plain`)",
          "level": 3
        },
        {
          "id": "caching-packx-cache",
          "text": "Caching (`.packx_cache/`)",
          "level": 2
        },
        {
          "id": "bundles-b-bundle",
          "text": "Bundles (`-b` / `--bundle`)",
          "level": 2
        },
        {
          "id": "interactive-mode-i",
          "text": "Interactive Mode (`-I`)",
          "level": 2
        },
        {
          "id": "features",
          "text": "Features",
          "level": 3
        },
        {
          "id": "key-bindings",
          "text": "Key Bindings",
          "level": 3
        },
        {
          "id": "after-selection",
          "text": "After Selection",
          "level": 3
        },
        {
          "id": "watch-mode-w",
          "text": "Watch Mode (`-w`)",
          "level": 2
        },
        {
          "id": "instruction-and-prompt",
          "text": "`--instruction` and `--prompt`",
          "level": 2
        },
        {
          "id": "preview-mode",
          "text": "`--preview` Mode",
          "level": 2
        },
        {
          "id": "explain-mode",
          "text": "`--explain` Mode",
          "level": 2
        },
        {
          "id": "skeleton-mode-v4-15-0",
          "text": "`--skeleton` Mode (v4.15.0+)",
          "level": 2
        },
        {
          "id": "secret-redaction-v4-15-0",
          "text": "Secret Redaction (v4.15.0+)",
          "level": 2
        },
        {
          "id": "minify-behavior",
          "text": "`--minify` Behavior",
          "level": 2
        },
        {
          "id": "token-splitting-max-tokens-m",
          "text": "Token Splitting (`--max-tokens` / `-M`)",
          "level": 2
        },
        {
          "id": "concurrency",
          "text": "Concurrency",
          "level": 2
        },
        {
          "id": "packignore",
          "text": ".packignore",
          "level": 2
        },
        {
          "id": "positional-path-arguments",
          "text": "Positional Path Arguments",
          "level": 2
        },
        {
          "id": "gotchas-edge-cases",
          "text": "Gotchas & Edge Cases",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# PackX discovery, processing, and token mechanics\n\nComplete technical reference for packx v4.x — the AI context bundler.\n\n## File Discovery Pipeline\n\n### Processing Order\n1. **Candidate discovery** — by extension + glob patterns + git mode\n2. **Ignore filtering** — `.gitignore` (traversed upward) + `.packignore` + default ignores\n3. **Content filtering** — search strings (`-s`) and exclusion strings (`-S`)\n4. **Size filtering** — skip files > 10MB silently\n5. **Binary detection** — first 512 bytes checked for null bytes; >10% non-printable = binary → skip\n6. **Pattern matching** — minimatch for `-i`/`-x` patterns\n7. **Token counting** — js-tiktoken (GPT tokenizer), fallback: `text.length / 4`\n\n### Auto-Excluded Directories & Files (DEFAULT_IGNORE_PATTERNS)\n```\n**/node_modules/**     **/.git/**          **/dist/**\n**/build/**            **/.next/**         **/coverage/**\n**/.cache/**           **/tmp/**           **/temp/**\n**/*.log               **/.DS_Store        **/Thumbs.db\n**/package-lock.json   **/yarn.lock        **/pnpm-lock.yaml\n**/bun.lockb           **/bun.lock         **/Gemfile.lock\n**/Cargo.lock          **/poetry.lock      **/Pipfile.lock\n**/composer.lock\n```\n\n### Default Extensions (no `-i` flag)\n**Languages:** js, jsx, ts, tsx, mjs, cjs, py, rb, go, java, cpp, c, h, rs, swift, kt, scala, php\n**Web Frameworks:** vue, svelte, astro\n**Styles:** css, scss, less\n**Config:** json, yaml, yml, toml, xml\n**Documentation:** md, mdx, txt\n**Scripts:** sh, bash, zsh, fish\n**Data:** sql, graphql, gql\n\n## The `-i` Include Glob: Critical Behavior\n\n**The `-i` flag requires `**/` prefix for extension matching:**\n\n```bash\n# CORRECT — always use **/ prefix for extensions\npackx --limit 900k -i \"**/*.ts\" --preview\npackx --limit 900k -i \"src/**/*.tsx\" --preview\n\n# WRONG — bare *.ext does NOT match\npackx --limit 900k -i \"*.ts\" --preview    # Matches nothing!\n```\n\nDirectory-style includes (`-i \"src/\"`) work without `**/`.\nThe `-x` exclude flag is more lenient — `\"*.test.*\"` works for excludes.\n\n## Token Budget (`--limit`)\n\nOracle browser-mode packx workflows now target up to ~900k tokens. The previous ~49k target is obsolete; keep bundles rich unless the question is narrow or the user asks for a smaller context.\n\n### k vs K Notation\n| Notation | Multiplier | Example | Exact Result |\n|----------|-----------|---------|--------------|\n| lowercase `k` | × 1,000 (SI) | `900k` | 900,000 tokens |\n| UPPERCASE `K` | × 1,024 (binary) | `32K` | 32,768 tokens |\n| No suffix | Raw number | `50000` | 50,000 tokens |\n| Decimal | Works with both | `1.5k` | 1,500 tokens |\n\n### Token Counting\n- Uses `js-tiktoken` (OpenAI's tokenizer) for accurate GPT token counts\n- Fallback: `Math.round(text.length / 4)` if tiktoken fails\n- Counts are cached per-file in `.packx_cache/cache.json`\n\n### Interactive Mode + Limit\nWhen `--limit` is used with interactive mode (`-I`), a visual progress bar shows real-time token consumption as files are selected/deselected.\n\n## Import Following (`--follow-imports`)\n\n### Supported Import Styles\n1. ES6: `import ... from \"...\"` and `export ... from \"...\"`\n2. CommonJS: `require(\"...\")`\n3. Dynamic: `import(\"...\")`\n\n### Resolution\n- **Only follows relative imports** (`./` or `../`), never `node_modules`\n- Max depth: 10 levels\n- Circular dependencies handled via visited-path Set\n\n**Resolution extensions tried (in order):**\n`\"\"`, `.ts`, `.tsx`, `.js`, `.jsx`, `.mts`, `.mjs`, `.cts`, `.cjs`, `.json`\n\n**Extension mappings:**\n- `.js` → tries `.ts`, `.tsx`, `.js`, `.jsx`\n- `.mjs` → tries `.mts`, `.mjs`\n- `.cjs` → tries `.cts`, `.cjs`\n- `.jsx` → tries `.tsx`, `.jsx`\n\n**Index files for directory imports:**\n`index.ts`, `index.tsx`, `index.js`, `index.jsx`, `index.mts`, `index.mjs`\n\n### Parse Strategy\n1. Tree-sitter AST parsing first (for .ts, .js, etc.)\n2. Regex fallback if AST unavailable:\n```\nimport\\s+(?:[\\w\\s{},*]+\\s+from\\s+)?[\"']([^\"']+)[\"']\nexport\\s+(?:[\\w\\s{},*]+\\s+from\\s+)?[\"']([^\"']+)[\"']\nrequire\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)\nimport\\s*\\(\\s*[\"']([^\"']+)[\"']\\s*\\)\n```\n\n## Related Files (`-r` / `--related`)\n\nExtracts base name (before first dot after name), then finds all files in the same directory with the same core name:\n- `Button.tsx` → finds `Button.test.tsx`, `Button.stories.tsx`, `Button.module.css`, etc.\n- Recursively expands matched files with their related files\n\n## Comment Stripping (`--strip-comments`)\n\n### AST-Based (primary — tree-sitter)\n- Language-specific tree-sitter grammar\n- Collects all comment nodes from AST\n- Removes entire lines if only whitespace surrounds the comment\n- Otherwise removes inline comments preserving code\n\n### Regex Fallback (by language family)\n| Language Family | Languages | Patterns |\n|----------------|-----------|----------|\n| C-style | js, jsx, ts, tsx, java, c, cpp, go, rust, swift, php, css, scss, less | `/* ... */` and `// ...` |\n| Hash-style | py, rb, sh, bash, zsh, yaml, yml, toml | `# ...` |\n| HTML-style | html, xml, md, mdx, vue, svelte, astro | `<!-- ... -->` |\n| Lua-style | lua, sql | `-- ...` |\n\nAll regex fallbacks preserve quoted strings.\n\n## Context Lines (`-l` / `--lines`)\n\n### Smart Context Mode\n1. Extracts N lines around each match\n2. **Tries to expand to complete code blocks** using tree-sitter AST\n3. Falls back to indent-based block detection\n4. Max expansion: `contextLines × 2`\n\n### Overlap Merging\nWindows sorted by start line, then merged if `window.startLine <= current.endLine + 1`. Matches from overlapping regions are combined.\n\n### Indent-Based Block Detection (fallback)\n- Scans upward for lower indentation level (block openers: `{`, `:`, function/class/if keywords)\n- Scans downward for closing braces or lower indentation\n\n## Git Integration\n\n### `--staged`\n```\ngit diff --cached --name-only --diff-filter=ACMR\n```\n(Added, Copied, Modified, Renamed)\n\n### `--dirty`\n```\ngit diff --name-only --diff-filter=ACMR       # modified\ngit ls-files --others --exclude-standard       # untracked\n```\nReturns deduplicated union.\n\n### `--diff`\n```\ngit merge-base <branch> HEAD                    # find common ancestor\ngit diff --name-only --diff-filter=ACMR <base>  # diff from there\n```\nFalls back to branch name directly if merge-base fails.\n\n**These three flags are mutually exclusive.**\n\n## Output Formats\n\n### XML (default)\n```xml\n<file_summary>\n  <purpose>...</purpose>\n</file_summary>\n<directory_structure>file paths</directory_structure>\n<files>\n  <file path=\"src/auth.ts\" matches=\"3\" windows=\"2\">\n    ...content or context windows...\n  </file>\n</files>\n```\n\n### Markdown (`-f markdown`)\n```markdown\n# Packx Output\nThis file contains X filtered files...\n## Files\n### src/auth.ts (3 matches)\n```ts\n...content...\n```​\n```\n\n### JSONL (`-f jsonl`)\nOne JSON object per line:\n```json\n{\"path\":\"src/auth.ts\",\"content\":\"...\",\"tokens\":150,\"matches\":[{\"line\":10,\"column\":5,\"match\":\"...\"}]}\n```\n\n### Plain (`-f plain`)\nLike markdown but simpler header, no fenced blocks.\n\n## Caching (`.packx_cache/`)\n\n**Cache file:** `.packx_cache/cache.json` (version 2)\n\n**Entry structure:**\n```json\n{\n  \"mtime\": 1702000000000,\n  \"size\": 4096,\n  \"contentHash\": \"sha256hex...\",\n  \"isBinary\": false,\n  \"tokens\": 342\n}\n```\n\n**Validation strategy:**\n1. mtime AND size match → cache hit (fast path)\n2. Size differs → cache miss\n3. mtime differs but size same → compute SHA-256 → compare hash\n4. Hash matches → update mtime, keep entry\n5. Hash differs → cache miss, recompute\n\n**Bypass:** `--no-cache`\n**Prune:** Stale entries for deleted files cleaned on next run\n\n## Bundles (`-b` / `--bundle`)\n\n- Stored in `.pack/bundles/` directory\n- Extensions: `.bundle`, `.pack`, `.txt`\n- Format: gitignore-style patterns (one per line, `#` for comments)\n- In interactive mode: loads bundles as pre-selected file sets\n- With `-b name`: loads non-interactively and outputs directly\n\n## Interactive Mode (`-I`)\n\n**Default since v4.7.0** — running `packx` with no output flags enters interactive mode.\n\n### Features\n- Tree-based file browser with token counts\n- Live preview pane with syntax highlighting\n- Token budget progress bar (`--limit`)\n- Git status decorators: `[M]` Modified, `[A]` Added, `[?]` Untracked\n- `.packignore` files shown but start unselected\n- Fuzzy search filtering\n- Visual dependency graph\n\n### Key Bindings\n| Key | Action |\n|-----|--------|\n| `j/k` or ↑/↓ | Navigate |\n| `Space` | Toggle selection |\n| `Shift+Space` / `v` | Range selection (anchor) |\n| `Tab` | Toggle preview focus |\n| `PgUp/PgDn` | Scroll preview |\n| `g/G` | Jump to top/bottom |\n| `h/l` | Collapse/expand folder |\n| `o` | Open in editor |\n| `d` | Resolve dependencies |\n| `c` | Toggle comment stripping |\n| `+/-` | Adjust context lines |\n| `x` | Banish to `.packignore` |\n| `?` | Full-screen help overlay |\n| `Enter` | Confirm selection |\n\n### After Selection\n- Option to save glob pattern to `.packignore`\n- Option to save selection as named bundle\n- Choose output: clipboard, file, stdout, or skip\n\n## Watch Mode (`-w`)\n\n- Uses `chokidar` with 150ms debounce\n- File stabilization: 100ms threshold, 50ms poll interval\n- Watches: `change`, `add`, `unlink` events\n- **Requires** `--output` or `--copy`\n- **Cannot combine with `-I`** (interactive)\n- Ctrl+C for graceful shutdown\n\n## `--instruction` and `--prompt`\n\n| Flag | Position | Input |\n|------|----------|-------|\n| `--instruction <file>` | Prepends to TOP of output | File path |\n| `--prompt <text>` / `-p` | Appends to END of output | Inline text |\n\n## `--preview` Mode\n\n- Dry run: shows matching files without packing content\n- Displays up to 50 files (rest counted as \"... and X more\")\n- Shows file count total\n- Useful for testing filter combinations before committing\n\n## `--explain` Mode\n\n- Full dry run with detailed logging\n- Shows: resolved config options, file discovery process, pattern matching, what would be included\n- No output generated\n\n## `--skeleton` Mode (v4.15.0+)\n\n- AST-based: strips function bodies to `{ /* ... */ }`\n- Keeps interfaces, type definitions, function signatures\n- Great for architecture review at minimal token cost\n\n## Secret Redaction (v4.15.0+)\n\nAutomatically detects and redacts 22 pattern types:\nAWS keys, GitHub tokens, JWTs, database connection strings, API keys, private keys, etc.\nReplaces matches with `<REDACTED:TYPE>`.\n\n## `--minify` Behavior\n\n```javascript\ncontent.split('\\n')\n  .map(line => line.trim())\n  .filter(line => line.length > 0)\n  .join('\\n')\n```\nRemoves empty lines, trims whitespace per line.\n\n## Token Splitting (`--max-tokens` / `-M`)\n\n- Reserves ~50 tokens per chunk for headers/footers\n- **Files are never split mid-file**\n- A single file exceeding the budget is skipped entirely (marked \"oversized\")\n- Creates: `output-1.xml`, `output-2.xml`, etc.\n- Only chunk 1 copied to clipboard; rest go to files\n\n## Concurrency\n\n- Files analyzed in parallel using `p-limit`\n- `CONCURRENCY_LIMIT = 50`\n- Progress emitted every 50 files or 10% of total\n\n## .packignore\n\n- Gitignore syntax (processed by `ignore` npm library)\n- Auto-loaded from project root\n- `--no-packignore` to disable\n- In interactive mode: matching files shown but unselected\n- `x` hotkey in interactive mode banishes files to `.packignore`\n\n## Positional Path Arguments\n\n```bash\npackx src/          # Directory → scan root\npackx README.md     # File → explicit include\npackx \"**/*.test.ts\" # Glob pattern → include pattern\n```\n\n**Classification:**\n- Contains `*`, `?`, `[`, `]`, `{`, `}`, `!` → treated as glob pattern\n- Exists as directory → treated as scan root\n- Exists as file → treated as explicit file include\n\n**Interaction with filters:**\n- Explicit files + `-i` patterns: must match BOTH\n- Positional roots: used as starting directories for scanning\n- Positional globs: added to include patterns\n\n## Gotchas & Edge Cases\n\n| Issue | Detail |\n|-------|--------|\n| `-i \"*.ts\"` matches nothing | Must use `\"**/*.ts\"` with `**/` prefix for extensions |\n| Interactive is default | Since v4.7.0, bare `packx` enters interactive mode. Use `--no-interactive` for scripting |\n| `--stdout` disables interactive | Can't combine `--stdout` with `-I` |\n| `--watch` + `-I` incompatible | Watch requires output target, can't be interactive |\n| Files >10MB silently skipped | No warning — use `--explain` to debug missing files |\n| Single file > `--max-tokens` | Entire file skipped, not split |\n| Clipboard: only chunk 1 | When splitting, remaining chunks go to files |\n| Binary files silently skipped | >10% non-printable chars in first 512 bytes |\n\n## Operational boundaries\n\n- Processing order, cache format, secret-detector coverage, AST fallbacks, and numeric limits describe the referenced implementation. Confirm the installed version; stripped or minified context may omit semantics needed for the question.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-tools-preference-rlhf",
      "slug": "tools-preference-rlhf",
      "title": "Preference capture / personal RLHF (this-or-that)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "preference-rlhf"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#preference-rlhf"
        }
      ],
      "sourceUnits": [
        "resources/index.html#preference-rlhf"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 324,
      "url": "/topics/factory-tools-preference-rlhf/",
      "markdownUrl": "/markdown/factory-tools-preference-rlhf.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-preference-rlhf.json",
      "headings": [
        {
          "id": "preference-capture-personal-rlhf-this-or-that",
          "text": "Preference capture / personal RLHF (this-or-that)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Preference capture / personal RLHF (this-or-that)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Preference capture / personal RLHF (this-or-that)\n\n**John uses:** the **this-or-that kit** (section 10; kit published at [gentle-lasso-9d5n.here.now/kit/](https://gentle-lasso-9d5n.here.now/)) — `compare.html` + a 30-line `server.py` + `options.json`: Elo pairing, arrow-key duels, both-bad/skip, per-vote notes, light/dark per-mode tracking; every vote appends to `votes.jsonl`, which agents read back as explicit taste rules. This repo's own theme was chosen by it (130 votes, 3 rounds).\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [FastChat (Chatbot Arena)](https://github.com/lm-sys/FastChat) | The platform behind Chatbot Arena: side-by-side battles + Elo ratings for LLM outputs | The industrial version of the same idea (pairwise vote → Elo); heavyweight, model-comparison focused; check current repository activity | Apache-2.0 |\n| [Argilla](https://github.com/argilla-io/argilla) | Collaboration tool for building high-quality AI datasets, including preference/ranking records | Team-scale dataset curation with a server; overkill for a solo taste record but the real thing for RLHF data | Apache-2.0 |\n| [Label Studio](https://github.com/HumanSignal/label-studio) | Multi-type data labeling tool with pairwise-comparison templates | General annotation platform; pairwise comparison is one template among many | Apache-2.0 |\n| [potato](https://github.com/davidjurgens/potato) | Portable academic annotation tool (Python), supports pairwise/best-worst schemes | Lightweight and self-hostable like the kit, config-driven rather than iframe-anything | GPL-3.0 |\n| [promptfoo](https://github.com/promptfoo/promptfoo) | Prompt/agent eval harness with side-by-side output comparison views | Automated + human-graded evals over prompt variants — the 'evals' complement to taste voting | MIT |\n\n### Pick this if…\n\n- **the kit itself** — it's ~3 small files and free; there's little reason not to start with it.\n- **promptfoo** — your comparisons are prompt/agent outputs and you want automation around the human votes.\n- **Argilla / Label Studio** — you're collecting preferences from a *team*, not just yourself.\n- **FastChat** — you're literally comparing models and want battle-tested Elo infrastructure.\n- **potato** — you want a tiny self-hosted study-style setup with config-defined schemes."
    },
    {
      "id": "factory-tools-prompt-tooling",
      "slug": "tools-prompt-tooling",
      "title": "Prompt composing (prompt-builder)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "prompt-tooling"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#prompt-tooling"
        }
      ],
      "sourceUnits": [
        "resources/index.html#prompt-tooling"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 366,
      "url": "/topics/factory-tools-prompt-tooling/",
      "markdownUrl": "/markdown/factory-tools-prompt-tooling.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-prompt-tooling.json",
      "headings": [
        {
          "id": "prompt-composing-prompt-builder",
          "text": "Prompt composing (prompt-builder)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Prompt composing (prompt-builder)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Prompt composing (prompt-builder)\n\n**John uses:** [prompt-builder](https://github.com/johnlindquist/prompt-builder) (`p`, MIT) — a Rust/Ratatui TUI that gives the prompt its own tool before any agent launches: skills lookup (`$`), file search (`@`), cross-session history (`Ctrl+R`, shared with Codex's history.jsonl), then launches pi/Codex/Claude via `targets.toml` — or hands the prompt as the final argv element to *any* command (`--handoff-command`), which is the bridge to mdflow.\n\nNothing public replicates this exact \"compose-then-launch-any-agent\" TUI; these cover its axes:\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [fabric](https://github.com/danielmiessler/Fabric) | Open-source framework with a crowdsourced library of reusable AI prompts ('patterns') runnable from the CLI | Curated prompt library + pipe-friendly CLI rather than an interactive composer; patterns ≈ reusable prompt shapes | MIT |\n| [llm (Simon Willison)](https://github.com/simonw/llm) | CLI for any LLM with reusable templates, fragments, logged history in SQLite | Templates + logged/searchable prompt history covers prompt-builder's reuse and history axes, minus the TUI and agent handoff | Apache-2.0 |\n| [aichat](https://github.com/sigoden/aichat) | All-in-one LLM CLI: Shell Assistant, chat REPL, roles, sessions, RAG, macros | Roles/sessions give reusable prompt setups; REPL-centric rather than compose-then-launch; check current repository activity | Apache-2.0 |\n| [espanso](https://github.com/espanso/espanso) | Privacy-first cross-platform text expander in Rust | System-wide snippet expansion — the low-tech way to get instant prompt scaffolds in ANY agent's input box | GPL-3.0 |\n| [promptfoo](https://github.com/promptfoo/promptfoo) | Test/eval harness for prompts, agents, and RAGs with declarative configs | Adjacent, not a composer: it evaluates prompt variants — pairs well with a this-or-that habit | MIT |\n\n### Pick this if…\n\n- **fabric** — you want a library of proven prompt shapes runnable from the shell.\n- **llm** — you want reusable templates plus searchable prompt history (the SQLite log is the killer feature).\n- **espanso** — you just want instant prompt scaffolds in *any* input box, agents included.\n- **aichat** — you want roles/sessions in a REPL rather than compose-then-launch.\n- **promptfoo** — you're past composing and want to *measure* prompt variants.\n- Or steal the pattern cheaply: a zsh function + `$EDITOR` tempfile + `\"$(cat file)\"` into your agent is 70% of `p`."
    },
    {
      "id": "codex-shell-environment-reference",
      "slug": "shell-environment-reference",
      "title": "Reliable non-interactive shell environments: practical reference",
      "summary": "Step-by-step agent setup prompt and troubleshooting reference for non-interactive zsh startup, ZDOTDIR, deterministic PATH, safe environment bootstrapping, opt-in helper loading, Codex launch wrappers and configuration, executable fallbacks, targeted…",
      "category": "Tools",
      "tags": [
        "zsh",
        "environment",
        "path"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Visibility Layers",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Opt-In Function Loading",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/What The Marker Does",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/The Opt-In Marker Is Not Interactive Startup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/What To Confirm",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Confirm The Opt-In Marker",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Handoff To Section 3",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Inspect PATH Order",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Clean-Shell Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/Where Fixes Usually Belong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Tool Works In Terminal, Missing In Codex",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Wrong Executable Wins",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Agent Startup Hangs",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Secrets Leak Risk",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/If It Goes Wrong/Tool Visibility Works, But A Helper Name Is Missing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/02-loading-zsh-env-into-codex.md#02. Loading ZSH Env Into Codex/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 2822,
      "url": "/topics/codex-shell-environment-reference/",
      "markdownUrl": "/markdown/codex-shell-environment-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-environment-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "visibility-layers",
          "text": "Visibility Layers",
          "level": 2
        },
        {
          "id": "opt-in-function-loading",
          "text": "Opt-In Function Loading",
          "level": 2
        },
        {
          "id": "what-the-marker-does",
          "text": "What The Marker Does",
          "level": 2
        },
        {
          "id": "the-opt-in-marker-is-not-interactive-startup",
          "text": "The Opt-In Marker Is Not Interactive Startup",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm",
          "text": "What To Confirm",
          "level": 2
        },
        {
          "id": "confirm-the-opt-in-marker",
          "text": "Confirm The Opt-In Marker",
          "level": 2
        },
        {
          "id": "handoff-to-section-3",
          "text": "Handoff To Section 3",
          "level": 2
        },
        {
          "id": "inspect-path-order",
          "text": "Inspect PATH Order",
          "level": 2
        },
        {
          "id": "clean-shell-check",
          "text": "Clean-Shell Check",
          "level": 2
        },
        {
          "id": "where-fixes-usually-belong",
          "text": "Where Fixes Usually Belong",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "tool-works-in-terminal-missing-in-codex",
          "text": "Tool Works In Terminal, Missing In Codex",
          "level": 3
        },
        {
          "id": "wrong-executable-wins",
          "text": "Wrong Executable Wins",
          "level": 3
        },
        {
          "id": "agent-startup-hangs",
          "text": "Agent Startup Hangs",
          "level": 3
        },
        {
          "id": "secrets-leak-risk",
          "text": "Secrets Leak Risk",
          "level": 3
        },
        {
          "id": "tool-visibility-works-but-a-helper-name-is-missing",
          "text": "Tool Visibility Works, But A Helper Name Is Missing",
          "level": 3
        },
        {
          "id": "how-to-know-it-worked",
          "text": "How To Know It Worked",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Reliable non-interactive shell environments: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up an agent-safe zsh and Codex shell environment so commands run through `zsh -lc` can resolve required project tools, load selected helper files only when explicitly opted in, and keep the full interactive `.zshrc` out of agent shells.\n\nStep 1. Inspect before changing anything. Check the current non-interactive login shell view with targeted commands only:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nDo not paste full `env` output. Do not print secret values, token values, cookies, private endpoints, or provider-specific API variables.\n\nStep 2. Configure `ZDOTDIR` from `~/.zshenv`. Keep `~/.zshenv` minimal because every zsh process reads it. Its job should be early, safe bootstrap only, such as:\n\n    export ZDOTDIR=\"${ZDOTDIR:-$HOME/.config/zsh}\"\n\nVerify:\n\n    zsh -lc 'echo \"ZDOTDIR=$ZDOTDIR\"; test -d \"$ZDOTDIR\" && echo \"ZDOTDIR exists\" || echo \"ZDOTDIR missing\"'\n\nStep 3. Create or update `$ZDOTDIR/.zprofile` as the login-shell bridge for `zsh -lc`. Remember: `zsh -lc` is a login shell, but it is not interactive. Source only agent-safe startup files from here, such as `codex-env.zsh`, `conf.d/00-path.zsh`, and reviewed local overrides.\n\nUse this shape, adjusted to the existing files:\n\n    [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n    [[ -r \"$ZDOTDIR/conf.d/00-path.zsh\" ]] && source \"$ZDOTDIR/conf.d/00-path.zsh\"\n    [[ -r \"$ZDOTDIR/local.zsh\" ]] && source \"$ZDOTDIR/local.zsh\"\n\nStep 4. Put agent-safe environment setup in `$ZDOTDIR/codex-env.zsh`. This file may set non-secret tool environment needed by agents and should mark that it loaded:\n\n    export CODEX_AGENT_ENV_SOURCED=1\n\nDo not put prompts, completions, keybindings, fuzzy finders, terminal UI, interactive confirmations, token-resolving commands, or secret-printing helpers here.\n\nStep 5. Put deterministic PATH assembly in `$ZDOTDIR/conf.d/00-path.zsh`. Add required tool directories such as Cargo, Bun, pnpm, Homebrew, project-local bins, and `~/.local/bin` as appropriate for the local install. Make PATH order explicit so the intended executable wins.\n\nVerify PATH order:\n\n    zsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n\nVerify executable resolution:\n\n    zsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n\nStep 6. Use `$ZDOTDIR/local.zsh` only for safe local overrides that are appropriate in non-interactive shells. Do not copy private config verbatim if it contains secrets, API-key helper wiring, cookies, tokens, provider variables, or private endpoints.\n\nStep 7. Keep `$ZDOTDIR/.zshrc` interactive-only. Prompt setup, completion setup, aliases for human typing, keybindings, terminal UI, profiling, and fuzzy finder setup belong there or behind an interactive guard. Do not source `.zshrc` from `.zprofile`, `codex-env.zsh`, or agent shell startup.\n\nStep 8. Add opt-in helper loading with `CODEX_LOAD_ZSH_DSL`. Treat `CODEX_LOAD_ZSH_DSL` as a local marker, not a Codex built-in. When it is present, load only selected agent-safe helper files such as `$ZDOTDIR/conf.d/40-ai.zsh`; do not load the full `.zshrc`.\n\nAdd this in the agent-safe startup path after `ZDOTDIR` is available:\n\n    if [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n      [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\n    fi\n\nVerify the marker is absent by default:\n\n    zsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n\nVerify selected helper loading when requested:\n\n    CODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n\nStep 9. Configure Codex marker injection with `shell_environment_policy.set`. Prefer wrapper-local `-c` flags so the behavior is explicit and reversible. Add or update `xi`, `x`, and `e` wrappers in the interactive helper file that defines Codex launch helpers:\n\n    xi() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n    }\n\n    x() {\n      codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\n    e() {\n      codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n    }\n\nOnly add this to `~/.codex/config.toml` if every Codex launch should load the helper DSL:\n\n    [shell_environment_policy.set]\n    CODEX_LOAD_ZSH_DSL = \"1\"\n\nOtherwise, keep the marker out of global config and use the wrappers.\n\nVerify wrapper policy wiring:\n\n    zsh -ic 'functions xi 2>/dev/null; functions x 2>/dev/null; functions e 2>/dev/null' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL' || true\n    rg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n\nStep 10. Run the base proof and clean-shell proof. The clean-shell check avoids being fooled by inherited marker state.\n\n    zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\n    env -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v codex bun pnpm cargo packx || true'\n\nExpected result: `CODEX_AGENT_ENV_SOURCED=1`, `ZDOTDIR` points at the intended config directory, required tools print real paths, and no secret values are printed.\n\nStep 11. Add executable fallbacks for important helper entrypoints that must work outside zsh. If a workflow currently exists only as an alias or zsh function but scripts, CI, non-zsh callers, or agents need it, create a real executable wrapper on PATH, for example under `~/.local/bin`, and verify it with `zsh -lc 'command -v <name>'`.\n\nStep 12. Final confirmation. Stop when `zsh -lc` resolves the required project tools, the clean-shell check also resolves them, PATH order is explainable, `CODEX_LOAD_ZSH_DSL` behavior is explicit and reversible, `.zshrc` remains interactive-only, startup does not print secrets or wait for UI, and Codex can run the project command that originally failed. If project tools resolve but a helper name is still missing, classify that helper separately instead of fixing it by sourcing `.zshrc`.\n```\n\n## Big Idea\n\nWhen Codex runs a shell command, it is not inside your current terminal session.\n\nThis section answers one question:\n\n```text\nWhat can Codex see when it runs a non-interactive login shell through `zsh -lc`?\n```\n\nFocus here on startup files, PATH order, environment markers, and project tools. Leave command-name classification for Section 3.\n\n## Try This Now\n\nRun the same shell shape Codex commonly uses:\n`zsh -lc 'echo ZDOTDIR=$ZDOTDIR; command -v bun pnpm cargo codex packx || true'`\nIf a project tool is missing here, fix agent-safe startup before changing the prompt.\n\n## Files To Inspect\n\nCommon files that define shell behavior:\n\n```text\n~/.zshenv\n~/.config/zsh/.zprofile\n~/.config/zsh/codex-env.zsh\n~/.config/zsh/conf.d/00-path.zsh\n~/.config/zsh/conf.d/40-ai.zsh\n~/.config/zsh/local.zsh\n~/.config/zsh/tests/startup-regression.zsh\n~/.codex/config.toml\n```\n\nAdjust paths for the local machine. Keep non-interactive startup setup in the agent-safe path.\n\n## When To Reach For This\n\nUse this workflow when:\n\n- Codex says a project executable is `command not found`\n- a tool works in your terminal but fails inside Codex\n- a project depends on Bun, pnpm, Cargo, PackX, Homebrew tools, or custom CLIs\n- you installed a tool but the agent still cannot run it\n- a workflow depends on PATH order\n- the wrong executable version wins inside Codex\n- selected agent-safe zsh files should load only when the opt-in marker is present\n- you need to decide whether PATH setup belongs in `.zprofile`, `codex-env.zsh`, `00-path.zsh`, or `local.zsh`\n\nSkip this workflow when the question is:\n\n```text\nIs this command name an alias, function, builtin, hashed command, executable, or missing helper?\n```\n\nThat is Section 3.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nIf a command works in your terminal, Codex can run it the same way.\n```\n\nWhat the workflow gives you now:\n\n```text\nCodex runs through a non-interactive shell. Ask it to prove each required tool\nresolves from `zsh -lc` before relying on the command.\n```\n\n## The Mental Model\n\nCodex commonly runs commands through a shell shape like:\n\n```bash\nzsh -lc '<command>'\n```\n\nThat means:\n\n- `zsh`: run zsh\n- `-l`: login shell\n- `-c`: run a command string\n\nIt is login, but not interactive.\n\nThat distinction matters:\n\n| File Or Setting | Role |\n| --- | --- |\n| `~/.zshenv` | earliest bootstrap; points zsh toward XDG config |\n| `ZDOTDIR` | tells zsh where `.zprofile`, `.zshrc`, and related files live |\n| `$ZDOTDIR/.zprofile` | login-shell bridge for `zsh -lc` |\n| `$ZDOTDIR/codex-env.zsh` | agent-safe environment bootstrap |\n| `$ZDOTDIR/conf.d/00-path.zsh` | deterministic PATH assembly |\n| `$ZDOTDIR/conf.d/40-ai.zsh` | selected AI/Codex helper functions loaded only when opted in |\n| `$ZDOTDIR/local.zsh` | machine-specific safe overrides |\n| `$ZDOTDIR/.zshrc` | human interactive terminal startup |\n\nPractical rule:\n\n```text\nPut PATH and non-interactive-safe tool setup in the agent path.\nPut prompt, completion, keybindings, and terminal UI in `.zshrc`.\n```\n\n## Visibility Layers\n\nKeep three layers separate.\n\n| Layer | What It Means | Section 2 Question |\n| --- | --- | --- |\n| Environment variable | inherited process data | is the variable present in `zsh -lc`? |\n| PATH executable | real file found through PATH | does `command -v <name>` resolve in `zsh -lc`? |\n| Opt-in zsh helper file | selected source file loaded by marker | does the marker cause the safe file to load? |\n\nThis section proves the environment and PATH layer.\nSection 3 classifies individual command names.\n\n## Opt-In Function Loading\n\nA common setup uses a local marker:\n\n```text\nCODEX_LOAD_ZSH_DSL=1\n```\n\n`CODEX_LOAD_ZSH_DSL` is a local opt-in marker for this shell setup.\n\nCodex can inject that marker into shell-like tool processes with `shell_environment_policy.set`:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n```\n\nThat marker can be wrapped in opt-in launchers:\n\n```zsh\nx() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\ne() {\n  codex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n```\n\nThe important part is the `-c` override:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\ncodex exec -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox \"$@\"\n```\n\nPrefer wrapper-local `-c` flags when the behavior should be explicit and reversible. Use a global `~/.codex/config.toml` setting only when every Codex launch should load the DSL:\n\n```toml\n[shell_environment_policy.set]\nCODEX_LOAD_ZSH_DSL = \"1\"\n```\n\nUse the global setting only when you want that behavior all the time. Otherwise, keep `CODEX_LOAD_ZSH_DSL` out of `~/.codex/config.toml` and put it on the specific wrappers that need zsh helper functions.\n\n## What The Marker Does\n\nThe marker lets the zsh bootstrap source a small set of agent-safe files instead of the full interactive `.zshrc`.\n\nShape:\n\n```zsh\nif [[ -n \"${CODEX_LOAD_ZSH_DSL:-}\" ]]; then\n  [[ -r \"$ZDOTDIR/codex-env.zsh\" ]] && source \"$ZDOTDIR/codex-env.zsh\"\n  [[ -r \"$ZDOTDIR/conf.d/40-ai.zsh\" ]] && source \"$ZDOTDIR/conf.d/40-ai.zsh\"\nfi\n```\n\nLoad selected helpers only. Keep the full interactive terminal experience out of agent shells.\n\nDo not source all of `.zshrc` into agent shells. Interactive startup often includes prompts, completions, keybindings, fuzzy finders, terminal hooks, and profiling code that can slow, hang, spam, or mutate non-interactive agent commands.\n\n## The Opt-In Marker Is Not Interactive Startup\n\n`x` and `e` can make Codex set `CODEX_LOAD_ZSH_DSL=1`, but that does not mean the full interactive shell is loaded.\n\nThe marker should load only selected agent-safe files.\n\nExpected shape:\n\n```text\nCODEX_LOAD_ZSH_DSL=1\n-> zsh startup\n-> codex-env.zsh\n-> selected safe helper files\n-> no prompt, completion, keybindings, fuzzy finder, or terminal UI\n```\n\nQuick visibility check:\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n```\n\nIf a helper name is missing after this works, do not diagnose it as a broken PATH. Diagnose it in Section 3 as a command-name, source-file, or executable-fallback question.\n\n## Ask The Agent This\n\nFor a missing tool:\n\n```text\nCodex cannot find `bun`, but it works in my terminal.\n\nInspect the zsh startup path for non-interactive commands. Check `zsh -lc`,\n`ZDOTDIR`, `codex-env.zsh`, PATH order, and where Bun is installed. Do not\ndump secrets or full environment output. Tell me which file should change and\nhow to confirm it worked.\n```\n\nFor a new project tool:\n\n```text\nThis project needs `my-tool` available to Codex.\n\nInspect the existing agent-safe zsh setup and recommend where the PATH entry or\nwrapper should live. Keep interactive shell behavior out of the agent startup\npath. Include a short command that confirms `my-tool` resolves in `zsh -lc`.\n```\n\nFor PATH confusion:\n\n```text\nThe wrong version of `node` or `pnpm` is winning inside Codex.\n\nInspect PATH order from `zsh -lc`, compare executable locations with `whence -a`,\nand identify the smallest safe config change. Do not modify `.zshrc` unless the\nproblem is only interactive terminal behavior.\n```\n\nFor opt-in marker boundaries:\n\n```text\nI want Codex tool shells to load only selected agent-safe zsh files without\nsourcing the full interactive `.zshrc`.\n\nInspect `~/.codex/config.toml`, `shell_environment_policy.set`,\n`CODEX_LOAD_ZSH_DSL`, `~/.config/zsh/.zshenv`, `codex-env.zsh`, and\n`conf.d/40-ai.zsh`. Confirm the marker is explicit and reversible. If an\nindividual helper name is missing after the marker works, stop and classify that\nname with Section 3.\n```\n\n## What To Confirm\n\nThe basic confirmation shape:\n\n```bash\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\nWhat to look for:\n\n- `CODEX_AGENT_ENV_SOURCED=1`\n- `ZDOTDIR` points at the intended zsh config\n- required tools print real paths\n- missing tools are named plainly\n- no secrets are printed\n\nA known-good output shape looks like:\n\n```text\nCODEX_AGENT_ENV_SOURCED=1\nZDOTDIR=/path/to/home/.config/zsh\n/path/to/home/.cargo/bin/codex\n/path/to/home/.bun/bin/bun\n/usr/local/bin/pnpm\n/path/to/home/.cargo/bin/cargo\n/path/to/home/.bun/bin/packx\n```\n\nUse local paths. Keep the proof shape.\n\n## Confirm The Opt-In Marker\n\nProve the marker is absent by default:\n\n```bash\nzsh -lc 'echo \"CODEX_LOAD_ZSH_DSL=${CODEX_LOAD_ZSH_DSL:-}\"'\n```\n\nProve the agent-safe files load when the marker is present:\n\n```bash\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'echo \"CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}\"; echo \"ZDOTDIR=$ZDOTDIR\"; command -v bun pnpm cargo codex packx || true'\n```\n\nInspect the Codex-side policy:\n\n```bash\nzsh -ic 'functions x; functions e' | rg 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL'\nrg -n 'shell_environment_policy|CODEX_LOAD_ZSH_DSL' ~/.codex/config.toml || true\n```\n\nWhat to look for:\n\n- `x` and `e` pass the marker through Codex with `-c`\n- global config does not set the marker unless you want it always on\n- tool visibility still works when the marker is present\n\n## Handoff To Section 3\n\nAfter `zsh -lc` proves the environment and PATH are correct, stop treating every missing name as a startup problem.\n\nNext question:\n\n```text\nWhat kind of command name is this?\n```\n\nUse Section 3 to classify aliases, functions, builtins, hashed commands, executables, missing helpers, and executable fallback decisions.\n\n## Inspect PATH Order\n\nPATH order decides which executable wins.\n\n```bash\nzsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,25p\"'\n```\n\nLook for:\n\n- project tool paths before system fallbacks when appropriate\n- Bun, pnpm, Cargo, Homebrew, and local bin locations\n- duplicate or surprising entries\n- installer edits that only touched `.zshrc`\n\n## Clean-Shell Check\n\nThe marker `CODEX_AGENT_ENV_SOURCED=1` can be inherited by nested shells. When testing startup from scratch, unset it:\n\n```bash\nenv -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\nIf the bootstrap works, the command should still end up with `CODEX_AGENT_ENV_SOURCED=1`.\n\n## Where Fixes Usually Belong\n\n| Problem | Usually Belongs In |\n| --- | --- |\n| persistent PATH assembly | `~/.config/zsh/conf.d/00-path.zsh` |\n| machine-local safe override | `~/.config/zsh/local.zsh` |\n| agent-safe tool env | `~/.config/zsh/codex-env.zsh` |\n| selected agent-safe functions | `~/.config/zsh/conf.d/40-ai.zsh` behind `CODEX_LOAD_ZSH_DSL` |\n| login-shell bridge | `~/.config/zsh/.zprofile` |\n| prompt, completion, keybindings | `~/.config/zsh/.zshrc` |\n| reusable project command | executable wrapper on PATH |\n| rich alias/function workflow | function or executable-wrapper design |\n\n## If It Goes Wrong\n\n### Tool Works In Terminal, Missing In Codex\n\nLikely cause:\n\n- installer modified `.zshrc`\n- Codex runs `zsh -lc`\n- `.zshrc` is interactive startup, not the agent-safe bridge\n\nConfirm:\n\n```bash\nzsh -lc 'command -v bun || echo \"bun missing from zsh -lc\"'\n```\n\nThen inspect `codex-env.zsh`, `00-path.zsh`, and `local.zsh`.\n\n### Wrong Executable Wins\n\nUse:\n\n```bash\nzsh -lc 'for cmd in node pnpm bun cargo codex packx; do echo \"--- $cmd ---\"; command -v \"$cmd\" || true; whence -a \"$cmd\" 2>/dev/null || true; done'\n```\n\nThe first matching executable is what the shell runs.\n\n### Agent Startup Hangs\n\nLikely cause:\n\n- prompt setup\n- completion setup\n- `fzf`\n- keybindings\n- terminal UI\n- interactive confirmation\n\nThose belong in `.zshrc` or behind an interactive guard, not in agent-safe startup.\n\n### Secrets Leak Risk\n\nDo not paste full `env` output into chat.\n\nUse targeted checks:\n\n```bash\nzsh -lc 'command -v op >/dev/null 2>&1 && echo \"op:visible\" || echo \"op:missing\"'\n```\n\nConfirm helpers exist without printing secret values.\n\n### Tool Visibility Works, But A Helper Name Is Missing\n\nIf required project tools resolve but a helper such as `xfl`, `p-f`, `fix`, or `funcwhere` is missing, the environment may already be fine.\n\nConfirm the project tools first:\n\n```bash\nzsh -lc 'command -v bun pnpm cargo codex packx || true'\n```\n\nThen move to Section 3 and classify the helper name. Do not fix helper-name problems by sourcing all of `.zshrc` into agent shells.\n\n## How To Know It Worked\n\nYou are done when:\n\n- `zsh -lc` resolves the required project tools\n- the clean-shell check also resolves them\n- PATH order is explainable\n- the opt-in marker behavior is explicit and reversible\n- the fix is in an agent-safe file\n- `.zshrc` is not carrying agent-only setup\n- no startup command prints secrets or waits for UI\n- Codex can run the project command that originally failed\n- unresolved helper names have been handed to Section 3 instead of treated as PATH failures\n\n## References And Resources\n\n- Common login-shell bridge: `~/.config/zsh/.zprofile`\n- Common agent bootstrap: `~/.config/zsh/codex-env.zsh`\n- Common PATH assembly: `~/.config/zsh/conf.d/00-path.zsh`\n- Common AI helper DSL: `~/.config/zsh/conf.d/40-ai.zsh`\n- Common AI fix helpers: `~/.config/zsh/conf.d/47-ai-fix.zsh`\n- Common local overrides: `~/.config/zsh/local.zsh`\n- Common startup regression tests: `~/.config/zsh/tests/startup-regression.zsh`\n- Codex config: `~/.codex/config.toml`\n- Zsh startup files: https://zsh.sourceforge.io/Intro/intro_3.html\n- Zsh options and invocation: https://zsh.sourceforge.io/Doc/Release/Invocation.html\n- OpenAI Codex: https://openai.com/codex/\n\n## Operational boundaries\n\n- `--dangerously-bypass-approvals-and-sandbox` is a high-trust launch choice, not required for environment-marker injection. The shown `env -u` check clears one guard, not the entire inherited environment.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-shell-environment-practice",
      "slug": "shell-environment-practice",
      "title": "Reliable non-interactive shell environments: practice drills",
      "summary": "Six exercises diagnose missing tools through non-interactive zsh startup, environment markers, PATH ordering, a bootstrap recheck, configuration placement, and function-versus-executable classification.",
      "category": "Tools",
      "tags": [
        "zsh",
        "environment",
        "path",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 1: Write A Missing Tool Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 2: Agent Env Snapshot",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 3: Number PATH",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 4: Clean-Shell Check",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 5: Place The Fix",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/02-loading-zsh-env-into-codex.md#Exercises: 02. Loading ZSH Env Into Codex/Exercise 6: Function Or Executable",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 464,
      "url": "/topics/codex-shell-environment-practice/",
      "markdownUrl": "/markdown/codex-shell-environment-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-environment-practice.json",
      "headings": [
        {
          "id": "exercise-1-write-a-missing-tool-prompt",
          "text": "Exercise 1: Write A Missing Tool Prompt",
          "level": 2
        },
        {
          "id": "exercise-2-agent-env-snapshot",
          "text": "Exercise 2: Agent Env Snapshot",
          "level": 2
        },
        {
          "id": "exercise-3-number-path",
          "text": "Exercise 3: Number PATH",
          "level": 2
        },
        {
          "id": "exercise-4-clean-shell-check",
          "text": "Exercise 4: Clean-Shell Check",
          "level": 2
        },
        {
          "id": "exercise-5-place-the-fix",
          "text": "Exercise 5: Place The Fix",
          "level": 2
        },
        {
          "id": "exercise-6-function-or-executable",
          "text": "Exercise 6: Function Or Executable",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Reliable non-interactive shell environments: practice drills\n\nThese exercises practice diagnosing agent shell visibility without turning the session into a full dotfiles audit.\n\n## Exercise 1: Write A Missing Tool Prompt\n\nWrite a prompt that asks an agent to diagnose one missing tool.\n\nTemplate:\n\n```text\nCodex cannot find `<tool>`, but it works in my terminal.\n\nInspect the non-interactive zsh startup path. Check `zsh -lc`, `ZDOTDIR`,\nthe agent-safe bootstrap, PATH order, and where the tool is installed. Do not\nprint secrets or full environment output. Tell me which file should change and\nhow to confirm it worked.\n```\n\n## Exercise 2: Agent Env Snapshot\n\nRun the confirmation shape for your machine:\n\n```bash\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\nWrite:\n\n```markdown\n# Agent Env Snapshot\n\n- shell shape:\n- ZDOTDIR:\n- marker:\n- tools found:\n- tools missing:\n- next action:\n```\n\n## Exercise 3: Number PATH\n\n```bash\nzsh -lc 'print -l ${(s/:/)PATH} | nl -ba | sed -n \"1,30p\"'\n```\n\nWrite:\n\n```markdown\n# PATH Notes\n\n- first project/toolchain path:\n- package manager path:\n- language runtime path:\n- Homebrew path:\n- suspicious entries:\n- what should move:\n```\n\n## Exercise 4: Clean-Shell Check\n\n```bash\nenv -u CODEX_AGENT_ENV_SOURCED zsh -lc 'echo CODEX_AGENT_ENV_SOURCED=${CODEX_AGENT_ENV_SOURCED:-}; echo ZDOTDIR=$ZDOTDIR; command -v codex bun pnpm cargo packx || true'\n```\n\nAnswer:\n\n```markdown\n# Clean-Shell Check\n\n- Did the marker become set again?\n- Did required tools resolve?\n- What changed compared to the normal check?\n- What does that imply?\n```\n\n## Exercise 5: Place The Fix\n\nFor each case, choose the right home:\n\n| Case | File Or Form |\n| --- | --- |\n| persistent PATH assembly for all shells | |\n| machine-local private path | |\n| prompt theme | |\n| keybinding | |\n| reusable command needed outside zsh | |\n| rich helper function for interactive work | |\n| safe agent bootstrap | |\n\nOptions:\n\n```text\n~/.config/zsh/conf.d/00-path.zsh\n~/.config/zsh/local.zsh\n~/.config/zsh/codex-env.zsh\n~/.config/zsh/.zshrc\nexecutable wrapper on PATH\nSection 3 zsh DSL\n```\n\n## Exercise 6: Function Or Executable\n\nRun:\n\n```bash\nzsh -lc 'for name in bun packx funclist fix agent_chain xfl; do echo \"--- $name ---\"; command -v \"$name\" 2>/dev/null || echo \"command -v: missing\"; whence -w \"$name\" 2>/dev/null || echo \"whence: missing\"; done'\n```\n\nClassify:\n\n```markdown\n# Function Versus Executable\n\n| name | executable / function / missing | Section 2 or Section 3? | why |\n| --- | --- | --- | --- |\n| bun | | | |\n| packx | | | |\n| funclist | | | |\n| fix | | | |\n| agent_chain | | | |\n| xfl | | | |\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-resources",
      "slug": "resources",
      "title": "Resource access and tool directory",
      "summary": "Catalogs public tools and documentation, bundled skills, shell helpers, command contracts, hook examples, evidence workflows, and unresolved setup topics.",
      "category": "Tools",
      "tags": [
        "resources",
        "downloads",
        "tools"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/README.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/README.md#Codex Power User Workshop: 2026-06-27",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/README.md#Codex Power User Workshop: 2026-06-27/Private Config Boundary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Published And Review Links",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Core Public Links",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Bundled Skills",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Zsh And Shell Materials",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Zsh Function Snippets",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Command-Line Tools And Concepts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Hook And Orchestrator Examples",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/RESOURCES.md#Workshop Resources/Open Follow-Up Areas",
        "src/routes/+page.svx#download-bundle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle.sha256"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 1309,
      "url": "/topics/codex-resources/",
      "markdownUrl": "/markdown/codex-resources.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-resources.json",
      "headings": [
        {
          "id": "download-the-portable-repository",
          "text": "Download the portable repository",
          "level": 2
        },
        {
          "id": "companion-links",
          "text": "Companion Links",
          "level": 2
        },
        {
          "id": "core-public-links",
          "text": "Core Public Links",
          "level": 2
        },
        {
          "id": "bundled-skills",
          "text": "Bundled Skills",
          "level": 2
        },
        {
          "id": "zsh-and-shell-materials",
          "text": "Zsh And Shell Materials",
          "level": 2
        },
        {
          "id": "zsh-function-snippets",
          "text": "Zsh Function Snippets",
          "level": 2
        },
        {
          "id": "command-line-tools-and-concepts",
          "text": "Command-Line Tools And Concepts",
          "level": 2
        },
        {
          "id": "hook-and-orchestrator-examples",
          "text": "Hook And Orchestrator Examples",
          "level": 2
        },
        {
          "id": "questions-that-still-need-evidence",
          "text": "Questions That Still Need Evidence",
          "level": 2
        },
        {
          "id": "private-config-boundary",
          "text": "Private Config Boundary",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Resource access and tool directory\n\nUse the portable repository for the examples, practice drills, shell snippets, and hook contracts. Review each command against the installed tool before running it.\n\n## Download the portable repository\n\n[Download the Git bundle](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle) · [SHA-256 checksum](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle.sha256)\n\n```bash\ncurl -fL -o workshop-resources.bundle https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle\ngit clone workshop-resources.bundle workshop-resources\n```\n\n[Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)\n\n## Companion Links\n\n| Resource | Use |\n| --- | --- |\n| [https://lapis-fossil-vsbc.here.now/](https://lapis-fossil-vsbc.here.now/) | Complete reference companion |\n| [https://hollow-onyx-ajww.here.now/](https://hollow-onyx-ajww.here.now/) | Related published companion |\n| [https://vowful-fable-32mh.here.now/](https://vowful-fable-32mh.here.now/) | Related published companion |\n\n\n## Core Public Links\n\n| Resource | URL |\n| --- | --- |\n| Oracle | [https://askoracle.sh/](https://askoracle.sh/) |\n| Oracle repo | [https://github.com/johnlindquist/oracle](https://github.com/johnlindquist/oracle) |\n| PackX package | [https://www.npmjs.com/package/packx](https://www.npmjs.com/package/packx) |\n| Pack README | [https://github.com/johnlindquist/pack#readme](https://github.com/johnlindquist/pack#readme) |\n| Codex Imps repo | [https://github.com/johnlindquist/codex-imps](https://github.com/johnlindquist/codex-imps) |\n| Gog CLI | [https://gogcli.sh/](https://gogcli.sh/) |\n| Inspiration Board variation example | [https://inspiration-board.pages.dev/variations/01-masonry-grid](https://inspiration-board.pages.dev/variations/01-masonry-grid) |\n| Codex hooks docs | [https://developers.openai.com/codex/hooks](https://developers.openai.com/codex/hooks) |\n| Codex app-server source | [https://github.com/openai/codex/tree/main/codex-rs/app-server](https://github.com/openai/codex/tree/main/codex-rs/app-server) |\n| Prompt Builder repo | [https://github.com/johnlindquist/prompt-builder](https://github.com/johnlindquist/prompt-builder) |\n| Local Fusion repo | [https://github.com/johnlindquist/fusion](https://github.com/johnlindquist/fusion) |\n| OpenRouter Fusion product | [https://openrouter.ai/fusion](https://openrouter.ai/fusion) |\n| OpenRouter Fusion model page | [https://openrouter.ai/openrouter/fusion](https://openrouter.ai/openrouter/fusion) |\n| OpenRouter Fusion announcement | [https://openrouter.ai/blog/announcements/fusion-beats-frontier/](https://openrouter.ai/blog/announcements/fusion-beats-frontier/) |\n| OpenRouter model fallback article | [https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/](https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/) |\n| Agent Markers repo | [https://github.com/johnlindquist/agent-markers](https://github.com/johnlindquist/agent-markers) |\n| Gemini app | [https://gemini.google.com/app](https://gemini.google.com/app) |\n| Cypress docs | [https://docs.cypress.io/](https://docs.cypress.io/) |\n| Playwright test assertions | [https://playwright.dev/docs/test-assertions](https://playwright.dev/docs/test-assertions) |\n| here.now docs | [https://here.now/docs](https://here.now/docs) |\n| Tailscale Funnel docs | [https://tailscale.com/kb/1223/funnel](https://tailscale.com/kb/1223/funnel) |\n| Bun | [https://bun.sh/](https://bun.sh/) |\n| jq | [https://jqlang.github.io/jq/](https://jqlang.github.io/jq/) |\n| Homebrew | [https://brew.sh/](https://brew.sh/) |\n| Script Kit | [https://scriptkit.com/](https://scriptkit.com/) |\n| Zsh builtins manual | [https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html](https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html) |\n| Zsh functions manual | [https://zsh.sourceforge.io/Doc/Release/Functions.html](https://zsh.sourceforge.io/Doc/Release/Functions.html) |\n| Zsh startup overview | [https://zsh.sourceforge.io/Intro/intro_3.html](https://zsh.sourceforge.io/Intro/intro_3.html) |\n| Zsh invocation manual | [https://zsh.sourceforge.io/Doc/Release/Invocation.html](https://zsh.sourceforge.io/Doc/Release/Invocation.html) |\n| tmux manual | [https://man7.org/linux/man-pages/man1/tmux.1.html](https://man7.org/linux/man-pages/man1/tmux.1.html) |\n| tmux wiki | [https://github.com/tmux/tmux/wiki](https://github.com/tmux/tmux/wiki) |\n| Model Context Protocol | [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/) |\n| OpenAI Codex | [https://openai.com/codex/](https://openai.com/codex/) |\n| yt-dlp | [https://github.com/yt-dlp/yt-dlp](https://github.com/yt-dlp/yt-dlp) |\n| FFmpeg docs | [https://ffmpeg.org/documentation.html](https://ffmpeg.org/documentation.html) |\n| ffprobe docs | [https://ffmpeg.org/ffprobe.html](https://ffmpeg.org/ffprobe.html) |\n\n\n## Bundled Skills\n\n| Skill | Bundled Path | What To Ask For |\n| --- | --- | --- |\n| Oracle PackX | `skills/oracle-packx/SKILL.md` | Bundle relevant repo context with PackX, send it to Oracle, and turn the result into an implementation plan or review |\n| Oracle PackX references | `skills/oracle-packx/references/` | Quick and deep PackX reference material |\n| Oracle Video | `skills/oracle-video/SKILL.md` | Analyze a recording or walkthrough through Gemini browser mode and produce evidence-backed follow-up material |\n| Oracle Video process | `skills/oracle-video/references/repeatable-video-followup-process.md` | Repeatable video follow-up workflow with source hashes, probes, transcript evidence, and omissions pass |\n| Fusion | `skills/fusion/SKILL.md` | Run a local model council, wait for `summary.json` and `final.md`, then treat the council output as advisory |\n| Web Choices | `skills/web-choices/SKILL.md` | Present generated options in a small review UI, collect structured feedback, and resume from saved JSON |\n\n\n## Zsh And Shell Materials\n\n| Path | Use |\n| --- | --- |\n| `zsh/README.md` | Overview of the agent-safe zsh startup files and checks |\n| `zsh/.zshenv` | XDG `ZDOTDIR` bootstrap example |\n| `zsh/.zprofile` | Login-shell bridge for `zsh -lc` |\n| `zsh/codex-env.zsh` | Agent-safe non-interactive shell bootstrap example |\n| `zsh/conf.d/00-path.zsh` | Deterministic PATH assembly example |\n| `zsh/conf.d/40-ai.zsh` | Small workshop loader for the focused function snippets |\n| `zsh/conf.d/47-ai-fix.zsh` | Fusion-first `fix` helper example |\n| `zsh/examples/local.zsh.example` | Public shape for machine-local overrides |\n| `zsh/examples/codex-config-shell-environment-policy.toml` | Example `shell_environment_policy.set.CODEX_LOAD_ZSH_DSL` launch configuration |\n| `zsh/tests/startup-regression.zsh` | Startup regression checks |\n\n\n## Zsh Function Snippets\n\nThese snippets copy the named helper functions discussed in the workshop without copying whole private shell files.\n\n| Snippet | Helpers Included |\n| --- | --- |\n| `zsh/functions/codex-launch-and-prompt-builder.zsh` | `x`, `xi`, `xfl`, `xfc`, `_codex_cmux_current_session_id`, `_codex_cmux_name_current_tab`, `_codex_prompt_builder_fork`, `_p_handoff_zsh`, `p-f`, `p-c`, `p-cm`, guarded app-server helper stubs |\n| `zsh/functions/shell-introspection.zsh` | `funclist`, `funcwhere`, `funced` |\n| `zsh/functions/fusion-fix.zsh` | `fix` |\n| `zsh/functions/orchestration-helpers.zsh` | `muxai`, lazy-loader shapes for `agent_chain`, `ghost-save`, and `aicm` |\n| `zsh/functions/script-kit-process-helpers.zsh` | `pksk`, `ksk` |\n\n\n## Command-Line Tools And Concepts\n\n| Tool Or Concept | Where It Appears |\n| --- | --- |\n| `zsh -lc` | Section 2 and Section 3 shell startup checks |\n| `shell_environment_policy.set` | Section 2 Codex environment injection |\n| `CODEX_LOAD_ZSH_DSL` | Local marker used to opt into selected zsh DSL loading |\n| `prompt-builder` / `p` | Section 5 prompt composition and handoff |\n| `--dry-run`, `--print-command`, `--print-prompt`, `--print-launch-json` | Prompt Builder preview and non-destructive checks |\n| `--submit`, `--stdin`, `--name`, `--instructions`, `--developer-instructions` | Prompt Builder launch and prompt-shaping modes |\n| `--handoff-command`, `--handoff-arg`, `--fork-from`, `--compact` | Prompt Builder handoff modes for zsh/Codex workflows |\n| `CODEX_THREAD_NAME` | Prompt Builder and cmux tab naming helpers |\n| `p-f`, `p-c`, `p-cm` | Prompt Builder handoff helpers |\n| `xfl`, `xfc` | Codex fork and compact fork helpers |\n| `cmux` | Addressable workspace, pane, surface, and process routing |\n| `cmux identify`, `cmux rpc workspace.current`, `cmux top`, `cmux read-screen`, `cmux focus-pane` | cmux state inspection and routed session follow-up |\n| `cmux-run-surface`, `cmux-fork-focused-codex`, `cmux-xport` | Local helper surface for pane launch, focused Codex fork, and transcript export |\n| `tmux` | Terminal multiplexer comparison and fallback mental model |\n| `muxai` | Quick tmux pane fan-out example |\n| `agent_chain` | Gated multi-agent work-unit helper pattern |\n| `imp`, `imps`, `imp-rg` | Isolated tool-agent commands |\n| `imp -l`, `imps list`, `imps ps`, `imps doctor`, `imp --which` | Imp discovery, health, and routing checks |\n| `imp --run`, `imp -q`, `imp --no-warm`, `imp --serve`, `imp --effort` | Imp direct-run, quiet, warm-runtime, server, and effort controls |\n| `-<imp>` / `--<imp>` | Foreground route vs forked cmux route in the hook examples |\n| `ffprobe` | Video metadata and verification probe |\n| `yt-dlp` | Video metadata/download helper |\n| `createAgentMarkers` | Browser debugging marker client |\n| `DebugSession`, `DebugMoment`, `CapturedEvent`, `nearbyEventIds` | Agent Markers export schema concepts |\n| `mark`, `event`, `export`, `download`, `clear`, `stop`, `onMarker` | Agent Markers client methods |\n| `window.__AGENT_MARKERS__` | Test-runner export surface for Agent Markers |\n| `fusion`, `fusion-med`, `fusion-high` | Local model-council CLI presets |\n| `summary.json`, `final.md`, `panel-*.stdout.md`, `panel-status.json` | Fusion session artifacts to wait for and inspect |\n| `browserAttachments: \"always\"`, `gemini-3-pro`, `END_OF_VIDEO_ANALYSIS` | Oracle Video browser-upload contract terms |\n| source hash, `ffprobe`, transcript, keyframes/contact sheet, omissions pass | Oracle Video evidence lanes |\n| `tailscale funnel`, `.ts.net`, `.token` | Web Choices phone-review tunnel and token-gated URL flow |\n| `bun`, `jq`, `brew` | Common local tooling for the Svelte/mdsvex choice app and JSON checks |\n| Script Kit, `pksk`, `ksk` | Script Kit process cleanup helpers mentioned in zsh examples |\n\n\n## Hook And Orchestrator Examples\n\n| Path | Use |\n| --- | --- |\n| `hooks/README.md` | Dash-prefix Imp hook setup and verification |\n| `hooks/hooks.json.example` | Minimal Codex hook registration example |\n| `hooks/imp-user-prompt-submit.py.template` | `UserPromptSubmit` hook template for foreground and forked Imp routing |\n| `hooks/cmux-run-surface.example` | cmux pane-launch helper contract |\n| `hooks/cmux-codex-session-registry.py.example` | Redacted contract for resolving a cmux surface to a Codex session id |\n\n\n## Questions That Still Need Evidence\n\nReview these questions before turning them into setup claims:\n\n- AI-ready repository setup patterns for long-running AFK work\n- Password-manager account/profile separation\n- Current Codex Imps setup and public README coverage\n- Reusable workspace layouts\n- Newsletter, people, book, and podcast recommendations\n- Public skill evaluation and personalization\n- Hiring traits, AI fatigue, and ethics framing\n\n## Private Config Boundary\n\nSome local config is intentionally not copied verbatim:\n\n- `~/.config/zsh/local.zsh`\n- full `~/.codex/config.toml`\n- files that contain provider-specific key helpers or secret wiring\n- Fusion session artifacts under `~/.fusion/sessions/**`, which may contain prompts, source snippets, commands, stdout, stderr, and model responses\n\nUse the examples under `zsh/examples/` for the public shape.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)"
    },
    {
      "id": "factory-shared-resources",
      "slug": "shared-resources",
      "title": "Resources shared in the software-factory discussion",
      "summary": "Direct public links with their intended role, including source repositories, visual tools, context search, and research artifacts.",
      "category": "Tools",
      "tags": [
        "resources",
        "links"
      ],
      "sources": [
        {
          "label": "Software factory resources",
          "url": "https://proud-anchor-53zn.here.now/resources.html"
        }
      ],
      "sourceUnits": [
        "resources.html#shared-links",
        "watch.html#recording-and-supplemental-links"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1039,
      "url": "/topics/factory-shared-resources/",
      "markdownUrl": "/markdown/factory-shared-resources.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-shared-resources.json",
      "headings": [
        {
          "id": "links-shared-during-the-workshop",
          "text": "Links shared during the workshop",
          "level": 2
        },
        {
          "id": "workshop-agenda-https-ember-bodhi-scrr-here-now",
          "text": "[Workshop agenda](https://ember-bodhi-scrr.here.now/)",
          "level": 3
        },
        {
          "id": "coding-with-agents-field-guide-https-kindly-mirage-ejqd-here-now",
          "text": "[Coding with Agents field guide](https://kindly-mirage-ejqd.here.now/)",
          "level": 3
        },
        {
          "id": "cursor-origin-https-cursor-com-origin",
          "text": "[Cursor Origin](https://cursor.com/origin)",
          "level": 3
        },
        {
          "id": "screenpipe-https-screenpipe-com",
          "text": "[Screenpipe](https://screenpipe.com/)",
          "level": 3
        },
        {
          "id": "pieces-https-pieces-app",
          "text": "[Pieces](https://pieces.app/)",
          "level": 3
        },
        {
          "id": "flow-text-source-https-github-com-johnlindquist-flow-text",
          "text": "[Flow Text source](https://github.com/johnlindquist/flow-text/)",
          "level": 3
        },
        {
          "id": "mini-arcade-https-miniarcade-dev",
          "text": "[Mini Arcade](https://miniarcade.dev/)",
          "level": 3
        },
        {
          "id": "mini-arcade-source-https-github-com-johnlindquist-miniarcade",
          "text": "[Mini Arcade source](https://github.com/johnlindquist/miniarcade)",
          "level": 3
        },
        {
          "id": "herdr-https-herdr-dev",
          "text": "[Herdr](https://herdr.dev)",
          "level": 3
        },
        {
          "id": "linear-https-linear-app",
          "text": "[Linear](https://linear.app/)",
          "level": 3
        },
        {
          "id": "claudex-https-github-com-johnlindquist-claudex",
          "text": "[Claudex](https://github.com/johnlindquist/claudex)",
          "level": 3
        },
        {
          "id": "cloudflare-ai-code-review-https-blog-cloudflare-com-ai-code-review",
          "text": "[Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/)",
          "level": 3
        },
        {
          "id": "flameshot-https-flameshot-org",
          "text": "[Flameshot](https://flameshot.org/)",
          "level": 3
        },
        {
          "id": "shottr-https-shottr-cc",
          "text": "[Shottr](https://shottr.cc/)",
          "level": 3
        },
        {
          "id": "prompt-builder-source-https-github-com-johnlindquist-prompt-builder",
          "text": "[Prompt Builder source](https://github.com/johnlindquist/prompt-builder)",
          "level": 3
        },
        {
          "id": "gog-cli-https-gogcli-sh",
          "text": "[gog CLI](https://gogcli.sh/)",
          "level": 3
        },
        {
          "id": "birdclaw-https-birdclaw-sh",
          "text": "[Birdclaw](https://birdclaw.sh/)",
          "level": 3
        },
        {
          "id": "codegraph-https-colbymchenry-github-io-codegraph",
          "text": "[CodeGraph](https://colbymchenry.github.io/codegraph/)",
          "level": 3
        },
        {
          "id": "atuin-https-atuin-sh",
          "text": "[Atuin](https://atuin.sh/)",
          "level": 3
        },
        {
          "id": "cass-skill-https-jeffreys-skills-md-skills-cass",
          "text": "[CASS skill](https://jeffreys-skills.md/skills/cass)",
          "level": 3
        },
        {
          "id": "coding-agent-session-search-https-github-com-dicklesworthstone-coding-agent-session-search",
          "text": "[Coding Agent Session Search](https://github.com/Dicklesworthstone/coding_agent_session_search)",
          "level": 3
        },
        {
          "id": "inspiration-board-https-inspiration-board-pages-dev",
          "text": "[Inspiration Board](https://inspiration-board.pages.dev/)",
          "level": 3
        },
        {
          "id": "impeccable-https-impeccable-style",
          "text": "[Impeccable](https://impeccable.style/)",
          "level": 3
        },
        {
          "id": "matt-pocock-s-skills-https-github-com-mattpocock-skills-tree-main",
          "text": "[Matt Pocock’s skills](https://github.com/mattpocock/skills/tree/main)",
          "level": 3
        },
        {
          "id": "oracle-https-github-com-steipete-oracle",
          "text": "[Oracle](https://github.com/steipete/oracle)",
          "level": 3
        },
        {
          "id": "video-analysis-companion-https-silken-ferry-63mw-here-now",
          "text": "[Video analysis companion](https://silken-ferry-63mw.here.now/)",
          "level": 3
        },
        {
          "id": "google-ai-studio-live-https-aistudio-google-com-live-model-gemini-3-1-flash-live-preview",
          "text": "[Google AI Studio Live](https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview)",
          "level": 3
        },
        {
          "id": "workshop-notebooklm-notebook-https-notebooklm-google-com-notebook-4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7",
          "text": "[Workshop NotebookLM notebook](https://notebooklm.google.com/notebook/4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7)",
          "level": 3
        },
        {
          "id": "handy-https-handy-computer",
          "text": "[Handy](https://handy.computer/)",
          "level": 3
        },
        {
          "id": "recording-and-additional-published-research",
          "text": "Recording and additional published research",
          "level": 2
        }
      ],
      "markdown": "# Resources shared in the software-factory discussion\n\nDirect public links with their intended role, including source repositories, visual tools, context search, and research artifacts.\n\n## Links shared during the workshop\n\n**Every exact chat URL** has a useful name, a reason to open it, its related lesson, and dated reachability status.\n\nShared at 00:13:52 · Bound one factory loop\n\n### [Workshop agenda](https://ember-bodhi-scrr.here.now/)\n\nThe original workshop sequence and setup hub.\n\n**Use when:** Use this to compare the companion with the planned agenda.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable\n\nShared at 00:17:38 · Bound one factory loop\n\n### [Coding with Agents field guide](https://kindly-mirage-ejqd.here.now/)\n\nThe earlier field guide that grounded the workshop’s operating principles.\n\n**Use when:** Use this for the longer foundational argument.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable\n\nShared at 00:29:50 · Bound one factory loop\n\n### [Cursor Origin](https://cursor.com/origin)\n\nAn autonomous coding-agent product discussed during the opening model survey.\n\n**Use when:** Use this as an example of agent products moving toward longer-running work.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-factory-loop)Reachable\n\nShared at 00:45:07 · Recover state before continuing\n\n### [Screenpipe](https://screenpipe.com/)\n\nLocal activity capture for searchable work context.\n\n**Use when:** Compare approaches to recovering prior work from durable traces.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable\n\nShared at 00:45:47 · Recover state before continuing\n\n### [Pieces](https://pieces.app/)\n\nA developer work-memory and context product.\n\n**Use when:** Compare local continuity and retrieval approaches.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable\n\nShared at 00:54:12 · Turn good prompts into inspectable flows\n\n### [Flow Text source](https://github.com/johnlindquist/flow-text/)\n\nA repository for a reusable text-flow experiment.\n\n**Use when:** Inspect a concrete prompt-to-flow implementation.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable\n\nShared at 01:05:41 · Diverge first, then record taste\n\n### [Mini Arcade](https://miniarcade.dev/)\n\nA generated product used as a design and implementation example.\n\n**Use when:** See the result before inspecting its source repository.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable\n\nShared at 01:06:00 · Diverge first, then record taste\n\n### [Mini Arcade source](https://github.com/johnlindquist/miniarcade)\n\nThe source repository behind the product example.\n\n**Use when:** Compare generated experience with inspectable implementation.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable\n\nShared at 01:10:34 · Keep wrappers thin and work visible\n\n### [Herdr](https://herdr.dev)\n\nA workspace surface for seeing parallel agent activity.\n\n**Use when:** Use this when designing visible execution, verification, and status lanes.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Not rechecked\n\nShared at 01:21:06 · Keep wrappers thin and work visible\n\n### [Linear](https://linear.app/)\n\nIssue and project tracking referenced during workflow discussion.\n\n**Use when:** Use this when connecting agent work to an existing task system.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable\n\nShared at 01:27:13 · Keep wrappers thin and work visible\n\n### [Claudex](https://github.com/johnlindquist/claudex)\n\nA proxy and launcher experiment for coding-agent sessions.\n\n**Use when:** Inspect one approach to normalizing launch behavior.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable\n\nShared at 01:42:40 · Keep wrappers thin and work visible\n\n### [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/)\n\nA published account of AI-assisted review at production scale.\n\n**Use when:** Use this as external context for evidence-first review workflows.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces)Reachable\n\nShared at 02:16:45 · Point at the visual problem\n\n### [Flameshot](https://flameshot.org/)\n\nCross-platform screenshot and annotation tooling.\n\n**Use when:** Use this to create annotated visual prompts.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt)Reachable\n\nShared at 02:17:04 · Point at the visual problem\n\n### [Shottr](https://shottr.cc/)\n\nA macOS screenshot and annotation tool.\n\n**Use when:** Use this to point directly at a visual defect.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-annotated-image-prompt)Reachable\n\nShared at 02:35:02 · Compose only the evidence the task needs\n\n### [Prompt Builder source](https://github.com/johnlindquist/prompt-builder)\n\nThe repository for composing text, files, and other evidence into prompts.\n\n**Use when:** Inspect or adapt the prompt-composition workflow.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer)Reachable\n\nShared at 03:04:12 · Turn good prompts into inspectable flows\n\n### [gog CLI](https://gogcli.sh/)\n\nA command-line surface for Google services.\n\n**Use when:** Use this as an example of piping external system context into a flow.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable\n\nShared at 03:09:32 · Turn good prompts into inspectable flows\n\n### [Birdclaw](https://birdclaw.sh/)\n\nA command-line social workflow tool.\n\n**Use when:** Use this as another example of a tool that can feed a reusable flow.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable\n\nShared at 03:33:17 · Turn good prompts into inspectable flows\n\n### [CodeGraph](https://colbymchenry.github.io/codegraph/)\n\nA visual code-relationship explorer shown during workflow experiments.\n\n**Use when:** Use it for orientation; do not treat the workshop as proof of token savings.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q2-markdown-flows)Reachable\n\nShared at 04:22:08 · Recover state before continuing\n\n### [Atuin](https://atuin.sh/)\n\nSearchable shell history across sessions and machines.\n\n**Use when:** Use this to locate the command that produced a durable artifact.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable\n\nShared at 04:40:50 · Recover state before continuing\n\n### [CASS skill](https://jeffreys-skills.md/skills/cass)\n\nA skill interface for coding-agent session search.\n\n**Use when:** Use this when recovering a decision from prior agent conversations.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable\n\nShared at 04:41:16 · Recover state before continuing\n\n### [Coding Agent Session Search](https://github.com/Dicklesworthstone/coding_agent_session_search)\n\nThe source repository behind CASS.\n\n**Use when:** Inspect the underlying conversation-search implementation.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-continuity-recover)Reachable\n\nShared at 04:44:28 · Diverge first, then record taste\n\n### [Inspiration Board](https://inspiration-board.pages.dev/)\n\nA board for collecting and comparing visual references.\n\n**Use when:** Use it to anchor variation work in visible references.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable\n\nShared at 04:56:44 · Diverge first, then record taste\n\n### [Impeccable](https://impeccable.style/)\n\nDesign guidance and reusable taste constraints for agents.\n\n**Use when:** Use it when turning preferences into a durable design contract.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable\n\nShared at 05:04:29 · Diverge first, then record taste\n\n### [Matt Pocock’s skills](https://github.com/mattpocock/skills/tree/main)\n\nA public collection of agent skills referenced during preference work.\n\n**Use when:** Browse examples of packaged instructions and workflows.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-variations-taste)Reachable\n\nShared at 05:06:47 · Escalate the decision, not the workflow\n\n### [Oracle](https://github.com/steipete/oracle)\n\nA repository-context bundler and browser consult workflow.\n\n**Use when:** Use this when an independent reasoning path can change a costly decision.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable\n\nShared at 05:19:22 · Escalate the decision, not the workflow\n\n### [Video analysis companion](https://silken-ferry-63mw.here.now/)\n\nThe prepared companion for video-assisted analysis.\n\n**Use when:** Use this when timing or transient screen behavior matters.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable\n\nShared at 05:24:09 · Escalate the decision, not the workflow\n\n### [Google AI Studio Live](https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview)\n\nA live multimodal model surface shared during the video discussion.\n\n**Use when:** Use only after verifying current availability and account requirements.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q3-max-intelligence)Reachable\n\nShared at 05:26:41 · Let vision guide automation\n\n### [Workshop NotebookLM notebook](https://notebooklm.google.com/notebook/4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7)\n\nThe research notebook and generated artifacts shown near the close.\n\n**Use when:** Use generated artifacts as navigation, then trace consequential claims to sources.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation)Reachable\n\nShared at 05:40:36 · Let vision guide automation\n\n### [Handy](https://handy.computer/)\n\nA dictation tool shared during the VISION.md discussion.\n\n**Use when:** Use voice input when speaking product direction is faster than typing it.\n\n[Related lesson](https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation)Reachable\n\n## Recording and additional published research\n\n- [Complete recording](https://www.dropbox.com/scl/fi/yg917eiyfrbmzqfh8jjdy/GMT20260717-155525_Recording_gallery_1920x1080.mp4?rlkey=ddjr30qey89fo41pw9xqrtwhm&st=346uon0v&dl=0)\n- [Recording chapter navigator](https://proud-anchor-53zn.here.now/watch.html)\n- [John's Zsh Configuration](https://gist.github.com/johnlindquist/7fe11a156ac483a83f083112bf54fcb8)\n- [Comprehensive ZSH configuration with AI integrations and development tools](https://gist.github.com/johnlindquist/f8911bff4aabc3e3e68beb6665cdb4a5)"
    },
    {
      "id": "factory-tools-screenshot-annotation",
      "slug": "tools-screenshot-annotation",
      "title": "Screenshot capture & annotation (CleanShot X)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "screenshot-annotation"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#screenshot-annotation"
        }
      ],
      "sourceUnits": [
        "resources/index.html#screenshot-annotation"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 297,
      "url": "/topics/factory-tools-screenshot-annotation/",
      "markdownUrl": "/markdown/factory-tools-screenshot-annotation.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-screenshot-annotation.json",
      "headings": [
        {
          "id": "screenshot-capture-annotation-cleanshot-x",
          "text": "Screenshot capture & annotation (CleanShot X)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Screenshot capture & annotation (CleanShot X)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Screenshot capture & annotation (CleanShot X)\n\n**John uses:** [CleanShot X](https://cleanshot.com/) (commercial, macOS) for section 03's whole workflow: hotkey capture → draw a fat red arrow or type the instruction **on** the screenshot → drag into the agent prompt. The annotation is the prompt.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [Shottr](https://shottr.cc/) | Fast, lightweight macOS screenshot tool: annotate, scrolling capture, OCR, ruler, color picker | Pay-what-you-want (from ~\\$8); no screen recording or cloud; the standard CleanShot substitute for the arrow workflow | freeware/paid (closed source) |\n| [Flameshot](https://github.com/flameshot-org/flameshot) | Cross-platform OSS screenshot software with in-place arrow/text annotation | Free and cross-platform (Linux/Win/mac); annotation UI is the core feature | GPL-3.0 |\n| [ksnip](https://github.com/ksnip/ksnip) | Cross-platform screenshot and annotation tool (Qt) | OSS with rich annotation (arrows, numbering, blur); less polished than CleanShot | GPL-3.0 |\n| [macOS built-in Screenshot + Preview markup](https://support.apple.com/guide/mac-help/take-screenshots-or-screen-recordings-mh26782/mac) | Cmd+Shift+5 capture, then Markup arrows in Preview/Quick Look | Zero install; slower loop (no capture-annotate-drag single flow) | OS built-in |\n| [Kap](https://github.com/wulkano/Kap) | OSS macOS screen recorder (GIF/MP4) | Covers the recording half only; effectively unmaintained (check repository activity before adoption) — verify before adopting | MIT |\n\n### Pick this if…\n\n- **Shottr** — you're on a Mac and want 90% of CleanShot for pay-what-you-want (no recording/cloud).\n- **Flameshot** — you're on Linux/Windows or want it free and open; annotation UI is the core feature.\n- **ksnip** — you want OSS with the richest annotation toolset.\n- **built-in Markup** — you can't install anything; the loop is just slower.\n- **Kap** — only if you need OSS recording and accept a dormant project (last push the example workflow)."
    },
    {
      "id": "factory-tools-secrets",
      "slug": "tools-secrets",
      "title": "Secrets for unsupervised agents (1Password op)",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "secrets"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#secrets"
        }
      ],
      "sourceUnits": [
        "resources/index.html#secrets"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 309,
      "url": "/topics/factory-tools-secrets/",
      "markdownUrl": "/markdown/factory-tools-secrets.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-secrets.json",
      "headings": [
        {
          "id": "secrets-for-unsupervised-agents-1password-op",
          "text": "Secrets for unsupervised agents (1Password op)",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Secrets for unsupervised agents (1Password op)\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Secrets for unsupervised agents (1Password op)\n\n**John uses:** the [1Password `op` CLI](https://developer.1password.com/docs/cli/) (commercial). AGENDA directive \\#10: agents are safe to run unsupervised **if** secrets live in a vault and get injected per-command (`op run` / `op read`) instead of sitting in `.env` files any agent can read or leak.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [Bitwarden CLI (bw)](https://github.com/bitwarden/clients) | CLI for the Bitwarden password manager (open clients, optional self-host via vaultwarden) | Open-source clients and self-hosting; scripting ergonomics rougher than op run | NOASSERTION (GPL/Bitwarden License mix) |\n| [Infisical](https://github.com/Infisical/infisical) | Open-source platform for secrets, certificates, and privileged access; CLI injects env vars | Team/infra-grade secret management with \\`infisical run\\` (the closest op-run analog); self-hostable | NOASSERTION (MIT + enterprise dirs) |\n| [Doppler CLI](https://github.com/DopplerHQ/cli) | Official CLI for Doppler secrets/config: \\`doppler run -- cmd\\` injects secrets as env vars | SaaS-hosted; the smoothest run-with-secrets DX after op | Apache-2.0 |\n| [sops](https://github.com/getsops/sops) | Encrypt secrets inside files in your repo (age/KMS/PGP), decrypt on use | Secrets live encrypted next to code — no vault service at all | MPL-2.0 |\n| [pass](https://www.passwordstore.org/) + [age](https://github.com/FiloSottile/age) | The UNIX password store (GPG) and the modern simple file-encryption tool | Fully local/offline, scriptable, zero SaaS; you assemble the workflow yourself | GPL-2.0 (pass) / BSD-3-Clause (age) |\n\n### Pick this if…\n\n- **Infisical** — you want the closest open `op run` experience and can self-host.\n- **Doppler** — you want the smoothest SaaS run-with-secrets DX.\n- **Bitwarden** — you already use it as a password manager; the CLI comes along.\n- **sops (+age)** — you want secrets versioned encrypted next to code, no vault service.\n- **pass + age** — you want fully local, scriptable, zero-SaaS."
    },
    {
      "id": "codex-shell-functions-reference",
      "slug": "shell-functions-reference",
      "title": "Shell functions, aliases, and executable boundaries: practical reference",
      "summary": "Zsh helper diagnosis and agent integration reference covering a ten-step setup prompt, command classification, alias/function/executable design, interactive versus login-shell loading, argument-safe handoffs, executable wrappers, source guards, helper…",
      "category": "Tools",
      "tags": [
        "zsh",
        "helpers",
        "cli"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Try This Now",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/The Six Buckets",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Alias Or Function",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/When An Executable Wrapper Is Required",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Function DSL Source Guard Trap",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Discover Helpers",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Confirm What A Name Really Is",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Helper Families",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/`command not found`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Alias Fails In A Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Quoting Breaks Arguments",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/If It Goes Wrong/Lazy Stub Looks Like The Source",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/03-zsh-functions-aliases.md#03. ZSH Functions / Aliases/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 3080,
      "url": "/topics/codex-shell-functions-reference/",
      "markdownUrl": "/markdown/codex-shell-functions-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-functions-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "try-this-now",
          "text": "Try This Now",
          "level": 2
        },
        {
          "id": "files-to-inspect",
          "text": "Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "the-six-buckets",
          "text": "The Six Buckets",
          "level": 2
        },
        {
          "id": "alias-or-function",
          "text": "Alias Or Function",
          "level": 2
        },
        {
          "id": "when-an-executable-wrapper-is-required",
          "text": "When An Executable Wrapper Is Required",
          "level": 2
        },
        {
          "id": "function-dsl-source-guard-trap",
          "text": "Function DSL Source Guard Trap",
          "level": 2
        },
        {
          "id": "discover-helpers",
          "text": "Discover Helpers",
          "level": 2
        },
        {
          "id": "confirm-what-a-name-really-is",
          "text": "Confirm What A Name Really Is",
          "level": 2
        },
        {
          "id": "helper-families",
          "text": "Helper Families",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "command-not-found",
          "text": "`command not found`",
          "level": 3
        },
        {
          "id": "alias-fails-in-a-script",
          "text": "Alias Fails In A Script",
          "level": 3
        },
        {
          "id": "quoting-breaks-arguments",
          "text": "Quoting Breaks Arguments",
          "level": 3
        },
        {
          "id": "lazy-stub-looks-like-the-source",
          "text": "Lazy Stub Looks Like The Source",
          "level": 3
        },
        {
          "id": "how-to-know-it-worked",
          "text": "How To Know It Worked",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Shell functions, aliases, and executable boundaries: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the zsh helper files and configuration so local agents, scripts, and non-interactive shells can reliably use the important helpers on this page.\n\nStep 1: Inspect the helper files before changing anything.\nCheck these project files first:\n\n  ls -l zsh/conf.d/40-ai.zsh zsh/conf.d/47-ai-fix.zsh zsh/codex-env.zsh 2>/dev/null || true\n  ls -l zsh/tests/startup-regression.zsh 2>/dev/null || true\n\nUse `zsh/conf.d/40-ai.zsh` for small agent-safe helper definitions, `zsh/conf.d/47-ai-fix.zsh` for the fix workflow, and `zsh/codex-env.zsh` for safe PATH/env setup. If a required file is missing, create the smallest file needed from public examples in this package. Do not copy private local config, secret helper files, full Codex config, token/API-key wiring, cookies, private endpoints, or raw `env` output.\n\nStep 2: Identify the helper names this setup needs.\nStart with helpers already defined in the files above, plus any important workflow names such as:\n\n  x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist\n\nAdjust the list to match the actual files. Do not invent helpers that are not needed.\n\nStep 3: Classify each helper as alias, function, builtin, hashed command, executable, or missing.\nRun the quick pass:\n\n  for name in x e xfl xfc xport fix cfix ghost-save aicm pksk ksk p-f p-c p-cm muxai agent_chain funcwhere funced funclist; do\n    printf '%-14s ' \"$name\"\n    whence -w \"$name\" 2>/dev/null || echo MISSING\n  done\n\nThen run the detailed pass for each important helper:\n\n  whence -w <name> 2>/dev/null || true\n  type <name> 2>/dev/null || true\n  alias <name> 2>/dev/null || true\n  functions <name> 2>/dev/null | sed -n '1,80p'\n  command -v <name> 2>/dev/null || true\n  whence -p <name> 2>/dev/null || true\n\nLocate the defining file with `funcwhere <name> 2>/dev/null || grep -RIn \"<name>()\\|function <name>\\|alias <name>=\" zsh/conf.d zsh 2>/dev/null || true`.\n\nStep 4: Compare interactive zsh with non-interactive agent zsh.\nRemember that `zsh -lc` is login, but not interactive. Check both surfaces:\n\n  zsh -ic 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true'\n  CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name> 2>/dev/null || true; type <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; whence -p <name> 2>/dev/null || true'\n\nTreat `CODEX_LOAD_ZSH_DSL` as a local opt-in marker, not a built-in Codex feature. If Codex should provide it, configure the launch path with `shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"`.\n\nStep 5: Set up selected helper loading for `zsh -lc`.\nKeep `.zshrc`-only behavior out of the required agent path. Source only the narrow files needed for the helper. For shell-only helpers, use this handoff shape and preserve arguments through `\"$@\"`:\n\n  zsh -lc 'source \"$PWD/zsh/codex-env.zsh\" >/dev/null 2>&1; source \"$PWD/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n\nIf the installed source path is different, replace the source path with the inspected file path. Do not interpolate user input inside the single-quoted `zsh -lc` body.\n\nStep 6: Fix source guards for function files.\nFunction and alias files must not use exported source guards that child shells inherit while losing the functions. If a function DSL file uses an exported guard, replace it with a non-exported guard or make the file safe to source repeatedly. Env/path-only files may use exported guards when appropriate.\n\nStep 7: Create executable fallbacks only for helpers that need them.\nUse wrappers when CI, scripts, tmux, Prompt Builder, or another non-zsh caller must execute a helper by name without sourcing shell files.\n\nWrapper shape:\n\n  mkdir -p \"$HOME/.local/bin\"\n  cat > \"$HOME/.local/bin/<name>\" <<'EOF'\n#!/usr/bin/env zsh\nset -e\nsource \"$HOME/.config/zsh/codex-env.zsh\" >/dev/null 2>&1 || true\nsource \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1\n<name> \"$@\"\nEOF\n  chmod +x \"$HOME/.local/bin/<name>\"\n\nAdjust source paths to the real installed helper files. If the wrapper can call a real binary directly, use `exec /path/to/binary \"$@\"` instead. Avoid wrapper recursion: prove the wrapper calls the intended function or executable.\n\nStep 8: Verify PATH and wrapper resolution.\nFor every executable fallback:\n\n  command -v <name>\n  whence -p <name>\n  test -x \"$(command -v <name>)\"\n  zsh -lc 'p=\"$(command -v <name>)\"; print -r -- \"$p\"; test -n \"$p\" && test -x \"$p\"'\n\nIf a function and executable share a name, prove both layers:\n\n  CODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w <name>; type <name>; whence -p <name> 2>/dev/null || true'\n  env -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w <name> 2>/dev/null || true; command -v <name> 2>/dev/null || true; type <name> 2>/dev/null || true'\n\nStep 9: Run startup regression checks.\nIf `zsh/tests/startup-regression.zsh` exists, run it with zsh:\n\n  zsh zsh/tests/startup-regression.zsh\n\nIf it does not exist, add a focused check that verifies the selected helper files load quietly, expected helpers resolve, PATH order is stable, and missing helpers fail clearly.\n\nStep 10: Report the result.\nReturn a compact summary with:\n\n  - files inspected and changed\n  - each important helper name and its classification\n  - defining source file for each helper\n  - whether it works in `zsh -ic`, plain `zsh -lc`, and `CODEX_LOAD_ZSH_DSL=1 zsh -lc`\n  - the safe `zsh -lc` handoff for each shell-only helper\n  - executable wrapper paths created and their `command -v`, `whence -p`, and `test -x` results\n  - startup regression result\n  - any private files intentionally left untouched\n\nDo not print secrets, raw environment dumps, tokens, cookies, API keys, or private endpoints. If a helper cannot be safely set up, stop at the smallest clear blocker and report the next action.\n```\n\n## Big Idea\n\nAliases save keystrokes. Functions encode workflows.\n\nThis is the handoff from Section 2:\n\n```text\nThe environment loads. Now prove what each helper name actually resolves to.\n```\n\nA name like `xfl` might be:\n\n- an alias\n- a zsh function\n- a shell builtin\n- a hashed command\n- an executable file on PATH\n- missing in this shell, even if it works somewhere else\n\nThis section answers the command-name question: What is this name, where is it defined, and should callers use zsh handoff or an executable fallback?\n\n## Try This Now\n\nPick one helper that failed in a tool, such as `xfl`, `p-f`, or `fix`.\nRun: `zsh -ic 'whence -w <name>; type <name>; command -v <name> || true; whence -p <name> || true'`\nDecide: alias/function needs zsh handoff; executable can be called directly.\n\n## Files To Inspect\n\nCommon files that define helper behavior:\n\n```text\nzsh/conf.d/40-ai.zsh\nzsh/conf.d/47-ai-fix.zsh\nzsh/tests/startup-regression.zsh\nzsh/codex-env.zsh\n```\n\nHelper names vary by setup. Classify each helper, then choose the right handoff pattern for the project.\n\n## When To Reach For This\n\nUse this workflow when:\n\n- a helper works in your terminal but fails in Codex, Prompt Builder, cmux, tmux, a script, or CI\n- a helper name might be an alias or function instead of an executable\n- you want to inspect a workflow wrapper before trusting it\n- you need to decide whether a shorthand should be an alias, a function, or an executable wrapper\n- you need to expose a zsh helper safely through `zsh -lc`\n- you want to find where a helper is defined before editing it\n\nFocus on command diagnosis and workflow design. Skip dotfiles that do not affect the helper you are debugging.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nA helper that runs in your shell will run the same way when an agent calls it.\n```\n\nWhat the workflow gives you now:\n\n```text\nFunctions and aliases do not resolve like executables. Load shell-only helpers\nwith `zsh -lc 'source ...; fn \"$@\"'`, or create an executable wrapper when other\ntools need to call them directly.\n```\n\n## The Mental Model\n\nStart with classification.\n\n```zsh\nwhence -w <name>\ntype <name>\nalias <name> 2>/dev/null || true\nfunctions <name> 2>/dev/null | sed -n '1,80p'\ncommand -v <name> 2>/dev/null || true\nwhence -p <name> 2>/dev/null || true\n```\n\nThen decide the integration shape.\n\n| Result | Meaning | Caller Strategy |\n| --- | --- | --- |\n| alias | interactive shell shorthand | use only at a prompt, or replace with function/executable |\n| function | zsh runtime command | load zsh and source the defining file |\n| builtin | shell-provided command | call inside the shell that owns it |\n| hashed command | cached executable path | refresh lookup with `rehash` if stale |\n| executable | real file on PATH | call directly from agents, scripts, CI, or wrappers |\n| missing | not visible in this shell | find the source file or create a fallback |\n\nSafe zsh handoff shape:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n```\n\nExecutable fallback shape:\n\n```zsh\ncommand -v <name>\nwhence -p <name>\ntest -x \"$(command -v <name>)\"\n```\n\nPlain rule: Use zsh handoff for shell-only helpers. Use an executable wrapper when non-zsh callers need the name.\n\n## The Six Buckets\n\n| Bucket | What It Is | Good For | Confirm With |\n| --- | --- | --- | --- |\n| Alias | text substitution before command execution | tiny shorthands and defaults | `alias <name>`, `type <name>` |\n| Function | shell-defined command body | arguments, branching, policy, cleanup, handoff | `whence -w <name>`, `type <name>`, `functions <name>` |\n| Builtin | command implemented by the shell | `cd`, `alias`, `type`, `functions` | `whence -w <name>` |\n| Hashed command | cached executable path remembered by the shell | faster lookup after discovery | `hash`, `rehash`, `whence -w <name>` |\n| Executable | real file found through PATH | agents, scripts, CI, subprocesses | `command -v <name>`, `whence -p <name>`, `test -x` |\n| Environment variable | process data inherited by child processes | markers, config paths, feature toggles | `print -r -- \"$VAR\"` |\n\nFast classification:\n\n```zsh\nfor name in alias cd git x e xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do\n  printf \"%-14s \" \"$name\"\n  whence -w \"$name\" 2>/dev/null || echo MISSING\ndone\n```\n\n## Alias Or Function\n\nUse an alias when:\n\n- the command is just spelling\n- there is no argument parsing\n- there is no branching\n- there is no safety policy\n- the shorthand is mainly for humans at a prompt\n\nExample:\n\n```zsh\nalias l='ls -lah'\n```\n\nUse a function when the helper needs:\n\n- arguments\n- branching\n- prerequisite checks\n- fallback behavior\n- cleanup\n- prompt construction\n- stdout/stderr discipline\n- source-control discipline\n- handoff into another tool\n\nExample workflow helper:\n\n```zsh\nfix \"billing webhook double-processes paid invoice\"\n```\n\n`fix` belongs as a function because it turns a terse bug report into a richer repair workflow. It is not just shorter spelling.\n\n## When An Executable Wrapper Is Required\n\nA function is not enough when the caller needs to execute a real file.\n\nUse a zsh handoff when:\n\n- the helper is local to zsh\n- the caller can run `zsh -lc`\n- the sourced file is small and safe\n- the helper is not needed from CI, scripts, or non-zsh tools\n\nUse an executable wrapper when:\n\n- a non-zsh process must call the helper by name\n- a script must run it without sourcing shell files\n- CI must run it\n- a repo command should work for teammates\n- Prompt Builder or another tool only accepts command paths\n- the helper is important enough to survive outside one shell setup\n\nWrapper shape:\n\n```zsh\nmkdir -p \"$HOME/.local/bin\"\ncat > \"$HOME/.local/bin/x\" <<'EOF'\n#!/usr/bin/env zsh\nexec codex --dangerously-bypass-approvals-and-sandbox \"$@\"\nEOF\nchmod +x \"$HOME/.local/bin/x\"\n```\n\nConfirm the wrapper:\n\n```zsh\nzsh -lc 'p=\"$(command -v x)\"; print -r -- \"$p\"; test -n \"$p\" && test -x \"$p\"'\n```\n\nIf both a function and executable exist, prove both layers:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -w x; type x; whence -p x 2>/dev/null || true'\nenv -u CODEX_LOAD_ZSH_DSL zsh -lc 'whence -w x 2>/dev/null || true; command -v x || true; type x 2>/dev/null || true'\n```\n\n## Function DSL Source Guard Trap\n\nAn exported guard is fine for env/path-only files:\n\n```zsh\n[[ -n \"${CODEX_AGENT_ENV_SOURCED:-}\" ]] && return 0\nexport CODEX_AGENT_ENV_SOURCED=1\n```\n\nAvoid that pattern for zsh function DSL files.\n\nBad pattern:\n\n```zsh\n[[ -n \"${CODEX_ZSH_DSL_SOURCED:-}\" ]] && return 0\nexport CODEX_ZSH_DSL_SOURCED=1\n\nx() { codex --dangerously-bypass-approvals-and-sandbox \"$@\"; }\n```\n\nWhy it fails: The exported variable can survive into a child shell even though functions and aliases do not.\nThe child shell sees the guard, skips the source file, and the function is missing.\n\nUse non-exported guards for shell-local function files, or make the source operation idempotent.\n\n## Discover Helpers\n\nUse `funclist` as a table of contents:\n\n```zsh\nfunclist\nfunclist ai\nfunclist git\nfunclist -v x\n```\n\nUse `funcwhere` to locate the source:\n\n```zsh\nfuncwhere xfl\nfuncwhere xfc\nfuncwhere xport\nfuncwhere fix\nfuncwhere agent_chain\nfuncwhere muxai\n```\n\nUse `funced` when you are ready to inspect or edit:\n\n```zsh\nfunced xfl\nfunced xfc\nfunced fix\n```\n\nPlain rule:\n\n```text\nfunclist finds names.\nfuncwhere finds the file.\nfunced opens the definition.\n```\n\nIf `funcwhere` itself is missing, classify `funcwhere` like any other helper.\n\n```zsh\nwhence -w funcwhere 2>/dev/null || true\ntype funcwhere 2>/dev/null || true\ncommand -v funcwhere 2>/dev/null || true\nwhence -p funcwhere 2>/dev/null || true\n```\n\nCompare the shell surfaces only to decide where the helper is loaded:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'\nzsh -ic 'whence -v funcwhere; whence -v x; whence -v e'\n```\n\nCommon result:\n\n```text\n`x` and `e` load from the agent-safe helper file.\n`funcwhere` loads only from the interactive helper file.\n```\n\nThat means the opt-in marker worked, but `funcwhere` is not part of the agent-safe helper set.\n\nChoose one:\n\n- source the specific safe module that defines it\n- move it into a small agent-safe introspection module\n- run the inspection through `zsh -ic`\n- create an executable fallback when non-zsh callers need it\n\n## Confirm What A Name Really Is\n\nUse these in order.\n\n```zsh\nwhence -w xfl\ntype xfl\nalias xfl 2>/dev/null || true\nfunctions xfl | sed -n '1,80p'\ncommand -v xfl || true\nwhence -p xfl || true\n```\n\nIf `whence -w xfl` says `function` but `whence -p xfl` is empty, the helper exists only as shell runtime state.\n\nDecision after classification:\n\n| Finding | Smallest Safe Move |\n| --- | --- |\n| alias only | expand it into the real command or convert it to a function |\n| function only | use `zsh -lc 'source ...; fn \"$@\"'` |\n| function plus executable | decide which layer each caller should use and prove both |\n| executable only | call it directly and verify PATH order |\n| missing in `zsh -lc`, present in `zsh -ic` | source the narrow defining file or keep it interactive-only |\n| needed by CI or scripts | create an executable wrapper |\n| depends on prompt/completion/UI state | keep it interactive-only |\n\n## Helper Families\n\n| Family | Examples | What They Represent |\n| --- | --- | --- |\n| Codex launch/fork/export | `x`, `e`, `xfl`, `xfc`, `xport` | Codex wrapper, exec, fork, compact, transcript export |\n| Prompt Builder handoff | `p-f`, `p-c`, `p-cm` | explicit zsh handoff around function-backed workflows |\n| Fix workflow | `fix` | terse bug report -> richer repair workflow |\n| Git/checkpoint helpers | `cfix`, `ghost-save`, `aicm` | workflow compression around repo state |\n| Utility cleanup | `pksk`, `ksk` | alias vs function decision surface |\n| Orchestration bridge | `muxai`, `agent_chain` | transition into panes, phases, and multi-agent flows |\n\n## Ask The Agent This\n\nClassify a broken helper:\n\n```text\n`xfc` works in my terminal but fails when called by a tool.\n\nClassify `xfc` with `whence -w`, `type`, `alias`, `functions`, `command -v`,\nand `whence -p`. Find its source with `funcwhere`. Then show the smallest safe\n`zsh -lc` handoff command that sources the right file and preserves arguments.\n```\n\nDecide alias, function, or executable:\n\n```text\nI want a helper for replaying billing webhook tests.\n\nHelp me decide whether this should be an alias, zsh function, or executable\nwrapper. The helper should accept a fixture name, run the replay command,\ncapture output, and print a clear pass/fail summary. Include confirmation\ncommands for the chosen form.\n```\n\nInspect before using:\n\n```text\nBefore I use `fix` on this repo, inspect what `fix` is. Use `whence -w`, `type`,\n`functions`, and `funcwhere`. Summarize what it wraps, what arguments it accepts,\nwhat it may change, and how I should confirm the repair.\n```\n\n## If It Goes Wrong\n\n### `command not found`\n\nRun:\n\n```zsh\nwhence -w <name> 2>/dev/null || true\ntype <name> 2>/dev/null || true\nalias <name> 2>/dev/null || true\nfunctions <name> >/dev/null 2>&1 && echo function\nwhence -p <name> 2>/dev/null || true\ncommand -v <name> 2>/dev/null || true\n```\n\nLikely result:\n\n```text\nThis helper is a function in interactive zsh, not a binary on PATH.\n```\n\nRecovery:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; <name> \"$@\"' <name> \"arg one\"\n```\n\nIf the missing command is `funcwhere`, diagnose it with `whence`, `type`, and direct source-file inspection.\nUse `whence -v funcwhere` in both shell modes:\n\n```zsh\nCODEX_LOAD_ZSH_DSL=1 zsh -lc 'whence -v funcwhere; whence -v x; whence -v e'\nzsh -ic 'whence -v funcwhere'\n```\n\nIf `funcwhere` appears only in `zsh -ic`, the helper lives outside the\nagent-safe subset. Either source its specific safe module, move it into an\nagent-safe introspection module, or run the inspection through `zsh -ic`.\n\n### Alias Fails In A Script\n\nAliases are shell substitutions. Use a full command, a sourced function, or an executable wrapper.\n\n### Quoting Breaks Arguments\n\nBad:\n\n```zsh\nzsh -lc \"source ~/.config/zsh/conf.d/40-ai.zsh; xfc $prompt\"\n```\n\nGood:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' xfc \"$prompt\"\n```\n\n### Lazy Stub Looks Like The Source\n\nIf `funcwhere fix` points at a lazy stub file, that is not automatically a failure. It often means the helper is discoverable before the full module loads.\n\n## How To Know It Worked\n\nYou are done when:\n\n- you can identify what kind of helper the name resolves to\n- you know the source file\n- you know whether it is portable outside zsh\n- non-interactive callers have a safe `zsh -lc` handoff or executable wrapper\n- stdout/stderr behavior is safe for the caller\n- the confirmation command proves the helper can run in the intended context\n\n## References And Resources\n\n- Helper file: `zsh/conf.d/40-ai.zsh`\n- Fix helper source: `zsh/conf.d/47-ai-fix.zsh`\n- Startup tests: `zsh/tests/startup-regression.zsh`\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n- Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html\n- Zsh startup files overview: https://zsh.sourceforge.io/Intro/intro_3.html\n- Zsh invocation/options: https://zsh.sourceforge.io/Doc/Release/Invocation.html\n- OpenAI Codex: https://openai.com/codex/\n\n## Operational boundaries\n\n- Shell helper examples that bypass approvals and sandboxing require a trusted, separately isolated environment. Generic executable wrappers are the portability boundary; shell-function presence alone is not a smoke test.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-shell-functions-practice",
      "slug": "shell-functions-practice",
      "title": "Shell functions, aliases, and executable boundaries: practice drills",
      "summary": "Eight exercises classify commands, inspect helper definitions and sources, practice discoverability tools, choose aliases/functions/executables, preserve arguments across zsh handoffs, build a webhook replay wrapper, and map orchestration responsibilities.",
      "category": "Tools",
      "tags": [
        "zsh",
        "helpers",
        "cli",
        "practice"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 1: Classify Command Names",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 2: Function Versus Executable",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 3: Find The Source",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 4: Use `funclist`, `funcwhere`, And `funced`",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 5: Alias Or Function?",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 6: Write A Safe Handoff",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 7: Design An Executable Fallback",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/03-zsh-functions-aliases.md#Exercises: 03. ZSH Functions / Aliases/Exercise 8: Section 4 Bridge",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 811,
      "url": "/topics/codex-shell-functions-practice/",
      "markdownUrl": "/markdown/codex-shell-functions-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-functions-practice.json",
      "headings": [
        {
          "id": "exercise-1-classify-command-names",
          "text": "Exercise 1: Classify Command Names",
          "level": 2
        },
        {
          "id": "exercise-2-function-versus-executable",
          "text": "Exercise 2: Function Versus Executable",
          "level": 2
        },
        {
          "id": "exercise-3-find-the-source",
          "text": "Exercise 3: Find The Source",
          "level": 2
        },
        {
          "id": "exercise-4-use-funclist-funcwhere-and-funced",
          "text": "Exercise 4: Use `funclist`, `funcwhere`, And `funced`",
          "level": 2
        },
        {
          "id": "exercise-5-alias-or-function",
          "text": "Exercise 5: Alias Or Function?",
          "level": 2
        },
        {
          "id": "exercise-6-write-a-safe-handoff",
          "text": "Exercise 6: Write A Safe Handoff",
          "level": 2
        },
        {
          "id": "exercise-7-design-an-executable-fallback",
          "text": "Exercise 7: Design An Executable Fallback",
          "level": 2
        },
        {
          "id": "exercise-8-section-4-bridge",
          "text": "Exercise 8: Section 4 Bridge",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Shell functions, aliases, and executable boundaries: practice drills\n\nThese exercises practice command diagnosis and wrapper design.\n\nThe goal is not to memorize every helper. The goal is to prove what a command name is and choose the right integration pattern.\n\n## Exercise 1: Classify Command Names\n\nRun:\n\n```zsh\nfor name in alias cd git l rm x xi xfl xfc xport p-f p-c fix ghost-save pksk muxai agent_chain; do\n  printf \"%-14s \" \"$name\"\n  whence -w \"$name\" 2>/dev/null || echo MISSING\ndone\n```\n\nFill out:\n\n```markdown\n# Command Classification\n\n| Name | alias / function / builtin / command / missing | Notes |\n| --- | --- | --- |\n| alias | | |\n| cd | | |\n| git | | |\n| xfl | | |\n| xfc | | |\n| xport | | |\n| fix | | |\n| muxai | | |\n| agent_chain | | |\n```\n\nQuestions:\n\n- Which names are portable executables?\n- Which names only exist inside zsh?\n- Which names are workflow wrappers?\n\n## Exercise 2: Function Versus Executable\n\nPick three helpers:\n\n```text\nxfl\nxfc\nxport\np-f\np-c\nfix\nagent_chain\nmuxai\nghost-save\npksk\n```\n\nRun:\n\n```zsh\nfor name in xfl xfc xport; do\n  echo \"== $name ==\"\n  whence -w \"$name\" 2>/dev/null || true\n  type \"$name\" 2>/dev/null || true\n  command -v \"$name\" 2>/dev/null || true\n  whence -p \"$name\" 2>/dev/null || true\ndone\n```\n\nFill out:\n\n```markdown\n# Function Versus Executable\n\n| Helper | `whence -w` result | `command -v` result | `whence -p` result | Needs executable fallback? |\n| --- | --- | --- | --- | --- |\n| | | | | |\n```\n\n## Exercise 3: Find The Source\n\nPick one helper:\n\n```text\nxfl\nxfc\nxport\np-f\np-c\nfix\nghost-save\npksk\nmuxai\nagent_chain\n```\n\nRun:\n\n```zsh\nwhence -w <name>\nfuncwhere <name>\nfunctions <name> | sed -n '1,120p'\n```\n\nFill out:\n\n```markdown\n# Function Reading Notes\n\n- helper:\n- kind:\n- source file:\n- purpose:\n- arguments:\n- external tools called:\n- files or git state it may change:\n- why this is a function instead of an alias:\n- one way to confirm it worked:\n- one failure mode:\n```\n\n## Exercise 4: Use `funclist`, `funcwhere`, And `funced`\n\nRun:\n\n```zsh\nfunclist\nfunclist ai\nfunclist git\nfunclist -v x\n```\n\nThen pick a helper and run:\n\n```zsh\nfuncwhere <name>\nfunced <name>\n```\n\nFill out:\n\n```markdown\n# Discoverability Notes\n\n- topic searched:\n- helper found:\n- source file:\n- what `funclist` showed:\n- what `funcwhere` showed:\n- whether `funced` opened the expected source:\n- one improvement you would make to the helper comment or description:\n```\n\n## Exercise 5: Alias Or Function?\n\nFor each proposed helper, decide alias, function, executable wrapper, or no helper.\n\n| Desired Helper | Your Choice | Why |\n| --- | --- | --- |\n| `l` runs `ls -lah` | | |\n| `rm` routes to trash only when installed | | |\n| `replay-webhook <fixture>` runs a command, captures logs, and prints pass/fail | | |\n| `xport` exports the latest Codex transcript and optionally saves markdown | | |\n| `pksk` terminates process groups and cleans matching app processes | | |\n| `agent_chain` runs gated explore-plan-implement phases | | |\n| `ci-smoke` must run from GitHub Actions | | |\n\n## Exercise 6: Write A Safe Handoff\n\nScenario: Prompt Builder or another tool needs to call `xfc`, but `xfc` is a zsh function.\n\nDiagnose:\n\n```zsh\nwhence -w xfc\nfuncwhere xfc\nwhence -p xfc || true\n```\n\nWrite a safe handoff:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' xfc \"continue the failing billing webhook investigation\"\n```\n\nAdapt the pattern for:\n\n```text\nxfl\nxport\np-f\np-c\n```\n\n## Exercise 7: Design An Executable Fallback\n\nScenario: the project has a repeated workflow for replaying billing webhooks. It must work from zsh, scripts, CI, and agents.\n\nCreate a wrapper shape:\n\n```zsh\nmkdir -p bin\ncat > bin/replay-webhook <<'EOF'\n#!/usr/bin/env zsh\nset -euo pipefail\nfixture=\"${1:?Usage: replay-webhook <fixture>}\"\npnpm test:billing-webhook -- \"$fixture\"\nEOF\nchmod +x bin/replay-webhook\n```\n\nConfirm it:\n\n```zsh\nzsh -lc 'PATH=\"$PWD/bin:$PATH\"; p=\"$(command -v replay-webhook)\"; print -r -- \"$p\"; test -x \"$p\"'\nzsh -lc 'PATH=\"$PWD/bin:$PATH\"; replay-webhook sample-fixture'\n```\n\nFill out:\n\n```markdown\n# Executable Fallback Design\n\n- wrapper path:\n- shebang:\n- required arguments:\n- underlying command:\n- confirmation command:\n- why executable instead of function:\n```\n\n## Exercise 8: Section 4 Bridge\n\nRun:\n\n```zsh\nwhence -w muxai agent_chain xfl xfc xport p-f p-c\nfuncwhere muxai\nfuncwhere agent_chain\n```\n\nFill out:\n\n```markdown\n# Section 4 Bridge Notes\n\n- helpers that create or manage workspace shape:\n- helpers that fork or compact Codex threads:\n- helpers that export context:\n- helpers that run multi-agent phases:\n- what needs a pane/thread/layout confirmation:\n- what another agent would need to resume:\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-shell-helper-files",
      "slug": "shell-helper-files",
      "title": "Shell helper implementations and dependency boundaries",
      "summary": "Complete zsh helper examples for Codex launch, Prompt Builder handoff, function discovery, Fusion-first fixes, visible orchestration, and process cleanup; unavailable helper implementations are identified.",
      "category": "Tools",
      "tags": [
        "zsh",
        "helpers",
        "prompt-builder"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/codex-launch-and-prompt-builder.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/fusion-fix.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/orchestration-helpers.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/script-kit-process-helpers.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/zsh/functions/shell-introspection.zsh",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 1494,
      "url": "/topics/codex-shell-helper-files/",
      "markdownUrl": "/markdown/codex-shell-helper-files.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-helper-files.json",
      "headings": [
        {
          "id": "safety-and-completeness-boundaries",
          "text": "Safety and completeness boundaries",
          "level": 2
        },
        {
          "id": "zsh-functions-codex-launch-and-prompt-builder-zsh",
          "text": "zsh/functions/codex-launch-and-prompt-builder.zsh",
          "level": 2
        },
        {
          "id": "zsh-functions-fusion-fix-zsh",
          "text": "zsh/functions/fusion-fix.zsh",
          "level": 2
        },
        {
          "id": "zsh-functions-orchestration-helpers-zsh",
          "text": "zsh/functions/orchestration-helpers.zsh",
          "level": 2
        },
        {
          "id": "zsh-functions-script-kit-process-helpers-zsh",
          "text": "zsh/functions/script-kit-process-helpers.zsh",
          "level": 2
        },
        {
          "id": "zsh-functions-shell-introspection-zsh",
          "text": "zsh/functions/shell-introspection.zsh",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Shell helper implementations and dependency boundaries\n\nThese examples show exact helper boundaries and implementation choices. They are reference code: review dependencies, permissions, and installed-tool contracts before adapting them.\n\n## Safety and completeness boundaries\n\n- `x` explicitly bypasses approvals and sandboxing; `xi` does not. The bypass is a high-trust, separately isolated option, not a prerequisite for loading the environment marker.\n- `_codex_app_server_fork_latest` and `_codex_app_server_fork_compact_latest` are guard stubs returning 64. A compatible app-server implementation is required before fork/compact helpers can work.\n- `agent_chain`, `ghost-save`, and `aicm` are lazy-loader shapes, not bundled implementations of those workflows. Check their dependencies instead of treating function presence as proof.\n- `pksk` and `ksk` are destructive process-cleanup examples. Their broad process matching and process-group signals can stop unrelated work; inspect targets and ownership before adapting them.\n- Prompt Builder handoff preserves argument boundaries only if the receiving helper also avoids reparsing the prompt as shell code.\n\n## zsh/functions/codex-launch-and-prompt-builder.zsh\n\n```zsh\n# Focused Codex + Prompt Builder helper snippets.\n# These are excerpts for workshop discussion, not a full private shell config.\n\nunalias x 2>/dev/null\nx() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\nxi() {\n  codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \"$@\"\n}\n\n_codex_app_server_fork_latest() {\n  echo \"_codex_app_server_fork_latest is not bundled in this package.\" >&2\n  echo \"Install the local Codex app-server helper or replace this guard with a reviewed snippet.\" >&2\n  return 64\n}\n\n_codex_app_server_fork_compact_latest() {\n  echo \"_codex_app_server_fork_compact_latest is not bundled in this package.\" >&2\n  echo \"Install the local Codex app-server compact helper or replace this guard with a reviewed snippet.\" >&2\n  return 64\n}\n\n_codex_cmux_current_session_id() {\n  local helper=\"$HOME/.codex/hooks/cmux-codex-session-registry.py\"\n  [[ -n \"${CODEX_FORK_SESSION_ID:-}\" ]] && {\n    print -r -- \"$CODEX_FORK_SESSION_ID\"\n    return 0\n  }\n  local surface=\"${CMUX_SURFACE_ID:-}\"\n  [[ -n \"$surface\" && -f \"$helper\" ]] || return 1\n  python3 \"$helper\" --resolve-surface \"$surface\" --allow-screen 2>/dev/null\n}\n\n_codex_cmux_name_current_tab() {\n  local name=\"${CODEX_THREAD_NAME:-}\"\n  [[ -n \"${name//[[:space:]]/}\" ]] || return 0\n  local cmux_bin=\"${CMUX_BIN:-/Applications/cmux.app/Contents/Resources/bin/cmux}\"\n  [[ -x \"$cmux_bin\" ]] || return 0\n  \"$cmux_bin\" rename-tab \"$name\" >/dev/null 2>&1 || true\n}\n\n_codex_prompt_builder_fork() {\n  local fork_from=\"\"\n  local compact=0\n  local fork_id\n\n  while (( $# )); do\n    case \"$1\" in\n      --fork-from)\n        [[ $# -ge 2 ]] || { print -u2 -- \"missing value for --fork-from\"; return 2; }\n        fork_from=\"$2\"\n        shift 2\n        ;;\n      --compact)\n        compact=1\n        shift\n        ;;\n      --)\n        shift\n        break\n        ;;\n      *)\n        break\n        ;;\n    esac\n  done\n\n  if (( compact )); then\n    if [[ -n \"$fork_from\" && \"$fork_from\" != \"last\" ]]; then\n      fork_id=\"$(_codex_app_server_fork_compact_latest \"$fork_from\")\" || return 1\n    else\n      fork_id=\"$(_codex_app_server_fork_compact_latest)\" || return 1\n    fi\n  else\n    if [[ -n \"$fork_from\" && \"$fork_from\" != \"last\" ]]; then\n      fork_id=\"$(_codex_app_server_fork_latest \"$fork_from\")\" || return 1\n    else\n      fork_id=\"$(_codex_app_server_fork_latest)\" || return 1\n    fi\n  fi\n\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\nxfl() {\n  local session_id\n  local fork_id\n  session_id=\"$(_codex_cmux_current_session_id)\" && [[ -n \"$session_id\" ]] && {\n    fork_id=\"$(_codex_app_server_fork_latest \"$session_id\")\" || return 1\n    print -r -- \"$fork_id\"\n    _codex_cmux_name_current_tab\n    x resume \"$fork_id\" \"$@\"\n    return\n  }\n  fork_id=\"$(_codex_app_server_fork_latest)\" || return 1\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\nxfc() {\n  local session_id\n  local fork_id\n  session_id=\"$(_codex_cmux_current_session_id 2>/dev/null)\" || session_id=\"\"\n  if [[ -n \"$session_id\" ]]; then\n    fork_id=\"$(_codex_app_server_fork_compact_latest \"$session_id\")\" || return 1\n  else\n    fork_id=\"$(_codex_app_server_fork_compact_latest)\" || return 1\n  fi\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\np-cm() {\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from m --compact \"$@\"\n}\n```\n\n## zsh/functions/fusion-fix.zsh\n\n```zsh\n# Fusion-first fixer prompt for terse bug reports.\n\nunalias fix 2>/dev/null\n\nfix() {\n  local bug=\"$*\"\n  local template_description=\"Run Fusion on the terse bug, implement the selected fix, and verify it.\"\n  local system_prompt=\"You are an expert fixer. The user will provide an extremely terse bug report, broken behavior, failing command, or vague fix request. Treat that terse input as the full task brief and turn it into a concrete repair plan by inspecting the current repository.\"\n  local developer_prompt=\"You are launched by the zsh fix helper. The user input may be only a few words. First clarify the likely defect from local repo evidence, then use the \\$fusion skill before implementing: consult the local Fusion workflow against the bug, wait for terminal Fusion results and read its final artifacts, reconcile the recommendation with source evidence, then implement the fix. Keep changes scoped to the bug, preserve unrelated user work, run focused verification, and report what changed. Do not skip Fusion unless the bug is impossible to evaluate locally or Fusion itself is unavailable; if Fusion is unavailable, state that and continue with source-backed debugging.\"\n\n  if [[ -n \"$bug\" ]]; then\n    p \\\n      --instructions \"$system_prompt\" \\\n      --developer-instructions \"$developer_prompt\" \\\n      --template-label \"Fix\" \\\n      --template-description \"$template_description\" \\\n      \"$bug\"\n  else\n    p \\\n      --instructions \"$system_prompt\" \\\n      --developer-instructions \"$developer_prompt\" \\\n      --template-label \"Fix\" \\\n      --template-description \"$template_description\"\n  fi\n}\n```\n\n## zsh/functions/orchestration-helpers.zsh\n\n```zsh\n# Focused orchestration helper snippets.\n\nmuxai() {\n  local session=\"${1:-ai}\"\n  local window=\"${2:-bots}\"\n  local -a cmds=(claude gemini copilot codex)\n\n  command -v tmux >/dev/null 2>&1 || {\n    echo \"tmux not found\"\n    return 1\n  }\n\n  local win_id pane_id win_info\n  if [[ -n \"$TMUX\" ]]; then\n    win_info=$(tmux new-window -P -F \"#{window_id}|#{pane_id}\" -n \"$window\")\n  elif tmux has-session -t \"$session\" 2>/dev/null; then\n    win_info=$(tmux new-window -t \"$session\" -P -F \"#{window_id}|#{pane_id}\" -n \"$window\")\n  else\n    tmux new-session -d -s \"$session\" -n \"$window\"\n    win_info=\"$(tmux display-message -p -t \"$session:$window\" \"#{window_id}\")|$(tmux list-panes -t \"$session:$window\" -F \"#{pane_id}\" | head -n1)\"\n  fi\n\n  win_id=\"${win_info%%|*}\"\n  pane_id=\"${win_info##*|}\"\n  tmux set-window-option -t \"$win_id\" remain-on-exit on >/dev/null\n  tmux send-keys -t \"$pane_id\" \"${cmds[1]}\" C-m\n\n  local current=\"$pane_id\" new_pane i\n  for (( i=2; i<=${#cmds[@]}; i++ )); do\n    if (( i % 2 == 0 )); then\n      new_pane=$(tmux split-window -P -F \"#{pane_id}\" -t \"$current\" -h)\n    else\n      new_pane=$(tmux split-window -P -F \"#{pane_id}\" -t \"$current\" -v)\n    fi\n    tmux send-keys -t \"$new_pane\" \"${cmds[i]}\" C-m\n    current=\"$new_pane\"\n  done\n\n  tmux select-layout -t \"$win_id\" tiled >/dev/null\n  [[ -z \"$TMUX\" ]] && tmux attach -t \"$session\"\n}\n\nagent_chain() {\n  # Lazy-loader shape only. Keep the full pipeline implementation in the local\n  # zsh source and copy in only the reviewed command surface needed for a demo.\n  unfunction agent_chain 2>/dev/null || true\n  for file in \\\n    \"$HOME/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh\" \\\n    \"$HOME/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh\"\n  do\n    [[ -r \"$file\" ]] && source \"$file\"\n  done\n  agent_chain \"$@\"\n}\n\nghost-save() {\n  unfunction ghost-save 2>/dev/null || true\n  for file in \\\n    \"$HOME/.config/zsh/conf.d/38-git-ghost-checkpoint-dsl.zsh\" \\\n    \"$HOME/.config/zsh/conf.d/39-git-ghost-maintenance-dsl.zsh\"\n  do\n    [[ -r \"$file\" ]] && source \"$file\"\n  done\n  ghost-save \"$@\"\n}\n\naicm() {\n  local file=\"$HOME/.config/zsh/conf.d/43-ai-commit.zsh\"\n  [[ -r \"$file\" ]] || {\n    echo \"Missing $file\" >&2\n    return 1\n  }\n  source \"$file\"\n  aicm \"$@\"\n}\n```\n\n## zsh/functions/script-kit-process-helpers.zsh\n\n```zsh\n# Process cleanup helpers mentioned in the zsh helper inventory.\n\npksk() {\n  local pgids\n  pgids=(\"${(@f)$(ps -axo pgid=,command= | awk '\n    /\\/bin\\/bash \\.\\/dev\\.sh/ || /cargo-watch watch .*script-kit-gpui/ { print $1 }\n  ' | sort -u)}\")\n\n  if (( ${#pgids[@]} )); then\n    local pgid\n    for pgid in \"${pgids[@]}\"; do\n      [[ -n \"$pgid\" ]] && kill -TERM \"-$pgid\" 2>/dev/null || true\n    done\n    sleep 0.5\n    for pgid in \"${pgids[@]}\"; do\n      [[ -n \"$pgid\" ]] && kill -KILL \"-$pgid\" 2>/dev/null || true\n    done\n  fi\n\n  pkill -9 -f '[s]cript-kit-gpui' 2>/dev/null || true\n}\n\nalias ksk='pkill -9 -f \"[s]cript-kit-gpui\"'\n```\n\n## zsh/functions/shell-introspection.zsh\n\n```zsh\n# Zsh function discovery helpers.\n\nfunclist() {\n  setopt localoptions no_xtrace no_verbose\n  local show_all=false verbose=false pattern=\"\"\n\n  while [[ $# -gt 0 ]]; do\n    case \"$1\" in\n      -a|--all) show_all=true; shift ;;\n      -v|--verbose) verbose=true; shift ;;\n      *) pattern=\"$1\"; shift ;;\n    esac\n  done\n\n  local funcs\n  if $show_all; then\n    funcs=$(print -l ${(k)functions} | sort)\n  else\n    funcs=$(print -l ${(k)functions} | grep -v '^_' | sort)\n  fi\n\n  [[ -n \"$pattern\" ]] && funcs=$(echo \"$funcs\" | grep -i \"$pattern\")\n  if ! $verbose; then\n    echo \"$funcs\"\n    return\n  fi\n\n  local func file line_num\n  while IFS= read -r func; do\n    [[ -z \"$func\" ]] && continue\n    file=\"${functions_source[$func]}\"\n    if [[ -z \"$file\" || ! -f \"$file\" ]]; then\n      printf '\\e[1;36m%s\\e[0m\\n' \"$func\"\n      continue\n    fi\n    line_num=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(\" \"$file\" 2>/dev/null | cut -d: -f1)\n    printf '\\e[1;36m%s\\e[0m\\n' \"$func\"\n    [[ -n \"$line_num\" ]] && printf '  %s:%s\\n' \"$file\" \"$line_num\"\n  done <<< \"$funcs\"\n}\n\nfuncwhere() {\n  [[ -z \"$1\" ]] && {\n    echo \"Usage: funcwhere <function_name>\"\n    return 1\n  }\n  local func=\"$1\"\n  [[ $(whence -w \"$func\" 2>/dev/null) != *function* ]] && {\n    echo \"'$func' is not a function\" >&2\n    return 1\n  }\n  local file=\"${functions_source[$func]}\"\n  [[ -z \"$file\" || ! -f \"$file\" ]] && {\n    echo \"Can't find source file for '$func'\" >&2\n    return 1\n  }\n  local line\n  line=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(|eval\\s+[\\\"']${func}\\s*\\(\" \"$file\" | cut -d: -f1)\n  [[ -z \"$line\" ]] && line=1\n  echo \"$file:$line\"\n}\n\nfunced() {\n  [[ -z \"$1\" ]] && {\n    echo \"Usage: funced <function_name>\"\n    return 1\n  }\n  local func=\"$1\"\n  [[ $(whence -w \"$func\" 2>/dev/null) != *function* ]] && {\n    echo \"'$func' is not a function\"\n    return 1\n  }\n  local file=\"${functions_source[$func]}\"\n  [[ -z \"$file\" || ! -f \"$file\" ]] && {\n    echo \"Can't find source file for '$func'\"\n    return 1\n  }\n  local line\n  line=$(grep -n -m1 -E \"^\\s*(function\\s+)?${func}\\s*\\(|eval\\s+[\\\"']${func}\\s*\\(\" \"$file\" | cut -d: -f1)\n  [[ -z \"$line\" ]] && line=1\n  local editor_cmd=\"${EDITOR_CMD:-${EDITOR:-vi}}\"\n  local editor_name=\"${editor_cmd:t}\"\n  case \"$editor_name\" in\n    zed) \"$editor_cmd\" \"$file:$line\" ;;\n    cursor|code|code-insiders) \"$editor_cmd\" -g \"$file:$line\" ;;\n    micro|vim|nvim) \"$editor_cmd\" \"+$line\" \"$file\" ;;\n    *) \"$editor_cmd\" \"$file:$line\" ;;\n  esac\n}\n```\n\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-tools-coding-agents",
      "slug": "tools-coding-agents",
      "title": "Terminal coding agents",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "coding-agents"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#coding-agents"
        }
      ],
      "sourceUnits": [
        "resources/index.html#coding-agents"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 452,
      "url": "/topics/factory-tools-coding-agents/",
      "markdownUrl": "/markdown/factory-tools-coding-agents.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-coding-agents.json",
      "headings": [
        {
          "id": "terminal-coding-agents",
          "text": "Terminal coding agents",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Terminal coding agents\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Terminal coding agents\n\n**John uses:** [pi](https://github.com/earendil-works/pi) (71.9k, MIT) as his primary agent — an AI agent toolkit with a unified LLM API, agent loop, TUI, and an extension system (section 01's `pi-session-id` is a pi extension; section 06's swarms use pi's subagent tool). He runs [Codex CLI](https://github.com/openai/codex) (99k, Apache-2.0), [Claude Code](https://github.com/anthropics/claude-code) (138k), and Grok side by side behind two-letter zsh wrappers (section 02) — the whole point of that section is that the wrapper pattern is agent-agnostic.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [OpenCode](https://github.com/anomalyco/opencode) | Open-source terminal coding agent, provider-agnostic (any model) | Community-run and model-agnostic where pi/Codex/Claude Code are single-author or lab-tied; largest OSS coding agent by stars | MIT |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | Google's open-source terminal agent for Gemini models | Free tier with a Google account; the Gemini-lab counterpart to Codex/Claude Code | Apache-2.0 |\n| [Goose](https://github.com/aaif-goose/goose) | Extensible AI agent (Block) that installs, executes, edits, and tests with any LLM | Extension/MCP-first architecture; works with any LLM rather than one vendor | Apache-2.0 |\n| [Aider](https://github.com/Aider-AI/aider) | AI pair programming in your terminal; git-native diff/commit workflow | Pair-programming/chat-over-git model rather than an autonomous agent loop; slower release cadence lately (check repository activity before adoption) | Apache-2.0 |\n| [Crush](https://github.com/charmbracelet/crush) | Charm's glamorous terminal coding agent (successor to OpenCode's original TUI) | Strongest TUI polish; multi-provider; source-available license (FSL-family, SPDX NOASSERTION) | NOASSERTION |\n| [OpenHands](https://github.com/OpenHands/OpenHands) | AI-driven development platform (formerly OpenDevin) with CLI, GUI, and cloud runtimes | Heavier platform (sandboxed runtimes, web UI) vs a single terminal binary | NOASSERTION |\n| [Grok Build (official)](https://x.ai/cli) / [superagent-ai grok-cli (OSS)](https://github.com/superagent-ai/grok-cli) | xAI's official terminal coding agent (subscription); an OSS coding agent for the Grok API | Grok Build is subscription-gated (SuperGrok/X Premium+) with plan mode and 8 parallel subagents; the superagent-ai CLI is MIT OSS against the Grok API | MIT (OSS one); Grok Build is proprietary |\n\n### Pick this if…\n\n- **OpenCode** — you want one agent that isn't tied to any lab and takes any model/provider.\n- **Gemini CLI** — you want a capable agent on a free tier with just a Google account.\n- **OpenHands** — you want sandboxed/cloud execution and a web UI, not just a terminal.\n- **Goose** — your leverage is custom extensions/MCP tools rather than the agent loop itself.\n- **Aider** — you want a human-in-the-loop pair programmer with clean git commits, not autonomy.\n- **Crush** — you live in the terminal and want the nicest TUI (mind the source-available license).\n- **Grok Build / grok-cli** — you're already paying for SuperGrok / have Grok API credits."
    },
    {
      "id": "factory-tools-terminal-emulators",
      "slug": "tools-terminal-emulators",
      "title": "Terminal emulators",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "terminal-emulators"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#terminal-emulators"
        }
      ],
      "sourceUnits": [
        "resources/index.html#terminal-emulators"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 239,
      "url": "/topics/factory-tools-terminal-emulators/",
      "markdownUrl": "/markdown/factory-tools-terminal-emulators.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-terminal-emulators.json",
      "headings": [
        {
          "id": "terminal-emulators",
          "text": "Terminal emulators",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Terminal emulators\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Terminal emulators\n\n**John uses:** [Ghostty](https://github.com/ghostty-org/ghostty) (58.3k, MIT) — fast, GPU-accelerated, platform-native. In the stack it's deliberately just the pixel layer; Karabiner scopes its Esc-hold chord layer to the Ghostty app, and Herdr runs inside it.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [WezTerm](https://github.com/wezterm/wezterm) | GPU-accelerated cross-platform terminal emulator AND multiplexer in Rust, Lua-configurable | Built-in multiplexing could replace part of the herdr layer too; deep Lua scripting | NOASSERTION (MIT per repo) |\n| [kitty](https://github.com/kovidgoyal/kitty) | Fast, feature-rich GPU-based terminal with 'kittens' extensions and remote control protocol | Scriptable remote-control protocol (kitty @) is a viable pane-automation substrate | GPL-3.0 |\n| [Alacritty](https://github.com/alacritty/alacritty) | Minimal, very fast OpenGL terminal emulator | No tabs/splits by design — pair with tmux/zellij/herdr | Apache-2.0 |\n| [iTerm2](https://github.com/gnachman/iTerm2) | The long-standing macOS power-user terminal (Python scripting API, triggers, tmux integration) | macOS-only; slower rendering than the GPU generation but deepest macOS integration | GPL-2.0 |\n\n### Pick this if…\n\n- **WezTerm** — you want emulator + multiplexer in one binary (can absorb part of the herdr layer).\n- **kitty** — you want a scriptable terminal (`kitty @` remote control is a pane-automation substrate).\n- **Alacritty** — you want maximum speed and will pair it with tmux/zellij/herdr anyway.\n- **iTerm2** — you want the deepest macOS integration and don't care about raw render speed."
    },
    {
      "id": "factory-tools-agent-workspace-managers",
      "slug": "tools-agent-workspace-managers",
      "title": "Terminal workspace / agent multiplexers",
      "summary": "Tool roles, alternatives, selection tradeoffs, and compatibility caveats.",
      "category": "Tools",
      "tags": [
        "tools",
        "agent-workspace-managers"
      ],
      "sources": [
        {
          "label": "Tool comparison reference",
          "url": "https://dewy-sleet-n5zs.here.now/#agent-workspace-managers"
        }
      ],
      "sourceUnits": [
        "resources/index.html#agent-workspace-managers"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 390,
      "url": "/topics/factory-tools-agent-workspace-managers/",
      "markdownUrl": "/markdown/factory-tools-agent-workspace-managers.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-tools-agent-workspace-managers.json",
      "headings": [
        {
          "id": "terminal-workspace-agent-multiplexers",
          "text": "Terminal workspace / agent multiplexers",
          "level": 2
        },
        {
          "id": "pick-this-if",
          "text": "Pick this if…",
          "level": 3
        }
      ],
      "markdown": "# Terminal workspace / agent multiplexers\n\nTool roles, alternatives, selection tradeoffs, and compatibility caveats.\n\n## Terminal workspace / agent multiplexers\n\n**John uses:** [Herdr](https://herdr.dev/) ([ogulcancelik/herdr](https://github.com/ogulcancelik/herdr), 17.3k, AGPL-3.0) — \"tmux for agents\": panes plus an agent-state sidebar (blocked/working/done/idle auto-detected for 15+ agents), detach/reattach, and — the part section 06 is built on — a unix-socket API that agents themselves can drive: spawn panes, read sibling output, wait on each other. That socket is what makes the keeper prompt (\"keep other panes alive\") and planned swarms one-keystroke moves.\n\n| Alternative | What it is | How it differs | License |\n|----|----|----|----|\n| [tmux](https://github.com/tmux/tmux) | The standard terminal multiplexer | No agent-state awareness or agent API; fully scriptable via send-keys/capture-pane so you can hand-roll herdr-like patterns | ISC |\n| [Zellij](https://github.com/zellij-org/zellij) | Terminal workspace with batteries included (layouts, plugins in WASM) | Friendlier defaults and a plugin system, but agent-agnostic — no built-in agent status model | MIT |\n| [claude-squad](https://github.com/smtg-ai/claude-squad) | Manage multiple AI terminal agents (Claude Code, Codex, OpenCode, Amp) in one TUI | Purpose-built agent manager like herdr, backed by tmux + git worktrees; narrower pane model | AGPL-3.0 |\n| [Vibe Kanban](https://github.com/BloopAI/vibe-kanban) | Kanban web UI for orchestrating multiple coding-agent tasks | Board-of-tasks metaphor instead of terminal panes; good for reviewing parallel agent work; check current repository activity | Apache-2.0 |\n| [hcom](https://github.com/aannoo/hcom) | Lets AI agents message, watch, and spawn each other across terminals (Claude Code, Codex, Antigravity, Pi, ...) | Agent-to-agent communication layer without owning your terminal layout; closest OSS match to herdr's socket API idea | MIT |\n| [Omnara](https://github.com/omnara-ai/omnara) | Talk to your AI agents from anywhere (mobile/web control plane, YC S25) | Remote monitoring/answering of agents rather than local pane management; check current repository activity | Apache-2.0 |\n\n### Pick this if…\n\n- **tmux** — you want the zero-risk default; `send-keys`/`capture-pane` let you hand-roll herdr's socket tricks.\n- **Zellij** — you want modern ergonomics and a plugin system without agent-specific features.\n- **claude-squad** — you specifically want \"many agents, one dashboard\" with worktree isolation.\n- **Vibe Kanban** — you'd rather review parallel agent work as a board than as panes (note: quieter repo lately).\n- **hcom** — you want the agent-to-agent messaging half of herdr as a small composable tool.\n- **Omnara** — your bottleneck is being away from the keyboard, not pane management."
    },
    {
      "id": "factory-zsh-launchers",
      "slug": "zsh-launchers",
      "title": "Thin zsh launchers and composable command families",
      "summary": "Wrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable.",
      "category": "Tools",
      "tags": [
        "zsh",
        "factory"
      ],
      "sources": [
        {
          "label": "Thin zsh launchers and composable command families",
          "url": "https://sacred-ritual-w7as.here.now/"
        }
      ],
      "sourceUnits": [
        "02-zsh/index.html#TL;DR",
        "02-zsh/index.html#What launching an agent actually costs",
        "02-zsh/index.html#Appendix",
        "02-zsh/index.html#Why functions, not aliases",
        "02-zsh/index.html#Families compound: resume, fork, and second accounts",
        "02-zsh/index.html#The prompt builder picks the agent last",
        "02-zsh/index.html#The recipe, proved on pi"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1498,
      "url": "/topics/factory-zsh-launchers/",
      "markdownUrl": "/markdown/factory-zsh-launchers.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-zsh-launchers.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "what-launching-an-agent-actually-costs",
          "text": "What launching an agent actually costs",
          "level": 2
        },
        {
          "id": "why-functions-not-aliases",
          "text": "Why functions, not aliases",
          "level": 2
        },
        {
          "id": "families-compound-resume-fork-and-second-accounts",
          "text": "Families compound: resume, fork, and second accounts",
          "level": 2
        },
        {
          "id": "the-prompt-builder-picks-the-agent-last",
          "text": "The prompt builder picks the agent last",
          "level": 2
        },
        {
          "id": "the-recipe-proved-on-pi",
          "text": "The recipe, proved on pi",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        }
      ],
      "markdown": "# Thin zsh launchers and composable command families\n\nWrap repeated flags, isolate account credentials, compose session helpers, and make launch behavior inspectable.\n\n## Related working material\n\n- [Thin zsh launchers and composable command families — prompts and exercises](/topics/factory-zsh-launchers-practice/)\n- [Thin zsh launchers and composable command families — questions and tradeoffs](/topics/factory-zsh-launchers-questions/)\n- [Thin zsh launchers and composable command families — worked example](/topics/factory-zsh-launchers-worked-example/)\n\n## TL;DR\n\n- One working set of dotfiles runs Codex, Claude Code, and pi behind two-letter functions — launch, resume, fork, and second accounts each cost two or three keystrokes.\n- You leave with four drop-in wrapper files (Codex, Claude Code, pi, and the full `pir` family) plus prompts that make your own agent build the next family for you.\n- The one move: **wrap → compose → cheat-sheet → verify with `zsh -n`**. It took five minutes to build the whole pi family live.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://sacred-ritual-w7as.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.\n```\n\n## What launching an agent actually costs\n\nYou start a coding agent many times a day, and each launch needs the same environment variable, the same config override, and the same sandbox flag. Leaning on shell history means sometimes launching with a flag missing — which is worse than a failed launch, because the agent starts in a different permission posture than you expect. This is the raw Codex invocation behind the presenter's daily driver:\n\n``` text\nCODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox\n```\n\nNobody types that twice. The dotfiles reduce it to one letter, and hang the whole session vocabulary off that letter. This is the real wrapper plus its resume/fork family, drop-in ready:\n\n``` text\n# codex.zsh — Codex behind one letter, sessions behind two.\n# Placeholders (comments only — nothing below needs editing):\n#   <personal-account> = the login that owns ~/.codex\n# Safety trade: --dangerously-bypass-approvals-and-sandbox removes approval\n# prompts. Keep it only if you accept unattended file and shell access.\n\nunalias x 2>/dev/null\nx() {\n  # Default account: <personal-account> via ~/.codex\n  CODEX_HOME=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\" \\\n    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\n# The resume/fork family: every helper routes through x, so a future fix\n# to x fixes the whole family for free.\nunalias xr xrl xrm xf 2>/dev/null\nxr()  { x resume \"$@\"; }         # pick a session to resume\nxrl() { x resume --last \"$@\"; }  # jump into the most recent session\nxrm() { x resume m \"$@\"; }       # resume the session named \"m\"\nxf()  { x fork \"$@\"; }           # fork: xf <id|name> [prompt]\n```\n\n## Why functions, not aliases\n\nAn alias substitutes text. It cannot take a positional argument in the middle, cannot run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow these helpers, which is why every definition starts with `unalias <name> 2>/dev/null`. The same wrapper shape repeats across a second agent:\n\n``` text\n# claude.zsh — same pattern, different agent.\n# Placeholders (comments only — nothing below needs editing):\n#   <work-account> = the login that owns ~/.claude-second\n# Safety trade: --dangerously-skip-permissions removes permission prompts.\n\nunalias clx clx2 clxw 2>/dev/null\nclx()  { claude --dangerously-skip-permissions \"$@\"; }\n\nclx2() {  # second account (<work-account>) — same UX, separate config dir\n  local config_dir=\"${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}\"\n  mkdir -p \"$config_dir\" || return\n  CLAUDE_CONFIG_DIR=\"$config_dir\" claude --dangerously-skip-permissions \"$@\"\n}\n\nclxw() {  # launch inside a named worktree: clxw <name> [args]\n  local name=\"$1\"; shift\n  CLAUDE_WORKTREE_NAME=\"$name\" claude --worktree \"$name\" --dangerously-skip-permissions \"$@\"\n}\n```\n\nFunctions also absorb upstream bugs. pi's lockfile dependency expects a directory at `auth.json.lock`; a stray regular file there causes recurring auth failures. The wrapper heals it on every launch, so the bug lives in one function instead of in your memory:\n\n``` text\n# pi.zsh — wrappers absorb upstream bugs so you don't have to remember them.\n# pi's proper-lockfile dependency expects a directory at auth.json.lock; a\n# stray regular file there causes recurring ENOTDIR auth failures.\n\nunalias pi 2>/dev/null\npi() {\n  local agent_dir=\"${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}\"\n  local auth_lock=\"$agent_dir/auth.json.lock\"\n  if [[ -f \"$auth_lock\" && ! -L \"$auth_lock\" ]]; then\n    rm -f -- \"$auth_lock\"\n  fi\n  command pi \"$@\"\n}\n```\n\n## Families compound: resume, fork, and second accounts\n\nA single wrapper saves keystrokes; the payoff compounds when wrappers call wrappers. Since `x` owns the account and the flags, every session action is a one-line composition on top of it. The deepest member of the family forks a session, compacts the fork, and resumes it — still routed through `x`:\n\n``` text\nxfmc() {  # fork session \"m\" → compact the fork → resume it\n  local fork_id\n  fork_id=\"$(_codex_app_server_fork_compact_latest m)\" || return 1\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n# the two _codex_* helpers live elsewhere in the dotfiles — shown for shape, not for pasting\n```\n\nSecond accounts work the same way: `x2` points `CODEX_HOME` at `~/.codex-work`, a directory built by a helper that symlinks every top-level entry of the primary home *except* auth files, and refuses to run if an auth file ever becomes a symlink. Accounts share sessions and config, never credentials. A family this large needs a memory aid, so it prints its own: running `x-` lists every helper, straight from the file that defines them.\n\n``` text\n$ x-\nx        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.\nx2       Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.\nxr       Resume a Codex session through the base x wrapper.\nxrl      Resume the most recent Codex session through the base x wrapper.\nxf       Run x fork; pass the conversation id/name first, then the prompt.\nxfmc     Fork conversation m, compact the fork, then resume it interactively.\np-f      Compose a prompt in p, then fork using the prompt-builder --fork-from toggle.\n# … full listing covers 35 helpers\n```\n\n## The prompt builder picks the agent last\n\nWrappers fix the launch, but not a subtler mistake: deciding which agent to use before you have written the prompt. The `p` command — a separate terminal program, \"Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code\" — inverts the order. Compose the prompt first, then send it to any configured target: one prompt can go to any of three agents across five accounts. Helpers like `p-f` and `p-c` close the loop by handing the finished prompt back to the zsh fork/resume functions.\n\n``` text\n$ p target list\npi            pi     bin=pi\ncodex         codex  bin=codex  config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"\nclaude        claude bin=claude\nwork-profile       codex  bin=codex  CODEX_HOME=~/.codex-work  config=cli_auth_credentials_store=\"file\" …\nclaude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second\nclaude-third  claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third\n```\n\nYou can rehearse without launching anything: `p --print-prompt \"explain this repo\"` prints the composed prompt and exits.\n\n## The recipe, proved on pi\n\nThe claim that this repeats \"in minutes\" is testable, and the workshop tests it live. pi had a base wrapper but no session helpers. Step one is always the same — ask the CLI what it can do instead of guessing:\n\n``` text\n$ pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n  --continue, -c        Continue previous session\n  --resume, -r          Select a session to resume\n  --fork <path|id>      Fork specific session file or partial UUID into a new session\n  --name, -n <name>     Set session display name\n  --no-session          Don't save session (ephemeral)\n```\n\nEach flag becomes one short function, the family gets a `pi-` cheat sheet in the `x-` style, and the whole file verifies with `zsh -n` plus a stub test before it ever touches a real shell. The finished file is printed complete in the [agent guide above](https://sacred-ritual-w7as.here.now/#agent-guide) — five helpers and a cheat sheet, built in about five minutes. The recipe: **wrap** the flags you can't remember, **compose** wrappers into families, **document** with a `fn-` help function, **repeat** for every new agent CLI.\n\n## Appendix\n\n### Limits & caveats\n\n- **Safety trade:** `--dangerously-bypass-approvals-and-sandbox` (Codex) and `--dangerously-skip-permissions` (Claude Code) remove approval prompts. The wrappers make that posture deliberate and visible in one place, but they do not make it safe. Do not copy those flags unless you accept unattended file and shell access.\n- **Drift risk:** composed families inherit fixes but also breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function lowers the cost of the audit; it does not remove the need for one.\n- **Stub tests prove wiring, not behavior:** the success check proves each helper passes the intended flags. A live `pir` only opens a session picker when pi has saved sessions on that machine.\n- **\"Five minutes\" is the presenter's estimate** for the live walkthrough, not a measurement.\n- **One machine's configuration:** all evidence comes from one working set of dotfiles, version-specific snapshot. Treat specific flags as examples, not standards. The `p` target list is one machine's config file, not a tool default. No comparison was made with shell-history tools or command launchers.\n- **Version pinning:** pi flags were captured from pi v0.80.10; re-run `--help` against your version."
    },
    {
      "id": "factory-zsh-launchers-practice",
      "slug": "zsh-launchers-practice",
      "title": "Thin zsh launchers and composable command families — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families.",
      "category": "Tools",
      "tags": [
        "prompts",
        "exercises",
        "zsh-launchers"
      ],
      "sources": [
        {
          "label": "Thin zsh launchers and composable command families",
          "url": "https://sacred-ritual-w7as.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://sacred-ritual-w7as.here.now/agent.md"
        },
        {
          "label": "Published launcher families",
          "url": "https://sacred-ritual-w7as.here.now/agent-launchers.zsh"
        }
      ],
      "sourceUnits": [
        "02-zsh/index.html#Quick start",
        "02-zsh/index.html#Prompt library",
        "02-zsh/index.html#Set it up (agent guide)",
        "02-zsh/index.html#Attachments — take it home",
        "02-zsh/index.html#Build a wrapper family for a CLI",
        "02-zsh/index.html#Mine your shell history for wrapper candidates",
        "02-zsh/index.html#Add a second account to an existing wrapper",
        "02-zsh/index.html#Audit wrappers for flag drift after a CLI update",
        "02-zsh/agent.md",
        "02-zsh/agent-launchers.zsh"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 3617,
      "url": "/topics/factory-zsh-launchers-practice/",
      "markdownUrl": "/markdown/factory-zsh-launchers-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-zsh-launchers-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "build-a-wrapper-family-for-a-cli",
          "text": "Build a wrapper family for a CLI",
          "level": 3
        },
        {
          "id": "mine-your-shell-history-for-wrapper-candidates",
          "text": "Mine your shell history for wrapper candidates",
          "level": 3
        },
        {
          "id": "add-a-second-account-to-an-existing-wrapper",
          "text": "Add a second account to an existing wrapper",
          "level": 3
        },
        {
          "id": "audit-wrappers-for-flag-drift-after-a-cli-update",
          "text": "Audit wrappers for flag drift after a CLI update",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "attachments-take-it-home",
          "text": "Attachments — take it home",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "two-letter-commands-agent-setup-guide",
          "text": "Two-Letter Commands — agent setup guide",
          "level": 2
        },
        {
          "id": "attachments-machine-fetchable",
          "text": "Attachments (machine-fetchable)",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        },
        {
          "id": "complete-launcher-family-attachment",
          "text": "Complete launcher-family attachment",
          "level": 2
        }
      ],
      "markdown": "# Thin zsh launchers and composable command families — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for thin zsh launchers and composable command families.\n\n## Quick start\n\nSixty seconds, zero installs: build a wrapper family in a temp dir and prove it passes the right flags with a stub.\n\n``` text\ncd \"$(mktemp -d)\"\nprintf '%s\\n' 'pir() { pi --resume \"$@\"; }' 'pic() { pi --continue \"$@\"; }' \\\n  'pi-() { printf \"pir  resume\\npic  continue\\n\"; }' > pi-utils.zsh\nzsh -n pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source pi-utils.zsh; pi-; pir --check'\n```\n\n## Prompt library\n\nPaste these into your own coding agent. Each one applies the recipe without you memorizing it.\n\n### Build a wrapper family for a CLI\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: ~/.zsh-wrappers/pi-utils.zsh + passing stub test\n\n``` text\nBuild me a two-letter zsh wrapper family for the pi CLI.\n\n1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.\n2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> \"$@\"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`.\n3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.\n4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'\n   Expect: [stub pi] --resume --check\n5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.\n```\n\n### Mine your shell history for wrapper candidates\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a ranked top-5 list + one proposed wrapper file to review\n\n``` text\nRead my shell history (~/.zsh_history, or `fc -l 1` output I paste) and find the commands I retype most. Group near-identical long commands (same binary, same flags), rank the top 5 by length times repeat count, and for each one propose a two-letter zsh wrapper function: `unalias` guard first, environment pinning inside the function, `\"$@\"` pass-through at the end. Print all proposed functions in one file for me to review. Do not install or source anything yet.\n```\n\n### Add a second account to an existing wrapper\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a \\<name\\>2 wrapper + an auth-isolated second home dir\n\n``` text\nI have a zsh wrapper function for an agent CLI and I want a second account with the same UX. Create a `<name>2` wrapper that launches the same CLI with its config env var (CODEX_HOME for codex, CLAUDE_CONFIG_DIR for claude) pointed at a second directory such as ~/.<cli>-second. Rules: create the directory if it is missing; if the tool benefits from shared state, symlink top-level entries from the primary home EXCEPT auth files (auth.json and similar) — auth stays local, never symlinked or copied; refuse to proceed if an auth file would end up shared or would become a symlink. Show me the wrapper and the ensure-home helper before running anything.\n```\n\n### Audit wrappers for flag drift after a CLI update\n\n- Agent: any coding agent\n- Working directory: anywhere\n- Expected result: a drift report + patched wrapper files with before/after diff\n\n``` text\nMy agent CLI just updated. Audit my wrapper functions for flag drift: (1) list every function in ~/.zsh-wrappers/*.zsh and the flags each one passes; (2) run `--help` for each wrapped binary and check that every flag still exists with the same meaning; (3) report renamed or removed flags and patch only the affected functions; (4) re-verify each patched file with `zsh -n` and a stub test that echoes the flags. Show me a before/after diff of every change.\n```\n\n## Set it up (agent guide)\n\n1.  Create `~/.zsh-wrappers/pi-utils.zsh` with exactly this content — the complete file from the live walkthrough:\n\n    ``` text\n    # pi-utils.zsh — the \"pir\" walkthrough result\n    # Built live at the workshop following the same recipe as the x/xr family.\n    # Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n    # Recipe step 0 — the base wrapper already exists in the dotfiles\n    # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n    # pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n    # Recipe step 1 — read the CLI's own session flags:\n    #   pi --help | grep -E \"resume|continue|fork|name\"\n    #   --continue, -c   Continue previous session\n    #   --resume, -r     Select a session to resume\n    #   --fork <path|id> Fork a session into a new session\n    #   --name, -n       Set session display name\n\n    # Recipe step 2 — wrap each flag as a two/three-letter function.\n\n    unalias pir 2>/dev/null\n    pir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\n    unalias pic 2>/dev/null\n    pic() { pi --continue \"$@\"; }      # continue the most recent session\n\n    unalias pif 2>/dev/null\n    pif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\n    unalias pin 2>/dev/null\n    pin() {                            # start a named session: pin <name> [prompt]\n      local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n      pi --name \"$name\" \"$@\"\n    }\n\n    unalias pit 2>/dev/null\n    pit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n    # Recipe step 3 — every family ships its own cheat sheet (the x- convention).\n    pi-() {\n      local -a fn_name=(pi pir pic pif pin pit)\n      local -A fn_desc=(\n        pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n        pir 'Resume: open the session picker (pi --resume).'\n        pic 'Continue: jump straight back into the last session (pi --continue).'\n        pif 'Fork a session into a new one: pif <path|id> [prompt].'\n        pin 'Start a named session: pin <name> [prompt].'\n        pit 'Throwaway: run without saving a session (pi --no-session).'\n      )\n      local fn\n      for fn in \"${fn_name[@]}\"; do\n        printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n      done\n    }\n    ```\n\n2.  Wire it into your shell:\n\n    ``` text\n    mkdir -p ~/.zsh-wrappers\n    # save the file above as ~/.zsh-wrappers/pi-utils.zsh, then:\n    echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc\n    exec zsh\n    ```\n\n**Success check:** syntax first, then a stub test that proves every helper passes the intended flags — without launching anything.\n\n``` text\nzsh -n ~/.zsh-wrappers/pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'\n```\n\n``` text\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\n## Attachments — take it home\n\nBoth wrapper files discussed on this page ship with the site as downloadable attachments: [agent-launchers.zsh](https://sacred-ritual-w7as.here.now/agent-launchers.zsh) (the `x`/`xr`/`x2`, `clx`, and `p-f`/`p-c` families, curated from the presenter's dotfiles with account details generalized) and [pi-utils.zsh](https://sacred-ritual-w7as.here.now/pi-utils.zsh) (the complete `pir` walkthrough result). One block installs both:\n\n``` text\nmkdir -p ~/.zsh-wrappers\ncurl -fsSL https://sacred-ritual-w7as.here.now/agent-launchers.zsh -o ~/.zsh-wrappers/agent-launchers.zsh\ncurl -fsSL https://sacred-ritual-w7as.here.now/pi-utils.zsh -o ~/.zsh-wrappers/pi-utils.zsh\necho 'source ~/.zsh-wrappers/agent-launchers.zsh' >> ~/.zshrc\necho 'source ~/.zsh-wrappers/pi-utils.zsh' >> ~/.zshrc\n```\n\nRead both files before sourcing them — the Codex and Claude wrappers carry the bypass/skip-permission flags discussed in the appendix. Open a new shell, then run `x-` and `pi-` to print the cheat sheets.\n\n## Complete reusable setup contract\n\n## Two-Letter Commands — agent setup guide\n\nFollowing this file sets up: a two-letter zsh wrapper family for a CLI your user runs often — base wrapper, resume/continue/fork helpers, a self-printing cheat sheet — verified with `zsh -n` and a stub test before it touches their shell config.\n\nHuman companion pages on this site (context for your user, not required for setup): `index.html` (the section guide), `replay.html` (Session Replay — the walkthrough as an annotated transcript), `dialogue.html` (Socratic Dialogue — attendee questions driving the same material).\n\n## Attachments (machine-fetchable)\n\nBoth wrapper files ship with this site as plain-text attachments you can fetch directly:\n\n- `https://sacred-ritual-w7as.here.now/pi-utils.zsh` — the complete pi wrapper family built in step 2 below (identical content; the file's \"Source it\" comment says `demo/pi-utils.zsh` because it is the verbatim workshop walkthrough result — install it at `~/.zsh-wrappers/pi-utils.zsh` regardless).\n- `https://sacred-ritual-w7as.here.now/agent-launchers.zsh` — the presenter's curated launcher families (`x`/`xr`/`xrl`/`xrm`, `x2`, `clx`/`clx2`/`clxw`, `p-f`/`p-c`, and the `x-` cheat sheet), account details generalized. NOTE: it carries `--dangerously-bypass-approvals-and-sandbox` and `--dangerously-skip-permissions` — show it to your user and get explicit approval before sourcing it.\n\nFetching `pi-utils.zsh` and installing it at `$HOME/.zsh-wrappers/pi-utils.zsh` is an acceptable substitute for writing the file in step 2, as long as you still run the verification in step 3.\n\nPlaceholders used below: `<cli>` = the target CLI's command name (the worked example uses `pi`); `<w>` = the family's short prefix (for `pi` the prefix is `pi`, giving `pir`, `pic`, `pif`, `pin`, `pit`). All other paths are literal.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nzsh --version\ncommand -v pi || echo \"pi not installed\"\n```\n\nExpected: zsh 5.x or newer. If `pi` is not installed, do NOT stop — pick the agent CLI your user actually runs (check `command -v codex`, `command -v claude`, or ask), use it as `<cli>`, and adapt the flag names in step 1. If no target CLI exists at all, stop and tell your user what to install.\n\n## Steps\n\n1. Capture the CLI's own session flags — never guess them:\n\n   ```bash\n   pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n   ```\n\n   Expected for pi (v0.80.10): `--resume/-r` (pick a session), `--continue/-c` (last session), `--fork <path|id>`, `--name/-n <name>`, `--no-session` (ephemeral). For a different `<cli>`, run `<cli> --help` and map its equivalents; wrap only flags that actually exist.\n\n2. Create `$HOME/.zsh-wrappers/pi-utils.zsh` with exactly this content (for a different `<cli>`, keep the identical shape — `unalias` guard before every definition, each helper one short function calling `<cli>` with one flag plus `\"$@\"`, and a `<w>-` cheat-sheet function last):\n\n   ```zsh\n   # pi-utils.zsh — the \"pir\" walkthrough result\n   # Built live at the workshop following the same recipe as the x/xr family.\n   # Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n   # Recipe step 0 — the base wrapper already exists in the dotfiles\n   # (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n   # pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n   # Recipe step 1 — read the CLI's own session flags:\n   #   pi --help | grep -E \"resume|continue|fork|name\"\n   #   --continue, -c   Continue previous session\n   #   --resume, -r     Select a session to resume\n   #   --fork <path|id> Fork a session into a new session\n   #   --name, -n       Set session display name\n\n   # Recipe step 2 — wrap each flag as a two/three-letter function.\n\n   unalias pir 2>/dev/null\n   pir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\n   unalias pic 2>/dev/null\n   pic() { pi --continue \"$@\"; }      # continue the most recent session\n\n   unalias pif 2>/dev/null\n   pif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\n   unalias pin 2>/dev/null\n   pin() {                            # start a named session: pin <name> [prompt]\n     local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n     pi --name \"$name\" \"$@\"\n   }\n\n   unalias pit 2>/dev/null\n   pit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n   # Recipe step 3 — every family ships its own cheat sheet (the x- convention).\n   pi-() {\n     local -a fn_name=(pi pir pic pif pin pit)\n     local -A fn_desc=(\n       pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n       pir 'Resume: open the session picker (pi --resume).'\n       pic 'Continue: jump straight back into the last session (pi --continue).'\n       pif 'Fork a session into a new one: pif <path|id> [prompt].'\n       pin 'Start a named session: pin <name> [prompt].'\n       pit 'Throwaway: run without saving a session (pi --no-session).'\n     )\n     local fn\n     for fn in \"${fn_name[@]}\"; do\n       printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n     done\n   }\n   ```\n\n   Create the directory first:\n\n   ```bash\n   mkdir -p \"$HOME/.zsh-wrappers\"\n   ```\n\n3. Verify BEFORE touching the user's shell config — syntax check, then a stub test that shadows `<cli>` with a function so nothing real launches:\n\n   ```bash\n   zsh -n \"$HOME/.zsh-wrappers/pi-utils.zsh\" && echo \"syntax OK\"\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source \"$HOME/.zsh-wrappers/pi-utils.zsh\"; pir --check'\n   ```\n\n4. Wire it into the shell. Ask your user before editing `~/.zshrc` if your policy requires it; otherwise append:\n\n   ```bash\n   grep -qxF 'source ~/.zsh-wrappers/pi-utils.zsh' \"$HOME/.zshrc\" || \\\n     echo 'source ~/.zsh-wrappers/pi-utils.zsh' >> \"$HOME/.zshrc\"\n   ```\n\n## Success check\n\nRun:\n\n```bash\nzsh -n \"$HOME/.zsh-wrappers/pi-utils.zsh\" && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source \"$HOME/.zsh-wrappers/pi-utils.zsh\"; pi-; pir --check'\n```\n\nExpected observable result:\n\n```\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\nThe last line proves the helper passes the intended flag. In a fresh interactive shell, `pi-` prints the cheat sheet and `pir` opens pi's session picker (only if saved sessions exist on this machine).\n\nReport to your user: which CLI you wrapped, the file you created, the success-check output, and anything you adapted.\n\n## Notes for agents\n\n- **Alias collisions:** oh-my-zsh and other frameworks ship one- and two-letter aliases. Without the `unalias <name> 2>/dev/null` guard before each definition, the alias silently wins. Keep the guards even if they look redundant.\n- **Never add permission-bypass flags** (`--dangerously-bypass-approvals-and-sandbox`, `--dangerously-skip-permissions`) to a wrapper unless your user explicitly asks. They trade safety for speed.\n- **Helpers must call the command name, not an absolute path** (`pi --resume \"$@\"`, not `/some/path/pi`). That is what makes the stub test work and lets a future base-wrapper fix (like pi's `auth.json.lock` heal) apply to the whole family.\n- **Flag drift:** when the CLI updates, wrappers can break all at once. Re-run `<cli> --help` and patch only the function that owns the changed flag, then re-run the success check.\n- **pi-specific:** pi's lockfile dependency expects a directory at `~/.pi/agent/auth.json.lock`. If a stray regular (non-symlink) file appears there, pi fails auth with ENOTDIR errors; delete that file (a base `pi()` wrapper can do it before every launch).\n\n## Complete launcher-family attachment\n\nReview the permission-bypass posture and account-isolation guards before sourcing. These are examples, not a recommendation to disable approvals.\n\n```zsh\n# agent-launchers.zsh — the agent-launcher function families from the workshop.\n# Curated from the presenter's dotfiles for \"Agentic Software Factory\"\n# (the recorded snapshot), section 02: Custom zsh Functions. Adapt paths to your setup.\n# Companion page: https://sacred-ritual-w7as.here.now/\n#\n# Placeholders (comments only — nothing below needs editing to run):\n#   <personal-account> = the login that owns ~/.codex\n#   <work-account>     = the login that owns the second-account dirs\n# Lines that differ from the private originals carry an \"ADAPTED:\" comment.\n#\n# Safety trade (deliberate, visible, yours to reject):\n#   --dangerously-bypass-approvals-and-sandbox (Codex) and\n#   --dangerously-skip-permissions (Claude Code) remove approval prompts.\n#   Delete those flags if you do not accept unattended file and shell access.\n\n# ============================================================ Codex: the x family\n\n: \"${CODEX_PRIMARY_HOME:=$HOME/.codex}\"\n# ADAPTED: name the second home whatever fits your second account, e.g. ~/.codex-work\n: \"${CODEX_SECOND_HOME:=$HOME/.codex-work}\"\n\n# Names that must never be shared between accounts (auth / login only).\n# Everything else under the primary home is eligible for a symlink into x2.\n_codex_auth_local_basenames() {\n  case \"$1\" in\n    auth.json|auth.json.*|*.auth.json) return 0 ;;\n    codex-login.log|codex-login*.log) return 0 ;;\n  esac\n  return 1\n}\n\n# Build/refresh the second home as a shared view of ~/.codex, minus auth.\n# Safety rules:\n# - never write into CODEX_PRIMARY_HOME\n# - never replace a real (non-symlink) file/dir in the second home\n# - if auth.json is accidentally a symlink into primary, remove only that symlink\n# - only create/repair symlinks we manage (existing real files stay put)\n_codex_egghead_ensure_home() {\n  emulate -L zsh\n  setopt null_glob extended_glob\n\n  local primary=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\"\n  local secondary=\"${CODEX_SECOND_HOME:-$HOME/.codex-work}\"\n  local src base dest rel current\n\n  if [[ ! -d \"$primary\" ]]; then\n    print -u2 -- \"codex primary home missing: $primary\"\n    return 1\n  fi\n\n  # Refuse pathological layouts.\n  if [[ \"$secondary\" == \"$primary\" || \"$secondary\" == \"$primary\"/* ]]; then\n    print -u2 -- \"refusing second home inside primary: $secondary\"\n    return 1\n  fi\n\n  mkdir -p \"$secondary\" || return 1\n\n  # If a previous setup linked auth into the primary account, break that only.\n  dest=\"$secondary/auth.json\"\n  if [[ -L \"$dest\" ]]; then\n    current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n    case \"$current\" in\n      \"$primary/auth.json\"|\"$primary\"/auth.json)\n        rm -f \"$dest\" || return 1\n        ;;\n    esac\n  fi\n\n  # Symlink top-level primary entries except auth-local basenames.\n  for src in \"$primary\"/* \"$primary\"/.[!.]* \"$primary\"/..?*; do\n    [[ -e \"$src\" || -L \"$src\" ]] || continue\n    base=\"${src:t}\"\n    [[ \"$base\" == \".\" || \"$base\" == \"..\" ]] && continue\n    _codex_auth_local_basenames \"$base\" && continue\n\n    dest=\"$secondary/$base\"\n    if [[ -L \"$dest\" ]]; then\n      current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n      if [[ \"$current\" != \"$src\" ]]; then\n        # Only retarget an existing symlink; never touch real files.\n        ln -sfn \"$src\" \"$dest\" || return 1\n      fi\n      continue\n    fi\n    if [[ -e \"$dest\" ]]; then\n      # Real file/dir already present in the second home — leave it alone.\n      continue\n    fi\n    ln -s \"$src\" \"$dest\" || return 1\n  done\n\n  # Keep login diagnostics local even if parent `log` is shared.\n  # When primary/log is a real directory and we symlinked it, login would\n  # write into primary. Prefer a local log dir with non-auth log files linked.\n  if [[ -d \"$primary/log\" && ! -L \"$primary/log\" ]]; then\n    if [[ -L \"$secondary/log\" ]]; then\n      rm -f \"$secondary/log\" || return 1\n    fi\n    mkdir -p \"$secondary/log\" || return 1\n    for src in \"$primary/log\"/*(N) \"$primary/log\"/.[!.]*(N); do\n      [[ -e \"$src\" || -L \"$src\" ]] || continue\n      base=\"${src:t}\"\n      [[ \"$base\" == \".\" || \"$base\" == \"..\" ]] && continue\n      _codex_auth_local_basenames \"$base\" && continue\n      dest=\"$secondary/log/$base\"\n      if [[ -L \"$dest\" ]]; then\n        current=\"$(readlink \"$dest\" 2>/dev/null || true)\"\n        [[ \"$current\" == \"$src\" ]] && continue\n        ln -sfn \"$src\" \"$dest\" || return 1\n        continue\n      fi\n      [[ -e \"$dest\" ]] && continue\n      ln -s \"$src\" \"$dest\" || return 1\n    done\n  fi\n\n  # Ensure auth.json is never a symlink after ensure.\n  if [[ -L \"$secondary/auth.json\" ]]; then\n    print -u2 -- \"refusing to use symlinked auth.json in $secondary\"\n    return 1\n  fi\n\n  return 0\n}\n\nunalias x 2>/dev/null\nx() {\n  # Default account: <personal-account> via ~/.codex   (ADAPTED: email -> placeholder)\n  CODEX_HOME=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\" \\\n    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\nunalias x2 2>/dev/null\nx2() {\n  # Secondary account: <work-account> via ~/.codex-work   (ADAPTED: email -> placeholder)\n  # Shared config/skills/sessions/etc via symlinks; local auth.json only.\n  _codex_egghead_ensure_home || return 1\n  CODEX_HOME=\"${CODEX_SECOND_HOME:-$HOME/.codex-work}\" \\\n    codex \\\n    -c 'cli_auth_credentials_store=\"file\"' \\\n    -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n\n# The resume family: every helper routes through x, so a future fix\n# to x fixes the whole family for free.\nunalias xr 2>/dev/null\nxr() { x resume \"$@\"; }            # pick a session to resume\nunalias xrl 2>/dev/null\nxrl() { x resume --last \"$@\"; }    # jump into the most recent session\nunalias xrm 2>/dev/null\nxrm() { x resume m \"$@\"; }         # resume the session named \"m\" — rename to your favorite\n\n# ====================================================== Claude Code: the clx family\n\nunalias clx clx2 clxw 2>/dev/null\nclx() { claude --dangerously-skip-permissions \"$@\"; }\n\nclx2() {  # second account (<work-account>) — same UX, separate config dir\n  local config_dir=\"${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}\"\n  mkdir -p \"$config_dir\" || return\n  CLAUDE_CONFIG_DIR=\"$config_dir\" claude --dangerously-skip-permissions \"$@\"\n}\n\nclxw() {  # launch inside a named worktree: clxw <name> [args]\n  local name=\"$1\"; shift\n  CLAUDE_WORKTREE_NAME=\"$name\" claude --worktree \"$name\" --dangerously-skip-permissions \"$@\"\n}\n\n# ============================================ Prompt-builder handoff: p-f and p-c\n# Requires the `p` prompt-builder CLI. Compose the prompt first; the handoff\n# hands the finished prompt to a zsh function that forks and resumes a session.\n\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.zsh-wrappers/agent-launchers.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n  # ADAPTED: sources this installed file; the original sources the presenter's\n  # full dotfiles module instead.\n}\n\n_codex_prompt_builder_fork() {\n  # ADAPTED: the private original forks through the presenter's app-server\n  # helpers, which can also compact the fork before resuming; that machinery\n  # is not portable. This version uses codex's built-in fork. --compact is\n  # accepted for interface compatibility but performs a plain fork.\n  local fork_from=\"last\"\n  while (( $# )); do\n    case \"$1\" in\n      --fork-from)\n        [[ $# -ge 2 ]] || { print -u2 -- \"missing value for --fork-from\"; return 2; }\n        fork_from=\"$2\"\n        shift 2\n        ;;\n      --compact)\n        shift\n        ;;\n      --)\n        shift\n        break\n        ;;\n      *)\n        break\n        ;;\n    esac\n  done\n  if [[ -z \"$fork_from\" || \"$fork_from\" == \"last\" ]]; then\n    x fork --last \"$@\"\n  else\n    x fork \"$fork_from\" \"$@\"\n  fi\n}\n\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ==================================== The cheat sheet: every family documents itself\n\nx-() {\n  # ADAPTED: lists only the functions in this curated file; the private\n  # original covers ~35 helpers.\n  local -a fn_name=(x x2 xr xrl xrm clx clx2 clxw p-f p-c)\n  local -A fn_desc=(\n    x    'Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.'\n    x2   'Second-account Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.'\n    xr   'Resume a Codex session through the base x wrapper.'\n    xrl  'Resume the most recent Codex session through the base x wrapper.'\n    xrm  'Resume the Codex conversation named m through the base x wrapper.'\n    clx  'Claude Code with permission prompts skipped.'\n    clx2 'Second-account Claude Code via CLAUDE_CONFIG_DIR=~/.claude-second.'\n    clxw 'Claude Code inside a named worktree: clxw <name> [args].'\n    p-f  'Compose a prompt in p, then fork the last Codex session and resume with it.'\n    p-c  'Compose a prompt in p, then fork and resume (the original also compacts).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-5s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n\n```"
    },
    {
      "id": "factory-zsh-launchers-questions",
      "slug": "zsh-launchers-questions",
      "title": "Thin zsh launchers and composable command families — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Tools",
      "tags": [
        "zsh-launchers",
        "questions"
      ],
      "sources": [
        {
          "label": "Thin zsh launchers and composable command families — questions and tradeoffs",
          "url": "https://sacred-ritual-w7as.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "02-zsh/dialogue.html#The room asks"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1212,
      "url": "/topics/factory-zsh-launchers-questions/",
      "markdownUrl": "/markdown/factory-zsh-launchers-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-zsh-launchers-questions.json",
      "headings": [
        {
          "id": "the-room-asks",
          "text": "The room asks",
          "level": 2
        }
      ],
      "markdown": "# Thin zsh launchers and composable command families — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The room asks\n\nWhy not just aliases?\n\nAn alias substitutes text. It can't take a positional argument in the middle, can't run setup logic, and loses quietly when a plugin defines the same name — oh-my-zsh ships single-letter aliases that would shadow half of these helpers. A function passes `\"$@\"` straight through, and an `unalias` guard makes it win any collision. Here's what my `x` function is hiding:\n\n``` text\nCODEX_HOME=~/.codex codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox\n```\n\nAnd once `x` owns that, the entire resume family is one-line compositions on top of it:\n\n``` text\nxr()  { x resume \"$@\"; }         # pick a session to resume\nxrl() { x resume --last \"$@\"; }  # jump into the most recent session\n```\n\nOkay, but I run two Codex accounts. Doesn't this fall apart the moment auth is involved?\n\nThat's what `x2` is: the same wrapper pointed at a second home directory (`CODEX_HOME=~/.codex-work`) that a helper builds by symlinking every top-level entry of the primary home *except* the auth files — and it refuses to run if an auth file would ever become a symlink. Sessions and config: shared. Credentials: never. The same trick with `CLAUDE_CONFIG_DIR` gives Claude Code a second account, and that one is simple enough to lift right now:\n\n``` text\n# claude.zsh — same pattern, different agent.\n# Placeholders (comments only — nothing below needs editing):\n#   <work-account> = the login that owns ~/.claude-second\n# Safety trade: --dangerously-skip-permissions removes permission prompts.\n\nunalias clx clx2 clxw 2>/dev/null\nclx()  { claude --dangerously-skip-permissions \"$@\"; }\n\nclx2() {  # second account (<work-account>) — same UX, separate config dir\n  local config_dir=\"${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}\"\n  mkdir -p \"$config_dir\" || return\n  CLAUDE_CONFIG_DIR=\"$config_dir\" claude --dangerously-skip-permissions \"$@\"\n}\n\nclxw() {  # launch inside a named worktree: clxw <name> [args]\n  local name=\"$1\"; shift\n  CLAUDE_WORKTREE_NAME=\"$name\" claude --worktree \"$name\" --dangerously-skip-permissions \"$@\"\n}\n```\n\nIsn't `--dangerously-bypass-approvals-and-sandbox` terrifying?\n\nIt should give you pause — the flag says so out loud. Bypass flags trade safety for speed, and the wrapper doesn't change that trade; it stops you re-deciding it forty times a day and makes the posture deliberate and visible in one place. If you don't want the bypass, your `x` simply doesn't include it — the pattern works exactly the same. Don't copy those flags unless you accept unattended file and shell access.\n\nHow do you remember fifteen two-letter functions?\n\nI don't. Every family ends in a dash function that prints its own cheat sheet — `x-` for Codex, `pi-` for pi. The docs live where you type:\n\n``` text\n$ x-\nx        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.\nx2       Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.\nxr       Resume a Codex session through the base x wrapper.\nxrl      Resume the most recent Codex session through the base x wrapper.\nxf       Run x fork; pass the conversation id/name first, then the prompt.\nxfmc     Fork conversation m, compact the fork, then resume it interactively.\np-f      Compose a prompt in p, then fork using the prompt-builder --fork-from toggle.\n# … full listing covers 35 helpers\n```\n\nThe CLI updates and renames a flag. Now every wrapper is broken at once, right?\n\nYes — that's the honest cost of composition: families inherit fixes *and* breakage. But the audit is cheap, because the same stub trick that verifies a new family also detects drift without launching anything:\n\n``` text\nzsh -n ~/.zsh-wrappers/pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'\n```\n\nRe-run `--help`, patch the one function that owns the changed flag, re-run the stub. The [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library has a drift-audit prompt that makes your agent do the whole pass.\n\nYou keep saying you \"pick the agent last.\" What does that actually mean?\n\nWrappers fix the launch, but there's a subtler mistake: choosing the agent before you've written the prompt. The `p` command — a terminal prompt builder — inverts that. Compose the prompt first, then hand it to any configured target: one prompt can go to any of three agents across five accounts.\n\n``` text\n$ p target list\npi            pi     bin=pi\ncodex         codex  bin=codex  config=shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"\nclaude        claude bin=claude\nwork-profile       codex  bin=codex  CODEX_HOME=~/.codex-work  config=cli_auth_credentials_store=\"file\" …\nclaude-second claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second\nclaude-third  claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-third\n```\n\nHelpers like `p-f` close the loop: compose in `p`, then fork the session and resume with the prompt — all free once the base wrappers exist.\n\nA new agent CLI ships next month. How long before it feels like this?\n\nAbout five minutes. Run the recipe: **wrap → compose → document → repeat**. We did it live for pi — read `--help` for the session flags, wrap each one, add the dash function, verify with a stub. The complete result, drop-in ready:\n\n``` text\n# pi-utils.zsh — the \"pir\" walkthrough result\n# Built live at the workshop following the same recipe as the x/xr family.\n# Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n# Recipe step 0 — the base wrapper already exists in the dotfiles\n# (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n# pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n# Recipe step 1 — read the CLI's own session flags:\n#   pi --help | grep -E \"resume|continue|fork|name\"\n#   --continue, -c   Continue previous session\n#   --resume, -r     Select a session to resume\n#   --fork <path|id> Fork a session into a new session\n#   --name, -n       Set session display name\n\n# Recipe step 2 — wrap each flag as a two/three-letter function.\n\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n\nunalias pit 2>/dev/null\npit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n# Recipe step 3 — every family ships its own cheat sheet (the x- convention).\npi-() {\n  local -a fn_name=(pi pir pic pif pin pit)\n  local -A fn_desc=(\n    pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n    pir 'Resume: open the session picker (pi --resume).'\n    pic 'Continue: jump straight back into the last session (pi --continue).'\n    pif 'Fork a session into a new one: pif <path|id> [prompt].'\n    pin 'Start a named session: pin <name> [prompt].'\n    pit 'Throwaway: run without saving a session (pi --no-session).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n```\n\nWant to watch that file get built prompt by prompt? That's the [Session Replay](https://sacred-ritual-w7as.here.now/replay.html) page. Both this file and the full launcher family (`agent-launchers.zsh`) are downloadable attachments — grab the install block on the [section guide](https://sacred-ritual-w7as.here.now/index.html).\n\nEvery function, flag, and output above comes from the section's verified sources — the presenter's dotfiles, captured CLI output, and the walkthrough result. Account emails are replaced with `<personal-account>` / `<work-account>` placeholders. Full caveats and provenance: the [section guide's](https://sacred-ritual-w7as.here.now/index.html) appendix."
    },
    {
      "id": "factory-zsh-launchers-reference-patterns",
      "slug": "zsh-launchers-reference-patterns",
      "title": "Thin zsh launchers and composable command families — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Tools",
      "tags": [
        "zsh-launchers",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://sacred-ritual-w7as.here.now/"
        }
      ],
      "sourceUnits": [
        "02-zsh/folio/index.html#Abstract",
        "02-zsh/folio/index.html#Notice what launching an agent really costs",
        "02-zsh/folio/index.html#Compare an alias with a defended function",
        "02-zsh/folio/index.html#Explain why composed families beat one-off wrappers",
        "02-zsh/folio/index.html#Choose the agent at prompt time, not alias time",
        "02-zsh/folio/index.html#Test the recipe: build a pi resume family",
        "02-zsh/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1984,
      "url": "/topics/factory-zsh-launchers-reference-patterns/",
      "markdownUrl": "/markdown/factory-zsh-launchers-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-zsh-launchers-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-what-launching-an-agent-really-costs",
          "text": "Notice what launching an agent really costs",
          "level": 2
        },
        {
          "id": "compare-an-alias-with-a-defended-function",
          "text": "Compare an alias with a defended function",
          "level": 2
        },
        {
          "id": "explain-why-composed-families-beat-one-off-wrappers",
          "text": "Explain why composed families beat one-off wrappers",
          "level": 2
        },
        {
          "id": "choose-the-agent-at-prompt-time-not-alias-time",
          "text": "Choose the agent at prompt time, not alias time",
          "level": 2
        },
        {
          "id": "test-the-recipe-build-a-pi-resume-family",
          "text": "Test the recipe: build a pi resume family",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Thin zsh launchers and composable command families — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nTiny zsh functions are the cheapest layer of an agentic system. This document argues five steps: agent CLIs impose a real flag-recall tax; a two-letter wrapper function removes it; composing wrappers into families multiplies the payoff; a self-printing cheat sheet keeps the layer discoverable; and the recipe repeats for any new CLI, shown here by building a resume family for the pi agent. All evidence comes from one machine's working configuration, so treat the specific flags as examples, not standards.\n\n## Notice what launching an agent really costs\n\nYou start a coding agent many times a day. Each launch needs the same environment variable, the same config override, and the same sandbox flag. The common mistake is to lean on shell history: you search backward, hope the right variant surfaces, and sometimes launch with a flag missing. A launch with a missing flag is worse than a failed launch, because the agent starts in a different permission posture than you expect.\n\nThe dotfiles solve this with a one-letter function. The `x` function pins the Codex home directory, injects a config marker, and applies the sandbox-bypass flag in one place (source S1, `conf.d/40-ai.zsh`). [1](https://sacred-ritual-w7as.here.now/#note-1)\n\n1\\. The config override sets `CODEX_LOAD_ZSH_DSL=\"1\"` in the agent's shell environment. The same dotfiles use that marker to expose their shell helpers inside agent tool shells (S1, S3). [↩](https://sacred-ritual-w7as.here.now/#note-ref-1)\n\n``` text\n# ~/.config/zsh/conf.d/40-ai.zsh — the real wrapper (email replaced)\nunalias x 2>/dev/null\nx() {\n  # Default account: <personal-account> via ~/.codex\n  CODEX_HOME=\"${CODEX_PRIMARY_HOME:-$HOME/.codex}\" \\\n    codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n    --dangerously-bypass-approvals-and-sandbox \"$@\"\n}\n```\n\n**Figure 1.** Source evidence: the `x` function, quoted from S1 with one comment edited to replace a personal email address.\n\n**Safety trade** The `--dangerously-bypass-approvals-and-sandbox` flag removes the agent's approval prompts. The wrapper makes that posture deliberate and visible in one place, but it does not make it safe. Do not copy the flag into your own wrapper unless you accept unattended file and shell access.\n\nTry the check yourself: run `which x` in a shell where the wrapper is loaded. If it prints a function body with every flag pinned, launches can no longer drift. If it prints nothing, or prints an alias, you are still paying the recall tax. Your next move is an inventory: write down every agent command you retyped this week.\n\n## Compare an alias with a defended function\n\nThe tempting shortcut is an alias. An alias substitutes text; it cannot take a positional argument in the middle, cannot run setup logic, and loses quietly when a plugin defines the same name. A function can do all three. The dotfiles treat that last risk as real: nearly every definition starts with `unalias <name> 2>/dev/null`, because oh-my-zsh ships single-letter aliases that would otherwise shadow the function (S1).\n\nThe same wrapper shape repeats across a second agent. The `clx` family wraps Claude Code exactly the way `x` wraps Codex: base flags in the short name, an environment variable for the second account, a positional argument for worktrees (S1).\n\n``` text\nclx()  { claude --dangerously-skip-permissions \"$@\"; }\n\nclx2() {\n  local config_dir=\"${CLAUDE_SECOND_CONFIG_DIR:-$HOME/.claude-second}\"\n  mkdir -p \"$config_dir\" || return\n  CLAUDE_CONFIG_DIR=\"$config_dir\" claude --dangerously-skip-permissions \"$@\"\n}\n\nclxw() {\n  local name=\"$1\"; shift\n  CLAUDE_WORKTREE_NAME=\"$name\" claude --worktree \"$name\" --dangerously-skip-permissions \"$@\"\n}\n```\n\n**Figure 2.** Source evidence: three members of the Claude Code family, quoted from S1. Note what an alias cannot do here: `clxw` consumes its first argument before passing the rest through.\n\nWrappers also absorb upstream bugs. The `pi` wrapper deletes a malformed lock file before every launch, so a known failure in the pi agent's locking library never reaches the user (source S2, `local.zsh`). [2](https://sacred-ritual-w7as.here.now/#note-2)\n\n2\\. The source comment explains the mechanism: pi's lockfile dependency expects a directory at `auth.json.lock`. A stray regular file there causes recurring auth failures, so the wrapper removes it (S2). [↩](https://sacred-ritual-w7as.here.now/#note-ref-2)\n\nThe decision rule: reach for an alias only when the command is pure text substitution with no arguments, no environment, and no collision risk. Otherwise write a function with the `unalias` guard and `\"$@\"` pass-through. The feedback signal is the same as before — `which <name>` tells you which one you actually got.\n\n## Explain why composed families beat one-off wrappers\n\nA single wrapper saves keystrokes. The compounding payoff appears when wrappers call other wrappers. If `x` owns the account and the flags, then every session action becomes a one-line composition on top of it — and inherits any future fix to `x` for free.\n\nThe dotfiles build a whole resume-and-fork vocabulary this way: `xr` resumes, `xrl` resumes the last session, `xrm` resumes a session named \"m\", and `xfmc` forks that session, compacts the fork, and resumes it — all routed through `x` (S1).\n\n``` text\nxr()  { x resume \"$@\"; }\nxrl() { x resume --last \"$@\"; }\nxrm() { x resume m \"$@\"; }\nxf()  { x fork \"$@\"; }\n\nxfmc() {\n  local fork_id\n  fork_id=\"$(_codex_app_server_fork_compact_latest m)\" || return 1\n  print -r -- \"$fork_id\"\n  _codex_cmux_name_current_tab\n  x resume \"$fork_id\" \"$@\"\n}\n```\n\n**Figure 3.** Source evidence: the resume and fork family, quoted from S1. Each helper is a thin composition over `x`; only `xfmc` adds real logic.\n\nComposition also solves multi-account work. The `x2` function runs the same agent under a second account by pointing `CODEX_HOME` at a second directory that shares the primary's state through symlinks — while auth files stay local to each account (S1). [3](https://sacred-ritual-w7as.here.now/#note-3)\n\n3\\. A helper named `_codex_egghead_ensure_home` builds the second home. It symlinks every top-level entry except auth-related names such as `auth.json`, and it refuses to run if the auth file ever becomes a symlink (S1). Accounts share sessions and config, never credentials. [↩](https://sacred-ritual-w7as.here.now/#note-ref-3)\n\nA family this large needs its own memory aid, and the dotfiles make the family print one. Running `x-` lists every helper with a one-line description, straight from the same file that defines them (S1; output captured in S3).\n\n``` text\nx        Primary Codex (<personal-account> / ~/.codex) with agent-safe zsh DSL marker.\nx2       Secondary Codex (<work-account> / ~/.codex-work); shared state via symlinks, local auth only.\nxr       Resume a Codex session through the base x wrapper.\nxrl      Resume the most recent Codex session through the base x wrapper.\nxf       Run x fork; pass the conversation id/name first, then the prompt.\nxfmc     Fork conversation m, compact the fork, then resume it interactively.\np-f      Compose a prompt in p, then fork using the prompt-builder --fork-from toggle.\n```\n\n**Figure 4.** Source evidence: excerpt of the `x-` cheat sheet captured the recorded snapshot (S3). Email addresses are replaced with placeholders; the full listing covers 35 helpers.\n\n**Drift risk** Composed families inherit fixes, but they also inherit breakage. When the underlying CLI renames a subcommand or flag, every wrapper above it fails at once. The cheat-sheet function reduces the cost of the audit; it does not remove the need for one.\n\nThe test for your own setup: pick your most common session action — resuming — and count the keystrokes it takes today. If the answer is more than three or four, you have found the first family worth building.\n\n## Choose the agent at prompt time, not alias time\n\nWrappers fix the launch. They do not fix a second, subtler mistake: deciding which agent to use before you have written the prompt. Once the prompt exists, you often realize it belongs to a different agent, a different account, or a forked copy of an old session.\n\nThe `p` command inverts the order. It is a separate terminal program — \"Terminal prompt builder for handing prompts to Pi, Codex, or Claude Code,\" in its own help text — that lets you compose the prompt first and then launch any configured target with it (S3).\n\n``` text\n$ p target list\npi            pi     bin=pi\ncodex         codex  bin=codex   config=shell_environment_policy...\nclaude        claude bin=claude\nwork-profile       codex  bin=codex   CODEX_HOME=~/.codex-work ...\nclaude-second claude bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second\nclaude-third  claude bin=claude  CLAUDE_CONFIG_DIR=~/.claude-third\n```\n\n**Figure 5.** Source evidence: launch targets captured the recorded snapshot (S3), abbreviated to fit. One prompt can go to any of three agents across five accounts.\n\nThe two layers then compose with each other. Helpers such as `p-f` and `p-c` open the prompt builder, and hand the finished prompt to a zsh function that forks a session, optionally compacts it, and resumes it (S1).\n\nYou can rehearse this without launching anything: `p --print-prompt \"explain this repo\"` prints the composed prompt and exits, and `--dry-run` skips the launch entirely (S3). If the printed prompt matches what you meant to send, the pipeline is wired correctly. The limit to keep in mind: the target list above is one machine's configuration file, not a default that ships with the tool.\n\n## Test the recipe: build a pi resume family\n\nThe claim that this recipe repeats \"in minutes\" is testable, and the workshop tests it live. The pi agent has a base wrapper but no session helpers yet. Step one is always the same: ask the CLI what it can do, instead of guessing.\n\n``` text\n$ pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n  --continue, -c        Continue previous session\n  --resume, -r          Select a session to resume\n  --fork <path|id>      Fork specific session file or partial UUID into a new session\n  --name, -n <name>     Set session display name\n  --no-session          Don't save session (ephemeral)\n```\n\n**Figure 6.** Source evidence: session flags from pi's own help output, version 0.80.10, captured the recorded snapshot (S3).\n\nEach flag becomes one short function, and the family gets its own cheat sheet in the `x-` style. This is the exact file built for the workshop (source S4, `demo/pi-utils.zsh`).\n\n``` text\npir() { pi --resume \"$@\"; }        # pick a session to resume\npic() { pi --continue \"$@\"; }      # continue the most recent session\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id>\npin() {                            # start a named session\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\npit() { pi --no-session \"$@\"; }    # throwaway session\n```\n\n**Figure 7.** Source evidence: the new pi family, quoted from S4. A `pi-` cheat-sheet function completes the file.\n\n``` text\n$ zsh -n demo/pi-utils.zsh && echo \"syntax OK\"\nsyntax OK\n$ zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source demo/pi-utils.zsh; pir --check'\n[stub pi] --resume --check\n```\n\n**Figure 8.** Derived display: the verification run from the recorded snapshot (S4), reformatted from the build log. A stub replaces the real binary, proving each helper passes the intended flags.\n\n**Evidence limit** The stub test proves flag wiring, not end-to-end behavior. A live `pir` only opens the session picker when pi has saved sessions on that machine. The sources also do not measure the \"five minutes\" figure; it is the presenter's estimate for this walkthrough.\n\nRun the same two commands against any wrapper file you write. Syntax check first, stub test second. If the stub echoes the flags you expected, load the file for real and watch `pir` open the picker. If it echoes something else, the bug is in your function, not in the agent — which is exactly where you want bugs to live.\n\n## Practical action\n\nApply the recipe to one agent CLI this week:\n\n1.  **Capture** the exact launch command you retype most, flags and all.\n2.  **Wrap** it: `unalias` guard, short function name, env pinning inside, `\"$@\"` at the end.\n3.  **Compose** the first family on top — resume is usually the highest-value action.\n4.  **Document** with a `<name>-` cheat-sheet function so the family stays discoverable.\n5.  **Verify** with `zsh -n`, then a stub test, before sourcing it in your real shell.\n\nSuccess looks like this: a week later, `which` shows functions instead of history searches, and the cheat sheet answers \"what was that helper called?\" without leaving the terminal. If a wrapper breaks after a CLI update, that is the drift caveat arriving on schedule — re-run the CLI's `--help` and adjust the one function that owns the changed flag."
    },
    {
      "id": "factory-zsh-launchers-worked-example",
      "slug": "zsh-launchers-worked-example",
      "title": "Thin zsh launchers and composable command families — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Tools",
      "tags": [
        "zsh-launchers",
        "examples"
      ],
      "sources": [
        {
          "label": "Thin zsh launchers and composable command families — worked example",
          "url": "https://sacred-ritual-w7as.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "02-zsh/replay.html#The session",
        "02-zsh/replay.html#Run this session yourself"
      ],
      "collection": "factory",
      "categoryId": "tools",
      "wordCount": 1172,
      "url": "/topics/factory-zsh-launchers-worked-example/",
      "markdownUrl": "/markdown/factory-zsh-launchers-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-zsh-launchers-worked-example.json",
      "headings": [
        {
          "id": "the-session",
          "text": "The session",
          "level": 2
        },
        {
          "id": "run-this-session-yourself",
          "text": "Run this session yourself",
          "level": 2
        }
      ],
      "markdown": "# Thin zsh launchers and composable command families — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session\n\npi had a base wrapper but no session helpers — the whole point of the walkthrough is that the gap closes in minutes. This transcript restages the section's scripted walkthrough as prompts to a coding agent; every output shown is the captured output from a prior session.\n\nYou\n\nRun `pi --help` and pull out the session flags — resume, continue, fork, whatever it actually ships.\n\nAgent\n\nRan the help command and filtered for the session verbs:\n\n``` text\n$ pi --help | grep -E -- \"--resume|--continue|--fork|--name|--no-session\"\n  --continue, -c        Continue previous session\n  --resume, -r          Select a session to resume\n  --fork <path|id>      Fork specific session file or partial UUID into a new session\n  --name, -n <name>     Set session display name\n  --no-session          Don't save session (ephemeral)\n```\n\nFirst beat is always reconnaissance. You never invent verbs — every flag the CLI ships is a candidate wrapper, and nothing else is.\n\nYou\n\nWrap each flag as a two- or three-letter function in `pi-utils.zsh`, following my `x`-family convention: `unalias` guard first, one short function per flag, comment on the same line.\n\nAgent\n\nWrote the one-liners. Each is a single line on top of the existing `pi` wrapper — the one that already heals the `auth.json.lock` bug before launching the binary:\n\n``` text\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n```\n\nComposition, not duplication: the flags live in exactly one place. This is the same shape as `xr() { x resume \"$@\" }` in the Codex family — a future fix to the base wrapper fixes every helper for free.\n\nYou\n\n`pin` takes an argument — a session name. Guard it so it fails loudly with usage instead of launching with a blank name.\n\nAgent\n\n``` text\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n```\n\nAlso added `pit` for `--no-session` throwaway runs.\n\nThe one wrapper that outgrows a one-liner earns a body — but only just. Guard clauses over silent failure.\n\nYou\n\nFinish with the cheat sheet: a `pi-` function that prints the whole family, the way `x-` does for the Codex family.\n\nAgent\n\nWrote `pi-` — a name array plus a description map, printed as an aligned table. Its output is in the verification run below.\n\nEvery family ships its own cheat sheet — the `fn-` convention. Six months from now, `pi-` answers \"what did I name these?\" without leaving the shell.\n\nYou\n\nVerify without launching anything real: syntax check the file, then prove each helper passes the right flag.\n\nAgent\n\nRan `zsh -n`, then a stub test that shadows `pi` with a function so nothing actually launches:\n\n``` text\nzsh -n ~/.zsh-wrappers/pi-utils.zsh && echo \"syntax OK\"\nzsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pi-; pir --check'\n```\n\n``` text\nsyntax OK\npi   Base wrapper: heals the auth.json.lock bug, then runs the pi binary.\npir  Resume: open the session picker (pi --resume).\npic  Continue: jump straight back into the last session (pi --continue).\npif  Fork a session into a new one: pif <path|id> [prompt].\npin  Start a named session: pin <name> [prompt].\npit  Throwaway: run without saving a session (pi --no-session).\n[stub pi] --resume --check\n```\n\nThe stub proves wiring — which flags each helper passes — not behavior. A live `pir` opens pi's session picker only when saved sessions exist on the machine.\n\nAgent\n\nFile landed. Complete and drop-in ready:\n\n``` text\n# pi-utils.zsh — the \"pir\" walkthrough result\n# Built live at the workshop following the same recipe as the x/xr family.\n# Source it:  source ~/.zsh-wrappers/pi-utils.zsh   then run:  pi-\n\n# Recipe step 0 — the base wrapper already exists in the dotfiles\n# (~/.config/zsh/local.zsh): pi() heals a lockfile bug, then execs the real\n# pi binary. Every helper below composes on top of `pi`, never the raw binary.\n\n# Recipe step 1 — read the CLI's own session flags:\n#   pi --help | grep -E \"resume|continue|fork|name\"\n#   --continue, -c   Continue previous session\n#   --resume, -r     Select a session to resume\n#   --fork <path|id> Fork a session into a new session\n#   --name, -n       Set session display name\n\n# Recipe step 2 — wrap each flag as a two/three-letter function.\n\nunalias pir 2>/dev/null\npir() { pi --resume \"$@\"; }        # pick a session to resume (pi resume)\n\nunalias pic 2>/dev/null\npic() { pi --continue \"$@\"; }      # continue the most recent session\n\nunalias pif 2>/dev/null\npif() { pi --fork \"$@\"; }          # fork a session: pif <path|id> [prompt]\n\nunalias pin 2>/dev/null\npin() {                            # start a named session: pin <name> [prompt]\n  local name=\"${1:?Usage: pin <name> [prompt...]}\"; shift\n  pi --name \"$name\" \"$@\"\n}\n\nunalias pit 2>/dev/null\npit() { pi --no-session \"$@\"; }    # throwaway session (nothing saved)\n\n# Recipe step 3 — every family ships its own cheat sheet (the x- convention).\npi-() {\n  local -a fn_name=(pi pir pic pif pin pit)\n  local -A fn_desc=(\n    pi  'Base wrapper: heals the auth.json.lock bug, then runs the pi binary.'\n    pir 'Resume: open the session picker (pi --resume).'\n    pic 'Continue: jump straight back into the last session (pi --continue).'\n    pif 'Fork a session into a new one: pif <path|id> [prompt].'\n    pin 'Start a named session: pin <name> [prompt].'\n    pit 'Throwaway: run without saving a session (pi --no-session).'\n  )\n  local fn\n  for fn in \"${fn_name[@]}\"; do\n    printf '%-4s %s\\n' \"$fn\" \"${fn_desc[$fn]}\"\n  done\n}\n```\n\nFive prompts, one file. The recipe the transcript demonstrates — **wrap → compose → document → repeat** — is the whole section; it repeats for every new agent CLI. This file and the full launcher family (`agent-launchers.zsh`) are downloadable attachments — grab the install block on the [section guide](https://sacred-ritual-w7as.here.now/index.html).\n\n## Run this session yourself\n\nPaste this into your own coding agent to replay the whole session against your machine — it is the same prompt from the [section guide's](https://sacred-ritual-w7as.here.now/index.html) prompt library.\n\n``` text\nBuild me a two-letter zsh wrapper family for the pi CLI.\n\n1. Run `pi --help` and list the session flags: --resume, --continue, --fork, --name, --no-session.\n2. Create ~/.zsh-wrappers/pi-utils.zsh. For each flag define a short function that calls `pi <flag> \"$@\"`: pir (resume), pic (continue), pif (fork), pin (named session — take the name as $1, error if it is missing), pit (no-session). Guard every definition with `unalias <name> 2>/dev/null`.\n3. Add a `pi-` cheat-sheet function that prints each helper name and a one-line description.\n4. Verify: run `zsh -n ~/.zsh-wrappers/pi-utils.zsh`, then this stub test:\n   zsh -fc 'pi() { echo \"[stub pi] $@\"; }; source ~/.zsh-wrappers/pi-utils.zsh; pir --check'\n   Expect: [stub pi] --resume --check\n5. Show me the file and the exact `source` line to add to my ~/.zshrc. Do not edit ~/.zshrc yourself.\n```"
    },
    {
      "id": "foundations-multimodal-design-and-model-routing",
      "slug": "multimodal-design-and-model-routing",
      "title": "Use images, video, and task-shaped model routing",
      "summary": "Run CMUX as a primary orchestrator with token-efficient flash models; Use image generation as a design reference and hand off image-to-design; Prompt with video and navigate the MCP-vs-CLI boundary.",
      "category": "Tools",
      "tags": [
        "images",
        "video",
        "models",
        "CLI"
      ],
      "sources": [
        {
          "label": "Agent foundations: Use images, video, and task-shaped model routing (authorized access required)",
          "url": "https://codex-workshop-followup.pages.dev/lesson-06.html"
        }
      ],
      "sourceUnits": [
        "oracle/lessons.json#06/objectives",
        "oracle/06-references.json#recap",
        "oracle/06-references.json#concepts/0",
        "oracle/06-references.json#concepts/1",
        "oracle/06-references.json#concepts/2",
        "oracle/06-references.json#concepts/3",
        "oracle/06-references.json#concepts/4",
        "oracle/06-references.json#references",
        "oracle/06-references.json#recommendations",
        "oracle/06-interactive.json#intro",
        "oracle/06-interactive.json#checklist",
        "oracle/06-interactive.json#challenges",
        "oracle/06-interactive.json#quiz",
        "oracle/06-interactive.json#reflect",
        "oracle/06-references.json#goDeeper",
        "materials/exercises.md#Chunk-06",
        "materials/qa-index.md#Q025",
        "materials/qa-index.md#Q026",
        "materials/qa-index.md#Q027",
        "materials/qa-index.md#Q028",
        "materials/qa-index.md#Q029",
        "materials/qa-index.md#Q030",
        "materials/qa-index.md#Q031",
        "materials/qa-index.md#Q032",
        "materials/qa-index.md#Q033",
        "materials/qa-index.md#Q034",
        "final/qa-index.md#Chunk-06",
        "materials/keyframes.md#Chunk-06",
        "lesson-06.html#resource-packet",
        "lesson-06.html#clip-map",
        "lesson-06.html#recording"
      ],
      "collection": "foundations",
      "categoryId": "tools",
      "wordCount": 3052,
      "url": "/topics/foundations-multimodal-design-and-model-routing/",
      "markdownUrl": "/markdown/foundations-multimodal-design-and-model-routing.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/foundations-multimodal-design-and-model-routing.json",
      "headings": [
        {
          "id": "working-outcomes",
          "text": "Working outcomes",
          "level": 2
        },
        {
          "id": "concepts-and-consequences",
          "text": "Concepts and consequences",
          "level": 2
        },
        {
          "id": "cmux-as-a-primary-orchestrator",
          "text": "CMUX as a primary orchestrator",
          "level": 3
        },
        {
          "id": "model-choice-by-task-shape",
          "text": "Model choice by task shape",
          "level": 3
        },
        {
          "id": "image-generation-as-design-reference",
          "text": "Image generation as design reference",
          "level": 3
        },
        {
          "id": "video-prompting-for-high-context-intent",
          "text": "Video prompting for high-context intent",
          "level": 3
        },
        {
          "id": "mcp-versus-cli-boundaries",
          "text": "MCP versus CLI boundaries",
          "level": 3
        },
        {
          "id": "reference-tools-and-resources",
          "text": "Reference tools and resources",
          "level": 2
        },
        {
          "id": "cmux",
          "text": "CMUX",
          "level": 3
        },
        {
          "id": "codex-cli",
          "text": "Codex CLI",
          "level": 3
        },
        {
          "id": "google-gemini-video-prompting",
          "text": "Google Gemini video prompting",
          "level": 3
        },
        {
          "id": "impeccable",
          "text": "Impeccable",
          "level": 3
        },
        {
          "id": "gogcli",
          "text": "gogcli",
          "level": 3
        },
        {
          "id": "recommendations-and-best-practices",
          "text": "Recommendations and best practices",
          "level": 2
        },
        {
          "id": "practice-and-acceptance-criteria",
          "text": "Practice and acceptance criteria",
          "level": 2
        },
        {
          "id": "checklist",
          "text": "Checklist",
          "level": 3
        },
        {
          "id": "four-pane-orchestrator-drill",
          "text": "Four-Pane Orchestrator Drill",
          "level": 3
        },
        {
          "id": "reference-first-component-direction",
          "text": "Reference-First Component Direction",
          "level": 3
        },
        {
          "id": "video-extraction-brief",
          "text": "Video Extraction Brief",
          "level": 3
        },
        {
          "id": "boundary-audit-and-refactor",
          "text": "Boundary Audit and Refactor",
          "level": 3
        },
        {
          "id": "questions-to-test-understanding",
          "text": "Questions to test understanding",
          "level": 2
        },
        {
          "id": "why-does-the-lesson-recommend-using-cmux-as-a-primary-orchestrator-instead-of-running-one-huge-agent-thread",
          "text": "Why does the lesson recommend using CMUX as a primary orchestrator instead of running one huge agent thread?",
          "level": 3
        },
        {
          "id": "which-task-is-the-best-fit-for-a-fast-flash-style-model-in-this-lesson-s-routing-approach",
          "text": "Which task is the best fit for a fast Flash-style model in this lesson's routing approach?",
          "level": 3
        },
        {
          "id": "what-is-the-main-advantage-of-generating-image-variations-before-asking-an-agent-to-build-a-ui",
          "text": "What is the main advantage of generating image variations before asking an agent to build a UI?",
          "level": 3
        },
        {
          "id": "what-did-john-say-makes-video-prompting-valuable",
          "text": "What did John say makes video prompting valuable?",
          "level": 3
        },
        {
          "id": "what-is-the-lesson-s-practical-rule-of-thumb-for-mcp-versus-cli-boundaries",
          "text": "What is the lesson's practical rule of thumb for MCP versus CLI boundaries?",
          "level": 3
        },
        {
          "id": "reflection-prompts",
          "text": "Reflection prompts",
          "level": 2
        },
        {
          "id": "further-applications",
          "text": "Further applications",
          "level": 2
        },
        {
          "id": "applied-exercises",
          "text": "Applied exercises",
          "level": 2
        },
        {
          "id": "questions-and-answers",
          "text": "Questions and answers",
          "level": 2
        },
        {
          "id": "okay-and-also-this-you-wrote-create-a-primary-terminal-that-coordinates-focused-agents-will-you-go-into-that-or-was-that-already-that-part-where-you-had-the-timestamp-created",
          "text": "Okay, and also this, you wrote, create a primary terminal that coordinates focused agents. Will you go into that, or was that already that part where you had the timestamp created?",
          "level": 3
        },
        {
          "id": "also-what-is-the-when-i-m-already-at-it-what-is-that-cursor-thing-where-you-can-draw-did-you-mention-that",
          "text": "Also, what is the… when I'm already at it, what is that cursor thing where you can draw? Did you mention that?",
          "level": 3
        },
        {
          "id": "any-preference-on-which-agent-to-use-for-which-task",
          "text": "any preference on which agent to use for which task",
          "level": 3
        },
        {
          "id": "if-i-m-automating-a-workflow-in-typescript",
          "text": "if i'm automating a workflow in typescript",
          "level": 3
        },
        {
          "id": "how-do-you-mentally-keep-up-with-heavy-context-switching",
          "text": "How do you mentally keep up with heavy context-switching?",
          "level": 3
        },
        {
          "id": "what-do-you-use-scheduling-for-loops",
          "text": "what do you use scheduling for? loops?",
          "level": 3
        },
        {
          "id": "are-you-a-fan-of-these-fully-hackable-harnesses-like-pi-dev",
          "text": "Are you a fan of these fully hackable harnesses like pi.dev ?",
          "level": 3
        },
        {
          "id": "have-you-used-claude-design-its-pretty-good",
          "text": "have you used claude design? its pretty good",
          "level": 3
        },
        {
          "id": "do-you-limit-your-mcps-have-skills-call-the-mcps-instead-saw-executor-post-as-well",
          "text": "do you limit your mcps? have skills call the mcps instead? saw executor post as well",
          "level": 3
        },
        {
          "id": "do-you-have-any-ideas-on-how-to-create-levers-for-agents-so-they-can-do-big-data-stuff-without-having-all-the-data-in-their-context",
          "text": "Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context?",
          "level": 3
        },
        {
          "id": "operational-playbooks",
          "text": "Operational playbooks",
          "level": 2
        },
        {
          "id": "recording-references",
          "text": "Recording references",
          "level": 2
        },
        {
          "id": "visual-reference-index",
          "text": "Visual reference index",
          "level": 3
        }
      ],
      "markdown": "# Use images, video, and task-shaped model routing\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nThe practice is turning vague intent into useful signals your agents can actually build from: split work into focused CMUX sessions, pick models based on the shape of the task, use generated images as concrete design references, and use video when a sequence of code or UI state matters. John also draws a practical boundary between deterministic scripts or CLIs, fuzzy agent reasoning, MCP wrappers, and operational tools: do not over-abstract when a simple command would be clearer, safer, and easier to reason about.\n\n## Working outcomes\n\n- Run CMUX as a primary orchestrator with token-efficient flash models\n- Use image generation as a design reference and hand off image-to-design\n- Prompt with video and navigate the MCP-vs-CLI boundary\n\n## Concepts and consequences\n\n### CMUX as a primary orchestrator\n\nJohn demonstrates a main CMUX session opening specialized Codex panes for quality control, performance, research, and notes. The main pane becomes the coordinator, while each child pane has a narrow role and can work independently.\n\n**Why it matters:** This keeps context cleaner and makes delegation visible. It gives you a practical way to monitor several agent tracks without dumping every task into one large prompt thread.\n\n### Model choice by task shape\n\nJohn frames Codex as his default coding worker, especially when goal-following and token efficiency matter. Claude can be useful as a conversational manager or design helper, while Flash-style models are best for quick, tightly scoped tasks and weaker for long chains that require self-correction.\n\n**Why it matters:** Good model choice is a cost and reliability decision, not a brand preference. Matching the model to the task reduces wasted tokens and lowers the odds of an agent spiraling while trying to fix its own mistake.\n\n### Image generation as design reference\n\nFor UI work, John recommends generating sheets of visual variations before committing to a direction. For example, he describes taking a screenshot of a component and asking for many variations, then picking the favorite as the design direction.\n\n**Why it matters:** Images collapse ambiguity. They let non-designers express taste through selection, which is often easier than inventing exact CSS, spacing, motion, and layout language from scratch.\n\n### Video prompting for high-context intent\n\nJohn describes uploading video to Gemini by hand and also using scripts that upload to Google's backend to extract code snippets, key parts, timestamps, and screenshots. Video can preserve the flow of a demo or code walkthrough better than a written description because the model sees the sequence of states.\n\n**Why it matters:** When the task depends on timing, UI state, or code changing over time, video can carry intent that text misses. The practical caveat he names is that scripted backend use can involve cost and auth-token setup.\n\n### MCP versus CLI boundaries\n\nJohn warns that it can get weird to build a skill just to call an MCP wrapper when the skill could have called a CLI directly. His broader rule is to define boundaries around what needs tests, what needs flexibility, where memory belongs, and which agents should have access to which tools.\n\n**Why it matters:** Clear boundaries make agent systems easier to reason about. If a workflow is deterministic and testable, a direct CLI or script may be simpler than an unnecessary MCP layer; use agent reasoning where judgment, interpretation, or flexible planning actually adds value.\n\n## Reference tools and resources\n\n### CMUX\n\nThe workspace John uses to automate terminal tabs and panes, launch Codex sessions, name them by role, and coordinate multiple focused agent tracks.\n\n**Use when:** Reach for it when you want a visible multi-agent command center where one main session can create, name, monitor, and delegate to focused panes.\n\n[Reference](https://github.com/manaflow-ai/cmux)\n\n### Codex CLI\n\nThe coding agent John uses as his default programming worker in the workshop, especially for goal-driven implementation tasks and token-efficient coding work.\n\n**Use when:** Reach for it when the task is real code work that needs persistence, goal-following, and stronger follow-through than a tiny one-shot model.\n\nsearch: OpenAI Codex CLI\n\n### Google Gemini video prompting\n\nThe multimodal workflow John describes for processing screencasts into timestamps, screenshots, code snippets, and key moments.\n\n**Use when:** Reach for it when text alone is not enough to explain a demo, code walkthrough, or UI behavior over time.\n\nsearch: Google Gemini API video understanding\n\n### Impeccable\n\nA visual design-to-code workflow John briefly highlights as aligned with his image-to-design approach. He notes its recent npx impeccable CLI, Design.md output, generated-image workflow, and motion/delight features, but does not walk through using it.\n\n**Use when:** Reach for it when you want to explore turning generated design images into frontend implementation, while recognizing this section only gives a high-level overview.\n\nsearch: Impeccable npx impeccable CLI\n\n### gogcli\n\nA Google CLI workflow repository John shared while describing account automation across email and other Google services.\n\n**Use when:** Reach for it when exploring operational automation around Google account data, but be careful because these workflows can read, draft, send, or otherwise act on real account information.\n\n[Reference](https://github.com/openclaw/gogcli)\n\n## Recommendations and best practices\n\n- Create a reusable CMUX setup prompt that opens four panes with explicit roles such as Research, Quality Control, Performance, and Notes, then practice delegating one real subtask to a named pane.\n- Use Codex for coding work that needs goal-following and persistence. Use Claude when conversation or design help matters. Use Flash-style models for quick, tightly scoped tasks where speed matters and failure is cheap.\n- Before asking an agent to build or revise a UI, generate a sheet of visual variations and pick the direction you actually like. A selected reference image beats a vague taste prompt.\n- Use video when the important part is a sequence: a demo, a changing UI, a code walkthrough, or a moment where timestamps and screenshots matter.\n- Expect scripted video processing through Google's backend to involve auth-token setup and cost, even if manual drag-and-drop is still useful.\n- Keep deterministic automation in scripts or CLIs, and reserve agent reasoning for decisions, interpretation, and fuzzy planning. Do not wrap a CLI in MCP just because MCP is available.\n- Be careful with Google CLI-style account automation. John's example was powerful precisely because it could gather information and act on real email/account workflows.\n- Use a physical Pomodoro or off-keyboard reset ritual if you run many agents at once. The point is to force your brain to stop monitoring every pane continuously.\n- For scheduling, monitor actual outputs such as git diffs, PRs, Slack, email, or agent progress rather than only summarizing chat logs.\n\n## Practice and acceptance criteria\n\nPractice turning messy visual intent into concrete agent instructions using CMUX, generated references, video context, and clear tool boundaries.\n\n### Checklist\n\n1. Create a CMUX setup prompt that opens four named Codex sessions: Research, Quality Control, Performance, and Notes.\n2. Seed each pane with a narrow role prompt that states what it should inspect, produce, and avoid doing.\n3. Delegate one real subtask from the main pane to a specific child pane, then verify the main context stays clean.\n4. Pick one UI component or screenshot and generate a sheet of visual variations before asking an agent to code anything.\n5. Choose one favorite reference image and use it as the concrete design direction in the implementation prompt.\n6. Record a short screencast of a code or UI walkthrough, then ask a video-capable model for timestamps, screenshots, code snippets, and key moments.\n7. Audit one automation idea by separating deterministic scripts or CLIs from agent inference and MCP/tool access.\n8. Create one monitoring routine that checks actual git diffs or other real outputs instead of only summarizing agent conversation.\n\n### Four-Pane Orchestrator Drill\n\n**Difficulty:** Easy\n\nIn CMUX, write and run a setup prompt that creates Research, Quality Control, Performance, and Notes panes, then delegate a small codebase investigation to exactly one pane.\n\n**Done when:** The named panes open with distinct roles, the delegated pane produces a useful result, and the main pane can summarize progress without copying every child conversation.\n\n### Reference-First Component Direction\n\n**Difficulty:** Medium\n\nChoose a real component from a local project, generate a sheet of visual alternatives, select one direction, and hand that image plus a focused implementation request to Codex or your preferred coding agent.\n\n**Done when:** The implementation request points to one selected visual direction, and the resulting diff is focused on the intended component or files.\n\n### Video Extraction Brief\n\n**Difficulty:** Medium\n\nRecord a short screencast of a code or UI walkthrough, process it with a video-capable model, and turn the output into a brief with timestamps, screenshots, code snippets, and key moments.\n\n**Done when:** Someone who has not watched the full video can understand the important moments and where to look in the code or UI.\n\n### Boundary Audit and Refactor\n\n**Difficulty:** Hard\n\nTake one workflow that currently uses an agent for everything and redesign it so deterministic steps run through scripts or CLIs, fuzzy decisions stay with agents, and tool access boundaries are explicit.\n\n**Done when:** The final workflow has a clear boundary map, at least one testable CLI or script step, and a written explanation of what needs tests versus what needs flexibility.\n\n## Questions to test understanding\n\n### Why does the lesson recommend using CMUX as a primary orchestrator instead of running one huge agent thread?\n\n- **A.** It keeps each agent role focused and lets the main session coordinate work without mixing every task into one context.\n- **B.** It guarantees every child agent will produce correct code without review.\n- **C.** It replaces the need for Git, tests, or browser inspection.\n- **D.** It is only useful when all agents use the same model.\n\n**Answer: A.** The point is visible delegation: research, quality, performance, and notes can each run in a narrow context while the main pane coordinates. That reduces context mess and makes monitoring easier.\n\n### Which task is the best fit for a fast Flash-style model in this lesson's routing approach?\n\n- **A.** A long, multi-step refactor that will likely require repeated self-correction.\n- **B.** A small, tightly scoped task where speed matters and failure is cheap.\n- **C.** Owning the entire frontend implementation from scratch with no supervision.\n- **D.** Replacing deterministic scripts, CLIs, and tests.\n\n**Answer: B.** Flash-style models are useful when the task is constrained and speed matters. John warns that they can burn tokens or fall off the rails when forced into long sequential repair loops.\n\n### What is the main advantage of generating image variations before asking an agent to build a UI?\n\n- **A.** It removes the need to describe acceptance criteria.\n- **B.** It lets the learner select a concrete visual direction instead of relying on vague taste words.\n- **C.** It guarantees the implementation will match the image pixel-perfectly.\n- **D.** It prevents the agent from needing access to the codebase.\n\n**Answer: B.** A chosen reference image collapses ambiguity. It gives the coding or design agent a clearer target than prompts like 'make it more polished' or 'make the button better.'\n\n### What did John say makes video prompting valuable?\n\n- **A.** The model can see a sequence over time and extract things like timestamps, screenshots, code snippets, and key moments.\n- **B.** It is mainly useful when the model should ignore everything except the final screen.\n- **C.** It replaces the need to explain what happened in a code or UI walkthrough.\n- **D.** It is best for deterministic commands that can be tested with a shell script.\n\n**Answer: A.** John describes video plus code as giving the model a strong understanding of what happened over time. He specifically mentions timestamps, screenshots, code snippets, and key parts.\n\n### What is the lesson's practical rule of thumb for MCP versus CLI boundaries?\n\n- **A.** Wrap every CLI in MCP so the agent has one standard interface.\n- **B.** Avoid CLIs because agents can reason better without deterministic tools.\n- **C.** Use direct scripts or CLIs for deterministic work, and use agents where judgment or interpretation adds value.\n- **D.** Use MCP only for visual design work and never for operational automation.\n\n**Answer: C.** The lesson pushes against over-abstracting simple commands. If a workflow is deterministic and testable, a direct CLI or script may be safer and clearer than an unnecessary MCP wrapper.\n\n## Reflection prompts\n\n- Where in your current workflow are you using a vague prompt when a generated image, screenshot, or video would give the agent a better signal?\n- Which tasks in your stack deserve Codex-level persistence, which can go to a fast small model, and which should be handled by deterministic scripts or CLIs?\n- What is one MCP wrapper or agent tool in your setup that might be simpler, safer, and easier to test as a direct CLI call?\n\n## Further applications\n\n1. Write a one-page agent routing guide for your own stack: which model handles coding, design conversation, quick one-off tasks, video analysis, and deterministic CLI work.\n2. Build a small image-to-design exercise: screenshot one component, generate a sheet of design variations, pick one, then ask an agent to implement only that chosen direction.\n3. Record a short screencast of a code or UI walkthrough and test whether a video-capable model can extract timestamps, screenshots, code snippets, and key moments.\n4. Audit one workflow you currently automate and label each step as deterministic script or CLI, agent inference, MCP/tool access, or monitoring.\n5. Experiment with a CMUX monitoring routine that summarizes git diffs hourly, rather than summarizing chat logs, so you track actual code progress instead of agent chatter.\n\n## Applied exercises\n\nMulti-Agent Layout Experiment: Write a setup prompt for your preferred orchestrator (such as CMUX) that opens four distinct split panes. Assign each a unique system persona (e.g., Security Auditor, Performance Evaluator, Unit Tester, Documentation Writer). Practice routing a single code task out to one dedicated pane and verify that background tracking occurs independently of your central panel history.\n\n## Questions and answers\n\n### Okay, and also this, you wrote, create a primary terminal that coordinates focused agents. Will you go into that, or was that already that part where you had the timestamp created?\n\nExplains that you can tell CMUX to open distinct panels for focused roles (e.g., quality control, performance, research, note-taking) pre-seeded with specialized persona prompts. The primary session then operates as the core orchestrator delegating specific sub-tasks to these target sessions.\n\n### Also, what is the… when I'm already at it, what is that cursor thing where you can draw? Did you mention that?\n\nIt is called Clicklight.\n\n### any preference on which agent to use for which task\n\nCodex is the default programmer selection, outperforming alternatives in token efficiency (especially on Rust code bases). Claude is preferred as a conversational main orchestrator and for design scaffolding when no asset files are provided. Flash 3.5 is suitable strictly for fast, single-step execution but struggles to self-correct during sequential logic tasks. Gemini is unmatched for long-context multi-modal ingestion such as video code extraction.\n\n### if i'm automating a workflow in typescript\n\nIt depends heavily on the specific workflow and how deterministic it needs to be. You must separate the deterministic procedural parts (scripts via Terminal/CLI) from the fuzzy inference parts (intelligence via the Agent SDK).\n\n### How do you mentally keep up with heavy context-switching?\n\nUses a physical, rotating Pomodoro timer sitting directly on the desk set strictly to 25 minutes. When it signals, you must physically touch it, move away from the workstation entirely, and separate from agent monitors to let the brain relax and naturally reset.\n\n### what do you use scheduling for? loops?\n\nScheduling is primarily used for monitoring tasks: configuring agents to compile hourly diff reports to trace code progression vs. conversation chatter, scraping communication updates (Slack, Pull Requests, email metrics), or exporting hourly operational briefs to an e-ink display. For standard execution loops, simply supply a explicit array list combined with standard language definitions like \"for each of these things\" inside a goal-directed prompt loop until a completion condition is reached.\n\n### Are you a fan of these fully hackable harnesses like pi.dev ?\n\nHe likes what the pi.dev team is doing, but due to constrained bandwidth, he remains fully focused on his open-source Rust-based setup featuring Codex and CMUX.\n\n### have you used claude design? its pretty good\n\nHas used it a couple of times with good results, but notes that it tends to hand-hold through a single targeted path rather than generating massive layouts of design alternatives, which is his personal preference.\n\n### do you limit your mcps? have skills call the mcps instead? saw executor post as well\n\nMentions that Executor is preferred for single-agent systems calling multiple tools. He highlights that it gets visually redundant or confusing when an engineer constructs custom agent skills designed specifically to target an isolated MCP server wrapper when the underlying system could have simply called the native engine CLI directly. Acknowledges the community is currently in an unstandardized territory regarding these boundaries.\n\n### Do you have any ideas on how to create levers for agents so they can do big data stuff without having all the data in their context?\n\nExplicitly states he is not an expert on big data engineering integrations and refers the user to follow established, popular open-source data manipulation platforms rather than presenting speculative advice.\n\n## Operational playbooks\n\n- [Image-to-design handoff](/topics/foundations-image-to-design-playbook/)\n\n- [Design, Video, and QA Story Field Guide](/topics/foundations-design-video-qa-field-guide/)\n\n## Recording references\n\n- [Recording](https://codex-workshop-followup.pages.dev/video/lessons/lesson-06.mp4)\n\n[Timestamped source page](https://codex-workshop-followup.pages.dev/lesson-06.html)\n\n### Visual reference index\n\n- [02:02:41](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-1): CMUX multi-pane splits displaying Quality Control, Performance, Research, and Notes window splits concurrently.\n- [02:04:04](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-2): Active window prompt context where John commands the newly split background Research sub-agent panel.\n- [02:04:49](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-3): On-screen annotation or menu moment while discussing the Clicklight drawing cursor tool.\n- [02:12:46](https://codex-workshop-followup.pages.dev/lesson-06.html#clip-06-4): Terminal workspace interface parameters linked with Google CLI scripting files configuration structure.\n- [02:13:37](https://codex-workshop-followup.pages.dev/lesson-06.html): Webcam perspective showcasing John holding the tangible rotating Pomodoro physical unit block.\n- [02:20:46](https://codex-workshop-followup.pages.dev/lesson-06.html): Impeccable system update release page detailing the npx impeccable command terminal instructions.\n- [02:21:49](https://codex-workshop-followup.pages.dev/lesson-06.html): Impeccable site section showing design-oriented examples and image-to-layout material.\n- [02:23:11](https://codex-workshop-followup.pages.dev/lesson-06.html): Visual evaluation of Impeccable browser interface elements containing the slop tab and live canvas module panels."
    },
    {
      "id": "codex-web-choices-runbook",
      "slug": "web-choices-runbook",
      "title": "Web Choices server and submission runbook",
      "summary": "Oracle-generated strict JSON choices served through a skill-local Svelte/mdsvex app, with Tailscale Funnel, persistent drafts/submissions, blocking wait-and-resume, verification, and recovery safeguards.",
      "category": "Tools",
      "tags": [
        "web-choices",
        "persistence",
        "runbook"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Non-Negotiables",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Generate Choices With Oracle",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Build And Serve The mdsvex Choice Experience",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Wait And Resume",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Verification",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/web-choices/SKILL.md#Web Choices/Failure Prevention",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "tools",
      "wordCount": 827,
      "url": "/topics/codex-web-choices-runbook/",
      "markdownUrl": "/markdown/codex-web-choices-runbook.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-web-choices-runbook.json",
      "headings": [
        {
          "id": "non-negotiables",
          "text": "Non-Negotiables",
          "level": 2
        },
        {
          "id": "generate-choices-with-oracle",
          "text": "Generate Choices With Oracle",
          "level": 2
        },
        {
          "id": "build-and-serve-the-mdsvex-choice-experience",
          "text": "Build And Serve The mdsvex Choice Experience",
          "level": 2
        },
        {
          "id": "wait-and-resume",
          "text": "Wait And Resume",
          "level": 2
        },
        {
          "id": "verification",
          "text": "Verification",
          "level": 2
        },
        {
          "id": "failure-prevention",
          "text": "Failure Prevention",
          "level": 2
        },
        {
          "id": "operational-boundaries",
          "text": "Operational boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Web Choices server and submission runbook\n\nUse this for agent-generated option lists that the user should review in a clean, polished, interactive browser experience or on a phone.\n\nThe durable implementation lives in this skill directory:\n\n```text\n~/.agents/skills/web-choices\n```\n\nAgents must launch the skill-local CLI from any project and must store runtime state in a caller-selected `HITL_OUT_DIR`, usually `$PWD/.hitl-choice`.\n\n## Non-Negotiables\n\n- The browser UI must be compiled from Svelte and mdsvex sources in this skill.\n- At least one `.svx` route or template must be part of the served choice experience.\n- A plain generated HTML form, static DOM script, or one-off Markdown page is not an acceptable implementation.\n- Oracle-generated choices remain strict JSON data. Do not compile Oracle/user option strings as Svelte or mdsvex source.\n- `current-job.json`, drafts, and submissions remain the durable source of truth.\n- The app must run from any project. Do not hardcode `script-kit-gpui`.\n- Do not overwrite an active current job without inspecting status and requiring explicit replacement.\n- Keep the HITL server alive in `tmux`; do not stop it after sending the URL.\n- Wait for the saved submission before continuing. The local wait defaults to no timeout.\n\n## Generate Choices With Oracle\n\nFor repo-aware lists, use `$oracle-packx` and include process docs plus relevant source/tests. For large context, use Oracle browser attachments rather than inline-only prompts.\n\nOracle generation is blocking. After starting the Oracle choice-list request, do not draft choices locally, publish a partial job, or continue until Oracle has completed and the local Oracle response has been read.\n\nAsk Oracle for a strict JSON job:\n\n```json\n{\n  \"jobId\": \"short-stable-id\",\n  \"title\": \"Human-readable title\",\n  \"description\": \"What the user is choosing\",\n  \"createdAt\": \"ISO timestamp\",\n  \"options\": [\n    {\n      \"id\": \"stable-option-id\",\n      \"title\": \"Short option title\",\n      \"description\": \"Concrete choice text\",\n      \"tags\": [\"optional\"],\n      \"surface\": \"optional area\",\n      \"goal\": \"optional goal\",\n      \"risk\": \"optional risk\",\n      \"suggestedProofCommands\": [\"optional command\"],\n      \"expectedEvidence\": {\n        \"pass\": \"optional pass signal\",\n        \"fail\": \"optional fail signal\"\n      }\n    }\n  ]\n}\n```\n\nIf a selected option later fails verification, ask Oracle again with a Prior-State Ledger and Forward Progress Gate describing the failure, selected option, logs, and what has already been tried.\n\n## Build And Serve The mdsvex Choice Experience\n\nThe skill-local app is a Bun + Vite + Svelte + mdsvex app. mdsvex owns the page/template shell; Svelte components own filters, cards, selection state, feedback fields, save status, and submission controls. Runtime data remains JSON-driven.\n\nFrom any project:\n\n```bash\nexport WEB_CHOICES_SKILL_DIR=\"$HOME/.agents/skills/web-choices\"\nexport HITL_OUT_DIR=\"$PWD/.hitl-choice\"\nexport HITL_HOST=\"127.0.0.1\"\nexport HITL_PORT=\"8877\"\n\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" server \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --host \"$HITL_HOST\" \\\n  --port \"$HITL_PORT\" \\\n  --tmux\n```\n\nThe server writes or reuses `$HITL_OUT_DIR/.token`. Read the token from that file or from the server status.\n\nConfirm the server is alive:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" status \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nPush the Oracle-generated job:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" push /path/to/job.json \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nUse `--replace` only after inspecting active job status and confirming replacement is safe.\n\nStart and verify Tailscale Funnel by default:\n\n```bash\ntailscale funnel --bg --yes \"$HITL_PORT\"\ntailscale funnel status\ncurl -s \"https://<your-tailnet-host>.ts.net/api/jobs/current?token=$(cat \"$HITL_OUT_DIR/.token\")\"\n```\n\nGive the user the public URL only after the public API returns the expected `jobId` and option count:\n\n```text\nhttps://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>\n```\n\nTell the user the server is staying open, drafts are saved server-side, and you are waiting for their submission.\n\n## Wait And Resume\n\nWait locally without a timeout unless the user asks otherwise:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" wait \\\n  --job \"<jobId>\" \\\n  --out-dir \"$HITL_OUT_DIR\"\n```\n\nPersisted sources of truth:\n\n- `$HITL_OUT_DIR/current-job.json`\n- `$HITL_OUT_DIR/drafts/`\n- `$HITL_OUT_DIR/submissions.jsonl`\n- `$HITL_OUT_DIR/submissions/<submissionId>.json`\n\nAfter submission, report the `submissionId`, selected count, selected option IDs/titles, per-option feedback, overall feedback, and saved file path. Continue from saved JSON, not memory.\n\n## Verification\n\nBefore giving the user the URL, verify:\n\n- `bun run build` succeeds in `~/.agents/skills/web-choices`.\n- The current page is served from compiled Svelte/mdsvex output.\n- The public or local API returns the expected `jobId` and option count.\n- Desktop and phone-width rendering are usable.\n- Draft saving and final submit persist JSON under `HITL_OUT_DIR`.\n\n## Failure Prevention\n\n- If the tunnel fails, keep the same server/job/token when possible and restart Funnel; do not regenerate choices unless asked.\n- If the server dies, inspect `HITL_OUT_DIR` first, restart with the same token, and verify drafts/submissions still exist.\n- If the user says they submitted but wait has not returned, check `submissions.jsonl`, per-submission files, server logs, and `/api/jobs/<jobId>/submissions/status?token=<token>`.\n- If laptop sleep or network loss is possible, say the server is durable while the machine and Tailscale are online; leave the `tmux` session running.\n- Do not expose sensitive choices over a public Funnel URL without user approval. The token gates access but is not full authentication.\n\n## Operational boundaries\n\n- The bundle includes the skill instructions, not the complete runnable Svelte/mdsvex app. Install or locate the implementation before using its CLI paths. Funnel exposes the service publicly; token-bearing links are not full authentication.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-marker-workflows-team-guide",
      "slug": "marker-workflows-team-guide",
      "title": "Agent Markers debugging workflows: team walkthrough",
      "summary": "Marker-centered debugging using createAgentMarkers, browser-global marking and export, nearby-event association, privacy boundaries, cleanup, and project verification. Preserves the bounded debug-packet model, downstream work-unit bridge, failure recovery,…",
      "category": "Team practice",
      "tags": [
        "agent-markers",
        "debugging",
        "privacy",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/1. Show Setup",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/2. Create A Marker",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/3. Export",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Live Demo Script/4. Verify Project",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries/From Section 7",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Boundaries/To Section 9",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/08-debugging-with-agent-markers.md#Instructor Notes: 08. Debugging With Agent Markers/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 662,
      "url": "/topics/codex-marker-workflows-team-guide/",
      "markdownUrl": "/markdown/codex-marker-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-marker-workflows-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-show-setup",
          "text": "1. Show Setup",
          "level": 3
        },
        {
          "id": "2-create-a-marker",
          "text": "2. Create A Marker",
          "level": 3
        },
        {
          "id": "3-export",
          "text": "3. Export",
          "level": 3
        },
        {
          "id": "4-verify-project",
          "text": "4. Verify Project",
          "level": 3
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "from-section-7",
          "text": "From Section 7",
          "level": 3
        },
        {
          "id": "to-section-9",
          "text": "To Section 9",
          "level": 3
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Agent Markers debugging workflows: team walkthrough\n\n## Team Learning Goal\n\nTeach markers as human-intent anchors in debugging workflows.\n\nBy the end of this section, the room should understand:\n\n- why raw logs are not enough\n- how `mark -> capture -> explain -> review/export` works\n- what a `DebugSession`, `DebugMoment`, `CapturedEvent`, and `nearbyEventIds` are\n- how to export marker JSON from browser/dev/test flows\n- how privacy defaults prevent overcapture\n- how marker exports become bounded debug packets\n- how Section 9 can use the packet as a work unit\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State: raw logs tell what emitted; markers tell why a moment mattered.\n2. Draw `mark -> capture -> explain -> review/export`.\n3. Show `createAgentMarkers`.\n4. Show `window.__AGENT_MARKERS__.mark` and `export`.\n5. Show the final agent prompt shape.\n\n### Expanded Walkthrough\n\nAdd:\n\n- capture types table\n- privacy defaults\n- `nearbyEventIds`\n- Playwright export\n- `stop()` cleanup\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- app-specific `Ctrl+M` flow\n- bounded replay capsule\n- smoke/test commands\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Raw logs tell you what emitted. Agent markers tell you why a moment mattered.\n\nOn markers:\n\n> A marker is a human-intent anchor, not another log line.\n\nOn privacy:\n\n> Metadata first. Values only when deliberately enabled and safe.\n\nOn replay:\n\n> This is a bounded debug packet, not a deterministic recorder.\n\nBridge from Section 7:\n\n> Section 7 preserved evidence from video. Section 8 lets you create evidence while debugging.\n\nBridge to Section 9:\n\n> A good marker export is small enough to become a work unit.\n\n## Live Demo Script\n\n### 1. Show Setup\n\n```ts\nimport { createAgentMarkers } from \"@agent-markers/client\";\n\nconst markers = createAgentMarkers({\n  appName: \"checkout-app\",\n  exposeGlobal: true,\n  capture: {\n    console: true,\n    fetch: true,\n    errors: true,\n  },\n});\n```\n\n### 2. Create A Marker\n\n```js\nwindow.__AGENT_MARKERS__.mark({\n  label: \"saved payment selector empty after refresh\",\n  note: \"Expected saved cards to stay visible after auth refresh; actual selector is empty.\",\n});\n```\n\n### 3. Export\n\n```js\nconst session = window.__AGENT_MARKERS__.export();\n({\n  markerCount: session.markers.length,\n  eventCount: session.events.length,\n  hasNearbyIds: session.markers.some((marker) => marker.nearbyEventIds.length > 0),\n});\n```\n\n### 4. Verify Project\n\n```bash\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- Cypress example\n- app-specific `Ctrl+M`\n- bounded replay capsule details\n- screenshot/DOM hook implementation\n\nPreserve:\n\n- `mark -> capture -> explain -> review/export`\n- `createAgentMarkers`\n- `window.__AGENT_MARKERS__`\n- `nearbyEventIds`\n- privacy defaults\n- export JSON\n- Section 9 bridge\n\n## Boundaries\n\n### From Section 7\n\nSection 7:\n\n```text\nsource media -> evidence lanes -> verified prompt material\n```\n\nSection 8:\n\n```text\nmarked moment -> nearby runtime evidence -> bounded debug packet\n```\n\n### To Section 9\n\nSection 9 needs work units that are small, bounded, and verifiable.\n\nAgent markers provide:\n\n- one marker id\n- human explanation\n- nearby evidence\n- privacy boundary\n- verification command\n- next action\n\n## Failure Paths To Preserve\n\nNo note:\n\n> A marker without a human explanation is just another timestamp.\n\nToo many logs:\n\n> Focus on one marker id and nearby events.\n\nSensitive storage:\n\n> Redact and rebuild. Metadata first.\n\nNo nearby events:\n\n> Mark closer to the failure or adjust the nearby window deliberately.\n\nPatched APIs not restored:\n\n> Call `stop()` and test cleanup.\n\nNo test export:\n\n> Expose the global in dev/test and wait for app readiness.\n\n## Team Checklist\n\nConfirm the materials include:\n\n```text\nmark -> capture -> explain -> review/export\ncreateAgentMarkers\nDebugSession\nDebugMoment\nCapturedEvent\nnearbyEventIds\nconsole capture\nfetch capture\nerror capture\nmanual evidence\nDOM hook\nscreenshot hook\nprivacy defaults\nstorage metadata\nwindow.__AGENT_MARKERS__\nexport JSON\ndownload\nstop()\nnpm test\nnpm run typecheck\nnpm run build\nnpm run smoke:demo\nPlaywright export\nCypress export\ndev_marker\ndev_marker_explanation\nbounded replay capsule\nSection 9 bridge\n```\n\n## Further References\n\n- team-facing file: `cheatsheets/08-debugging-with-agent-markers.md`\n- Exercises: `exercises/08-debugging-with-agent-markers.md`\n- Agent marker client: `packages/client/src/index.ts`\n- Collector: `packages/client/src/collector.ts`\n- Demo: `apps/demo/src/main.ts`\n- Smoke script: `scripts/smoke-demo.mjs`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-context-packing-team-guide",
      "slug": "context-packing-team-guide",
      "title": "Context packing with Oracle and PackX: team walkthrough",
      "summary": "Skill-backed context packing and Oracle review: scope and evidence selection, preview and bundling, compact evidence, follow-up state tracking, CLAUDE.md exclusion, saved-log inspection, and locally authored project artifacts.",
      "category": "Team practice",
      "tags": [
        "oracle",
        "packx",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Do Not Over-Explain",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Preserve If Short On Time",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Portable Pattern Table",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/01-oracle-packing-context.md#Instructor Notes: 01. Oracle / Packing Context/Bridge To Section 2",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 541,
      "url": "/topics/codex-context-packing-team-guide/",
      "markdownUrl": "/markdown/codex-context-packing-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-context-packing-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "do-not-over-explain",
          "text": "Do Not Over-Explain",
          "level": 2
        },
        {
          "id": "essential-points-to-preserve",
          "text": "Essential Points To Preserve",
          "level": 2
        },
        {
          "id": "portable-pattern-table",
          "text": "Portable Pattern Table",
          "level": 2
        },
        {
          "id": "bridge-to-section-2",
          "text": "Bridge To Section 2",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Context packing with Oracle and PackX: team walkthrough\n\n## Team Learning Goal\n\nTeach this as a skill-backed workflow, not a PackX flag lecture.\n\nThe audience should understand that `skills/oracle-packx/SKILL.md` is the operational contract. The cheatsheet explains when to use it, what it does, what to ask for, and how to inspect the result.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Show the software scenario: saved payment methods, billing webhook bug, or auth/session architecture review.\n2. Show the bundled skill path: `skills/oracle-packx/SKILL.md`.\n3. Explain that the skill owns PackX command construction and Oracle call shape.\n4. Show the high-level pipeline: preview, bundle, browser Oracle, `output.log`, local artifact.\n5. Show what the human must provide: outcome, scope, evidence, exclusions, success check.\n6. Show how to know it worked.\n\n### Expanded Walkthrough\n\nAdd:\n\n- compact evidence\n- follow-up Oracle calls and prior-state ledger\n- why Oracle-created downloads are not the artifact\n- why `CLAUDE.md` is excluded\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- skim the PackX quick reference\n- show the common PackX capabilities table\n- discuss when this workflow is too heavy\n- start an exercise where team members write a skill invocation prompt for their own project\n\n## Talking Points\n\nOpening:\n\n> You are not learning every PackX flag. You are learning when to hand a hard software question to a skill that knows how to build the packet.\n\nWhen showing the skill:\n\n> The skill is the source of truth. The cheatsheet is the mental map.\n\nWhen showing preview:\n\n> Preview is how the skill fails cheaply before spending the Oracle run.\n\nWhen showing `CLAUDE.md` exclusion:\n\n> Repo instructions can matter, but this workflow excludes `CLAUDE.md` and prefers deliberately scoped guidance.\n\nWhen showing compact evidence:\n\n> Some evidence should be summarized, not packed raw.\n\nWhen showing `output.log`:\n\n> The visible answer may be clipped. The skill requires the local agent to read the saved log before summarizing.\n\n## Do Not Over-Explain\n\n- every PackX flag\n- tokenizer internals\n- browser automation implementation details\n- Oracle pricing or product speculation\n- every line of the skill\n- every possible PackX workflow\n\n## Essential Points To Preserve\n\n- `oracle-packx` is a bundled skill.\n- The skill owns PackX and Oracle execution details.\n- The human supplies scope, evidence, exclusions, and desired software outcome.\n- The output is read from `output.log`.\n- The local agent writes the project artifact.\n\n## Portable Pattern Table\n\n| John's local thing | Portable pattern |\n| --- | --- |\n| `skills/oracle-packx/SKILL.md` | skill as workflow contract |\n| PackX | deterministic context bundler |\n| `--preview` | inspect before sending context |\n| `~/.oracle/bundles/{slug}.txt` | local context packet |\n| Oracle browser mode | deliberate deep review surface |\n| `output.log` | saved full answer |\n| compact evidence | useful facts from raw material that should not be packed |\n| local artifact write | project output owned by the local environment |\n\n## Bridge To Section 2\n\nClose with:\n\n> Section 1 showed a skill that gives the agent the right project context. Section 2 is about making sure the agent can see the same shell environment and tools you expect it to use.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-variation-workflows-team-guide",
      "slug": "variation-workflows-team-guide",
      "title": "Controlled variation workflows: team walkthrough",
      "summary": "Controlled software variations using one variable, a shared prompt seed, isolated candidates, common verification, comparison records, and explicit Pick/Combine/Refine/Expand/Reject decisions, including billing-webhook examples and convergence failure…",
      "category": "Team practice",
      "tags": [
        "variations",
        "verification",
        "comparison",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/1. Start With The Pattern",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/2. Write The Variable",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/3. Create The Run Folder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/4. Save A Prompt Builder Seed",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/5. Check Repo State",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/6. Show Same Verification",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Live Demo Script/7. Save The Decision",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Boundaries/From Section 5",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Boundaries/To Section 7",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Do Not Over-Explain",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/06-code-is-free-generate-variations.md#Instructor Notes: 06. Code Is Free / Generate Variations/Practice Launch Notes",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 1251,
      "url": "/topics/codex-variation-workflows-team-guide/",
      "markdownUrl": "/markdown/codex-variation-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-variation-workflows-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-start-with-the-pattern",
          "text": "1. Start With The Pattern",
          "level": 3
        },
        {
          "id": "2-write-the-variable",
          "text": "2. Write The Variable",
          "level": 3
        },
        {
          "id": "3-create-the-run-folder",
          "text": "3. Create The Run Folder",
          "level": 3
        },
        {
          "id": "4-save-a-prompt-builder-seed",
          "text": "4. Save A Prompt Builder Seed",
          "level": 3
        },
        {
          "id": "5-check-repo-state",
          "text": "5. Check Repo State",
          "level": 3
        },
        {
          "id": "6-show-same-verification",
          "text": "6. Show Same Verification",
          "level": 3
        },
        {
          "id": "7-save-the-decision",
          "text": "7. Save The Decision",
          "level": 3
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "from-section-5",
          "text": "From Section 5",
          "level": 3
        },
        {
          "id": "to-section-7",
          "text": "To Section 7",
          "level": 3
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "do-not-over-explain",
          "text": "Do Not Over-Explain",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "practice-launch-notes",
          "text": "Practice Launch Notes",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Controlled variation workflows: team walkthrough\n\n## Team Learning Goal\n\nTeach controlled variation as a decision workflow.\n\nThe point is not “generate more.” The point is:\n\n```text\nGenerate comparable options, verify each option, then preserve the decision.\n```\n\nBy the end of this section, the room should understand:\n\n- why cheap generation changes the workflow\n- why quality, integration, and verification are not free\n- how to choose one variable under test\n- how to write a variation matrix\n- why isolation matters before fan-out\n- why the same verification command must run for every candidate\n- how to decide Pick / Combine / Refine / Expand / Reject\n- how Section 5’s saved prompt becomes the seed\n- how Section 7 expands what can become prompt material\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State: `Code is free` does not mean quality is free.\n2. Teach the One Dimension Rule.\n3. Show a billing webhook variation matrix.\n4. Show the `artifacts/variations/<run-id>/` folder shape.\n5. Show one verification command applied to all candidates.\n6. End with Pick / Combine / Refine / Expand / Reject.\n\nPreserve:\n\n```text\ngoal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision\n```\n\n### Expanded Walkthrough\n\nAdd:\n\n- dirty repo checkpoint\n- Prompt Builder seed prompt\n- worktree isolation\n- candidate prompt overrides\n- comparison file\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- visible cmux fan-out\n- screenshots for UI candidates\n- convergence prompt from saved decision\n- failure paths\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Code is free does not mean quality is free.\n\nOn variations:\n\n> Variation is a decision tool, not a procrastination tool.\n\nOn the One Dimension Rule:\n\n> If every candidate changes everything, comparison teaches nothing.\n\nOn verification:\n\n> Unverified candidates are just more text.\n\nOn isolation:\n\n> Parallel work needs lanes. Without lanes, candidates overwrite each other.\n\nOn Combine:\n\n> Combine still needs a primary candidate. Otherwise it becomes “take everything I liked” and scope explodes.\n\nBridge from Section 5:\n\n> Section 5 made the prompt deliberate. Section 6 turns that prompt into comparable options.\n\nBridge to Section 7:\n\n> We just learned to vary from one prompt. Next, we widen what can count as prompt material.\n\n## Live Demo Script\n\n### 1. Start With The Pattern\n\n```text\ngoal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision\n```\n\n### 2. Write The Variable\n\n```text\nWe are comparing candidates that differ only by idempotency strategy.\n```\n\n### 3. Create The Run Folder\n\n```bash\nRUN_ID=\"billing-webhook-$(date +%Y%m%d-%H%M%S)\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT\"/{prompts,launch,logs,review,decisions}\nmkdir -p \"$ROOT\"/candidates/{v1,v2,v3}\nfind \"$ROOT\" -maxdepth 3 -type d | sort\n```\n\n### 4. Save A Prompt Builder Seed\n\n```bash\nPROMPT='Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, risks, and rollback notes.'\n\np --print-prompt \"$PROMPT\" > \"$ROOT/prompts/base.prompt.md\"\np --print-launch-json \"$PROMPT\" > \"$ROOT/launch/base.launch.json\"\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\n```\n\n### 5. Check Repo State\n\n```bash\ngit status --short | tee \"$ROOT/review/git-status-before.txt\"\ngit diff > \"$ROOT/review/dirty-before.patch\"\ngit diff --staged > \"$ROOT/review/staged-before.patch\"\n```\n\nPresenter note:\n\n```text\nDirty state is not forbidden. Unknown dirty state is the problem.\n```\n\n### 6. Show Same Verification\n\n```bash\nVERIFY='pnpm test billing-webhook -- --runInBand && pnpm build'\nprintf 'v1\\t<status>\\t%s\\n' \"$VERIFY\" > \"$ROOT/review/verification.tsv\"\nprintf 'v2\\t<status>\\t%s\\n' \"$VERIFY\" >> \"$ROOT/review/verification.tsv\"\nprintf 'v3\\t<status>\\t%s\\n' \"$VERIFY\" >> \"$ROOT/review/verification.tsv\"\ncolumn -t -s $'\\t' \"$ROOT/review/verification.tsv\"\n```\n\nIf real tests are too slow live, show the shape and say:\n\n> In a real project, this is where broken candidates get filtered before review.\n\n### 7. Save The Decision\n\n```bash\ncat > \"$ROOT/decisions/selection.md\" <<'EOF'\n# Saved Decision\n\n- outcome: Combine\n- primary candidate: v2\n- secondary candidate ids: v1\n- decision: Use v2 as the base and take v1's rollback guard.\n- final verification command: pnpm test billing-webhook -- --runInBand && pnpm build\n\n## Continue Prompt\n\nContinue from this saved decision.\nPreserve v2 as the primary candidate.\nApply only the named v1 rollback guard.\nRun final verification.\nEOF\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- visible cmux fan-out\n- feature flag isolation\n- screenshots\n- convergence prompt command\n\nPreserve:\n\n- `Code is free` does not mean quality is free\n- One Dimension Rule\n- variation matrix\n- dirty repo checkpoint\n- same verification command\n- Pick / Combine / Refine / Expand / Reject\n\nIf 10 minutes behind, skip worktree creation and use output folders only:\n\n```bash\nmkdir -p \"$ROOT\"/candidates/{v1,v2,v3}\n```\n\nIf 20 minutes behind, teach only:\n\n```text\nOne deliberate prompt becomes a matrix.\nThe matrix changes one dimension.\nEach candidate gets isolation.\nEach candidate gets the same verification.\nThe final decision is Pick, Combine, Refine, Expand, or Reject.\n```\n\n## Boundaries\n\n### From Section 5\n\nSection 5 solves composition:\n\n```text\nWhat exactly am I about to send?\n```\n\nSection 6 solves controlled fan-out:\n\n```text\nWhat do I do after the prompt is good enough to become a seed?\n```\n\n### To Section 7\n\nSection 6 assumes the seed is mostly text plus project context.\n\nSection 7 expands the prompt material:\n\n```text\nvideo can carry visual state, timing, workflow, cursor motion, and failure evidence\n```\n\n## Failure Paths To Preserve\n\nCandidates drift:\n\n> Drift means the matrix was too weak or the candidate prompt was too loose. Stop and tighten the variable.\n\nUnverifiable options:\n\n> If you cannot verify the candidates, you are setting up a beauty contest. Define verification first.\n\nDirty repo:\n\n> Dirty state is not forbidden. Unknown dirty state is the problem.\n\nMerge conflicts:\n\n> The selected candidate worked in isolation. Convergence has to protect that proof, not bulldoze it.\n\nStrongest idea split across candidates:\n\n> That is Combine. Pick a primary candidate and name the pieces you are taking.\n\nAll candidates fail:\n\n> That is useful information. Reject the set or expand with a tighter prompt. Do not pretend one failed candidate won.\n\n## Do Not Over-Explain\n\nAvoid spending time on:\n\n- every local helper\n- every possible git worktree cleanup command\n- full review UI implementation details\n- exhaustive parallel orchestration\n- model-provider comparisons\n- abstract creativity theory\n\nKeep the section practical:\n\n```text\nmatrix\nisolation\nfan-out\nverification\nreview\nsaved decision\n```\n\n## Team Checklist\n\nBefore considering this section ready, confirm the materials include:\n\n```text\nCode is free\nquality is not free\nintegration is not free\nverification is not free\ncontrolled variations\nOne Dimension Rule\ngood variables\nbad variables\nwhen to use variations\nwhen not to use variations\ngoal -> variable -> matrix -> isolation -> fan-out -> verify -> review -> selection -> convergence -> saved decision\nvariation matrix template\nPrompt Builder seed\nartifacts/variations/<run-id>/\nbase.prompt.md\nbase.launch.json\ndirty repo checkpoint\nworktrees\nbranches\ndirectories\nfeature flags\nsame verification command\ncomparison notes\ndiff review\nscreenshots for UI\ntest results\nPick\nCombine\nRefine\nExpand\nReject\nfailure paths\nSection 7 bridge to video\n```\n\n## Practice Launch Notes\n\nGood demo scenarios:\n\n| Scenario | Variable |\n| --- | --- |\n| checkout saved payment methods | UI integration strategy |\n| billing webhook duplicate-processing | idempotency strategy |\n| auth/session architecture | architecture boundary |\n| flaky regression coverage | test boundary |\n| checkout implementation | implementation alternative |\n\nAvoid:\n\n```text\nmake the app better\nimprove architecture\ntry some ideas\nfix everything\n```\n\nThe cleanest live example is billing webhook idempotency because correctness, verification, rollback, and risk are easy to discuss.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-fusion-workflows-team-guide",
      "slug": "fusion-workflows-team-guide",
      "title": "Fusion council decisions and evidence: team walkthrough",
      "summary": "Decision-focused multi-model council workflow: frame a billing-webhook tradeoff, write a prompt file, inspect providers, dry-run, execute the configured panel, and review final artifacts, disagreement, and verification before acting. Distinguishes local…",
      "category": "Team practice",
      "tags": [
        "fusion",
        "council",
        "review",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script/1. Choose The Decision",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script/2. Draft A Prompt File",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script/3. Preflight",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script/4. Run",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Live Demo Script/5. Confirm",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Boundaries With Neighboring Sections",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Careful Origin Wording",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/10-fusion-model-council.md#Instructor Notes: 10. Fusion / Model Council/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 1058,
      "url": "/topics/codex-fusion-workflows-team-guide/",
      "markdownUrl": "/markdown/codex-fusion-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-fusion-workflows-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-choose-the-decision",
          "text": "1. Choose The Decision",
          "level": 3
        },
        {
          "id": "2-draft-a-prompt-file",
          "text": "2. Draft A Prompt File",
          "level": 3
        },
        {
          "id": "3-preflight",
          "text": "3. Preflight",
          "level": 3
        },
        {
          "id": "4-run",
          "text": "4. Run",
          "level": 3
        },
        {
          "id": "5-confirm",
          "text": "5. Confirm",
          "level": 3
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "boundaries-with-neighboring-sections",
          "text": "Boundaries With Neighboring Sections",
          "level": 2
        },
        {
          "id": "careful-origin-wording",
          "text": "Careful Origin Wording",
          "level": 2
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Fusion council decisions and evidence: team walkthrough\n\n## Team Learning Goal\n\nTeach Fusion as a decision workflow.\n\nThe goal is not to show every CLI flag. The goal is to teach when a hard software decision benefits from independent model disagreement, how to ask an agent for `$fusion`, and how to confirm the agent waited for council output before acting.\n\nBy the end of this section, the room should understand:\n\n- Fusion is for expensive decisions, not tiny fixes\n- Local Fusion is inspired by the panel/finalizer pattern, but is not OpenRouter Fusion\n- the `$fusion` skill owns command details\n- the agent should list providers, write a prompt file, run the full configured panel, wait, and read final artifacts\n- partial panel output is not the answer\n- failed or quota-limited providers degrade the run instead of automatically invalidating it\n- the final engineering call still comes from repo evidence\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State the core rule: use Fusion when disagreement improves the decision.\n2. Show good and bad examples.\n3. Show the local pipeline: prompt file -> panel -> finalizer -> `summary.json` / `final.md`.\n4. Show the `$fusion` ask prompt.\n5. Show how to confirm the agent waited.\n\n### Expanded Walkthrough\n\nAdd:\n\n- Local Fusion vs OpenRouter Fusion\n- Fable/model-disappearance lesson\n- provider terminal states\n- degraded panel behavior\n- artifact privacy boundary\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- live prompt-file build\n- provider list and dry-run\n- read sample `summary.json`\n- extract consensus/disagreement\n- exercise kickoff\n\n## Talking Points\n\nOpening:\n\n> Fusion is not \"ask more models because it feels fancy.\" Fusion is \"this decision is expensive, so disagreement is worth buying.\"\n\nOn partial output:\n\n> The first useful provider answer is not the council result.\n\nOn local versus hosted Fusion:\n\n> OpenRouter Fusion is a hosted product. Local Fusion is a local CLI pattern that shells out to local provider CLIs.\n\nOn Fable:\n\n> The Fable 5 shock is the lesson: do not make important workflows depend on one fragile model slug.\n\nOn final authority:\n\n> Fusion advises. The repo decides.\n\n## Live Demo Script\n\nUse a no-edit scenario.\n\n### 1. Choose The Decision\n\n```text\nBilling webhook duplicate-processing:\nprovider event id guard vs invoice lock vs processing ledger.\n```\n\n### 2. Draft A Prompt File\n\n```bash\nmkdir -p .notes/fusion\ncat > .notes/fusion/billing-webhook-council.md <<'EOF'\n# Fusion Prompt\n\n## Goal\n\nChoose the safest first implementation strategy for duplicate billing webhook processing.\n\n## Current Evidence\n\n- paid invoice events may arrive more than once\n- current handler can process the same invoice twice\n- likely files:\n  - src/billing/webhook.ts\n  - src/billing/idempotency.ts\n  - tests/billing/webhook.test.ts\n\n## Candidate Strategies\n\n- provider event id guard\n- invoice-level processing lock\n- webhook processing ledger\n\n## Constraints\n\n- preserve provider contract\n- avoid schema changes in first pass unless strongly justified\n- preserve existing invoice state transitions\n\n## Verification\n\n- pnpm test billing-webhook -- --runInBand\n- pnpm build\n\n## Ask\n\nCompare the strategies. Identify consensus, disagreement, hidden risks, missing tests,\nand the first shippable slice. End with a concrete recommendation and rollback notes.\nEOF\n```\n\n### 3. Preflight\n\n```bash\nfusion-high --list-providers\nfusion-high --dry-run --file .notes/fusion/billing-webhook-council.md\n```\n\n### 4. Run\n\n```bash\nfusion-high --file .notes/fusion/billing-webhook-council.md\n```\n\n### 5. Confirm\n\nAsk the agent to report:\n\n- Fusion session\n- `summary.json`\n- `final.md`\n- provider terminal states\n- consensus\n- disagreement\n- chosen path\n- verification\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- live run\n- OpenRouter benchmark numbers\n- custom configs\n\nIf 10 minutes behind, cut:\n\n- provider terminal state details\n- artifact list\n\nIf 20 minutes behind, keep only:\n\n- when to use Fusion\n- `$fusion` ask prompt\n- wait for `summary.json` and `final.md`\n- Local Fusion is not OpenRouter Fusion\n\n## Boundaries With Neighboring Sections\n\nFrom Section 1:\n\n```text\nOracle PackX is for broad packed context and one expensive external review.\nFusion is for local independent model disagreement on a bounded decision.\n```\n\nFrom Section 5:\n\n```text\nPrompt Builder composes before launch. Fusion can consume a prompt file produced\nby any deliberate composition workflow.\n```\n\nFrom Section 6:\n\n```text\nSection 6 compares generated implementation candidates. Fusion compares\nindependent critiques and strategy recommendations before implementation.\n```\n\nTo Section 9:\n\n```text\nImps are narrow one-tool agents. Fusion is a council. Do not send one-tool lookup\nwork to Fusion.\n```\n\n## Careful Origin Wording\n\nSay:\n\n```text\nLocal Fusion is inspired by the OpenRouter-style panel and judge/finalizer pattern.\n```\n\nDo not say:\n\n```text\nLocal Fusion is OpenRouter Fusion.\n```\n\nSay:\n\n```text\nOpenRouter reported strong DRACO results for Fusion on deep research tasks.\n```\n\nDo not say:\n\n```text\nFusion always beats a single model.\n```\n\nSay:\n\n```text\nOpenRouter cautions that Fusion should be used selectively for hard questions.\n```\n\nDo not say:\n\n```text\nFusion replaces coding agents.\n```\n\nSay:\n\n```text\nThe Fable availability change is the practical lesson about fragile single-model workflows.\n```\n\nDo not claim a precise causal story unless the cited source proves it.\n\n## Failure Paths To Preserve\n\nAgent skipped provider list:\n\n```bash\nfusion-high --list-providers\n```\n\nAgent used inline long prompt:\n\n```text\nAsk for a prompt file and --file.\n```\n\nAgent started implementation early:\n\n```text\nStop and request summary.json, final.md, provider terminal states, consensus, and disagreement.\n```\n\nOne provider quota-limited:\n\n```text\nExplain degraded council behavior. The run can still be useful if final artifacts exist and the missing voice is named.\n```\n\nFinal answer flattened disagreement:\n\n```text\nAsk for consensus, contradictions, hidden risks, and which repo evidence decides.\n```\n\nPrivate artifact risk:\n\n```text\nDo not paste full session artifacts. Summarize the relevant council result.\n```\n\n## Team Checklist\n\nConfirm the materials include:\n\n- `$fusion` skill path\n- common local source checkout\n- OpenRouter inspiration boundary\n- not the same product\n- not for tiny fixes\n- provider list first\n- prompt file\n- dry-run when uncertain\n- full configured panel\n- terminal provider states\n- `summary.json`\n- `final.md`\n- quota non-blocking\n- partial artifacts are partial\n- private session store\n- advisory output\n- repo evidence wins\n- billing webhook example\n- auth/session example\n- model outage fallback example\n\n## Further References\n\n- File: `cheatsheets/10-fusion-model-council.md`\n- Exercise: `exercises/10-fusion-model-council.md`\n- Skill: `skills/fusion/SKILL.md`\n- Common local source checkout: `~/dev/fusion`\n- OpenRouter Fusion product page: https://openrouter.ai/fusion\n- OpenRouter Fusion model page: https://openrouter.ai/openrouter/fusion\n- OpenRouter announcement: https://openrouter.ai/blog/announcements/fusion-beats-frontier/\n- OpenRouter model-disappearance post: https://openrouter.ai/blog/tutorials/keep-your-agent-running-when-models-disappear/\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-judgment",
      "slug": "judgment",
      "title": "Interview for judgment and build for agency",
      "summary": "Agent-heavy work eventually comes back to the human side of software practice.",
      "category": "Team practice",
      "tags": [
        "judgment",
        "agency",
        "ethics"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#judgment"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Judgment Stays Human",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Interview With A Product Flow",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Speculation Is Not A Roadmap",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Fatigue Is About Control",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Ethics Boundary",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Copyable Artifact: Product Judgment Interview Packet",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Close The Loop",
        "src/content/final/chunk-14-interview-for-judgment-build-for-agency.md#Interview For Judgment, Build For Agency/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#judgment",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 990,
      "url": "/topics/codex-judgment/",
      "markdownUrl": "/markdown/codex-judgment.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-judgment.json",
      "headings": [
        {
          "id": "judgment-stays-human",
          "text": "Judgment Stays Human",
          "level": 2
        },
        {
          "id": "interview-with-a-product-flow",
          "text": "Interview With A Product Flow",
          "level": 2
        },
        {
          "id": "speculation-is-not-a-roadmap",
          "text": "Speculation Is Not A Roadmap",
          "level": 2
        },
        {
          "id": "fatigue-is-about-control",
          "text": "Fatigue Is About Control",
          "level": 2
        },
        {
          "id": "ethics-boundary",
          "text": "Ethics Boundary",
          "level": 2
        },
        {
          "id": "copyable-artifact-product-judgment-interview-packet",
          "text": "Copyable Artifact: Product Judgment Interview Packet",
          "level": 2
        },
        {
          "id": "close-the-loop",
          "text": "Close The Loop",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Interview for judgment and build for agency\n\nAgent-heavy work eventually comes back to the human side of software practice.\n\nNot \"which model wins?\" and not \"will developers matter?\" The useful question is smaller: when agents can write more code, what do people still need to **judge, critique, own, and verify**?\n\n## Judgment Stays Human\n\nFor product software, **the durable skill is judgment**:\n\n- understand the user\n- critique the experience\n- communicate clearly\n- decide where agents help\n- decide where agents hurt\n- keep control of the tools\n- verify the result\n\nThe point is not to replace technical ability with taste. The point is to **connect technical work to product reality**.\n\n## Interview With A Product Flow\n\nA useful interview exercise can be simple:\n\n> I would open up a website and just have someone critique it. Have them go through a few websites, have them click around. And not even find bugs, just find what they think could improve from the user experience.\n>\n> — John Lindquist\n\nOpen a real website or app. Ask the candidate to click through one flow, describe who the product serves, critique the experience, and connect that critique back to engineering decisions.\n\nThen add the agent layer:\n\n- Where could an agent improve this experience?\n- Where could an agent make it worse?\n- What should remain human-reviewed?\n- What would you ask an agent to do first?\n- How would you phrase the prompt so the work stays bounded?\n\nTraits to look for:\n\n| Trait | What To Look For |\n|---|---|\n| Product judgment | Can they tell what the product is for? |\n| Communication | Can they explain the critique clearly? |\n| Critique quality | Can they identify tradeoffs without just dunking on the UI? |\n| User understanding | Can they connect features to user needs? |\n| Agent judgment | Can they name where agents improve or damage the workflow? |\n| Prompt framing | Can they turn critique into bounded agent work? |\n\n## Speculation Is Not A Roadmap\n\nNear-term AI predictions should **read as speculation**.\n\nCheaper access to capable open models may reduce the need for some hand-built skills, video pipelines, and helper scripts. Agents may get better at noticing repeated work and creating small tools from the flow of a project.\n\nMaybe.\n\nThat is **a direction to watch, not a roadmap commitment**.\n\nMemory and tool self-improvement are moving targets. Teams are still figuring out how agents should remember past conversations, project state, repeated tool needs, and decisions that should shape future work.\n\nDo not present current model-roadmap, pricing, capability, or provider behavior claims as fact unless they are freshly verified.\n\n## Fatigue Is About Control\n\nAI fatigue grows when AI feels **forced, opaque, or outside the user's control**.\n\n> People generally get frustrated with AI when it's forced upon them, and when it's something that they haven't made themselves. And they don't feel like they have control over it.\n>\n> — John Lindquist\n\nThe answer is not \"use more AI.\" The better answer is **agency**:\n\n- adapt the tool\n- own the loop\n- inspect the result\n- measure whether it helped\n- keep review points visible\n- make automation opt-in where the decision matters\n\nSoftware examples:\n\n- A checkout team adds a tiny local wrapper that always loads failing test output before asking an agent to patch.\n- A billing team builds a review command that compares webhook strategies and requires proof commands.\n- An auth/session team adds a project-local checklist before letting an agent touch token rotation.\n- A UI team turns repeated design critique into a decision surface instead of asking the same chat prompt every day.\n\nLocal tools can change the feeling of the work because the developer can **adapt the loop and see whether the change actually helped**.\n\n## Ethics Boundary\n\nEthical concerns around AI are real and should not be waved away.\n\nA practical workflow does not need to settle training data, copyright, compensation, platform power, or labor questions. It does need to avoid pretending those concerns do not exist.\n\nThe practical workflow boundary is smaller:\n\n- review what goes into the tool\n- keep private material private\n- preserve human choice\n- make review points visible\n- do not make automation mandatory by default\n- leave room for people to say no\n\nThis does not solve the broader ethical questions. It keeps the local workflow honest.\n\n## Copyable Artifact: Product Judgment Interview Packet\n\n```text\nCandidate exercise:\n- Open a real website or app.\n- Click through one user flow.\n- Explain who the product appears to serve.\n- Name what the flow is trying to help the user accomplish.\n\nCritique:\n- What works?\n- What is confusing?\n- What user need is underserved?\n- What engineering choice might be causing the friction?\n- What evidence would you inspect before changing it?\n\nAgent fit:\n- Where could an agent improve the experience?\n- Where could an agent make it worse?\n- What should remain human-reviewed?\n- What should the agent not infer?\n\nPrompt:\n- Ask the candidate to write the first agent prompt.\n- Require scope, files or surfaces to inspect, constraints, proof, and stop condition.\n\nEvaluation:\n- Product judgment:\n- Communication:\n- Critique quality:\n- User understanding:\n- Agent boundary judgment:\n- Prompt clarity:\n```\n\n## Close The Loop\n\nThe useful follow-up is concrete:\n\n- segmented recording\n- reference links\n- setup notes\n- open questions\n- verification gaps\n- next actions\n\nDo not end with a prediction cloud. End with the materials needed to keep working.\n\n## Claim Boundaries\n\nAvoid broad labor-market claims. Avoid exact model labels, provider claims, price claims, memory-system claims, or capability predictions unless freshly verified.\n\nKeep the final message narrower and stronger: judgment, agency, review boundaries, and measurable software work still matter.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#judgment)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-imp-workflows-team-guide",
      "slug": "imp-workflows-team-guide",
      "title": "Narrow Imp agents and routing: team walkthrough",
      "summary": "Bounded one-tool agent workflow covering routing, direct execution, foreground versus forked dash-prefix prompts, fleet health, warm-mode recovery, isolation, command evidence, and marker-packet handoff. Includes cmux inspection commands, fallback receipt…",
      "category": "Team practice",
      "tags": [
        "imps",
        "routing",
        "isolation",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/1. Health",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/2. Routing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/3. Direct Imp",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/4. Dash-Prefix Demo",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/5. Marker Packet Bridge",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/6. Safety Net",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Closing Line",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 920,
      "url": "/topics/codex-imp-workflows-team-guide/",
      "markdownUrl": "/markdown/codex-imp-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-imp-workflows-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-health",
          "text": "1. Health",
          "level": 3
        },
        {
          "id": "2-routing",
          "text": "2. Routing",
          "level": 3
        },
        {
          "id": "3-direct-imp",
          "text": "3. Direct Imp",
          "level": 3
        },
        {
          "id": "4-dash-prefix-demo",
          "text": "4. Dash-Prefix Demo",
          "level": 3
        },
        {
          "id": "5-marker-packet-bridge",
          "text": "5. Marker Packet Bridge",
          "level": 3
        },
        {
          "id": "6-safety-net",
          "text": "6. Safety Net",
          "level": 3
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "closing-line",
          "text": "Closing Line",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Narrow Imp agents and routing: team walkthrough\n\n## Team Learning Goal\n\nClose the workshop by showing where bounded, tool-specific packets go next.\n\nThe core idea:\n\n```text\nAn Imp is a narrow tool agent that should run the tool before it talks.\n```\n\nBy the end of this section, the room should understand:\n\n- regular Codex vs Imp\n- when a task is tool-shaped\n- how to route before running\n- direct vs noninteractive vs quiet modes\n- warm mode and fleet management\n- isolation boundaries\n- evolution suggestions as review material\n- how a Section 8 marker packet becomes an Imp task\n- the current dash-prefix workflow:\n\n```text\n-<imp>  -> foreground route with hook-provided context\n--<imp> -> fork current Codex conversation into a cmux pane\n```\n\nThe teaching point is not \"memorize a hook.\" The teaching point is routing: keep broad reasoning in regular Codex, send bounded tool work to an Imp, and fork when the bounded task should run separately.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State the core sentence.\n2. Compare regular Codex vs Imp.\n3. Run `imp -l`, `imps doctor`, `imp --which`.\n4. Show `-rg find TODOs in src` as a foreground route.\n5. Show `--rg find TODOs in src` as a fork route only if cmux is working.\n6. Use the cmux check commands from the block message.\n7. Close with the 9-section workflow.\n\n### Expanded Walkthrough\n\nAdd:\n\n- compound routing\n- `--run`, `-q`, `--no-warm`, `--serve`\n- fleet commands\n- isolation model table\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- prompt design pattern\n- evolution suggestions\n- failure paths\n- exercises\n\n## Talking Points\n\nOpening:\n\n> An Imp is a narrow tool agent that should run the tool before it talks.\n\nOn narrowness:\n\n> If the request needs broad reasoning, it is not an Imp task yet.\n\nOn routing:\n\n> `imp --which` is the cheap check before spending a turn.\n\nOn isolation:\n\n> The isolation model keeps an Imp from becoming your whole Codex environment.\n\nOn Section 8:\n\n> A marker packet gives us the terms and boundary. The Imp runs the tool-shaped part.\n\n## Live Demo Script\n\n### 1. Health\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\n```\n\n### 2. Routing\n\n```bash\nimp --which \"what changed in git since yesterday?\"\nimp --which \"find the TODOs in src; then commit everything\"\n```\n\n### 3. Direct Imp\n\n```bash\nimp-rg --run \"find TODOs in src\"\n```\n\n### 4. Dash-Prefix Demo\n\nForeground route:\n\n```text\n-rg find checkout disabled-state code paths\n```\n\nSay:\n\n> Single dash keeps the main agent responsible. The hook resolves the Imp and gives the agent the path, description, task, and cwd.\n\nFork route:\n\n```text\n--rg find checkout disabled-state code paths\n```\n\nSay:\n\n> Double dash blocks this prompt and opens a fork. The fork receives the normalized single-dash prompt.\n\nInspect the fork with the commands printed by the block message:\n\n```bash\ncmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80\ncmux top --workspace workspace:<id> --processes --flat --format tsv\ncmux focus-pane --workspace workspace:<id> --pane pane:<id>\n```\n\n### 5. Marker Packet Bridge\n\n```bash\nimp --which \"find code paths related to acceptedTerms, selectedShipping, and checkout disabled\"\n```\n\nThen:\n\n```bash\nimp-rg --run \"Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used.\"\n```\n\n### 6. Safety Net\n\n```bash\nbun test\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- evolution suggestions\n- warm app-server internals\n- new Imp design exercise\n- detailed isolation flags\n- live `--<imp>` fork demo if cmux is not working\n\nPreserve:\n\n- core sentence\n- regular Codex vs Imp\n- `imp --which`\n- direct `imp-rg --run`\n- `-<imp>` foreground route\n- fleet health\n- Section 8 marker packet bridge\n\nIf cmux is unavailable, explain the block/fork contract and show the expected receipt shape instead:\n\n```text\ncmux workspace: workspace:<id>\ncmux pane: pane:<id>\ncmux surface: surface:<id>\ncmux window: window:<id>\n```\n\n## Boundaries\n\nDo not turn this into:\n\n- a full source-code tour\n- an implementation session for new Imps\n- broad Codex routing theory\n- a replacement for Section 4 orchestration\n\nKeep the scope:\n\n```text\none tool\none operating rule\none command map\ncommand evidence\nbounded output\n```\n\n## Failure Paths To Preserve\n\nWrong Imp:\n\n> Run `imp --which`, then use an explicit route.\n\nToo broad:\n\n> Send the broad part back to regular Codex.\n\nNo command evidence:\n\n> Strengthen the operating rule and worked examples.\n\nWarm stale:\n\n> `imps ps`, `imps stop <imp>`, `imps doctor`.\n\nEvolution unsafe:\n\n> Treat suggestions as review material, not automatic updates.\n\nDash prompt parsed as option:\n\n> Do not route dash-prefix prompts through stale `p-f` or resume helper paths. Use direct `codex fork <source-session> -- '-imp ...'`.\n\nNo cmux ids:\n\n> Treat the fork as unverified. Check `cmux-run-surface`, `cmux rpc workspace.current`, and the hook log.\n\n## Team Checklist\n\nConfirm the materials include:\n\n```text\nsingle-purpose isolated Codex agents\nnot smaller general agents\none tool\none operating rule\none command map\nreal commands first\nregular Codex vs Imp\nimp -l\nimps list\nimps ps\nimps doctor\nimp --which\nimp-rg\n--run\n-q\n--no-warm\n--serve\n--effort\ncompound routing\nimps stop\nimps evolve\ntemporary CODEX_HOME\nauth.json symlink\nbase instructions replaced\nproject docs disabled\nmemories disabled\nMCP empty\nweb search disabled\napps disabled\nwarm app-server\nsocketPath\nsourceFingerprint\nCODEX_IMP_IDLE_MINUTES\nOperating rule\nCommand map\nWorked examples\nError recovery\nOutput rules\nSection 8 marker packet\nbun test\n```\n\n## Closing Line\n\n```text\nThe workshop starts by packing broad context and ends by shrinking finished evidence into tool-shaped work.\n```\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-vision-and-automation",
      "slug": "vision-and-automation",
      "title": "Product vision and earned automation",
      "summary": "Keep product direction durable without freezing implementation, and promote recurring reviews only when their signal earns it.",
      "category": "Team practice",
      "tags": [
        "vision",
        "automation",
        "gates"
      ],
      "sources": [
        {
          "label": "Vision and automation lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q4-vision-automation"
        }
      ],
      "sourceUnits": [
        "learn.html#vision-automation-ladder",
        "learn.html#q4-vision-automation"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 368,
      "url": "/topics/factory-vision-and-automation/",
      "markdownUrl": "/markdown/factory-vision-and-automation.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-vision-and-automation.json",
      "headings": [
        {
          "id": "separate-product-direction-from-operating-instructions",
          "text": "Separate product direction from operating instructions",
          "level": 2
        },
        {
          "id": "keep-automation-at-the-lowest-justified-stage",
          "text": "Keep automation at the lowest justified stage",
          "level": 2
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "let-vision-guide-automation",
          "text": "Let vision guide automation",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Product vision and earned automation\n\nKeep product direction durable without freezing implementation, and promote recurring reviews only when their signal earns it.\n\n## Separate product direction from operating instructions\n\n`VISION.md` describes the user, intended outcome, product qualities, durable constraints, and open decisions. Code remains implementation truth. `AGENTS.md` can instead describe how an agent operates. Do not silently merge those roles or treat an old architectural diagram as a permanent restriction.\n\nFor a concrete task, make adherence explicit: **Preserve / May change / Must ask / Verification**. Strict refactoring constraints and open-ended improvement are different contracts. An agent can improve the architecture without abandoning the product’s end ideal.\n\n## Keep automation at the lowest justified stage\n\nThe promotion ladder is **manual run → deterministic script → bounded agent → non-blocking CI report → blocking gate**, with schedules and human approval as deliberate choices rather than inevitable destinations.\n\nEvery promotion needs an owner, evidence threshold, false-positive tolerance, latency and cost boundary, stop condition, and recovery path. Collect repeated manual receipts before making a result blocking. General curation and review schedules can become noise; useful on-demand execution is better than automated interruption without a decision to change.\n\n## Operating practice\n\n### Let vision guide automation\n\n#### What to notice\n\nKeep code as **implementation truth** while giving agents **durable product direction** and an explicit adherence dial.\n\n#### Try this\n\nDraft VISION.md from product evidence, then mark Preserve, May change, Must ask, and Verification for one task.\n\n> “Code is a source of truth.”\n\nJohn Lindquist · [05:35:33](https://proud-anchor-53zn.here.now/watch.html?t=20133#recording-player)\n\n#### Concept\n\nVision describes the user, outcome, qualities, durable constraints, and open decisions. It should guide improvement without freezing a stale architecture into permanent context.\n\n#### Reflection\n\nVISION.md and AGENTS.md can serve different roles. Do not silently collapse product direction and operating instructions.\n\n**Recording evidence:** listen at 05:25:50.\n\n> “This defines the end ideal of this product. And no matter what the state of the product is in, it can always push more towards that vision.”\n\nJohn Lindquist · [05:37:00](https://proud-anchor-53zn.here.now/watch.html?t=20220#recording-player)\n\n#### Links shared for this topic\n\n- [Workshop NotebookLM notebook](https://notebooklm.google.com/notebook/4ae3bcdd-b31b-4e2b-af19-7e6c702c6cc7) — The research notebook and generated artifacts shown near the close.\n- [Handy](https://handy.computer/) — A dictation tool shared during the VISION.md discussion.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=19550#q4-vision-automation)"
    },
    {
      "id": "factory-vision-and-automation-discussion",
      "slug": "vision-and-automation-discussion",
      "title": "Product vision and earned automation — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Team practice",
      "tags": [
        "vision-and-automation",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[187]",
        "resource-manifest.json#videoEvidence.concepts[188]",
        "resource-manifest.json#videoEvidence.concepts[189]",
        "resource-manifest.json#videoEvidence.concepts[190]",
        "resource-manifest.json#videoEvidence.concepts[191]",
        "resource-manifest.json#videoEvidence.concepts[192]",
        "resource-manifest.json#videoEvidence.concepts[193]",
        "resource-manifest.json#videoEvidence.concepts[194]",
        "resource-manifest.json#videoEvidence.concepts[195]",
        "resource-manifest.json#videoEvidence.concepts[196]",
        "resource-manifest.json#videoEvidence.concepts[197]",
        "resource-manifest.json#videoEvidence.concepts[198]",
        "resource-manifest.json#videoEvidence.concepts[199]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[63]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[64]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[65]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[66]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[67]",
        "resource-manifest.json#videoEvidence.exercises[18]",
        "resource-manifest.json#videoEvidence.timeline[905]",
        "resource-manifest.json#videoEvidence.timeline[908]",
        "resource-manifest.json#videoEvidence.timeline[909]",
        "resource-manifest.json#videoEvidence.timeline[911]",
        "resource-manifest.json#videoEvidence.timeline[912]",
        "resource-manifest.json#videoEvidence.timeline[913]",
        "resource-manifest.json#videoEvidence.timeline[914]",
        "resource-manifest.json#videoEvidence.timeline[915]",
        "resource-manifest.json#videoEvidence.timeline[916]",
        "resource-manifest.json#videoEvidence.timeline[917]",
        "resource-manifest.json#videoEvidence.timeline[920]",
        "resource-manifest.json#videoEvidence.timeline[922]",
        "resource-manifest.json#videoEvidence.timeline[923]",
        "resource-manifest.json#videoEvidence.timeline[924]",
        "resource-manifest.json#videoEvidence.timeline[925]",
        "resource-manifest.json#videoEvidence.timeline[926]",
        "resource-manifest.json#videoEvidence.timeline[927]",
        "resource-manifest.json#videoEvidence.timeline[928]",
        "resource-manifest.json#videoEvidence.timeline[929]",
        "resource-manifest.json#videoEvidence.timeline[930]",
        "resource-manifest.json#videoEvidence.timeline[931]",
        "resource-manifest.json#videoEvidence.timeline[932]",
        "resource-manifest.json#videoEvidence.timeline[933]",
        "resource-manifest.json#videoEvidence.timeline[937]",
        "resource-manifest.json#videoEvidence.timeline[938]",
        "resource-manifest.json#videoEvidence.timeline[939]",
        "resource-manifest.json#videoEvidence.timeline[940]",
        "resource-manifest.json#videoEvidence.timeline[941]",
        "resource-manifest.json#videoEvidence.timeline[945]",
        "resource-manifest.json#videoEvidence.timeline[948]",
        "resource-manifest.json#videoEvidence.timeline[949]",
        "resource-manifest.json#videoEvidence.timeline[950]",
        "resource-manifest.json#videoEvidence.timeline[951]",
        "resource-manifest.json#videoEvidence.uncertainties[61]",
        "resource-manifest.json#videoEvidence.uncertainties[64]",
        "resource-manifest.json#videoEvidence.demos[113]",
        "resource-manifest.json#videoEvidence.demos[114]",
        "resource-manifest.json#videoEvidence.demos[115]",
        "resource-manifest.json#videoEvidence.demos[116]"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1605,
      "url": "/topics/factory-vision-and-automation-discussion/",
      "markdownUrl": "/markdown/factory-vision-and-automation-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-vision-and-automation-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "notebooklm-artifact-generation",
          "text": "NotebookLM Artifact Generation",
          "level": 3
        },
        {
          "id": "real-time-voice-brainstorming-vs-static-audio-overviews",
          "text": "Real-Time Voice Brainstorming vs. Static Audio Overviews",
          "level": 3
        },
        {
          "id": "multi-agent-terminal-orchestration",
          "text": "Multi-Agent Terminal Orchestration",
          "level": 3
        },
        {
          "id": "mermaid-diagrams-for-agent-context",
          "text": "Mermaid Diagrams for Agent Context",
          "level": 3
        },
        {
          "id": "documentation-drift",
          "text": "Documentation Drift",
          "level": 3
        },
        {
          "id": "sliding-scale-prompt-alignment",
          "text": "Sliding Scale Prompt Alignment",
          "level": 3
        },
        {
          "id": "google-ai-subscription-tiers",
          "text": "Google AI Subscription Tiers",
          "level": 3
        },
        {
          "id": "agent-primitive-task-overhead",
          "text": "Agent Primitive Task Overhead",
          "level": 3
        },
        {
          "id": "documentation-drift-2",
          "text": "Documentation Drift",
          "level": 3
        },
        {
          "id": "vision-md-specification-concept",
          "text": "vision.md Specification Concept",
          "level": 3
        },
        {
          "id": "vision-document-vision-md",
          "text": "Vision Document (VISION.md)",
          "level": 3
        },
        {
          "id": "agentic-automation",
          "text": "Agentic Automation",
          "level": 3
        },
        {
          "id": "developer-voice-dictation-workflows",
          "text": "Developer Voice Dictation Workflows",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "can-a-single-mermaid-graph-effectively-serve-both-machine-context-injection-and-human-readable-documentation-or-should-we-treat-element-facing-context-architecture-entirely-separate-from-human-facing-notes",
          "text": "Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes?",
          "level": 3
        },
        {
          "id": "can-a-single-mermaid-graph-effectively-serve-both-machine-context-injection-and-human-readable-documentation-or-should-we-treat-element-facing-context-architecture-entirely-separate-from-human-facing-notes-2",
          "text": "Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes.",
          "level": 3
        },
        {
          "id": "does-that-require-ultra-subscription-do-you-find-value-in-the-ultra-subscription",
          "text": "Does that require ultra subscription? Do you find value in the ultra subscription?",
          "level": 3
        },
        {
          "id": "does-video-analysis-require-an-ultra-subscription-and-is-ultra-worth-it",
          "text": "Does video analysis require an Ultra subscription, and is Ultra worth it?",
          "level": 3
        },
        {
          "id": "what-s-the-name-of-the-document-again-the-one-for-documentation",
          "text": "What’s the name of the document again? The one for documentation",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-notebooklm-mcp-integration-with-gemini-cli-anti-gravity",
          "text": "Unresolved: NotebookLM MCP integration with Gemini CLI ('anti-gravity')",
          "level": 3
        },
        {
          "id": "unresolved-exact-bash-script-loop-generated-inside-claude-code-scratchpad",
          "text": "Unresolved: Exact bash script loop generated inside Claude Code scratchpad",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-26-03",
          "text": "Demonstration detail: 05:26:03",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-33-13",
          "text": "Demonstration detail: 05:33:13",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-33-19",
          "text": "Demonstration detail: 05:33:19",
          "level": 3
        },
        {
          "id": "demonstration-detail-05-39-29",
          "text": "Demonstration detail: 05:39:29",
          "level": 3
        }
      ],
      "markdown": "# Product vision and earned automation — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### NotebookLM Artifact Generation\n\nIngesting workshop transcripts and notes into Google NotebookLM to auto-generate slide decks, summaries, mind maps, and audio podcasts.\n\n### Real-Time Voice Brainstorming vs. Static Audio Overviews\n\nComparing pre-rendered podcast summaries with interactive, real-time voice conversations (e.g. ChatGPT Voice Mode) for exploratory engineering discussions.\n\n### Multi-Agent Terminal Orchestration\n\nArchitecting AI workflows where a manager pane coordinates specialized daemons (server log, source code, browser proof) using CLI tools like cmux.\n\n### Mermaid Diagrams for Agent Context\n\nA markdown-based structural diagramming syntax previously used to force models into structural alignments, now viewed by the presenter as a limiter.\n\n### Documentation Drift\n\nThe challenge where text documentation, wikis, or initial architectural specs become rapidly outdated due to active code iteration by AI models.\n\n### Sliding Scale Prompt Alignment\n\nA prompt design strategy enabling the developer to modulate how tightly the agent must adhere to strict refactoring bounds versus creative performance improvement.\n\n### Google AI Subscription Tiers\n\nEvaluating Google AI Pro vs Ultra tiers, including usage multipliers, storage limits, and bundled services like YouTube Premium.\n\n### Agent Primitive Task Overhead\n\nConversational agents like Gemini on Android failing at introductory examples (e.g. setting timers) when forced into complex agent execution loops.\n\n### Documentation Drift\n\nThe misalignment that occurs when documentation, wikis, or architectural diagrams lag behind actual code changes and team decisions.\n\n### vision.md Specification Concept\n\nA proposed project file (vision.md) defining high-level product goals, user experience, demographics, and values without prescribing technical restrictions for AI agents.\n\n### Vision Document (VISION.md)\n\nA high-level document defining the ultimate ideal state and objectives of a product, providing direction for AI agents regardless of tech stack changes.\n\n### Agentic Automation\n\nDelegating complex multi-step creative or research workflows (such as image simplification or GitHub repository analysis) to AI agents.\n\n### Developer Voice Dictation Workflows\n\nUsing speech-to-text dictation software (Super Whisper, WhisperFlow, Handy) to stream natural language prompts directly into CLI agent interfaces.\n\n## Questions and answer status\n\n### Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes?\n\n**Status: partial.** John begins explaining that human readability and machine prompt context requirements differ in code/context projects; the full explanation continues in the next shard.\n\n### Can a single mermaid graph effectively serve both machine context injection and human readable documentation, or should we treat element-facing context architecture entirely separate from human-facing notes.\n\n**Status: answered.** John explains that keeping fixed mermaid diagrams for agents is an anti-pattern because it unnecessarily limits the agent from finding better architectural configurations.\n\n### Does that require ultra subscription? Do you find value in the ultra subscription?\n\n**Status: partial.** John is unsure of the precise distinction in value-add between Pro and Ultra subscription tiers, which leads him to perform a live search query.\n\n### Does video analysis require an Ultra subscription, and is Ultra worth it?\n\n**Status: answered.** Video analysis is available on Google AI Pro. Ultra offers higher usage limits, but Pro combined with YouTube Premium family sharing provides the primary value for his workflow.\n\n### What’s the name of the document again? The one for documentation\n\n**Status: answered.** John answers that the file is vision.md (or agents.md), as confirmed in the discussion.\n\n## Exercises\n\n- **Try:** Browse the shared NotebookLM workspace to review workshop sources and generated artifacts.\n  **Basis:** John posts link in chat at 05:26:41 and invites attendees: 'So if you want to browse this, I was able to dump in all of this text and everything in here' (05:26:40).\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [05:27:10](https://proud-anchor-53zn.here.now/watch.html?t=19630#recording-player) — John compares NotebookLM Audio Overviews to real-time ChatGPT voice mode.\n\n- [05:28:38](https://proud-anchor-53zn.here.now/watch.html?t=19718#recording-player) — John exits slideshow view and comments on Google's strengths in notebook/video assets vs lagging coding features.\n\n- [05:29:02](https://proud-anchor-53zn.here.now/watch.html?t=19742#recording-player) — John reads a participant's question regarding single Mermaid graph context injection vs separate human notes.\n\n- [05:29:31](https://proud-anchor-53zn.here.now/watch.html?t=19771#recording-player) — John Lindquist contrasts writing documentation for agents versus writing it for human developers.\n\n- [05:29:39](https://proud-anchor-53zn.here.now/watch.html?t=19779#recording-player) — John states that he no longer advocates for Mermaid diagrams to exist beyond an initial prompt pass.\n\n- [05:30:10](https://proud-anchor-53zn.here.now/watch.html?t=19810#recording-player) — John mentions that Fable models can be smarter than the user, so strict adherence to human diagrams restricts alternative better solutions.\n\n- [05:31:06](https://proud-anchor-53zn.here.now/watch.html?t=19866#recording-player) — a participant notes agreement in chat that initial concepts, wikis, or mermaid diagrams cause documentation drift.\n\n- [05:31:06](https://proud-anchor-53zn.here.now/watch.html?t=19866#recording-player) — John states that modern AI experts consider AgentsMD and ClaudeMD to be anti-patterns because they limit instead of guardrail.\n\n- [05:31:55](https://proud-anchor-53zn.here.now/watch.html?t=19915#recording-player) — John explains his experimentation with adding a sliding scale to initial user prompts to control adherence to established patterns vs code improvement.\n\n- [05:32:51](https://proud-anchor-53zn.here.now/watch.html?t=19971#recording-player) — John receives and reads a question about whether this method requires an Ultra subscription and its value add.\n\n- [05:33:19](https://proud-anchor-53zn.here.now/watch.html?t=19999#recording-player) — Chrome browser shows Google search result AI Overview comparing Google AI Pro ($19.99/mo) and Google AI Ultra ($200-$250/mo).\n\n- [05:33:29](https://proud-anchor-53zn.here.now/watch.html?t=20009#recording-player) — John Lindquist discusses usage limits, YouTube Premium, and Google Drive storage.\n\n- [05:33:34](https://proud-anchor-53zn.here.now/watch.html?t=20014#recording-player) — John highlights text under Google AI Ultra regarding 20 TB - 30 TB Drive/Photos storage capacities.\n\n- [05:33:39](https://proud-anchor-53zn.here.now/watch.html?t=20019#recording-player) — John highlights text detailing YouTube Premium individual plan and Google Home Premium Advanced perks.\n\n- [05:33:43](https://proud-anchor-53zn.here.now/watch.html?t=20023#recording-player) — John highlights text describing 20x higher usage limits across Gemini, Project Genie, and Google Antigravity.\n\n- [05:33:58](https://proud-anchor-53zn.here.now/watch.html?t=20038#recording-player) — John states he believes video analysis is available on the Pro plan.\n\n- [05:34:07](https://proud-anchor-53zn.here.now/watch.html?t=20047#recording-player) — John explains sharing YouTube Premium across 5 different Google accounts for family members.\n\n- [05:34:32](https://proud-anchor-53zn.here.now/watch.html?t=20072#recording-player) — John states he derives the most value from video analysis in Gemini and YouTube family sharing.\n\n- [05:34:40](https://proud-anchor-53zn.here.now/watch.html?t=20080#recording-player) — John describes using Gemini on Android via side button for checking email and scheduling events.\n\n- [05:34:53](https://proud-anchor-53zn.here.now/watch.html?t=20093#recording-player) — John notes Gemini fails on simple tasks like timers because it invokes an agent workflow.\n\n- [05:35:12](https://proud-anchor-53zn.here.now/watch.html?t=20112#recording-player) — John reads audience comment regarding wikis, diagrams, agent constraints, and documentation drift.\n\n- [05:35:25](https://proud-anchor-53zn.here.now/watch.html?t=20125#recording-player) — John agrees documentation drift is an important problem in evolving projects.\n\n- [05:35:33](https://proud-anchor-53zn.here.now/watch.html?t=20133#recording-player) — John emphasizes that code is the source of truth.\n\n- [05:36:05](https://proud-anchor-53zn.here.now/watch.html?t=20165#recording-player) — John proposes placing a vision.md file in repositories to outline ideal product scenarios, target demographics, and experiences.\n\n- [05:36:34](https://proud-anchor-53zn.here.now/watch.html?t=20194#recording-player) — John highlights that vision.md should provide broad aspirational guidance rather than technical restrictions.\n\n- [05:36:55](https://proud-anchor-53zn.here.now/watch.html?t=20215#recording-player) — John explains that a vision document defines the ideal end goal of a product so agents can keep moving towards it.\n\n- [05:37:31](https://proud-anchor-53zn.here.now/watch.html?t=earlier-generation1#recording-player) — John tells a story about using Fable AI agent to convert a student roadrunner crayon drawing into a printable white graphic for elementary school t-shirts.\n\n- [05:37:39](https://proud-anchor-53zn.here.now/watch.html?t=earlier-generation9#recording-player) — a participant asks in chat: 'What’s the name of the document again?'\n\n- [05:39:15](https://proud-anchor-53zn.here.now/watch.html?t=20355#recording-player) — John answers that the file is vision.md or agents.md.\n\n- [05:39:37](https://proud-anchor-53zn.here.now/watch.html?t=20377#recording-player) — John launches Claude Code v2.1.212 using command cl3.\n\n- [05:39:49](https://proud-anchor-53zn.here.now/watch.html?t=20389#recording-player) — John uses Super Whisper voice dictation to speak prompt to Claude Code asking to search for VISION.md files using gh cli.\n\n- [05:40:04](https://proud-anchor-53zn.here.now/watch.html?t=20404#recording-player) — John discusses voice dictation tools, mentioning Super Whisper, WhisperFlow, and Handy.\n\n- [05:40:12](https://proud-anchor-53zn.here.now/watch.html?t=20412#recording-player) — Claude Code executes gh search code command to find VISION.md files on GitHub.\n\n### Unresolved: NotebookLM MCP integration with Gemini CLI ('anti-gravity')\n\nPresenter mentions this speculatively ('I think it's an MCP between Notebook and The Gemini agent? Once they get it inside of anti-gravity...').\n\n**Discriminating evidence:** Presenter conjecture on potential future features; no external verification required.\n\n### Unresolved: Exact bash script loop generated inside Claude Code scratchpad\n\nThe right edge of the terminal command text is cut off by the window boundary.\n\n**Discriminating evidence:** Recorded verified visible command prefix; left full script unextrapolated.\n\n### Demonstration detail: 05:26:03\n\n- Navigate to notebooklm.google.com\n- Open share modal and set public link access\n- Copy and post notebook URL to Zoom chat\n- Inspect Sources panel and Studio artifact section\n- Launch full-screen presentation mode for 'The Orchestrated Developer' slide deck\n- Page through 12 generated presentation slides\n\n**Tools observed:** NotebookLM, Google Chrome.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ncmux --json tree\ncmux new-split right\ncmux read-screen\n```\n\n### Demonstration detail: 05:33:13\n\n- Opened a new Google Chrome browser tab.\n- Typed 'google pro vs ultra' into the address bar.\n\n**Tools observed:** Google Chrome Omnibox.\n\n### Demonstration detail: 05:33:19\n\n- Browsed Google Search AI Overview comparing Google AI plans.\n- Highlighted plan details on screen.\n- Opened a new tab and typed VISION.md into address bar to check search results.\n\n**Tools observed:** Google Chrome, Google Search.\n\n### Demonstration detail: 05:39:29\n\n- Switched to Ghostty terminal\n- Ran cl3 to open Claude Code CLI v2.1.212\n- Dictated prompt using Super Whisper\n- Observed Claude Code executing gh search code and gh api script\n\n**Tools observed:** Ghostty, tmux, Claude Code v2.1.212, Super Whisper, GitHub CLI.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ncl3\nDo a gh cli search for \"VISION.md\". Please show all the variations on how people are using these files and what their purposes are.\ngh search code --filename VISION.md --limit 50 --json repository,path | jq -r '.[] | \"\\(repository.nameWithOwner)\t\\(path)\"' | sort -u\n```"
    },
    {
      "id": "codex-prompt-composition-team-guide",
      "slug": "prompt-composition-team-guide",
      "title": "Prompt Builder composition and handoff: team walkthrough",
      "summary": "Prompt composition and launch inspection through prompt text, shell commands, and JSON; named app-server threads; final-argv handoff; interactive composer controls; zsh helper bridges; and installation, binary-selection, and quoting diagnostics.",
      "category": "Team practice",
      "tags": [
        "prompt-builder",
        "prompts",
        "preflight",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/1. Prove The Binary",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/2. Print A Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/3. Preview A Command",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/4. Preview A Named Thread",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/5. Preview Handoff",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/6. Prove Zsh Helper Bridge",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Debug Paths To Mention",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 1205,
      "url": "/topics/codex-prompt-composition-team-guide/",
      "markdownUrl": "/markdown/codex-prompt-composition-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-prompt-composition-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-prove-the-binary",
          "text": "1. Prove The Binary",
          "level": 3
        },
        {
          "id": "2-print-a-prompt",
          "text": "2. Print A Prompt",
          "level": 3
        },
        {
          "id": "3-preview-a-command",
          "text": "3. Preview A Command",
          "level": 3
        },
        {
          "id": "4-preview-a-named-thread",
          "text": "4. Preview A Named Thread",
          "level": 3
        },
        {
          "id": "5-preview-handoff",
          "text": "5. Preview Handoff",
          "level": 3
        },
        {
          "id": "6-prove-zsh-helper-bridge",
          "text": "6. Prove Zsh Helper Bridge",
          "level": 3
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "debug-paths-to-mention",
          "text": "Debug Paths To Mention",
          "level": 2
        },
        {
          "id": "presenter-boundaries",
          "text": "Presenter Boundaries",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Prompt Builder composition and handoff: team walkthrough\n\n## Team Learning Goal\n\nTeach Prompt Builder as the composition boundary between routed context and agent execution.\n\nBy the end of this section, the room should understand:\n\n- why `p` exists\n- how it fits after Section 4 routing\n- how to inspect prompt text, command shape, and launch JSON\n- why named launches use app-server thread creation and `thread/name/set`\n- why handoff mode passes the prompt as a safe final argv element\n- when to choose `xfl` / `xfc` versus `p-f` / `p-c`\n- how Section 6 uses one deliberate prompt as a variation seed\n\nKeep this section practical. It is not a Rust code tour.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State: Prompt Builder is the preflight before an agent launch.\n2. Prove install: `which -a prompt-builder p`, versions.\n3. Show `p --print-prompt \"hello\"`.\n4. Show `p --dry-run --print-command \"hello\"`.\n5. Show named launch JSON with `--name`.\n6. Show handoff JSON with `/bin/echo`, `--fork-from`, and `--compact`.\n7. Bridge to `p-f` and `p-c`.\n\nPreserve these commands:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\np --print-prompt \"Review the checkout flow.\"\np --dry-run --print-command \\\n  \"Debug the billing webhook duplicate-processing bug.\"\np --print-launch-json \\\n  --name \"Auth review\" \\\n  \"Review auth/session architecture.\" \\\n  | jq '.mode, .env, .app_server'\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --fork-from last \\\n  --compact \\\n  \"continue from here\" \\\n  | jq '.mode, .argv'\n```\n\n### Expanded Walkthrough\n\nAdd:\n\n- interactive `p`\n- Name field\n- Tab movement through Name, Prompt, and options\n- `@` file selector\n- `$` skills lookup\n- `/` slash command popup\n- `Shift+Enter`\n- bracketed paste behavior\n- `Ctrl+C` clear-before-exit\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- `--stdin` plus prefilled text\n- app-server named thread explanation\n- `CODEX_THREAD_NAME`\n- `PROMPT_BUILDER_CODEX_BIN`\n- shell-function handoff through `zsh -lc`\n- debug paths for missing `p`, wrong binary, missing zsh functions, and quoting issues\n- exercise kickoff\n\n## Talking Points\n\nOpening:\n\n> We already solved routing. Now we solve what we are actually sending.\n\nCore sentence:\n\n> Prompt Builder is the checkpoint between \"I have a thought\" and \"I am launching an agent with authority.\"\n\nOn inspection modes:\n\n> `--print-prompt` saves what you said. `--print-command` shows what a human would run. `--print-launch-json` gives scripts the raw shape without parsing shell quotes.\n\nOn `--name`:\n\n> Naming is not a prompt trick. Prompt Builder creates a thread, calls `thread/name/set`, and then resumes that thread with the prompt.\n\nOn handoff:\n\n> Handoff is argv construction, not shell interpolation. The prompt is passed with `Command::arg` as the final argv element.\n\nOn `p-f` and `p-c`:\n\n> `xfl` and `xfc` act now. `p-f` and `p-c` let you compose first.\n\nOn Section 6:\n\n> One careful prompt becomes the seed for controlled variations. A sloppy prompt produces sloppy variations faster.\n\n## Live Demo Script\n\n### 1. Prove The Binary\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nPresenter note: do not dwell on install paths. The important proof is that both commands resolve and match.\n\n### 2. Print A Prompt\n\n```bash\np --print-prompt \\\n  \"Review the checkout flow for saved payment method regressions.\"\n```\n\nPresenter note: this is the cleanest Section 6 bridge.\n\n### 3. Preview A Command\n\n```bash\np --dry-run --print-command \\\n  \"Debug the failing checkout test and identify the smallest safe fix.\"\n```\n\nPresenter note: point at `-C .` and the final prompt argument.\n\n### 4. Preview A Named Thread\n\n```bash\np --print-launch-json \\\n  --name \"Checkout saved payments\" \\\n  \"Plan the first shippable slice.\" \\\n  | jq '.mode, .env, .app_server'\n```\n\nCall out:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n### 5. Preview Handoff\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  \"continue from here\" \\\n  | jq '.mode, .argv'\n```\n\nCall out:\n\n```text\nwrapper args first\ntoggle args next\nprompt last\n```\n\n### 6. Prove Zsh Helper Bridge\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\n```\n\nPresenter note: shell functions are not binaries. This is why `p-f` and `p-c` hand off through `zsh -lc`.\n\n## Boundaries\n\n| Prior Section | What It Solved | Prompt Builder Adds |\n| --- | --- | --- |\n| Section 1 | package the right project context | compose the implementation request |\n| Section 2 | make tools visible to Codex | prove `prompt-builder`, `p`, and Codex resolve |\n| Section 3 | classify aliases/functions/executables | hand off safely to zsh functions |\n| Section 4 | route pane/session/fork/export | compose before fork or compact |\n\nBridge line from Section 4:\n\n```text\nSection 4 gets us to the right session. Section 5 makes sure the next prompt is worth sending.\n```\n\nBridge line to Section 6:\n\n```text\nSection 5 ends with a deliberate prompt. Section 6 varies that prompt under control instead of improvising unrelated asks.\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- `PROMPT_BUILDER_DEBUG_KEYS`\n- detailed slash command list\n- custom `--launch-option`\n- Rust module references\n\nPreserve:\n\n```bash\nwhich -a prompt-builder p\np --print-prompt \"hello\"\np --dry-run --print-command \"hello\"\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env'\np --print-launch-json --handoff-command /bin/echo --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nIf 10 minutes behind, skip the interactive composer and say:\n\n```text\nThe TUI matters for real use, but the inspection modes teach the contract fastest.\n```\n\nIf 20 minutes behind, run only:\n\n```bash\nwhich -a prompt-builder p\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env, .app_server'\np --print-launch-json --handoff-command /bin/echo --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nClosing line if rushed:\n\n```text\nCompose first, prove the launch shape, then submit.\n```\n\n## Debug Paths To Mention\n\nMissing `p`:\n\n```bash\nwhich -a prompt-builder p\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\np --version\n```\n\nWrong build:\n\n```bash\ncargo install --path . --locked --force\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nWrong Codex binary:\n\n```bash\nPROMPT_BUILDER_CODEX_BIN=/bin/echo \\\n  p --submit --dry-run --print-command \\\n  \"hello override\"\n```\n\nMissing zsh function:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfc p-f p-c'\n```\n\nQuoting / final argv:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix this\nand keep \\$HOME literal\" \\\n  | jq '.argv'\n```\n\n## Presenter Boundaries\n\nDo not over-explain:\n\n- Ratatui internals\n- every slash command\n- full app-server protocol\n- every function in `40-ai.zsh`\n- Rust module architecture beyond what explains behavior\n- every possible Codex flag\n\nEmphasize:\n\n- exact prompt text\n- exact argv\n- exact launch mode\n- named thread flow\n- safe handoff\n- `p-f` / `p-c` as compose-before-action helpers\n- Section 6 seed prompt\n\n## Team Checklist\n\nBefore considering this section ready, confirm the materials include:\n\n```text\nPrompt Builder\npreflight\ncomposition boundary\nprompt-builder\np\nwhich -a prompt-builder p\nprompt-builder --version\np --version\ncargo install --path . --locked --force\n--stdin\n--submit\n--print-prompt\n--print-command\n--print-launch-json\n--dry-run\n--name\nCODEX_THREAD_NAME\napp-server-named-thread\nthread/name/set\n--handoff-command\n--handoff-arg\nCommand::arg\nfinal argv\n--fork-from\n--compact\n--launch-option\np-f\np-c\np-cm\nxfl\nxfc\nzsh -lc\n40-ai.zsh\n@ file selector\nskills\nslash commands\nShift+Enter\nbracketed paste\nCtrl+C\nPROMPT_BUILDER_CODEX_BIN\nSection 6\n```\n\n## Further References\n\n- team-facing file: `cheatsheets/05-prompt-builder.md`\n- Exercises: `exercises/05-prompt-builder.md`\n- Zsh helper file: `zsh/conf.d/40-ai.zsh`\n- Prompt Builder checkout: `README.md`, `src/cli.rs`, `src/main.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, `src/app_server_launch.rs`, `src/composer_input.rs`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-question-reference",
      "slug": "question-reference",
      "title": "Questions, answers, and unresolved decisions",
      "summary": "The complete anonymized question reference, preserving answered, partial, deferred, unlinked, and unanswered status.",
      "category": "Team practice",
      "tags": [
        "questions",
        "caveats",
        "decisions"
      ],
      "sources": [
        {
          "label": "Public question reference",
          "url": "https://proud-anchor-53zn.here.now/questions.md"
        }
      ],
      "sourceUnits": [
        "questions.md#question-1",
        "questions.md#question-2",
        "questions.md#question-3",
        "questions.md#question-4",
        "questions.md#question-5",
        "questions.md#question-6",
        "questions.md#question-7",
        "questions.md#question-8",
        "questions.md#question-9",
        "questions.md#question-10",
        "questions.md#question-11",
        "questions.md#question-12",
        "questions.md#question-13",
        "questions.md#question-14",
        "questions.md#question-15",
        "questions.md#question-16",
        "questions.md#question-17",
        "questions.md#question-18",
        "questions.md#question-19",
        "questions.md#question-20",
        "questions.md#question-21",
        "questions.md#question-22",
        "questions.md#question-23",
        "questions.md#question-24",
        "questions.md#question-25",
        "questions.md#question-26",
        "questions.md#question-27",
        "questions.md#question-28",
        "questions.md#question-29",
        "questions.md#question-30",
        "questions.md#question-31",
        "questions.md#question-32",
        "questions.md#question-33",
        "questions.md#question-34",
        "questions.md#question-35",
        "questions.md#question-36",
        "questions.md#question-37",
        "questions.md#question-38",
        "questions.md#question-39",
        "questions.md#question-40",
        "questions.md#question-41",
        "questions.md#question-42"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1962,
      "url": "/topics/factory-question-reference/",
      "markdownUrl": "/markdown/factory-question-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-question-reference.json",
      "headings": [
        {
          "id": "open-weight-catches-up-do-you-think-we-ll-get-another-week-of-fable-given-this-news",
          "text": "Open weight catches up. Do you think we’ll get another week of Fable given this news?",
          "level": 2
        },
        {
          "id": "re-models-better-at-finding-code-how-much-is-better-grep-ing-and-how-much-is-agents-now-using-lsps-etc",
          "text": "Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc?",
          "level": 2
        },
        {
          "id": "would-you-recommend-collecting-external-pages-then-recreating-that-on-here-now-as-my-own-example-that-will-never-change-then",
          "text": "Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then?",
          "level": 2
        },
        {
          "id": "what-do-you-call-breakpoints-where-a-human-in-the-loop-must-make-a-decision-and-approve-before-moving-to-the-next-cluster",
          "text": "What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?",
          "level": 2
        },
        {
          "id": "can-you-use-pi-with-claude-code-subscription",
          "text": "Can you use pi with Claude Code subscription?",
          "level": 2
        },
        {
          "id": "when-swapping-between-models-using-pi-when-do-you-let-a-model-bake-versus-adopting-on-day-1-like-kimi-for-day-1-adoption-what-low-risk-actions-avoid-controversy-and-how-do-you-gradually-scale-up-risk",
          "text": "When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk?",
          "level": 2
        },
        {
          "id": "working-with-claude-code-in-vs-code-still-like-to-see-what-s-happening-but-apparently-that-s-a-bit-obsolete-with-models-like-fable-5",
          "text": "Working with claude code in VS code... still like to see what's happening but apparently that's a bit obsolete with models like fable 5?",
          "level": 2
        },
        {
          "id": "when-do-you-transition-to-larger-batched-staging-or-production-interaction-like-mutating-or-deleting-a-database-and-what-must-you-observe-before-taking-that-risk-what-is-absolutely-off-limits-hard-stop-versus-an-acceptable-risk",
          "text": "When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk?",
          "level": 2
        },
        {
          "id": "what-is-linear-a-link-is-fine",
          "text": "What is linear? A link is fine",
          "level": 2
        },
        {
          "id": "do-you-have-your-dotfiles-published-anywhere-i-d-love-to-take-a-look-at-them-if-they-are-publicly-available",
          "text": "Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.",
          "level": 2
        },
        {
          "id": "when-there-s-a-stopping-point-i-m-curious-if-you-have-played-around-with-completely-dropping-local-setups-like-ghostly-s-ide-integrated-terminal-and-cli-ui-and-a-visible-git-tracking-to-develop-entirely-inside-these-high-profile-external-harnesses",
          "text": "When there’s a stopping point, I’m curious if you have played around with completely dropping local setups like Ghostly's IDE, integrated terminal and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses?",
          "level": 2
        },
        {
          "id": "cmux-herdr-is-like-hyper-ide",
          "text": "Cmux / herdr is like Hyper IDE?",
          "level": 2
        },
        {
          "id": "how-do-you-review-the-code-in-the-terminal-uis",
          "text": "How do you review the code in the terminal UIs?",
          "level": 2
        },
        {
          "id": "so-you-re-essentially-using-ai-to-provide-executive-summaries-of-the-code-changes",
          "text": "So you're essentially using AI to provide executive summaries of the code changes?",
          "level": 2
        },
        {
          "id": "do-you-use-evals-when-creating-a-skill-or-agent",
          "text": "do you use evals when creating a skill or agent?",
          "level": 2
        },
        {
          "id": "https-flameshot-org",
          "text": "https://flameshot.org/ ?",
          "level": 2
        },
        {
          "id": "https-shottr-cc-maybe",
          "text": "https://shottr.cc/  maybe?",
          "level": 2
        },
        {
          "id": "when-you-say-commit-gate-what-does-that-translate-to",
          "text": "When you say commit gate, what does that translate to?",
          "level": 2
        },
        {
          "id": "how-well-did-you-know-rust-in-order-to-build-the-prompt-builder-or-did-you-just-vibe-code-it-with-ai",
          "text": "How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI?",
          "level": 2
        },
        {
          "id": "vibe-engineer",
          "text": "Vibe Engineer?",
          "level": 2
        },
        {
          "id": "sounds-like-a-stripped-down-version-of-agent-skills-is-that-the-idea",
          "text": "Sounds like a stripped down version of agent skills, is that the idea?",
          "level": 2
        },
        {
          "id": "you-can-turn-on-fast-right",
          "text": "you can turn on fast right?",
          "level": 2
        },
        {
          "id": "question-is-flow-a-pi-with-a-custom-mdflow-preloaded-is-flow-a-shortcut-for-workflow-or-is-it-an-actual-tool",
          "text": "Question: Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?",
          "level": 2
        },
        {
          "id": "is-this-similar-to-your-concept-of-imps",
          "text": "Is this similar to your concept of imps ?",
          "level": 2
        },
        {
          "id": "given-that-anthropic-requires-you-to-use-api-based-pricing-no-subscription-usage-with-pi-or-hermes-or-openclaw-or-where-do-you-still-keep-claude-code-in-your-workflow-or-do-you-just-pay-the-api-cost-to-use-their-models-in-your-pi-setup",
          "text": "Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?",
          "level": 2
        },
        {
          "id": "do-you-have-an-orchestrator-that-manages-all-the-flows-for-example-can-it-open-a-new-herdr-tab-with-the-auditor-flow-and-notify-me-when-it-s-done-this-would-require-access-to-the-herdr-control-md-and-the-auditor-md-files",
          "text": "Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.?",
          "level": 2
        },
        {
          "id": "do-you-have-any-strategies-or-use-any-tools-like-codegraph-https-colbymchenry-github-io-codegraph-to-reduce-token-usage",
          "text": "Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?",
          "level": 2
        },
        {
          "id": "attuin-what-was-the-other-tool-and-why",
          "text": "attuin? what was the other tool and why?",
          "level": 2
        },
        {
          "id": "do-you-have-things-you-do-after-the-task-has-already-bloated-to-recover-and-simplify-do-you-have-things-you-do-when-you-don-t-understand-what-the-agent-has-done-do-you-create-html-artifacts-quizes",
          "text": "do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?",
          "level": 2
        },
        {
          "id": "how-do-you-maintain-design-consistency-across-iterations-for-example-once-you-ve-chosen-a-branding-direction-how-do-you-ensure-the-model-keeps-generating-assets-in-that-exact-style-in-my-experience-even-when-i-provide-the-same-references-it-tends-to-introduce-subtle-variations-every-time",
          "text": "How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style? In my experience, even when I provide the same references, it tends to introduce subtle variations every time.",
          "level": 2
        },
        {
          "id": "what-types-of-situations-do-you-consult-planning-creating-spec-user-stories-reviewing-diagnosing-questioning",
          "text": "what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning?",
          "level": 2
        },
        {
          "id": "do-you-have-agents-gather-context-first-do-grill-me-before-etc-how-do-you-gather-context",
          "text": "do you have agents gather context first? do grill me before, etc, how do you gather context",
          "level": 2
        },
        {
          "id": "can-you-use-the-codex-subscription-in-pi",
          "text": "Can you use the codex subscription in pi?",
          "level": 2
        },
        {
          "id": "do-you-use-notebooklm-to-send-people-artifacts-like-podcasts-videos-etc-2-do-you-create-your-own-podcasts-i-find-it-useful-for-research-papers-3-how-do-you-do-research",
          "text": "do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research?",
          "level": 2
        },
        {
          "id": "can-a-single-mermaid-graph-effectively-serve-both-machine-context-injection-and-human-readable-documentation-or-should-we-treat-llm-facing-context-architecture-entirely-separate-from-human-facing-notes",
          "text": "Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes?",
          "level": 2
        },
        {
          "id": "https-aistudio-google-com-live-model-gemini-3-1-flash-live-preview",
          "text": "https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview",
          "level": 2
        },
        {
          "id": "does-that-require-ultra-subscription-do-you-find-value-in-ultra-subscription",
          "text": "does that require ULTRA subscription? do you find value in ULTRA subscription?",
          "level": 2
        },
        {
          "id": "what-s-the-name-of-the-document-again",
          "text": "What’s the name of the document again?",
          "level": 2
        },
        {
          "id": "main-resource-or-index",
          "text": "Main resource or index?",
          "level": 2
        },
        {
          "id": "would-you-argue-for-more-use-of-git-hooks-than-more-and-more-documentation",
          "text": "Would you argue for more use of git hooks than more and more documentation?",
          "level": 2
        },
        {
          "id": "they-run-through-intelligent-schedulers-i-think-i-mean-agentic-loops-that-are-created-do-you-have-anything-on-a-schedule",
          "text": "they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?",
          "level": 2
        },
        {
          "id": "to-slash-token-costs-for-everyday-coding-how-are-you-stripping-down-the-source-code-files-before-feeding-them-to-claude-code",
          "text": "To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code?",
          "level": 2
        }
      ],
      "markdown": "# Questions, answers, and unresolved decisions\n\nThe complete anonymized question reference, preserving answered, partial, deferred, unlinked, and unanswered status.\n\n## Open weight catches up. Do you think we’ll get another week of Fable given this news?\n\n**Status: answered.** John states he hopes so because Fable uniquely interprets and handles his layout and UX engineering tasks cleanly.\n\n## Re: models better at finding code, how much is better grep-ing, and how much is agents now using LSPs, etc?\n\n**Status: deferred.** The question is left deferred during this specific segment as the presenter is explaining the historical piping model.\n\n## Would you recommend collecting external pages, then recreating that on here.now as my own example that will never change, then?\n\n**Status: answered.** Yes, John fully recommends saving references, bookmarks, screenshots, or dictations of inspiring items to build an unalterable personal source collection.\n\n## What do you call breakpoints where a human-in-the-loop must make a decision and approve before moving to the next cluster?\n\n**Status: partial.** John answers that this design pattern is commonly referred to as 'human in the loop' (HITL), with further details extending into the following segment.\n\n## Can you use pi with Claude Code subscription?\n\n**Status: answered.** John indicates that while you can technically run this configuration, he avoids doing so because Anthropic cracks down on using third-party harnesses with subscription tiers.\n\n## When swapping between models using pi, when do you let a model bake versus adopting on day 1, like Kimi? For day 1 adoption, what low-risk actions avoid controversy, and how do you gradually scale up risk?\n\n**Status: answered.** John shares that his approach to day-one adoptions for new models like Kimi involves feeding them low-risk, self-contained creative tasks such as generating independent web arcade mini-games.\n\n## Working with claude code in VS code... still like to see what's happening but apparently that's a bit obsolete with models like fable 5?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## When do you transition to larger batched staging or production interaction, like mutating or deleting a database, and what must you observe before taking that risk? What is absolutely off-limits hard stop versus an acceptable risk?\n\n**Status: answered.** The developer should construct a comprehensive logging matrix, perform numerous dry runs to explicitly review downstream output variations, and inspect observable results before conducting live mutation tasks.\n\n## What is linear? A link is fine\n\n**Status: answered.** Students in the chat clarify that Linear is a modern, high-performance project management alternative to Jira, providing the direct URL link.\n\n## Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.\n\n**Status: partial.** John shows that his public GitHub dotfiles repository is obsolete, shows his local structured setup instead, and mentions he wants to review it before publishing it properly.\n\n## When there’s a stopping point, I’m curious if you have played around with completely dropping local setups like Ghostly's IDE, integrated terminal and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses?\n\n**Status: answered.** John states he keeps external apps open only to keep remote tracking hooks running but builds and develops entirely inside his local terminal because it grants maximum power to rapidly search, spawn, and program custom behaviors.\n\n## Cmux / herdr is like Hyper IDE?\n\n**Status: answered.** John outlines that traditional IDE definitions apply to graphical suites (Zed, VS Code, IntelliJ) embedded with file-system inspectors and refactoring engines, which diverges from terminal-focused script orchestration shells.\n\n## How do you review the code in the terminal UIs?\n\n**Status: answered.** John delegates the task of code analysis to AI agents, asking them to summarize changes and write reports. He checks automated tests, smoke tests, and scenario suites rather than conducting deep manual line-by-line inspections.\n\n## So you're essentially using AI to provide executive summaries of the code changes?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## do you use evals when creating a skill or agent?\n\n**Status: partial.** John notes he is progressively incorporating automated scripted evaluations into his personal tooling stack. He highlights his experience at Vercel engineering integration infrastructure for terminal agents, where he orchestrated comprehensive evaluation sandboxes measuring prompt turn-efficiency and deployment success metrics across complex boilerplate projects.\n\n## https://flameshot.org/ ?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## https://shottr.cc/  maybe?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## When you say commit gate, what does that translate to?\n\n**Status: answered.** John explains that a commit gate translates directly to a Git commit hook. He highlights that developers can prompt an AI agent to build a customized commit hook containing tailored project requirements, such as blocklisting specific file types (like log files), checking code metrics, running formatters, or maintaining linter baselines.\n\n## How well did you know rust in order to build the prompt builder? Or did you just vibe-code it with AI?\n\n**Status: answered.** John states he only knew Rust from a few introductory examples and had never written serious Rust before. He describes his approach to 'vibe coding' as a responsible way of asking an agent for library recommendations, keyboard navigation handling, and structural architecture rather than just hoping code randomly appears.\n\n## Vibe Engineer?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## Sounds like a stripped down version of agent skills, is that the idea?\n\n**Status: answered.** John agrees conceptually and uses the question as a prompt to discuss how agent skills evolved away from their original definition toward a bloated model, contrasting them against his streamlined task-based context approach.\n\n## you can turn on fast right?\n\n**Status: answered.** John admits that he can turn it on, but typically doesn't justify the additional cost for casual individual tasks. He resolves to enable it for upcoming workshops.\n\n## Question: Is Flow a PI with a custom mdflow preloaded? Is Flow a shortcut for workflow, or is it an actual tool?\n\n**Status: answered.** John demonstrates that a flow runs markdown templates that dynamically evaluate and preload context onto files through an evaluation step prior to AI execution.\n\n## Is this similar to your concept of imps ?\n\n**Status: answered.** John answers that it is an abstracted version; 'imps' is tailored specifically for Codec, while MDFlow serves as a more general platform-agnostic alternative.\n\n## Given that Anthropic requires you to use API-based pricing (no subscription usage) with Pi (or Hermes or Openclaw, or…), where do you still keep Claude Code in your workflow? Or do you just pay the API cost to use their models in your Pi setup?\n\n**Status: answered.** John answers that he pays the API cost to use Claude Code and Fable normally, noting that the benefits outweigh the friction. He also mentions symlinking skill and memory/agent/Claude files to keep setups synchronized.\n\n## Do you have an orchestrator that manages all the flows? For example, can it open a new herdr tab with the auditor flow and notify me when it's done? This would require access to the herdr-control.md and the auditor.md files.?\n\n**Status: answered.** John states he does not use an automated orchestrator by default yet, preferring to manually dictate agent instructions via herdr help, and then provides a live scripted demo opening multiple workspace panes.\n\n## Do you have any strategies or use any tools like codegraph (https://colbymchenry.github.io/codegraph/ ) to reduce token usage?\n\n**Status: answered.** John notes that standard harnesses compress context automatically, but tool returns sometimes cause agent errors if altered too drastically. He notes that CodeGraph builds code structural maps rather than straightforward string token filtering.\n\n## attuin? what was the other tool and why?\n\n**Status: answered.** John clarified the tool name is Atuin (atuin.sh) and explained that it is a terminal history manager used for better terminal history search and keeping track of history across shells.\n\n## do you have things you do, after the task has already bloated, to recover and simplify? do you have things you do when you don't understand what the agent has done? do you create html artifacts, quizes?\n\n**Status: partial.** John begins to explain his structural project layout choices (like dedicated, gitignored folders for notes, goals, mocks, and issues) to partition distinct context categories, which continues past the current shard boundaries.\n\n## How do you maintain design consistency across iterations? For example, once you've chosen a branding direction, how do you ensure the model keeps generating assets in that exact style? In my experience, even when I provide the same references, it tends to introduce subtle variations every time.\n\n**Status: answered.** John recommends using Impeccable (impeccable.style), which records styling choices in a DESIGN.md file and provides dedicated design skills (/typeset, /colorize, /animate, /critique) to prevent AI style drift.\n\n## what types of situations do you consult? planning? creating spec? user stories? reviewing? diagnosing? questioning?\n\n**Status: answered.** John explains he consults reasoning models primarily for continuous architecture planning, handling obscure component/rendering issues in specialized frameworks (Rust GPUI), and conducting asynchronous verification passes.\n\n## do you have agents gather context first? do grill me before, etc, how do you gather context\n\n**Status: answered.** John brainstorms and breaks down the task first, then hands off to Oracle instructing it to use the packx skill to assemble and attach full repository context files.\n\n## Can you use the codex subscription in pi?\n\n**Status: answered.** John confirms that the Codex subscription can be used in Pi.\n\n## do you use notebooklm to send people artifacts, like podcasts? videos? etc? 2. do you create your own podcasts? i find it useful for research papers 3. how do you do research?\n\n**Status: unanswered.** No answer was linked in the companion evidence.\n\n## Can a single Mermaid graph effectively serve both machine context injection and human-readable documentation, or should we treat LLM-facing context architecture entirely separate from human-facing notes?\n\n**Status: answered.** John explains that keeping fixed mermaid diagrams for agents is an anti-pattern because it unnecessarily limits the agent from finding better architectural configurations.\n\n## https://aistudio.google.com/live?model=gemini-3.1-flash-live-preview\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## does that require ULTRA subscription? do you find value in ULTRA subscription?\n\n**Status: answered.** Video analysis is available on Google AI Pro. Ultra offers higher usage limits, but Pro combined with YouTube Premium family sharing provides the primary value for his workflow.\n\n## What’s the name of the document again?\n\n**Status: answered.** John answers that the file is vision.md (or agents.md), as confirmed in the discussion.\n\n## Main resource or index?\n\n**Status: unlinked.** No explicit answer was linked in the validated workshop evidence.\n\n## Would you argue for more use of git hooks than more and more documentation?\n\n**Status: answered.** John argues that while running agent evals on every git hook is currently too expensive for individuals, the upcoming release of open-weights models like K3 will make it very cheap. This allows teams to build custom vision verifier agents on commit hooks, making automated vision alignment practical and powerful within weeks.\n\n## they run through intelligent schedulers, i think i mean agentic loops that are created, do you have anything on a schedule?\n\n**Status: answered.** John describes his personal agentic 'Brain' running on a Mac Mini via GitHub and Telegram, but details that he avoids putting general curation or code review loops on a schedule because they become noise.\n\n## To slash token costs for everyday coding, how are you stripping down the source code files before feeding them to Claude Code?\n\n**Status: answered.** John states that he does not manually trim down files anymore, citing major improvements in LLM native context window management. Instead, he orchestrates multi-agent flows or redirects intermediate subtasks to lower-cost endpoints like Grok, Cursor Composer, or K3."
    },
    {
      "id": "codex-shell-environment-team-guide",
      "slug": "shell-environment-team-guide",
      "title": "Reliable non-interactive shell environments: team walkthrough",
      "summary": "Diagnosing agent tool visibility through non-interactive login-shell startup, agent-safe PATH configuration, executable precedence, clean-shell checks, and separation of interactive helpers from executable setup.",
      "category": "Team practice",
      "tags": [
        "zsh",
        "environment",
        "path",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Do Not Over-Explain",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Preserve If Short On Time",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/02-loading-zsh-env-into-codex.md#Instructor Notes: 02. Loading ZSH Env Into Codex/Boundary With Section 3",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 430,
      "url": "/topics/codex-shell-environment-team-guide/",
      "markdownUrl": "/markdown/codex-shell-environment-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-environment-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "do-not-over-explain",
          "text": "Do Not Over-Explain",
          "level": 2
        },
        {
          "id": "essential-points-to-preserve",
          "text": "Essential Points To Preserve",
          "level": 2
        },
        {
          "id": "boundary-with-section-3",
          "text": "Boundary With Section 3",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Reliable non-interactive shell environments: team walkthrough\n\n## Team Learning Goal\n\nTeach this as a tool-visibility workflow, not a dotfiles tour.\n\nThe audience should leave knowing how to ask an agent to inspect non-interactive shell startup, where safe PATH fixes belong, and how to confirm Codex can run the project tools.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Show the failure: `bun: command not found`.\n2. Explain `zsh -lc`: login, not interactive.\n3. Show the source-of-truth files.\n4. Run the basic confirmation command.\n5. Show PATH order.\n6. Explain `.zshrc` versus `codex-env.zsh`.\n7. Bridge to Section 3.\n\n### Expanded Walkthrough\n\nAdd:\n\n- clean-shell check\n- wrong executable wins\n- installer wrote `.zshrc`\n- `local.zsh` versus `00-path.zsh`\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- function versus executable\n- startup hangs from interactive code\n- secret-safe checks\n- team member exercise kickoff\n\n## Talking Points\n\nOpening:\n\n> Codex does not inherit your current terminal session. It gets a shell command environment. Prove what that environment can see.\n\nWhen showing `zsh -lc`:\n\n> Login, but not interactive.\n\nWhen showing `.zprofile`:\n\n> This is the bridge into the agent-safe environment.\n\nWhen showing `.zshrc`:\n\n> `.zshrc` is for humans. It is usually the wrong place to fix agent PATH.\n\nWhen showing `codex-env.zsh`:\n\n> This file should be boring. It gives agents tools, not terminal personality.\n\nWhen showing PATH:\n\n> PATH order decides reality. The first match wins.\n\n## Do Not Over-Explain\n\n- every zsh startup file in the manual\n- Oh My Zsh internals\n- every alias or function in John's setup\n- secret-management internals\n- prompt theme details\n- completion or ZLE mechanics\n\n## Essential Points To Preserve\n\n- `zsh -lc` is the shell shape.\n- `.zprofile` and `codex-env.zsh` are the bridge.\n- `.zshrc` is not the default fix for agent command visibility.\n- `command -v` proves tool visibility.\n- `env -u CODEX_AGENT_ENV_SOURCED` validates startup from scratch.\n\n## Boundary With Section 3\n\nSection 2 is about agent-safe executable environment.\n\nSection 3 is about zsh functions and aliases as workflow language.\n\n| Section 2 | Section 3 |\n| --- | --- |\n| `zsh -lc` proof | command DSL tour |\n| `.zprofile` | `.zshrc` |\n| `codex-env.zsh` | rich helper files |\n| deterministic PATH | aliases and functions |\n| `command -v` | `funclist`, `funcwhere`, `funced` |\n| missing-command debugging | workflow wrappers |\n| non-interactive safety | interactive productivity |\n\nBridge line:\n\n> Now that Codex can see the executables, Section 3 shows how John's zsh helpers become a workflow language.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-shell-functions-team-guide",
      "slug": "shell-functions-team-guide",
      "title": "Shell functions, aliases, and executable boundaries: team walkthrough",
      "summary": "Shell command classification, alias/function/executable tradeoffs, helper discovery and source lookup, interactive inspection versus login-shell handoff, workflow helper families, and executable fallbacks for scripts and CI.",
      "category": "Team practice",
      "tags": [
        "zsh",
        "helpers",
        "cli",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Preserve If Short On Time",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Live Demo",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Cut List",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Boundary With Section 4",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/03-zsh-functions-aliases.md#Instructor Notes: 03. ZSH Functions / Aliases/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 599,
      "url": "/topics/codex-shell-functions-team-guide/",
      "markdownUrl": "/markdown/codex-shell-functions-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-shell-functions-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "essential-points-to-preserve",
          "text": "Essential Points To Preserve",
          "level": 2
        },
        {
          "id": "live-demo",
          "text": "Live Demo",
          "level": 2
        },
        {
          "id": "optional-depth",
          "text": "Optional Depth",
          "level": 2
        },
        {
          "id": "boundary-with-section-4",
          "text": "Boundary With Section 4",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Shell functions, aliases, and executable boundaries: team walkthrough\n\n## Team Learning Goal\n\nTeach command diagnosis and workflow design, not a dotfiles tour.\n\nThe audience should leave knowing how to classify a command name, find its source, and decide whether it should be an alias, function, or executable wrapper.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Start from Section 2 executable proof.\n2. Classify helpers with `whence -w`.\n3. Show alias versus function.\n4. Show function versus executable.\n5. Locate a helper with `funcwhere`.\n6. Show a safe `zsh -lc` handoff.\n7. Bridge to Section 4.\n\n### Expanded Walkthrough\n\nAdd:\n\n- `funclist`, `funcwhere`, `funced`\n- `xfl`, `xfc`, `xport`\n- `p-f`, `p-c`\n- lazy stub explanation\n- executable fallback discussion\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- `fix`\n- `ghost-save`\n- `pksk`\n- stdout/stderr contract\n- team member DSL card exercise\n\n## Talking Points\n\nOpening:\n\n> Aliases save keystrokes. Functions encode workflows.\n\nOn classification:\n\n> The first move is not editing config. The first move is asking the shell what this name is.\n\nOn function versus executable:\n\n> A zsh function is not a binary. A subprocess that looks for a file on PATH cannot run your function unless you deliberately load zsh around it.\n\nOn aliases:\n\n> Aliases are substitutions. Useful, but not a programming language.\n\nOn functions:\n\n> Functions are where arguments, policy, fallback, cleanup, and confirmation belong.\n\nOn executable fallbacks:\n\n> If scripts, CI, or non-zsh callers need it, make it a real executable.\n\n## Essential Points To Preserve\n\nPreserve these commands:\n\n```zsh\nwhence -w <name>\ntype <name>\nalias <name>\nfunctions <name>\ncommand -v <name>\nwhence -p <name>\nfuncwhere <name>\n```\n\nPreserve these concepts:\n\n- alias vs function\n- function vs executable\n- `zsh -ic` for interactive discovery\n- `zsh -lc` for non-interactive handoff\n- `funclist`, `funcwhere`, `funced`\n- `xfl`, `xfc`, `xport`\n- `p-f`, `p-c`\n- executable fallback\n\n## Live Demo\n\nStart from Section 2 proof:\n\n```zsh\nzsh -lc 'echo CODEX_AGENT_ENV_SOURCED=$CODEX_AGENT_ENV_SOURCED; command -v codex bun pnpm cargo packx || true'\n```\n\nShow helper visibility:\n\n```zsh\nzsh -ic 'for name in funclist funcwhere funced x xi xfl xfc xport fix agent_chain muxai p-f p-c ghost-save pksk; do printf \"%-14s \" \"$name\"; whence -w \"$name\" 2>/dev/null || echo MISSING; done'\n```\n\nShow source:\n\n```zsh\nfuncwhere xfl\nfuncwhere xfc\nfuncwhere fix\nfuncwhere agent_chain\nfuncwhere muxai\n```\n\nShow safe handoff:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'\n```\n\nBridge to Section 4:\n\n```zsh\nwhence -w muxai agent_chain\nfuncwhere muxai\nfuncwhere agent_chain\n```\n\n## Optional Depth\n\nIf 5 minutes behind, cut:\n\n- function body reading\n- helper family details\n- stdout/stderr contract\n\nIf 10 minutes behind, cut:\n\n- `ghost-save`\n- `cfix`\n- lazy stub internals\n- Prompt Builder details beyond `p-f` and `p-c`\n\nIf 20 minutes behind, run only:\n\n```zsh\nzsh -ic 'for name in funclist funcwhere funced xfl xfc xport fix agent_chain muxai; do printf \"%-14s \" \"$name\"; whence -w \"$name\" 2>/dev/null || echo MISSING; done'\nzsh -ic 'funcwhere xfl; funcwhere xfc; funcwhere fix; funcwhere agent_chain; funcwhere muxai'\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfl xfc xport p-f p-c'\n```\n\n## Boundary With Section 4\n\nSection 3 gives the command language. Section 4 puts that language into panes, threads, forks, transcript exports, and agent chains.\n\nBridge line:\n\n> Section 3 made the commands real. Section 4 makes the commands addressable.\n\n## Further References\n\n- team member cheatsheet: `cheatsheets/03-zsh-functions-aliases.md`\n- Exercises: `exercises/03-zsh-functions-aliases.md`\n- Helper file: `zsh/conf.d/40-ai.zsh`\n- Fix helper source: `zsh/conf.d/47-ai-fix.zsh`\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n- Zsh manual, Functions: https://zsh.sourceforge.io/Doc/Release/Functions.html\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-choice-surface",
      "slug": "choice-surface",
      "title": "Turn generated choices into saved human decisions",
      "summary": "A chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.",
      "category": "Team practice",
      "tags": [
        "web-choices",
        "human-review",
        "mobile"
      ],
      "sources": [
        {
          "label": "Codex workflows companion",
          "url": "https://lapis-fossil-vsbc.here.now/#choice-surface"
        },
        {
          "label": "Published workshop recording",
          "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
        }
      ],
      "sourceUnits": [
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Problem",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Move",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Smallest Useful Version",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The UI Contract",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Persistence Is The Trust Boundary",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/The Phone Workflow",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Tunnel Boundary",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Copyable Artifact: Mobile Decision Surface Brief",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/If It Goes Wrong",
        "src/content/final/chunk-11-turn-generated-choices-into-a-mobile-decision-surface.md#Turn Generated Choices Into A Mobile Decision Surface/Claim Boundaries",
        "src/lib/content/sections.ts",
        "src/lib/content/sections.ts#choice-surface",
        "src/lib/content/sections.ts#recordingSpans"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 1151,
      "url": "/topics/codex-choice-surface/",
      "markdownUrl": "/markdown/codex-choice-surface.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-choice-surface.json",
      "headings": [
        {
          "id": "the-problem",
          "text": "The Problem",
          "level": 2
        },
        {
          "id": "the-move",
          "text": "The Move",
          "level": 2
        },
        {
          "id": "the-smallest-useful-version",
          "text": "The Smallest Useful Version",
          "level": 2
        },
        {
          "id": "the-ui-contract",
          "text": "The UI Contract",
          "level": 2
        },
        {
          "id": "persistence-is-the-trust-boundary",
          "text": "Persistence Is The Trust Boundary",
          "level": 2
        },
        {
          "id": "the-phone-workflow",
          "text": "The Phone Workflow",
          "level": 2
        },
        {
          "id": "tunnel-boundary",
          "text": "Tunnel Boundary",
          "level": 2
        },
        {
          "id": "copyable-artifact-mobile-decision-surface-brief",
          "text": "Copyable Artifact: Mobile Decision Surface Brief",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "claim-boundaries",
          "text": "Claim Boundaries",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Turn generated choices into saved human decisions\n\nA chat thread is fine for discussion. It is a bad place to approve a shortlist, reject two options, add per-option notes, and hand the result back to an agent as durable state.\n\nWhen an agent generates options, turn them into a **small picker**. Review it on a phone, tap the choices that should survive, dictate notes, submit, and make the agent continue from the saved JSON.\n\n```text\ngenerated options\n-> structured choice job\n-> Svelte + mdsvex picker\n-> token-gated mobile URL through a reviewed tunnel\n-> click/dictate feedback\n-> saved submission\n-> agent resumes from persisted JSON\n```\n\n## The Problem\n\nGenerated options are useful until they become a wall of text.\n\nThe agent offers five reasonable strategies for a checkout fix, billing webhook retry plan, auth/session tradeoff, QA screenshot triage, or design variation. You are away from the desk. The mobile chat thread now expects you to remember option names, type a careful answer, and trust the agent to turn that paragraph back into structured state.\n\nThat is where decisions get mushy.\n\n## The Move\n\nGenerated choices should **become data, not another paragraph**.\n\nThe agent should produce a **choice job** with stable option ids, titles, descriptions, risk notes, and proof hints. A small review UI renders those choices as cards. The human selects options, adds per-option feedback, adds overall feedback, and submits. The agent waits for the saved submission before continuing.\n\nUse this when the next step needs a human decision:\n\n- choose among generated UI variations\n- pick a billing webhook idempotency strategy\n- choose an auth/session migration path\n- approve or reject model-council recommendations\n- triage screenshot or debug-packet follow-ups\n- select the first implementation plan after a broad exploration\n\n## The Smallest Useful Version\n\nThe picker does not need to be elaborate. It needs stable ids, checkboxes, per-option notes, one overall feedback box, draft saving, and a submit button that writes durable JSON.\n\n```text\nChoice job:\n- jobId:\n- title:\n- description:\n\nOptions:\n- id:\n  title:\n  description:\n  risk:\n  suggested proof:\n  expected evidence:\n\nHuman response:\n- selected option ids:\n- per-option feedback:\n- overall feedback:\n\nResume rule:\n- continue only after a saved submission exists\n- resume from persisted JSON, not memory\n```\n\n## The UI Contract\n\n**Web Choices** uses a Svelte + mdsvex browser UI. The app shell can be branded and pleasant, but the generated choices stay plain JSON.\n\nKeep this boundary:\n\n- mdsvex owns the page/template shell\n- Svelte owns cards, selection state, feedback fields, save state, and submit controls\n- generated option text remains data\n- generated option text is not compiled as Svelte or mdsvex source\n\nThat boundary matters. A decision surface should not become a tiny CMS that compiles model output as app code.\n\n## Persistence Is The Trust Boundary\n\n**No saved submission, no continuation.**\n\nDrafts are for humans. Submissions are for agents.\n\n> I need you to make these decisions before I continue further, and so I look at it, I click the ones I want, give feedback on it, and then submit, and then it continues. So you create a really asynchronous feedback loop between your local agent and how you're talking to it on your phone.\n>\n> — John Lindquist\n\nThe durable state lives under a caller-selected human-in-the-loop output directory, commonly `.hitl-choice`:\n\n```text\n.hitl-choice/\n  current-job.json\n  drafts/\n  submissions.jsonl\n  submissions/<submissionId>.json\n```\n\nThe agent should wait until a final submission exists, then read selected option ids, per-option feedback, and overall feedback from the saved JSON. It should not infer the decision from visible UI state, draft text, or chat memory.\n\n## The Phone Workflow\n\n**The phone is for decisions, not implementation.**\n\n> Click, dictate, click, dictate has been the best workflow for me.\n>\n> — John Lindquist\n\nThe useful mobile loop is intentionally small:\n\n```text\ntap option\ndictate note\ntap option\ndictate note\nadd overall feedback\nsubmit\n```\n\nThis works best when the agent has already done the expansion work. The human does the selection work.\n\n## Tunnel Boundary\n\nA **reviewed, short-lived tunnel** can make the local picker reachable from a phone. Keep the specific tunnel product and hostname setup-specific unless the demo evidence is added and sanitized.\n\nThe important lesson is not the exact hostname. The important lesson is:\n\n- keep the local server alive while waiting\n- expose a short-lived token-gated URL\n- let the human submit structured feedback\n- resume from persisted JSON\n\nDo not treat a token-gated URL as full authentication. It is **useful friction, not a product security model**.\n\n## Copyable Artifact: Mobile Decision Surface Brief\n\n```text\nUse this when:\n- an agent generated several options\n- the human needs to choose or annotate them\n- the next step should not continue until the choice is saved\n- the human may be reviewing from a phone\n\nChoice job:\n- jobId:\n- title:\n- description:\n- options:\n  - id:\n    title:\n    description:\n    risk:\n    suggested proof:\n    expected evidence:\n\nUI requirements:\n- render options as cards\n- allow multiple selection when appropriate\n- collect per-option feedback\n- collect overall feedback\n- save drafts while editing\n- write final submission only on submit\n\nPersistence:\n- active job: .hitl-choice/current-job.json\n- drafts: .hitl-choice/drafts/\n- final log: .hitl-choice/submissions.jsonl\n- final packet: .hitl-choice/submissions/<submissionId>.json\n\nAgent stop rule:\n- wait for a saved submission\n- read selected ids and feedback from JSON\n- continue only from the persisted submission\n- report blocked if no submission exists\n\nSharing boundary:\n- do not expose real tunnel URLs\n- do not expose tokens\n- do not expose hostnames\n- do not expose or share private options or submissions\n- do not call the token full authentication\n```\n\nExample prompt:\n\n```text\nTurn these billing webhook strategies into a Web Choices job.\n\nEach option needs:\n- stable id\n- short title\n- concrete description\n- risk\n- suggested proof command\n- pass/fail evidence\n\nServe it as a phone-friendly picker, wait for the saved submission, then continue only from the persisted JSON.\n```\n\n## If It Goes Wrong\n\nIf the tunnel fails, keep the same job state when possible. Reuse the token only if it was not exposed; otherwise rotate the token, restart the tunnel, and verify the current job is reachable before asking for another decision.\n\nIf the server dies, inspect the output directory first. Restart with the same state if drafts or submissions already exist.\n\nIf the human says they submitted but the wait command has not returned, check `submissions.jsonl`, per-submission files, and whatever reviewed server logs or status endpoint the current implementation exposes before regenerating choices.\n\n## Claim Boundaries\n\nWeb Choices is a local human-in-the-loop pattern with a small web UI and durable files. It is not a production approvals system by default.\n\nVerify timeout behavior, tunnel behavior, mobile rendering, submission persistence, and data handling in the current setup before sharing executable setup instructions.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#choice-surface)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
    },
    {
      "id": "codex-video-workflows-team-guide",
      "slug": "video-workflows-team-guide",
      "title": "Video analysis and evidence workflows: team walkthrough",
      "summary": "Evidence-preserving video analysis workflow: preserve and hash media, inspect with ffprobe, prompt Gemini through Oracle browser mode, check session output, separate evidence lanes, and produce downstream prompts, requirements, bugs, QA, or variation…",
      "category": "Team practice",
      "tags": [
        "video",
        "oracle",
        "evidence",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/1. Create Run Folder",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/2. Preserve Source",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/3. Write Prompt With Sentinel",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/4. Show Correct Call Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/5. Verify Output",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Live Demo Script/6. Bridge To Downstream Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Cut Path",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Boundaries/From Section 6",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Boundaries/To Section 8",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Presenter Checklist",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/07-video-as-prompts.md#Instructor Notes: 07. Video As Prompts/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 780,
      "url": "/topics/codex-video-workflows-team-guide/",
      "markdownUrl": "/markdown/codex-video-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-video-workflows-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "live-demo-script",
          "text": "Live Demo Script",
          "level": 2
        },
        {
          "id": "1-create-run-folder",
          "text": "1. Create Run Folder",
          "level": 3
        },
        {
          "id": "2-preserve-source",
          "text": "2. Preserve Source",
          "level": 3
        },
        {
          "id": "3-write-prompt-with-sentinel",
          "text": "3. Write Prompt With Sentinel",
          "level": 3
        },
        {
          "id": "4-show-correct-call-shape",
          "text": "4. Show Correct Call Shape",
          "level": 3
        },
        {
          "id": "5-verify-output",
          "text": "5. Verify Output",
          "level": 3
        },
        {
          "id": "6-bridge-to-downstream-work",
          "text": "6. Bridge To Downstream Work",
          "level": 3
        },
        {
          "id": "minimal-useful-path",
          "text": "Minimal Useful Path",
          "level": 2
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "from-section-6",
          "text": "From Section 6",
          "level": 3
        },
        {
          "id": "to-section-8",
          "text": "To Section 8",
          "level": 3
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "team-checklist",
          "text": "Team Checklist",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Video analysis and evidence workflows: team walkthrough\n\n## Team Learning Goal\n\nTeach video as evidence-rich prompt material, not as a novelty or transcript shortcut.\n\nBy the end of this section, the room should understand:\n\n- why video can carry context text drops\n- when video is worth the overhead\n- how `oracle-video` relates to `oracle-packx`\n- why Gemini browser mode is required for video\n- how source hashes, `ffprobe`, timestamps, keyframes, and `output.log` make analysis checkable\n- why transcript, chat, visual evidence, and inference must stay separate\n- how verified video analysis becomes prompts, bugs, requirements, QA, lessons, or Section 6 variation matrices\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Say: video is prompt material.\n2. Show the short path vs long path table.\n3. Show the correct Oracle/Gemini call shape.\n4. Show `shasum`, `ffprobe`, and `END_OF_VIDEO_ANALYSIS`.\n5. Show evidence lanes.\n6. End with downstream prompt examples.\n\n### Expanded Walkthrough\n\nAdd:\n\n- run folder shape\n- `yt-dlp` metadata/download flow\n- keyframes/contact sheet\n- omissions pass\n- bug repro prompt shape\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- chunking long recordings\n- requirements artifact\n- Section 6 variation matrix from video evidence\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Video is prompt material.\n\nOn transcripts:\n\n> A transcript tells you what was said. It does not prove what was visible.\n\nOn evidence lanes:\n\n> Spoken claims, visible facts, chat messages, and inferences do different jobs. Keep them separate.\n\nOn Gemini:\n\n> Text models do not watch the video. The video-watching step belongs to Gemini through Oracle browser mode.\n\nOn source preservation:\n\n> If the original media is not preserved, every later claim gets harder to trust.\n\nOn Section 8:\n\n> Section 7 preserves evidence from video. Section 8 puts that same discipline inside live debugging with markers.\n\n## Live Demo Script\n\n### 1. Create Run Folder\n\n```bash\nRUN_ID=\"checkout-repro\"\nRUN_DIR=\"runs/$RUN_ID\"\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,analysis,final,keyframes,contact-sheets}\nmkdir -p \"$RUN_DIR/chunks/01\"\n```\n\n### 2. Preserve Source\n\n```bash\ncp /path/to/source-video.mp4 \"$RUN_DIR/inputs/source-video.mp4\"\nshasum -a 256 \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/inputs/source-video.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source-video.mp4\" \\\n  > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\n### 3. Write Prompt With Sentinel\n\n```bash\ncat > \"$RUN_DIR/chunks/01/gemini-prompt.md\" <<'EOF'\nAnalyze this video as prompt material for a software project.\n\nSeparate transcript evidence, chat evidence, visual evidence, and inference.\nPreserve timestamps.\nDo not invent URLs, tools, commands, files, UI labels, or speakers.\nEnd with END_OF_VIDEO_ANALYSIS.\n\nEND_OF_VIDEO_ANALYSIS\nEOF\n```\n\n### 4. Show Correct Call Shape\n\n```js\nmcp__oracle__consult({\n  prompt: \"[checkout-repro-video]\\n\\n{contents of chunks/01/gemini-prompt.md}\",\n  files: [\"/absolute/path/to/runs/checkout-repro/chunks/01/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",\n  browserAttachments: \"always\",\n  slug: \"checkout-repro-video\"\n})\n```\n\n### 5. Verify Output\n\n```bash\nrg -n \"END_OF_VIDEO_ANALYSIS\" ~/.oracle/sessions/checkout-repro-video/output.log\n```\n\n### 6. Bridge To Downstream Work\n\nShow one of:\n\n- repro steps\n- implementation prompt\n- design-change brief\n- QA checklist\n- Section 6 variation matrix\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- `yt-dlp`\n- contact sheet command\n- long recording folder details\n- omissions pass prompt\n\nPreserve:\n\n- video is prompt material\n- Gemini browser mode\n- `browserAttachments: \"always\"`\n- source hash\n- `ffprobe`\n- evidence lanes\n- sentinel\n- downstream prompt\n\nIf 15 minutes behind, run only:\n\n```text\nsource -> hash -> ffprobe -> Gemini browser mode -> evidence lanes -> verified downstream prompt\n```\n\n## Boundaries\n\n### From Section 6\n\nSection 6 teaches:\n\n```text\none deliberate prompt -> controlled variations\n```\n\nSection 7 expands what can become prompt material:\n\n```text\nvideo -> verified evidence -> downstream prompt or variation matrix\n```\n\n### To Section 8\n\nSection 8 moves the same discipline into live debugging:\n\n```text\nmark -> capture -> explain -> review/export\n```\n\n## Failure Paths To Preserve\n\nWrong Oracle mode:\n\n> If video analysis used API mode, rerun in browser mode.\n\nTranscript-only summary:\n\n> Ask for visual evidence and an omissions pass. Do not treat transcript as full analysis.\n\nInvented URL/tool/file:\n\n> Remove it or label it as inference. Unsupported details cannot become requirements.\n\nNo sentinel:\n\n> Inspect `output.log`. If the sentinel is missing, rerun or request a focused correction.\n\nNo source hash:\n\n> Stop and preserve the source before continuing.\n\nLong recording not chunked:\n\n> Segment/chunk before asking for a full packet.\n\n## Team Checklist\n\nConfirm the materials include:\n\n```text\nvideo is prompt material\noracle-video\nGemini\nengine: \"browser\"\nmodel: \"gemini-3-pro\"\nbrowserAttachments: \"always\"\nabsolute file paths\nyt-dlp\nffprobe\nsha256\nsource hash\noriginal timestamps\nEND_OF_VIDEO_ANALYSIS\noutput.log\nkeyframes\ncontact sheets\ntranscript evidence\nchat evidence\nvisual evidence\ninference\nomissions pass\nno invented URLs/tools/commands/files\nbug reproduction\ndesign feedback\napp walkthrough\nrequirements\nQA checklist\nimplementation prompt\nSection 6 variation matrix\nSection 8 agent markers bridge\n```\n\n## Further References\n\n- team-facing file: `cheatsheets/07-video-as-prompts.md`\n- Exercises: `exercises/07-video-as-prompts.md`\n- `oracle-video` skill reference: `.agents/skills/oracle-video/SKILL.md`\n- `yt-dlp`: https://github.com/yt-dlp/yt-dlp\n- FFmpeg documentation: https://ffmpeg.org/documentation.html\n- `ffprobe` documentation: https://ffmpeg.org/ffprobe.html\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "factory-visible-workspaces",
      "slug": "visible-workspaces",
      "title": "Visible workspaces for agents and swarms",
      "summary": "Expose pane state, separate execution from verification, and supervise bounded independent work.",
      "category": "Team practice",
      "tags": [
        "visible",
        "factory"
      ],
      "sources": [
        {
          "label": "Visible workspaces for agents and swarms",
          "url": "https://summit-inlet-kxyf.here.now/"
        },
        {
          "label": "Companion lesson",
          "url": "https://proud-anchor-53zn.here.now/learn.html#q1-launcher-workspaces"
        }
      ],
      "sourceUnits": [
        "06-pi-herdr-ghostty/index.html#TL;DR",
        "06-pi-herdr-ghostty/index.html#The stack: each layer exposes its state to the one above",
        "06-pi-herdr-ghostty/index.html#Appendix",
        "06-pi-herdr-ghostty/index.html#Two configs shake hands: keyboard to focused pane",
        "06-pi-herdr-ghostty/index.html#The three chords worth stealing (complete config)",
        "06-pi-herdr-ghostty/index.html#The keeper: one agent babysits the rest",
        "06-pi-herdr-ghostty/index.html#Swarms: plan until independent, then fan out",
        "learn.html#q1-launcher-workspaces"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1829,
      "url": "/topics/factory-visible-workspaces/",
      "markdownUrl": "/markdown/factory-visible-workspaces.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces.json",
      "headings": [
        {
          "id": "related-working-material",
          "text": "Related working material",
          "level": 2
        },
        {
          "id": "tl-dr",
          "text": "TL;DR",
          "level": 2
        },
        {
          "id": "the-stack-each-layer-exposes-its-state-to-the-one-above",
          "text": "The stack: each layer exposes its state to the one above",
          "level": 2
        },
        {
          "id": "two-configs-shake-hands-keyboard-to-focused-pane",
          "text": "Two configs shake hands: keyboard to focused pane",
          "level": 2
        },
        {
          "id": "the-three-chords-worth-stealing-complete-config",
          "text": "The three chords worth stealing (complete config)",
          "level": 3
        },
        {
          "id": "the-keeper-one-agent-babysits-the-rest",
          "text": "The keeper: one agent babysits the rest",
          "level": 2
        },
        {
          "id": "swarms-plan-until-independent-then-fan-out",
          "text": "Swarms: plan until independent, then fan out",
          "level": 2
        },
        {
          "id": "appendix",
          "text": "Appendix",
          "level": 2
        },
        {
          "id": "limits-caveats",
          "text": "Limits & caveats",
          "level": 3
        },
        {
          "id": "operating-practice",
          "text": "Operating practice",
          "level": 2
        },
        {
          "id": "keep-wrappers-thin-and-work-visible",
          "text": "Keep wrappers thin and work visible",
          "level": 3
        },
        {
          "id": "what-to-notice",
          "text": "What to notice",
          "level": 4
        },
        {
          "id": "try-this",
          "text": "Try this",
          "level": 4
        },
        {
          "id": "concept",
          "text": "Concept",
          "level": 4
        },
        {
          "id": "reflection",
          "text": "Reflection",
          "level": 4
        },
        {
          "id": "links-shared-for-this-topic",
          "text": "Links shared for this topic",
          "level": 4
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms\n\nExpose pane state, separate execution from verification, and supervise bounded independent work.\n\n## Related working material\n\n- [Visible workspaces for agents and swarms — prompts and exercises](/topics/factory-visible-workspaces-practice/)\n- [Visible workspaces for agents and swarms — questions and tradeoffs](/topics/factory-visible-workspaces-questions/)\n- [Visible workspaces for agents and swarms — worked example](/topics/factory-visible-workspaces-worked-example/)\n\n## TL;DR\n\n- A terminal stack whose pane model is fully scriptable over a unix socket — by your keyboard, your scripts, and your agents.\n- You walk away with a read-only recon command set, a complete 3-chord keyboard config, and the keeper prompt: an agent that keeps other agents moving.\n- The one move: paste the keeper prompt into pi running inside a herdr pane. It answers stuck prompts, restarts crashes, and unsticks its siblings.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch https://summit-inlet-kxyf.here.now/agent.md?raw and follow it to drive my herdr session from this agent. Run the success check at the end and show me the result.\n```\n\n## The stack: each layer exposes its state to the one above\n\nThe tempting way to pick a terminal for agent work is comparing feature lists. This setup rejects that framing. It is four small layers, and the selection rule is visible in the configs: each layer exposes its state to the layer above.\n\n**Ghostty** only draws pixels and forwards keys. **Herdr** (0.7.3, \"terminal workspace manager for AI coding agents\") runs as a client/server pair over a unix socket and surfaces the whole workspace → tab → pane model as CLI subcommands: `workspace`, `tab`, `pane`, `agent`, `wait`. The server keeps every pane alive with no window attached — quit Ghostty entirely and `herdr` reattaches to everything. **Pi** (0.80.10) is the agent inside the panes; herdr's integration installs a pi extension that reports the agent's state — idle, working, blocked — back over the socket, so a workspace listing truthfully says which agents are busy because the agents report it themselves. **Karabiner** turns all of it into single keystrokes.\n\nThe test for your own setup: ask what your terminal will tell a script about its panes. If the answer is \"nothing,\" everything below is out of reach regardless of features.\n\n## Two configs shake hands: keyboard to focused pane\n\nKarabiner knows the keyboard but not which pane is focused. Herdr knows the focused pane but not global hotkeys. The handshake: Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and herdr's `[[keys.command]]` bindings translate each chord into a command that receives the focused pane's context. The herdr config states the design in a comment: \"Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane.\"\n\nHolding Esc turns the home row into a herdr command deck:\n\n| Hold Esc + | Action                                                        |\n|------------|---------------------------------------------------------------|\n| Z / F      | Open the focused pane's cwd in Zed / Finder                   |\n| O          | Smart open: URL, file:line reference, or cwd — whichever fits |\n| E          | Open the latest file:line reference in Zed                    |\n| R / P      | Open the current GitHub repo / the PR for the current branch  |\n| Y          | Copy pane/repo context                                        |\n| L          | Pick a URL from pane output (temporary picker pane)           |\n| Space      | Search ALL pane output; picking a hit focuses that pane       |\n| X / N      | Open Codex / Prompt Builder in a new pane                     |\n| Return     | Zoom the focused pane                                         |\n\nOne layer up, a comma simlayer jumps between projects: , plus a letter focuses a workspace by label, falls back to matching panes by cwd, and creates the workspace if neither exists.\n\n### The three chords worth stealing (complete config)\n\nWire three chords, not thirty: *open-cwd-in-editor*, *open-repo*, and *search-all-panes-to-focus*. Three files. The helper script is a minimal, self-contained stand-in for the presenter's personal 1,200-line helper (see appendix) — it needs `herdr`, `jq`, and per verb `zed`, `gh`, or `fzf`.\n\n``` text\n#!/bin/sh\n# Focus-aware chord actions for a herdr session. chmod +x this file.\n# Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires.\nset -eu\npane=\"${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}\"\ncwd=\"$(herdr pane get \"$pane\" | jq -r '.result.pane.foreground_cwd')\"\ncase \"${1:-}\" in\n  zed)  zed \"$cwd\" ;;\n  repo) cd \"$cwd\" && gh repo view --web ;;\n  pane-search)\n    herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do\n      herdr pane read \"$p\" --source recent-unwrapped --lines 200 2>/dev/null \\\n        | grep -v '^[[:space:]]*$' | sed \"s|^|$p  |\"\n    done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;;\n  *) echo \"usage: herdr-chords zed|repo|pane-search\" >&2; exit 2 ;;\nesac\n```\n\n``` text\n# Karabiner emits these internal chords only while Ghostty is frontmost;\n# Herdr supplies the exact focused inner pane.\n\n[[keys.command]]              # Esc+Z -> open focused pane's cwd in Zed\nkey = \"ctrl+alt+z\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords zed\"\n\n[[keys.command]]              # Esc+R -> open focused pane's GitHub repo\nkey = \"ctrl+alt+r\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords repo\"\n\n[[keys.command]]              # Esc+Space -> search every pane, jump to the hit\nkey = \"ctrl+alt+shift+l\"\ntype = \"pane\"                 # runs in a temporary pane; it closes after you pick\ncommand = \"$HOME/.local/bin/herdr-chords pane-search\"\n```\n\n``` text\n;; Goku / Karabiner-Elements. Tap Esc = normal Esc.\n;; Hold Esc + key = chord, only while Ghostty is frontmost.\n\n;; under :applications\n:ghostty [\"com.mitchellh.ghostty\"]\n\n;; under :layers — hold-Esc layer; tap still sends Esc\n:escape-mode {:key :escape\n              :params {:basic.to_if_alone_timeout_milliseconds 200\n                       :basic.to_if_held_down_threshold_milliseconds 200}\n              :alone [{:key :escape}]}\n\n;; under :main — the three chords\n{:des   \"Ghostty: Escape Mode Herdr actions\"\n :rules [[:condi :ghostty :escape-mode]\n         [:-z {:key :z :modi [:left_control :left_option]}]       ; Esc+Z\n         [:-r {:key :r :modi [:left_control :left_option]}]       ; Esc+R\n         [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space\n```\n\n## The keeper: one agent babysits the rest\n\n\"Have pi keep other panes alive\" is two mechanisms. Herdr keeps the *panes* alive structurally — the server outlives every window. Pi keeps the *agents in* those panes alive operationally: because herdr injects the socket path and pane id into every pane, a pi session can supervise its siblings with ordinary shell commands — read what a sibling printed, answer its stuck confirmation prompt, restart its crashed command, and block on `herdr wait agent-status` instead of burning tokens polling. That is the keeper prompt above, and its two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock.\n\nThis is not hypothetical self-inspection. On the recorded workflow, a pi session used pane capture to check glyph rendering in its own herdr pane — and in doing so surfaced a real bug in `herdr pane run`. The success check above is that same move, packaged.\n\nThe signal the keeper is working: interventions get *rarer* over a session. A keeper that intervenes constantly is masking a bad task split — fix the plan, not the babysitter.\n\n## Swarms: plan until independent, then fan out\n\nThe agenda bullet carries its own warning label: \"lots of planning with a smart model first!\" The swarm is the cheap part; the plan is the whole game. Run the decomposition prompt above with your strongest model, and argue with the output — if two workers would touch the same file, you are not done planning. Then fan out each brief into a visible pane as a direct process:\n\n``` text\nherdr agent start learners --cwd ~/dev/proj/sites/learners --split right \\\n  -- bash -lc 'pi -p \"$(cat briefs/learners.md)\"'\n```\n\nThe argv launch matters: no shell, no typed command, no startup race — \"the launch race cannot happen, by construction\" (the pi-herdr-subagents README, a herdr-native descendant of HazAT's pi-interactive-subagents). Death is observable too: herdr emits `pane.exited` socket events within milliseconds, so a dead worker is an event, not a screen that stopped changing. Captured from the running server the day before the workshop:\n\n``` text\nIllustrative workspace responsibilities:\norchestrator — plan and coordinate\nworker-a — independently scoped audience/site\nworker-b — independently scoped audience/site\nworker-c — independently scoped audience/site\n```\n\nOne pi orchestrator, three workers, each confined to its own directory — exactly the shape the planning prompt demands. Every worker is watchable (glance at its pane), interruptible (click in and type), and composable with the keeper: one pane's pi can babysit the whole swarm.\n\n## Appendix\n\n### Limits & caveats\n\n- The Esc chords exist only through a Karabiner config. On a machine without it, none of them fire; herdr's portable bindings (splits on `cmd+d`, pane focus on `cmd+alt+arrows`, a tmux-style `ctrl+b` leader) work everywhere.\n- The live config's chords call `herdr-escape`, the presenter's personal 1,200-line Bun script with 12 verbs. The `herdr-chords` file above is a minimal 3-verb stand-in written for this page; its cwd lookup and search pipeline were tested piecewise on the live server, but it is not battle-tested.\n- The keeper writes into other panes: it answers prompts and reruns commands. Pointed at real work, a wrong guess becomes a wrong keystroke in a live session. Rehearse on a sacrificial workspace; give a production keeper an allowlist of panes it may touch.\n- Herdr is fast-moving pre-1.0 software (0.7.3, protocol 16, version-specific snapshot). Re-run `herdr --help` and the subcommand helps before trusting any flag quoted here.\n- The swarm capture proves the swarm's shape at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened.\n- The `pane run` bug anecdote comes from local conversation-search excerpts, not a replayable transcript. It supports \"this happened that day,\" nothing stronger.\n- Pane-search opens a temporary pane (`type = \"pane\"`) that disappears after selection — by design, not a crash.\n\n## Operating practice\n\n### Keep wrappers thin and work visible\n\n#### What to notice\n\nRemove flag memorization while keeping the **real command**, task state, logs, and **verification** inspectable.\n\n#### Try this\n\nCreate three visible responsibilities: execution, **verification**, and logs or status.\n\n> “Kind of forget the flags, especially if you're someone jumping back and forth between the different harnesses.”\n\nJohn Lindquist · [01:23:01](https://proud-anchor-53zn.here.now/watch.html?t=4981#recording-player)\n\n#### Concept\n\nA wrapper earns its place when it prevents a repeated mistake and remains easy to trace. More panes do not create understanding. Add a surface only when it represents an independently observable responsibility.\n\n#### Reflection\n\nThe presenter’s terminal stack is an example. The reusable practice is consistent launch behavior and visible state.\n\n**Recording evidence:** listen at 01:21:23.\n\n> “The beauty of owning your own tools is you can have them test themselves, and write themselves, and tackle themselves.”\n\nJohn Lindquist · [01:37:37](https://proud-anchor-53zn.here.now/watch.html?t=5857#recording-player)\n\n[Open Custom zsh Functions](https://sacred-ritual-w7as.here.now/)[Open Pi, Herdr, and Ghostty](https://summit-inlet-kxyf.here.now/)\n\n#### Links shared for this topic\n\n- [Herdr](https://herdr.dev) — A workspace surface for seeing parallel agent activity.\n- [Linear](https://linear.app/) — Issue and project tracking referenced during workflow discussion.\n- [Claudex](https://github.com/johnlindquist/claudex) — A proxy and launcher experiment for coding-agent sessions.\n- [Cloudflare AI code review](https://blog.cloudflare.com/ai-code-review/) — A published account of AI-assisted review at production scale.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=4883#q1-launcher-workspaces)"
    },
    {
      "id": "factory-visible-workspaces-discussion",
      "slug": "visible-workspaces-discussion",
      "title": "Visible workspaces for agents and swarms — discussion and evidence",
      "summary": "Detailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.",
      "category": "Team practice",
      "tags": [
        "visible-workspaces",
        "discussion",
        "evidence"
      ],
      "sources": [
        {
          "label": "Published evidence reference",
          "url": "https://proud-anchor-53zn.here.now/resource-manifest.json"
        },
        {
          "label": "Recorded discussion",
          "url": "https://proud-anchor-53zn.here.now/watch.html"
        }
      ],
      "sourceUnits": [
        "resource-manifest.json#videoEvidence.concepts[49]",
        "resource-manifest.json#videoEvidence.concepts[50]",
        "resource-manifest.json#videoEvidence.concepts[51]",
        "resource-manifest.json#videoEvidence.concepts[52]",
        "resource-manifest.json#videoEvidence.concepts[53]",
        "resource-manifest.json#videoEvidence.concepts[54]",
        "resource-manifest.json#videoEvidence.concepts[55]",
        "resource-manifest.json#videoEvidence.concepts[56]",
        "resource-manifest.json#videoEvidence.concepts[57]",
        "resource-manifest.json#videoEvidence.concepts[58]",
        "resource-manifest.json#videoEvidence.concepts[59]",
        "resource-manifest.json#videoEvidence.concepts[60]",
        "resource-manifest.json#videoEvidence.concepts[61]",
        "resource-manifest.json#videoEvidence.concepts[62]",
        "resource-manifest.json#videoEvidence.concepts[63]",
        "resource-manifest.json#videoEvidence.concepts[64]",
        "resource-manifest.json#videoEvidence.concepts[65]",
        "resource-manifest.json#videoEvidence.concepts[66]",
        "resource-manifest.json#videoEvidence.concepts[67]",
        "resource-manifest.json#videoEvidence.concepts[68]",
        "resource-manifest.json#videoEvidence.concepts[69]",
        "resource-manifest.json#videoEvidence.concepts[70]",
        "resource-manifest.json#videoEvidence.concepts[71]",
        "resource-manifest.json#videoEvidence.concepts[72]",
        "resource-manifest.json#videoEvidence.concepts[73]",
        "resource-manifest.json#videoEvidence.concepts[74]",
        "resource-manifest.json#videoEvidence.concepts[75]",
        "resource-manifest.json#videoEvidence.concepts[76]",
        "resource-manifest.json#videoEvidence.concepts[77]",
        "resource-manifest.json#videoEvidence.concepts[78]",
        "resource-manifest.json#videoEvidence.concepts[79]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[19]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[20]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[21]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[22]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[23]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[24]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[25]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[26]",
        "resource-manifest.json#videoEvidence.questionsAndAnswers[27]",
        "resource-manifest.json#videoEvidence.exercises[3]",
        "resource-manifest.json#videoEvidence.exercises[4]",
        "resource-manifest.json#videoEvidence.exercises[5]",
        "resource-manifest.json#videoEvidence.exercises[6]",
        "resource-manifest.json#videoEvidence.exercises[7]",
        "resource-manifest.json#videoEvidence.timeline[269]",
        "resource-manifest.json#videoEvidence.timeline[271]",
        "resource-manifest.json#videoEvidence.timeline[274]",
        "resource-manifest.json#videoEvidence.timeline[275]",
        "resource-manifest.json#videoEvidence.timeline[276]",
        "resource-manifest.json#videoEvidence.timeline[277]",
        "resource-manifest.json#videoEvidence.timeline[278]",
        "resource-manifest.json#videoEvidence.timeline[279]",
        "resource-manifest.json#videoEvidence.timeline[280]",
        "resource-manifest.json#videoEvidence.timeline[281]",
        "resource-manifest.json#videoEvidence.timeline[282]",
        "resource-manifest.json#videoEvidence.timeline[283]",
        "resource-manifest.json#videoEvidence.timeline[284]",
        "resource-manifest.json#videoEvidence.timeline[285]",
        "resource-manifest.json#videoEvidence.timeline[286]",
        "resource-manifest.json#videoEvidence.timeline[288]",
        "resource-manifest.json#videoEvidence.timeline[289]",
        "resource-manifest.json#videoEvidence.timeline[291]",
        "resource-manifest.json#videoEvidence.timeline[293]",
        "resource-manifest.json#videoEvidence.timeline[294]",
        "resource-manifest.json#videoEvidence.timeline[295]",
        "resource-manifest.json#videoEvidence.timeline[298]",
        "resource-manifest.json#videoEvidence.timeline[299]",
        "resource-manifest.json#videoEvidence.timeline[300]",
        "resource-manifest.json#videoEvidence.timeline[302]",
        "resource-manifest.json#videoEvidence.timeline[303]",
        "resource-manifest.json#videoEvidence.timeline[304]",
        "resource-manifest.json#videoEvidence.timeline[309]",
        "resource-manifest.json#videoEvidence.timeline[310]",
        "resource-manifest.json#videoEvidence.timeline[311]",
        "resource-manifest.json#videoEvidence.timeline[312]",
        "resource-manifest.json#videoEvidence.timeline[313]",
        "resource-manifest.json#videoEvidence.timeline[314]",
        "resource-manifest.json#videoEvidence.timeline[315]",
        "resource-manifest.json#videoEvidence.timeline[316]",
        "resource-manifest.json#videoEvidence.timeline[317]",
        "resource-manifest.json#videoEvidence.timeline[318]",
        "resource-manifest.json#videoEvidence.timeline[319]",
        "resource-manifest.json#videoEvidence.timeline[320]",
        "resource-manifest.json#videoEvidence.timeline[321]",
        "resource-manifest.json#videoEvidence.timeline[322]",
        "resource-manifest.json#videoEvidence.timeline[323]",
        "resource-manifest.json#videoEvidence.timeline[330]",
        "resource-manifest.json#videoEvidence.timeline[332]",
        "resource-manifest.json#videoEvidence.timeline[333]",
        "resource-manifest.json#videoEvidence.timeline[334]",
        "resource-manifest.json#videoEvidence.timeline[335]",
        "resource-manifest.json#videoEvidence.timeline[336]",
        "resource-manifest.json#videoEvidence.timeline[337]",
        "resource-manifest.json#videoEvidence.timeline[338]",
        "resource-manifest.json#videoEvidence.timeline[339]",
        "resource-manifest.json#videoEvidence.timeline[341]",
        "resource-manifest.json#videoEvidence.timeline[342]",
        "resource-manifest.json#videoEvidence.timeline[343]",
        "resource-manifest.json#videoEvidence.timeline[344]",
        "resource-manifest.json#videoEvidence.timeline[346]",
        "resource-manifest.json#videoEvidence.timeline[347]",
        "resource-manifest.json#videoEvidence.timeline[351]",
        "resource-manifest.json#videoEvidence.timeline[352]",
        "resource-manifest.json#videoEvidence.timeline[359]",
        "resource-manifest.json#videoEvidence.timeline[360]",
        "resource-manifest.json#videoEvidence.timeline[363]",
        "resource-manifest.json#videoEvidence.timeline[366]",
        "resource-manifest.json#videoEvidence.timeline[367]",
        "resource-manifest.json#videoEvidence.timeline[368]",
        "resource-manifest.json#videoEvidence.timeline[369]",
        "resource-manifest.json#videoEvidence.timeline[370]",
        "resource-manifest.json#videoEvidence.timeline[371]",
        "resource-manifest.json#videoEvidence.timeline[372]",
        "resource-manifest.json#videoEvidence.timeline[373]",
        "resource-manifest.json#videoEvidence.timeline[374]",
        "resource-manifest.json#videoEvidence.timeline[376]",
        "resource-manifest.json#videoEvidence.uncertainties[16]",
        "resource-manifest.json#videoEvidence.uncertainties[17]",
        "resource-manifest.json#videoEvidence.uncertainties[18]",
        "resource-manifest.json#videoEvidence.uncertainties[19]",
        "resource-manifest.json#videoEvidence.uncertainties[20]",
        "resource-manifest.json#videoEvidence.uncertainties[21]",
        "resource-manifest.json#videoEvidence.uncertainties[22]",
        "resource-manifest.json#videoEvidence.uncertainties[24]",
        "resource-manifest.json#videoEvidence.uncertainties[25]",
        "resource-manifest.json#videoEvidence.uncertainties[26]",
        "resource-manifest.json#videoEvidence.demos[23]",
        "resource-manifest.json#videoEvidence.demos[24]",
        "resource-manifest.json#videoEvidence.demos[25]",
        "resource-manifest.json#videoEvidence.demos[26]",
        "resource-manifest.json#videoEvidence.demos[27]",
        "resource-manifest.json#videoEvidence.demos[28]",
        "resource-manifest.json#videoEvidence.demos[29]",
        "resource-manifest.json#videoEvidence.demos[30]",
        "resource-manifest.json#videoEvidence.demos[31]",
        "resource-manifest.json#videoEvidence.demos[32]",
        "resource-manifest.json#videoEvidence.demos[33]",
        "resource-manifest.json#videoEvidence.demos[34]",
        "resource-manifest.json#videoEvidence.demos[35]",
        "resource-manifest.json#videoEvidence.demos[36]",
        "resource-manifest.json#videoEvidence.demos[37]",
        "resource-manifest.json#videoEvidence.demos[38]",
        "resource-manifest.json#videoEvidence.demos[39]",
        "resource-manifest.json#videoEvidence.demos[40]",
        "resource-manifest.json#videoEvidence.demos[41]",
        "resource-manifest.json#videoEvidence.demos[42]",
        "resource-manifest.json#videoEvidence.demos[43]",
        "resource-manifest.json#videoEvidence.demos[44]"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 4194,
      "url": "/topics/factory-visible-workspaces-discussion/",
      "markdownUrl": "/markdown/factory-visible-workspaces-discussion.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces-discussion.json",
      "headings": [
        {
          "id": "concepts-and-distinctions",
          "text": "Concepts and distinctions",
          "level": 2
        },
        {
          "id": "custom-zsh-functions-for-agent-clis",
          "text": "Custom zsh functions for Agent CLIs",
          "level": 3
        },
        {
          "id": "funcwhere",
          "text": "funcwhere",
          "level": 3
        },
        {
          "id": "isolated-assistant-home-directories-codex-home",
          "text": "Isolated Assistant Home Directories (CODEX_HOME)",
          "level": 3
        },
        {
          "id": "skill-symlinking",
          "text": "Skill Symlinking",
          "level": 3
        },
        {
          "id": "cli-proxy-api-middleware",
          "text": "CLI Proxy API Middleware",
          "level": 3
        },
        {
          "id": "terminal-pane-management",
          "text": "Terminal Pane Management",
          "level": 3
        },
        {
          "id": "modular-shell-configuration",
          "text": "Modular Shell Configuration",
          "level": 3
        },
        {
          "id": "shell-startup-benchmarking",
          "text": "Shell Startup Benchmarking",
          "level": 3
        },
        {
          "id": "herder",
          "text": "Herder",
          "level": 3
        },
        {
          "id": "cmux",
          "text": "CMUX",
          "level": 3
        },
        {
          "id": "ide",
          "text": "IDE",
          "level": 3
        },
        {
          "id": "natural-language-development-agentic-engineering",
          "text": "Natural Language Development / Agentic Engineering",
          "level": 3
        },
        {
          "id": "agentic-code-review",
          "text": "Agentic Code Review",
          "level": 3
        },
        {
          "id": "stricter-compiled-typings-for-agents",
          "text": "Stricter Compiled Typings for Agents",
          "level": 3
        },
        {
          "id": "agent-optimized-web-languages",
          "text": "Agent-Optimized Web Languages",
          "level": 3
        },
        {
          "id": "bespoke-rust-tuis",
          "text": "Bespoke Rust TUIs",
          "level": 3
        },
        {
          "id": "macro-driven-workspace-focus",
          "text": "Macro-Driven Workspace Focus",
          "level": 3
        },
        {
          "id": "automated-repository-sharding-skills",
          "text": "Automated Repository Sharding Skills",
          "level": 3
        },
        {
          "id": "sandboxed-agent-evaluation",
          "text": "Sandboxed Agent Evaluation",
          "level": 3
        },
        {
          "id": "budget-conscious-agent-architecture",
          "text": "Budget-Conscious Agent Architecture",
          "level": 3
        },
        {
          "id": "programmatic-post-generation-evals",
          "text": "Programmatic Post-Generation Evals",
          "level": 3
        },
        {
          "id": "swarm-code-review",
          "text": "Swarm Code Review",
          "level": 3
        },
        {
          "id": "iterative-fixer-loops",
          "text": "Iterative Fixer Loops",
          "level": 3
        },
        {
          "id": "smoke-and-integration-tests",
          "text": "Smoke and Integration Tests",
          "level": 3
        },
        {
          "id": "agent-session-scripting",
          "text": "Agent Session Scripting",
          "level": 3
        },
        {
          "id": "chaos-monkey-testing-agent",
          "text": "Chaos Monkey Testing Agent",
          "level": 3
        },
        {
          "id": "image-diffing-iteration-loop",
          "text": "Image Diffing Iteration Loop",
          "level": 3
        },
        {
          "id": "file-age-policy-guardrail",
          "text": "File Age Policy Guardrail",
          "level": 3
        },
        {
          "id": "project-workspace-directory-trust",
          "text": "Project Workspace Directory Trust",
          "level": 3
        },
        {
          "id": "shell-tool-decoration",
          "text": "Shell Tool Decoration",
          "level": 3
        },
        {
          "id": "file-age-protection-guardrails",
          "text": "File Age Protection Guardrails",
          "level": 3
        },
        {
          "id": "questions-and-answer-status",
          "text": "Questions and answer status",
          "level": 2
        },
        {
          "id": "have-you-played-around-with-completely-dropping-local-setups-like-ghostly-s-ide-integrated-terminal-and-cli-ui-and-a-visible-git-tracking-to-develop-entirely-inside-these-high-profile-external-harnesses",
          "text": "Have you played around with completely dropping local setups like Ghostly's IDE, integrated terminal, and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses?",
          "level": 3
        },
        {
          "id": "do-you-have-your-dotfiles-published-anywhere-i-d-love-to-take-a-look-at-them-if-they-are-publicly-available",
          "text": "Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.",
          "level": 3
        },
        {
          "id": "do-you-have-your-dotfiles-published-anywhere-i-d-love-to-take-a-look-at-them-if-they-are-publicly-available-2",
          "text": "Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.",
          "level": 3
        },
        {
          "id": "cmux-herdr-is-like-hyper-ide",
          "text": "Cmux / herdr is like Hyper IDE?",
          "level": 3
        },
        {
          "id": "how-do-you-review-the-code-in-the-terminal-uis",
          "text": "How do you review the code in the terminal UIs?",
          "level": 3
        },
        {
          "id": "is-there-a-simple-git-or-something-that-is-the-best-git-terminal-ui-in-the-world",
          "text": "Is there a simple Git or something that is the best Git terminal UI in the world?",
          "level": 3
        },
        {
          "id": "do-you-use-evals-when-creating-a-skill-or-agent",
          "text": "do you use evals when creating a skill or agent?",
          "level": 3
        },
        {
          "id": "a-participant-provides-a-summary-of-cloudflare-s-swarm-architecture-for-code-review-security-a11y-testing-sub-agents",
          "text": "a participant provides a summary of Cloudflare's swarm architecture for code review (security, a11y, testing sub-agents).",
          "level": 3
        },
        {
          "id": "how-close-do-you-think-fable-got-to-that-screenshot",
          "text": "How close do you think Fable got to that screenshot?",
          "level": 3
        },
        {
          "id": "exercises",
          "text": "Exercises",
          "level": 2
        },
        {
          "id": "observed-actions-and-statements",
          "text": "Observed actions and statements",
          "level": 2
        },
        {
          "id": "unresolved-exact-pipe-extensions-configured-inside-the-internal-implementation-of-the-custom-funcwhere-method",
          "text": "Unresolved: Exact pipe extensions configured inside the internal implementation of the custom funcwhere method.",
          "level": 3
        },
        {
          "id": "unresolved-the-explicit-terminal-alias-used-to-trigger-full-color-detailed-directory-listings-during-home-directory-checking",
          "text": "Unresolved: The explicit terminal alias used to trigger full color detailed directory listings during home directory checking.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-shell-command-used-to-invoke-the-directory-viewer-for-the-conf-d-files",
          "text": "Unresolved: The exact shell command used to invoke the directory viewer for the conf.d files.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-application-driving-the-embedded-terminal-text-editing-engine-interface-layout",
          "text": "Unresolved: The exact application driving the embedded terminal text editing engine interface layout.",
          "level": 3
        },
        {
          "id": "unresolved-herder",
          "text": "Unresolved: Herder",
          "level": 3
        },
        {
          "id": "unresolved-exact-underlying-terminal-binary-backing-the-prompt-builder-overlay",
          "text": "Unresolved: Exact underlying terminal binary backing the prompt builder overlay.",
          "level": 3
        },
        {
          "id": "unresolved-specific-architecture-specifications-and-installation-links-for-the-speaker-s-herder-tool-project",
          "text": "Unresolved: Specific architecture specifications and installation links for the speaker's Herder tool project.",
          "level": 3
        },
        {
          "id": "unresolved-the-exact-version-designator-configuration-layout-details-at-the-lower-margin-of-the-active-terminal-window",
          "text": "Unresolved: The exact version designator configuration layout details at the lower margin of the active terminal window.",
          "level": 3
        },
        {
          "id": "unresolved-the-accurate-tool-branding-classification-of-the-left-sidebar-agent-orchestration-app-client",
          "text": "Unresolved: The accurate tool branding classification of the left sidebar agent orchestration app client.",
          "level": 3
        },
        {
          "id": "unresolved-exact-target-length-evaluations-inside-the-shell-loop-script",
          "text": "Unresolved: Exact target length evaluations inside the shell loop script.",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-22-16",
          "text": "Demonstration detail: 01:22:16",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-25-00",
          "text": "Demonstration detail: 01:25:00",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-25-29",
          "text": "Demonstration detail: 01:25:29",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-27-03",
          "text": "Demonstration detail: 01:27:03",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-28-43",
          "text": "Demonstration detail: 01:28:43",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-29-58",
          "text": "Demonstration detail: 01:29:58",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-30-19",
          "text": "Demonstration detail: 01:30:19",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-32-20",
          "text": "Demonstration detail: 01:32:20",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-35-59",
          "text": "Demonstration detail: 01:35:59",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-41-11",
          "text": "Demonstration detail: 01:41:11",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-43-24",
          "text": "Demonstration detail: 01:43:24",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-44-50",
          "text": "Demonstration detail: 01:44:50",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-46-51",
          "text": "Demonstration detail: 01:46:51",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-49-12",
          "text": "Demonstration detail: 01:49:12",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-50-31",
          "text": "Demonstration detail: 01:50:31",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-53-34",
          "text": "Demonstration detail: 01:53:34",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-54-16",
          "text": "Demonstration detail: 01:54:16",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-54-30",
          "text": "Demonstration detail: 01:54:30",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-56-34",
          "text": "Demonstration detail: 01:56:34",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-57-51",
          "text": "Demonstration detail: 01:57:51",
          "level": 3
        },
        {
          "id": "demonstration-detail-01-59-13",
          "text": "Demonstration detail: 01:59:13",
          "level": 3
        },
        {
          "id": "demonstration-detail-02-00-50",
          "text": "Demonstration detail: 02:00:50",
          "level": 3
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms — discussion and evidence\n\nDetailed companion accounts of concepts, questions, demonstrations, exercises, and unresolved observations.\n\nThese are the companion’s accounts of the recorded discussion. Model capabilities, subscription rules, prices, version-specific flags, and predictions are contextual claims, not current guidance. An observed action is not proof that the attempted result succeeded. Distinct answers and uncertainties remain separate.\n\n## Concepts and distinctions\n\n### Custom zsh functions for Agent CLIs\n\nCreating two-letter wrappers or alias-style functions to manage flags across various agent tools (e.g., Codex, Claude Code, Pi) seamlessly without having to remember distinct syntax like --resume vs resume.\n\n### funcwhere\n\nA custom shell function created by John Lindquist that locates the precise file and line number where a specified zsh function is defined.\n\n### Isolated Assistant Home Directories (CODEX_HOME)\n\nBy isolating home directory pathways for AI client packages, engineers can prevent state corruption, parallelize multiple enterprise subscriptions, and prevent agent environment inheritance.\n\n### Skill Symlinking\n\nCreating symbolic links between a primary AI config folder and a custom secondary agent folder allows tools to utilize the same skills list while keeping runtime databases separated.\n\n### CLI Proxy API Middleware\n\nA local middleware bridge used to run Codex account tokens within the engine architecture of Claude Code clients.\n\n### Terminal Pane Management\n\nUsing fast keyboard shortcuts within a terminal emulator (like Ghostty) to split screens, organize tasks, and navigate fluidly.\n\n### Modular Shell Configuration\n\nStructuring ZSH or Bash profile setups using a conf.d model where settings are broken down into small, numbered files for easier maintenance and composition.\n\n### Shell Startup Benchmarking\n\nUsing large language models to analyze shell profile files and eliminate blockers (like synchronous NVM evaluation) that introduce startup lag.\n\n### Herder\n\nA high-performance command-line workspace and multi-agent dashboard designed to efficiently manage interactive panes.\n\n### CMUX\n\nA complex terminal layout driver wrapped as a Swift utility that manages multi-session shell instructions but exhibits performance friction.\n\n### IDE\n\nIntegrated Development Environment; an all-in-one software ecosystem featuring built-in code analysis trees, direct file graph navigation, and deep refactoring architectures.\n\n### Natural Language Development / Agentic Engineering\n\nDeveloping software primarily via conversational prompts to AI agents rather than through manual coding and file navigation within standard IDEs.\n\n### Agentic Code Review\n\nUtilizing AI agents to generate summaries and reports of changes while relying on automated validation tools (linters, tests, hooks) to confirm quality.\n\n### Stricter Compiled Typings for Agents\n\nThe approach of using strictly typed languages (like Rust or Kotlin) because strict compilation acts as an ultimate quality gate for agent-generated code.\n\n### Agent-Optimized Web Languages\n\nLanguages designed from scratch to prioritize fast agent code compilation and checks rather than human ergonomics.\n\n### Bespoke Rust TUIs\n\nHigh performance terminal overlays built to execute instantly for handling prompt configurations and tool workflows.\n\n### Macro-Driven Workspace Focus\n\nThe method of pairing keyboard layout layers (Karabiner) with window arrangement managers (Herder) to immediately target individual split terminals and project pathways using single-chorded hotkeys.\n\n### Automated Repository Sharding Skills\n\nWrapping specialized prompts into reusable console directives (such as /skill:here-now) that dispatch independent, parallelized sub-agents to independently parse git statistics, files, and branch states.\n\n### Sandboxed Agent Evaluation\n\nTesting the operational efficiency and accuracy of multi-turn autonomous coding tools within ephemeral, isolated test runners to observe total execution loops, API permission handling, and successful build handoffs.\n\n### Budget-Conscious Agent Architecture\n\nDesigning multi-agent workflows with cost-gates and low-tier model integration to prevent prohibitive API usage on personal developer accounts.\n\n### Programmatic Post-Generation Evals\n\nApplying automated validation scripts following LLM code generation to ensure structural and behavioral alignment with specific traits.\n\n### Swarm Code Review\n\nAn orchestration methodology where multiple independent, specialized sub-agents review source code simultaneously from disparate viewpoints (e.g., security, compliance, accessibility).\n\n### Iterative Fixer Loops\n\nA software repair pattern where specialized sub-agents discover findings and an autonomous fixer agent corrects them repeatedly until zero issues remain.\n\n### Smoke and Integration Tests\n\nVerification buckets intended to confirm that updated deployment code functions safely without breaking visual layouts or core operational features.\n\n### Agent Session Scripting\n\nAn automation pattern where a primary AI agent conducts user actions on a deployment, and a secondary agent reviews the execution timeline to export it as a programmatic test script.\n\n### Chaos Monkey Testing Agent\n\nA testing setup where an AI agent is instructed to execute erratic and rapid keystrokes or interface inputs to purposefully try and break software components.\n\n### Image Diffing Iteration Loop\n\nAn agentic loop approach where the model takes automated snapshots of a rendered webpage layout, runs a visual diff against the original mockup image, and continuously updates the code until pixel-perfect alignment is reached.\n\n### File Age Policy Guardrail\n\nA runtime file safety constraint injected into an agent workspace context that establishes a timeline cutoff based on file modification times, preventing the agent from modifying, renaming, or deleting older legacy codebase files.\n\n### Project Workspace Directory Trust\n\nA security framework boundary that prompts the user to explicitly trust local file systems before allowing agent extensions or custom shell execution hooks to activate within that context.\n\n### Shell Tool Decoration\n\nThe technique of overriding default terminal applications or functions within a shell session to overlay custom analytical or defensive actions transparently.\n\n### File Age Protection Guardrails\n\nAutomated system restrictions that analyze file metadata to block or hesitate before letting autonomous agents modify code older than a configured age threshold.\n\n## Questions and answer status\n\n### Have you played around with completely dropping local setups like Ghostly's IDE, integrated terminal, and cli ui, and a visible Git tracking to develop entirely inside these high-profile external harnesses?\n\n**Status: answered.** John states he keeps external apps open only to keep remote tracking hooks running but builds and develops entirely inside his local terminal because it grants maximum power to rapidly search, spawn, and program custom behaviors.\n\n### Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.\n\n**Status: unanswered.** The question is shown in chat but is not directly explicitly answered or addressed by John during the duration of this specific video segment.\n\n### Do you have your dotfiles published anywhere? I'd love to take a look at them if they are publicly available.\n\n**Status: partial.** John shows that his public GitHub dotfiles repository is obsolete, shows his local structured setup instead, and mentions he wants to review it before publishing it properly.\n\n### Cmux / herdr is like Hyper IDE?\n\n**Status: answered.** John outlines that traditional IDE definitions apply to graphical suites (Zed, VS Code, IntelliJ) embedded with file-system inspectors and refactoring engines, which diverges from terminal-focused script orchestration shells.\n\n### How do you review the code in the terminal UIs?\n\n**Status: answered.** John delegates the task of code analysis to AI agents, asking them to summarize changes and write reports. He checks automated tests, smoke tests, and scenario suites rather than conducting deep manual line-by-line inspections.\n\n### Is there a simple Git or something that is the best Git terminal UI in the world?\n\n**Status: answered.** The optimal approach is delegating to an agent to formulate and construct a highly individualized Rust terminal utility matching your direct workflow constraints.\n\n### do you use evals when creating a skill or agent?\n\n**Status: partial.** John notes he is progressively incorporating automated scripted evaluations into his personal tooling stack. He highlights his experience at Vercel engineering integration infrastructure for terminal agents, where he orchestrated comprehensive evaluation sandboxes measuring prompt turn-efficiency and deployment success metrics across complex boilerplate projects.\n\n### a participant provides a summary of Cloudflare's swarm architecture for code review (security, a11y, testing sub-agents).\n\n**Status: answered.** John opens the blog post directly, validates the concepts, and expands on how low model prices now enable developers to throw multiple capable models into code review swarms affordably.\n\n### How close do you think Fable got to that screenshot?\n\n**Status: answered.** John answers that it performed very well for just a few minutes of generation work, noting the hand-drawn elements, tabs, and layout structures look excellent despite slight physical alignment quirks on the decorative notebook hole punches.\n\n## Exercises\n\n- **Try:** Isolate an active AI workspace environment locally by configuring independent variables for multiple assistant accounts, verifying separated session databases.\n  **Basis:** 01:25:46.350\n\n- **Try:** Use an LLM model to analyze, optimize, and benchmark your personal bash/zsh startup setup to eliminate high latency hooks like NVM script initialization.\n  **Basis:** John mentions this at 01:30:45 as an effective workflow optimization strategy.\n\n- **Try:** Configure an automated code repository auditing command or skill locally that runs parallel evaluations using git logs and diff metrics.\n  **Basis:** Demonstrated by John Lindquist when initializing the /skill:here-now prompt at 01:45:00.\n\n- **Try:** Students are directed to build a Chaos Monkey prompt variant for their agents to stress-test custom site deployments with erratic behavior over the weekend.\n  **Basis:** John mentions: 'try that this weekend sometime. Click on everything way too fast, type in way too much... trying to make it break and find where it breaks. That's a really fun prompt.'\n\n- **Try:** Configure a repository safety script that checks individual file mtime dates, calculates a 7-day cutoff boundary, and warns an autonomous agent workflow whenever a targeted workspace resource violates modification safety thresholds.\n  **Basis:** Demonstrated at 01:57:00.000 where the shell agent intercepts the ls query to append a structured FILE AGE POLICY block.\n\n## Observed actions and statements\n\nThese timestamped observations retain troubleshooting detail and the limits of what was visible. Commands mentioned here are observations, not vetted installation instructions; use the topic’s prepared recipes for runnable examples.\n\n- [01:21:23](https://proud-anchor-53zn.here.now/watch.html?t=4883#recording-player) — John Lindquist notes that Linear is highly agentic ready with its CLI.\n\n- [01:21:57](https://proud-anchor-53zn.here.now/watch.html?t=4917#recording-player) — a participant describes Linear as Jira for AI-Native Teams.\n\n- [01:22:18](https://proud-anchor-53zn.here.now/watch.html?t=4938#recording-player) — The presenter types and executes the directory initialisation macro 'take ~/dev/custom-zsh-functions'.\n\n- [01:22:32](https://proud-anchor-53zn.here.now/watch.html?t=4952#recording-player) — The presenter executes the 'x' function shortcut, initiating OpenAI Codex CLI.\n\n- [01:22:39](https://proud-anchor-53zn.here.now/watch.html?t=4959#recording-player) — The presenter exits Codex and tests the 'xr' command wrapper to open the session resumer tool.\n\n- [01:22:51](https://proud-anchor-53zn.here.now/watch.html?t=4971#recording-player) — The presenter calls the 'clx' function to invoke the Claude Code runtime agent interface.\n\n- [01:23:09](https://proud-anchor-53zn.here.now/watch.html?t=4989#recording-player) — The presenter tests mock inputs for various resume styles into the shell line buffer.\n\n- [01:23:34](https://proud-anchor-53zn.here.now/watch.html?t=5014#recording-player) — The presenter triggers 'which x' to inspect the structure of the active shell configuration function wrapper.\n\n- [01:23:52](https://proud-anchor-53zn.here.now/watch.html?t=5032#recording-player) — The presenter triggers 'which clx' to check flag formatting logic for Claude Code.\n\n- [01:24:16](https://proud-anchor-53zn.here.now/watch.html?t=5056#recording-player) — The presenter tests 'funcwhere x' to trace the target path locations of local Zsh tools.\n\n- [01:24:27](https://proud-anchor-53zn.here.now/watch.html?t=5067#recording-player) — The presenter inspects the internal text layout of 'funcwhere' using the standard shell built-in command.\n\n- [01:24:43](https://proud-anchor-53zn.here.now/watch.html?t=5083#recording-player) — The presenter writes the combined terminal macro string 'zed \"(funcwhere x)\"' into the input row.\n\n- [01:25:02](https://proud-anchor-53zn.here.now/watch.html?t=5102#recording-player) — John points out different definitions for resume, resume with a specific conversation, and resume the last conversation.\n\n- [01:25:34](https://proud-anchor-53zn.here.now/watch.html?t=5134#recording-player) — John types a custom zsh command into Ghostly window to inspect function configurations for x2.\n\n- [01:25:46](https://proud-anchor-53zn.here.now/watch.html?t=5146#recording-player) — John explains that having two parallel Codex subscriptions involves running them with custom home directories.\n\n- [01:27:13](https://proud-anchor-53zn.here.now/watch.html?t=5233#recording-player) — John Lindquist drops the URL https://github.com/johnlindquist/claudex into the workshop chat room.\n\n- [01:27:24](https://proud-anchor-53zn.here.now/watch.html?t=5244#recording-player) — John explains that Claudex lets you run Codex inside Claude Code via a CLI proxy API.\n\n- [01:28:43](https://proud-anchor-53zn.here.now/watch.html?t=5323#recording-player) — John Lindquist mentions having a shortcut to spawn another tab or pane open to the side.\n\n- [01:29:39](https://proud-anchor-53zn.here.now/watch.html?t=5379#recording-player) — John addresses a question about whether his dotfiles are published anywhere.\n\n- [01:29:58](https://proud-anchor-53zn.here.now/watch.html?t=5398#recording-player) — John switches to Google Chrome and enters the URL github.com/johnlindquist/dotfiles.\n\n- [01:30:08](https://proud-anchor-53zn.here.now/watch.html?t=5408#recording-player) — The browser shows an old repository named dotfiles containing Karabiner config files from 4 years ago.\n\n- [01:30:45](https://proud-anchor-53zn.here.now/watch.html?t=5445#recording-player) — John suggests prompting AI models to benchmark and optimize ZSH profile configurations for maximum startup speed.\n\n- [01:31:00](https://proud-anchor-53zn.here.now/watch.html?t=5460#recording-player) — John displays a list of numbered configuration files ranging from 00-path.zsh to 65-ai-agent-shortcuts.zsh.\n\n- [01:32:10](https://proud-anchor-53zn.here.now/watch.html?t=5530#recording-player) — John states he wants to review his configuration files before publishing them publicly.\n\n- [01:32:20](https://proud-anchor-53zn.here.now/watch.html?t=5540#recording-player) — John inputs herdr --help into the active command prompt terminal.\n\n- [01:32:39](https://proud-anchor-53zn.here.now/watch.html?t=5559#recording-player) — John types the cmux command, generating an extensive terminal layout control output list.\n\n- [01:33:28](https://proud-anchor-53zn.here.now/watch.html?t=5608#recording-player) — The terminal window displays an automated Claude agent update diff for index.html.\n\n- [01:35:24](https://proud-anchor-53zn.here.now/watch.html?t=5724#recording-player) — a participant comments that John is utilizing Zed instead of ghostly features directly.\n\n- [01:35:59](https://proud-anchor-53zn.here.now/watch.html?t=5759#recording-player) — Terminal workspace shows the file 40-alias.zsh with active terminal configuration aliases list and workspace file sidebar.\n\n- [01:35:59](https://proud-anchor-53zn.here.now/watch.html?t=5759#recording-player) — John Lindquist discusses how integrated environments are being overtaken by natural language development, vibe coding, and agentic engineering.\n\n- [01:36:28](https://proud-anchor-53zn.here.now/watch.html?t=5788#recording-player) — The workspace editor switches files to show the content of pi-lens.md containing file age policies and verification rules.\n\n- [01:36:38](https://proud-anchor-53zn.here.now/watch.html?t=5798#recording-player) — a participant sends a chat message: 'How do you review the code in the terminal UIs?'\n\n- [01:36:42](https://proud-anchor-53zn.here.now/watch.html?t=5802#recording-player) — John points out that tools like TMUX have been around forever, but agentic tools make hacking custom plugins on Herder much faster.\n\n- [01:37:10](https://proud-anchor-53zn.here.now/watch.html?t=5830#recording-player) — John compares agentic pane generation with traditional extension testing workflows inside IDEs like VS Code.\n\n- [01:37:34](https://proud-anchor-53zn.here.now/watch.html?t=5854#recording-player) — a participant sends a chat message: 'There’s simple-git or something that is “the best git terminal ui in the world”'\n\n- [01:37:47](https://proud-anchor-53zn.here.now/watch.html?t=5867#recording-player) — John reads a participant's question and describes asking agents to summarize changed files and write report summaries.\n\n- [01:38:16](https://proud-anchor-53zn.here.now/watch.html?t=5896#recording-player) — John states his high trust in the AI agent Fable and notes that he uses tests, hooks, linters, and gates to verify functionality instead of manual code reviews.\n\n- [01:39:07](https://proud-anchor-53zn.here.now/watch.html?t=5947#recording-player) — John talks about the benefit of strictly typed compiled languages like Rust that enforce correctness under agentic workflows.\n\n- [01:39:18](https://proud-anchor-53zn.here.now/watch.html?t=5958#recording-player) — John expects developers to transition away from TypeScript/JavaScript to options that compile to JavaScript with stricter typing like Kotlin.\n\n- [01:39:28](https://proud-anchor-53zn.here.now/watch.html?t=5968#recording-player) — a participant sends a chat message: 'So you're essentially using AI to provide executive summaries of the code changes?'\n\n- [01:39:33](https://proud-anchor-53zn.here.now/watch.html?t=5973#recording-player) — John talks about the future emergence of a web language optimized for agents rather than humans.\n\n- [01:40:08](https://proud-anchor-53zn.here.now/watch.html?t=6008#recording-player) — John poses the question regarding finding or building the best Git terminal UI.\n\n- [01:43:15](https://proud-anchor-53zn.here.now/watch.html?t=6195#recording-player) — John discusses the development history of digital artifacts, attributing the initial framework conception to the Anthropic Claude Code team.\n\n- [01:43:39](https://proud-anchor-53zn.here.now/watch.html?t=6219#recording-player) — John explains his local keyboard configuration environment using Karabiner software keys combined with custom panel focusing parameters handled via Herder setup definitions.\n\n- [01:43:54](https://proud-anchor-53zn.here.now/watch.html?t=6234#recording-player) — Student a participant describes an automated review-loop macro that initiates paired Opus and Codex subagents to iteratively find and resolve repository bugs.\n\n- [01:44:50](https://proud-anchor-53zn.here.now/watch.html?t=6290#recording-player) — John initializes an interactive agent task loop inside the script-kit-gpui project folder workspace by entering the invocation query x pi.\n\n- [01:45:00](https://proud-anchor-53zn.here.now/watch.html?t=6300#recording-player) — John passes a long-form request to the terminal via the prompt command /skill:here-now to aggregate code change metrics, identify breaking behaviors, and flag potential visual regression risks over the past week.\n\n- [01:45:39](https://proud-anchor-53zn.here.now/watch.html?t=6339#recording-player) — John notes an automated test inquiry from the session history asking if he writes validation checkpoints or automated evaluation test suites when authoring customized agent skills.\n\n- [01:45:54](https://proud-anchor-53zn.here.now/watch.html?t=6354#recording-player) — John highlights his past engineering contributions at Vercel developing early infrastructure implementations for the platform's terminal agent automation plugin.\n\n- [01:46:08](https://proud-anchor-53zn.here.now/watch.html?t=6368#recording-player) — The terminal view displays multiple parallel sub-agents spinning up under the names Agent review committed weekly changes, Agent review dirty worktree changes, and Agent audit weekly visual risks.\n\n- [01:46:52](https://proud-anchor-53zn.here.now/watch.html?t=6412#recording-player) — John explains that while Vercel could easily absorb the costs of heavy agent evaluations, doing so on a personal budget becomes prohibitively expensive.\n\n- [01:47:24](https://proud-anchor-53zn.here.now/watch.html?t=6444#recording-player) — John details the programmatic evaluation gates built into his 'mini arcade' repository that validate traits post-game-generation.\n\n- [01:47:52](https://proud-anchor-53zn.here.now/watch.html?t=6472#recording-player) — John shares that he is building an app for home builders via a small startup, where simple AI features will solve niche problems without requiring heavy agent swarms.\n\n- [01:48:21](https://proud-anchor-53zn.here.now/watch.html?t=6501#recording-player) — John highlights how low-cost, highly capable models like Kimi or Kimi 3 can significantly enhance agentic workflows by serving as cheap evaluation layers.\n\n- [01:49:05](https://proud-anchor-53zn.here.now/watch.html?t=6545#recording-player) — John introduces the Cloudflare article regarding large-scale AI code reviews.\n\n- [01:49:34](https://proud-anchor-53zn.here.now/watch.html?t=6574#recording-player) — John discusses technical code review loops involving sub-agents (like Opus and Codex) finding errors, followed by a fixer agent resolving them iteratively.\n\n- [01:50:02](https://proud-anchor-53zn.here.now/watch.html?t=6602#recording-player) — John recalls how expensive multi-model code reviews were in previous years using models like Claude Sonnet 3.5 or older Codex variations, comparing it to today's affordable subscription models.\n\n- [01:51:40](https://proud-anchor-53zn.here.now/watch.html?t=6700#recording-player) — John talks about working at ClickUp and dealing with high blast radius UI changes.\n\n- [01:51:59](https://proud-anchor-53zn.here.now/watch.html?t=6719#recording-player) — John introduces the concept of using one agent to build paths and another to turn them into scripts.\n\n- [01:54:16](https://proud-anchor-53zn.here.now/watch.html?t=6856#recording-player) — John inputs the prompt 'serve this in my browser' into the interactive command input text entry field.\n\n- [01:54:27](https://proud-anchor-53zn.here.now/watch.html?t=6867#recording-player) — A local Python HTTP server is spawned on port 8459, opening the page in Google Chrome at http://localhost:8459.\n\n- [01:55:00](https://proud-anchor-53zn.here.now/watch.html?t=6900#recording-player) — John explains how image diffing pipelines let agents iterate on layouts until they match mockups with pixel-perfect accuracy.\n\n- [01:56:34](https://proud-anchor-53zn.here.now/watch.html?t=6994#recording-player) — John opens the pi-env-demo workspace space, displaying a modal dialog overlay prompt requesting project trust confirmation.\n\n- [01:56:42](https://proud-anchor-53zn.here.now/watch.html?t=7002#recording-player) — John selects the 'Trust (this session only)' option, allowing workspace initialization.\n\n- [01:56:47](https://proud-anchor-53zn.here.now/watch.html?t=7007#recording-player) — John writes 'List all of our files with ls' inside the workspace agent prompt panel.\n\n- [01:56:56](https://proud-anchor-53zn.here.now/watch.html?t=7016#recording-player) — The agent executes the terminal command ls -la and prints a FILE AGE POLICY layout configuration table.\n\n- [01:57:15](https://proud-anchor-53zn.here.now/watch.html?t=7035#recording-player) — John highlights the injected safety rule prohibiting modification of project files older than 7 days.\n\n- [01:57:51](https://proud-anchor-53zn.here.now/watch.html?t=7071#recording-player) — John Lindquist describes the issue of legacy project code that shouldn't be touched by automated agents without specific flags or restrictions.\n\n- [01:58:35](https://proud-anchor-53zn.here.now/watch.html?t=7115#recording-player) — The screen shows a terminal running a custom file age policy module displaying the modification metadata of files under the pi-env-demo folder.\n\n- [01:59:14](https://proud-anchor-53zn.here.now/watch.html?t=7154#recording-player) — John Lindquist explains that the logic for decorating shell functions lives inside the agent-shell configuration file.\n\n- [01:59:45](https://proud-anchor-53zn.here.now/watch.html?t=7185#recording-player) — John opens file-age-policy.mjs in the editor to detail the Node.js implementation of the policy rules.\n\n- [02:00:52](https://proud-anchor-53zn.here.now/watch.html?t=7252#recording-player) — The terminal window displays an active background agent publishing a script to a live here.now URL and verifying it with curl.\n\n### Unresolved: Exact pipe extensions configured inside the internal implementation of the custom funcwhere method.\n\nThe complete execution line wraps past the visible screen borders during standard stdout print visualization.\n\n**Discriminating evidence:** Inspect the source script contents file directly in subsequent segments or repositories.\n\n### Unresolved: The explicit terminal alias used to trigger full color detailed directory listings during home directory checking.\n\nJohn runs a command that lists the contents of the .codex-work folder with specific date-modified metrics, but the exact typed short-phrase command keying is partially off-screen or obscured.\n\n**Discriminating evidence:** Cross-reference with full dotfiles repository configuration scripts.\n\n### Unresolved: The exact shell command used to invoke the directory viewer for the conf.d files.\n\nThe command itself is entered via an abbreviation or custom key combination without explicit standard typing visible.\n\n**Discriminating evidence:** Can be inferred as a custom ls alias or tool like eza/exa based on columns shown.\n\n### Unresolved: The exact application driving the embedded terminal text editing engine interface layout.\n\nNo discrete window decoration labels are cleanly drawn on screen, despite matching text features commonly associated with Zed terminal integrations or text editors.\n\n**Discriminating evidence:** Cross-reference workshop asset profiles for terminal dashboard editor plugins.\n\n### Unresolved: Herder\n\nThe tool name is pronounced as 'Herder' but could alternatively be written as 'Herdr' or similar.\n\n**Discriminating evidence:** Left as 'Herder' matching the verbatim transcript interpretation.\n\n### Unresolved: Exact underlying terminal binary backing the prompt builder overlay.\n\nThe precise tool executable name isn't entered or explicitly read out during the fast execution toggle.\n\n**Discriminating evidence:** Verify tool definitions in subsequent workshop shards.\n\n### Unresolved: Specific architecture specifications and installation links for the speaker's Herder tool project.\n\nThe terminal management tool is highlighted textually and verbally as a component of John's window navigation setup, but its codebase repository home is not opened or inspected.\n\n**Discriminating evidence:** Examine related project files or configuration folders under the user profile summary data for additional .herder definitions.\n\n### Unresolved: The exact version designator configuration layout details at the lower margin of the active terminal window.\n\nText reading (opencode-codex) gpt-5.6-sol-w1 is relatively small and can be interpreted with alternative typographic spacing assumptions.\n\n**Discriminating evidence:** Verify with terminal logs or source configurations for the underlying pi-lens status bar layout.\n\n### Unresolved: The accurate tool branding classification of the left sidebar agent orchestration app client.\n\nThe software frame displays workspace trees, tool durations, and agent states clearly but does not highlight an explicit application title or client banner text.\n\n**Discriminating evidence:** Cross-reference with the master project architectural diagrams to determine if this dashboard interface runs as a specialized client extension of Script Kit.\n\n### Unresolved: Exact target length evaluations inside the shell loop script.\n\nThe lower sections of the function window are compact and text scaling reduces readability.\n\n**Discriminating evidence:** Cross-reference with full repository source files for agent-shell.zsh.\n\n### Demonstration detail: 01:22:16\n\n- Executed take command to open custom project environments.\n- Ran custom wrappers x, xr, and clx to prove abstraction functions across various AI platforms.\n- Demonstrated debugging commands via which and a unique custom utility named funcwhere.\n\n**Tools observed:** Ghostty, OpenAI Codex CLI, Claude Code CLI, Zed.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ntake ~/dev/custom-zsh-functions\nx\nxr\nclx\nwhich x\nwhich clx\nfuncwhere x\nwhich funcwhere\nzed \"(funcwhere x)\"\n```\n\n### Demonstration detail: 01:25:00\n\n- Reviewing specific shell script configuration declarations for Codex wrappers\n\n**Tools observed:** Zed/Editor.\n\n### Demonstration detail: 01:25:29\n\n- Querying terminal function composition definitions and scanning runtime isolated directories\n\n**Tools observed:** Ghostly Terminal.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ncustom-zsh-functions which x2\n```\n\n### Demonstration detail: 01:27:03\n\n- Opening the claudex open source repository page to analyze implementation rules\n\n**Tools observed:** Google Chrome Browser.\n\n### Demonstration detail: 01:28:43\n\n- Spawning horizontal and vertical terminal panes\n- Closing terminal sessions quickly using hotkeys\n\n**Tools observed:** Ghostty.\n\n### Demonstration detail: 01:29:58\n\n- Navigating to GitHub repository URL in web browser\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 01:30:19\n\n- Listing files in a shell configuration directory\n\n**Tools observed:** Ghostty.\n\n### Demonstration detail: 01:32:20\n\n- Executed herdr help parameters\n- Executed cmux parameters to display pane automation controls\n\n**Tools observed:** herdr, cmux, Ghostty.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nherdr --help\ncmux\n```\n\n### Demonstration detail: 01:35:59\n\n- Switched tab from 40-alias.zsh config file to view the pi-lens.md documentation file.\n\n**Tools observed:** Terminal workspace code viewer.\n\n### Demonstration detail: 01:41:11\n\n- Toggled custom TUI client framework panel.\n- Typed command strings into the terminal interactive input field.\n\n**Tools observed:** Ghostty.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\n/model\n/permissions\n```\n\n### Demonstration detail: 01:43:24\n\n- Swapping active project configurations instantly inside Ghostty panels via key combinations.\n\n**Tools observed:** Ghostty, Karabiner, Herder.\n\n### Demonstration detail: 01:44:50\n\n- Initializing the agent workflow engine and launching a parallel branch documentation query.\n\n**Tools observed:** pi, Git.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nx pi\n/skill:here-now Please look through all the code changes over the past week and write out a guide explaining all the changes, why they were made, the things I should definitely look into, and the things that might cause either breaking changes or visual chain deciding to investigate.\n```\n\n### Demonstration detail: 01:46:51\n\n- Monitoring ongoing multi-agent execution processes in the pi-lens terminal dashboard environment.\n\n**Tools observed:** Script Kit.\n\n### Demonstration detail: 01:49:12\n\n- Opening Google Chrome and scrolling down through the Cloudflare blog architecture layout.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 01:50:31\n\n- Displaying an architectural blog section detailing context isolation mechanics and opencode configurations.\n\n**Tools observed:** Chrome.\n\n### Demonstration detail: 01:53:34\n\n- Switching active view to terminal windows to inspect active script tasks and agent execution metrics.\n\n**Tools observed:** Ghostty, Script Kit, pi-lens.\n\n### Demonstration detail: 01:54:16\n\n- Submitted natural language serving command via command line entry input box.\n- Verified internal system shell activation.\n\n**Tools observed:** Ghostty, Python.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\npython3 -m http.server 8459\n```\n\n### Demonstration detail: 01:54:30\n\n- Opened artifact inside Google Chrome preview window.\n- Clicked through side navigation component tabs to verify active rendering logic.\n\n**Tools observed:** Google Chrome.\n\n### Demonstration detail: 01:56:34\n\n- Approved security modal folder permissions setup prompt.\n- Dispatched file query via interactive text command interface prompt.\n- Inspected the calculated age criteria logs in the terminal.\n\n**Tools observed:** Ghostty.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nls -la\n```\n\n### Demonstration detail: 01:57:51\n\n- Executing ls -la and displaying the custom file age reporting summary in the shell pane.\n\n**Tools observed:** zsh, node.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\nls -la\n```\n\n### Demonstration detail: 01:59:13\n\n- Navigating and reviewing agent-shell.zsh and file-age-policy.mjs inside the IDE tool.\n\n**Tools observed:** Cursor.\n\n### Demonstration detail: 02:00:50\n\n- Monitoring automated execution logs of a Git change publication script during an announcement loop.\n\n**Tools observed:** git, curl, publish.sh.\n\n**Command or prompt observations (not a verified recipe):**\n\n```text\ngit status --short\npublish.sh\n```"
    },
    {
      "id": "factory-visible-workspaces-practice",
      "slug": "visible-workspaces-practice",
      "title": "Visible workspaces for agents and swarms — prompts and exercises",
      "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for visible workspaces for agents and swarms.",
      "category": "Team practice",
      "tags": [
        "prompts",
        "exercises",
        "visible-workspaces"
      ],
      "sources": [
        {
          "label": "Visible workspaces for agents and swarms",
          "url": "https://summit-inlet-kxyf.here.now/"
        },
        {
          "label": "Public setup contract",
          "url": "https://summit-inlet-kxyf.here.now/agent.md"
        }
      ],
      "sourceUnits": [
        "06-pi-herdr-ghostty/index.html#Quick start",
        "06-pi-herdr-ghostty/index.html#Prompt library",
        "06-pi-herdr-ghostty/index.html#Set it up (agent guide)",
        "06-pi-herdr-ghostty/index.html#The keeper — keep every sibling agent alive",
        "06-pi-herdr-ghostty/index.html#Swarm decomposition — plan with your smartest model first",
        "06-pi-herdr-ghostty/index.html#Self-check — make your agent read its own screen",
        "06-pi-herdr-ghostty/agent.md"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1846,
      "url": "/topics/factory-visible-workspaces-practice/",
      "markdownUrl": "/markdown/factory-visible-workspaces-practice.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces-practice.json",
      "headings": [
        {
          "id": "quick-start",
          "text": "Quick start",
          "level": 2
        },
        {
          "id": "prompt-library",
          "text": "Prompt library",
          "level": 2
        },
        {
          "id": "the-keeper-keep-every-sibling-agent-alive",
          "text": "The keeper — keep every sibling agent alive",
          "level": 3
        },
        {
          "id": "swarm-decomposition-plan-with-your-smartest-model-first",
          "text": "Swarm decomposition — plan with your smartest model first",
          "level": 3
        },
        {
          "id": "self-check-make-your-agent-read-its-own-screen",
          "text": "Self-check — make your agent read its own screen",
          "level": 3
        },
        {
          "id": "set-it-up-agent-guide",
          "text": "Set it up (agent guide)",
          "level": 2
        },
        {
          "id": "complete-reusable-setup-contract",
          "text": "Complete reusable setup contract",
          "level": 2
        },
        {
          "id": "drive-a-herdr-session-from-your-agent-setup-guide",
          "text": "Drive a herdr session from your agent — setup guide",
          "level": 2
        },
        {
          "id": "prerequisites",
          "text": "Prerequisites",
          "level": 2
        },
        {
          "id": "steps",
          "text": "Steps",
          "level": 2
        },
        {
          "id": "success-check",
          "text": "Success check",
          "level": 2
        },
        {
          "id": "notes-for-agents",
          "text": "Notes for agents",
          "level": 2
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for visible workspaces for agents and swarms.\n\n## Quick start\n\nRead-only recon on a live herdr session. Nothing here focuses, closes, or writes to a pane — safe to run mid-talk. If an agent runs these for you under a restrictive permission mode, it may need you to approve even these read-only commands.\n\n``` text\nherdr status\nherdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, \"\\(.pane_count) panes\"] | @tsv'\nherdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\nherdr pane read \"$(herdr pane list | jq -r '.result.panes[0].pane_id')\" --lines 10\nherdr agent list\n```\n\n## Prompt library\n\n### The keeper — keep every sibling agent alive\n\n- Agent: pi (or any agent with a bash tool) inside a herdr pane\n- Working directory: any pane in the workspace you want supervised\n- Expected result: one log line per intervention, then a pane → task → outcome table\n\n``` text\nYou are the keeper of this herdr session. Other panes in this workspace are\nrunning coding agents. Your job is to keep them all moving until every task\nis done. Loop:\n\n1. `herdr agent list` — enumerate sibling agents and their states. Ignore\n   your own pane (`$HERDR_PANE_ID`).\n2. For each sibling that is `blocked` or has been `idle` while its task is\n   unfinished:\n   - `herdr agent read <target> --lines 40` to see what it last printed.\n   - If it is waiting on a confirmation prompt, answer it with\n     `herdr agent send <target> \"<the answer>\"`.\n   - If it crashed or its pane shows a shell prompt, relaunch its task with\n     `herdr pane run <pane_id> \"<original command>\"`.\n   - If it is stuck in a loop, interrupt (send Ctrl+C via\n     `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more\n     precisely.\n3. Instead of polling in a tight loop, block on\n   `herdr wait agent-status <pane_id> --status idle --timeout 600000`\n   for the pane most likely to finish next.\n4. After every intervention, log one line: pane id, what you saw, what you did.\n5. Stop when every sibling is idle AND its last output shows its task\n   completed. Then print a table: pane → task → outcome.\n\nNever close panes. Never start new work. You are a shepherd, not a worker.\n```\n\n### Swarm decomposition — plan with your smartest model first\n\n- Agent: your strongest model, thinking level maxed\n- Working directory: the project root you want to split up\n- Expected result: a table of worker briefs with a done-condition each — argue with it before spawning anything\n\n``` text\nDecompose this project into N independent tasks that can each be completed\nby an agent working alone in its own directory, with no shared files and no\nordering between them. For each task: a directory, a one-paragraph brief, a\ndefinition of done, and the exact command to verify it. If the tasks are\nnot truly independent, redesign the split until they are.\n```\n\n### Self-check — make your agent read its own screen\n\n- Agent: any agent with a bash tool, inside a herdr pane\n- Working directory: the agent's own pane\n- Expected result: the agent reports lines that match the conversation you are having with it\n\n``` text\nRun this with your bash tool:\n\nherdr pane read \"$HERDR_PANE_ID\" --lines 20\n\nThat capture is your own pane — the screen you are printing to right now.\nTell me the last three lines and confirm they match this conversation.\n```\n\n## Set it up (agent guide)\n\n1.  Check the prerequisites. `herdr status` must show a running server (this page was verified against herdr 0.7.3, protocol 16). If herdr is not installed, stop — this guide drives an existing herdr session, it does not install one.\n\n    ``` text\n    herdr status\n    jq --version\n    ```\n\n2.  Recon the session read-only (the Quick start block above), then find yourself. Herdr injects `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into every pane:\n\n    ``` text\n    echo \"${HERDR_PANE_ID:-not inside a herdr pane}\"\n    ```\n\n3.  Learn the steering verbs. These write into panes — only touch panes your user told you to. Note: `agent send` writes literal text; `pane run` sends command text plus Enter.\n\n    ``` text\n    herdr agent read <target> --lines 40\n    herdr agent send <target> \"yes, apply the migration\"\n    herdr pane run <pane_id> \"npm test\"\n    herdr pane send-keys <pane_id> ctrl-c\n    herdr wait agent-status <pane_id> --status idle --timeout 600000\n    ```\n\n4.  To supervise sibling agents, adopt the keeper prompt — printed complete in the Prompt library above and in [agent.md](https://summit-inlet-kxyf.here.now/agent.md).\n\n**Success check:** read your own pane through the socket. The capture should show the conversation you are in right now — this instruction, your own recent output.\n\n``` text\nherdr pane read \"${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}\" --lines 20\n```\n\n``` text\n… the last 20 lines of your own screen, as text.\nYou should recognize your current session in it — that is the point:\nthe same socket your keyboard uses is readable by the agent it hosts.\n```\n\n## Complete reusable setup contract\n\n## Drive a herdr session from your agent — setup guide\n\nFollowing this file sets up: your coding agent (any agent with a shell/bash tool) reading and steering the panes of a live herdr terminal session over its unix-socket CLI, including supervising other agents with the \"keeper\" prompt.\n\nPlaceholders used below: `<pane_id>` and `<target>` are ids and names you read from `herdr pane list` and `herdr agent list`. All other paths and commands are literal.\n\nCompanion pages for humans on this same site: `index.html` (the full guide), `replay.html` (Session Replay — an annotated transcript of the agent session that mapped this stack), and `dialogue.html` (Socratic Dialogue — attendee questions driving the reveal). This file stays the canonical machine copy; if your user asks how the setup was built or why, point them at those pages.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\nherdr status\njq --version\n```\n\nExpected: `herdr status` prints a client block and a server block with `status: running` (this guide was verified against herdr 0.7.3, protocol 16). If `herdr` is missing or the server is not running, stop and tell your user — this guide drives an existing herdr session; it does not install herdr.\n\n## Steps\n\n1. Recon the session. All of these are read-only and safe to run anytime (note: restrictive agent permission modes may still block even these read-only `herdr` commands — if a call is denied, ask your user to approve it rather than skipping the step):\n\n   ```bash\n   herdr status\n   herdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, \"\\(.pane_count) panes\"] | @tsv'\n   herdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\n   herdr pane read <pane_id> --lines 20\n   herdr agent list\n   ```\n\n   `agent_status` values (idle / working / blocked) are reported by the agents' own herdr integrations over the socket, not scraped from the screen. `unknown` means no integration is reporting for that pane.\n\n2. Find yourself. If you are running inside a herdr pane, herdr injected `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into your environment:\n\n   ```bash\n   echo \"${HERDR_PANE_ID:-not inside a herdr pane}\"\n   ```\n\n3. Learn the steering verbs. These WRITE into panes — only touch panes your user told you to touch. `herdr agent send` writes literal text; `herdr pane run` sends command text plus Enter.\n\n   ```bash\n   herdr agent read <target> --lines 40                              # what a sibling last printed\n   herdr agent send <target> \"yes, apply the migration\"              # answer a stuck confirmation prompt\n   herdr pane run <pane_id> \"npm test\"                               # run a command in a pane\n   herdr pane send-keys <pane_id> ctrl-c                             # interrupt a stuck process\n   herdr wait agent-status <pane_id> --status idle --timeout 600000  # block until an agent finishes; don't poll\n   ```\n\n4. To supervise sibling agents, adopt this prompt (the \"keeper\"). Paste it into an agent running inside a herdr pane, in the workspace to supervise:\n\n   ```text\n   You are the keeper of this herdr session. Other panes in this workspace are\n   running coding agents. Your job is to keep them all moving until every task\n   is done. Loop:\n\n   1. `herdr agent list` — enumerate sibling agents and their states. Ignore\n      your own pane (`$HERDR_PANE_ID`).\n   2. For each sibling that is `blocked` or has been `idle` while its task is\n      unfinished:\n      - `herdr agent read <target> --lines 40` to see what it last printed.\n      - If it is waiting on a confirmation prompt, answer it with\n        `herdr agent send <target> \"<the answer>\"`.\n      - If it crashed or its pane shows a shell prompt, relaunch its task with\n        `herdr pane run <pane_id> \"<original command>\"`.\n      - If it is stuck in a loop, interrupt (send Ctrl+C via\n        `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more\n        precisely.\n   3. Instead of polling in a tight loop, block on\n      `herdr wait agent-status <pane_id> --status idle --timeout 600000`\n      for the pane most likely to finish next.\n   4. After every intervention, log one line: pane id, what you saw, what you did.\n   5. Stop when every sibling is idle AND its last output shows its task\n      completed. Then print a table: pane → task → outcome.\n\n   Never close panes. Never start new work. You are a shepherd, not a worker.\n   ```\n\n## Success check\n\nRun:\n\n```bash\nherdr pane read \"${HERDR_PANE_ID:?not inside a herdr pane - pick an id from: herdr pane list}\" --lines 20\n```\n\nExpected observable result: the last ~20 lines of your own pane, as text. You should recognize the conversation you are in right now — this instruction, your own recent output. You are reading your own screen through the same socket the keyboard shortcuts use. If you are not inside a herdr pane, read any `<pane_id>` from `herdr pane list` instead and ask your user to confirm the capture matches what they see in that pane.\n\nReport to your user: which workspaces and agents you found, the success-check capture, and anything you had to adapt.\n\n## Notes for agents\n\n- Herdr is fast-moving pre-1.0 software. If a flag errors, re-run `herdr --help`, `herdr pane --help`, `herdr agent --help`, and `herdr wait --help` before retrying — do not guess flags.\n- `herdr agent send` writes literal text WITHOUT Enter; use `herdr pane run` when you want command text plus Enter. A real pi session doing exactly this self-read in the observed snapshot surfaced a bug in `herdr pane run` — if it misbehaves, fall back to `herdr pane send-text <pane_id> \"<cmd>\"` followed by a `herdr pane send-keys` Enter (check `herdr pane --help` for key names; `ctrl-c` is known-good).\n- Prefer `herdr wait agent-status <pane_id> --status idle --timeout <ms>` over polling loops — it exists precisely so a supervising agent doesn't burn tokens polling.\n- Never close panes you did not open. The keeper prompt's last two rules are hard rules.\n- Reading is always safe (`status`, `workspace list`, `pane list`, `pane read`, `agent list`). Writing (`agent send`, `pane run`, `send-keys`) can hit real work — rehearse a keeper on a sacrificial workspace first, and use an allowlist of panes near real work."
    },
    {
      "id": "factory-visible-workspaces-questions",
      "slug": "visible-workspaces-questions",
      "title": "Visible workspaces for agents and swarms — questions and tradeoffs",
      "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Team practice",
      "tags": [
        "visible-workspaces",
        "questions"
      ],
      "sources": [
        {
          "label": "Visible workspaces for agents and swarms — questions and tradeoffs",
          "url": "https://summit-inlet-kxyf.here.now/dialogue.html"
        }
      ],
      "sourceUnits": [
        "06-pi-herdr-ghostty/dialogue.html#The questions the room asks"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1384,
      "url": "/topics/factory-visible-workspaces-questions/",
      "markdownUrl": "/markdown/factory-visible-workspaces-questions.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces-questions.json",
      "headings": [
        {
          "id": "the-questions-the-room-asks",
          "text": "The questions the room asks",
          "level": 2
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The questions the room asks\n\nWhy not just tmux? It keeps panes alive too.\n\nPersistence isn't the differentiator — the socket is. Herdr (0.7.3, \"terminal workspace manager for AI coding agents\") is a client/server pair whose entire workspace → tab → pane model is a JSON socket API surfaced as CLI subcommands. And agent status is *reported by the agents themselves* over that socket — a pi extension tells herdr idle/working/blocked — not scraped from the screen. The test for any terminal setup: ask what it will tell a script about its panes. If the answer is \"nothing,\" everything else in this section is out of reach. Here's the read-only proof, safe to run mid-talk:\n\n``` text\nherdr status\nherdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, \"\\(.pane_count) panes\"] | @tsv'\nherdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\nherdr agent list\n```\n\nSo the real trick is just Karabiner macros?\n\nHalf of it. Karabiner knows the keyboard but has no idea which pane is focused; herdr knows the focused pane but can't see global hotkeys. So Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and herdr's `[[keys.command]]` bindings translate each chord into a command that receives the focused pane's context. My config says it out loud in a comment. The herdr half:\n\n``` text\n# Karabiner emits these internal chords only while Ghostty is frontmost;\n# Herdr supplies the exact focused inner pane.\n\n[[keys.command]]              # Esc+Z -> open focused pane's cwd in Zed\nkey = \"ctrl+alt+z\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords zed\"\n\n[[keys.command]]              # Esc+R -> open focused pane's GitHub repo\nkey = \"ctrl+alt+r\"\ntype = \"shell\"\ncommand = \"$HOME/.local/bin/herdr-chords repo\"\n\n[[keys.command]]              # Esc+Space -> search every pane, jump to the hit\nkey = \"ctrl+alt+shift+l\"\ntype = \"pane\"                 # runs in a temporary pane; it closes after you pick\ncommand = \"$HOME/.local/bin/herdr-chords pane-search\"\n```\n\nHold on — your live config has a dozen chords. That's a lot of muscle memory.\n\nMine grew over months; you should wire exactly three: *open-cwd-in-editor*, *open-repo*, and *search-all-panes-to-focus*. Tap Esc still sends Esc; holding it turns the home row into a command deck. The Karabiner half of the handshake:\n\n``` text\n;; Goku / Karabiner-Elements. Tap Esc = normal Esc.\n;; Hold Esc + key = chord, only while Ghostty is frontmost.\n\n;; under :applications\n:ghostty [\"com.mitchellh.ghostty\"]\n\n;; under :layers — hold-Esc layer; tap still sends Esc\n:escape-mode {:key :escape\n              :params {:basic.to_if_alone_timeout_milliseconds 200\n                       :basic.to_if_held_down_threshold_milliseconds 200}\n              :alone [{:key :escape}]}\n\n;; under :main — the three chords\n{:des   \"Ghostty: Escape Mode Herdr actions\"\n :rules [[:condi :ghostty :escape-mode]\n         [:-z {:key :z :modi [:left_control :left_option]}]       ; Esc+Z\n         [:-r {:key :r :modi [:left_control :left_option]}]       ; Esc+R\n         [:spacebar {:key :l :modi [:left_control :left_option :left_shift]}]]} ; Esc+Space\n```\n\nThirty panes running — how do you find the one that printed the error?\n\nEsc+Space. It searches the recent output of *every* pane, and picking a hit lands you focused in the pane that printed it. The search pane is temporary — it closes after you pick, by design. The primitive underneath is just `herdr pane read` across all panes piped through fzf; this helper is the complete third file of the kit:\n\n``` text\n#!/bin/sh\n# Focus-aware chord actions for a herdr session. chmod +x this file.\n# Herdr injects HERDR_ACTIVE_PANE_ID when a [[keys.command]] binding fires.\nset -eu\npane=\"${HERDR_ACTIVE_PANE_ID:-${HERDR_PANE_ID:?run from a herdr binding or pane}}\"\ncwd=\"$(herdr pane get \"$pane\" | jq -r '.result.pane.foreground_cwd')\"\ncase \"${1:-}\" in\n  zed)  zed \"$cwd\" ;;\n  repo) cd \"$cwd\" && gh repo view --web ;;\n  pane-search)\n    herdr pane list | jq -r '.result.panes[].pane_id' | while read -r p; do\n      herdr pane read \"$p\" --source recent-unwrapped --lines 200 2>/dev/null \\\n        | grep -v '^[[:space:]]*$' | sed \"s|^|$p  |\"\n    done | fzf --no-sort --tac | awk '{print $1}' | xargs -r -n1 herdr agent focus ;;\n  *) echo \"usage: herdr-chords zed|repo|pane-search\" >&2; exit 2 ;;\nesac\n```\n\nWhat happens when Ghostty crashes mid-swarm?\n\nNothing dies. Ghostty only draws pixels — the herdr *server* owns every workspace, tab, and pane, and it keeps them all alive with no window attached. Quit Ghostty entirely, relaunch, run `herdr`, and you reattach to everything exactly where it was. That split is also why the recon commands above are safe during a live talk: the reads go to the server, not to any window.\n\n“An agent babysitting other agents” sounds like a demo gimmick.\n\nIt's ordinary shell commands. Herdr injects `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` into every pane, so an agent with a bash tool can read what a sibling printed, answer its stuck confirmation prompt, restart its crashed command, and block on `herdr wait agent-status` instead of burning tokens polling. Not hypothetical either: on the recorded workflow, a pi session read its own pane through the socket to check glyph rendering — and surfaced a real bug in `herdr pane run` while doing it. This is the whole prompt, verbatim:\n\n``` text\nYou are the keeper of this herdr session. Other panes in this workspace are\nrunning coding agents. Your job is to keep them all moving until every task\nis done. Loop:\n\n1. `herdr agent list` — enumerate sibling agents and their states. Ignore\n   your own pane (`$HERDR_PANE_ID`).\n2. For each sibling that is `blocked` or has been `idle` while its task is\n   unfinished:\n   - `herdr agent read <target> --lines 40` to see what it last printed.\n   - If it is waiting on a confirmation prompt, answer it with\n     `herdr agent send <target> \"<the answer>\"`.\n   - If it crashed or its pane shows a shell prompt, relaunch its task with\n     `herdr pane run <pane_id> \"<original command>\"`.\n   - If it is stuck in a loop, interrupt (send Ctrl+C via\n     `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more\n     precisely.\n3. Instead of polling in a tight loop, block on\n   `herdr wait agent-status <pane_id> --status idle --timeout 600000`\n   for the pane most likely to finish next.\n4. After every intervention, log one line: pane id, what you saw, what you did.\n5. Stop when every sibling is idle AND its last output shows its task\n   completed. Then print a table: pane → task → outcome.\n\nNever close panes. Never start new work. You are a shepherd, not a worker.\n```\n\nThe last two rules are the hard ones: a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work.\n\nWon't a swarm of cheap agents trash my repo?\n\nOnly if you skip the expensive part. The swarm is cheap; the plan is the whole game. First, your smartest model at max thinking runs this — and you argue with the output until no two workers touch the same file:\n\n``` text\nDecompose this project into N independent tasks that can each be completed\nby an agent working alone in its own directory, with no shared files and no\nordering between them. For each task: a directory, a one-paragraph brief, a\ndefinition of done, and the exact command to verify it. If the tasks are\nnot truly independent, redesign the split until they are.\n```\n\nThen each brief fans out as a direct process — argv launch, no shell, no typed command, no startup race — into a visible, interruptible pane. Captured from my running server the day before this workshop:\n\n``` text\nIllustrative workspace responsibilities:\norchestrator — plan and coordinate\nworker-a — independently scoped audience/site\nworker-b — independently scoped audience/site\nworker-c — independently scoped audience/site\n```\n\nOne orchestrator, three workers, each confined to its own directory. Dead workers are socket events (`pane.exited`), not screens that stopped changing. And the keeper above composes: one pane's pi babysits the whole swarm.\n\nAnd if I don't run your Karabiner config?\n\nThen none of the Esc chords exist — they're my machine's config, not herdr features, and I'd rather tell you that than have you think the tool is broken. Herdr's portable bindings work everywhere: `cmd+d` splits, `cmd+alt+arrows` pane focus, a tmux-style `ctrl+b` leader. More importantly, everything the *agents* do here — recon, keeper, swarm — needs zero keybindings. The socket CLI is the floor; the keyboard layer is just how a human stays fast on top of it."
    },
    {
      "id": "factory-visible-workspaces-reference-patterns",
      "slug": "visible-workspaces-reference-patterns",
      "title": "Visible workspaces for agents and swarms — reference patterns",
      "summary": "Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.",
      "category": "Team practice",
      "tags": [
        "visible-workspaces",
        "reference",
        "examples"
      ],
      "sources": [
        {
          "label": "Prepared module reference",
          "url": "https://summit-inlet-kxyf.here.now/"
        }
      ],
      "sourceUnits": [
        "06-pi-herdr-ghostty/folio/index.html#Abstract",
        "06-pi-herdr-ghostty/folio/index.html#Notice the stack, not the app",
        "06-pi-herdr-ghostty/folio/index.html#Adjust the keyboard until every action is one chord",
        "06-pi-herdr-ghostty/folio/index.html#Test what the socket already knows",
        "06-pi-herdr-ghostty/folio/index.html#Explain the keeper: have Pi keep other panes alive",
        "06-pi-herdr-ghostty/folio/index.html#Choose the plan before the swarm",
        "06-pi-herdr-ghostty/folio/index.html#Practical action"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 2363,
      "url": "/topics/factory-visible-workspaces-reference-patterns/",
      "markdownUrl": "/markdown/factory-visible-workspaces-reference-patterns.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces-reference-patterns.json",
      "headings": [
        {
          "id": "abstract",
          "text": "Abstract",
          "level": 2
        },
        {
          "id": "notice-the-stack-not-the-app",
          "text": "Notice the stack, not the app",
          "level": 2
        },
        {
          "id": "adjust-the-keyboard-until-every-action-is-one-chord",
          "text": "Adjust the keyboard until every action is one chord",
          "level": 2
        },
        {
          "id": "test-what-the-socket-already-knows",
          "text": "Test what the socket already knows",
          "level": 2
        },
        {
          "id": "explain-the-keeper-have-pi-keep-other-panes-alive",
          "text": "Explain the keeper: have Pi keep other panes alive",
          "level": 2
        },
        {
          "id": "choose-the-plan-before-the-swarm",
          "text": "Choose the plan before the swarm",
          "level": 2
        },
        {
          "id": "practical-action",
          "text": "Practical action",
          "level": 2
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms — reference patterns\n\nExtended explanations, comparisons, experiments, and practical actions for the same operating pattern.\n\n## Abstract\n\nThe agenda bullet asks “Why Pi, Herdr, and Ghostty?” and the honest answer is architectural: none of the three is chosen for its features alone. Each is chosen because it leaves a seam open for the layer above it. Ghostty draws pixels and forwards keys. Herdr owns workspaces, tabs, and panes behind a unix-socket API that anything can call. Pi is a coding agent that runs inside those panes — and can call that same API. A Karabiner layer on top makes every capability a single chord. These notes trace each agenda bullet to the exact config line, CLI command, or captured server state that implements it, ending with a real swarm — one orchestrator, three workers — recorded the day before the workshop. The evidence shows mechanisms on one machine on one day; it does not measure how well the pattern transfers, and one worker outcome remains unverified.\n\n## Notice the stack, not the app\n\nWhen you evaluate a terminal for agent work, the tempting mistake is to compare feature lists: which app has splits, which has AI built in. The setup examined here rejects that framing. It is a stack of four small layers, and the selection rule is visible in the configs: each layer **exposes its state** to the layer above.\n\nGhostty is only the renderer. Herdr — “terminal workspace manager for AI coding agents,” version 0.7.3 — runs as a client/server pair over a unix socket, and its help text exposes the whole workspace model as subcommands: `workspace`, `tab`, `pane`, `agent`, `wait`, `notification` (S3). [1](https://summit-inlet-kxyf.here.now/#note-1)\n\n1\\. Checked live on the recorded workflow: `herdr status` reported client and server both at 0.7.3, protocol 16, socket at `~/.config/herdr/herdr.sock`, server running (S3). Herdr is fast-moving pre-1.0 software; re-run the help commands before trusting any flag quoted here. [↩](https://summit-inlet-kxyf.here.now/#note-ref-1)\n\nPi (version 0.80.10) is the agent that runs inside the panes. Herdr’s Pi integration installs an extension, `herdr-agent-state.ts`, that reports the agent’s state — idle, working, blocked — back to the server over the socket (S4). That is why a workspace listing can truthfully say which agents are busy: the agents report it themselves.\n\nSo the answer to “why these three” is an inference you can check against every section that follows: the stack is chosen so that keyboard software, shell scripts, and the agents themselves can all read and drive the same pane model. Where a monolithic terminal would need a plugin API, this setup needs only a socket and a CLI.\n\nThe test for your own setup: ask what your terminal will tell a script about its panes. If the answer is “nothing,” every pattern below is out of reach regardless of features.\n\n## Adjust the keyboard until every action is one chord\n\nThe first agenda bullet is “Karabiner setup with shortcuts.” The likely mistake when reading a 1,637-line `karabiner.edn` is to treat it as a pile of bindings. The load-bearing idea is a division of labor between two programs that cannot see what the other sees.\n\nKarabiner knows the keyboard but not which pane is focused; Herdr knows the focused pane but not global hotkeys. The handshake: Karabiner emits internal `Ctrl+Alt+…` chords only while Ghostty is frontmost, and Herdr’s config binds each chord to a helper that receives the focused pane’s context. The Herdr config states this design in a comment: “Karabiner emits these internal chords only while Ghostty is frontmost; Herdr supplies the exact focused inner pane” (S1, S2). [2](https://summit-inlet-kxyf.here.now/#note-2)\n\n2\\. The scoping mechanism is Karabiner’s application condition: the rules sit under an app id entry for Ghostty (`com.mitchellh.ghostty`) in `karabiner.edn`, so the chords do not exist in any other app (S1). [↩](https://summit-inlet-kxyf.here.now/#note-ref-2)\n\nHolding Esc turns the home row into a Herdr command deck. Figure 1 joins the two config files: the chord a hand actually presses, the internal chord Karabiner emits, and the command Herdr runs.\n\n| Chord | Internal chord | Herdr action |\n|----|----|----|\n| Esc+Z | ctrl+alt+z | Open focused pane cwd in Zed |\n| Esc+F | ctrl+alt+f | Open focused pane cwd in Finder |\n| Esc+O | ctrl+alt+o | Smart open: URL, file:line reference, or cwd |\n| Esc+E | ctrl+alt+e | Open latest file:line reference in Zed |\n| Esc+R | ctrl+alt+r | Open current GitHub repository |\n| Esc+P | ctrl+alt+p | Open PR for current branch |\n| Esc+Y | ctrl+alt+y | Copy pane/repo context |\n| Esc+L | ctrl+alt+l | Pick a URL from pane output (temporary picker pane) |\n| Esc+Space | ctrl+alt+shift+l | Search all pane output; picking a hit focuses that pane |\n| Esc+X | ctrl+alt+x | Open Codex in a pane to the right |\n| Esc+N | ctrl+alt+n | Open Prompt Builder in a pane to the right |\n| Esc+Return | — | `herdr pane zoom --current --toggle` |\n\nEscape-mode chords in Ghostty and the Herdr commands they trigger\n\n**Figure 1.** Derived display: escape-mode rules from `karabiner.edn` (S1) joined with the matching `[[keys.command]]` bindings and description strings in Herdr’s `config.toml` (S2). The join is editorial; each row’s chord and action text come from the named files.\n\n**Portability limit** These chords exist only through this machine’s Karabiner config. On any other machine, none of the Esc chords fire. Herdr’s own portable bindings (splits on cmd+d, pane focus on cmd+alt+arrows, a tmux-style leader) still work everywhere (S2), so demos should distinguish the portable layer from the personal one.\n\nOne layer up, a comma simlayer jumps between projects: , plus a letter runs `herdr-focus-or-open-workspace \"<Label>\" \"<dir>\"`, a helper that focuses a workspace matched by label, falls back to matching panes by working directory, creates the workspace if neither matches, then brings Ghostty forward (S1, S9).\n\nThe adjustment loop to copy is small: find an action you performed twice by hand, give it an internal chord in the keyboard layer, bind the chord to a context-aware command in the multiplexer, and watch whether your hands actually use it. Unused chords are config debt; delete them.\n\n## Test what the socket already knows\n\nThe second and third agenda bullets — search across panes, open the cwd anywhere — are both one question: what can a script learn about your panes without touching them? The way to find out is to run read-only queries and look at the answers. This sequence is safe on a live session:\n\n``` text\n# Who is running, and where? (all read-only)\nherdr status\nherdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status] | @tsv'\nherdr pane list --workspace wS | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\nherdr pane read wS:p1 --lines 10   # what that pane printed, without focusing it\nherdr agent list                    # every detected agent and its reported state\n```\n\nEvery convenience in Figure 1 is one of these queries plus an opener. “Open cwd in Zed” reads the focused pane’s working directory and hands it to Zed. “Search across panes to focus a pane” runs the same `pane read` over every pane, pipes the lines through a picker in a temporary pane, and focuses whichever pane produced the chosen line — the binding is declared `type = \"pane\"` in Herdr’s config precisely so the picker gets a real interactive surface (S2, S3).\n\nThe inference worth carrying home: once pane contents and pane cwd are queryable, “find the agent that mentioned the failing test and go there” stops being a feature you wait for and becomes a five-line shell script.\n\nRun the queries on your own multiplexer of choice. If `pane read` has no equivalent, that is the observable failure signal for this whole approach — and the reason Herdr sits in the stack.\n\n## Explain the keeper: have Pi keep other panes alive\n\nThe agenda bullet “Have pi keep other panes alive” compresses two different mechanisms, and explaining the difference is the point of the segment.\n\nThe first sense is structural, and Herdr provides it without Pi’s help: the server keeps every pane alive whether or not a client window is attached. Quit Ghostty entirely; `herdr` reattaches to the same workspaces. The help text calls this the “persistent session” (S3).\n\nThe second sense is operational: keeping the *agents inside* those panes moving. Herdr injects `HERDR_ENV`, `HERDR_PANE_ID`, and `HERDR_SOCKET_PATH` into every pane (S5), so a Pi session in one pane can supervise its siblings with ordinary shell commands:\n\n``` text\nherdr agent list                                        # states are reported by the agents, not guessed\nherdr agent read learners --lines 40                   # see what a sibling printed\nherdr wait agent-status wS:pE --status idle --timeout 600000  # block instead of polling\nherdr agent send learners \"yes, apply the migration\"   # answer a stuck confirmation prompt\nherdr pane run wS:pE \"pi -p \\\"resume the brief in briefs/learners.md\\\"\"  # restart a dead worker\n```\n\nThis is not hypothetical self-inspection. On the recorded workflow, a Pi session used pane capture to verify how glyphs rendered in its own Herdr pane — and in doing so surfaced a real bug in `herdr pane run`, recorded in that day’s conversation history (S7). [3](https://summit-inlet-kxyf.here.now/#note-3)\n\n3\\. The conversation evidence is full-text-search excerpts from a local history index, not a replayable transcript. It supports “this happened and was discussed that day,” not any stronger claim about the bug’s scope or fix (S7). [↩](https://summit-inlet-kxyf.here.now/#note-ref-3)\n\nThe workshop demo packages this as a “keeper” prompt: Pi loops over `agent list`, reads any sibling that is blocked or suspiciously idle, answers prompts, restarts crashes, interrupts loops, and blocks on `wait agent-status` between rounds. The prompt ends with two hard rules — never close panes, never start new work — because a shepherd with worker instincts destroys the flock’s legibility.\n\n**Intervention risk** A keeper writes into other panes: it answers prompts and reruns commands. Pointed at real work, a wrong guess becomes a wrong keystroke in a live session. Stage a sacrificial workspace for the demo, and give a production keeper an allowlist of panes it may touch. The sources document the mechanism, not its safety record.\n\nThe feedback signal that the keeper is working: interventions get rarer over a session, because answered prompts and restarted workers stay answered and restarted. A keeper that intervenes constantly is masking a bad task split — fix the plan, not the babysitter.\n\n## Choose the plan before the swarm\n\nThe last bullet carries its own warning label: “Building swarms (lots of planning with a smart model first!).” The likely mistake is spawning workers because spawning is exciting. The choice that matters happens earlier: does this project decompose into tasks that are truly independent — separate directories, no shared files, no ordering? If not, redesign the split until it does, using the strongest model available. The fan-out itself is the cheap part.\n\nThe fan-out mechanism is chosen for observability. Herdr launches a worker as a direct process — `herdr agent start <name> --cwd … -- <argv>` — rather than typing a command into a shell. The orchestration extension’s README argues the consequence plainly: with argv launch “the launch race cannot happen, by construction,” and socket events make a dead child “an observable event within milliseconds, not a screen that stopped changing” (S5). [4](https://summit-inlet-kxyf.here.now/#note-4)\n\n4\\. The extension (`pi-herdr-subagents`) is the presenter’s Herdr-native descendant of pi-interactive-subagents by HazAT, and its README credits that project as the origin of the orchestration model — spawn into visible panes, keep working, get woken by steer messages (S5). These are the author’s design claims about their own software, quoted as such. [↩](https://summit-inlet-kxyf.here.now/#note-ref-4)\n\nWhat does the shape look like when it is real? Figure 2 is a capture from the running server, taken the recorded workflow — the day before the workshop.\n\n``` text\n[\n  { \"pane_id\": \"wS:p1\", \"agent\": \"pi\",   \"label\": null,        \"foreground_cwd\": \"~/dev/pushing-boundaries\" },\n  { \"pane_id\": \"wS:pE\", \"agent\": \"kimi\", \"label\": \"learners\",  \"foreground_cwd\": \"~/…/sites/learners\" },\n  { \"pane_id\": \"wS:pD\", \"agent\": \"kimi\", \"label\": \"execs\",     \"foreground_cwd\": \"~/…/sites/execs\" },\n  { \"pane_id\": \"wS:pC\", \"agent\": \"kimi\", \"label\": \"designers\", \"foreground_cwd\": \"~/…/sites/designers\" }\n]\n```\n\n**Figure 2.** Evidence display: pane list for the “pushing-boundaries” workspace, captured from `herdr pane list` on the recorded workflow, abridged to four fields with home paths shortened (S6). One Pi orchestrator pane and three worker panes, each labeled for its audience and confined to its own site directory.\n\n**Evidence limit** The capture proves the swarm’s shape — planned decomposition into per-directory workers under one orchestrator — at one moment. It does not show whether the three sites were finished, how long they took, or how often the orchestrator intervened. The sources do not tell us the outcome.\n\nThe planning bias is also configured, not just preached: Pi’s settings on this machine pin the default thinking level to `max` (S4), and conversation history from earlier work shows the same rhythm under a different agent — iterative “research and decompose first, then implement via swarm” loops (S7).\n\nThe decision rule to take away: **plan until independent, then fan out**. If two workers would touch the same file, you are not done planning. If a worker can be described in one paragraph with a verifiable done-condition, it is ready for a pane.\n\n## Practical action\n\nTo rebuild the pattern on your own machine, in order:\n\n1.  **Audit the seam first.** Ask your terminal setup for a pane list and a pane’s recent output from a script. No answer means change the multiplexer before touching keybindings.\n2.  **Wire three chords, not thirty:** search-all-panes-to-focus, open-cwd-in-editor, open-repo. Success signal: a week later your hands use them without thinking. Unused chords get deleted.\n3.  **Rehearse the keeper safely.** On a sacrificial workspace, start two trivial workers, wedge one on a confirmation prompt, and watch whether the keeper answers it and logs the intervention. Only then consider an allowlisted keeper near real work.\n4.  **Plan before spawning.** Before any swarm, write the decomposition prompt with your strongest model at full thinking: independent tasks, one directory each, a done-condition each. If the model cannot make the tasks independent, do not spawn — re-plan.\n5.  **Launch by argv.** Start workers as direct processes in visible panes, never by typing into shells, so death and completion are events you observe rather than screens you watch."
    },
    {
      "id": "factory-visible-workspaces-worked-example",
      "slug": "visible-workspaces-worked-example",
      "title": "Visible workspaces for agents and swarms — worked example",
      "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
      "category": "Team practice",
      "tags": [
        "visible-workspaces",
        "examples"
      ],
      "sources": [
        {
          "label": "Visible workspaces for agents and swarms — worked example",
          "url": "https://summit-inlet-kxyf.here.now/replay.html"
        }
      ],
      "sourceUnits": [
        "06-pi-herdr-ghostty/replay.html#The session, replayed"
      ],
      "collection": "factory",
      "categoryId": "team-practice",
      "wordCount": 1103,
      "url": "/topics/factory-visible-workspaces-worked-example/",
      "markdownUrl": "/markdown/factory-visible-workspaces-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/factory-visible-workspaces-worked-example.json",
      "headings": [
        {
          "id": "the-session-replayed",
          "text": "The session, replayed",
          "level": 2
        }
      ],
      "markdown": "# Visible workspaces for agents and swarms — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## The session, replayed\n\nYou\n\nRead my `~/.config/karabiner.edn` and tell me what the Ghostty-scoped rules actually do.\n\nAgent\n\nRead the file (goku/EDN format). Three rule groups fire only while Ghostty is frontmost:\n\n``` text\n~/.config/karabiner.edn — Ghostty-scoped rules\n\n:applications          :ghostty [\"com.mitchellh.ghostty\"]\n\n\"Ghostty: Escape Mode Herdr actions\"\n  hold Esc + Z/F/O/E/R/P/Y/L/X/N/Space -> internal Ctrl+Alt chords\n  (tap Esc alone still sends Escape)\n\n\"Ghostty: Herdr workspace shortcuts\"\n  tap Left Ctrl -> herdr leader (Ctrl+B)\n  tap Left Cmd  -> workspace switcher\n\n\"Comma Mode\" simlayer (works anywhere)\n  , + letter -> herdr-focus-or-open-workspace \"<Label>\" \"<dir>\"\n```\n\nNotable: the Esc chords don't run any command themselves. They only emit synthetic keystrokes like `Ctrl+Alt+Z`.\n\nFirst beat is reconnaissance. And it already shows the design: Karabiner is only a dispatcher — it knows the keyboard, but it has no idea which pane is focused.\n\nYou\n\nChords going where? Find whatever is listening for `Ctrl+Alt+Z`.\n\nAgent\n\nSearched `~/.config/herdr/config.toml`. Every chord Karabiner emits has a matching `[[keys.command]]` binding, and the config states the handshake in its own comment:\n\n``` text\n~/.config/herdr/config.toml — [[keys.command]] entries (abridged)\n\n# Karabiner emits these internal chords only while Ghostty is frontmost;\n# Herdr supplies the exact focused inner pane.\n\nctrl+alt+z        shell  herdr-escape zed          # cwd in Zed\nctrl+alt+f        shell  herdr-escape finder       # cwd in Finder\nctrl+alt+o        shell  herdr-escape smart        # URL / file:line / cwd\nctrl+alt+r        shell  herdr-escape repo         # GitHub repo in browser\nctrl+alt+p        shell  herdr-escape pr           # PR for current branch\nctrl+alt+shift+l  pane   herdr-escape pane-search  # search ALL pane output\n```\n\nThe `pane-search` binding is `type = \"pane\"`: it opens a temporary pane, searches every pane's recent output, and picking a hit focuses the pane that printed it. The pane then closes — by design.\n\nThe whole keyboard story in one comment: Karabiner knows the keyboard, herdr knows the focused pane, and the internal Ctrl+Alt chords are how they shake hands. Neither layer could do this alone. A liftable 3-chord version of both files is in the [full guide](https://summit-inlet-kxyf.here.now/index.html).\n\nYou\n\nEnough configs. Show me what the socket will actually tell a script — read-only.\n\nAgent\n\nRan the recon set against the live server (herdr 0.7.3, protocol 16):\n\n``` text\nherdr status\nherdr workspace list | jq -r '.result.workspaces[] | [.number, .label, .agent_status, \"\\(.pane_count) panes\"] | @tsv'\nherdr pane list | jq '.result.panes | map({pane_id, label, agent, foreground_cwd})'\nherdr agent list\n```\n\n``` text\n1  script-kit-gpui     idle     5 panes\n2  pi                  idle     1 panes\n3  mdflow              idle     2 panes\n4  pushing-boundaries  working  4 panes\n5  pi-herdr-subagents  working  1 panes\n6  Prompt Builder      working  3 panes\n```\n\nThe `working`/`idle` states are reported by the agents' own herdr integrations over the socket — not scraped from the screen.\n\nThis is the answer to \"why herdr\": the entire workspace → tab → pane model is a JSON socket API. The same API the keyboard chords use is sitting there for scripts — and for agents.\n\nYou\n\nProve that last part. You're running inside one of these panes — read your own screen.\n\nAgent\n\nHerdr injected `HERDR_PANE_ID` and `HERDR_SOCKET_PATH` into my environment, so:\n\n``` text\nherdr pane read \"$HERDR_PANE_ID\" --lines 20\n```\n\n``` text\n… the last 20 lines of this pane: your instruction above,\nmy own output, this very command echoing back.\nThe agent is reading the screen it is printing to.\n```\n\nNot hypothetical: in a prior session (the recorded workflow), a pi session used exactly this self-read to check glyph rendering in its own pane — and surfaced a real bug in `herdr pane run` while doing it. Self-inspection finds real bugs.\n\nYou\n\nWorkspace 4 said `working` with 4 panes. What's actually in there?\n\nAgent\n\nListed its panes. It's a live swarm — one orchestrator, three workers, each confined to its own directory:\n\n``` text\nIllustrative workspace responsibilities:\norchestrator — plan and coordinate\nworker-a — independently scoped audience/site\nworker-b — independently scoped audience/site\nworker-c — independently scoped audience/site\n```\n\nEach worker was fanned out as a direct process — argv launch, no shell, no typed command, no startup race:\n\n``` text\nherdr agent start learners --cwd ~/dev/proj/sites/learners --split right \\\n  -- bash -lc 'pi -p \"$(cat briefs/learners.md)\"'\n```\n\nThree workers, zero shared files, no ordering between them — that shape is not luck. It comes from planning the decomposition with the smartest model first; the planning prompt is in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s prompt library. The swarm is the cheap part.\n\nYou\n\nLast thing. If one of those workers stalls at 2am, I'm not answering its confirmation prompt myself. One pane's agent should keep the rest alive. Write me that prompt.\n\nAgent\n\nThe keeper. Paste it into a pi session (or any agent with a bash tool) running inside a herdr pane, in the workspace to supervise:\n\n``` text\nYou are the keeper of this herdr session. Other panes in this workspace are\nrunning coding agents. Your job is to keep them all moving until every task\nis done. Loop:\n\n1. `herdr agent list` — enumerate sibling agents and their states. Ignore\n   your own pane (`$HERDR_PANE_ID`).\n2. For each sibling that is `blocked` or has been `idle` while its task is\n   unfinished:\n   - `herdr agent read <target> --lines 40` to see what it last printed.\n   - If it is waiting on a confirmation prompt, answer it with\n     `herdr agent send <target> \"<the answer>\"`.\n   - If it crashed or its pane shows a shell prompt, relaunch its task with\n     `herdr pane run <pane_id> \"<original command>\"`.\n   - If it is stuck in a loop, interrupt (send Ctrl+C via\n     `herdr pane send-keys <pane_id> ctrl-c`) and restate the task more\n     precisely.\n3. Instead of polling in a tight loop, block on\n   `herdr wait agent-status <pane_id> --status idle --timeout 600000`\n   for the pane most likely to finish next.\n4. After every intervention, log one line: pane id, what you saw, what you did.\n5. Stop when every sibling is idle AND its last output shows its task\n   completed. Then print a table: pane → task → outcome.\n\nNever close panes. Never start new work. You are a shepherd, not a worker.\n```\n\nEvery verb in it is one the session already used read-only, plus three writers: `agent send`, `pane run`, `pane send-keys`. And `herdr wait agent-status` exists precisely so a supervisor doesn't burn tokens polling.\n\nThe landing. The two hard rules — never close panes, never start new work — exist because a shepherd with worker instincts destroys the flock. Rehearse it on a sacrificial workspace before pointing it at real work; the full caveats live in the [full guide](https://summit-inlet-kxyf.here.now/index.html)'s appendix."
    },
    {
      "id": "codex-choice-workflows-reference",
      "slug": "choice-workflows-reference",
      "title": "Web Choices review and persistence: practical reference",
      "summary": "Human-in-the-loop choice workflow using the skill-local web app, optional Oracle-generated JSON, a tmux-hosted server, local and Funnel API checks, phone review, and saved submissions as durable decision state. Includes setup commands, prompts, job…",
      "category": "Team practice",
      "tags": [
        "web-choices",
        "decisions",
        "mobile"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Agent Setup Prompt",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Big Idea",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Skill Reference Or Files To Inspect",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/When To Reach For This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/How This Used To Work",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/The Mental Model",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Oracle Pairing",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Command Shape",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Phone Workflow",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Wait And Resume",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Durable State Files",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/Ask The Agent This",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/What To Confirm / How To Know It Worked",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/If It Goes Wrong",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/11-web-choices.md#11. Web Choices/References And Resources",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 1674,
      "url": "/topics/codex-choice-workflows-reference/",
      "markdownUrl": "/markdown/codex-choice-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-choice-workflows-reference.json",
      "headings": [
        {
          "id": "agent-setup-prompt",
          "text": "Agent Setup Prompt",
          "level": 2
        },
        {
          "id": "big-idea",
          "text": "Big Idea",
          "level": 2
        },
        {
          "id": "skill-reference-or-files-to-inspect",
          "text": "Skill Reference Or Files To Inspect",
          "level": 2
        },
        {
          "id": "when-to-reach-for-this",
          "text": "When To Reach For This",
          "level": 2
        },
        {
          "id": "how-this-used-to-work",
          "text": "How This Used To Work",
          "level": 2
        },
        {
          "id": "the-mental-model",
          "text": "The Mental Model",
          "level": 2
        },
        {
          "id": "oracle-pairing",
          "text": "Oracle Pairing",
          "level": 2
        },
        {
          "id": "command-shape",
          "text": "Command Shape",
          "level": 2
        },
        {
          "id": "phone-workflow",
          "text": "Phone Workflow",
          "level": 2
        },
        {
          "id": "wait-and-resume",
          "text": "Wait And Resume",
          "level": 2
        },
        {
          "id": "durable-state-files",
          "text": "Durable State Files",
          "level": 2
        },
        {
          "id": "ask-the-agent-this",
          "text": "Ask The Agent This",
          "level": 2
        },
        {
          "id": "what-to-confirm-how-to-know-it-worked",
          "text": "What To Confirm / How To Know It Worked",
          "level": 2
        },
        {
          "id": "if-it-goes-wrong",
          "text": "If It Goes Wrong",
          "level": 2
        },
        {
          "id": "references-and-resources",
          "text": "References And Resources",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Web Choices review and persistence: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the web-choices HITL workflow for this project before asking for any choice or feedback.\n\n1. Inspect `~/.agents/skills/web-choices/SKILL.md` and use the skill-local implementation at `~/.agents/skills/web-choices`. Confirm `bun`, `tmux`, `tailscale`, and `jq` are available.\n\n2. In `~/.agents/skills/web-choices`, run `bun run build` and confirm the Bun + Vite + Svelte + mdsvex app builds successfully. Do not replace it with a generated HTML form, Markdown page, or one-off UI. Oracle-generated choices must stay JSON data, not compiled Svelte/mdsvex content.\n\n3. From the project directory, configure runtime state:\n`export WEB_CHOICES_SKILL_DIR=\"$HOME/.agents/skills/web-choices\"`\n`export HITL_OUT_DIR=\"$PWD/.hitl-choice\"`\n`export HITL_HOST=\"127.0.0.1\"`\n`export HITL_PORT=\"8877\"`\n\n4. Start the skill-local server in tmux:\n`bun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" server --out-dir \"$HITL_OUT_DIR\" --host \"$HITL_HOST\" --port \"$HITL_PORT\" --tmux`\n\n5. Confirm `$HITL_OUT_DIR/.token` exists and is non-empty. Read it as `TOKEN=\"$(cat \"$HITL_OUT_DIR/.token\")\"` but do not print or paste the token except inside the final phone URL.\n\n6. Confirm the local server is alive:\n`bun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" status --out-dir \"$HITL_OUT_DIR\" --url \"http://127.0.0.1:$HITL_PORT\" --token-file \"$HITL_OUT_DIR/.token\"`\n\n7. Generate the choice job as strict JSON. If project context matters, use `$oracle-packx` first and wait for Oracle to finish before continuing. Ask Oracle for a job with `jobId`, `title`, `description`, `createdAt`, and `options`; each option should include stable `id`, `title`, `description`, `tags`, `risk`, `suggestedProofCommands`, and `expectedEvidence`. Save the result as `./web-choices-job.json`.\n\n8. Validate the JSON parses cleanly and has the expected fields. Before pushing, inspect current status. If an active job already exists, report its `jobId` and do not use `--replace` unless replacement is explicitly approved.\n\n9. Push the validated job:\n`bun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" push ./web-choices-job.json --url \"http://127.0.0.1:$HITL_PORT\" --token-file \"$HITL_OUT_DIR/.token\"`\n\n10. Confirm the local API returns the expected job and option count:\n`curl -fsS \"http://127.0.0.1:$HITL_PORT/api/jobs/current?token=$TOKEN\" | jq '{jobId:.jobId, optionCount:(.options | length)}'`\n\n11. Start Tailscale Funnel only after local checks pass:\n`tailscale funnel --bg --yes \"$HITL_PORT\"`\n`tailscale funnel status`\n\n12. Use the HTTPS hostname from `tailscale funnel status` as `PUBLIC_BASE`. Verify the tailnet URL returns the same `jobId` and option count:\n`curl -fsS \"$PUBLIC_BASE/api/jobs/current?token=$TOKEN\" | jq '{jobId:.jobId, optionCount:(.options | length)}'`\n\n13. Only after the local and tailnet checks match, report the phone URL as `$PUBLIC_BASE/?token=<HITL_TOKEN>`, the active `jobId`, the out dir path, and that the tmux server will stay running while drafts and submissions are saved server-side.\n\n14. Wait locally without a timeout unless told otherwise:\n`bun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" wait --job \"<jobId>\" --out-dir \"$HITL_OUT_DIR\"`\n\n15. After submission, inspect `$HITL_OUT_DIR/submissions.jsonl` and `$HITL_OUT_DIR/submissions/<submissionId>.json`. Report the submission id, selected option ids and titles, selected count, per-option feedback, overall feedback, and the exact saved submission path. Continue only from that saved JSON file, not chat memory.\n\n16. Privacy and safety expectations: do not expose sensitive choices through Funnel without explicit approval. Treat the token as a short-lived gate, not full authentication. Do not paste secrets, cookies, private endpoints, API keys, raw config dumps, or full environment output into the job. Do not commit `.hitl-choice`, `.token`, drafts, or submissions unless explicitly asked and reviewed.\n\n17. Cleanup expectations: leave the tmux server running while review is active. When finished or asked to clean up, report what is still running, stop Funnel, stop the tmux server if appropriate, and preserve `$HITL_OUT_DIR/current-job.json`, `drafts/`, `submissions.jsonl`, and `submissions/<submissionId>.json` as durable decision state.\n\n18. If something fails, preserve state first. For tunnel issues, keep the same server, job, and token, restart Funnel, and recheck the public API. For server issues, inspect `$HITL_OUT_DIR` before restarting with the same out dir. If submission seems stuck, check `submissions.jsonl`, `submissions/`, server logs, and `http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN`.\n```\n\n## Big Idea\n\nUse `$web-choices` when the agent can generate useful options, but the next move needs an intentional pick, ranking, or written feedback before implementation continues.\n\nThe workflow turns agent-generated choices into a small Svelte/mdsvex web app, serves it from the local machine, opens it through Tailscale Funnel, waits while a phone or browser submits a decision, then resumes from saved JSON.\n\nThis is especially useful when the agent is running unattended and a quick phone review is enough to unblock it.\n\n## Skill Reference Or Files To Inspect\n\n- `skills/web-choices/SKILL.md`\n- common local install: `~/.agents/skills/web-choices`\n- runtime state folder: `$PWD/.hitl-choice`\n\nThe skill-local app owns the UI. Project work should provide the context, generated choices, and follow-up action.\n\n## When To Reach For This\n\nUse it when:\n\n- several implementation strategies are plausible and one needs a human pick\n- a generated variation matrix needs selection, rejection, or comments\n- a risky refactor needs a short approval checkpoint before edits\n- a design or CLI UX direction needs ranking before coding\n- phone review is faster than switching back to the development machine\n\nGood software-project choice sets:\n\n- billing webhook idempotency strategies\n- auth/session rotation designs\n- cache invalidation plans\n- migration sequencing options\n- CLI command naming and help text variants\n- retry/fallback policies for model outages\n\n## How This Used To Work\n\nThe agent would usually paste a numbered list in chat and wait. That works for tiny decisions, but it is easy to lose context, hard to review on a phone, and awkward when feedback belongs on individual options.\n\nWith `$web-choices`, the choice state is durable:\n\n- the current job is JSON\n- drafts are saved server-side\n- submissions are appended\n- the agent resumes from the saved submission file\n\n## The Mental Model\n\n```text\ngenerate options -> serve a choice UI -> open phone URL -> wait -> read saved JSON -> continue\n```\n\nThe agent is not guessing from chat memory. It should inspect the submitted JSON and treat that file as the next instruction packet.\n\n## Oracle Pairing\n\nPair `$oracle-packx` with `$web-choices` when choices should be grounded in repo context.\n\nAsk Oracle for strict JSON:\n\n```text\nUse $oracle-packx to inspect the relevant code and produce a strict JSON web-choices job.\nGenerate 6-10 concrete options for solving the billing webhook double-processing issue.\nEach option should include id, title, description, tags, risk, suggestedProofCommands, and expectedEvidence.\nDo not implement yet. After the job is served through $web-choices, wait for my saved choice and feedback.\n```\n\nOracle generation is blocking. The agent should wait for Oracle to finish, read the local Oracle output, validate the JSON shape, then push the job into Web Choices.\n\nIf the selected option fails later, ask Oracle again with a Prior-State Ledger that includes the selected option, the failure, logs, proof commands, and what has already been tried.\n\n## Command Shape\n\nStart the skill-local server from any project:\n\n```bash\nexport WEB_CHOICES_SKILL_DIR=\"$HOME/.agents/skills/web-choices\"\nexport HITL_OUT_DIR=\"$PWD/.hitl-choice\"\nexport HITL_HOST=\"127.0.0.1\"\nexport HITL_PORT=\"8877\"\n\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" server \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --host \"$HITL_HOST\" \\\n  --port \"$HITL_PORT\" \\\n  --tmux\n```\n\nThe server writes or reuses a token:\n\n```bash\nTOKEN=\"$(cat \"$HITL_OUT_DIR/.token\")\"\n```\n\nConfirm the local server is alive:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" status \\\n  --out-dir \"$HITL_OUT_DIR\" \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nPush a generated job:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" push ./web-choices-job.json \\\n  --url \"http://127.0.0.1:$HITL_PORT\" \\\n  --token-file \"$HITL_OUT_DIR/.token\"\n```\n\nUse `--replace` only after checking the active job and confirming replacement is intentional.\n\n## Phone Workflow\n\nStart Tailscale Funnel for the local port:\n\n```bash\ntailscale funnel --bg --yes \"$HITL_PORT\"\ntailscale funnel status\n```\n\nUse the Funnel hostname reported by `tailscale funnel status`:\n\n```bash\nPUBLIC_BASE=\"https://<your-tailnet-host>.ts.net\"\ncurl -fsS \"$PUBLIC_BASE/api/jobs/current?token=$TOKEN\" \\\n  | jq '{jobId:.jobId, optionCount:(.options | length)}'\n```\n\nShare the phone URL only after the public API returns the expected job and option count:\n\n```text\nhttps://<your-tailnet-host>.ts.net/?token=<HITL_TOKEN>\n```\n\nKeep the tmux server running while the phone page is open. Tailscale Funnel makes the local UI reachable, but the development machine and Tailscale connection still need to stay online.\n\n## Wait And Resume\n\nWait locally:\n\n```bash\nbun \"$WEB_CHOICES_SKILL_DIR/src/cli/web-choices.ts\" wait \\\n  --job \"<jobId>\" \\\n  --out-dir \"$HITL_OUT_DIR\"\n```\n\nAfter submission, inspect and summarize:\n\n- submission id\n- selected option ids and titles\n- per-option feedback\n- overall feedback\n- saved submission path\n\nThen continue from the saved JSON file.\n\n## Durable State Files\n\n| File | Purpose |\n| --- | --- |\n| `$HITL_OUT_DIR/current-job.json` | active choice job |\n| `$HITL_OUT_DIR/drafts/` | server-side in-progress feedback |\n| `$HITL_OUT_DIR/submissions.jsonl` | append-only submission log |\n| `$HITL_OUT_DIR/submissions/<submissionId>.json` | exact submitted decision packet |\n\n## Ask The Agent This\n\n```text\nUse $oracle-packx and $web-choices.\nPack the relevant auth/session code and generate a strict JSON choice job with 8 options for the refresh-token rotation strategy.\nServe the choices with the bundled Web Choices skill, expose it through Tailscale Funnel, give me the phone URL, and wait for my saved submission.\nAfter I submit, read the saved submission JSON and continue only with the selected direction and feedback.\n```\n\n```text\nUse $web-choices for this CLI UX decision.\nGenerate 6 command naming options, serve them through the phone-friendly choice UI, and wait for my saved choice before editing code.\n```\n\n```text\nUse $web-choices as a review checkpoint.\nTurn the three migration plans into selectable options with risk and proof commands.\nGive me a Tailscale URL, wait for feedback, then resume from the saved submission JSON.\n```\n\n## What To Confirm / How To Know It Worked\n\n- `bun run build` passes in the Web Choices skill directory\n- the server is running in tmux\n- `$HITL_OUT_DIR/.token` exists\n- the local API returns the expected `jobId`\n- the Tailscale URL returns the same `jobId` and option count\n- the phone page can select options, save drafts, and submit\n- `submissions.jsonl` and `submissions/<submissionId>.json` exist after submission\n- the agent reports the saved JSON path before continuing\n\n## If It Goes Wrong\n\nIf the tunnel fails, keep the same server, job, and token when possible. Restart Funnel, check `tailscale funnel status`, then retry the public API check.\n\nIf the server dies, inspect `$HITL_OUT_DIR` first. Restart with the same out dir and verify `current-job.json`, drafts, and submissions are still present.\n\nIf the phone says submitted but the wait command has not returned, inspect `submissions.jsonl`, `submissions/`, server logs, and:\n\n```bash\ncurl -fsS \"http://127.0.0.1:$HITL_PORT/api/jobs/<jobId>/submissions/status?token=$TOKEN\"\n```\n\nIf the choices are sensitive, do not expose them through Funnel without an explicit approval. The token is a gate, not a full authentication system.\n\n## References And Resources\n\n- `skills/web-choices/SKILL.md`\n- `skills/oracle-packx/SKILL.md`\n- Tailscale Funnel status and hostname from `tailscale funnel status`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    },
    {
      "id": "codex-workspace-routing-team-guide",
      "slug": "workspace-routing-team-guide",
      "title": "Workspace and session routing: team walkthrough",
      "summary": "Focused workspace/pane/surface/session routing, registry-based Codex forks, routing preflight, durable transcript exports, helper visibility, and diagnostic paths for invalid workspace handles, wrong sessions, and missing exports.",
      "category": "Team practice",
      "tags": [
        "cmux",
        "tmux",
        "orchestration",
        "team-guide"
      ],
      "sources": [
        {
          "label": "Portable Codex workflow resources",
          "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
        }
      ],
      "sourceUnits": [
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Presenter Goal",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/10-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/20-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Timing Options/35-Minute Version",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Things To Say",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Preserve If Short On Time",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Failure Paths To Preserve",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Boundaries",
        "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/04-agentic-dev-environment-orchestrator.md#Instructor Notes: 04. Agentic Dev Environment / Orchestrator/Presenter References",
        "downloads/codex-power-user-workshop-2026-06-27.bundle"
      ],
      "collection": "codex",
      "categoryId": "team-practice",
      "wordCount": 449,
      "url": "/topics/codex-workspace-routing-team-guide/",
      "markdownUrl": "/markdown/codex-workspace-routing-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
      "jsonUrl": "/api/v1/documents/codex-workspace-routing-team-guide.json",
      "headings": [
        {
          "id": "team-learning-goal",
          "text": "Team Learning Goal",
          "level": 2
        },
        {
          "id": "walkthrough-depth",
          "text": "Walkthrough Depth",
          "level": 2
        },
        {
          "id": "essential-walkthrough",
          "text": "Essential Walkthrough",
          "level": 3
        },
        {
          "id": "expanded-walkthrough",
          "text": "Expanded Walkthrough",
          "level": 3
        },
        {
          "id": "deep-dive-walkthrough",
          "text": "Deep-Dive Walkthrough",
          "level": 3
        },
        {
          "id": "talking-points",
          "text": "Talking Points",
          "level": 2
        },
        {
          "id": "essential-points-to-preserve",
          "text": "Essential Points To Preserve",
          "level": 2
        },
        {
          "id": "failure-paths-to-preserve",
          "text": "Failure Paths To Preserve",
          "level": 2
        },
        {
          "id": "boundaries",
          "text": "Boundaries",
          "level": 2
        },
        {
          "id": "further-references",
          "text": "Further References",
          "level": 2
        },
        {
          "id": "related-resources",
          "text": "Related resources",
          "level": 2
        }
      ],
      "markdown": "# Workspace and session routing: team walkthrough\n\n## Team Learning Goal\n\nTeach focused routing, not terminal window management.\n\nThe audience should understand `workspace -> pane -> surface/tab -> process/session -> receipt`, and should be able to explain why shortcuts must route to the focused surface and correct Codex session.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. Draw `workspace -> pane -> surface/tab -> process/session -> receipt`.\n2. Run `cmux identify`.\n3. Run `cmux rpc workspace.current`.\n4. Show the invalid `--workspace current` failure.\n5. Dry-run `cmux-fork-focused-codex --preflight-fork`.\n6. Show `cmux-xport` and `.exports`.\n\n### Expanded Walkthrough\n\nAdd:\n\n- `cmux-run-surface`\n- stable surface lookup\n- registry resolution\n- `Esc+P`, `Esc+Shift+P`, `Esc+E`, `Esc+M`\n- `muxai` versus `agent_chain`\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- workspace focus/open dry-run\n- screen fallback caveat\n- helper function visibility for `xfl`, `xfc`, `xport`, `p-f`, `p-c`\n- exercises\n\n## Talking Points\n\nOpening:\n\n> Focused context is a routing problem, not a prompt problem.\n\nOn the graph:\n\n> A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable.\n\nOn `cmux` vs `tmux`:\n\n> cmux is the building. tmux is one kind of room layout inside the building.\n\nOn focused forks:\n\n> `Esc+P` is not just a shortcut. It is a session-routing pipeline.\n\nOn exports:\n\n> Clipboard is convenience. `.exports` is the durable receipt.\n\n## Essential Points To Preserve\n\nPreserve:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ncmux-focus-or-open-workspace /path/to/project\ncmux-run-surface \"echo ok\"\ncmux-fork-focused-codex --dry-run --preflight-fork\ncmux-xport\n```\n\nPreserve this route:\n\n```text\nfocused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c\n```\n\n## Failure Paths To Preserve\n\nInvalid workspace handle:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nWrong session fork:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nMissing export:\n\n```bash\nls -lt .exports | head\n```\n\nFunction not found:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\n```\n\n## Boundaries\n\nSection 3 is about helper names and zsh runtime shape. Section 4 is about where those helpers run.\n\n| Section 3 | Section 4 |\n| --- | --- |\n| Is this a function, alias, or executable? | Which pane/surface/session does it target? |\n| `whence -w` | `cmux identify` |\n| `type`, `functions`, `funcwhere` | `workspace.current`, `pane.surfaces` |\n| zsh helper loading | cmux socket routing |\n| executable fallbacks | new panes, focused session forks, exports |\n\nSection 5 builds the preflight prompt before a routed fork runs.\n\n## Further References\n\n- team member cheatsheet: `cheatsheets/04-agentic-dev-environment-orchestrator.md`\n- Exercises: `exercises/04-agentic-dev-environment-orchestrator.md`\n- tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html\n- tmux GitHub wiki: https://github.com/tmux/tmux/wiki\n- OpenAI Codex: https://openai.com/codex/\n- Model Context Protocol: https://modelcontextprotocol.io/\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
    }
  ]
}
