create-pmos 0.52.0 → 0.53.0

package/workspace/guide/layout.md

@@ -1,27 +1,101 @@
 ---
 type: Guide
 title: "Guide: layout"
-description: "The three workspace columns: navigation, detail and tabs, and what each one holds."
+description: "The frame: one top bar, the place on screen, the detail and the agent dock; the phone tabs; the keys; and the older layout."
 timestamp: 2026-10-05
 ---
 
 # Guide: layout
 
-On a desktop screen the workspace has four columns. They are, from left to right, the repository rail, the list, the detail and the tabs. A phone, and the address option `?layout=legacy`, keep the older layout with three columns: navigation, detail and tabs. The rest of this page describes those three columns.
+On a desktop screen the workspace is one frame. It has one top bar, the place on screen under it, the detail when you open one, and the agent dock at the right. There is no left sidebar.
 
-## The repository rail, the list and the tools
+## The top bar
 
-The rail is 64 pixels wide and shows one tile for each repository. A dot on a tile means that repository has something that needs you. The selected repository has no dot, because the list beside it shows what needs you. The `+` tile adds a repository and the menu button opens the tools: knowledge, memory, skills, scheduled tasks, validate, the guide and the others.
+The top bar has these parts, from left to right:
 
-A tool opens as a tab, not in place of the list. Choose the same tool again and the existing tab comes to the front.
+- **Repository ▾** names the current repository. Press it to choose another repository, or **All repositories** to see the work of every repository at once. All repositories replaces the old Portfolio mode.
+- **Today, Initiatives, Board and Reports** are the four places. Press one to show it. The Today count shows how many items need you.
+- **Search or capture ⌘K** opens the command palette. Type to find an initiative, a repository, an open tab or a command.
+- **Sync** shows only when the current repository is not in sync with its remote. Press it to fetch, bring in the work of the other machine, record your changes and push. When the repository is in sync, Sync is not shown.
+- **Settings** opens the settings of the workspace.
 
-Press ⌘K (Ctrl-K) to jump to anything: an initiative, a repository, an open tab, a session or a tool. Type to filter, use the arrow keys to choose, and press Enter. Esc closes it.
+Each place is drawn when its run is built. Until then the place says which run brings it, for example "Board arrives in Run 4."
+
+## Settings
+
+Settings holds settings only, in five sections:
+
+- **Repositories**: every registered repository. Press a repository to make it the current one. Press its ⋯ for **Rename** or **Remove from PMOS**. Each asks in a sheet, and a remove asks you to confirm. **Add repository** shows the scan of a folder before you add it.
+- **Profiles**: the Claude profiles a session can start with. They open in the detail.
+- **New sessions**: the default CLI and the default model for a new session in the dock.
+- **Validate consent**: the consent of the current repository. Turn it on or off here. **Open Validate** opens the Validate page as a tab.
+- **Theme**: Dark or Light.
+
+Your work is never in Settings. It is in Today, Initiatives, Board and Reports.
+
+## The agent dock
+
+The dock holds your terminals, documents, conversations, skills and web pages. It is open on Today. On every other place it is a 44-pixel rail at the right edge.
+
+- Press ⌘J (Ctrl-J), or the button on the rail, to open the dock. Press ⌘J again, or the fold button in the dock, to fold it to the rail.
+- The dock never opens by itself. A tab that opens while the dock is a rail waits in the dock until you open it.
+- **＋ Session** in the dock starts a new session. Its menu also has **Session with options** and one item for each skill of the repository. A skill opens in its own tab in the dock.
+- The Web button in the dock opens a web page in a tab.
+
+Folding the dock, or going to another place, does not touch your terminals.
+
+## The detail
+
+The detail shows one item in full, for example an initiative or the profiles. It opens as a column between the place and the dock when you open an item. Press × at its top, or press Esc, to close it.
+
+## Questions
+
+When the workspace needs an answer from you, for example the name for a rename or a confirmation before a remove, it opens a sheet. A sheet has a title, the question, and two buttons: the one that does it and **Cancel**. Esc, the close button and a press outside the sheet all mean Cancel. The workspace never uses the browser's own dialogs.
+
+## Colour and size
+
+The workspace is neutral. A primary button is the text colour on the page colour, in both themes. The one brand colour marks the Today dot and the Today count, and nothing else. The bar, the dock and the bottom bar follow the theme; only a terminal stays dark. Corners are square. Controls are icons from one set, not text symbols. On a touch screen every field is 16 pixels, so the phone does not zoom when you tap it, and every control is at least 44 pixels high.
 
