Record accumulated architecture and agent-writing guidance

.agents/agent-writing.md

@@ -0,0 +1,76 @@
+# Writing for agents
+
+These approved rules govern guides and instructions written for agents,
+including initial prompts and on-demand reference chapters. They supplement
+the general Writing Guide in `AGENTS.md` and the
+[product-interface rules](product-interface.md).
+
+Optimize each guide for helping the agent take the next correct action. Keep
+the writing human-readable so people can review what the agent is taught.
+
+## Approved rules
+
+1. Lead with when to read the guide and what action it enables.
+2. State whether instructions apply to Sidekick responses, REPL entries or both.
+3. Give direct instructions explaining what to write, under which conditions and what happens.
+4. Show complete, safe-to-copy examples with required bindings and expected results.
+5. Pair consequential, likely mistakes with the correct alternative and its practical consequence.
+6. Keep one coherent topic per guide and name prerequisite and deeper guides using their exact component invocation.
+7. Separate stable rules from current facts and obtain actual paths, capabilities and settings through inspection.
+8. Use consistent terminology and ground component syntax in its authoritative reference.
+
+## Common guide format
+
+Use predictable Markdown sections in this order:
+
+- **Title and opening:** when to read the guide and what it enables.
+- **Applies to:** the execution contexts covered.
+- **Instructions:** the actions and conditions needed to use the topic.
+- **Example:** complete source followed by its expected result.
+- **Common mistake:** a consequential trap and the correct alternative.
+- **Read next:** exact invocations for related guides.
+
+Omit optional sections when they add no useful information. A guide is useful
+when an unfamiliar agent can discover it and perform the intended task
+correctly with the documented initial context.
+
+## Example guide excerpt
+
+This excerpt illustrates the writing format for the Sidekick bindings chapter;
+component availability is determined by the active syntax reference.
+
+````markdown
+# Bindings
+
+Read this before using values created by earlier REPL entries.
+
+## Applies to
+
+Sidekick responses and the root bindings inherited by REPL entries.
+
+## Instructions
+
+- Read current published values with REPL.Bindings.
+- Use returned binding names in entry source when appropriate.
+- Each Sidekick response starts with an empty binding environment.
+- Feedback does not automatically create response bindings.
+
+## Example
+
+```xmd
+<REPL.Bindings />
+```
+
+The host returns a JSON map of published binding names and values
+as feedback, then requests your next response.
+
+## Common mistake
+
+Receiving a binding named names does not make {names} available
+in your next Sidekick response. It can be referenced inside an
+entry that inherits that binding.
+
+## Read next
+
+Read <Guide.Recovery /> when continuing interrupted work.
+````

.agents/architect.md

@@ -146,6 +146,8 @@ concept to explain itself.
 ## Communication rules
 
 1. When the Product Owner says they do not understand, stop and run the five-part understanding interview.
+2. Before proposing a new abstraction, show the concrete problem, why existing APIs cannot solve it, and what decision requires the Product Owner.
+3. Explain behavior with familiar words and a concrete example before introducing technical terms; use only terms needed for the current decision.
 
 When the Product Owner says they do not understand, stop the current design
 discussion and run this interview before continuing:

.agents/architecture-rules.md

@@ -28,6 +28,7 @@ the system itself; this file governs how new architecture is designed.
 19. Renderer output is copied out of the engine before returning, and a refused frame is redrawn on a renderer rebuilt for that frame's dimensions without changing selection, focus, actions or the frame itself.
 20. A contextual adapter owns terminal modes, listeners and readers, registers their release before taking them, and restores them exactly once on every exit.
 21. A narrow surface displays the one route selected; every other surface is absent from the frame, its map and its targets rather than hidden within them.
+22. Never mutate `next` or attach metadata to it; keep the continuation callable unchanged.
 23. Use methods on an owned handle for operations tied to that instance.
 24. Use a Context to select a scoped service; capture it for any lifetime that requires a fixed provider.
 25. Use middleware when per-call interception or transformation is an intended extension point.

.agents/planner.md

@@ -166,3 +166,26 @@ End every planning handoff with the exact base, produced artifact paths,
 settled decisions, unresolved blockers and the next Implementor action. An
 implementation review records the exact reviewed SHA and the focused commands
 it rests on.
