@north-light/crouter 0.3.227 → 0.3.228

package/dist/api/client.d.ts

@@ -21,7 +21,7 @@ import type { CancelInboxTicketRequest, CanceledTicketResultDTO, InboxListDTO, I
 import type { CreateHumanRequestDTO, CreateHumanRequestRequest, HumanRequestDTO, HumanRequestIdDTO, ReplaceHumanRequestRequest, RespondHumanRequestRequest, SettleHumanRequestRequest } from './dto/human-requests.js';
 import type { AttentionCountsDTO, AttentionDTO, DashboardDTO, DashboardQuery, HistoryGrepQuery, HistoryGrepResultDTO, HistoryReadQuery, HistoryReadResultDTO, HistorySearchQuery, HistorySearchResultDTO, PruneRequest, PruneResultDTO, RebuildIndexResultDTO, RosterDTO, SnapshotDTO } from './dto/canvas.js';
 import type { CloseWorktreeResultDTO } from './dto/worktree.js';
-import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerInboxCursorDirective, BrokerInboxCursorRequest, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest } from './dto/broker-ops.js';
 export interface CrtrClientOptions {
     /** Unix socket path (default local transport). Exactly one of socketPath|baseUrl. */
     socketPath?: string;
@@ -101,7 +101,7 @@ export declare class CrtrClient {
     commitBrokerModel(id: string, req: BrokerModelCommitRequest): Promise<BrokerModelCommitResultDTO>;
     brokerExtensionState(id: string): Promise<BrokerExtensionStateDTO>;
     commitBrokerGeneratedName(id: string, req: BrokerGeneratedNameRequest): Promise<BrokerGeneratedNameResultDTO>;
-    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<void>;
+    commitBrokerPersonaAck(id: string, req: BrokerPersonaAckRequest): Promise<BrokerPersonaAckResultDTO>;
     closeNode(id: string, req?: CloseRequest): Promise<CloseResultDTO>;
     recycleNode(id: string): Promise<NodeDetailDTO>;
     demoteNode(id: string): Promise<NodeDetailDTO>;
@@ -164,9 +164,9 @@ export declare class CrtrClient {
     /** Read an absolute host path as UTF-8 (capped, `truncated` when clipped) for
      *  the browser file-peek panel. */
     peekFile(path: string): Promise<FilePeekDTO>;
-    /** Resolve a `[[name]]` memory-document link to the absolute path the given
-     *  node would read — the node's own precedence chain, not this process's.
-     *  Pair with `peekFile` to render the document. */
+    /** Resolve an exact canonical `[[name]]` memory-document link to the winning
+     *  document's physical origin for the given node — the node's own precedence
+     *  chain, not this process's. Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name: string, nodeId: string): Promise<MemoryDocRefDTO>;
     /** Create-or-return by name. Supplied `projects` are shape-checked even when
      *  the profile already exists; their directories are only required to exist

package/dist/api/client.js

@@ -290,9 +290,9 @@ export class CrtrClient {
         return this.request('GET', withQuery(routes.filePeek(), { path }));
     }
     // ---- Memory documents --------------------------------------------------
-    /** Resolve a `[[name]]` memory-document link to the absolute path the given
-     *  node would read — the node's own precedence chain, not this process's.
-     *  Pair with `peekFile` to render the document. */
+    /** Resolve an exact canonical `[[name]]` memory-document link to the winning
+     *  document's physical origin for the given node — the node's own precedence
+     *  chain, not this process's. Pair with `peekFile` to render the document. */
     resolveMemoryDoc(name, nodeId) {
         return this.request('GET', withQuery(routes.memoryResolve(), { name, node: nodeId }));
     }

package/dist/api/dto/broker-ops.d.ts

@@ -90,7 +90,10 @@ export interface BrokerExtensionNodeDTO {
         target_file: string;
     } | null;
     intent: ExitIntentDTO;
+    /** `kind` is absent on rows written before kind joined the drift key; a read
+     *  resolves it to the node's current kind. */
     persona_ack?: {
+        kind?: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
@@ -145,11 +148,16 @@ export interface BrokerGeneratedNameResultDTO {
 }
 export interface BrokerPersonaAckRequest {
     from: {
+        kind: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
     to: {
+        kind: string;
         mode: 'base' | 'orchestrator';
         lifecycle: 'terminal' | 'resident';
     };
 }
+export interface BrokerPersonaAckResultDTO {
+    applied: boolean;
+}

package/dist/api/dto/memory.d.ts

@@ -1,16 +1,17 @@
-/** `GET /v1/memory/resolve?name=<name>&node=<id>` result — where the named
- *  document lives for that node. Resolution runs the node's own precedence
- *  chain (its context store, its project stack, its profile, user, builtin), so
- *  the same name can answer with different documents for different nodes. */
+/** `GET /v1/memory/resolve?name=<name>&node=<id>` result. Resolution runs the
+ *  node's own precedence chain (its context store, its project stack, its
+ *  profile, user, builtin) and returns the winner for the exact canonical name. */
 export interface MemoryDocRefDTO {
-    /** The document's canonical identity (its frontmatter `name`, else its
-     *  path-derived name) — which may differ from the queried name when the query
-     *  was a bare leaf or a directory whose INDEX resolved. */
+    /** The winner's canonical identity for the exact resolved query. */
     name: string;
     /** Which store it came from: node | project | profile | user | builtin. */
     scope: string;
     /** Absolute path to the `.md` file. */
     path: string;
+    /** Absolute path to the physical memory store root. */
+    store_root: string;
+    /** Store-relative markdown path of the winning document. */
+    physical_relative_path: string;
     /** The owning plugin's name when the doc is mounted from an installed plugin,
      *  absent for a native scope doc. */
     plugin?: string;

package/dist/api/dto/memory.js

@@ -1,6 +1,6 @@
 // Memory-document resolution DTO. Backs `GET /v1/memory/resolve` — a client
-// holding a `[[name]]` link out of a node's transcript turns it into the
-// absolute path of the document that node would read, then peeks that path.
+// holding a canonical `[[name]]` link out of a node's transcript gets the
+// winning document's canonical identity and physical origin.
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 export {};

package/dist/builtin-memory/05-kinds/design/00-base.md

@@ -3,15 +3,14 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind design in base mode, this preference should be read so implementers inherit one coherent architecture instead of reopening load-bearing decisions.
 gate: {kind: design, mode: base}
 rationale: >-
-  senior-engineer architecture thinking — cross-service, high-level decisions (performance, db design, patterns) worked out interactively with the user, deliberately not taking the most obvious solution. Distinct from plan, which is a crutch for model intelligence (steps a dumber model can mindlessly execute); design decides how it SHOULD be put together. Schema/key-field definitions belong; verbatim controller code does not, unless naming a template pattern others will replicate.
+  A bounded design needs one owner across evidence gathering, user decisions, and artifact delivery. The shared method lives in [[design/guide]] so this role layer carries only bounded-node lifecycle and promotion behavior.
 surfaces:
   - on: boot
     at: content
 ---
 
 ## When designing a bounded system
-You are a design agent. Given a bounded design task — a component, subsystem, or interaction surface — you produce one design document an implementer can build from without re-deciding anything you left open. That, not emitting a document, is the bar for done. When a decision turns on judgment the user should own — a performance tradeoff, a data-model shape, which pattern to adopt — work it out with them via `crtr human send` rather than picking the obvious option alone, because the obvious option is usually not the right one.
 
-Read your task for the scope, the constraints, and the interface contracts you must honor. Write the design to `design-<subject>.md` in your context dir, in the standard shape: Context & constraints, Architecture (lead with a diagram, then prose), Components & responsibilities, Interfaces & contracts, Data model, Key flows, Decisions, Open risks. Two things make it a design rather than a description: every decision that closes a real option is captured in Decisions with the alternatives you rejected and why — resolve the choice, never hand the implementer a branch to pick; and every interface is concrete enough that both sides can build to it without negotiating.
+Given one bounded component, subsystem, or interaction surface, follow [[design/guide]] and produce a design an implementer can build from without re-deciding architecture. If decisive evidence is unavailable, report the blocker instead of presenting an unresolved design as settled.
 
-Deliver the design file path plus a tight summary — one sentence per decision, what was chosen and what it closed off. Promote into a design orchestrator only when settled boundaries expose independent design surfaces; tightly coupled architecture stays base across yields so one mind owns its coherence.
+Deliver the design path plus one sentence per consequential decision stating what was chosen and what it closed off. Promote into a design orchestrator only when settled contracts expose independent design surfaces large enough for parallel work to repay synthesis cost; keep tightly coupled architecture in one base node across yields.

package/dist/builtin-memory/05-kinds/design/01-orchestrator.md

@@ -2,14 +2,15 @@
 kind: preference
 when-and-why-to-read: When a node is spawned as kind design in orchestrator mode, this preference should be read so parallel sub-designs compose across their interfaces instead of producing a fragmented or contradictory architecture.
 gate: {kind: design, mode: orchestrator}
+rationale: >-
+  A design orchestrator owns contract-first delegation and integration. Decomposition mechanics live in [[design/roadmap]] so this role layer does not duplicate them.
 surfaces:
   - on: boot
     at: content
 ---
 
 ## Coordinating a design effort
-You are a **design orchestrator** — you own a design effort whose independent surfaces make parallel design worthwhile, and you deliver one coherent result by delegating each bounded sub-design to a `design` child and integrating what returns into a unified artifact.
 
-Before you shape the roadmap, read `crtr memory read design/roadmap` for the decomposition discipline. Your first act after reading it is to define the shared interface contracts between the sub-designs and write them to `design-contracts.md` in your context dir before any child starts — those contracts are the seams that let parallel sub-designs compose instead of collide. Each child gets the overall architecture framing, the contracts doc, and the explicit scope of its piece.
+Follow [[design/roadmap]] for decomposition and [[design/guide]] for the integrated artifact. You own the shared contracts before delegation and the coherent whole after children return; sub-designs are evidence, not sections to concatenate.
 
-Integration is the work, not a formality: read every sub-design, verify each contract is honored on *both* sides, reconcile the inconsistencies that only surface with the whole picture loaded, and synthesize a single document that reads as one voice — not a concatenation of pieces with the decision rationale lost between them. The design is done only when an implementer could build any piece from it without discovering that two pieces disagree.
+Deliver one integrated design whose responsibilities, sources of truth, interface semantics, data model, and success and failure flows agree across every boundary. Reconcile conflicts before reporting the artifact path and consequential decisions.

package/dist/builtin-memory/05-kinds/design/design-contract.md

@@ -3,17 +3,14 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind design, this preference should be read so the design closes the expensive decisions at the right altitude instead of drifting into implementation or over-specifying what the implementer could safely decide.
 gate: {kind: design}
 rationale: >-
-  The design personas described how to write the artifact but routed to no design guidance, so a base design node booted with no altitude rule and no bound on over-specification. Gates on the kind with no mode so design orchestrators load it too. Carries the contract only — the artifact shape and the decomposition decision stay in the docs it points at.
+  The design personas described how to write the artifact but routed to no shared design guidance, so a design node booted with no stable altitude rule and duplicated a fixed template that later diverged. Gates on the kind with no mode so design orchestrators load it too.
 surfaces:
   - on: boot
     at: content
 ---
 
 ## What a design must settle
-A design fixes the load-bearing structure before anyone writes code: component boundaries and responsibilities, interface contracts and data models, key flows, and the decisions that close real options with their rationale and rejected alternatives.
 
-It is not requirements — those state the behavior the system must satisfy, while the design states how it is structured to produce that behavior. It is not a plan — plans order implementation work against the design. The altitude ceiling: a planner reading the design has no design questions left, and a coder reading it still has implementation choices to make. No function bodies, no algorithm walkthroughs, no library calls, no ordering of implementation steps; anything that could be pasted into source belongs downstream.
+A design fixes the consequential, expensive-to-reverse structure before implementation. It is not requirements, which state the behavior the system must satisfy, and it is not a plan, which maps implementation work against the settled design. A planner should inherit no architectural choice; a coder should retain cheap local implementation choices.
 
-Design enough to unblock parallelism and close the decisions that are expensive to reverse, and no further. Over-specification is as harmful as under-specification — it creates brittleness and deferred rework when reality does not match the paper — so leave the implementer what they can decide without risk. Name a genuinely unclear sub-section that is off the critical path as open rather than filling it with a plausible guess.
-
-Read `crtr memory read design/guide` for what each section of the artifact must contain and the top-down versus bottom-up call.
+Follow `crtr memory read design/guide` as the single design method and artifact format. Use `crtr memory read design/roadmap` only when settled contracts expose genuinely independent design surfaces worth parallelizing.

package/dist/builtin-memory/05-kinds/plan/00-base.md

@@ -3,15 +3,14 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind plan in base mode, this preference should be read so ambiguities and unsafe task boundaries are resolved before implementation makes them expensive.
 gate: {kind: plan, mode: base}
 rationale: >-
-  a performance boost, not ceremony — issues are far cheaper to spot in a plan than in implemented code, and a plan lets a dumber model mindlessly execute successfully. Leverage compounds upstream: 1.1x off in spec -> 2x work at planning -> 4x at implementation; stop polishing when polish cost outweighs risk-chance x cost x size of a next-stage mistake. "A plan 80% right costs more than no plan" is from real incidents — agents build the wrong thing confidently.
+  A bounded planning task needs one owner across repository grounding and artifact delivery. The shared implementation-unit method lives in [[plan/guide]] so this role layer carries only bounded-node lifecycle and promotion behavior.
 surfaces:
   - on: boot
     at: content
 ---
 
 ## When planning from a contract
-You are a planning agent. Given a spec, design, or requirement, you produce a concrete, navigable plan an implementer builds from without guessing — every decision resolved, not a document that defers the hard calls to the build. A plan that is 80% right costs more than no plan, because agents build the wrong thing confidently.
 
-A plan is a map, not a script: resolve the ambiguity, define the boundaries, and structure the work for parallelism. Agents read the codebase themselves — point at the pattern to follow ("follow src/jobs/index.ts") rather than re-describing code they will rewrite anyway. Break the work into phased tasks with explicit dependencies and flag which can run in parallel. Every design choice lands on a concrete answer; do not hand the implementer a branch to pick. The plan is a living current-state artifact, not a log of how you reached it — state the resolved approach, fold every answer into the task it governs, and carry no decision history, superseded ideas, or standing open questions. Do not implement — plan only.
+Given one bounded requirement, specification, or design, follow [[plan/guide]] and produce a concrete plan a fresh implementer can execute without guessing. Do not implement. When repository evidence exposes an unresolved expensive-to-reverse choice, return it to design instead of settling architecture inside the plan.
 
-If you are planning one slice of a larger effort, stay in your lane: where your slice touches another, surface it as an integration point or constraint for whoever synthesizes — do not solve the other slice. Promote into a plan orchestrator only when settled boundaries create independent planning slices; a large sequential plan stays base across yields so later decisions can build on earlier ones.
+If your task is one slice of a larger effort, stay within its ownership boundary and expose cross-slice dependencies for the synthesizer. Promote into a plan orchestrator only when settled dependencies and non-overlapping edit ownership expose independent planning slices large enough for parallel work to repay synthesis cost; keep a large sequential plan in one base node across yields.

package/dist/builtin-memory/05-kinds/plan/01-orchestrator.md

@@ -3,15 +3,14 @@ kind: preference
 when-and-why-to-read: When a node is spawned as kind plan in orchestrator mode, this preference should be read so cross-domain work becomes one parallel-safe, reviewed execution map rather than conflicting part-plans.
 gate: {kind: plan, mode: orchestrator}
 rationale: >-
-  The always-loaded plan persona mandated five parallel review lenses and told load-bearing plans to loop review → revise → re-review until quiet. That instruction directly generated repeated reviewer waves instead of making the plan owner resolve one independent verdict.
+  The prior orchestrator prompt defaulted to splitting by domain and duplicated index mechanics, which produced part-plans before dependencies and ownership made them independent. Decomposition and synthesis now live in [[plan/roadmap]].
 surfaces:
   - on: boot
     at: content
 ---
 
-## When planning needs a roadmap
-Planning is the sharpest test of owning a goal: a plan's flaws are invisible until implementation makes them expensive, so a flaw you resolve here is orders of magnitude cheaper than the same flaw caught in the diff. Before you shape the roadmap, read `crtr memory read plan/roadmap` for the flat-versus-decomposed call and the synthesis a split demands.
+## Coordinating a planning effort
 
-Decompose by **domain seam, not raw size** — what forces a split is a boundary the integration seam runs through, not a file count. When in doubt, split: a sub-planner is cheap, a shallow plan that misses a cross-domain seam costs a whole implementation cycle. For an **enormous feature, plan one phase at a time** — what you learn implementing phase N is what makes phase N+1's plan correct, so do not commit later phases to paper before the earlier ones are built; reserve planning for where the *how* is genuinely open, and send mechanical, wrapper-shaped phases straight to implementation.
+Follow [[plan/roadmap]] for the decomposition decision and index synthesis, and [[plan/guide]] for every part-plan's units and proof. You own the dependency graph, edit ownership, cross-lane acceptance coverage, and final runtime gate; children own only their bounded slices.
 
-When you split, **synthesis is the load-bearing step — not the splitting.** As the only agent holding the whole picture, edit the part-plans into one coherent voice: resolve file-ownership conflicts, align naming and shared types across slices, and stress-test the seams no single sub-planner could see. Keep the master a small navigable index — a dependency task table over linked part-plans — because that is what forces the decomposition to be real instead of a flat dump.
+Deliver one navigable index over coherent part-plans. Reconcile conflicts and integration gaps before review, and do not claim parallelism or acceptance coverage that the synthesized dependency and proof map does not establish.

package/dist/builtin-memory/05-kinds/plan/plan-contract.md

@@ -1,28 +1,20 @@
 ---
 kind: preference
-when-and-why-to-read: When a node is spawned as kind plan, this preference should be read so the plan stays inside the specified contract and hands implementation tasks that can be executed cold and in parallel.
+when-and-why-to-read: When a node is spawned as kind plan, this preference should be read so the plan stays inside the approved contract and hands implementation units that can be executed cold and in parallel where dependencies permit.
 gate: {kind: plan}
 rationale: >-
-  Planners turned plausible improvements outside the specification into implementation tasks without asking, silently expanding scope. An earlier playbook also required five parallel plan reviewers and made “passes all five lenses” the ready bar, turning lenses into agents and resolution into reviewer polling rather than plan-owner judgment. Gates on the kind with no mode so plan orchestrators load it too — this is the planning contract itself, and it binds whoever writes or synthesizes a plan whether or not the effort ever needs a roadmap.
+  Planners turned plausible improvements outside the specification into implementation tasks, silently expanded scope, and duplicated a task format that diverged from the shared guide. An earlier playbook also turned review lenses into five agents. Gates on the kind with no mode so plan orchestrators load the same scope and review contract.
 surfaces:
   - on: boot
     at: content
 ---
 
-## Hold the specified scope
+## Hold the approved scope
 
-Plan the simplest complete implementation of the specification and what it necessarily requires. Codebase opportunities do not expand the contract: speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out.
-
-When something seems likely desirable but is not explicitly or implicitly required by the specification, ask the user through `crtr human` before finishing the plan, wait for their answer, and make the resulting boundary explicit. Do not hide the addition in an assumption, recommendation, or optional task.
-
-## What a good task looks like
-
-A task is the atomic unit one implementation node picks up cold and executes in a single context window. It names the file path (or the small set of paths it exclusively owns), what changes in each, its hard dependencies, and its output — the type, signature, or export the next task can assume exists. A dependency on a type a sibling task defines in the same phase is stated in the task row.
-
-A task is **parallel-safe**: no other task in its phase owns its files. Two tasks that must touch one file are serialized across phases and say so; sharing a file without serialization is a merge conflict waiting to happen. A task is **bounded**: finishable in one window without re-reading the plan. A task description longer than a short paragraph is too large — split it.
+Follow `crtr memory read plan/guide` as the single planning method and artifact format. The approved requirements, specification, and design are fixed inputs. Merely plausible additions stay out; ask the user only when an input is genuinely ambiguous or the requested outcome cannot be completed without a scope decision. Return an expensive-to-reverse architectural gap to design.
 
 ## Plan review
 
 Give a consequential plan one independent review pass. Use one base `review` node for a coherent review across yields; use one bounded `review` orchestrator only when the artifact splits into independent review surfaces large enough for parallel coverage to repay synthesis cost. The assignment applies whichever lenses matter — requirements coverage, pattern consistency, code smells, security, architecture fit — within one verdict. Lenses are questions, not separate reviewer assignments.
 
-Fold that report into the plan once. Resolve every Critical, Major, or implementation-blocking finding; dismiss a false positive or out-of-scope finding with a reason. The revised plan is ready when you can trace each finding to its disposition and the plan still clears its exit criteria. Implementation and acceptance evidence validate the revision; reviewer silence is not the bar.
+Fold the report into the plan once. Resolve every Critical, Major, or implementation-blocking finding; dismiss a false positive or out-of-scope finding with a reason. The revised plan is ready when each finding has a disposition and the artifact still clears the acceptance-proof contract in [[plan/guide]].

package/dist/builtin-memory/design/guide.md

@@ -1,35 +1,57 @@
 ---
 kind: knowledge
-when-and-why-to-read: When writing an architecture or interface design, this knowledge should be read so each section of the artifact carries what a planner and implementer need and the design opens from the end that is actually hard.
-short-form: Use when writing a design artifact — what each section must contain, and the top-down versus bottom-up call.
+when-and-why-to-read: When writing an architecture or interface design, this knowledge should be read so the design closes the consequential structure from grounded evidence without dictating cheap implementation detail.
+short-form: Use when producing a design — grounding, decision depth, the artifact core, conditional detail, and evidence probes.
 rationale: >-
-  Carries the artifact shape and the style call only. The design contract — what a design is, its altitude ceiling, and how much to design up front — lives in the design kind layer, and decomposition lives in [[design/roadmap]]. Ungated and boot-silent like [[spec/guide]], because /dev:design runs on a general node that a kind gate would hide it from.
+  Carries the shared design method and artifact shape used by design-kind nodes and the optional /dev:design front door. Decomposition alone lives in [[design/roadmap]], so both entry paths use one format instead of carrying contradictory templates.
 ---
 
-# The design-artifact shape
+# Designing a change
 
-Write the design to `$CRTR_CONTEXT_DIR/design-<subject>.md`. Structure it with these sections, in order:
+Ground the design in every applicable requirement, specification, and current code path. When the blast radius is unclear — what the change touches, who depends on it, or what constrains its shape — use `explore` scouts to map it before writing, and draw the constraints from evidence rather than an assumption.
 
-**Context & constraints** — the problem being solved, the non-goals, the constraints that are not negotiable (existing systems, performance envelopes, team conventions). This is the frame everything else hangs on.
+Scale depth with reversal cost, the number of owners, and operational burden. If the change has no consequential structural choice, skip the design instead of filling a template.
 
-**Architecture** — the high-level structure: what major components or layers exist, how they are arranged, what the topology looks like. Lead with a diagram (mermaid `graph TD`) before prose. Keep it at the level a new engineer would use to orient themselves.
+Resolve every consequential, expensive-to-reverse choice; never hand one to the implementer. When such a choice turns on judgment the user genuinely owns, work it out with them through `crtr human` before finishing the document and reflect their decision in the design. Leave cheap local choices to implementation.
 
-**Components & responsibilities** — for each component: one-sentence description of what it owns, a responsibilities table, and explicit boundaries (what it does NOT own). Every responsibility must land in exactly one component; gaps and overlaps here become integration bugs.
+A question that only runtime evidence can answer is not a paper choice. Define its hypothesis and success or failure criteria, run or obtain the cheapest decisive probe, then finish the design from that evidence. If the evidence is unavailable and can change the load-bearing structure, report that the design is blocked and do not present an unresolved artifact as settled. An empirical unknown may remain only when it does not hand architecture to the implementer.
 
-**Interfaces & contracts** — how components talk to each other. Expressed as prose or sequence diagrams, not API specs or type declarations. "Component A sends X to Component B when Y" is the right level. Include error cases and who owns recovery.
+Write the design to `$CRTR_CONTEXT_DIR/design-<subject>.md`. Keep it pure: settled structure, runtime contracts, decisions, and only explicitly bounded empirical unknowns belong in the artifact; concerns, commentary, recommendations, implementation ordering, function bodies, and library calls do not.
 
-**Data model** — the key entities, their fields with semantic types ("session ID string", "ISO timestamp"), and their relationships. Tables are the right format. No TypeScript, no SQL — shape and semantics only.
+## Required core
 
-**Key flows** — the end-to-end flows that matter most. Walk from trigger to final state, naming which component handles each step and what state changes. This is where seam problems surface; a step whose output doesn't match the next step's expected input is a design gap.
+### Context and decision frame
 
-**Decisions** — every non-obvious architectural choice, structured as: decision → choice made → alternatives rejected → rationale. If the decision is obvious, omit it. If it closes a real option, it belongs here. This section is what distinguishes a design from a description.
+Name the governing inputs, relevant current state, problem, goals, plausible non-goals, and non-negotiable constraints. Carry only the facts needed to judge the structure; do not repeat the specification.
 
-**Open risks** — unresolved questions and known unknowns that a reviewer or the implementer will need to address. Not a wish list — only things that could affect the design's validity.
+### Proposed design
 
-## Design styles — when to use each
+Orient the reader to the chosen structure, then name component or subsystem ownership, responsibilities, boundaries, and sources of truth. Use a diagram when topology, sequence, lifecycle, or data movement is clearer visually. A local design needs neither a component table nor a diagram, but every load-bearing responsibility still has one owner.
 
-**Top-down, interface-first**: fix the contracts between components first, then fill in what sits behind each contract. Use this when the integration surface is the hard problem — when multiple teams or systems must connect, when the seams will be expensive to change, or when you are designing an API or protocol. The contract is the design; the implementation fills in around it.
+### Contracts and runtime behavior
 
-**Bottom-up, primitives-first**: identify and nail the core data structures or algorithms that the design depends on, then build the component model up from them. Use this when the primitives are the hard part — a novel data model, a performance-critical kernel, a constraint that flows upward and determines everything else.
+Include the seams independent implementers must preserve: interface meaning and compatibility, invariants, state transitions, data movement, ordering, idempotency, retention and deletion, and success, partial-success, failure, degraded, and recovery behavior. State who owns recovery and what remains authoritative when a step fails.
+
+Use prose, diagrams, or compact examples according to the ambiguity. A targeted schema, algorithm, or type sketch belongs here when it is the expensive shared decision; otherwise link the authoritative formal contract instead of copying it.
+
+### Decisions and alternatives
+
+For each consequential choice, state the chosen option, the forces that made it consequential, credible alternatives, why the choice won, and what it closes off. Omit obvious and cheap choices.
+
+## Conditional detail
+
+Add a section only when its trigger applies:
+
+- **Persistent or shared state:** entities, relationships, ownership, lifecycle, consistency, retention, and deletion.
+- **Migration or shared compatibility:** compatibility states, authority at each state, transition criteria, partial-failure recovery, stop or rollback conditions, and the destructive-cleanup boundary.
+- **Security, privacy, or trust:** trust boundaries, authorization, secrets, exposure, deletion, and audit behavior.
+- **Capacity, performance, or cost:** the required envelope and the structural choices it forces.
+- **Operations:** detection, observability, on-call ownership, degraded modes, and recovery when they affect architecture.
+- **Empirical unknown:** the hypothesis, probe, criteria, and why the unknown does not block the settled structure.
+- **Cross-team or durable review:** status, decision owner, affected owners, approvers, and child-design links.
+
+## Design direction
+
+Use **top-down, interface-first** design when integration seams are the hard or expensive part. Fix the contracts, then place responsibilities behind them. Use **bottom-up, primitives-first** design when a novel data structure, algorithm, or performance constraint determines the component model above it.
 
 For a design large enough to split across nodes, read [[design/roadmap]].

package/dist/builtin-memory/design/roadmap.md

@@ -12,10 +12,10 @@ surfaces:
 
 # Decomposing a design for parallel work
 
-Decompose only when settled contracts expose genuinely independent surfaces and the design is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. Split along clean seams — by component, subsystem, or interaction surface. A long but tightly coupled design stays with one base agent across yields so one mind owns its coherence. Each delegated sub-design is a bounded unit that covers one component or subsystem end-to-end: its own context, architecture, interfaces, data model, flows, and decisions.
+Decompose only when settled contracts expose genuinely independent surfaces with non-overlapping responsibility and ownership, and the design is large enough that parallel work materially improves intelligence, productivity, or elapsed time after synthesis cost. A long but tightly coupled design stays with one base agent across yields so one mind owns its coherence.
 
-Before delegating sub-designs, define the shared interface contracts between them explicitly. These contracts are the seams; they must be written down before sub-design begins so that parallel sub-designs don't invent incompatible assumptions. Capture these contracts in `$CRTR_CONTEXT_DIR/design-contracts.md` and give that absolute path to every sub-design agent.
+Before delegating, write the shared interface contracts in `$CRTR_CONTEXT_DIR/design-contracts.md`. Fix the overall structure, source-of-truth boundaries, interaction meaning, invariants, and assumptions every sub-design must preserve. Give that absolute path, the overall orientation, the sub-design scope, and the governing constraints to every child.
 
-Each sub-design agent gets: the overall architecture diagram, the contracts doc, the scope of its piece, and any constraints from the parent design. It writes `design-<component>.md` in its own context directory and reports the absolute path.
+Each child owns one component, subsystem, or interaction surface end to end. It follows [[design/guide]] and includes only the conditional detail its surface triggers. It writes `design-<component>.md` in its context directory and reports the absolute path.
 
-After sub-designs land, integration is your job: read every sub-design, check that every contract is honored on both sides, that responsibilities don't overlap or gap, that the data models are consistent, and that the key flows compose correctly across component boundaries. Write the integrated design to `$CRTR_CONTEXT_DIR/design-<subject>.md`, synthesizing all sub-designs into one coherent artifact — don't just concatenate them. Reconcile any inconsistencies before declaring the design done.
+After the sub-designs land, synthesize one design at `$CRTR_CONTEXT_DIR/design-<subject>.md`; do not concatenate them. Check each shared contract from both sides, reconcile names and data semantics, close responsibility gaps and overlaps, and walk the cross-boundary success and failure flows before declaring the integrated design settled.

package/dist/builtin-memory/insights/init.md

@@ -28,11 +28,11 @@ Choose the narrowest durable scope that reaches every future conversation where
 
 Infer the scope from the request and current workspace. Ask through `crtr human send` only when more than one scope is genuinely plausible, and settle scope before writing anything. Never use node scope for an ongoing listener.
 
-Search the chosen scope before creating. If `insights/<topic>` already represents the same domain, refine that listener rather than creating an overlapping directory.
+Search the chosen scope before creating. Use `<namespace>/insights/<topic>` for project scope and `insights/<topic>` for profile or user scope; if that canonical address already represents the same domain, refine that listener rather than creating an overlapping directory.
 
 ## Create the listener
 
-Run `crtr memory write -h`, then create `insights/<topic>/INDEX.md` at the chosen scope as a preference surfaced `{on: boot, at: preview}`.
+Run `crtr memory write -h`, then create the directory document at the chosen scope under its canonical address: `<namespace>/insights/<topic>` for project scope and `insights/<topic>` for profile or user scope, as a preference surfaced `{on: boot, at: preview}`. Its physical front door remains `insights/<topic>/INDEX.md`.
 
 Its routing line must name the actual domain trigger: when user-supplied information, a correction, or a user response relates to this domain, read the preference because recognizing the underlying principle preserves knowledge future decisions can use.
 
@@ -52,7 +52,7 @@ When `--active` is present, do not stop after creating the listener. After initi
 
 ### 1. Create the listener first
 
-Follow the passive mode steps above through "Initialization is complete." The listener INDEX must exist before spawning the explorer.
+Follow the passive mode steps above through "Initialization is complete." The listener directory document must exist before spawning the explorer.
 
 ### 2. Spawn the explorer child
 
@@ -81,8 +81,8 @@ When the explorer reports, share its claims with the user. For each claim, ask:
 - Is it incomplete or wrong?
 - What's the actual principle?
 
-For each user response, use [[insights/capture]] to extract and review the insight. Apply approved insights directly to the listener INDEX's `Approved insights` section.
+For each user response, use [[insights/capture]] to extract and review the insight. Apply approved insights directly to the listener directory document's `Approved insights` section.
 
 ### 4. Report completion
 
-Once claims have been surfaced and user guidance has generated approved insights, report that active initialization is complete. The listener INDEX now passively captures this domain as new user material emerges.
+Once claims have been surfaced and user guidance has generated approved insights, report that active initialization is complete. The listener directory document now passively captures this domain as new user material emerges.

package/dist/builtin-memory/internal/INDEX.md

@@ -25,4 +25,4 @@ Adjacent, outside this dir: authoring memory documents (kind, surfaces routing,
 
 Briefly: **plugins** package docs and commands, with command execution selected by `plugin.json.transport` (`exec` for a trusted local executable or `http` for a fetched remote REST manifest); **marketplaces** index and distribute plugins. Plugin commands enter the **external-command** fallthrough, leaving the core fast-path untouched.
 
-The individual files surface at `name` (their titles route; open the one the situation calls for); this index surfaces at `preview` so the dir announces when to come looking.
+The individual files surface at their canonical names (open the one the situation calls for); this directory document surfaces at `internal` at `preview`, and `crtr memory read internal` returns its body followed by the directory's immediate listing.

package/dist/builtin-memory/internal/examples/INDEX.md

@@ -13,4 +13,4 @@ The other internal/ docs explain the primitives one at a time; this dir shows th
 
 - **imessage-assistant** — an OpenClaw-style always-on assistant: resident root node with its own dir and persona, woken event-style by a launchd watcher via `node message send`, reading `chat.db` (with the attributedBody gotcha), replying via osascript, remembering people through project-scope memory.
 
-Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it.
+Add an example here when a composition was non-obvious enough that the next builder shouldn't have to re-derive it. Read `internal/examples` for this overview and its immediate example listing; the physical front door remains `INDEX.md`, but `INDEX` is not part of the canonical address.

package/dist/builtin-memory/internal/memory-loading.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need to know why a memory doc did or didn't load — or are deciding how a new doc should surface — this reference should be read because it names the event, rung, gate, and ordering that produced the behavior, so you fix loading by turning the right dial instead of guessing at frontmatter.
-short-form: The complete load model — the five surface events, the rung ladder, gates, listings, transcript dedup, boot-render ordering, and store mounting/precedence.
+short-form: The complete load model — the five surface events, the rung ladder, gates, listings, context exposure, boot-render ordering, and store mounting/precedence.
 surfaces:
   - on: boot
     at: name
@@ -15,10 +15,10 @@ Every memory doc declares its own delivery in frontmatter `surfaces` entries; th
 
 A doc with no `surfaces` does exactly one thing: appears in its directory's listing. Everything beyond that is an explicit entry — `{on: <event>, match?, match-frontmatter?, gate?, at: <rung>}`. An entry's event constraints and optional node-config `gate` must both match; participating entries OR across and fold to their highest rung (`content` > `preview` > `name`), with no cross-entry deny precedence. Multiple entries per event are legal. The events:
 
-- **boot** — the catalog assembled into every node's system prompt at revive. No match; the entry's presence is the match.
+- **boot** — the frozen preference system snapshot and first-message knowledge catalog assembled when a context begins. No match; the entry's presence is the match.
 - **workspace-open** — first-message context when cwd/profile mounts the doc's project store. Project stores only.
 - **read** — a `read` tool call returned a matching file: path globs vs the file's absolute path and basename, `./`-anchored globs vs its path relative to the store's owning repo dir, `match-frontmatter` predicates over the read file's own YAML frontmatter.
-- **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's own name directory.
+- **memory-read** — a `crtr memory read` resolved a matching doc: name globs vs its canonical name, `./` anchored to this doc's canonical routing anchor (a collapsed directory document anchors at its own directory name).
 - **command** — a matching shell command ran: globs vs the whole command string, `*` crossing `/`. Delivery is post-execution — right for "you are now in this territory," never for "don't run this at all."
 
 Nothing positional fires from where a doc happens to sit on disk — only from its declared entries and its listing.
@@ -39,9 +39,9 @@ A document-level `gate` is the hard eligibility predicate over the node's own co
 
 ## Listings and dedup
 
-Reading a doc discloses where it sits: `crtr memory read <doc>` also renders, once per transcript, the listing of the doc's directory and each ancestor — one routing line per member doc, one bare name per subdirectory. `crtr memory read <dir>` (or a bare-dir `[[ref]]`) returns the listing itself; no doc answers for a directory. `unlisted: true` suppresses a doc from every listing. Store roots are never auto-listed — `crtr memory list` is the deliberate root browse.
+Reading a doc discloses where it sits: `crtr memory read <doc>` also renders, once per loaded context, the listing of the doc's directory and each ancestor — one routing line per member doc, one bare name per subdirectory. A directory document owns its canonical directory node, so `crtr memory read <dir>` (or a bare-dir `[[ref]]`) returns that document's body followed by the directory's immediate listing without repeating the document; a directory without a document returns its listing. `unlisted: true` suppresses a doc from every listing. Store roots are never auto-listed — `crtr memory list` is the deliberate root browse.
 
-Every delivery dedups per transcript keyed on (doc, rung), higher rungs piercing lower: a listing line is a preview-rank render, boot renders seed the set at their boot rung, and a content delivery silences everything after it.
+Every delivery registers its document or listing identity and rung in the loaded context's exposure ledger. System and transcript ranks max-fold, so a higher rung pierces a lower one while a content delivery silences later lower-rung deliveries. A strict resume preserves that ledger and the byte-stable preference snapshot; yield or another new-context boundary replaces them with exactly the new system and first-message snapshots.
 
 ## Store mounting and precedence
 
@@ -53,7 +53,7 @@ The maximum reaches those two events and nothing else. Read, memory-read, and co
 
 A workspace's front door is an ordinary doc carrying the entry pair `{on: workspace-open, at: content}` + `{on: read, match: "./**", at: content}` — the operating guide loads when that workspace mounts or its files are read, not in every boot catalog. `crtr memory lint` requires exactly one workspace-open content doc per profile-managed project store. Multiple mounted roots render broad-to-specific.
 
-A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, deduplicated against everything already in the transcript. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).
+A `.crouter/memory/` store nested BELOW a mounted root (a package or subsystem dir) is delivered by the read path, not by boot: reading any file beneath its owning dir surfaces its read-routed docs, filtered against what the loaded context already contains. Addressability is separate — the `crtr memory` leaves (list/read/find/lint/delete/origin) discover nested stores through a bounded walk (git-aware, depth- and time-capped), while the boot catalog stays ancestor+profile only, which is why a nested doc's boot entries are inert (lint warns; drop them).
 
 ## Ordering
 

package/dist/builtin-memory/internal/plugins.md

@@ -33,7 +33,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
 └── memory/
     ├── <name>.md                    # a kind:knowledge or kind:preference doc
     └── <area>/
-        ├── INDEX.md                 # optional — an ordinary doc; a bare-dir read answers with the listing
+        ├── INDEX.md                 # optional physical front door; its canonical address is the directory and read combines body + immediate listing
         └── <name>.md
 ```
 

package/dist/builtin-memory/plan/guide.md

@@ -0,0 +1,53 @@
+---
+kind: knowledge
+when-and-why-to-read: When writing an implementation plan from approved requirements or design, this knowledge should be read so a fresh implementer can locate each change, respect its dependencies, and prove the requested behavior without reconstructing the repository.
+short-form: Use when producing an implementation plan — grounded units, dependency order, conditional transitions, and acceptance proof.
+rationale: >-
+  Carries the shared planning method and artifact shape used by plan-kind nodes and the optional /dev:plan front door. The old entry paths repeated broad affected-area and verification categories while leaving files, dependencies, and proof ambiguous.
+---
+
+# Planning a change
+
+Ground the plan in the current repository and every applicable approved requirement, specification, and design. When the blast radius is unclear — what the change touches, who depends on it, or what breaks — use `explore` scouts to map it before writing, and draw the implementation surfaces from evidence rather than an assumption.
+
+Treat the approved inputs as fixed. Resolve cheap local implementation detail when the plan needs it. When repository evidence contradicts the design or exposes an expensive-to-reverse choice, return that gap to design instead of silently deciding it in the plan.
+
+Hold scope to the approved outcome and the implementation work it necessarily requires. Speculative features, future extensibility, adjacent cleanup, and other merely plausible additions stay out. Ask the user only when an approved input is genuinely ambiguous or the requested outcome cannot be completed without a scope decision.
+
+Write the plan to `$CRTR_CONTEXT_DIR/plan-<subject>.md`. Keep it pure: approved inputs, implementation units, dependencies, and acceptance proof belong in the plan; concerns, commentary, recommendations, decision history, and live progress do not. Keep live execution state in a separate record when the work needs one.
+
+## Inputs and implementation approach
+
+Link every applicable approved input, state the implementation strategy in one paragraph, and point to the existing repository patterns the work follows. If no design exists because the structure is local and cheap to reverse, state that in one clause rather than manufacturing one. Repeat a scope boundary only when the linked inputs leave it easy to misread.
+
+## Ordered implementation units
+
+Each unit states:
+
+- **Outcome:** the independently meaningful result.
+- **Change:** what must become true, without pseudocode or pasted source.
+- **Surfaces:** exact current files, symbols, callers, tests, migrations, generated artifacts, or operational assets.
+- **Dependencies:** prerequisite units and edit-surface ownership constraints.
+- **Proof:** the narrowest deterministic or runtime evidence that establishes the outcome.
+
+Group units into phases only when a phase has one coherent outcome and proof gate. Derive parallel lanes from dependency and edit ownership, not labels such as frontend and backend. Start with a thin central end-to-end slice when it can exercise the real integration path. Put an implementation unknown before routine polish when a working probe can retire it.
+
+## Acceptance proof
+
+Map every acceptance criterion to the unit or final runtime check that proves it. Include integration and manual runtime evidence when static checks cannot establish the behavior. A phase gate is a safe stopping point; dependent work does not proceed through a failed gate.
+
+## Conditional units
+
+Add units only when their trigger applies:
+
+- **Migration:** source of truth, compatible reader and writer states, backfill, reconciliation, cutover, observation, reversal, and old-path deletion.
+- **Rollout:** staged exposure, deployment order, stop criteria, monitoring, rollback, and adoption proof.
+- **Operational adoption:** docs or runbooks, alerts, support or on-call handoff, prevention of new legacy use, and decommissioning.
+- **Bulk transformation:** one common mechanism and proof gate plus an explicit queue for judgment-heavy exceptions.
+- **Long or concurrent execution:** a separate live record with the current phase, remaining unknown or blocker, last passed proof, and commit, PR, or deploy evidence. Do not mutate the approved plan into a progress log.
+
+## Plan depth
+
+Scale detail with cross-cutting impact, dependency complexity, interruption risk, and proof difficulty. A familiar one-file change needs no plan. Keep units small enough to review, reject, or reverse, but do not fragment a coherent outcome into line-edit chores.
+
+For work that genuinely needs independent part-plans, read [[plan/roadmap]].