create-pmos 0.52.0 → 0.53.1

package/workspace/guide/integrated-work.md

@@ -0,0 +1,94 @@
+---
+type: Guide
+title: "Integrated work: from a merged commit to Done"
+description: "How pmos verify-work marks factory work items integrated from the default branch, how a plan item then reads Done, when the Build step is done, why factory work starts only from Now, and the two factory health reasons."
+timestamp: 2026-10-05
+---
+
+# Integrated work: from a merged commit to Done
+
+Some items of a breakdown go to the factory. The factory does the work in the product repository and opens a pull request. This page tells you how a merged pull request makes its item Done, and what the workspace shows on the way.
+
+## Two ledgers, one link
+
+- The breakdown items are in `planning/runs/plan-items.jsonl`. You and the agent write this file. See [Breakdown](breakdown.md).
+- The factory work items are in `planning/work-items.jsonl`. Only the factory writer adds lines to this file.
+- When an item goes to the factory, its work item gets the field `plan_item`. This field holds the id of the breakdown item, for example `checkout.k3m9x2a7qd`. It is the only link between the two files.
+- A breakdown line never goes into `planning/work-items.jsonl`. The checker in CI stops a `plan_item` that names no breakdown item.
+
+## Factory work starts only from Now
+
+An initiative must be in Now before the factory takes work for it. This rule applies to a feature that is anchored to a KR. It does not apply to a chore, an incident or an initiative anchored to a health budget.
+
+If the initiative is in Next or Later, the factory refuses the work and gives the reason. The factory also refuses the work when Initiatives shows "Now, unconfirmed": only a Now that you confirmed counts. To continue:
+
+1. Open Initiatives.
+2. Move the initiative to Now, or confirm it in Now. Only you can do this.
+3. Send the work to the factory again.
+
+## Mark merged work: `pmos verify-work`
+
+A commit can name a work item in a trailer, on its own line at the end of the commit message:
+
+```
+Work-Item: checkout.3
+```
+
+When that commit is on the default branch, the work item is integrated. To record this, run:
+
+```
+pmos verify-work
+```
+
+The command does these steps:
+
+1. It finds the default branch in the local refs: `origin/main`, `main`, `origin/master` or `master`, in that order. It does not fetch. To see new commits, pull first (Sync).
+2. It reads the `Work-Item:` trailers on that branch.
+3. For each work item that is not integrated yet, it adds one `integrated` line to `planning/work-items.jsonl`. The line names the commit.
+
+You can run the command again at any time. A work item that is already integrated is not written again.
+
+Options:
+
+- `--branch <ref>` reads only the commits up to `<ref>`. The ref must be on the default branch. A ref that is not merged is refused, and the command writes nothing.
+- `--dry-run` shows what the command would write, and writes nothing.
+- `--json` prints the result as JSON.
+- `--root <dir>` runs in a different repository.
+
+The command runs the repository's own copy of `scripts/verify-work.js`. A repository with no factory writer has no work items, and the command tells you so.
+
+### What the command does not write
+
+The command reports these cases and writes nothing for them:
+
+- **Refused.** The work item is merged, but the factory writer does not accept `integrated` yet. Usually the work item was not verified, or its last check failed. The line shows the reason from the writer. The command then exits with 1.
+- **Unknown.** A trailer names a work item that is not in the ledger.
+
+A commit that is only on another branch is not read.
+
+## What you see on the item
+
+- **Done.** When its work item is integrated, the breakdown item reads Done. Nobody moves it by hand, and no line is added to `plan-items.jsonl`.
+- **Done · your call · not merged.** You moved the item to Done, but its work item is not integrated yet. The item stays Done because you decided it. The text tells you that the work is not on the default branch.
+
+## When the Build step is done
+
+An item never completes a stage, with one exception. For a code initiative, the Build step is done when every factory work item under Build is integrated. The work items under Build are the ones whose `plan_item` is a breakdown item in the Build stage.
+
+- While one of them is not integrated, the Build step is pending. The step names the work items it waits for.
+- A breakdown item that you move to Done by hand does not complete the Build step.
+- A withdrawn work item, or a withdrawn breakdown item, is not counted.
+- When no work item names a breakdown item under Build, the commits decide the Build step, as before.
+
+CI, the `node scripts/workflow-state.js` command and the workspace use the same rule, so they show the same Build step.
+
+## Factory health
+
+Two health reasons come from the factory. Each shows its reason as text.
+
+- **Off track.** A factory work item failed its check, and nobody fixed it or withdrew it.
+- **At risk.** The initiative is in Next or Later, but the factory claimed work for it, or commits on the trunk are attributed to it. Building starts only from Now. Move the initiative to Now, or stop the work.
+
+## Where to read next
+
+- [Breakdown](breakdown.md): the items of an initiative, the Tree and the Board.

package/workspace/guide/knowledge-graph.md