-Press ⌘↵ (Ctrl-Enter) to enter Focus. The rail and the list go out of view, the active tab takes the width, and the detail stays as a narrow slice on the right. Press Esc or Navigate to return. Focus does not restart a terminal.
+## Keys
 
-Today is a tool tab. It shows what needs you, with an action and a reason to dismiss each item, what is being prepared, and a Repository / All switch.
+| Key | What it does |
+|---|---|
+| g t, g i, g b, g r | Show Today, Initiatives, Board or Reports. |
+| ⌘K (Ctrl-K) | Open or close the command palette. |
+| ⌘J (Ctrl-J) | Open or fold the dock. |
+| j, k | Move down or up the rows of the place. |
+| Enter | Open the row that has the focus. |
+| Space | Tick the row. Space never opens a row. On another button of the row, for example ⋯, Space presses that button. |
+| a | Do the main action of the row, when the row has one. |
+| x | Dismiss the row, when the row can be dismissed. |
+| Alt-Up, Alt-Down | Move the row up or down, when the row can move. |
+| Esc | Close the palette, then the detail. In the open dock, Esc closes the tab in front. After a click in the place or the detail, Esc does not close a tab. |
 
-Each tool tab shows a board: Today, All repos, Knowledge, Memory, Skills, Scheduled tasks, Validate, the guide and Reports. Reports is in the menu, under Library, and lists only the run reports that exist. If a part of a board has no data behind it, the board does not show that part, or it says that the data is not read.
+A key that you type in a field, or in a terminal, goes to the field or the terminal.
+
+## On a phone
+
+A phone shows one panel at a time. The tabs at the bottom are **Today, Initiatives, Board, Reports and Agent**. Agent shows the dock, with your terminals. Search or capture ⌘K is pinned at the top of Today.
+
+The bar at the top has Back (when you are deeper than a tab), Repository, the name of the screen, ⌘K, Sync (only when the repository is not in sync) and Settings. Settings opens over the current tab. Back returns to the tab.
+
+Every row has a visible ⋯ button. Every control is at least 44 pixels high. Nothing works only when you hover.
+
+## The older layout
+
+The address options `?layout=legacy` and `?fixture=cockpit` keep the older layouts. The rest of this page describes them. In the cockpit, the workspace has four columns: the repository rail, the list, the detail and the tabs. With `?layout=legacy` it has three columns: navigation, detail and tabs.
+
+### The repository rail, the list and the tools
+
+The rail is 64 pixels wide and shows one tile for each repository. A dot on a tile means that repository has something that needs you. The selected repository has no dot, because the list beside it shows what needs you. The `+` tile adds a repository. The rail has no tools menu: the repository list and Validate are in Settings, and everything else is in ⌘K.
+
+Today, Validate, live notes and Add repository open as a tab, not in place of the list. Choose the same one again and the existing tab comes to the front.
+
+Press ⌘K (Ctrl-K) to jump to anything: an initiative, a repository, an open tab, a session or a tool. Type to filter, use the arrow keys to choose, and press Enter. Esc closes it.
+
+In the older layouts, Today is a tab. It shows what needs you, with an action and a reason to dismiss each item, what is being prepared, and a Repository / All switch.
+
+If a part of a board has no data behind it, the board does not show that part, or it says that the data is not read.
 
 The `+` tile on the rail opens Add repository as a tab. The tab shows the scan of the folder before you add it.
 
@@ -37,23 +111,23 @@ Each tab shows a dot, its title and, under the title, its initiative and its ses
 
 If many tabs are open, the strip stays one row and scrolls sideways. Use the mouse wheel on the strip to scroll it. The tab in front always scrolls into view. Press `⇅ tabs at side` to show the tabs as a list down the left of the tabs column. In the list, each tab is one row, with its title, its initiative and session, and ×. The `+ session` button is at the top of the list, and the other controls are at the bottom. Press `⇆ tabs on top` to go back to the strip. The workspace remembers your choice in this browser. A phone and `?layout=legacy` always show the strip.
 
-## Navigation
+### Navigation
 
-The first column holds the list of repositories. Under it is the list for the current mode. When you choose a repository, its initiatives appear there. When you choose an item in the settings and tools drawer, its list replaces the initiatives. Choose a repository again to return to its initiatives.
+The first column holds the list of repositories. Under it is the list for the current mode. When you choose a repository, its initiatives appear there. 
 
 If you have many repositories, the repository list scrolls inside its own space. The list under it stays on screen.
 
 Drag the right edge of the column to change its width. Double-click the edge to restore the default width.
 
