create-pmos 0.52.0 → 0.53.0

package/workspace/fixtures/reports-page/draft-biweekly-2026-10-16.md

@@ -0,0 +1,97 @@
+---
+type: Reference
+title: "Biweekly report 2026-10-16"
+description: "The biweekly report for 2026-10-16. pmos report draft writes every number; prose goes only between the note markers."
+timestamp: 2026-10-16T00:00:00Z
+cadence: biweekly
+slot: 2026-10-16
+window: "2026-10-02T09:00:00Z to 2026-10-16T00:00:00Z (since the last issue)"
+synthetic: true
+---
+
+# Biweekly report 2026-10-16
+
+## Headline
+
+2 initiatives moved; 1 is at risk.
+
+<!-- pmos:note report.headline -->
+Audit log export is the one to watch this cycle.
+<!-- /pmos:note -->
+
+## Timeline
+
+Frozen at 2026-10-16T00:00:00Z. 2 Oct to 30 Oct; today is 16 Oct.
+
+| Initiative | Stage | Start | Due | Milestones |
+|---|---|---|---|---|
+| Partner SSO | build | 2026-10-01 | 2026-10-24 | 24 Oct |
+
+## Initiatives
+
+### Audit log export (audit-log)
+
+Stage: Evaluate · At risk: check-by 1 Oct passed · 3 of 5 (+1)
+
+Measured: KR-2 42% of 60%, as of 2026-10-14 (planning/metrics/kr-2.csv@3f2a9c1)
+
+**Last cycle**
+
+- Done: CSV writer (audit-log.a1b2c3d4e5)
+- Gates passed: spec, 3 Oct
+- Horizon moves: Next to Now, 3 Oct
+- Overdue, carried over: Retention rule, due 10 Oct
+
+**Coming cycle** (items that start or fall due)
+
+- Export UI, starts 17 Oct, due 28 Oct
+
+<!-- pmos:note audit-log -->
+Legal review is the open dependency.
+<!-- /pmos:note -->
+
+### Partner SSO (partner-sso)
+
+Stage: Build · On track · 7 of 12 (+4)
+
+**Last cycle**
+
+- Done: none
+- Gates passed: none
+- Horizon moves: none
+- Overdue, carried over: none
+
+**Coming cycle** (the next 3 by order)
+
+- Pilot partners on SSO
+
+<!-- pmos:note partner-sso -->
+
+<!-- /pmos:note -->
+
+## New since last report
+
+- Billing v2 (billing-v2), 8 Oct
+
+## Decided this cycle
+
+- Audit log export moved to Now, 3 Oct (planning/runs/placements.jsonl)
+
+## Needs your call
+
+For leadership only.
+
+<!-- pmos:note report.asks -->
+
+<!-- /pmos:note -->
+
+## Sources reached and not reached
+
+**Reached**
+
+- planning/runs/plan-items.jsonl
+- planning/runs/placements.jsonl
+
+**Not reached**
+
+- tracker: not refreshed since 2 Oct

package/workspace/fixtures/today-api/provider-rows.json

