create-pmos 0.52.0 → 0.53.1

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.
+
+On a phone, the scratchpad is the **compose line** at the bottom of a terminal tab. (On a desktop, open it with **▲ scratchpad** under the dock's tabs.) 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.

package/workspace/guide/index.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Guide: start here"
-timestamp: 2026-10-04
+timestamp: 2026-10-06
 ---
 
 # Guide: start here
@@ -10,33 +10,44 @@ This guide describes the PMOS workspace as it works today. It ships with the app
 
 ## The screen
 
-The workspace has three columns. [Layout](layout.md) explains where things open.
+On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 
-1. **Navigation.** The repositories you added, with the list of the current mode under them. The default list is the initiatives of the selected repository. The settings and tools drawer at the bottom opens the other lists here.
-2. **The detail.** The item you selected: an initiative with its status, next steps and artifacts, or a skill, a schedule or a memory item.
-3. **Tabs.** Terminals, documents, conversations and guide pages.
+1. **The top bar.** Repository ▾, the four places, search (⌘K), Sync when the repository is not in sync, and Settings.
+2. **The place.** One of Today, Initiatives, Board or Reports. It fills the screen under the bar.
+3. **The detail.** The item you opened: an initiative with its status, next steps and artifacts, or the profiles. It opens beside the place and closes with ×.
+4. **The agent dock.** Terminals, documents, conversations and web pages. It is open on Today and a thin rail elsewhere.
 
-## The settings and tools drawer
+## Where things are
 
-| Item | What it opens |
+| You want | Go to |
 |---|---|
-| today | What is waiting for you now, with your feedback and the settings of the proactive engine. |
-| memory | What the repository remembers: decisions and notes kept in its memory ledger. |
-| knowledge | The decisions, concepts and skills of the repository. |
-| portfolio | Every initiative of every repository, grouped by domain. |
-| guide | This guide. |
-| validate | Checks that one repository agrees with itself, on your machine. It can also check with TypeSafe, which sends text only after you turn it on. |
-| focus | What is waiting on you, across all repositories. |
-| skills | Built-in and user skills. A built-in is read-only. |
-| scheduled tasks | Skills that run on a schedule. |
+| What is waiting for you now | Today |
+| The initiatives of a repository, or of every repository | Initiatives. Choose **All repositories** in Repository ▾ for every repository. |
+| The items of an initiative | Board, or Breakdown in the initiative detail |
+| Run reports | Reports |
+| Repositories, Profiles, New sessions (the default CLI and model), Validate consent, Theme | Settings |
+| Validate | Settings, under Validate consent: **Open Validate** |
+| A document, a decision record, a memory entry, a page of this guide | ⌘K, with its scope: Knowledge, Memory or Guide |
+| A report across every repository | ⌘K: Portfolio report |
+| A note, or a message to a session | ⌘K |
 
 ## Where to read next
 
-- [Layout](layout.md): the three columns and the rule for where a list or a detail opens.
+- [Start the workspace without a terminal](launcher.md): the PMOS app, the login item and `pmos launcher`.
+- [Layout](layout.md): the frame, the keys and the rule for where a list or a detail opens.
 - [Statuses](statuses.md): what each status means, where it comes from, and what you can change.
 - [Initiatives and next steps](initiatives-and-next-steps.md): the detail, the next steps, and the artifacts.
+- [Breakdown](breakdown.md): an initiative's items in the Tree and on the Board, the item sheet, Undo, Keep, Hand to agent and `pmos item`.
 - [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
 - [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
 - [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.
 - [Live notes](live-notes.md): take notes in a meeting, confirm each talking point, and what goes to Jev when you turn it on.
 - [Find knowledge without reading whole files](knowledge-graph.md): what `pmos kg` finds, its commands, how to read its numbers, and its limits.
+- [Initiatives: the Roadmap, the List and the initiative sheet](initiatives-screen.md): how to read and order the initiatives of a repository, open the sheet, make a new initiative, and review the cycle.
+- [Initiatives and the Roadmap: Now, Next and Later](initiatives-roadmap.md): what day one shows, how an agent proposes a move, and `pmos initiative` and `pmos measure` from a terminal.
+- [PM-only acts: what only you can do](pm-only-acts.md): which acts are yours, how the workspace checks that a press comes from your page or your terminal, and what to do when one is refused.
+- [PM-only lines: how the workspace checks your acts](pm-only-lines.md): how each act is recorded, what the Today card "A PM-only line is not attested" means, and the grants for a bulk lifecycle change and a Release.
+- [Breakdown › Timeline](timeline.md): an initiative's items on a time axis, split by stage, with milestones, today, and the at-risk flag when an item starts before its predecessor ends.
+- [Initiatives › Timeline](initiatives-timeline.md): when each initiative runs, one row per initiative, and how to reorder rows by their grip.
+- [Board](board.md): one Kanban for the items of every initiative, its filters, Release, and `pmos board`.
+- [Integrated work](integrated-work.md): how `pmos verify-work` turns a merged commit into Done, and what "Done · your call · not merged" means.

package/workspace/guide/initiatives-roadmap.md

@@ -0,0 +1,130 @@
+---
+type: Guide
+title: "Initiatives and the Roadmap: Now, Next and Later"
+description: "How an initiative gets a place in Now, Next or Later, what day one shows, how an agent proposes a move, how to add an initiative, how to record a measurement, and how to use pmos initiative and pmos measure from a terminal."
+timestamp: 2026-10-05
+---
+
+# Initiatives and the Roadmap: Now, Next and Later
+
+The Roadmap puts each initiative of a repository in one of three horizons:
+
+- **Now** — the work that is in progress. Only you put an initiative in Now.
+- **Next** — the work that starts when a place in Now is free.
+- **Later** — the rest. A new initiative starts at the top of Later.
+
+The order in a horizon is your priority order. An initiative can also have a **check-by** date: the day you want to look at it again.
+
+The Roadmap shows work lanes only: feature, discovery, chore, incident, content, prototype and the other lanes of the work group. A document lane (for example strategy) is a file, not a row. It is not on the Roadmap, in the list, in the sheet or in an export.
+
+## Where the Roadmap is kept
+
+The workspace keeps the places in `planning/runs/placements.jsonl` in the repository (`pmos/state/placements.jsonl` in a PM-artifacts repository). Each move adds one line to that file. Nothing is changed or removed. The workspace page and the `pmos initiative` command use the same writer, so they always show the same order.
+
+Each line records who wrote it and from where. You cannot set this yourself. The writer refuses a line that names its own writer.
+
+## Day one
+
+The first time you open the Roadmap, the file has no lines yet. The workspace then places each initiative from its activity:
+
+- An initiative with activity in the last 5 days reads **Now, unconfirmed**. Move it to confirm it, or move it to Next or Later.
+- An initiative with no activity for 45 days reads **dormant**, at the end of Later.
+- Every other initiative is in Later, the most recent activity first.
+- An accepted or stopped initiative is never in Now. It goes to the end of Later.
+
+The two numbers are `stall_days` and `dormant_days` in `planning/plan-rules.json`.
+
+While an initiative reads Now, unconfirmed, the Today list shows one **Review the cycle** row. The same row shows when an agent proposal waits for you and when a check-by date has passed.
+
+## Agent proposals
+
+An agent session can move an initiative to Next or Later, or change the order. The workspace writes each such move as a **proposal**. A proposal does not move anything. It shows on the Roadmap with the name of the agent session.
+
+- **Adopt** a proposal to make the move. Only you adopt a proposal.
+- **Drop** a proposal to close it. You or the agent that made it can drop it.
+
+When you move the same initiative yourself, your move replaces its open proposals.
+
+## Acts only you can do
+
+Two acts are yours only. The workspace refuses them from an agent session.
+
+- **Move to Now**, and any reorder or check-by of an initiative that is in Now.
+- **Adopt** an agent proposal.
+
+On the page, each press does one initiative. The page refuses a request that moves more than one initiative to Now. In a terminal, you type the initiative id (or the proposal id) to confirm. The command refuses with no interactive terminal.
+
+## Add an initiative
+
+Every initiative needs an anchor: a KR of the current period or a health budget `health:<id>` from `planning/okrs/health-budgets.md`. The workspace refuses an initiative with no anchor, from the page, from the terminal and from an agent session.
+
+The writer makes the record in `planning/initiatives/<id>.md` with its type, title, timestamp, lane and anchor. A chore also needs its intent in one paragraph. The new initiative starts at the top of Later. Commit the record to keep it.
+
+The writer refuses:
+
+- a lane that the repository does not have, or a document lane;
+- an anchor that names no KR or health budget;
+- an id that is already a record.
+
+### From a capture
+
+A capture note in `planning/requirements/capture-<date>-<n>.md` (`pmos/state/requirements/` in a PM-artifacts repository; a quick note from the command palette) becomes a **Proposed** row on the Today list: "Proposed: title · lane · anchor". The workspace proposes the title from the first sentence and an anchor when the words match a KR or a health budget.
+
+When the note matches a file in `planning/out-of-scope/`, the row says **matches an earlier rejection** and names that file. Read it before you add the initiative.
+
+Press **Add** to make the initiative, or use `pmos initiative new --from <capture>`. After that, the capture leaves the list.
+
+### No anchor
+
+An old record with no `parent_kr` shows on the Today list as "<title> has no anchor". Add an anchor to its record.
+
+## Break this down
+
+An empty Breakdown offers **Break this down** with a starter list. The list is in `planning/work-starters.md`. Change that file to change the list. See [Breakdown](breakdown.md).
+
+## Export a breakdown
+
+The export gives an initiative's breakdown as markdown: the title and anchor, then one heading per stage, then each item with its state, owner and dates. It writes no file. Two exports of the same breakdown are the same text.
+
+## Measurements
+
+A measurement is the value of a KR or a health budget on a date, with its source. The workspace keeps measurements in `planning/runs/measurements.jsonl`. The List shows the latest measurement next to each anchor.
+
+Every measurement needs a source: the file the value comes from and its commit, as `<path>@<commit sha>`. The writer refuses a measurement with no source. An agent can record a measurement, because a measurement is evidence, not a decision. The `measure` skill tells an agent how to do this.
+
+## From a terminal: pmos initiative
+
+`pmos initiative` uses the same writers as the page. You need no running server.
+
+| Command | What it does |
+|---|---|
+| `pmos initiative new "<title>" --lane <lane> --anchor <anchor> [--intent "<text>"] [--id <id>]` | Makes the record and puts it at the top of Later. |
+| `pmos initiative new --from <capture> [--anchor <anchor>]` | Adds the initiative a capture proposes. |
+| `pmos initiative now <id>` | Moves it to the end of Now. You only: type the id to confirm. |
+| `pmos initiative next <id> [--top]` | Moves it to the end of Next, or to its top. |
+| `pmos initiative later <id> [--top]` | Moves it to the end of Later, or to its top. |
+| `pmos initiative top <id>` | Moves it to the top of its horizon. |
+| `pmos initiative up <id>` | Moves it one place up. |
+| `pmos initiative down <id>` | Moves it one place down. |
+| `pmos initiative check-by <id> <YYYY-MM-DD\|none>` | Sets or clears its check-by date. |
+| `pmos initiative adopt <proposal>` | Makes the move an agent proposed. You only: type the proposal id to confirm. |
+| `pmos initiative drop <proposal>` | Closes a proposal. |
+| `pmos initiative list` | Shows Now, Next and Later in order, with the open proposals. |
+| `pmos initiative export <id>` | Writes the breakdown as markdown to the terminal. |
+
+Every command takes `--json` and `--root <dir>`. In an agent session, `next`, `later`, `top`, `up`, `down` and `check-by` write a proposal. The command does not accept `--by` or `--via`.
+
+The command exits 0 when it is done, 1 when it refuses, and 2 for a usage error.
+
+## From a terminal: pmos measure
+
+| Command | What it does |
+|---|---|
+| `pmos measure add <anchor> <value> --source <path>@<sha> [--target <number>] [--unit <unit>] [--as-of YYYY-MM-DD]` | Records a measurement. With no `--as-of`, the date is today. |
+| `pmos measure list [<anchor>]` | Shows the measurements, oldest first, for each anchor. |
+
+Put an anchor with a space in quotes: `pmos measure add "KR 2.1" 41 --source planning/okrs/q4.md@1a2b3c4`.
+
+## The checks
+
+CI runs `scripts/check-placements.js` and `scripts/check-measurements.js` on each pull request. Each check fails on a line that is not JSON, a line that breaks the format, and one event id with two different lines. It reports, and does not fail on, a line the Roadmap ignores, for example an agent line that adopts a proposal.

package/workspace/guide/initiatives-screen.md

@@ -0,0 +1,89 @@
+---
+type: Guide
+title: "Initiatives: the Roadmap, the List and the initiative sheet"
+description: "How to read and order the initiatives of a repository on the Roadmap and the List, open the initiative sheet, make a new initiative, and review the cycle."
+timestamp: 2026-10-05
+---
+
+# Initiatives: the Roadmap, the List and the initiative sheet
+
+The Initiatives place shows every initiative of the selected repository. Each initiative is in one horizon: Now, Next or Later. A horizon is an order, not a date. The order and the horizon of each initiative are lines in `planning/runs/placements.jsonl`. The workspace page and the `pmos initiative` command write the same lines.
+
+Press **Roadmap** or **List** at the top to change the view. The workspace keeps your choice in this browser.
+
+## The Roadmap
+
+The Roadmap has three columns: Now, Next and Later. Each column is a ranked list of cards. The line at the top reads, for example, "Now · 5 KR · 3 health". It counts the initiatives in Now by what they serve: a key result (KR) or a health budget. When the rules set an advisory cap for Now, the line shows it. The cap only advises. It never stops a move.
+
+A card shows the title, the stage, "7 of 12" for the items done, the check-by date when a card in Now has one, and the reason when the initiative is not on track. An initiative that is on track shows no health text.
+
+### Move a card
+
+- **Drag.** Hold the grip at the start of the card, then drop it in a column. On a touch screen, hold for a moment before you drag.
+- **Keyboard.** Select the card and press Alt and the Up or Down arrow.
+- **The card menu.** The menu has: Open, To top, Up, Down, Move to Now, Move to Next, Move to Later and Set check-by. On a phone, press the three dots on a card. Two presses move a card up one place. On a desk the three dots are not on the card, and a line above the columns says so. Right-click the card, or press the menu key while it has focus. Set check-by is on the cards of Now only. A card that leaves Now loses its check-by date.
+
+Only you can move an initiative into Now. The workspace writes the line as yours. If the server refuses a move, the card goes back and a message tells you why.
+
+### Unconfirmed, proposed and dormant
+
+- **unconfirmed.** An initiative that reads Now only because it is active, with no line from you. Confirm it in the Cycle review.
+- **proposed.** An agent proposed a move. It changes nothing until you keep it in the Cycle review.
+- **Dormant.** An initiative with no activity for a long time. Press the dormant line under Later to show them.
+
+## The List
+
+The List groups the initiatives by objective, and inside each objective by anchor. An anchor is the KR or the health budget that the initiative serves. A group shows its measured value only when the repository has one: for example "41% on 2 Oct → 55%". A group with no measured value shows none.
+
+Press **Select** (or the `x` key) to choose rows. The bar shows what you can do with the choice:
+
+- **Move to Next** and **Move to Later**.
+- **Change lifecycle.** A sheet opens with the state to set: On hold, Closed, Cancelled or Active. It opens on On hold. Press **Confirm** to write it. This is off until the workspace can write one lifecycle line for each initiative on your press. Until then the button is disabled and says that the act arrives in Run 2. You can still change one initiative at a time in its sheet.
+
+You can select 20 initiatives at most. The List never moves several initiatives into Now at once, and never changes an anchor for several. Those are one-at-a-time acts.
+
+## The initiative sheet
+
+Press a card or a row to open its sheet. On a desk the sheet is about 70% of the width. On a phone it fills the screen.
+
+From the top:
+
+1. The horizon, the health reason when there is one, and the More button.
+2. Line 1: the stage and who the initiative waits on. Line 2: the stage steps, as a row of stages.
+3. One line of text: "Waiting on you: approval" with **Open gate**, or "Waiting on agent: build" with **Hand to agent**. When nothing is owed it says so.
+4. Three tabs: **Breakdown**, **Files** and **History**. The Breakdown tab is the same Breakdown as in its own tab, and it shows here too.
+
+An initiative that is finished reads "Accepted". An initiative on hold, closed or cancelled reads that word instead of a stage. After 5 days with no activity, the line adds "idle 5 d".
+
+The More button in the sheet has:
+
+- **Move to Now**, **Move to Next**, **Move to Later**.
+- **Set check-by.** On an initiative in Now. A date by which you want to look again. The Cycle review lists the dates that passed.
+- **Lifecycle.** On hold, Close, Mark cancelled or Reopen. Only you can change it. A sheet asks you to confirm and gives you a field for the reason.
+- **Change anchor.** Only you can change it. Enter a KR id such as KR 2.1, or health: and an id. It rewrites the anchor line in the frontmatter of the initiative record and nothing else.
+- **Copy CLI.** Copies the `pmos initiative` command for the same act.
+- **Export breakdown.** Copies the Breakdown as text.
+
+## Make a new initiative
+
+Press **New initiative**. Give a title, choose a lane and choose an anchor. An initiative with no anchor is refused. The new initiative starts in Later. When it is real work, move it to Now yourself.
+
+The same act from a terminal is `pmos initiative new "<title>" --anchor <kr>`.
+
+### Break this down
+
+An initiative with no items shows **Break this down** in its Breakdown. When the repository has a file `planning/work-starters.md`, its bullet lines show as a starter list, and **Add n items** adds them all. You can also press **Break this down** and type the first item.
+
+## Today: the triage card and the Cycle review
+
+- **Triage.** "Proposed: Partner SSO · new feature · KR 2.1" with **Add**. An agent read a capture and proposed an initiative. One press of Add writes it, in Later.
+- **Cycle review.** The card opens a sheet with three lists. Now, unconfirmed: **Confirm** keeps it in Now, **Move back** puts it in Later. Agent proposals: **Keep** applies the move as your line, **Drop** removes it. Check-by dates passed: set a new date, or move the initiative to Next. Each press acts on one initiative: there is no Confirm all, because Move to Now is never done in bulk.
+- **Monthly kill check.** The same sheet opens from the monthly check of the kill conditions, with the file that the check reads.
+
+## Keys
+
+| Key | What it does |
+|---|---|
+| Alt and Up or Down | Moves the selected card up or down one place. |
+| `x` | Starts and ends Select in the List. |
+| Escape | Closes a menu or a sheet. |

package/workspace/guide/initiatives-timeline.md

@@ -0,0 +1,57 @@
+---
+type: Guide
+title: "Initiatives › Timeline: when each initiative runs"
+description: "How to read the Timeline of Initiatives, what draws a bar, how to reorder rows, and what to do on a phone."
+timestamp: 2026-10-05
+---
+
+# Initiatives › Timeline
+
+The Timeline shows each initiative as a row, with its work laid out by month. Use it to see when work runs and which initiatives have no dates yet.
+
+The Roadmap answers "in what order?". The Timeline answers "when?". The Timeline uses the placement lines that the Roadmap uses. An initiative that no line has placed reads Later. Held, closed and cancelled initiatives have no row here.
+
+## Open the Timeline
+
+1. Open **Initiatives**.
+2. In the View control, press **Timeline**. The other views are **Roadmap** and **List**.
+
+## Read the chart
+
+- **Months.** The months run across the top. The chart starts at the first month that holds a date and ends at the last. It always includes today, and it is at least three months and at most 24 months wide. Today is the date on the machine that runs the workspace. If the dates reach outside 24 months, the chart opens a few months before today, and a note under it says that a date outside those months is cut off. The dates in a row's meta line stay complete.
+- **Groups.** The rows are in three groups: Now, Next and Later. A group shows only when it has a dated initiative. Inside a group the rows follow the placement lines. A row that no line has placed comes after the rows that have one, in id order.
+- **Row.** A row has a grip, a title, and one line with the lane, the number of items done ("7 of 12") and the dates the bar covers.
+- **Bar.** The bar runs from the earliest start date to the latest due date of the initiative's items. It is split by stage, so you can see when Intake ends and when Build starts. A stage with no dated item has no part of the bar.
+- **Diamond.** A milestone item shows as a diamond on its due date.
+- **Today.** One line crosses the chart at today's date. On a chart wider than the screen, the chart opens with today in view.
+- **Stages.** Press the arrow at the start of a row to show one row for each stage. A stage row shows the stage, how many items are done ("Build · 3 of 5") and its own bar. The arrow reads "Show stages of …" or "Hide stages of …" for a screen reader.
+- **Not dated.** An initiative with no dated item has no bar. It sits below the chart, in the heading **Not dated**, in its group. It shows only the order it carries. Give one of its items a start or a due date in the Breakdown and its bar appears.
+
+If no initiative has a dated item, the Timeline says so and shows no chart.
+
+## What the Timeline shows
+
+- **Work lanes only.** An initiative in a document lane (a strategy, a report, a decision record) has no row. You reach those as files.
+- **Held, closed and cancelled initiatives** have no row.
+- **Dates come from items.** Nothing on the Timeline has a date of its own. A date is the start or the due date of an item. You set it on the item, in the Breakdown. See [Breakdown](breakdown.md).
+- **Bars do not move.** You cannot drag a bar to change a date. A drag that starts on a bar writes nothing.
+
+## Reorder a row
+
+A row reorders inside its own group. It never changes horizon here: to move an initiative to Now, Next or Later, use the Roadmap.
+
+- **Grip.** Hold the grip at the start of the row and drag it up or down. On a phone, hold the grip for a moment first, then drag. The row is placed after the row above it.
+- **Keyboard.** Put the focus on the title and press Alt+ArrowUp or Alt+ArrowDown.
+- **Menu.** Press **⋯** on the row. The menu has **Open**, and then **To top**, **Up** and **Down** when the row can move that way. A row alone in its group has only **Open**.
+
+A move writes one line to `planning/runs/placements.jsonl` (`pmos/state/placements.jsonl` in a kit repository). The line says who moved the row: it is you, from the page. A row that no line has placed cannot be named by a line that follows it. When you move a row next to such a row, the move writes one line for each row from the first row it changes to the last row that needs a line, and a message says how many. After that, those rows keep the order you see. If the workspace refuses the move, a message gives the reason and the rows stay in the order the file has.
+
+Moving a row inside Now is a placement into Now. If the workspace asks for your press for it, the message says so.
+
+## On a phone
+
+At 390 px the chart scrolls sideways inside its own box. The page does not scroll sideways. The name of each row stays at the left edge while the months move under it. Every control on a row, the grip, the arrow and the **⋯** button, is at least 44 px high and wide.
+
+## Keep the view current
+
+The Timeline reads again about every ten seconds while the page is visible, and when you return to the page. A change made in a terminal, or by an agent, shows without a reload.