-## Detail
+### Detail
 
-The second column shows one item in full. Choose an initiative, a skill, a schedule or a memory item, and its detail opens here.
+The second column shows one item in full. Choose an initiative or the profiles, and its detail opens here.
 
-## Tabs
+### Tabs
 
 The third column holds your terminals, documents, conversations and guide pages. Folding or resizing the other columns does not touch your terminals.
 
-## Open a file
+### Open a file
 
 Press a file anywhere in the workspace to open it in a tab. Any text file opens, whatever its extension.
 
@@ -67,30 +141,22 @@ A tab for a file that is not markdown is read-only. It has no edit, diff or save
 
 If a file cannot be shown, the tab says why. The reasons are: the file is binary, it is larger than 2 MB, it is not valid text, or it is outside the workspace.
 
-## The rule for where things open
+### The rule for where things open
 
 A list or a directory opens in the navigation column, under the repository list. A detail opens in the detail column. A file-like row opens in a tab, as any document does.
 
 | Item | Kind | Opens in |
 |---|---|---|
 | Initiatives | list | navigation |
-| Memory | list | navigation |
-| Knowledge | list | navigation |
-| Portfolio | list | navigation |
-| Guide | list | navigation |
 | Validate | list | navigation |
-| Today | list | navigation |
-| Focus | list | navigation |
-| Skills | list | navigation |
-| Scheduled tasks | list | navigation |
 
 What a row in a list opens:
 
-- A row in Initiatives, Portfolio or Focus opens the initiative in the detail column.
-- A row in Skills, Knowledge, Guide or Validate opens the file in a tab, beside your terminals.
-- Scheduled tasks, Memory and Today are used inside the list. They have no separate detail.
+- A row in Initiatives opens the initiative in the detail column.
+- Validate opens as a tab, beside your terminals.
+- A Knowledge, Memory or Guide result in ⌘K opens a document in a tab, or a memory entry in a sheet.
 
-## Folding
+### Folding
 
 On a desktop screen, the list and the detail each have a `⟨` button. The list's button is at the right of `+ New initiative`. The detail's button is at its top right. Press it to fold that column to a thin strip. Press the strip to open the column again. The rail does not fold.
 
@@ -102,10 +168,10 @@ In the older layout:
 
 The workspace remembers which columns are open and how wide the navigation column is.
 
-## Light theme
+### Light theme
 
-In the light theme, the tabs column stays dark, because a terminal is dark in both themes. The tab strip and the bar under the tabs use light text on that dark band.
+In the light theme, the whole workspace is light: the top bar, the dock, the tab strip and the bar under the tabs follow the theme. Only the terminal stays dark, because a terminal is dark in both themes.
 
-## On a phone
+### On a phone
 
-A phone shows one panel at a time. The bottom bar moves between them.
+In the older layouts, a phone also shows one panel at a time. The tabs at the bottom move between them.

package/workspace/guide/live-notes.md

@@ -12,7 +12,7 @@ The Live notes view takes notes during a meeting. Each thing that is said become
 ## Open the view
 
 1. Select the repository in the navigation column.
-2. Open the menu and select **live notes** under **Library**. The view opens as a tab for that repository.
+2. Press ⌘K, type **live notes** and press Enter. The view opens as a tab for that repository.
 3. Press **New session**. A session is one meeting.
 
 If the repository has more than 255 open initiatives, the view asks you to select an anchor first. The session then uses only the initiatives of that anchor.
@@ -57,8 +57,8 @@ A point that looks like a secret, such as a key or a token, is withheld. The vie
 
 Jev checks a point only when all three of these are true:
 
-1. A TypeSafe key is saved (open **validate** in the settings and tools drawer).
-2. Validation is turned on for this repository (also under **validate**).
+1. A TypeSafe key is saved (open Settings, then **Open Validate** under Validate consent).
+2. Validation is turned on for this repository (also in Settings, under Validate consent).
 3. **Check with Jev** is on in the Live notes view. It applies to this repository only.
 
 If one is missing, the view says which one, in words.

package/workspace/guide/pm-only-acts.md