+
+When passing a sequence of changes to a new Planner, carry the context of the
+whole sequence, including prerequisites and parallel work. The handoff includes
+a self-contained snapshot of:
+
+- the overall outcome and why the work is split;
+- every delivery's purpose, status, dependencies and remaining scope;
+- landed PRs and exact merge commits, the verified current base, and any
+  difference between reviewed revisions and published or merged revisions;
+- accepted product and architecture decisions that constrain later deliveries,
+  including superseded approaches that must not return;
+- parallel tracks, their overlap, owners or known assignment status, and their
+  governing plans;
+- unresolved decisions, preserved worktrees and evidence, and the exact next
+  action and authorization boundary.
+
+Maintain a shared sequence record and link its governing plans and reviews.
+Include the concise sequence snapshot in the new handoff itself; do not rely
+on conversation history or a chain of earlier handoffs to supply it. Separate
+verified facts from reported or unknown status and mark historical snapshots.
+The receiving Planner refreshes the record against current evidence and carries
+it forward again at the next Planner transition. Planning one delivery does
+not silently discard the dependencies or accepted decisions of the others.

.agents/product-interface.md

@@ -9,6 +9,9 @@ shape the product's output.
 Component descriptions also follow the specialized additions in
 [component-descriptions.md](component-descriptions.md).
 
+Guides and instructions written for agents also follow
+[agent-writing.md](agent-writing.md).
+
 ## Approved rules
 
 1. Design public XMD interfaces so people understand what to write, what will happen, what it affects and what they receive.

AGENTS.md

@@ -489,6 +489,8 @@ the corpus or enabling in-shard concurrency is not an answer to a miss.
 
 ## Writing Guide
 
+In Codex, always use ASCII diagrams in fenced text blocks; Mermaid diagrams are not readable in the user's client.
+
 1. Write for the reader's understanding, not as a transcript of the reasoning
    that produced the design. Preserve conclusions, contracts, and consequential
    constraints. Include rationale only when a surprising decision would
@@ -512,6 +514,12 @@ Avoid words in the canonical [banned-words list](scripts/banned-words.js) when
 writing architecture prose or JSDoc. Choose wording for the specific meaning;
 keep literal code references intact. `deno task lint` enforces the list.
 
+### Writing for agents
+
+Before writing or changing agent-facing guides or instructions, read
+[the writing-for-agents rules](.agents/agent-writing.md). Use its approved rules
+and common guide format for initial prompts and on-demand reference chapters.
+
 ### Component descriptions
 
 Write a component description for an author deciding what to type. Lead with an

architecture.md

@@ -68,8 +68,9 @@ Determinism is two properties:
 - **Behavioral predictability** — a key product feature: generate a plan as a
   program where ~80% is deterministic and ~20% is probabilistic.
 - **Replay determinism** — the journal doesn't lose the execution chain:
-  replaying the journal arrives at the same state, where execution can
-  continue.
+  replaying the journal restores the recorded execution state, where execution
+  can continue. Whether the live environment matches that state is a separate
+  host contract.
 
 ### State ownership
 
@@ -6069,6 +6070,36 @@ than a test fixture's list of components: adding a component cannot make
 validation effectful.
 
 
+## REPL execution model
+
+The REPL is a foreground interactive environment for experimenting with and
+testing components. It assumes a user or agent is available to inspect what
+happened, orient to the current environment and adjust the script for further
+work. Workflows supply the persistence and recovery contracts for background
+automation.
+
+Replay fast-forwards execution through the retained history to its latest
+recorded state. Recorded results restore execution values and progress without
+re-executing the effects that produced them. Once that history is consumed, new
+work acts on the live environment.
+
+The recorded execution state and the live environment may disagree. The REPL
+accepts that disconnect: replay neither restores the environment nor requires
+it to match historical results before continuing. Environmental mismatch alone
+does not justify repeating a completed effect or blocking continuation. The
+user or agent addresses the mismatch through inspection, orientation and
+changes to subsequent work.
+
+For example, an entry writes `A` to a file and records the result. The user then
+changes the file to `B`. Replay returns the recorded write result without
+writing `A` again; the file remains `B`. A subsequent new operation observes
+and acts on `B`.
+
+This execution model retains journal integrity, configured permissions, entry
+ownership and external-effect reconciliation. Workflow-specific environmental
+validation and recovery belong to the workflow host; REPL history alone creates
+no requirement to snapshot, validate or recover an entire checkout.
+
 ## The private REPL composition kernel
 
 `packages/cli/src/repl/` is a private CLI feature, not a package boundary and