@@ -68,84 +68,19 @@ The workspace decides the category with local rules only. It uses no model and s
 
 When a later rule disagrees with the rule that decided, the file keeps the earlier answer. A `Reference` or `Research` file with no better evidence has no category. It shows as `undetermined`. That is not the same as `other`: `other` means the file is none of the kinds, and `undetermined` means no rule could tell.
 
-The Knowledge view shows the category after each document name. Point at it to see which rule decided. Press a category above the list to show only those documents, and press it again to show all. The category is advisory. `pmos kg stats` counts the files in each category.
-
-### Ask Jev about undetermined files
-
-Jev can give a category to a file that the local rules leave `undetermined`. This is off until you turn it on. Jev never sees a file that already has a category from a local rule or from your correction. The measured pass below is the one exception for the local rules.
-
-Three things must all be on before anything is sent:
-
-1. A TypeSafe key, saved on the Validate page.
-2. Validation, switched on for this repository.
-3. **Categorize with Jev**, the switch in the Knowledge view.
-
-If one of them is off, the Knowledge view tells you which one.
-
-To start:
-
-1. Turn on **categorize with Jev**.
-2. Press **ask Jev about undetermined files**. The view shows how many requests it will send, about how many characters, and the host. Nothing is sent yet.
-3. Press **confirm and send** to send that number. If the files changed after you looked, even when the number is the same, the send stops and you look again.
-
-After the first confirmed send, the workspace sends only new or changed undetermined files. It does this when it reads the documents of this repository, at most once a minute. It reads them when it starts and when you open the Knowledge view. If more than 25 files wait, it does not send them. It tells you, and you confirm the count again.
-
-What is sent for each file: the title, the headings and the start of the text, at most 3,000 characters. The file path and the whole file are not sent. A file under an excluded path is not sent. A file whose start looks like a password or a key is not sent.
-
-Jev's answer shows as the category with `(jev)` after it. Point at it to see how sure Jev was, in words. If Jev was not sure, the file stays `undetermined` with `(jev unsure)` after it, and the tooltip names the two categories Jev was between. A Jev category is advisory. Each answer is kept on your computer, outside the repository, and the same text is not sent twice. Nothing is written into the repository.
-
-After a pass, the Knowledge view shows what happened to each undetermined file. Files with a problem are at the top of the list:
-
-- **failed**: the request did not succeed. The row gives the reason. The file keeps the local result, and the next pass sends it again.
-- **not asked**: sending stopped before this file. The row gives the reason.
-- **unreadable**: the workspace could not read Jev's answer. The file is not sent again until it changes.
-- **unsure**: Jev was not sure. The row names the two categories, and the file stays `undetermined`.
-- **withheld** or **excluded**: the file was not sent. The row says why.
-- **categorized**: Jev gave a category. The row names it.
-
-A line above the list counts the files in the view: decided by the local rules or your corrections, categorized by Jev, and still `undetermined`.
-
-If the service rejects the key two times, cannot be reached three times in a row, or sends three answers in a row that the workspace cannot read, sending stops for this repository. An answer that cannot be read is not sent again. Press **resume** to start again.
+The Knowledge view is cut, so no screen lists the category of a document. The category is advisory. `pmos kg stats` counts the files in each category, and the Knowledge scope of ⌘K finds a document by its name.
 
 ### Measure how well Jev categorizes
 
 The measured pass sends the files of the labelled set to Jev and compares the answers with the labels. It runs only when you start it in a terminal. The workspace never starts it.
 
-The measured pass also sends labelled files that a local rule already decides, because it measures Jev on them. It does not send a file that you corrected. The three switches, the excluded paths and the password and key check apply as for the Knowledge view.
+The measured pass also sends labelled files that a local rule already decides, because it measures Jev on them. It does not send a file that you corrected. The switches for the repository, the excluded paths and the password and key check apply to it.
 
 1. Run `node workspace/doc-category-bench.js --jev`. It shows how many files it would send, about how many characters, the host, and a `--confirm` value. It sends nothing.
 2. Read which categories the labelled set cannot test. When a category has no label in the set, the result says nothing about that category.
 3. To send, run the command again with `--confirm` and the value it showed, for example `--confirm 40:372a…`. The value holds the count and the files. If the files changed, nothing is sent and you look again.
 
