create-pmos 0.516.0 → 0.518.0

package/workspace/guide/initiative-boards.md

@@ -1,123 +0,0 @@
----
-type: Guide
-title: "Initiatives on the console: Portfolio, boards and workflows"
-description: "How to use the Initiatives tab of the console page (/): the Portfolio of boards, a board and its nine tabs, an initiative with its own workflow and stage records, and the Build and deliver setting."
-timestamp: 2026-11-03
----
-
-# Initiatives on the console: Portfolio, boards and workflows
-
-The Initiatives tab of the console page (`/`) has these levels: **Portfolio** › **Board** › **Initiative** › **Epic** › **Item**. A breadcrumb at the top takes you back one level. The address bar keeps your place in the `init=` parameter, so a reload opens the same page.
-
-## Portfolio
-
-The Portfolio shows one row per board. A board is a product folder, for example IDPF. Each row shows:
-
-- the board name and its health: On track, Needs attention or Off track
-- the owner, and **Build and deliver** with the Jira project keys, or "PMOS tasks only"
-- the initiatives per category: Discover, Plan, Do and Learn
-- the next release
-
-Under the rows are a timeline of all boards (board › initiative › epic) and the boards that have new asks. Press a board name to open the board. Press **New board** to add a board.
-
-## A board
-
-The tabs are **Summary**, **Initiatives**, **Triage**, **Backlog**, **Board**, **Timeline**, **Releases**, **Docs** and **Sprints**. A board with Build and deliver off has no Releases and no Sprints tab.
-
-On a screen wider than 600 pixels, the breadcrumb, the board status, the tabs and the Board settings gear are on one row. **Backlog**, **Releases**, **Docs** and **Sprints** are behind **More**. Press **More** to open a menu of them. When one of them is the open tab, it shows next to the other five tabs.
-
-- **Summary** shows the initiatives at a glance and one bar per category. At a glance lists up to six open initiatives. Initiatives with work, and Now initiatives that are not on track, come first. The others follow by end date. Press a bar to open the Initiatives tab with that category.
-- **Initiatives** lists the initiatives of the board, 25 on each page. See [Initiatives: status, hold, cancel, merge and archive](#initiatives-status-hold-cancel-merge-and-archive).
-- **Triage** lists the new asks. Add an ask, then open it to see its draft. The New asks heading names the workflow and the first stage that **Accept** uses. Press **Accept** to start an initiative. An initiative needs an anchor (a KR or a health budget). On a board, **New initiative** lists the anchors that `planning/okrs/` declares. Pick one from the list. Press **Ask for more** to ask a question, or **Decline** and give a reason.
-- **Backlog**, **Board** and **Timeline** show the epics and items. Jira items and PMOS tasks are mixed. The filters are on one row and are the same on the three tabs:
-  - Type in the search box to find an item by key, title or owner.
-  - Press **All initiatives** to choose one initiative. Its ID then shows on the button.
-  - Press the filter icon to set **Type**, **Source** (Jira or PMOS tasks) and **Done** (Show or Hide). A board with Build and deliver off has no Source. The badge on the icon counts the filters that are on.
-  - A filter that is on shows next to the icon. Press its x to remove it, or press **Clear** to remove all.
-  - In Backlog, add a PMOS task to an initiative.
-  - In Board, drag a PMOS task to a column, or use its menu. A Jira item has a lock: change it in Jira.
-  - In Timeline, use **Weeks**, **Months**, **Quarter**, **Year**, **2 years** and **5 years** to zoom. The four-corners icon beside the zoom spreads the Timeline over the whole window, as on the Board; press it again or press Escape to go back. Drag the empty chart to pan. Drag a PMOS bar to reschedule the task, or focus the bar and press the Left or Right arrow key. The toast has **Undo**. A Jira bar is locked.
-- **Releases** shows the next release, the later ones and the past ones, with their scope initiatives. Release dates live on the Calendar. Press **On the Calendar** in the Unreleased heading to open it.
-- **Docs** lists the documents of the board by initiative.
-- **Sprints** shows the Jira sprints and the sprint burndown. They are read-only. The heading of the active sprint shows when PMOS last read them from Jira.
-
-### Initiatives: status, hold, cancel, merge and archive
-
-The Initiatives tab has one row of controls: the search box, the view menu, the filter icon, the sort icon and **New initiative**.
-
-- **The view menu** shows the current view: Now and next, Mine, At risk, No owner or All. Now and next, Mine and No owner show only active initiatives.
-- **The filter icon** opens Status, Stage, Category and Owner. (The Horizon filter went with Now, Next and Later, D105.) The Status list has three groups: Active (On track, At risk, Late), Paused (On hold) and Closed (Done, Cancelled). The badge on the icon counts the filters that are on. Each filter that is on shows as a chip above the list. Press a chip to remove that filter, or press **Clear**.
-- **The sort icon** opens the sort keys and the order.
-
-Each initiative has a **stage** and a **status**. The stage is the step in its own workflow. The status is one of these:
-
-| Status | Meaning |
-|---|---|
-| On track, At risk, Late | The initiative is active. |
-| On hold | You paused it. It keeps its stage, its work and its history. It never turns Late while it is paused. |
-| Done | It reached the end of its workflow, or it was accepted or closed. |
-| Cancelled | You stopped it. It is counted as cancelled, not done. |
-
-An initiative in the last stage of its workflow (for example **Closed**, or a stage in the Done category) is never Late or At risk. On the Timeline its bar ends at its own end date. It has no line to Today, no late dot and no late milestone.
-
-A cancelled initiative is hidden from every view. The list footer says how many are hidden, for example "1 cancelled hidden". Press it to see them, or pick Cancelled in the Status filter.
-
-Press **…** on a row to open its menu. It is the initiative's short menu: Split, Merge into, Program, Copy, The record and **Delete** (see [Home](home.md#an-initiative)). Press the stage name on the initiative's stage card for the stage picker:
-
-- **A stage**: the stages of its own workflow. Press an earlier one to move back, a later one to move on.
-- **Put on hold**: give a reason and pick when to check back (in 2 weeks, in a month, next quarter, or no date). The check-back date shows on the row and on the initiative page. **Resume** makes it active again at the same stage.
-- **Won't do**: pick a reason and add a note if you want. It replaces Cancel. **Back to Triage** makes it active again.
-- **Merge into another…** (in ⋯): for a duplicate. Pick the initiative to keep. The most alike ones are first. Pick what moves: the Jira epic links and the PMOS tasks. The duplicate goes to the Archive as "Merged into" the one you keep. Its documents, asks and notes stay with it. Nothing changes in Jira.
-- **Archive** (in the stage picker): for an initiative that does not belong. It leaves every list, count and timeline of the board. Nothing is deleted. If it belongs on another board, the sheet can move it there instead.
-
-When two active initiatives on the same anchor have almost the same title, the less advanced one shows "Looks like a duplicate of" the other. Press it to open Merge. In the merge sheet, press **Not a duplicate** to stop the hint.
-
-Each action has **Undo** on its toast. The footer link "N archived" opens the archive. Press **Restore** on an archived initiative to put it back as it was. Press **Undo merge** on a merged one: the epic links and tasks that moved go back.
-
-The initiative page shows a banner when the initiative is on hold, cancelled or archived, with its reason, its date and **Resume**, **Reopen**, **Restore** or **Undo merge**. Its **…** menu has the same status and tidy-up actions as the row menu.
-
-Hold, cancel, resume and reopen are lines in `lifecycle.jsonl`. Archive and merge are lines in the board ledger, `boards.jsonl`. No initiative record is changed.
-
-### Board settings
-
-Press the gear in the board header to open the board settings.
-
-- **Build and deliver**: turn it on to mirror Jira. Type one or more Jira project keys, separated by commas, for example `IDPF, LB`. A board can map several Jira projects. With it off, every item is a PMOS task and the Build workflows are not available.
-- **Workflows this board offers**: the templates that a new initiative on this board can use.
-- **Default for new initiatives and accepted asks**: the template that a new initiative or an accepted ask starts on.
-
-## An initiative
-
-Each initiative has its own workflow, picked from a template: for example Product, Quick fix, Research only, or Content and launch. The stepper shows the stages of that workflow. Press a stage to move the initiative there. The move is your decision, so nothing blocks it. An order rule shows as a warning chip next to the status, at the right of the breadcrumb, for example "Skipped Plan" or "No spec yet". Press the gear next to the stepper to change the template or edit the stages. When you remove a stage that holds the initiative, the editor asks where it goes. In the editor, each stage is one row: drag handle, category colour, name, category, then move up, move down and remove. A short note under the name shows only when it adds something, for example **current stage**, **new**, or the old name of a renamed stage.
-
-Press **Tools**, at the right of the stepper, to open a tool. The menu lists the tools of the current stage first, then the tools of the other stages. The **…** menu at the right of the breadcrumb opens the Dashboard and the Jira epics of the initiative, and holds Status and Tidy up. The tabs are **Overview**, **Breakdown**, **Docs**, **Tickets**, **Timeline** and **History**.
-
-The **Overview** shows the stage records of the current stage:
-
-| Category | Records |
-|---|---|
-| Discover | Problem statement |
-| Plan | RICE score, with its rank on the board |
-| Do | Launch checklist, sprint burndown (from Jira, read-only) |
-| Learn | Kill conditions, learnings |
-
-A project workflow has the launch checklist and the learnings only. If the workspace server cannot store stage records yet, the cards say "Nothing recorded yet." and nothing is saved.
-
-## Core documents
-
-Each level has a set of core documents. A level answers one question for one reader: the Portfolio asks "Are we betting on the right things?", a board asks "Is this area moving, and what comes next?", and an initiative asks "What are we building, why, and did it work?".
-
-- **Portfolio:** press **Documents** next to **Overview**. The number on the button counts the drafts and the documents that are due.
-- **Board:** the **Docs** tab starts with the core documents. The sprint review and the release notes show only when Build and deliver is on. The documents linked to the board follow under **Other documents**.
-- **Initiative:** the **Docs** tab has one section for each of Discover, Plan, Do and Learn. The current section lists its documents. A finished section, or one not reached yet, folds to one line.
-
-Each row shows what the document is for, its state, how often it changes, who reads it and who writes it. The states are Up to date, Due, Draft ready, Not started, None yet, Out of date and Comes later. Press a row to open the document, the tab, the stage tool or Reports that holds it.
-
-- **Draft it:** on a document that is not started, PMOS drafts it. The row shows "Agent drafting" until the draft is ready.
-- **Propose them, Run a scan, Set it up:** a row read from its own source offers the step that makes that source: OKRs are proposed as a draft, Horizon scan opens Scan now, and a status report opens Reports.
-- **Review the draft:** opens the draft in the document sheet. Above the draft, **Issue it** makes the draft the current document. **Ask PMOS to change it** asks for a new draft. PMOS sends nothing to anyone.
-- The Briefing shows one row for each level that has drafts waiting. Press the row to open that Docs view.
-
-## Demo mode
-
-Open `/?demo=1` to see five sample boards and about 310 initiatives. In demo mode nothing is saved, and a reload starts again.

package/workspace/guide/initiatives-screen.md

@@ -1,179 +0,0 @@
----
-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-11-02
----
-
-# Initiatives: the Roadmap, the List and the initiative sheet
-
-The Initiatives place shows every initiative of the selected repository. The initiatives are on one ranked list, the Roadmap. A rank is an order, not a date. The rank of each initiative is a line 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.
-
-An open initiative uses one column. At its top is the **mission**: one panel with three parts, and Tasks fills the width below it.
-
-### The mission
-
-- **The telemetry card.** It shows the stage, the plan dates, **Time left** and **Elapsed**. A picture fills the card. Time runs from left to right, from the plan start to the plan end, and the months are marked along the bottom. The path runs on the ground while the rocket is made, and it rises at lift-off, in the middle of Build, to the planet at the release. Each stage is a colour of the path: done stages are green, the current stage is thicker and blue, a late stage is orange, and a stage on hold is grey. A diamond on the path is a milestone. Press a diamond, the planet or the dish to open its task. Milestones that are close together are one diamond with a number.
-- **To finish this stage.** It shows how many tasks of the stage are done, the stage's open milestone tasks with their dates, and the move to the next stage. The move is blue only when every task of the stage is done and nothing waits on you. At other times it is quiet. Under the rows are the owner, the stakeholders, the workflow and the program. On a wide screen this part stands beside the telemetry card.
-- **About.** It has the description and the success measure. The description is the first paragraph of the PRD's Problem section. Press **Show more** to read all of it, or **Open the PRD** to open the file. The success measure is the one Claude drafts. A proposal opens About until you press its check mark. A kept measure shows each row with its now value and its target. When there is no description or no measure, About gives you a link that asks Claude in Home to write it.
-
-When you open an initiative, the three parts are hidden at first and only a banner shows: the stage, the dates, the days left, the count of tasks done, the success measure and the move to the next stage. Press the arrow on the banner to show the telemetry card first. Press the arrow on the telemetry card to hide all three parts again. **To finish this stage** and **About** each have their own arrow, and they stay as you left them when you hide and show the mission. The workspace keeps these choices for each initiative in this browser. On a phone, the first screen shows **To finish this stage** and **About** closed.
-
-On a phone, the page uses one 16 px margin and has no grey panel around the mission. The telemetry card is shorter: the stage name is on the first line, and the dates, **Time left** and **Elapsed** are on the next line, so the picture does not repeat the Today label. **To finish this stage** and **About** are one white card. The first row shows the next stage and the count of tasks done. Its round arrow opens the move sheet. The second row shows the owner, the stakeholders, the workflow and the program. The third row is **About**. In Tasks, the rows start near the card's edge, and the late and open counts of a stage are on the same line as its dates.
-
-Tasks has no **Full width** icon: use the split panel to make the Viewer wider. On a phone, Tasks is a list only. The workspace keeps a Timeline or Kanban view that you chose on a larger screen, and shows it again there.
-
-Open a task to edit its Notes. Leave the box or press Ctrl/Cmd+Enter to save. Closing the viewer also saves the pending edit. After the save succeeds, reopening the task reads the saved notes, even if you opened it while the save was pending. The save toast offers Undo.
-
-### Scan repository
-
-The workspace reads the stage, the files and the breakdown of each initiative from the repository. It reads them again when an initiative record changes, and at the latest after ten minutes. A change that does not touch a record, for example a new PRD or a pull request merged on the trunk, can show late.
-
-To read the repository again now, press **Scan repository** at the top of the screen. The same action is in the **⋯** menu of an initiative sheet, and in the command menu (⌘K). A toast shows **Scanning the repository…**. When the scan ends, a toast tells you how many initiatives it checked and how many moved, by stage, for example "Checked 42 initiatives. 9 moved: 4 to PRD, 3 to Evaluate, 2 to Handoff. Documents or Jira keys found for 30 of them." When it found nothing for any initiative, the toast says so. Then the view updates. The scan writes nothing, except the tidy you confirm (below). It works the same on PMOS itself and on a tenant repository.
-
-### What the scan finds in a document repository
-
-In a document repository (`.pmos-profile` is `pm-artifacts`), the scan reads every document in the repository: Markdown, text, Word, PDF and HTML files that git does not ignore, whether git tracks them yet or not. A folder that is not a git repository is read the same way. Each initiative has two names the scan looks for: its id (the record's file name) and its title. Spaces, capitals, underscores and punctuation do not matter, so the title "Guest Checkout" matches `guest-checkout`, `Guest Checkout` and `guest_checkout`. A document belongs to an initiative when:
-
-- its frontmatter names the initiative in `initiative:`, `initiative_id:` or `initiatives:`, or
-- a folder in its path has the initiative's name, for example `Product/Guest Checkout/PRD.md`, or
-- its file name or its own `title:` carries the initiative's name, for example `PRD - Guest Checkout v2.md`. A one-word name shorter than six letters must start the file name. When two initiatives match, the longer name wins.
-
-The file name, then the `type:` in the frontmatter, then the folder names give the document its role:
-
-| Role | Words | Step it completes |
-|---|---|---|
-| Evaluation | `eval`, `evaluation`, `review`, `verdict`, `scorecard` | review |
-| Handoff | `handoff`, `hand-off`, `handover` | handed off |
-| Brief | `brief`, `problem`, `idea`, `intake`, `one-pager`, `bug-report` | the brief, for example Problem brief |
-| Draft | `prd`, `spec`, `specification`, `requirements`, `findings`, `plan`, `strategy`, `report`, `decision` | the draft, for example PRD |
-
-A rubric or a template is not evidence. Jira keys also complete the handoff: the keys the Jira tab recorded when it pushed the tickets, a `jira:`, `jira_key:` or `jira_epic:` key in the record, a Jira link or a line that says Jira in the record, and a Jira link in one of its documents. A path that the record names always comes before a found document. A found document never fails a gate. Acceptance is always yours: the scan never records it.
-
-### Tidy duplicate documents
-
-An initiative has one document of each kind: one brief, one PRD, one evaluation and one handoff. When a document repository holds more than one of a kind for an initiative, for example `checkout-prd.md` and `checkout-prd-v2.md`, **Scan repository** first opens the **Tidy duplicate documents** sheet. It lists each group and selects the document to keep:
-
-1. the file the record names (`doc_path:` or `brief_path:`), else
-2. the most recently changed file (its last git commit, else the file's own time), else
-3. the shortest path.
-
-Select another file to keep a different one. Clear a group's check box to leave that group as it is. Then press **Archive N and scan**. Every other document of each checked group moves to `pmos/state/archive/duplicates/`, under its original path. Nothing is deleted. A file that git tracks moves with `git mv`, so it shows as a rename when you next commit. Each move is one line in `moves.jsonl` in the same folder, so you can move a file back by hand. A document that belongs to more than one initiative never moves. The scan does not read the archive. The scan then runs, and its toast starts with how many documents were archived.
-
-Press **Scan without tidying** to scan with every document in place. Press **Cancel** or Escape to do neither. The tidy writes no initiative record.
-
-### Check documents with Jev
-
-A file name, a folder or a `type:` line can give a document the wrong kind. When Jev is set up for the repository, **Scan repository** first asks Jev to read each document that is tied to an initiative and say what it is: a problem brief, a PRD, an evaluation, a handoff, or none of these. Jev is set up when three things are true: a TypeSafe key is saved, validation is on for the repository, and the switch that lets Jev categorize documents is on.
-
-1. The **Check documents with Jev** sheet says how many documents Jev reads and how many requests that sends. Nothing is sent before you press **Check with Jev**. Jev gets each document's title, headings and opening only. It never gets the path or the whole file. A document in an excluded folder, or one that may contain a secret, is not sent. A document Jev read before, and that did not change, is not sent again.
-2. The next sheet lists each document that Jev reads as a different kind, with how sure Jev is. A kind that Jev is unsure of is not listed. Clear a check box to keep the kind the scan gives now. Then the sheet lists the duplicates by Jev's kinds, and in each group it selects the version Jev picks as the most complete and current. The file the record names is still kept first.
-3. Press the confirm button. Each changed kind is one line in `pmos/state/document-kinds.jsonl`, and the scan uses that kind from now on. A document set to "none of these" leaves the scan. Then the duplicates move to the archive as in [Tidy duplicate documents](#tidy-duplicate-documents), and the scan runs. Its toast says how many kinds changed and how many documents moved.
-
-Press **Scan without Jev** to use the file names only. When Jev is not set up, the scan toast says which part is missing, and the tidy sheet uses the file names.
-
-## The Roadmap
-
-The Roadmap is one ranked list: Prioritize's output, "Ranked on the roadmap". The first card is the most important. Now, Next and Later are retired (D105). The rank says what comes first; the lifecycle stage (Triage to Evaluate) says where each initiative is. The line at the top reads, for example, "Roadmap · 8 · 5 KR · 3 health". It counts the initiatives on the list by what they serve: a key result (KR) or a health budget.
-
-A card shows the rank, the title, the lifecycle stage, "7 of 12" for the items done, the check-by date when it 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 its new place. 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, To bottom and Set check-by.
-
-Each move writes one `ranked` line. The line names who wrote it: you, or the agent session. If the server refuses a move, the card goes back and a message tells you why.
-
-### Old lines, proposed and dormant
-
-- **Old lines.** A line written before D105 put an initiative in Now, Next or Later. It still counts: those initiatives keep their order, Now first, then Next, then Later. Nothing in the file changes.
-- **not ranked yet.** An initiative that no line has ranked. On day one the active ones come first, by activity. Rank one to fix its place.
-- **proposed.** A move an agent proposed before D98. It changes nothing until you keep it in the Cycle review. Since D98 an agent's move applies at once and names the agent.
-- **Dormant.** An initiative that no line has ranked and that has had no activity for a long time. Press the dormant line under the list to show them. An initiative that a line ranked never goes dormant.
-- **No record yet.** A PRD, rubric or prototype folder that no initiative record points at. Press the "with no record" line under the list to show them. In List they are the last group. Press one to open its PRD. Only a record can be ranked, so these have no menu.
-
-## 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:
-
-- **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 changes an anchor for several initiatives at once. That is a one-at-a-time act.
-
-## 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 rank on the Roadmap, 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. The tabs: **Breakdown**, **Files**, **History**, **Jira tickets**, **People** and **Notes**. The Breakdown tab is the same Breakdown as in its own tab, and it shows here too. **Notes** lists the meeting notes linked to the initiative, newest first, each with its summary and **Open**. See [Notes](notes.md).
-
-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".
-
-### How the stage is read
-
-The stage is the first stage with an open step at or after the furthest stage that has evidence. Work that went past a step, for example a build that merged before a contract was logged, is not held at the earlier stage. The earlier stage shows a warning mark, and its tooltip names the step that is still open, for example "Skipped: contract is still open". An accepted initiative has no current stage.
-
-The build counts as done when the trunk holds evidence for this initiative: a merged `initiative/<id>` branch, a commit that names the id and changes build files, or a merged change that changed this initiative's own documents (its record, or a file the record names) and build files together. A change that touched the documents of more than two initiatives is not evidence for any of them.
-
-### The Files tab
-
-The Files tab lists every file that belongs to the initiative, in three groups:
-
-- **Named by the record.** The record, and each file its frontmatter names with a key that ends in `_path`: `prd_path`, `rubric_path`, `explainer_path`, `design_path` and others. A file the record names that does not exist is shown as missing.
-- **Linked documents.** The documents the library joins to the initiative: a document that declares its `initiative_id`, a document the record names, a file name that starts with the id.
-- **Changed for it in git.** The files that the commits for this initiative changed and that still exist. These are its own branch, trunk commits that name the id, and merged changes that carried its documents. The file opens read-only.
-
-**List · Graph** at the top of the tab changes the view. **List** shows the groups above. **Graph** shows the files of the initiative as a network:
-
-- a filled dot is a markdown file of the initiative: a file that the record names, or a linked document. Its label is its role, such as PRD, Rubric or Explainer;
-- a hollow dot is a file outside the initiative that one of its files links to, or that links to one of its files. A decision shows its number, such as D65;
-- a line is a link that a file writes. A dashed line is a decision that a file cites.
-
-The graph shows at most 14 outside files, the most-linked first. The legend says how many are left out. Press a dot to mark its lines and to see its title, its path and **Open file**. The same files and links always give the same picture. On a phone the list is shown.
-
-### A breakdown read from the spec
-
-When nobody has planned items for an initiative, the Breakdown tab shows the items of its spec above the empty Breakdown: the user stories, or the entries of the Requirements section of the PRD that the record names. Each item shows the state of the whole initiative: **Done** after you accept it, **Built** when its build is on the trunk, and **Todo** before that. These items are read-only and nothing is written. To track an item, add it to the Breakdown. The card and the row show the same count, for example "0 of 8 · from board-delivery-truth-prd.md".
-
-The More button in the sheet has:
-
-- **To top**, **Up**, **Down**, **To bottom**.
-- **Set check-by.** 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 lands at the end of the Roadmap. Rank it when it matters.
-
-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, at the end of the Roadmap.
-- **Cycle review.** The card opens a sheet with two lists. Agent proposals: **Keep** applies the move as your line, **Drop** removes it. Check-by dates passed: set a new date, or rank the initiative lower. Each press acts on one initiative: there is no Keep all.
-- **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

@@ -1,55 +0,0 @@
----
-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-11-02
----
-
-# 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 rank lines that the Roadmap uses. An initiative that no line has ranked follows the ranked ones, by its activity. 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.
-- **Order.** The rows are in one list, in Roadmap order (Now, Next and Later are retired). A row that no line has ranked comes after the rows that have one.
-- **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**. 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 on the one list. The move is the same as a move on 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 on the list 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 ranked 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.
-
-## On a phone
-
-A phone, or a window 760 px wide or less, does not show the Timeline. There, Initiatives shows the Roadmap, or the List from the search (see [the layout guide](layout.md)). Use a wider window to see the Timeline.
-
-## 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.

package/workspace/guide/phone-companion.md

@@ -1,89 +0,0 @@
----
-type: Guide
-title: "Guide: the phone companion"
-description: "At phone width the console shows a companion: one moment of your day, your items one at a time, Tell PMOS and Record."
-timestamp: 2026-10-22
----
-
-# Guide: the phone companion
-
-When the console (`/`) is 640 pixels wide or less, for example on a phone, it shows the companion and not the desktop pages. The companion is not a small copy of the desktop. It shows the one thing that is useful now, and it keeps decisions for your computer.
-
-## The moment card
-
-The top card shows where you are in your day and why it is useful now. PMOS chooses the moment from today's meetings and the clock. One icon before the date shows the part of the day: a sun for the morning, a bolt for working hours, a calendar for a meeting, a chart for the evening and a moon for the end of the day. Only the icon of the current part shows.
-
-| Moment | When | What the card shows |
-|---|---|---|
-| Your morning | Before noon, with no meeting in the next 30 minutes | Your briefing: the top three points of the desktop Briefing, each opens its details. Then how many things wait on you, how many drafts wait for your review, and the first meeting with **The brief of this meeting** |
-| Before you walk in | The next meeting starts in 30 minutes or less | What is prepared for it, the items to close first, each with **Done**, and **The brief of this meeting** |
-| In the meeting | A meeting is in progress | **Record this meeting?** with **Record** and **Not this one**. Recording opens focus (see below). |
-| Just ended | A meeting ended less than 20 minutes ago | **What came out of it?** If you recorded the meeting, the card shows the summary, the decisions, the actions and the open questions from its notes, the same notes as on the Notes page. While PMOS writes the notes, the card says so. If you did not record it, **Tell PMOS** puts the meeting name in the bar so you can type the result. |
-| Free time | 15 minutes or more before the next meeting | The items that fit in the time: overdue items first, then items due today, at most two. Each has **Done** and **Later today**. Under them, what the agent finished for you. |
-| Finished for you | After noon, before 17:00, with no meeting near | The drafts that the agent finished today, newest first. **Read it** shows the draft as a document, with its headings, lists and tables, the same as on your computer. Approve a draft, or send it back with a note, on your computer: nothing is sent from the phone. Under them, the items that fit. |
-| Evening recap | From 17:00 | How today went: the meetings, the decisions you confirmed, and the items done. Then what moved, each with what it is (Decided, Done, Agent) and where it came from. A decision from meeting notes that you did not confirm in Replay is not counted, and a line says how many wait. Then one thing for tonight, with **Done** and how many are still open. |
-| End of day | From 20:00, and before 05:00 | Today in one line, the meetings of the next working day (tap one to see its brief), and how many items carry over |
-
-When the moment changes, a short message shows at the top for 6 seconds. The message shows only while the page is open. The companion does not send notifications.
-
-In the evening and at the end of the day, the card does not show the things that wait on you one at a time. The number at the top right still opens them.
-
-## Waiting on you
-
-Under the moment card, the things that wait on you show one at a time ("1 of 9"). They are the same things that the **Needs you** section of the desktop Briefing counts: your own items, the Jira and plan items assigned to you that are overdue, blocked or due today, the items of the morning brief, and the decisions.
-
-- For your own Work items, **Done** marks the item done; the message that follows has **Undo**. **Later today** shows the item again later.
-- For the other rows, **Details** shows why the row is there, its facts and a link to where it lives. Decisions wait for your computer.
-- **Next** shows the next row. **See all** lists every row; tap a row to see its details.
-
-## Meetings
-
-Under the card, **Later today** lists the rest of today's meetings. Tap a meeting to see its brief: the time, the people, the initiative, then the same brief as the meeting card of the desktop Calendar (in short, what matters today, what came out of the last one, what to be ready with, and the links). From the brief you can record the meeting or open focus.
-
-## Tell PMOS
-
-Type a note, a to-do or an idea in the bar at the bottom and press Enter. PMOS puts it in your Work inbox. The bar does not answer questions. The small microphone puts the cursor in the bar; use the microphone of your phone's keyboard to speak. No audio goes to PMOS from this button.
-
-## Record
-
-The red button records a conversation or a meeting with the same recorder as **Record** on the desktop. When the recording starts, the phone opens focus.
-
-### When the phone locks
-
-A web page cannot record while the phone is locked. Keep the PMOS screen open during a meeting.
-
-- While it records, PMOS keeps the screen on, so the phone does not lock by itself. If the power button locks the phone, or you go to another app, the recording pauses.
-- When you come back to PMOS, the recording continues in the same note. PMOS tells you how long the gap was. The replay has silence for the gap, and the times of the later lines stay correct.
-- If the phone asks for a tap first, PMOS shows **Tap anywhere on the page to go on recording**. Tap the page once.
-- Battery saver can stop PMOS from keeping the screen on. Then set a longer screen lock time in the phone's settings, or keep the phone awake by hand.
-
-## Focus
-
-Focus shows the meeting on one screen. You do not scroll it. From the top:
-
-- **Back to your day**, the title, and the clock: the time since the start and the time left. Under them, the bar of what the room talked about.
-- The topic that the room is on now, and how long it has been on it.
-- **Topics**, **Captured**, **Note** and **Your slides** (or **Material**). Each one opens a sheet over focus. **Note** shows what the live note has found so far, or the last lines of the transcript.
-- **The room**: the last line that was said, in large text, with the line before it in faint text. It changes when someone speaks. Under it, **What's being said**, with context. Tap a context to see its detail.
-- **PMOS, to you**: only the newest note that PMOS wrote for you, in large text, with the line that it answers. Tap **‹** to see earlier notes. If a new note comes while you look at an earlier one, tap **1 newer** to go to it. PMOS holds some notes for the right moment. Tap **Holding** to see them, and tap **Now** to see one now.
-- At the bottom, **Ask PMOS quietly** and **Stop**. Only you see your question and the answer. The answer shows as the newest note, under your question. **Stop** asks before it stops the recording.
-
-A recording that is not on the calendar, for example a talk in the corridor, opens the same focus without topics and slides.
-
-**Back to your day** closes focus. The recording continues. While it records, the bar at the bottom shows the name, the time, **Focus** and **Stop**, and the top card shows the notes that are being taken. **Focus** opens focus again.
-
-## The full console
-
-A phone always shows the companion. There is no way to the desktop pages on a phone: use your computer for them. In a window wider than 640 pixels the console always shows the desktop pages.
-
-The number of things that wait on you, at the top right, opens the list of all of them.
-
-## Loading
-
-On a phone, PMOS loads only the companion, not the pages of the computer. This makes the first load faster on a phone connection. If you turn the screen so that it is wider than a phone, the page loads again and shows the pages of the computer.
-
-## Limits
-
-- No notification on the lock screen, and no spoken brief.
-- No recommendation for a decision. Decisions with options wait for your computer.
-- To make tasks from the notes of a meeting, use the Notes page on your computer.

package/workspace/guide/reports-dashboards.md

@@ -1,70 +0,0 @@
----
-type: Guide
-title: "Reports: dashboards of reports"
-description: "How the console Reports page shows dashboards at portfolio, board and initiative scope, how to edit one, how to send one as a report, and what the Charts tab holds."
-timestamp: 2026-10-12
----
-
-# Reports: dashboards of reports
-
-A report answers one question. A dashboard is a set of reports for one scope. Open the Reports tab of the console to see them.
-
-## The three tabs
-
-Each tab has one job. A line under the tabs repeats it: **Live** goes to Dashboards, **Sent** goes to Reports, **Building blocks** goes to Charts.
-
-- **Dashboards.** The charts of one scope, drawn from the repository's records. A dashboard is live: it changes when your work changes. The tab shows how many dashboards there are.
-- **Reports.** The documents you send, with their set-ups. See [Set up a report by asking](reports-set-up.md). The tab shows how many drafts wait for you.
-- **Charts.** Every chart the workspace can draw, with the question it answers, the dashboards that use it and the reports that use it. The tab shows how many charts there are. A chart that the Structure step of a report saved is listed too, tagged **Data chart**, with its source and the dashboards and reports that use it. See [Shape what a report says](report-structure.md).
-
-The old tab names still work. A link to Library opens Charts. A link to Drafts opens Reports.
-
-The headline deck of the Reports page is above the tabs. It shows only report signals: claims that block sending, ticket keys in a leadership report, a digest that is due, and people who hold an old date. It never repeats the Briefing's cards. When there is no report signal, the deck says that nothing needs you. The scope buttons are on the same row as the tabs.
-
-## Choose a scope
-
-Press **Portfolio**, **Board** or **Initiative**.
-
-- **Portfolio** covers every initiative.
-- **Board** covers the initiatives of one board. A board is a domain. Choose it from the list beside the scope.
-- **Initiative** covers one initiative. Choose it from the list.
-
-A report shows only the rows that belong to the scope. A report with no rows in the scope shows an empty card. The card says what is missing and what fills it. The workspace never invents a number.
-
-## The reports
-
-| Report | The question it answers |
-|---|---|
-| North star | Is the north-star metric on its plan? |
-| Quarter outcomes | Where is each key result, where should it be, and where will it land? |
-| Early signals | What is drifting before the numbers say so? |
-| Delivery against promise | Which promised dates will hold? |
-| Maturity by pillar | Where does each pillar stand against its target? |
-| Bets and their checkpoints | When does each bet persevere or pivot? |
-| Synergy and coverage | Do the bets add up to the key results? |
-
-The Calendar page no longer carries these. They moved here.
-
-## Edit a dashboard
-
-1. Press **Edit dashboard**.
-2. Use the arrows to move a report. Press the cross to take one off. The report stays in the library, and **Undo** brings it back.
-3. Choose a report under **Add from the report library**.
-4. Press **Done editing**.
-
-The workspace keeps your layout for each scope in its runtime state. It does not write to the repository. **Reset to default** returns a scope to its first layout.
-
-## Send a dashboard as a report
-
-A dashboard is live. A report is a document that you send on a day. To send a dashboard as a report, press **Send this as a report…** in the head of the dashboard.
-
-1. A sheet shows the proposed report: its name, what it is built from, the output, the schedule and the audience.
-2. Change the name. Choose the output: **PDF** or **Google Slides**. Choose the schedule: **Weekly**, **Every 2 weeks** or **Monthly**. Choose the audience: **Leadership** or **Team**.
-3. Press **Set up**.
-
-PMOS shows the first draft date. Each cycle is a snapshot document of the dashboard as it was on that day. The document is in Reports, under Documents, and the set-up is under Set up. The dashboard stays live.
-
-PMOS drafts only. It sends nothing. It writes to Google only when you press **Create the copy** in the document.
-
-The Share sheet and the schedule control of a dashboard are gone. Each schedule is now the schedule of a report. See and change it in Reports, under Set up.
-

package/workspace/guide/reports-page.md

@@ -1,87 +0,0 @@
----
-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-15
----
-
-# 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 Reports page has three tabs: Dashboards, Reports and Charts. See [Reports: dashboards of reports](reports-dashboards.md) and [Set up a report by asking](reports-set-up.md).
-
-The Reports tab is for the documents that you issue. It has four parts:
-
-- **Ask PMOS.** Describe a report. PMOS drafts it.
-- **Found in your work.** The reports PMOS found that you already issue.
-- **Set up.** One row for each report with a schedule.
-- **Documents.** One row for each cycle of each report. A draft or an issued document opens in the [document sheet](document-sheet.md).
-
-The parts that this guide describes below, such as Draft now, Edit notes and the report schedules, are the controls of the cadence report. The Reports tab does not show them. The `pmos report` commands in "In a terminal" do the same acts.
-
-## 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.
-
-For a report with a saved structure, **Draft now** starts a session that follows the structure. The button shows **Drafting…** until the draft is ready, and a notice says when it is. A **Redraft**, and a draft at a slot you name, stay instant. A report with no saved structure is drafted at once.
-
-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.