@@ -8115,10 +8146,15 @@ and categorization rather than clarify them, so both stay exactly as written.
 | Term | Meaning |
 | --- | --- |
 | behavioral predictability | a plan as a program: ~80% deterministic, ~20% probabilistic [Reference](#three-axes). |
-| replay determinism | the journal doesn't lose the execution chain: replaying arrives at the same state, where execution can continue [Reference](#three-axes). |
+| replay determinism | the journal preserves the execution chain: replay restores the recorded execution state from which execution can continue; correspondence with the live environment is a separate host contract [Reference](#three-axes). |
 | replay | using the durable journal to restore the recorded portion of a document execution without repeating durable effects; after the recorded entries are consumed, execution may continue live [Reference](#replay-and-effect-transactions). |
 | divergence | reserved for replay: a replay that departs from the recorded journal [Reference](#replay-and-effect-transactions). |
+| foreground execution | interactive work designed around the available attention of a user or agent, who inspects the environment, addresses mismatches and adjusts subsequent work |
+| background automation | work designed to proceed without ongoing user or agent attention, with its persistence and recovery guarantees supplied by the workflow host |
+| REPL | the foreground interactive environment for experimenting with and testing components; replay restores recorded execution state, while the user or agent handles differences between that state and the live environment |
 | REPL history | the immutable ordered execution records the REPL reads from the durable journal and projects into `ReplModel`; the History surface presents this read model and is not itself a journal [Reference](#the-private-repl-composition-kernel). |
+| message ID | the number Sidekick retains to identify a saved person message within its conversation; fixed once saved, possibly noncontiguous, and independent of the turn numbers recorded by Core. The conversation and message ID together form its lookup key |
+| turn | one request to an agent, together with the response or failure from that request |
 | middleware | applied by the lexical structure, used by runtime execution [Reference](#two-layers). |
 | workflow run | a workflow being carried out with its progress and outcome recorded durably; document executions perform its work, while ongoing effects remain scoped to the document execution in which they run [Reference](#workflow-runs). |
 | document execution | one evaluation of a root document initiated through `execute()`, producing one output stream and one completion result while reading and appending a durable journal; its ongoing effects belong to the Effection scope in which the evaluation runs [Reference](#workflow-runs). |
@@ -8202,9 +8238,9 @@ and categorization rather than clarify them, so both stay exactly as written.
 | trusted host | the code that decides what an execution is for — a CLI entrypoint or a workflow runner — as distinct from the document, the components it expands, and the middleware packages composed around it [Reference](#trusted-host-orchestration). |
 | native session launch | Construction and ownership handoff of one durable session to its provider-native interactive UI. [Owning rule](#native-agent-sessions). |
 | provider-native session identity | The provider conversation identity, distinct from XMD and ACP identifiers [Full contract](#native-agent-sessions). |
-| pending session placement | One operation-local placement before its first consumer constructs a session [Full contract](#native-agent-sessions). |
-| session materialization | The backend acceptance that makes a new conversation available to native resume [Full contract](#native-agent-sessions). |
-| established session | An immutable route and asserted conversation identity [Full contract](#native-agent-sessions). |
+| agent session | The session is created when it is first used. [Full contract](#native-agent-sessions). |
+| session creation | Creating the provider session so it can be reopened. [Full contract](#native-agent-sessions). |
+| existing session | An agent session that has already been created. [Full contract](#native-agent-sessions). |
 | instruction layer | Provider-native instructions installed before user content [Full contract](#native-agent-sessions). |
 | foreground-terminal lease | The exclusive execution-owned right to inherit the foreground terminal [Full contract](#native-agent-sessions). |
 | native launcher | The host adapter that launches a provider UI and reports only its status [Full contract](#native-agent-sessions). |