-It uses the key that you saved on the Validate page, or `TYPESAFE_API_KEY` in the terminal. It prints the agreement, each category, how many answers were unsure, how many files were not sent and why, and every disagreement. The labels in the set are not yet confirmed, so the result is provisional. Only one pass at a time runs for a repository. If the workspace is sending, the command stops and sends nothing.
-
-### Correct a category
-
-When a category is wrong, set the correct one. Your correction comes before all five rules.
-
-1. In the Knowledge view, press **fix** at the end of the document row.
-2. Select the category. For a `ticket`, also select the ticket kind.
-3. Press **save correction**.
-
-The category after the document name changes. Point at it: it says `decided by pm correction`. When a rule gives a different category, the text names that rule too.
-
-The workspace keeps your corrections in its runtime state directory, never in the repository. Each repository has its own corrections. A correction does not change a file. To remove a correction, press **fix** and then **clear correction**. The rules then decide again.
-
-### Write the category into the file
-
-You can also write the category into the document, as a `category:` line in its frontmatter. This is a separate step, and it is the only step here that changes a file.
-
-1. Press **fix** and select the category.
-2. Press **write it into the file**. The workspace shows the change. It does not write yet.
-3. Examine the change. Press **apply** to write it, or **cancel**.
-
-The workspace changes one `category:` line in the frontmatter block at the top of the file. For a ticket, it also changes one `ticket_kind:` line. It adds the line when there is none. No other line of the file changes.
-
-The workspace does not write when:
-
-- The file has no frontmatter block at the top. It does not add a block.
-- The frontmatter has two `category:` lines.
-- The file changed after the workspace showed you the change. Press **write it into the file** again to see the new change.
+It uses the key that you saved on the Validate page (Settings › Validate consent › Open Validate), or `TYPESAFE_API_KEY` in the terminal. It prints the agreement, each category, how many answers were unsure, how many files were not sent and why, and every disagreement. The labels in the set are not yet confirmed, so the result is provisional. Only one pass at a time runs for a repository. If the workspace is sending, the command stops and sends nothing.
 
 ## Where the map is kept
 

package/workspace/guide/launcher.md

@@ -0,0 +1,51 @@
+---
+type: Guide
+title: "Start the workspace without a terminal"
+timestamp: 2026-10-06
+---
+
+# Start the workspace without a terminal
+
+`pmos launcher` makes a PMOS app and a login item. After you set it up once, you do not need a terminal to start the workspace.
+
+## Set it up once
+
+Open a terminal in the repository that the app must open. Type:
+
+```sh
+pmos launcher on
+```
+
+To set up a different repository, give its path: `pmos launcher on ~/code/my-product`.
+
+This command writes two things:
+
+| Thing | macOS | Linux |
+|---|---|---|
+| The PMOS app | `~/Applications/PMOS.app`. Open it from Spotlight or Launchpad, or drag it to the Dock. | An app menu entry, `~/.local/share/applications/pmos.desktop`. |
+| The login item | `~/Library/LaunchAgents/com.pmos.workspace.plist` | `~/.config/autostart/pmos-workspace.desktop` |
+
+To make only the app, without the login item, type `pmos launcher on --no-login`.
+
+## What each one does
+
+- **The app** opens the workspace in your browser. When no server runs, it starts one first. It does the same thing as `pmos` in a terminal.
+- **The login item** starts the workspace server when you log in. It does not open a browser window. Open the app when you want the window.
+
+Both run `pmos up` on the repository you chose. They use the PATH that your terminal had when you typed `pmos launcher on`. That is how they find `claude`, `git` and `tmux`.
+
+What each start printed is in `launcher.log`, in the workspace state folder (`~/Library/Application Support/pmos` on macOS, `~/.local/state/pmos` on Linux).
+
+## Check it
+
+Type `pmos launcher status`. It shows the repository, the node program and the `pmos` program that the app uses, and whether the login item is installed. A path marked "not found" stops the app. If you move or upgrade node, type `pmos launcher on` again.
+
+## Remove it
+
+Type `pmos launcher off`. It removes the app and the login item. It removes only files that `pmos launcher on` wrote. A file with the same name that you wrote yourself stays.
+
+## Limits
+
+- The login item never starts remote (tailnet) mode, and it writes no token. To open the workspace from your phone, start remote mode yourself as `workspace/REMOTE.md` tells you.
+- Native Windows is not supported. The workspace needs WSL on Windows. Type `pmos launcher on` inside WSL.
+- The login item runs once, at login. If the server stops, open the app to start it again.

package/workspace/guide/layout.md

@@ -1,27 +1,105 @@
 ---
 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.
+- To make the dock wider or narrower, drag its left edge. With the edge focused, the left and right arrow keys change the width in steps. Double-click the edge to go back to the default width. The width is kept in this browser.
+- **Focus** in the dock gives the dock the whole window. The place and the detail are hidden, and the dock stays full width on every place. Press **Exit focus**, or ⌘⇧J (Ctrl-Shift-J), to show the place again. Folding the dock also ends Focus.
+- **▲ scratchpad** in the bar under the tabs opens the scratchpad. The pad keeps one note for each terminal session, and one for the repository when no terminal is in front. **Send to terminal** types the note into the session in front.
+
+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 (Ctrl-Shift-J) | Focus: give the dock the whole window, or show the place again. |
+| 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 +115,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 +145,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 +172,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`.