@@ -0,0 +1,204 @@
+{
+  "needs": [
+    {
+      "run_id": "report-needs:issue:biweekly:2026-10-16",
+      "initiative_id": null,
+      "kind": "report-issue",
+      "derived": true,
+      "question": "The biweekly of 16 Oct is ready to issue",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "report-needs",
+      "today": {
+        "kind": 1,
+        "source": "report-needs",
+        "cause": "A draft is ready to issue",
+        "evidence": "planning/reports/biweekly/2026-10-16.md",
+        "act": {
+          "label": "Issue",
+          "cli": "pmos report issue biweekly 2026-10-16"
+        }
+      }
+    },
+    {
+      "run_id": "work-check-needs:review:partner-sso.k3j9x0p2qa",
+      "initiative_id": "partner-sso",
+      "kind": "item-review",
+      "derived": true,
+      "question": "\"draft partner email\" is in Review",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "work-check-needs",
+      "today": {
+        "kind": 4,
+        "source": "work-check-needs",
+        "cause": "An item waits in Review",
+        "evidence": "planning/runs/plan-items.jsonl",
+        "act": {
+          "label": "Open",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "work-check-needs:release:partner-sso:b-01",
+      "initiative_id": "partner-sso",
+      "kind": "release",
+      "derived": true,
+      "question": "3 work items are ready to release",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "work-check-needs",
+      "today": {
+        "kind": 4,
+        "source": "work-check-needs",
+        "cause": "A factory batch is ready",
+        "evidence": "planning/runs/work-items.jsonl",
+        "act": {
+          "label": "Release",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "work-check-needs:no-evidence:partner-sso.q8d2m5h1zc",
+      "initiative_id": "partner-sso",
+      "kind": "item-no-evidence",
+      "derived": true,
+      "question": "\"update the partner FAQ\" reads Done with no evidence",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "work-check-needs",
+      "today": {
+        "kind": 4,
+        "source": "work-check-needs",
+        "cause": "An agent item reads Done with no evidence",
+        "evidence": "planning/runs/plan-items.jsonl",
+        "act": {
+          "label": "Open",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "initiative-needs:triage:capture-2026-10-04-1",
+      "initiative_id": null,
+      "kind": "triage",
+      "derived": true,
+      "question": "Proposed: Partner SSO \u00b7 new feature \u00b7 KR 2.1",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "initiative-needs",
+      "today": {
+        "kind": 6,
+        "source": "initiative-needs",
+        "cause": "A capture was triaged",
+        "evidence": "planning/requirements/capture-2026-10-04-1.md",
+        "act": {
+          "label": "Add",
+          "cli": "pmos initiative new --from capture-2026-10-04-1"
+        }
+      }
+    },
+    {
+      "run_id": "initiative-needs:cycle:2026-10-05",
+      "initiative_id": null,
+      "kind": "cycle-review",
+      "derived": true,
+      "question": "Confirm what is in Now",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "initiative-needs",
+      "today": {
+        "kind": 7,
+        "source": "initiative-needs",
+        "cause": "Day one: 2 initiatives read Now, unconfirmed",
+        "evidence": "planning/runs/placements.jsonl",
+        "act": {
+          "label": "Review",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "report-needs:cycle:kill-check:2026-10",
+      "initiative_id": null,
+      "kind": "cycle-kill-check",
+      "derived": true,
+      "question": "The monthly kill-condition check is due",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "report-needs",
+      "today": {
+        "kind": 7,
+        "source": "report-needs",
+        "cause": "The month ended",
+        "evidence": "planning/okrs/kill-conditions.md",
+        "act": {
+          "label": "Review",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "pm-lines-needs:z9y8x7w6v5u4",
+      "initiative_id": "partner-sso",
+      "kind": "pm-line",
+      "derived": true,
+      "question": "A PM-only line is not attested",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "pm-lines-needs",
+      "today": {
+        "kind": 8,
+        "source": "pm-lines-needs",
+        "cause": "A placed line into Now has no via",
+        "evidence": "planning/runs/placements.jsonl line 12",
+        "act": {
+          "label": "Show line",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "initiative-needs:no-anchor:old-import",
+      "initiative_id": "old-import",
+      "kind": "no-anchor",
+      "derived": true,
+      "question": "Legacy importer has no anchor",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "initiative-needs",
+      "today": {
+        "kind": 8,
+        "source": "initiative-needs",
+        "cause": "An initiative record names no KR or health budget",
+        "evidence": "planning/initiatives/old-import.md",
+        "act": {
+          "label": "Add anchor",
+          "cli": null
+        }
+      }
+    },
+    {
+      "run_id": "report-needs:no-output:weekly:2026-10-02",
+      "initiative_id": null,
+      "kind": "schedule-no-output",
+      "derived": true,
+      "question": "The weekly schedule left no output",
+      "doc": null,
+      "ws": "w-north",
+      "provider": "report-needs",
+      "today": {
+        "kind": 8,
+        "source": "report-needs",
+        "cause": "No draft for the slot of 2 Oct",
+        "evidence": "planning/reports/weekly",
+        "act": {
+          "label": "Draft now",
+          "cli": "pmos report draft weekly"
+        }
+      }
+    }
+  ]
+}

package/workspace/fixtures/today-api/seam-probe-kinds.json

@@ -0,0 +1,5 @@
+{
+  "_comment": "Row kinds that only pm-seams-test.js uses. No needs provider, no registerTodayCard owner and no slice may use them (d86-seams checks it).",
+  "plain": "seam-probe-plain",
+  "drawn": "seam-probe-drawn"
+}

package/workspace/guide/board.md

@@ -0,0 +1,81 @@
+---
+type: Guide
+title: "Board: the items of every initiative"
+description: "How to read and use the Board destination, filter it, add an item, move a card, release a batch of work items, and print the same Board with pmos board."
+timestamp: 2026-10-05
+---
+
+# Board: the items of every initiative
+
+The Board shows the items of all your work initiatives in one place. It has four columns: Todo, Doing, Review and Done. A card is one item. The Board is a view of the same items that the Breakdown of each initiative shows, so a card is always in the column that its row has in the Tree.
+
+A document initiative has no items, so it has no card and no place in the filter.
+
+## Open the Board
+
+Press **Board** in the navigation, or press `g` then `b`. In the older layout, choose Board in the command palette. The Board opens in a tab.
+
+## Filters
+
+Three filters decide which cards show. Press a button at the top, or choose an initiative from the list.
+
+- **Active** is the default. It shows an item that changed in the last days, an open item of an initiative that is in Now, and every item that is yours. The number of days is `stall_days` in `planning/plan-rules.json`.
+- **Mine** shows only the items that you own.
+- **An initiative.** Choose one from the list to see all its items. Choose **All initiatives** to go back to Active.
+
+Done shows the last 14 days under every filter, however long ago the item last changed. An older Done item is counted in the column ("3 older in the Tree") and stays in the Tree of its initiative.
+
+## Add an item
+
+Press **Add item**, the one main button of the Board. Type a title, choose the initiative and the stage, and press **Add** or Enter. The item goes into the ledger of that initiative, the same way as in the Breakdown.
+
+## Move a card
+
+- **On a wide screen,** drag a card to another column. A drop on Done is held for 8 seconds, so you can press **Undo**.
+- **On a phone,** press the card to open its sheet and press a state button. A card moves in 2 taps. From another column it takes 3: first press the column name, then the card, then the state.
+- **From the menu.** Press the three dots on a card, then choose Move to a state.
+
+When you move a card that an agent owns, the card reads "moved by you". The agent's own next move can change it again.
+
+A card that reads "Done · your call · not merged" is Done because you said so. The work in the repository is not merged yet.
+
+## Release
+
+When all the work items of a batch passed their checks, the Board shows a **Release** card above the columns. One press on **Release** grants the whole batch. It is one grant for the batch, and the grant names the initiative and the batch. The factory opens pull requests and never merges them.
+
+Only you can press Release. An agent cannot. When the grant writer of the workspace is not available, the button is disabled and the card says "Release arrives in Run 2."
+
+The same card also shows in Today when a batch is ready.
+
+## Today
+
+Today shows three things from the Board:
+
+- an item in Review that waits for you;
+- a batch that is ready for Release;
+- an item that an agent marked Done with no evidence. Open it and add evidence, such as `commit:<sha>` or `pr:<number>`.
+
+## Signals
+
+| signal | meaning |
+|---|---|
+| Blocked | the item has a reason that it cannot go on |
+| no evidence | an agent marked the item Done and gave no evidence |
+| late | the due date passed and the item is not Done |
+| moved by you | you moved a card that an agent owns |
+| Proposed | an agent proposed the item and you did not keep it |
+
+## From a terminal
+
+`pmos board` prints the same Board that the page shows. It reads the repository, so the workspace server does not need to run.
+
+```
+pmos board                      the Active filter
+pmos board --mine               your own items
+pmos board --init <initiative>  one initiative
+pmos board --json               the same answer as GET /api/board, for scripts
+```
+
+The text form prints one column per block, then one line for each card: the initiative, the stage, the title and the owner, and what needs your notice. The command only reads. It writes no line to any ledger.
+
+`pmos board` exits with 0 when it printed the Board, 1 when the initiative is not on the Board, and 2 when the command line is wrong.

package/workspace/guide/breakdown.md

@@ -0,0 +1,154 @@
+---
+type: Guide
+title: "Breakdown: an initiative's items"
+description: "How to break an initiative into items, move them in the Tree and on the Board, keep what an agent proposes, hand an item to an agent, and use pmos item from a terminal."
+timestamp: 2026-10-05
+---
+
+# Breakdown: an initiative's items
+
+An initiative's breakdown is the list of items that do its work. Each item has a title, an owner, a stage and a state. The state is Todo, Doing, Review or Done.
+
+The workspace keeps the items in `planning/runs/plan-items.jsonl` in the repository. Each change adds one line to that file. Nothing is changed or removed. The workspace page and the `pmos item` command use the same writer, so they always show the same items.
+
+## Open the Breakdown
+
+1. Select an initiative in the list.
+2. In the detail, press **Breakdown**. The row shows how many items are done, for example "7 of 12". It shows "no breakdown" when the initiative has no items, and "no breakdown · 9 proposed" when an agent proposed items that you did not keep yet.
+3. The Breakdown opens in a tab. Press **Tree** or **Board** at the top to change the view. The bar on the right shows the same count as the detail.
+
+## The Tree
+
+The Tree shows the stages of the initiative in order, for example Intake, Spec, Contract, Build and Evaluate. A stage shows only when it has items, items an agent proposed, or a step that is still owed.
+
+- **Stage header.** The name, CURRENT on the stage the initiative is at now, and a count such as "2 of 5 · 3 proposed". Press the arrow at the end of the header to collapse or expand the stage.
+- **Owed row.** "Owed: contract · agent" means that the workflow still needs that step from the agent (or from you). The row has the label DERIVED. You cannot edit it, move it or tick it. It goes away when the step is done.
+- **Show n done.** Done items are folded away. Press the line to show them.
+- **Owed steps are not shown.** When the workflow cannot be read, the Tree shows no owed rows. A note at the top says so and gives the reason. The owed rows come back the next time the workflow can be read.
+- **Flagged lines.** A line in `plan-items.jsonl` can have no effect: a broken line, an item added twice, or a Keep that was not written from the workspace page. The rows cannot show such a line, so a note at the top of the pane gives the number of flagged lines and the first three.
+- **Item row.** A grip, a box to tick, the title and one line with the owner, the due date and, when an agent made the last change, which agent ("by agent · sess-3"). At most two signals show (see Signals below). Press the title to open the item sheet. Press the three dots for a menu: Open, Move to a state, Move up, Move down, Hand to agent, Withdraw.
+- **Add item.** Press **Add item** at the end of a stage, type a title and press Enter. The field stays open for the next title. Press Enter in an empty field, or Escape, to close it. To add many items at once, paste a list with one title on each line. Markers such as `- `, `* `, `[ ] ` and `1. ` are removed. You can paste at most 50 lines.
+
+### Signals
+
+| Signal | What it means |
+|---|---|
+| Blocked | You or an agent gave a reason why the item cannot go on. The reason shows when you point at the signal, and in the item sheet. |
+| no evidence | An agent moved the item to Done without evidence, such as a commit or a pull request. Add the evidence in the item sheet, or move the item back. |
+| late | The due date is in the past and the item is not Done. |
+| Doing, Review | The state of the item, in the Tree only. On the Board, the column shows the state. |
+| moved by you | You moved an item that an agent owns. The agent sees the same signal. |
+| Proposed | An agent added the item and you did not keep it yet. A proposed item does not count in the progress. |
+
+### Keys in the Tree
+
+| Key | What it does |
+|---|---|
+| Arrow up, Arrow down (or k, j) | Move between rows and stage headers. |
+| Enter | Open the item sheet of the row. |
+| Space | Tick the row Done, or tick it back to Todo. |
+| n | Add an item after the row, or at the end of the stage. |
+| Alt+Arrow up, Alt+Arrow down | Move the row up or down. At the top or the bottom of a stage, the row moves into the stage before or after. |
+| Escape | Close the add field or the sheet. |
+
+To move an item with a mouse or a finger, drag its grip. Drop it between two rows to change its order, or drop it on a stage header to put it at the end of that stage. On a phone, hold the grip for a moment before you drag.
+
+Collapsing a stage is your own view. The workspace keeps it in this browser only. It writes nothing to the repository.
+
+## The Board
+
+The Board shows the same items in four columns: Todo, Doing, Review and Done. A card is always in the column of its state, so the Tree and the Board always agree.
+
+- Each card shows the title, the stage, the owner, the due date and, when an agent made the last change, which agent. The card's menu has Move to a state, Hand to agent and Withdraw. Open it with the three dots, or, on a wide Board with a mouse, where the cards have no three dots, right-click the card or press Shift+F10 on it.
+- An empty column says so, for example "Nothing in Review.".
+- The Done column shows the items done in the last 14 days. Older done items stay in the Tree, and the column says how many there are.
+- When the Board is wide enough, drag a card to another column to change its state. To make it wide on a desktop, fold the list or the detail with its `⟨` button ([Layout](layout.md#folding)).
+- When the Board is narrow, for example on a phone, it shows one column at a time. Press Todo, Doing, Review or Done above the cards to change the column. To move a card, press the card, then press the new state in the item sheet.
+
+If you move an item that an agent owns, the item shows "moved by you". The agent sees the same signal.
+
+## The item sheet
+
+The sheet shows every field of one item, from top to bottom:
+
+1. The state: Todo, Doing, Review or Done. Under it, two lines show only when they apply:
+   - "Proposed by agent · sess-3 on 5 Oct." with **Keep all**, for an item that an agent proposed. Keep all keeps every item of that agent's card.
+   - **Add evidence**, for an item that reads Done with no evidence. Type `commit:<sha>`, `pr:<number>`, `file:<path>` or `note:<text>` and press Enter. If the workspace refuses the reference, a message tells you why and your text stays in the field to correct.
+2. Title.
+3. Owner: You, Agent, a person (type the name) or a tracker (type the reference).
+4. Stage.
+5. After: the items that must finish first. Choose an item of this initiative, or type the id of an item in another initiative and press **Add**.
+6. Start and Due.
+7. Milestone.
+8. Blocked, and Blocked because. An item is blocked only when you give a reason.
+9. Note.
+10. **Hand to agent.**
+11. History: who made each change, what changed, and when.
+
+Each field saves by itself: a text field when you press Enter or leave it, the other fields when you change them. Each save adds one line to the file. Press **Close** or Escape to close the sheet.
+
+## Undo
+
+Done and Withdraw wait 8 seconds before they are saved. A message shows at the bottom with **Undo**. Press **Undo** to cancel. Nothing is saved. If you do not press it, the change is saved after 8 seconds. If you close the page during the 8 seconds, the change is saved at once.
+
+A tick back from Done to Todo is saved at once.
+
+## Items an agent proposes
+
+An agent can add items with `pmos item add`. Its items arrive as proposed. They show in the Tree and on the Board, but they do not count in the progress until you keep them.
+
+The Tree shows one card for each agent session, named by the session: "Agent · sess-3 proposed 9 items on 5 Oct." Today shows the same card in its needs-you list, and the Today count in the navigation counts it.
+
+- **Keep** keeps all the items of the card. Only you can keep items, and only from the workspace page. There is no command for it.
+- **Withdraw all** withdraws all the items of the card, with Undo.
+
+If the agent adds more items after the card shows, they stay proposed. The card shows the new count when it refreshes.
+
+Today also shows two other breakdown cards:
+
+- **no evidence**: an agent marked an item Done without evidence, such as a commit or a pull request. Open the item and add the evidence, or ask the agent to run its move again with `--evidence`.
+- **check**: a line in `plan-items.jsonl` that has no effect, for example a Keep that the workspace page did not write.
+
+## Hand to agent
+
+Press **Hand to agent** in the item sheet, or in the menu of a row or a card (the three dots, or a right-click or Shift+F10 on a card of a wide Board).
+
+1. The sheet shows one line: "Agent will: …" with what the agent does first and where it works, for example on a new branch. Press **Details** to read the full prompt, the branch and the folder.
+2. Press **Go** to start the session, or **Cancel**. Go starts exactly what you read. If the item changed after you read it, Go refuses, and you must press Hand to agent again.
+3. The session opens in a terminal tab. The agent reports with `pmos item`.
+
+If a session already works on the item, the sheet says "A session is already working on this item." and offers **Open session**.
+
+Nothing else starts a session from the Breakdown. A drag, a drop or a change of state never starts one.
+
+## Who made a change
+
+Each line in the file names who wrote it. The workspace shows it as:
+
+| Label | Who |
+|---|---|
+| you | You, from the workspace page or from your own terminal. |
+| agent · sess-3 | The agent session that the workspace started, from its terminal. |
+| agent (unknown) | A command run without a session the workspace started, and not at your own terminal. |
+
+The file records an agent with its full session token, for example `agent:sess-3.0a1b2c3d`. The workspace page gets only `agent:sess-3` and shows "agent · sess-3".
+
+An agent cannot keep its own items. An agent can withdraw only the items that it added; the items you added, only you can withdraw.
+
+A terminal that the workspace starts for an agent is marked as that agent's, so its commands are recorded as the agent even when they run at a terminal. Your own shell terminals are not marked, so their commands are recorded as you.
+
+## From a terminal: pmos item
+
+Every command takes `--json` for output a script can read, and `--root <dir>` to name the repository. Without `--root`, the command uses the repository of the current folder.
+
+| Command | What it does |
+|---|---|
+| `pmos item add <initiative> "<title>" --stage <stage>` | Adds an item. Options: `--due`, `--start` (YYYY-MM-DD), `--owner you\|agent\|person:<name>\|tracker:<ref>`, `--after <item>`, `--milestone`, `--note "<text>"`. |
+| `pmos item set <item> …` | Changes fields: `--title`, `--stage`, `--due`, `--start`, `--owner`, `--after`, `--milestone` or `--no-milestone`, `--note`, `--blocked "<reason>"`. Give `none` to clear a field. |
+| `pmos item move <item> todo\|doing\|review\|done` | Changes the state. An agent adds `--evidence commit:<sha>` (or `pr:`, `file:`, `session:`, `note:`) when it moves an item to Done. If it forgot, it runs the same move to Done again with `--evidence`. |
+| `pmos item withdraw <item>` | Withdraws an item. An agent can withdraw only its own items. |
+| `pmos item list <initiative>` | Lists the items by stage, with the progress. |
+
+A stage is its id or its label, for example `build` or `Build`. An item id is the initiative id, a dot, and ten characters, for example `partner-sso.k3j9x0p2qa`.
+
+The command decides who wrote the line from where it runs. It does not take a `--by` option.

package/workspace/guide/command-palette.md

@@ -0,0 +1,75 @@
+---
+type: Guide
+title: "Command palette"
+description: "How to use the ⌘K palette: run a command, see its command-line form, keep a note, ask the bound session, search Knowledge, Memory and the Guide, and use the compose line on a phone."
+timestamp: 2026-10-05
+---
+
+# Command palette
+
+The command palette is one box for three jobs: open something, run a command, or keep a note. Press **⌘K** (Ctrl+K on Windows and Linux) to open it. Press **Esc** to close it.
+
+## Rows
+
+Type in the box. The rows change as you type. They always come in this order:
+
+1. **Matched rows.** A command, an initiative, a repository, a session, a tab or a view whose name matches what you typed. A command shows its command-line form next to its name, for example `pmos item`. You can run the same command from a terminal.
+2. **Capture as note.** Keeps what you typed as a note.
+3. **Ask the session.** "Ask" and the name of a session. The session is the terminal tab you are in. When you are not in a terminal tab, it is the terminal of the selected initiative, or else the latest terminal of this repository. It shows only when a terminal tab is open.
+
+When nothing matches, **Capture as note** is the top row and is already selected. Press **Enter** to keep the note.
+
+Press **Up** and **Down** to move the selection. Press **Enter** to choose the selected row. You can also press a row.
+
+## Capture as note
+
+Capture as note keeps your words in one file and changes nothing else.
+
+- The file is `requirements/capture-YYYY-MM-DD-<n>.md` in the state folder of the selected repository. That folder is `pmos/state/` in a kit repository (one with `pmos/state/initiatives/` and no `planning/initiatives/`), and `planning/` in any other repository. It is the folder that holds the initiatives, so a later step finds the note there. `<n>` counts from 1 for each day.
+- The file has `type: Reference`, a title, a timestamp, `source: capture` and `by`. The text is the body, unchanged.
+- A file is never overwritten. When two notes race for one number, the second takes the next number.
+- A toast shows the name of the note. The palette closes.
+- When the note cannot be saved, the palette stays open, shows the reason, and keeps your text. Press **Enter** to try again.
+- Select a repository first. A note is kept in one repository, and is never kept in another one.
+
+The note is not a decision and not a requirement yet. A later step reads new notes and files each as a proposal for you to keep or drop.
+
+## Ask the session
+
+**Ask** sends what you typed to the session named on the row, then presses Enter. It works as if you had typed the text in that terminal. When the session is not connected, nothing is sent and the palette says so.
+
+## Portfolio reports
+
+Three commands write a report across every repository into the hub repository:
+
+| Command | What it writes |
+|---|---|
+| Portfolio report: weekly | The weekly report. |
+| Portfolio report: OKR | The OKR report. |
+| Portfolio report: matching… | The report on the initiatives whose names match words you type. A sheet asks for the words. |
+
+Nothing is written until you run one. When the report is written, the workspace says the path and opens the file as a tab. If a repository could not be read, the message names it. If no hub repository is set up, the message says so and nothing is written.
+
+## Search scopes
+
+The tabs under the box set where the search looks.
+
+| Scope | What it searches |
+|---|---|
+| All | Commands, initiatives, repositories, sessions, tabs and views. Strategy documents and decision records are also found here. |
+| Knowledge | Strategy documents, decision records, notes and governance files of the selected repository. Choose a row to open the document in a tab. |
+| Memory | The entries in Memory. Choose a row to read the entry in a sheet. |
+| Guide | The pages of this Guide. Choose a row to open the page in a tab. |
+
+The palette reads the lists of all three scopes when it opens. When a list cannot be read, the palette says which scope failed and why. The other scopes still work.
+
+## On a phone
+
+The palette opens as a sheet from the bottom edge. Each row is at least 48 pixels high, and the rows are reached by touch.
+
+There is no separate capture box. The scratchpad remains in one place only: the **compose line** at the bottom of a terminal tab. Type a message there and press **Send**. The text is typed into the session and the line clears. The line keeps your text for each session until you send it, so a message you did not finish is still there when you come back.
+
+## Related
+
+- [Live notes](live-notes.md) keeps a note for each day.
+- [Initiatives](initiatives-and-next-steps.md) explains what an initiative shows.