@creator-notes/cnotes 0.58.0 → 0.59.1

package/dist/lib/brand.d.ts

@@ -20,6 +20,9 @@ export declare const BRAND: {
     readonly url: "https://creatornotes.app";
     /** Bare domain. */
     readonly domain: "creatornotes.app";
+    /** Developer portal (docs only). The API stays on `url`; never a server target. */
+    readonly devUrl: "https://cnotes.dev";
+    readonly devDomain: "cnotes.dev";
     /** The installed command. */
     readonly command: "cnotes";
     /** Published package name. */

package/dist/lib/brand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/lib/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;IAChB,kDAAkD;;IAElD,kEAAkE;;IAElE,mBAAmB;;IAEnB,6BAA6B;;IAE7B,8BAA8B;;IAE9B,uFAAuF;;IAEvF,oCAAoC;;CAE5B,CAAC"}
+{"version":3,"file":"brand.d.ts","sourceRoot":"","sources":["../../src/lib/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,KAAK;IAChB,kDAAkD;;IAElD,kEAAkE;;IAElE,mBAAmB;;IAEnB,mFAAmF;;;IAGnF,6BAA6B;;IAE7B,8BAA8B;;IAE9B,uFAAuF;;IAEvF,oCAAoC;;CAE5B,CAAC"}

package/dist/lib/brand.js

@@ -20,6 +20,9 @@ export const BRAND = {
     url: "https://creatornotes.app",
     /** Bare domain. */
     domain: "creatornotes.app",
+    /** Developer portal (docs only). The API stays on `url`; never a server target. */
+    devUrl: "https://cnotes.dev",
+    devDomain: "cnotes.dev",
     /** The installed command. */
     command: "cnotes",
     /** Published package name. */

package/dist/lib/brand.js.map

@@ -1 +1 @@
-{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/lib/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,kDAAkD;IAClD,IAAI,EAAE,eAAe;IACrB,kEAAkE;IAClE,GAAG,EAAE,0BAA0B;IAC/B,mBAAmB;IACnB,MAAM,EAAE,kBAAkB;IAC1B,6BAA6B;IAC7B,OAAO,EAAE,QAAQ;IACjB,8BAA8B;IAC9B,WAAW,EAAE,uBAAuB;IACpC,uFAAuF;IACvF,SAAS,EAAE,SAAS;IACpB,oCAAoC;IACpC,IAAI,EAAE,uBAAuB;CACrB,CAAC"}
+{"version":3,"file":"brand.js","sourceRoot":"","sources":["../../src/lib/brand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB,kDAAkD;IAClD,IAAI,EAAE,eAAe;IACrB,kEAAkE;IAClE,GAAG,EAAE,0BAA0B;IAC/B,mBAAmB;IACnB,MAAM,EAAE,kBAAkB;IAC1B,mFAAmF;IACnF,MAAM,EAAE,oBAAoB;IAC5B,SAAS,EAAE,YAAY;IACvB,6BAA6B;IAC7B,OAAO,EAAE,QAAQ;IACjB,8BAA8B;IAC9B,WAAW,EAAE,uBAAuB;IACpC,uFAAuF;IACvF,SAAS,EAAE,SAAS;IACpB,oCAAoC;IACpC,IAAI,EAAE,uBAAuB;CACrB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creator-notes/cnotes",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "CLI for CreatorNotes — create notes, build canvases, search knowledge from the terminal",
   "type": "module",
   "bin": {

package/skills/attention-planner/SKILL.md

@@ -1,18 +1,19 @@
 ---
 name: attention-planner
-description: Turn everything that arrived into either finished agent work or one answerable Attention card scheduled as a focus block, then close the loop when the human answers. Use when the user invokes /attention-planner, asks "what needs me today", "plan my attention", "triage the digest", "triage this transcript", "what did I answer", "close the day", "close the week", or says they answered a card ("I filled ATTENTION-12"). Runs on the cnotes CLI and expects the cnotes skill to be installed.
+description: Turn everything that arrived into either finished agent work or one answerable Attention card scheduled as a focus block, then close the loop when the human answers. Use when the user invokes /attention-planner, asks "what needs me today", "plan my attention", "protect a block for <thing>", "triage the digest", "triage this transcript", "what did I answer", "close the day", "close the week", or says they answered a card ("I filled ATTENTION-12"). Runs on the cnotes CLI and expects the cnotes skill to be installed.
 metadata:
-  short-description: One answerable card a day, loop closed by the agent
+  short-description: One open card at a time, loop closed by the agent
 ---
 
 # Attention planner
 
 The job: restore the human's control over their commitments, one answerable
 card at a time. The human holds three things an agent cannot supply: judgment,
-authorization, and accountability. The agent holds unlimited attention. So
-route every item that arrived to the cheapest resource that can safely settle
-it, hand the human only the residue as a card they can answer in the time it
-says, and when they answer, make things move and say what moved.
+authorization, and accountability. The agent's attention is cheap, bounded
+only by its tools, access, runtime, and cost, never by a working day. So route
+every item that arrived to the cheapest resource that can safely settle it,
+hand the human only the residue as a card they can answer in the time it says,
+and when they answer, make things move and say what moved.
 
 Felt from the chair: "I answered one thing, five things moved, and I know what
 is still waiting." Judge every write by that sentence. Create the smallest
@@ -26,31 +27,49 @@ canvas layout, the humanizer). Consult it rather than guessing.
 
 | Concept | CreatorNotes shape |
 |---|---|
-| Rules | One standing note the human ratified, titled `Attention rules`: hours and timezone, deep units per day and their length, the protected morning, sources the agent may read, actions it may take unasked, actions that always need a yes. Found with `cnotes search "attention rules"`. Mentioned from every card |
+| Rules | One standing note the human ratified, titled `Attention rules`: hours and timezone, deep units per day and their length, the protected morning, protected priorities, sources the agent may read, actions it may take unasked, reviews it may complete unasked, actions that always need a yes. Found with `cnotes search "attention rules"`. Mentioned from every card |
 | Queue | Today's **IncomingDigest** note. The only list. Headings: `Agent completed`, `Ready for shallow window`, `Waiting for Deep Work`, `Moved today`. Versioned through the day, never duplicated. If the intake pipeline wrote none, create today's from what arrived |
-| Card | An **Attention** note: a time-boxed decision interface for one human. Tagged `open` plus `deep` or `shallow`. At most one deep and one shallow per run. Shapes and worked examples in [references/card-shapes.md](references/card-shapes.md) |
+| Card | An **Attention** note: a time-boxed interface for one human. Four shapes: **decide** (deep), **make** (deep), **shallow**, and the one-time **rules** card. Tagged `deep` or `shallow` plus a state: `open` (unanswered), `answered` (answer recorded, follow-through running), `closed` (every promise settled). Shapes and worked examples in [references/card-shapes.md](references/card-shapes.md) |
 | Block | A `cnotes focus plan` landed on the card with `--canvas` and `--target`. The only source of truth for when. The card title carries no time, so a moved block never leaves a stale title |
-| Orientation canvas | Deep cards only: `<Card title> · Orientation`, the card first, then the notes it rests on, laid out once with `cnotes canvas place`. The block opens here |
+| Orientation canvas | For a deep card whose answer rests on more than the card itself: `ATTENTION-N · Orientation`, built once with `cnotes canvas place` as a left-to-right story with the flow of thought written beside the notes, per [references/orientation-canvas.md](references/orientation-canvas.md). The block opens here. A card that carries everything the reader needs lands its block on the home board instead |
 
 An Attention is not a Task. A Task says what work must be done. A card says
 why this needs the human now, gives enough context to decide without opening
 other notes, separates confirmed from inferred, asks only for the inputs that
-person alone can give, states what the agent does after the answer, and names
-which external actions still wait for approval.
+person alone can give, states what the agent does after the answer, names
+which external actions still wait for approval, and says how the agent will
+learn that the answer exists.
 
 ## Lanes
 
 | Lane | What belongs here | Budget | Block |
 |---|---|---|---|
-| Agent automatic | Retrieve, compare, summarize, draft, reproduce, organize. Anything an existing decision or rule already settles | Unlimited | None. Do it now, version the notes it touched, list it under `Agent completed` |
-| Deep Work | Making or judging that cannot be drafted and batch-approved | Deep units from the Rules (default four of 45 minutes, combinable to 90 or 135 for one sitting) | One card, morning first |
-| Shallow PM | Approve, send, route, or a two-minute yes or no after the agent prepared the draft | One 30-minute window per working day after the first deep block. Never a deep unit | Lands on the queue, or on the shallow card |
+| Agent automatic | Retrieve, compare, summarize, draft, reproduce, organize. Anything an existing decision or rule already settles | Bounded by tools, access, runtime, and cost. Never by human attention | None. Do it now, version the notes it touched, list it under `Agent completed` |
+| Deep Work | Deciding or making that cannot be drafted and batch-approved. Two shapes: **decide** ends in an answer; **make** ends in an artifact the human had to produce or explore themselves | Deep units from the Rules (default four of 45 minutes, combinable to 90 or 135 for one sitting) | One card, morning first |
+| Shallow PM | Approve, send, route, complete a prepared review, or a two-minute yes or no after the agent prepared the draft | One 30-minute window per working day after the first deep block. Never a deep unit | Lands on the queue, or on the shallow card |
 | Interrupt | A real customer blocked, an irreversible move imminent, a committed response at risk | The next unused deep unit | The card names what it displaced |
 
 Inbox processing is never Deep Work. A ready approve-and-send is never Deep
 Work. An unscheduled deep item is not a card; it waits on the queue under
 `Waiting for Deep Work`.
 
+## Budgets
+
+Three numbers, kept apart because they answer different questions.
+
+| Budget | Value | Governs |
+|---|---|---|
+| Daily capacity | The Rules' deep units (default four of 45 minutes) | How much sitting time exists. A card's block spends one to three units. Units the block leaves unplanned stay unplanned; a later run may plan a second sitting on the same open card, never a second card |
+| Open cards | One open deep card and one open shallow card at any moment, plus the rules card on the first run | Whether a new card may exist at all. A card leaves this count when it becomes `answered`, so follow-through never blocks the next question |
+| New cards per run | At most one deep and one shallow | How much a single run may add. Three runs a day cannot stack three deep cards: the open-card cap holds across runs. A run that finds the deep slot taken versions that card or leaves the item under `Waiting for Deep Work` |
+
+Open cards inherited above the cap (from an older planner, or a run that
+broke the rule) are not planned. The gates in intake step 6 pick the one that
+holds the slot; the rest wait under `Waiting for Deep Work`, named with a
+mention, until it frees. An inherited card is brought up to the current
+contract (shape on the Lane line, the trigger line) only when its block is
+planned, never as a sweep.
+
 ## Three loops
 
 ### 1 · Intake (agent, every morning)
@@ -59,94 +78,165 @@ Work. An unscheduled deep item is not a card; it waits on the queue under
    create it exactly as [references/attention-type.md](references/attention-type.md)
    says, then read the rubric back and author to it.
 2. **Read the Rules.** If none exist, this run's only card is the Rules card
-   (shape in card-shapes). Do not guess a schedule.
-3. **Load the delta, not the world.** `cnotes focus list --days 7`, open cards
-   (`cnotes notes list --type Attention --tags open --json`), today's queue,
-   the priority board the Rules name if any, then what arrived since the last
-   run: `cnotes shared`, `cnotes timeline --since 1d`, new Transcript notes,
-   and the digest the intake pipeline wrote. A digest or canvas digest is
-   orientation; open the underlying notes before any consequential claim.
+   (shape in card-shapes). Do not guess a schedule. If the Rules exist but
+   lack a line this skill reads (protected priorities, reviews the agent may
+   complete unasked), treat the missing line as "none", say so on the queue,
+   and put the two lines under `Ready for shallow window` as one item. Never
+   mint a second Rules card.
+3. **Load the delta, not the world.** `cnotes focus list --days 7`, open and
+   answered cards (`cnotes notes list --type Attention --tags open --json`,
+   then `--tags answered`), today's queue, the priority board the Rules name
+   if any, then what arrived since the last run: `cnotes shared`,
+   `cnotes timeline --since 1d`, new Transcript notes, and the digest the
+   intake pipeline wrote. A digest or canvas digest is orientation; open the
+   underlying notes before any consequential claim.
 4. **Open the run.** `cnotes operations begin --prompt "Attention planner · <date> · intake"`.
    One active run per user: if `begin` refuses, another session is writing.
    Hold the run only while writing.
-5. **Do the agent-automatic work first.** For each item ask: can the agent
-   retrieve, compare, draft, reproduce, or organize it; does an existing
-   decision or rule settle it; would waiting block a customer, a deadline, or
-   a dependent owner; is the evidence ready enough to decide? Version the
-   existing notes with the results. Never turn a research chore into human
-   attention. If evidence is missing, assign its retrieval to the agent or
-   the responsible owner.
+5. **Do the agent-automatic work first.** Settle any `answered` card's
+   unfinished follow-through before anything new (loop 3). Then for each
+   item ask: can the agent retrieve, compare, draft, reproduce, or organize
+   it; does an existing decision or rule settle it; would waiting block a
+   customer, a deadline, or a dependent owner; is the evidence ready enough
+   to decide? Version the existing notes with the results. Never turn a
+   research chore into human attention. If evidence is missing, assign its
+   retrieval to the agent or the responsible owner.
 6. **Choose at most one deep item.** Ordered gates, not a score: Interrupt,
-   then the one decision that unlocks the most dependent work, then queue.
-   Ties: the item already named highest priority, the earliest real deadline,
-   enough evidence to decide now, the least context switching. Search for an
-   open card asking the same decision and version it rather than minting a
-   sibling. If an urgent item displaces a planned block, name the displaced
-   block on the card. Never hide the trade.
+   then a protected priority (an item the Rules or the priority board name
+   as protected or highest, in that order), then the one decision or making
+   that unlocks the most dependent work, then queue. A busy operational
+   decision never outranks a protected priority just because more things
+   hang off it. Ties: the earliest real deadline, enough evidence to decide
+   now, the least context switching. Search for an open card asking the same
+   thing and version it rather than minting a sibling. If the deep slot is
+   already taken by an open card, the item waits. If an urgent item displaces
+   a planned block, name the displaced block on the card. Never hide the
+   trade.
 7. **Write the card.** Read `cnotes types show Attention` and the cnotes
-   skill's humanizer reference first. Question and default first, context
-   second, evidence per [references/evidence-ledger.md](references/evidence-ledger.md),
-   the post-answer contract last. Every card names one existing Project,
+   skill's humanizer reference first. Pick the shape: **decide** when the
+   block ends in an answer the agent can act on; **make** when the human must
+   produce or explore something themselves (a strategy, a draft only they
+   can write, a problem not yet answerable) and the block protects that
+   sitting. Question and default first for decide; what the sitting produces
+   first for make. Context second, evidence per
+   [references/evidence-ledger.md](references/evidence-ledger.md), the
+   post-answer contract last, ending with how the agent learns the answer
+   exists (step 9 of loop 3). Every card names one existing Project,
    Decision, or Customer with an `advances` mention plus one sentence of what
-   becomes true. No such object exists: the work is queue hygiene. Leave it on
-   the queue and do not invent a Project to hang it on. Mention every note by
-   `[ID: Title](relationship:verb)`, never as a bare display ID.
+   becomes true. No such object exists: the work is queue hygiene. Leave it
+   on the queue and do not invent a Project to hang it on. Mention every note
+   by `[ID: Title](relationship:verb)`, never as a bare display ID.
 8. **Route artifact review.** When the human must inspect a canvas, section,
    or draft, create the official request only after the artifact exists:
    `cnotes review request <canvas> --reviewer me --target <ref> --brief "…" --acceptance "…" --source ATTENTION-N --idempotency-key "attention-N-<slug>-v1" --json`.
-   Paste the returned `url` and `requestId` into the card. Never construct the
-   URL. Private comments (`canvas comments add`) are working notes, not a
-   request. `comments submit` sends a finished review to someone else's canvas
-   and requests nothing.
-9. **Schedule.** Deep card: prepare its orientation canvas, then
-   `cnotes focus plan --start <ISO with the Rules' offset> --duration 45m|90m|135m --goal "Deep Work · <decision>" --canvas CANVAS-X --target ATTENTION-N`.
-   Shallow window: one block after the first deep block, landed on the queue
-   or the shallow card when that note sits on a canvas, goal-only otherwise.
-   Cancel the window when `Ready for shallow window` is empty. A block that
-   moves is cancelled before it is re-planned. Never plan a closed or past
-   card. Verify with `cnotes focus list`.
+   Paste the returned `url` and `requestId` into the card, and write on the
+   card what an `approved` outcome authorizes. Never construct the URL.
+   Private comments (`canvas comments add`) are working notes, not a request.
+   `comments submit` sends a finished review to someone else's canvas and
+   requests nothing.
+9. **Schedule.** Deep card: decide whether it needs an orientation canvas.
+   It does when the answer rests on something beyond the card: a standing
+   decision that constrains it, a source that left things open, an artifact
+   to inspect. Build it per
+   [references/orientation-canvas.md](references/orientation-canvas.md)
+   (frames, labelled edges, banner, portals, and a text card per step that
+   projects the card), then
+   `cnotes focus plan --start <ISO with the Rules' offset> --duration 45m|90m|135m --goal "Deep Work · <decision or artifact>" --canvas CANVAS-X --target ATTENTION-N`.
+   A card that carries everything the reader needs skips the canvas: land the
+   block on the home board with `--canvas <home board> --target ATTENTION-N`,
+   or goal-only when there is no home board. Shallow window: one block after
+   the first deep block, landed on the queue or the shallow card when that
+   note sits on a canvas, goal-only otherwise. Cancel the window when
+   `Ready for shallow window` is empty. A block that moves is cancelled
+   before it is re-planned. Never plan a closed or past card. Verify with
+   `cnotes focus list`.
 10. **Update the queue.** Version today's digest with `Agent completed`,
     `Ready for shallow window`, and `Waiting for Deep Work`. Mark the intake
     source processed only after those writes and plans succeeded.
-11. **Close the run.** Report the card by title, when its block runs, what the
-    agent finished, and what waits. Surface the orientation canvas link.
+11. **Close the run.** Report the card by title and shape, when its block
+    runs, what the agent finished, what waits, and how the agent will learn
+    the answer (a scheduled close, or the human saying so). Surface the
+    orientation canvas link when one exists.
 
 ### 2 · Decide (human, time-boxed)
 
-The block opens the orientation canvas landed on the card. The human reads the
-question and the recommended default first; everything else is on the card if
-they want it. They answer by filling the `Your decision` line and saving, or
-by replying in chat with the card's title. Nothing else is asked of them: no
-"tell the agent" ritual, no naming of the next step. The card already says
-what happens next.
+The block opens the canvas landed on the card. On a decide card the human
+reads the question and the recommended default first; everything else is on
+the card if they want it. They answer by filling the `Your decision` line and
+saving, or by replying in chat with the card's title. On a make card they
+work in the sitting, then fill the `Outcome` line with what now exists or
+"continue", or leave the produced note versioned; either is an answer. Nothing
+else is asked of them when a scheduled close will find the answer. When no
+schedule exists, the card's last line asks them to say they answered, and
+that one sentence is the whole ritual.
 
 ### 3 · Close the loop (agent, after each block and at day end)
 
-1. **Find answered cards.** An open card whose latest version has a filled
-   `Your decision` line, a chat reply naming a card, or a review request that
-   reached a terminal status (`cnotes review get <requestId> --json`).
-2. **Open the run**, then convert each answer into the promised updates:
+1. **Find answered cards.** An open card is answered when its latest version
+   has text after `**Your decision:**` or `**Outcome:**`, when a chat reply
+   names it, when a make card's produced note carries a version by the human
+   after the block started, or when a linked review request reached an
+   outcome that maps to an answer. Map every review state explicitly, as
+   `cnotes review get <requestId> --json` returns it:
+
+   | Review state | Meaning for the card |
+   |---|---|
+   | `submitted`, outcome `approved` | Yes to what the card's `Review action` says the review settles. Follow through on that, and on nothing the card did not name |
+   | `submitted`, outcome `changes_requested` | No as drafted. The findings are the human's edit: version the artifact, request again under the next idempotency key (`-v2`), card stays `open` |
+   | `submitted`, no outcome | Not an answer; a plain comment send. Read the comments as working notes and keep the card `open` |
+   | `returned` | Not an answer. The reason names what the reviewer lacked; supply it and request again |
+   | `revoked`, `expired` | Not an answer. The ask died; request again or move the item to the queue |
+   | `pending`, `accepted` | Waiting |
+
+   Execute only when the answer resolves the card's question and grants the
+   permission the action needs. A terminal review is not by itself a grant.
+2. **Record the answer.** Open the run, then version the card with a
+   `## Follow-through` section (shape in card-shapes): the version number the
+   answer was read from, and one line per promised action from `After you
+   answer`, each with a status: `done`, `waiting: <whose yes>`,
+   `failed: <reason>`, `skipped: <why>`. Tag it `answered,<lane>`. Write this
+   before executing anything, so a crash leaves a ledger, not a mystery.
+3. **Execute from the ledger.** Convert the answer into the promised updates:
    version connected notes, produce the promised draft or brief, hand named
-   owners their requests.
-3. **Mint durable objects only when the answer created them.** A Decision,
+   owners their requests. Update each line as it lands. On a rerun, read the
+   ledger first: a `done` line is never repeated, a `failed` line is retried,
+   a `waiting` line is checked for its yes. A send recorded `done` is never
+   sent twice, whatever the queue says.
+4. **Mint durable objects only when the answer created them.** A Decision,
    Requirement, Task, Question, or Issue, and only then. Prefer a new version
    of an existing note over a sibling.
-4. **Respect the reserved actions.** Customer contact, commitments, deletions,
+5. **Respect the reserved actions.** Customer contact, commitments, deletions,
    and anything irreversible happen only if the answer explicitly approved
-   them. Record what still waits.
-5. **Close the card.** Version it with a `## Closed` section (what was done,
-   what still waits, with mentions), then `cnotes notes update ATTENTION-N --tags closed,<lane>`.
-   Open the next card only if judgment is still needed, and still only one.
-6. **Update the queue.** `Moved today`, in outcome language.
+   them. Otherwise the line stays `waiting: <whose yes>` and the ask goes to
+   the queue under `Ready for shallow window`.
+6. **Close the card.** Only when no ledger line is `failed` and every
+   `waiting` line names a yes that now sits on the queue: version it with a
+   `## Closed` section (what was done, what still waits, with mentions), then
+   `cnotes notes update ATTENTION-N --tags closed,<lane>`. A card with a
+   `failed` line stays `answered` and is the first thing the next run
+   settles. A new answer on an already `answered` card (the human edited the
+   line after the recorded version) gets a second `Follow-through` block, not
+   a silent rerun.
+7. **Open the next card** only if judgment is still needed, and still only
+   one, and only if the deep slot is empty.
+8. **Update the queue.** `Moved today`, in outcome language, including any
+   follow-through that failed or still waits.
+9. **State the trigger.** The last line of every card's `After you answer`
+   says how the agent learns the answer exists: "A scheduled close runs at
+   <time>" when a routine exists, or "Tell the agent you answered" when none
+   does. Never promise follow-through the host cannot wake up for.
 
 ## Closing the day and the week
 
 **Day.** When the user says so, or after the last block, version today's
 digest with `Moved today`: what is now true that was not true this morning;
 deep units used of the budget; whether the shallow window ran or was
-cancelled; what is still open. A sent email is not a move. A drafted note is
-not a move. If nothing moved, write that. Do not mint a journal or an
-Achievement note.
+cancelled; what is still open, including answered cards whose follow-through
+failed or waits. A move is a change in what is true: a commitment made, a
+blocker released, a decision recorded, an artifact that now exists. A sent
+email or a drafted brief counts by the change it enabled, named in outcome
+language; the artifact alone is not the move. If nothing moved, write that.
+Do not mint a journal or an Achievement note.
 
 **Week.** Friday after the last block, version the standing Update titled
 `Attention spend · weekly close` (create it once if it does not exist, never a
@@ -158,10 +248,14 @@ shows a trade the human must choose.
 ## Intake sources
 
 - **IncomingDigest.** Already synthesized, PII-free evidence. Read only the
-  latest version of today's. Never write PII, names, ticket IDs, or
-  source-system identifiers into CreatorNotes. Join Q-IDs only through the
-  owner's private action key if they gave one. Older IntakeDigest or
-  DailyAttentionDigest notes are superseded: read them, never create them.
+  latest version of today's. PII here means what the pipeline stripped: end
+  users' names, emails, phone numbers, ticket IDs, and source-system
+  identifiers. Never write those into CreatorNotes. Workspace members, named
+  owners, Customer notes (an account, not a person), and speaker attribution
+  by role or member name are workspace vocabulary and belong on cards. Join
+  Q-IDs only through the owner's private action key if they gave one. Older
+  IntakeDigest or DailyAttentionDigest notes are superseded: read them, never
+  create them.
 - **Transcript.** Raw evidence, never a reading assignment for the human.
   Preserve it. Write one short Huddle outcome note `derived-from` it,
   separating what participants settled from what they proposed, questioned,
@@ -169,10 +263,17 @@ shows a trade the human must choose.
   artifact production to the named owners. Tag the transcript `digested` only
   after the linked updates and plans succeed. The card carries the
   decision-ready context and links the transcript as provenance only.
-- **Shared with you.** `cnotes shared` is the inbox of asks and shares. A
-  review assigned to you is agent work: `cnotes review get`, judge the pinned
-  target against every criterion, then `complete` or `return`. Never fabricate
-  an outcome you could not judge.
+- **Shared with you.** `cnotes shared` is the inbox of asks and shares. The
+  agent prepares every review assigned to the human: `cnotes review get`,
+  judge the pinned target against every criterion, draft the findings and
+  the outcome. It runs `complete` or `return` itself only when the Rules
+  delegate that class of review (the Rules card names which). Every other
+  prepared review goes under `Ready for shallow window` with the drafted
+  outcome as the recommended default, the criterion that fails and the edit
+  that would satisfy it, and the human completes it in the window. Dates and
+  promises inside a draft go stale while a review waits; check them against
+  today before calling a criterion met. Never fabricate an outcome you could
+  not judge.
 
 ## Board hygiene
 
@@ -187,8 +288,9 @@ when the send rests on them.
 ## Invariants
 
 1. Work the agent can do safely never becomes a card.
-2. At most one deep card per run. A shallow card only for a drafted,
-   consequential external send. The Rules card is the single exception.
+2. One open deep card and one open shallow card at a time, at most one of
+   each minted per run. A shallow card only for a drafted, consequential
+   external send. The Rules card is the single exception.
 3. Every card names what it advances with an `advances` mention, or the work
    stays on the queue.
 4. Untested product behaviour is Unknown. It never appears as fact in a
@@ -196,16 +298,32 @@ when the send rests on them.
    Validation, then draft.
 5. A review request carries the server-returned URL and request ID, or it
    does not exist on the card.
-6. PII and source identifiers never enter CreatorNotes from the queue.
+6. End-user PII and source identifiers never enter CreatorNotes from the
+   queue.
 7. Intake is marked processed only after the writes and plans succeed.
+8. The agent executes only on an answer that resolves the question and grants
+   the permission the action needs. A terminal review, a cancelled ask, or a
+   returned review is not an answer.
+9. A card closes only from its follow-through ledger, and a ledger line is
+   never repeated once `done`.
 
 Triage mints nothing but Attention, plus Comms or Validation when a card will
 approve or rest on that object, plus one Huddle on the transcript path. Every
 other type waits for the answer.
 
-## Run it unasked
+## How the agent wakes
 
 Three moments: morning intake, the close after the last block, the Friday
-close. If the host agent supports scheduled routines, schedule all three so
-the card is waiting when the human sits down and nobody has to remember to
-ask.
+close. The text of this skill cannot wake anyone; only one of these can:
+
+- **Scheduled routines**, when the host agent supports them. Schedule all
+  three so the card is waiting when the human sits down and the close finds
+  the answer without being told. This is the intended mode.
+- **The human's invocation**: "I filled ATTENTION-12", "close the day",
+  "what did I answer". Always a trigger, and the only one when no routine
+  exists.
+
+There is no event trigger: saving an answer or finishing a block does not
+notify the agent. So at the end of intake, say which mode is in force, and
+write it on the card (loop 3, step 9). Automatic follow-through that was
+never scheduled is a broken promise, not a feature.

package/skills/attention-planner/references/attention-type.md

@@ -23,7 +23,7 @@ it must never block a quick human capture.
 
 ```bash
 RUBRIC=$(cat <<'TXT'
-An Attention note is a time-boxed decision interface for one human. It asks only for judgment, permission, preference, or accountability that an agent cannot supply safely. A good one leads with the question and a recommended default, says why it needs attention now, gives enough source-grounded context to decide without opening other notes, and states what happens after the answer and which external actions still need approval. Keep the time box honest: about two minutes for a shallow approve-or-send, 45 to 135 minutes for deep judgment.
+An Attention note is a time-boxed interface for one human. It asks only for judgment, permission, preference, or accountability that an agent cannot supply safely, or protects a sitting in which the human must make or explore something themselves. A good one leads with the question and a recommended default, or with what the sitting produces, says why it needs attention now, gives enough source-grounded context to decide without opening other notes, and states what happens after the answer, which external actions still need approval, and how the agent will learn the answer exists. Keep the time box honest: about two minutes for a shallow approve-or-send, 45 to 135 minutes for deep judgment or making.
 
 If you are an agent: do every safe step first and list it under "What the agent already did". Name the Project, Decision, or Customer this card advances with an advances mention and one sentence of what becomes true. Classify each consequential claim as Confirmed, Reported, Inference, Recommendation, or Unknown, and link its source with a readable relationship mention such as [NOTE-12: Title](relationship:references); never a bare display ID. Treat untested product behaviour as Unknown. Lean less the harder the choice is to undo; on a pure value fork, do not pick, give the default with its dissent. When the human must inspect a canvas or draft, link an official review request with its server-returned URL and request ID; private comments are not a request. Write "Complete when" as an observable state, never "discussed" or "reviewed".
 TXT
@@ -37,7 +37,8 @@ cnotes types show Attention -w <workspaceId> --json   # validationPrompt must be
 ```
 
 If an existing Attention type comes back with an empty `validationPrompt`,
-apply the same rubric the same way and read it back again.
+or one that predates the make shape (no mention of a sitting), apply the
+rubric above the same way and read it back again.
 
 ## Related types the planner may touch
 

package/skills/attention-planner/references/card-shapes.md

@@ -1,27 +1,34 @@
 # Card shapes
 
-Three shapes, one rule: the reader arrives cold and should be able to answer
+Four shapes, one rule: the reader arrives cold and should be able to answer
 before scrolling. Question first, recommended default second, context third,
 evidence fourth, the post-answer contract last. Depth follows the stakes: a
 shallow card is a screen at most, a deep card a few, and neither carries a
 section that adds no decision value. Provenance and the post-answer contract
-are never omitted.
-
-The human answers after the colon on a `**Your decision:**` line. A card is
-answered when any such line has text after the colon, or when the human names
-the card in chat. Titles carry no time: the focus block is the source of truth
+are never omitted, and the contract always ends by saying how the agent will
+learn the answer exists.
+
+The human answers after the colon on a `**Your decision:**` line (decide and
+shallow cards) or an `**Outcome:**` line (make cards). A card is answered when
+any such line has text after the colon, when the human names the card in chat,
+or, on a make card, when the produced note carries a version by the human after
+the block started. Titles carry no time: the focus block is the source of truth
 for when, and a moved block must not leave a stale title behind.
 
+States travel as tags: `open` until answered, `answered` while the ledger runs,
+`closed` once every promise is settled. The lane tag (`deep`, `shallow`) stays
+throughout.
+
 Read `cnotes types show Attention` and the cnotes skill's humanizer reference
 before writing. Mention every note as `[ID: Title](relationship:verb)`; reuse
 the workspace's relationship vocabulary (`cnotes rel types`).
 
-## Deep card
+## Deep card · decide
 
 ```markdown
 # <The decision the human will produce>
 
-**Lane:** Deep Work · 45 min
+**Lane:** Deep Work · 45 min · decide
 **Advances:** [PROJECT-N: Title](relationship:advances) by <what becomes true if this block succeeds>
 **Rules:** [NOTE-N: Attention rules](relationship:references)
 
@@ -69,6 +76,8 @@ options cost. Under one screen. Orientation mentions belong here:>
 2. The agent will <scheduling, delegation, or preparation step>.
 3. The agent will not <customer contact, commitment, destructive change, or
    other external side effect> without your explicit yes.
+4. <"A scheduled close runs at HH:MM and picks this up." or "Tell the agent
+   you answered; nothing runs until you do.">
 
 ## Complete when
 
@@ -82,6 +91,8 @@ after the artifact exists and `cnotes review request` returned:
 ## Review action
 
 **Decision:** <what this review settles>
+**An approved outcome authorizes:** <exactly what the agent may then do, and
+what still needs a separate yes>
 **Acceptance:** <short, testable criteria>
 **Open the review:** [Review the proposal](<url returned by the server>)
 **Request:** `<requestId>`
@@ -90,6 +101,72 @@ after the artifact exists and `cnotes review request` returned:
 [SECTION-N: The exact review surface](relationship:related-to)
 ```
 
+## Deep card · make
+
+For a sitting the human must spend themselves: a strategy to develop, a
+problem to explore before it has an answerable question, a draft only they
+can write. The block protects the making; the agent scaffolds it and takes
+over afterwards. The card leads with what the sitting produces, not with a
+question.
+
+```markdown
+# <The artifact or state the sitting produces>
+
+**Lane:** Deep Work · 90 min · make
+**Advances:** [PROJECT-N: Title](relationship:advances) by <what becomes true when this exists>
+**Rules:** [NOTE-N: Attention rules](relationship:references)
+
+## What this sitting produces
+
+<One sentence: the note, section, or canvas that exists at the end, and the
+state it must reach. Name the target note with a mention:>
+
+- [STRATEGY-N: Title](relationship:produces)
+
+**Outcome:**
+
+## Why now
+
+<Stakes and what waits on this. Three sentences.>
+
+## Start here
+
+<The agent's scaffold: the notes to open first, the draft or outline it
+prepared, the questions to hold in mind, the constraints that already bind
+the answer. Under one screen. Orientation mentions belong here.>
+
+## Evidence
+
+<Only the claims the making rests on. The full table when a claim would
+change what gets made; otherwise one line per claim with its class and
+source.>
+
+## What the agent already did
+
+- <the outline, comparison, or research that seeds the sitting>
+- <what is assigned to another owner, by name>
+
+## After the block
+
+1. The agent will read the produced note and <version the linked notes, or
+   extract the decisions it contains into Decision notes>.
+2. The agent will <schedule the next sitting if the outcome says "continue",
+   or route what now exists>.
+3. The agent will not <share, send, or commit the artifact> without your
+   explicit yes.
+4. <"A scheduled close runs at HH:MM and picks this up." or "Tell the agent
+   you finished; nothing runs until you do.">
+
+## Complete when
+
+<An observable state of the artifact: "a version of STRATEGY-N names the
+wedge and the two alternatives it rejects", never "time was spent".>
+```
+
+The `Outcome` line takes what now exists, or `continue` with what is still
+missing. A make card whose outcome is `continue` stays `open` and the next run
+plans another sitting on the same card; it never mints a sibling.
+
 ## Shallow card
 
 Only for a consequential external send that already has a draft. Anything
@@ -142,6 +219,8 @@ The one shallow card allowed without a draft. Its answer becomes the standing
 - Sources the agent may read: <the intake workspace, shared items, transcripts, the priority board>
 - Actions the agent may take unasked: research, compare, draft, version notes, plan and cancel focus blocks
 - Actions that always need a yes: customer contact, commitments, deletions, anything irreversible
+- Protected priorities: <the one or two objects that outrank throughput, such as a strategy canvas, or "none">
+- Reviews the agent may complete unasked: <a class, such as reviews it requested itself or drafts under 500 words, or "none: prepare every review, I complete it">
 - Interrupt rule: a blocked customer takes the next unused deep unit
 
 **Your decision:**
@@ -152,27 +231,48 @@ The agent saves the ratified lines as the standing `Attention rules` note,
 mentions it from every future card, and runs intake.
 ```
 
+## Follow-through section
+
+Appended as a new version the moment an answer is found, before anything is
+executed, and updated as each line lands. The tags change to
+`answered,<lane>` in the same write. A rerun reads this first: `done` is never
+repeated, `failed` is retried, `waiting` is checked for its yes.
+
+```markdown
+## Follow-through
+
+Answer read from version <N>, <date>: <the answer in one line>.
+
+1. <promised action> · done · [NOTE-N: Title](relationship:references)
+2. <promised action> · waiting: <whose yes, and where it sits on the queue>
+3. <promised action> · failed: <reason, and what the next run will try>
+4. <promised action> · skipped: <why the answer made it unnecessary>
+```
+
+A second answer on the same card (the human changed the line after version
+N) gets a second `Follow-through` block under it, never an edit of the first.
+
 ## Closed section
 
-Appended as a new version when the loop closes, before the tags change to
-`closed,<lane>`:
+Appended as a new version only when no line above is `failed` and every
+`waiting` line names a yes that now sits on the queue. The tags change to
+`closed,<lane>` in the same write.
 
 ```markdown
 ## Closed
 
-Answered <date>: <the answer in one line>.
 Done: <what the agent did, with mentions>.
-Still waiting: <the external action that needs a yes, or "nothing">.
+Still waiting: <the external action that needs a yes and where it sits, or "nothing">.
 ```
 
-## Worked example · deep
+## Worked example · decide
 
 A fictional customer, written the way a real card should read.
 
 ```markdown
 # Choose the recovery offer for Northwind's export failures
 
-**Lane:** Deep Work · 45 min
+**Lane:** Deep Work · 45 min · decide
 **Advances:** [CUSTOMER-7: Northwind Logistics](relationship:advances) by a recovery offer they can accept this week instead of escalating to procurement
 **Rules:** [NOTE-31: Attention rules](relationship:references)
 
@@ -216,6 +316,7 @@ Exports over 50,000 rows time out; the agent reproduced it today. The fix is sch
 1. The agent will fill the offer into the draft and version it.
 2. The agent will queue the send for the shallow window.
 3. The agent will not send anything to Northwind without your explicit yes on the draft.
+4. A scheduled close runs at 12:15 and picks this up.
 
 ## Complete when
 
@@ -252,4 +353,25 @@ Their procurement conversation is Friday. Sending today gives them two working d
 1. `yes`: the agent sends it and records the send on the customer note.
 2. `edit`: the agent applies your edit, then sends.
 3. `hold`: it returns to the queue under `Ready for shallow window`.
+4. A scheduled close runs at 12:15 and picks this up.
 ```
+
+## Worked example · follow-through
+
+The decide card above, after the human wrote "fix date plus one month's
+credit" on version 3 and the close loop ran:
+
+```markdown
+## Follow-through
+
+Answer read from version 3, Tuesday: fix date plus one month's credit.
+
+1. Fill the offer into [COMMS-12: Northwind recovery note](relationship:references) · done
+2. Queue the send for the shallow window · done · listed under `Ready for shallow window` on [INCOMINGDIGEST-9: Tuesday](relationship:references)
+3. Send to Northwind · waiting: your yes on [ATTENTION-43: Send the recovery note to Northwind?](relationship:references)
+```
+
+Every line is `done` or `waiting` on a yes that sits on the queue, so the card
+closes in the same run. Had line 1 failed (the draft locked by another
+session, say), the card would stay `answered` and the next run would retry
+line 1 before minting anything new.

package/skills/attention-planner/references/evidence-ledger.md

@@ -44,10 +44,11 @@ The ledger's depth follows the stakes, not the template.
 
 | Card | Ledger |
 |---|---|
-| Deep | The full table, one row per consequential claim |
+| Decide | The full table, one row per consequential claim |
+| Make | Only the claims the making rests on. The full table when a claim would change what gets made; otherwise one line per claim with its class and source |
 | Shallow | One line per claim the draft makes, each with its class and source. If the draft makes no product-behaviour claims, one line saying so |
 | Rules | None. The card asks for preferences, not facts |
 
-A deep card with no Reported, Inference, or Unknown rows is a signal to look
+A decide card with no Reported, Inference, or Unknown rows is a signal to look
 again: either the decision is agent-automatic and should not be a card, or a
 claim has been promoted without a source.

package/skills/attention-planner/references/orientation-canvas.md

@@ -0,0 +1,112 @@
+# Orientation canvas
+
+A deep card whose answer rests on more than itself gets a canvas the block
+opens on: a standing decision that constrains it, a source that left things
+open, an artifact to inspect. A card that carries everything the reader needs
+skips the canvas and lands its block on the home board; a canvas that would
+hold only the card and its source is presentation overhead, not orientation.
+When the canvas is warranted, it is not done when the right notes are on it. A flat pile of five correct notes makes the human
+reconstruct the chain the agent already knows, which is the failure the canvas
+exists to prevent. Lay it as a story the reader follows left to right in ten
+seconds, and write the flow of thought on the board beside the notes.
+
+Title: `ATTENTION-N · Orientation`, using the card's immutable display id, never
+its heading. Goal: one sentence saying what the block decides and that the card
+is first. One `cnotes canvas place` call builds the whole thing from a spec; the
+sections size themselves around their content, so no coordinates.
+
+## The frames, left to right
+
+| Frame | Holds | Edge to the card |
+|---|---|---|
+| `1 · Came from` | The digest, transcript, or share the card was minted from, plus one text card saying which item and why nothing else needed the sitting | `produced` |
+| `2 · Decide here` | The Attention card, with a text card beside it per element: why now, then one per numbered decision with its recommendation and what flips it | none; this is the card |
+| `What it rests on` (under frame 2) | The standing Decision that constrains the answer, the Huddle or Validation that left things open, each with a text card | `constrains`, `left open`, `grounds` |
+| `3 · Advances` | The Project, Decision, or Customer the card names in `advances`, with a text card saying what becomes true if the block succeeds and which external send still needs a yes | from the card: `advances` |
+| `Where things live` (bottom) | Portals: the work board the card came from and the home board | none |
+
+Banner at the top, `richtext` medium, untinted, at most five sentences, in the
+cnotes skill's banner order (hard rule 7 under "Canvas Elements"): what happened,
+what this board is for, who answers and where, how to read it. Then the lines
+only this canvas needs: the block day and time, "answer on the card", where the
+portals go. A banner that opens with the block time and the reading order and
+never says what the card is about fails the cnotes cold-reader test.
+Reminder material (rules, operating plan) does not go on an orientation canvas;
+the home board carries it.
+
+## The text cards
+
+Each text card is a projection of a note that already holds the full record.
+The rules are the cnotes skill's rules for text elements, applied hard:
+
+- At most three sentences. One bold lead phrase is fine (`**Why now.**`, `**1 · The date you owe.**`).
+- Every number, date, name, and recommendation is lifted from the card or its
+  source verbatim. Never restate a figure, never add one. Run the preservation
+  gate before placing.
+- Name every note and canvas with a relationship mention carrying its real title
+  (`[DECISION-6J2: Title](relationship:constrains)`); it renders as a chip. A bare
+  display id is a defect. The chip is for the reader, not the graph: the note body
+  still carries the mention that travels.
+- Untinted by default. Tint only by role: `#F59E0B` for the constraining rule,
+  `#3B82F6` for source evidence. Nothing else.
+- `size: "small"` (560px) beside a 280px note card. Put text cards in the same
+  frame as the note they project, in a vertical stack under or beside it.
+
+A text card that says something no note says is a bug: put it in the note first,
+then project it.
+
+## Spec template
+
+```json
+{ "placement": "exact", "origin": { "x": 100, "y": 100 },
+  "root": { "kind": "stack", "axis": "vertical", "gap": "spacious", "items": [
+    { "kind": "item", "type": "richtext", "size": "medium", "content": "# <Day HH:MM> · <card title>\n<reading order; answer on the card; portals below>" },
+    { "kind": "stack", "axis": "horizontal", "gap": "spacious", "align": "start", "items": [
+      { "kind": "section", "name": "1 · Came from", "child": { "kind": "stack", "axis": "vertical", "gap": "medium", "items": [
+        { "kind": "item", "type": "note", "noteId": "<DIGEST>", "key": "src" },
+        { "kind": "item", "type": "richtext", "size": "small", "content": "<which item, why only this sitting>" } ] } },
+      { "kind": "stack", "axis": "vertical", "gap": "medium", "items": [
+        { "kind": "section", "name": "2 · Decide here", "child": { "kind": "stack", "axis": "horizontal", "gap": "medium", "align": "start", "items": [
+          { "kind": "item", "type": "note", "noteId": "ATTENTION-N", "key": "card" },
+          { "kind": "stack", "axis": "vertical", "gap": "tight", "items": [
+            { "kind": "item", "type": "richtext", "size": "small", "content": "**Why now.** <from the card>" },
+            { "kind": "item", "type": "richtext", "size": "small", "content": "**1 · <decision>.** <recommendation>. Flips if <condition>." } ] } ] } },
+        { "kind": "section", "name": "What it rests on", "child": { "kind": "stack", "axis": "horizontal", "gap": "medium", "align": "start", "items": [
+          { "kind": "stack", "axis": "vertical", "gap": "tight", "items": [
+            { "kind": "item", "type": "note", "noteId": "<DECISION>", "key": "rule" },
+            { "kind": "item", "type": "richtext", "size": "small", "colorHex": "#F59E0B", "content": "<the standing rule and what it forces here>" } ] },
+          { "kind": "stack", "axis": "vertical", "gap": "tight", "items": [
+            { "kind": "item", "type": "note", "noteId": "<HUDDLE or VALIDATION>", "key": "open" },
+            { "kind": "item", "type": "richtext", "size": "small", "colorHex": "#3B82F6", "content": "<what it left open, what is reported, what is unknown>" } ] } ] } } ] },
+      { "kind": "section", "name": "3 · Advances", "child": { "kind": "stack", "axis": "vertical", "gap": "medium", "items": [
+        { "kind": "item", "type": "note", "noteId": "<PROJECT>", "key": "obj" },
+        { "kind": "item", "type": "richtext", "size": "small", "content": "<what becomes true; which send stays with the human>" } ] } } ] },
+    { "kind": "section", "name": "Where things live", "child": { "kind": "stack", "axis": "horizontal", "gap": "medium", "items": [
+      { "kind": "item", "type": "canvas", "linkedCanvasId": "<work board convex id>" },
+      { "kind": "item", "type": "canvas", "linkedCanvasId": "<home board convex id>" } ] } } ] },
+  "edges": [
+    { "from": "@src",  "to": "@card", "label": "produced" },
+    { "from": "@card", "to": "@obj",  "label": "advances" },
+    { "from": "@rule", "to": "@card", "label": "constrains" },
+    { "from": "@open", "to": "@card", "label": "left open" } ] }
+```
+
+Drop a frame that has nothing to hold; never leave an empty one. Add a frame
+only when the card rests on something the reader must see (a Contradiction or a
+Fork gets its own layout from the workspace's layout catalog instead).
+
+## Rebuilding
+
+An orientation canvas is rebuilt, not patched: `bulk-remove` every node (notes,
+sections, portals, the banner) inside one operations run, then `place` the new
+spec. Section ids change; nothing should reference them by id. The focus block
+targets the card, not a section, so it survives the rebuild. Verify with
+`cnotes focus list` that the block still lands on the canvas and the card.
+
+## Read-back test
+
+`cnotes canvas read`: every note sits in a named frame, every edge carries a
+verb, every text card is at most three sentences and traceable to a note, the
+banner names the block, and both portals resolve. Then the glance test: a
+person zoomed to fit should see came from, decide here, advances, and start
+reading at the card.

package/skills/cnotes/SKILL.md

@@ -253,7 +253,11 @@ cnotes canvas digest <canvasId>
 # NAMING: never put an em-dash (—) or en-dash (–) in a canvas name. Use the interpunct
 # · (U+00B7, MIDDLE DOT — a small mid-height dot, NOT a bullet •) as the separator,
 # e.g. "Path to Revenue · Funding strategy", not "Path to Revenue — Funding strategy".
-cnotes canvas create "<name>" [--goal "<text>"] [--audience "<text>"]   # prints Ref (CANVAS-N) + Link — surface them to the user (see "Surfacing the canvas link")
+cnotes canvas create "<name>" --goal "<text>" [--audience "<text>"]   # prints Ref (CANVAS-N) + Link — surface them to the user (see "Surfacing the canvas link")
+# --goal is not optional in practice: write it FIRST, for a reader, as the decision or artifact
+# the board exists to produce ("Decide whether X; pick the first slice"), never as a brief to
+# yourself ("Research Tufte, diverge on..."). The goal renders only inside the (i) popover, so
+# nobody sees it before the banner; the banner restates it (hard rule 7).
 cnotes canvas update <canvasId> [--title "<text>"] [--goal "<text>"] [--audience "<text>"]
 cnotes canvas delete <canvasId>
 cnotes canvas set-as-home <canvasId>
@@ -266,10 +270,12 @@ cnotes canvas add-node <canvasId> --note <noteId> [--x <n>] [--y <n>]   # (despi
 # text = free-form rich text placed on the canvas (wire type: richtext). Markdown —
 # headings, emphasis, images. Optional background tint (--color); DEFAULT IS NO BACKGROUND.
 # A HEADING IS JUST `--content '# Q1 Goals'` with no tint — there is no separate heading
-# element. CARD-sized framing (at most ~3 sentences): orientation banners, emphasis
+# element. CARD-sized framing (at most ~3 sentences; the orientation banner may run to ~5 and follows hard rule 7), emphasis
 # quoting a note, image tiles. Unversioned, unsearchable, no display ID (nothing can cite
-# it) — never the sole home of a claim. NO [NOTE-X](relationship:...) / [[...]] mention
-# syntax (corrupts the card; use plain display IDs). Knowledge worth keeping = a typed note.
+# it) — never the sole home of a claim. When the card names a note or canvas, write a
+# relationship mention with the REAL title, `[NOTE-12: Title](relationship:verb)`: it renders
+# as a chip (verified 2026-09-05). A bare display id in card prose is a defect. The chip is
+# presentational (no graph edge), so knowledge worth keeping = a typed note.
 cnotes canvas add-text <canvasId> --content "<markdown>" [--size small|medium|large] [--color "<hex>"] [--x <n>] [--y <n>]  # inline (short only)
 cnotes canvas add-text <canvasId> --content-file <path.md> [--size small|medium|large] [--color "<hex>"] [--x <n>] [--y <n>]
 cnotes canvas add-richtext ...   # DEPRECATED alias of add-text (identical flags). Use add-text.
@@ -876,7 +882,7 @@ A canvas holds two tiers of material, and the difference is load-bearing:
 | N distinct things (questions, risks, options, findings) | **N notes** grouped in a **list**; `--description` = one-line frame | bullets in one text element or in a list `--description` |
 | A named REGION of the canvas ("Shaping", "Open Questions") | a **section** frame (`add-section`) — draggable region, mention-addressable as `[[SECTION-<n>]]` from note bodies | a floating text heading over an implied area |
 | A heading / one-line label where a frame is too heavy (a column header inside a frame, a lane key) | a **text** element holding a markdown heading — `add-text --content '# Q1 Goals'`, no `--color` (leave it untinted), title case | a tinted card, or a section frame for something that isn't a region |
-| Prose telling the reader how to traverse THIS canvas | a **text** orientation banner (one per canvas or band; up to ~5 sentences) | a Guide note nobody needs off-canvas |
+| Orientation: what happened, what this board is for, and how to read it | a **text** orientation banner in the fixed shape of rule 7 (one per canvas; a band may add a short one; up to ~5 sentences) | a reading-order-only banner, or a Guide note nobody needs off-canvas |
 | Emphasis — restating a key claim for screen presence | a **text** element that QUOTES a note (the note stays the home) | the text element as the only copy |
 | An image tile (logo, mockup, screenshot) | a **text** element holding the image, beside the owning note; embed the same image in the note body via `cnotes files upload <path> --markdown` so the note stays self-contained | the image as the knowledge itself |
 | A grid of images for review (mood board) | N text-element image tiles in a `grid` place spec + ONE note holding the decision criteria / rationale for the set | a caption note per tile, or rationale in the tiles |
@@ -887,7 +893,7 @@ A canvas holds two tiers of material, and the difference is load-bearing:
 #### Hard rules (each one has burned a real canvas)
 
 1. **A canvas element must never be the sole home of a claim.** Verdict tallies, dates, scan provenance, and even a moat-defining sentence have each been authored as text elements — then cited downstream while being unversioned, unsearchable, and uncitable. If a text element says something true and useful, a note says it first; the text element may quote the note. (Canvas-specific wayfinding — how to read THIS canvas — is the one exemption; it has no off-canvas value.)
-2. **No relationship-mention syntax inside text elements or list descriptions.** `[NOTE-12](relationship:references)` and `[[NOTE-12]]` corrupt a canvas text element — the card renders blank. Reference notes in canvas prose as plain display IDs ("see RISK-64"). Mentions belong in NOTE bodies, where they create real graph edges.
+2. **Name notes and canvases from text elements with relationship mentions, never bare ids.** `[NOTE-12: Title](relationship:references)` inside a text element renders as a mention chip carrying the target's real title (the Text node registers the mention schema; verified live 2026-09-05, and a list description renders the same mention as a labelled span). "See RISK-64" as plain prose is a defect: the reader gets no title and no link. Pick the relationship type from the verb the sentence uses and reuse the workspace vocabulary. The chip is presentational: it creates no graph relationship, is not searchable, and is not versioned, so a relationship that must survive off the canvas still lives as a mention in a NOTE body (rule 5).
 3. **A text element is capped at card size**: at most 3 sentences, one heading at most, never a list of distinct knowledge items (questions, risks, findings — those are N notes; a 3-line color legend or lane key is fine). The one exception is the orientation banner (table row 5, up to ~5 sentences). A heading-only text element (`--content '# Q1 Goals'`) is of course fine — that is the smallest legitimate use. The cap is physical as much as doctrinal: a text element renders its full content inline, so long blocks explode the canvas — one canvas hit 43,000px tall from eight text reference blocks and had to be rebuilt as notes.
 4. **Detail's HOME is the note body; text detail cards are projections.** Write the full spec/content INTO each note's body first. A parallel text card under a note is allowed only as a projection — it condenses or quotes a note that already contains everything, and says so ("from STAGE-3"). A detail card whose content exists nowhere else is the anti-pattern: one teaching canvas carried its entire method in text cards over one-line stub notes, and an agent reading it back got seven stubs and no method.
 5. **Edges can connect any node type** (note, text, list, canvas-link, section — plus legacy heading nodes), as long as both endpoints are on the same canvas; labels are short verb phrases ("fixes", "grounds", "depends on"). A section endpoint is addressed by the section node's Convex id (`sectionNodes[].id` in `canvas get --json` — `canvas read` shows only display ids), not its SECTION-n display id, and the edge anchors to the frame's border — use one when the relationship's endpoint is genuinely the whole region ("this cluster feeds that stage"), not as a shortcut for a note-to-note link. `canvas read` returns edges, so they are no longer invisible on read-back — but an edge is still CANVAS-LOCAL: it is not part of the note graph, never appears in `rel list`, is not searchable, and means nothing once you leave this canvas. So any relationship **between notes** that must survive off the canvas has to ALSO exist as a mention inside the note bodies. The mention is the copy that travels; the edge is the copy you can see. Edges to text/list/canvas-link nodes are diagram decoration (pointing a label at a cluster, wiring a portal) and carry no note-to-note relationship to mirror.
@@ -904,14 +910,23 @@ A canvas holds two tiers of material, and the difference is load-bearing:
 
    Do not hand-pick a hex outside this table: the renderer snaps every tint to the nearest role by hue, so an off-palette color does not get you a new shade — it just picks a role imprecisely (`#c2410c` lands on Danger, not Warning). A tint colors the CARD only; text inside it keeps the normal prose colors, so the tint can never make a card harder to read. If you cannot name the role, omit the color.
 
-#### Two completion tests
+7. **The orientation banner opens for a stranger, in a fixed order.** The banner is the first and often the only card a cold reader sees (the goal sits behind the (i) button; nobody reads it first), so a banner that gives only the reading order fails: one shipped as "A story in six frames, read top to bottom. Frames 1 to 3 are the events: a release note is written, an agent writes an ad from it, the scope changes" and the reader could not say which release note, whose agent, or why any of it mattered. Write it in this order, at most ~5 sentences, heading = the board's subject (the canvas title or the goal), never a clever name for the banner:
+   1. **What happened** — one dated sentence naming the people, products and events a stranger can look up ("On 19 September 2026 Deniss asked why CreatorNotes records every note a person opens but nothing an agent reads").
+   2. **What this board is for** — the goal restated in reader's words: the decision or artifact it produces.
+   3. **Who acts on it and how** — who decides, answers, or builds, and where the answer goes (as a mention chip with its real title, rule 2).
+   4. **How to read it** — reading order and what each frame holds.
+   Nothing before the banner has defined anything, so no unnamed referents in it: not "the ad", "the app", "the scope", "the card" until the thing has been named or chipped. Wayfind maps and Attention orientation canvases add their own lines (destination, block time) after these four, never instead of them.
 
-Run both before ending your operation:
+#### Three completion tests
+
+Run all three before ending your operation:
 
 **The read-back test (for the next agent):** run `cnotes canvas read` and check that every claim is present as a NOTE section with a display ID, and the reasoning can be followed through note bodies and their mentions. Content that appears only as anonymous text-element prose fails the test even when visible — nothing can cite, search, or version it. List members read back as ID+title links without bodies; that is fine — the IDs are citable and batch-fetchable via `cnotes notes get`. As a heuristic for working canvases, at least ~4 notes per text element (zero text elements is fine); fewer means text elements are carrying content. Explainer canvases using the projection pattern (rule 4) are exempt from the ratio, not from the test.
 
 **The glance test (for the human):** zoomed to fit, a person should grasp what this canvas argues and where to start reading in about 10 seconds. A canvas that passes read-back but renders as an undifferentiated card grid is also not done — that is what section labels, orientation banners, projections, and layout are for.
 
+**The cold-reader test (for the person who was not in the session):** cover everything but the banner. Can someone who never saw the conversation say what happened, what this board decides or produces, and who acts on it? If the banner only gives the reading order, or leans on "the ad" / "the app" / "the card" before naming them, it fails (rule 7). Run this on the banner text itself, not on your memory of the run.
+
 #### Worked example
 
 Right shape (a real competitor scan): 31 typed notes (COMPETITOR profile, FACT evidence row, INSIGHT verdicts per dimension, RISK/IDEA/STRATEGY response bands, QUESTION follow-ups in a list), three short text banners framing the bands ("Threats, Steals, Response — what hurts us, what's worth taking, the plan"), and labeled edges mirrored as mentions (`FACT-44 --grounds--> INSIGHT-361`).
@@ -922,7 +937,7 @@ Wrong shape (same material): one 5,000-char text element holding a "deep scan wr
 
 The durable rules above stand on versioning, search, and citability. Four rules also lean on today's platform behavior — if a future release changes these, the corresponding rule can relax:
 
-- Mention syntax corrupts canvas text elements / list descriptions (motivates rule 2; an @-mention affordance is planned).
+- Mentions inside text elements and list descriptions are presentational chips only: no graph relationship, no search presence, no versions (motivates rule 1 and the mirror-as-mentions half of rule 5).
 - `canvas read` returns sections, edges and portals, but list containers still read back as their one-line frame only. An edge read back is still canvas-local and ungraphed (motivates rule 5's mirror-as-mentions requirement).
 - Agents have no update verb for **text or list** elements — to change one, remove and re-add it (one more reason content that evolves belongs in notes, which have versions). Section frames are the exception: `canvas update-section` edits a frame in place.
 
@@ -1100,7 +1115,7 @@ Full DSL alternative: a layout doc whose leaves are
 
 The optional `key` lets edges and other items reference this leaf later (`@<key>`).
 
-`richtext.content` (the **text** element) accepts markdown directly — the server converts to TipTap before measuring. Plain markdown only: NO `[NOTE-X](relationship:...)` / `[[...]]` mention syntax (it corrupts the card — reference notes as plain display IDs), and keep it card-sized per "Canvas Elements — When to Use What".
+`richtext.content` (the **text** element) accepts markdown directly — the server converts to TipTap before measuring. Markdown including relationship mentions: `[NOTE-X: Title](relationship:verb)` renders as a chip with the real title, so use one wherever the card names a note or canvas (a bare id is a defect), and keep it card-sized per "Canvas Elements — When to Use What".
 
 `list.description` is a one-line **frame**, never the content itself — the content is `noteIds` (the member notes). For N distinct things, create N notes (right type per item, e.g. `Question` for open questions) and list their ids. A `list` with a multi-item description and an empty `noteIds` is the wrong shape — use a card-sized **text** element (`richtext`, at most ~3 sentences) only for a short framing block with no members; anything longer, or any set of distinct items, is N notes.
 

package/skills/cnotes/references/humanizer.md

@@ -252,8 +252,9 @@ These are objective and never need judgment. Enforce them on every write:
 - **Relationship type matches the narrated verb** — prose "Blocks X" around a
   `references`/untyped chip is a graph bug, not a style choice: retype to
   `relationship:blocks` (or `[[blocks::NOTE-123]]`) and drop the redundant verb.
-- **No mention syntax inside canvas richtext or list descriptions** — it corrupts
-  the card. Reference notes there as plain display IDs ("see RISK-64").
+- **Canvas richtext and list descriptions name notes with relationship mentions** —
+  `[NOTE-12: Title](relationship:verb)` renders as a chip with the real title; a bare
+  display id in card prose ("see RISK-64") is a defect.
 - **Richtext stays card-sized** — at most ~3 sentences, one heading; distinct
   items are N typed notes, not a wall of text.
 - **No placeholder or artifact tokens** — "lorem ipsum", "TODO", "[insert X]",

package/skills/wayfind/SKILL.md

@@ -137,8 +137,10 @@ The user arrives with a loose idea.
    `wayfind` plus the mode.
 5. **Place the map** in one `cnotes canvas place` spec: orientation banner,
    the four sections with their contents, blocking edges (blocker → dependent,
-   label "blocks"). Banner is at most five sentences, plain display IDs only —
-   mention syntax corrupts richtext.
+   label "blocks"). Banner is at most five sentences in the cnotes skill's banner
+   order (hard rule 7 under "Canvas Elements"): what happened and who asked,
+   the destination in reader's words, who resolves tickets and how, then how the
+   four frames read. Plain display IDs only — mention syntax corrupts richtext.
 6. **Fire the research subagents** for frontier research tickets; fold whatever
    returns into resolutions (steps 4–6 of the work loop) before closing.
 7. **Close the run, surface the canvas link, stop.** Charting resolves nothing