@@ -0,0 +1,89 @@
+---
+type: Guide
+title: "PM-only acts: what only you can do"
+description: "Which acts only the PM can do, how the workspace checks that a press comes from your page or your terminal, what to do when a press is refused, and what an agent can and cannot write."
+timestamp: 2026-10-05
+---
+
+# PM-only acts: what only you can do
+
+Some acts decide what the work is and when it is done. Only you, the PM, can do them. An agent cannot do them, even when you ask it to in a chat.
+
+## The acts
+
+| Act | Where you do it |
+|---|---|
+| Accept a run, approve or return a review, approve a document | Not on the page yet. In your own terminal, run `node scripts/record-acceptance.js`. |
+| Accept or send back a step that an agent ran | Not on the page yet. A later run adds it. |
+| Approve a contract | Not on the page yet. In your own terminal, run `node scripts/log-run.js` with `PM_approved: true` in the contract. |
+| Record a D60 disposition of a prototype | Not on the page yet. A later run adds it. |
+| Hold, close, cancel or reopen an initiative | The initiative's lifecycle menu |
+| Keep the items an agent proposed | The Keep card in the Breakdown or on Today |
+| Move an initiative to Now, or adopt an agent's proposal to move it | Initiatives (arrives with the Initiatives screen) |
+| Change the anchor (`parent_kr`) of an initiative | The document editor, or the confirm step of Add a repository |
+| Bind a session to an initiative | The session's initiative menu, or ＋ session on an initiative |
+| Issue a report | Reports (arrives in Run 5) |
+| Release a batch of factory work | The Board (arrives in Run 4) |
+
+Each line that the workspace server writes for one of these acts says who wrote it (`by: pm:wawan`) and how (`via: ui` from the page, `via: cli` from a terminal).
+
+## How the workspace checks a press
+
+When the workspace server starts, it makes a new random value for this launch. It puts the value in the page that it serves to your browser. It does not put the value in any terminal session, and it does not write the value to a log.
+
+Each press from the page sends three things: the page's own address (the Origin), the launch value, and the request. The server refuses the press when:
+
+- the request has no Origin, or the Origin is a different site or a different port;
+- the launch value is missing or wrong.
+The server also refuses a request that sets a field that only the server sets, for example `by`, `via`, `at` or `grant`.
+
+A press that is refused writes nothing.
+
+The terminal on the page sends the launch value when it connects. A session that you start with ＋ session on an initiative is bound to that initiative only when the value is correct. If it is not correct, the session starts without an initiative and the terminal says why.
+
+### When a press is refused
+
+If the workspace started again after you opened the page, the page reads the new launch value and sends your press again, one time. You do not have to do anything.
+
+If a press shows "the workspace restarted, so reload the page, then try again", reload the page, then press again.
+
+## Acts from a terminal
+
+A command that does a PM-only act asks you to type a word first, usually the initiative id. Type the id exactly, then press Enter. If the text does not match, the command writes nothing.
+
+The command refuses the act when:
+
+- it runs inside an agent session (the session has a `PMOS_SESSION` value);
+- it does not run in an interactive terminal, for example in a pipe or a script.
+
+Any other command that runs without a terminal is recorded as `agent:unknown`, not as you.
+
+## Change many initiatives at once
+
+You can change the lifecycle of up to 20 initiatives in one press. The press makes one grant for the change, and each lifecycle line names that grant. Until the grant writer is available, the workspace refuses the press and writes nothing.
+
+You cannot move initiatives to Now or change an anchor in one press for many initiatives. Do these one at a time.
+
+## What an agent can write
+
+An agent can:
+
+- add items, and order, date, start and finish the items of its session (with evidence);
+- move an item that you handed to that session with Hand to agent. It cannot move any other item that you own;
+- create an initiative (it lands in Later), write report text, and record a measurement with a source;
+- propose a change for you to keep or drop.
+
+An agent cannot:
+
+- do any act in the table above;
+- change the title, stage, dates or owner of an item that you own (owner "you"), or mark it blocked. It asks you instead;
+- withdraw an item that it did not add.
+
+## What this does not prevent
+
+A program that runs as your own user can read the page, as your browser does, and send a press. A program that fakes a terminal can type the id. The workspace closes the paths that an agent's tools use by default.
+
+Some paths are still open:
+
+- A program can connect to the terminal socket without the launch value. It cannot bind a session to an initiative, but it can start a session and type into any terminal, including your own shell. A `pmos` command that it types in your shell runs as you.
+- An agent's `pmos item` commands are not yet checked against the initiative that its session is bound to, and a session value that names no session is not refused. The repository's checks find the other lines later, when they reach a pull request. See [Breakdown](breakdown.md) for the items and the Keep card.

package/workspace/guide/pm-only-lines.md

@@ -0,0 +1,61 @@
+---
+type: Guide
+title: "PM-only lines: how the workspace checks your acts"
+description: "Which acts only you can do, how each one is recorded, what the Today card 'A PM-only line is not attested' means, what to do about it, and the grants for a bulk lifecycle change and a Release."
+timestamp: 2026-10-05
+---
+
+# PM-only lines: how the workspace checks your acts
+
+Some acts are yours only. An agent can propose them, but it cannot do them. These acts are PM-only:
+
+- Move to Now, and adopt an agent's proposal.
+- Issue a report.
+- Accept a run, approve or return a review, approve a document or a contract, and record a D60 disposition.
+- Change the lifecycle of an initiative.
+- Change the anchor of an initiative.
+- Keep the items that an agent proposed.
+- Release a factory batch.
+
+Each act adds one line to a ledger in the repository. The line records who did the act (`by`) and how (`via`). `via` is `ui` for a press in the workspace and `cli` for a command that you confirm at your own terminal.
+
+## How the acts are protected
+
+- **In the workspace.** A press sends a value that the workspace makes each time it starts. A request without it is refused.
+- **At a terminal.** A PM-only `pmos` command asks you to type a confirmation. An agent's tool has no terminal, so the command refuses it.
+- **In an agent session.** The cockpit mod stops an agent that calls a PM-only route, runs a PM-only `pmos` command, or loads a ledger's writer from its own code.
+- **In CI.** The Initiative Gate runs `scripts/check-pm-lines.js`. It fails on a PM-only line that is not attested (see below). It needs the full git history: on a shallow clone it fails and asks for `fetch-depth: 0`.
+
+These checks find a forged line. They do not make a forgery impossible. A program that runs as your own user can still write a line that looks like yours.
+
+## The Today card "A PM-only line is not attested"
+
+Today shows a needs-repair card for each PM-only line that fails a check. The card names the file and the line number, for example `planning/runs/placements.jsonl line 12`. Press **Show line** to see the line. The cause is one of these:
+
+| Cause | What it means | What to do |
+|---|---|---|
+| … has no via | The line was written after `via_required_from` and does not say how. A writer always adds `via`, so a person or a program added the line by hand. | If you did the act, do it again from the workspace or the terminal, then remove the hand-written line in a commit. If you did not do it, remove the line. |
+| … cites a grant that grants.jsonl does not hold | The line names a grant that does not exist. | Remove the line. Do the act again; the press mints a new grant. |
+| … cites a grant that does not cover it | The grant exists, but it is for a different act: another scope, another state or initiative, or a time outside the grant's 120 minutes. | Remove the line. Do the act again; the press mints a new grant. |
+| … is written by an agent | A line that only you may write has an agent in `by`. An agent's placement is always a proposal. | Remove the line. If you agree with the change, make it yourself. |
+| … arrived in an agent-authored commit | A commit by an agent added a PM-only line. This is how a line that a script wrote, or a patch added with `git apply`, arrives. | Look at the commit. If the act is yours, commit the ledger line yourself, without an agent trailer. Otherwise remove the line. |
+
+A line can have more than one cause. The card then lists each one.
+
+## Older lines
+
+`via_required_from` in `planning/plan-rules.json` is the time from which a PM-only line must say how it was written. Lines written before that time have no `via`. The gate counts them once for each file and does not fail on them. A line counts as older only when both of these are true:
+
+- Its own time is before `via_required_from`.
+- The commit that added it comes before the commit that set `via_required_from`, in the git history.
+
+The gate does not use the dates of a commit, because the person or program that makes a commit can set them. While the value is `null`, every line counts as older.
+
+## Grants for a bulk change and a Release
+
+Some presses mint a grant: your permission for one action, used once, for 120 minutes.
+
+- **A bulk lifecycle change.** In the Initiatives list, select up to 20 initiatives and change their lifecycle. The press mints one `lifecycle-bulk` grant that names the state and each initiative. Each lifecycle line cites that grant. Move to Now and an anchor change are never bulk acts.
+- **A Release.** A Release of a factory batch mints one `release` grant for that batch.
+
+To mint a grant at a terminal in a cockpit session, type `/pmos-grant release:<initiative>:<batch-id>` or `/pmos-grant lifecycle-bulk:<state>:<id>,<id>`. The state is one of `active`, `closed`, `on-hold` and `cancelled`.

package/workspace/guide/reports-page.md

@@ -0,0 +1,80 @@
+---
+type: Guide
+title: "Reports: draft, read and issue"
+description: "How to draft a report, add your notes, issue it, and print or copy it. How the report schedules and the Today cards for reports work."
+timestamp: 2026-10-05
+---
+
+# Reports: draft, read and issue
+
+A report tells one audience what moved in the repository. The workspace drafts it from the repository's own files. You read it, add your notes and issue it. A report that you issued is frozen.
+
+The workspace keeps each report in a file of the repository, for example `planning/reports/biweekly/2026-10-16.md`. The issues ledger, `planning/runs/issues.jsonl`, records each Issue. The page and the `pmos report` command use the same writers, so they always show the same reports.
+
+## Open Reports
+
+Open the Reports tab with the shortcut `g r`, from the command palette, or from the Today card of a report. Reports shows the repository that is open.
+
+The page has three parts:
+
+- **Report schedules.** The schedules that draft a report.
+- **Reports.** The reports of the repository, newest first.
+- **The selected report.** Its text and the actions you can do on it.
+
+## Draft a report
+
+1. Press **Draft now**. The workspace writes the draft of the cadence you have selected, for example biweekly. A cadence is one kind of report: daily, weekly, biweekly or monthly.
+2. The new draft is selected. Every number in it comes from the repository's ledgers. The page never changes a number.
+
+A second **Draft now** for the same slot is refused. Press **Redraft** to write the draft again. A Redraft keeps every note. It moves a note with its initiative, even when the order of the initiatives changed. A note of an initiative that left the window stays at the end, under "Notes kept from an earlier draft".
+
+To draft another cadence, open the menu with the three dots and choose **Draft now** with the name of the cadence.
+
+## Edit notes
+
+Press **Edit notes**. One sheet shows every note of the draft: the headline, each initiative, and the needs-your-call part when the definition names an audience. Write your text and press **Save notes**. Saving a note draws the report again from the files as they are now, and keeps every note. Use it for the text, not to freeze a number: a number can change when the repository changed since the draft was written. A draft with no note markers has no note to edit. An issued report cannot be edited.
+
+## Issue a report
+
+Issue takes two presses.
+
+1. Press **Issue**. This button is on the page and on the Today card "A draft is ready to issue". A sheet reads the draft and shows its headline.
+2. Press **Issue** in the sheet. The workspace records the Issue in the issues ledger with the sha of the file you read.
+
+If the file changed after you read it, the workspace refuses and nothing is issued. Close the sheet, read the draft again and press Issue again.
+
+After Issue the file is frozen. **Redraft** and **Edit notes** are gone for that report. If someone edits the file anyway, the row shows "Edited after issue".
+
+Only you can issue. An agent cannot press Issue, and the page does not take a name from you: the workspace writes who pressed.
+
+## Print or copy an issued report
+
+An issued report offers two actions, in the sheet after Issue and on the page:
+
+- **Print / PDF** opens the print dialog with the report alone, in the light theme. Choose "Save as PDF" in that dialog to make a PDF.
+- **Copy as markdown** puts the report on the clipboard without its frontmatter and without the note markers.
+
+These are the only two ways a report leaves the page. The page has no control that moves a report out of the workspace. You decide where a printed or copied report goes.
+
+## Report schedules
+
+A schedule drafts a report at its time. It never issues one. A schedule belongs to a report by its skill: the skill `report-biweekly` feeds the biweekly report, whatever the cadence of the schedule says.
+
+- **Pause** stops a schedule. **Resume** starts it again.
+- **Set up report schedules** appears when the repository has none. One press creates the recommended schedules. It never creates one twice.
+- **Other schedules (n)** lists the schedules that feed no report. Manage them with the `pmos schedule` commands.
+
+A schedule fires only while the workspace server runs.
+
+## The Today cards
+
+| Card | When it shows | What the press does |
+|---|---|---|
+| A draft is ready to issue | A draft exists, it is newer than the last issued report of its cadence, and it is not issued. | Opens the Issue sheet. |
+| A schedule ran and left no draft | A schedule ran and no report file of its cadence is newer than the run, after two hours of grace. | Writes the draft now. |
+
+The card for the monthly kill-condition check is drawn with the initiative cards.
+
+## In a terminal
+
+The same acts exist as commands: `pmos report draft`, `pmos report issue` and `pmos report list`. The ledger records who ran each command.

package/workspace/guide/reports.md

@@ -0,0 +1,73 @@
+---
+type: Guide
+title: "Reports: draft and issue a cadence report"
+description: "How pmos report drafts a cadence report with every number, how the notes are kept when you draft again, and how you issue and freeze a report."
+timestamp: 2026-10-05
+---
+
+# Reports: draft and issue a cadence report
+
+A cadence report tells its readers where each initiative stands. The biweekly report is the first one. The `pmos report` command drafts a report, issues it and lists the reports. It reads files in the repository only. It sends nothing and it fetches nothing.
+
+## What a draft contains
+
+The script `pmos report draft` writes every number. No model runs. It reads the ledgers since the last issued report of the same cadence. If no report is issued yet, it reads the last 14 days (`report_cycle_days` in `planning/plan-rules.json`).
+
+The draft has these sections, in this order:
+
+1. **Headline.** A count of the initiatives that moved, are off track or are at risk.
+2. **Timeline.** The dated items of each initiative, as they were when the numbers were read.
+3. **One block for each initiative.** Only work initiatives that were active in the window get a block. Off track and at risk come first. A block shows the stage, the health and its reason, and the progress, for example "7 of 12 (+4)": 7 of 12 items are done, and 4 of them were done in this window. **Last cycle** lists the items done, the gates passed, the moves between Now, Next and Later, and the overdue items. **Coming cycle** lists the items that start or are due in the next window. If there are none, it lists the next 3 items in order.
+4. **New since last report.** The initiatives that were added in the window.
+5. **Decided this cycle.** The decisions you made in the window. A decision that waits for you is not in the report. It comes to you on the Cycle review card, and it does not stop you from issuing.
+6. **Needs your call.** The asks to the audience that the definition names, and to no one else.
+7. **Sources reached and not reached.** The files the script read, and each source it did not read, with the reason.
+
+A block shows a measured value only when a measurement line gives it, with its source as `<path>@<sha>`. The script does not calculate a value.
+
+If a block is off track or at risk and has no reason, the script stops and writes no draft.
+
+## The definition
+
+The definition file tells the script and the agent what the report is for. For PMOS itself it is `planning/reports/definitions/biweekly.md`. In a kit repository it is `pmos/state/reports/definitions/biweekly.md`. Its frontmatter gives the `cadence`, the `audience` and the `sections`. If the definition names no audience, Needs your call stays empty.
+
+## Notes
+
+Each block has a note between two markers:
+
+```
+<!-- pmos:note <initiative-id> -->
+Your note. Start it with "Warning:" when the block needs attention.
+<!-- /pmos:note -->
+```
+
+The headline note is `report.headline`. The asks are in the `report.asks` note, one ask on each line, each line starting with "- ". Write prose only between the markers. Do not type numbers: the script writes them.
+
+When you draft a slot again, every note stays as you wrote it, next to its initiative. The order of the blocks can change. A note for an initiative that is no longer in the window moves to "Notes kept from an earlier draft".
+
+## The commands
+
+`pmos report draft <cadence> [<slot>]` writes the draft to `planning/reports/<cadence>/<slot>.md`. The slot is a date, YYYY-MM-DD. If you do not give a slot, the slot is today. If a draft for the slot exists, the command stops and writes nothing. To draft the slot again and keep every note, add `--redraft`. To fix the clock, add `--now <time>`: two drafts with the same inputs and the same `--now` are the same, byte for byte.
+
+```
+pmos report draft biweekly 2026-10-16
+pmos report draft biweekly 2026-10-16 --redraft
+```
+
+`pmos report issue <cadence> <slot>` issues the report. Only you can do this, at a terminal. The command asks you to type the cadence and the slot, for example `biweekly-2026-10-16`. An agent session, a command with no terminal, or a different text is refused, and nothing is written. The command records the path and the git blob sha of the file in `planning/runs/issues.jsonl`. The report is then frozen: a draft of that slot is refused, and the Initiative Gate fails if the file changes. Nothing is sent. To share the report, print it or copy it as markdown.
+
+```
+pmos report issue biweekly 2026-10-16
+```
+
+`pmos report list [<cadence>]` shows each draft and each issued report, newest first, with who issued it.
+
+Every command accepts `--root <dir>` to name the repository. `draft` and `list` also accept `--json`.
+
+## The window
+
+The window starts at the time of the last issued report of the same cadence, so no time falls between two reports. The next draft starts where the last issued report stopped.
+
+## The report lane
+
+An initiative in the report lane completes its last step when you issue its report. The workflow engine reads the issued line for the initiative's `doc_path` in `issues.jsonl`.

package/workspace/guide/timeline.md

@@ -0,0 +1,70 @@
+---
+type: Guide
+title: "Breakdown › Timeline: the items on a time axis"
+description: "How to read the Timeline view of a Breakdown, move the dates of an item by dragging its bar, change a due date by dragging the end of a bar, and read the health flags."
+timestamp: 2026-10-05
+---
+
+# Breakdown › Timeline: the items on a time axis
+
+The Timeline view shows the items of one initiative on a time axis. Each item that has a start date or a due date has a bar. The bar runs from the start date to the due date.
+
+## Open the Timeline
+
+1. Open the Breakdown of an initiative.
+2. At the top of the Breakdown, press **Timeline**. The Timeline is next to **Tree** and **Board**.
+
+## Read the Timeline
+
+- **Months.** The months are across the top. The axis starts at the first month that has a date and stops at the last month that has a date. It always shows today and at least three months.
+- **Today.** A vertical line shows today. The label **Today** is on its own line above the month labels, next to the line.
+- **Scrolling.** The chart scrolls to the side inside its own area, on every screen width. When the Timeline opens, the chart scrolls so that today shows. The column with the titles stays in its position while the chart scrolls.
+- **All items.** The first row shows the full initiative, from the first start date to the last due date. It has one segment for each stage. A small gap shows where each stage starts, also when two stages overlap.
+- **Stage rows.** Under the first row, the items are in groups by stage. The stages are in the same order as in the Tree. Each stage row shows the dates of its items and the number of dated items, for example "Build, 3 dated items".
+- **Item rows.** Each item row shows the title, the dates and the bar. A Done item has a darker bar.
+- **Milestones.** An item that is a milestone shows a diamond on its due date. The diamond also shows on the stage row and on the first row.
+- **Proposed items.** An item that an agent proposed and that you did not keep yet has a lighter bar with a dashed edge and the signal **Proposed**. A proposed item does not make a stage bar or the first row longer.
+- **Items with no dates.** An item with no start date and no due date has no bar. A line under the chart gives the number of such items. To give an item dates, open it and set **Start** and **Due** in the item sheet.
+
+An item with only a start date or only a due date has a bar of one day.
+
+## Move the dates of an item
+
+- **Move both dates.** Drag the bar to the left or to the right. The start date and the due date move by the same number of days.
+- **Change the due date.** Drag the end of the bar (the line at its right edge). Only the due date changes. The due date cannot go before the start date.
+- **Short bars.** A bar that is narrower than about 24 pixels always moves whole. To change only its due date, use the keyboard or the item sheet.
+- **Open the item.** Press the bar without moving it. The item sheet opens.
+
+The bar shows the new dates while you drag it. When you let go, the workspace saves the change.
+
+With the keyboard:
+
+1. Press Tab until the bar has the focus.
+2. Press the Left or Right arrow key to move both dates by one day.
+3. Press Shift with the Left or Right arrow key to change only the due date.
+4. Press Enter to save. Press Escape to go back to the saved dates.
+
+If you move the focus away from a bar that has a change, the workspace saves the change. If you press Tab, the focus then goes to the next bar.
+
+What a move writes:
+
+- Each drag adds one line to `planning/runs/plan-items.jsonl`. The line is a `set` line with the dates of the item. When you change only the due date, the line has only the due date.
+- An item that has only a due date keeps only a due date when you move it.
+- A move changes one item only. The dates of other items do not change, also when they come after the item. The Timeline does not count effort in days.
+- If the workspace cannot save the change, a message gives the reason. The bar goes back to the saved dates.
+
+## Health
+
+The Timeline shows a flag only when an item is not on track. The flag is text and a small dot, on its own line under the dates of the item. The bar of the item has a coloured outline.
+
+- **At risk: starts before an item ends.** The item starts on or before the day that one of its predecessors ends. The flag names that predecessor and its due date. A Done predecessor does not cause this flag. A Done item never shows it.
+- **At risk: due on a date, not done.** The due date is before today and the item is not Done.
+- **Off track: milestone due on a date, not done.** A milestone has a due date before today and it is not Done. Its diamond has the same colour as the text of the flag.
+
+Limit: this view checks only the predecessors in the same initiative. A predecessor in a different initiative does not cause a flag here. To see such a clash, compare the dates of the two items.
+
+To remove a flag, change the dates of the item or of its predecessor, or move the item to Done.
+
+## On a phone
+
+On a narrow screen, the page does not scroll to the side: only the chart does. To move a bar, touch it and drag it to the side. A short bar takes a touch a little to its left or right. To scroll the chart, drag the empty part of a row.