create-pmos 0.38.8 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.38.8",
+  "version": "0.40.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@6e5901f
+kernel-source: pmos@cd7bc4a
 assembled: 2026-10-03
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T10:44:27Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T10:44:27Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-03T03:25:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T10:44:27Z"}
 status: stable
 ---
 

package/workspace/README.md

@@ -46,6 +46,42 @@ npm run test:ui      # browser checks: terminal geometry, reader scroll, markdow
 ```
 </details>
 
+## Status clarity and the user guide (`status-clarity`)
+
+The initiative list can say what each status means. Choose **status**, then **what do these mean?**: one row per group with what it means, the fact it is read from, who acts, what moves it and what you can do. The text comes from `lib/status-groups.js`, the table that also files the rows, so the legend and the grouping cannot disagree.
+
+The initiative detail opens with a **status banner**: the group, why (the evidence the server derived, for example the open item in its own words), who acts, the next thing to do, and what changes the status. Next steps are split into **yours** and **mine**; each item has an `id`, an `owner` (`pm` or `agent`) and `act` (`null` for now). Hold, close, cancel and reopen are explained under the control and every change is listed. No other status can be set by hand: they are read from git and the ledgers. Acceptance is the PM's and is recorded in a session, so the banner says how and the workspace never records one.
+
+Files listed under **files from git** open in a read-only tab. A file that exists only on the initiative's branch is read from that branch through `GET /api/doc?ref=initiative/<id>` (an initiative branch only, text under 2 MB). A binary file says it cannot be previewed.
+
+The user guide is `workspace/guide/*.md`. The **guide** item in the settings and tools drawer opens its pages in a read-only tab (`GET /api/guide`). A change to `workspace/public/pm/**` must change the guide in the same pull request (a workspace CI step), and `guide.test.js` fails when a status group, a drawer item or a `pmos` command is not mentioned.
+
+## Three columns (`column-layout`)
+
+The desktop has three columns: **navigation**, **detail** and **tabs**. Navigation is the repository list with the list of the current mode under it (the initiatives of the selected repository, or memory, skills, knowledge, scheduled tasks, focus, portfolio, the guide). The repository list is capped at 42% of the height and scrolls inside its cap, so the list under it stays on screen. The detail column shows an initiative. The tabs column holds terminals, documents, conversations and guide pages and is never rebuilt by a layout change.
+
+The DOM still holds four hosts in the same order (repositories, list, detail, tabs); `placeHosts` in `public/pm/app.js` puts the list host under the repositories by grid placement. About a hundred test assertions and the phone layout depend on that order, so it is not changed. The list folds to a one-line bar, the navigation column folds to a 36px rail (the list folds with it), and the detail column folds to its own rail. Drag the navigation column's right edge to resize it (220 to 560px); a double click restores 280px. `state.js` no longer stores `col1W`; an old stored layout loads and keeps its tabs.
+
+`MODE_PLACE` in `public/pm/modes.js` is the rule for where things open, and `ROW_OPENS` says what a row in each list opens: an initiative opens in the detail column, a skill, a knowledge note or a guide page opens in a tab, and a schedule or a memory entry is used inside the list. A list or a detail kind missing from these tables fails `pm-r19-test.js`.
+
+## Next-step actions (`next-step-actions`)
+
+Each next step carries an `act` (`open`, `session`, `work`, `gate`, `lifecycle`; `lib/next-step-actions.js`). For a `work` step the PM presses **prepare**, which returns a plan and creates nothing (`POST /api/next-step/prepare`): the branch and tree (`startPreview`: an existing `initiative/<id>` worktree is reused, otherwise one is created on go), the sessions already running on the initiative, the read-only sources the chosen profile declares and that suit the step, whether the typed-judgment helper is on, the session budget, and the exact first input with its hash. **Go** (`POST /api/next-step/go`, `confirm: true`, the hash) re-prepares, refuses if anything differs from what was shown, and starts the session through `startWork` with `origin: next-step` and the prompt as `initialInput`. The socket's `start` message still cannot carry a prompt.
+
+Only the step the ladder has reached can be prepared; the build is refused until the pre-run contract is PM-approved; the contract, acceptance and open items are `gate` acts and have no start control; a stopped initiative must be reopened. The prompt states the propose-only boundary (`RULES`): commit to the local branch or write drafts; no push, pull request, send, post, ticket, acceptance, contract approval or merge. `lib/session-budget.js` limits sessions started from steps (3 at once, 8 a day, `GET`/`POST /api/next-step/settings`); sessions started by hand are never counted.
+
+`lib/judgment.js` owns the instruction that tells a session to use the Typesafe skill (off by default, per run; it needs `TYPESAFE_API_KEY` and sends the question text to an outside service) and the shape check for `JUDGMENT {json}` lines (classify, score, yes or no). The next-step routes and modules make no model or network call (the one named egress in the workspace is D79's repository validation, a separate feature).
+
+After the session ends, `GET /api/next-step/summary` returns the files the branch changed against trunk, the end of the conversation and the judgments, checked; `POST /api/next-step/review` records the PM's verdict (`accept` or `send-back` with a note). Runs and verdicts are `next-step-runs.jsonl` and `step-reviews.jsonl` in the runtime state directory. A verdict never changes the initiative's status.
+
+## Today: what is waiting for you (`proactive-engine`, slice D1)
+
+`lib/proactive.js` is a pure core: it reads the records the workspace already derives and finds five conditions: a need waiting on the PM, an initiative returned at acceptance, an ended next-step session with no review, a scheduled task whose last run failed, and an active initiative with no agent run for the stalled threshold (5 days by default). The ranking is fixed and stated in the guide. `GET /api/proactive/today` computes the list on each request. A scan (`POST /api/proactive/scan`, and a 10-minute automatic tick inside the existing 60-second interval) appends new items once a day to `signals.jsonl`. Feedback (`useful`, `not-useful`, `wrong-priority`, `missed` with a note, and the events `opened`, `dismissed`) is appended to `proactive-feedback.jsonl`; a dismissed item is hidden for 7 days. Settings are in `proactive-settings.json` (engine on or off, one trigger off, the stalled threshold, quiet hours, pause learning; the last has no effect yet because nothing learns from the verdicts in this slice). The same actions are in `pmos proactive today|scan|settings|feedback` (`lib/proactive-cli.js`), a thin client of those routes. The list is drawn in the navigation column by the `today` drawer item. It runs only while the server runs, reads no mail or calendar, and starts no session, sends nothing and changes no record of an initiative (`proactive.test.js` E25-E26 read the source for that). Tests: `proactive.test.js` (pure core, routes, CLI) and `pm-r22-test.js` (the page). The guide page is `guide/proactive-engine.md`.
+
+## The morning brief (`proactive-engine`, slice D2)
+
+The top of Today is a brief: a greeting, the day's calendar, ranked priorities and a worth-asking list. The server does not build it. The built-in skill `skills/morning-brief.skill` runs in an agent session, reads the sources the settings allow (calendar, wispr, mail, jira, confluence; mail is off by default) and the derived list (`pmos proactive today`), and submits one brief with `pmos proactive brief submit --file`. `POST /api/proactive/brief` checks it with `lib/brief.js` and stores `briefs/<date>.json` in the runtime state folder, replacing any earlier brief for the same day; `GET` returns the newest one with a `stale` flag when its date is not today. The check refuses, with the reason and without storing, a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, an over-long field, an item that rests on a source not reported as read, a source reported as read that the settings switched off, and a claim of typed scoring when that setting is off. The bucket is derived: under 0.5 confidence is "worth asking". The order is fixed: confidence, then PM-owned, then title. `POST /api/schedules/seed` with `set: "brief"` (one press in Today, or `pmos proactive brief schedule`) makes the daily 06:45 schedule once; as with every schedule, one made after its time of day runs once within a minute. The routes make no model or network call and write only the brief file. Typed scoring is a standing opt-in setting that is off by default. Tests: `proactive.test.js` G, H, I and `pm-r22-test.js` B1-B11. The guide page is `guide/proactive-engine.md`.
+
 ## Scheduled tasks from the terminal (`schedule-cli`)
 
 `pmos schedule` and `pmos skill` talk to the running workspace server, so the terminal and the workspace share one schedule store and one validator. Every change is saved the moment the command succeeds. A refused value names what is allowed and changes nothing. With no server running the command says so and exits 1.
@@ -99,7 +135,7 @@ The three-column layout is retired. The surface is now **four collapsible panels
 **Fixture mode.** `?fixture=proto` renders the whole surface from a bundled seed file, with the server unable to read any repository — that is how the design comparison is run (`npm run test:parity`), and it is never the default.
 
 ## Artifact links are declarations, not integrations
-The PMOS server makes no outbound request and holds no credential, and the workspace makes no request you did not ask for. Its git network verbs are named and press-only: `Sync` runs `fetch`, a fast-forward or an own-commit rebase, a commit of record paths, and `push` — only when you press it, never on a timer or on load, never forced ([D70](/okf/products/pmos/adr/d70-stopped-initiatives-and-sync.md)). A web page opens in a tab only when you type or click its address, and a restored web tab loads only when you press "load this page" ([D69](/okf/products/pmos/adr/d69-web-tab.md)). Linking an artifact to an external destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to `pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector configured its summary line says exactly that: *no connector configured — nothing was read, and nothing will be written*, with the approval buttons disabled. A difference summary it never read would be the watermelon this repo has a word for.
+The PMOS server makes no outbound request and holds no credential, with one named exception ([D79](/okf/products/pmos/adr/d79-typesafe-validation-egress.md)): when you save a TypeSafe key and turn validation on for a repository, the **validate** page sends that repository's document text to `api.typesafe.ai`, from one module, only after you confirm the plan. With no key, nothing is sent. The key stays on this machine, is never shown again, and is never given to a terminal. The consistency checks at the top of the **validate** page are local: they read files and git and send nothing. Automatic checking is off until you switch it on for a repository, and then the workspace appends problems to that repository's `claims.jsonl`. The workspace makes no request you did not ask for. Its git network verbs are named and press-only: `Sync` runs `fetch`, a fast-forward or an own-commit rebase, a commit of record paths, and `push` — only when you press it, never on a timer or on load, never forced ([D70](/okf/products/pmos/adr/d70-stopped-initiatives-and-sync.md)). A web page opens in a tab only when you type or click its address, and a restored web tab loads only when you press "load this page" ([D69](/okf/products/pmos/adr/d69-web-tab.md)). Linking an artifact to an external destination therefore records a **declaration** — `{artifact_path, kind, target}` appended to `pmos/state/artifact-links.jsonl`. The sync panel renders as designed, and with no connector configured its summary line says exactly that: *no connector configured — nothing was read, and nothing will be written*, with the approval buttons disabled. A difference summary it never read would be the watermelon this repo has a word for.
 
 ## The gates are real, never automatic (R5)
 `approve` / `return` / `accept` write the PMOS file-mode vocabulary to `acceptances.jsonl` and clear the matching needs entry — only ever on your click.

package/workspace/bin/pmos.js

@@ -396,6 +396,12 @@ function doctor() {
     code = await require('../lib/schedule-cli').run(process.argv.slice(2), {
       say, call: async (m, p, b) => (port ? api(port, m, p, b) : null) });
   }
+  else if (cmd === 'proactive') {
+    const live = await discover();
+    const port = live.length ? live[0].port : null;
+    code = await require('../lib/proactive-cli').run(process.argv.slice(2), {
+      say, call: async (m, p, b) => (port ? api(port, m, p, b) : null) });
+  }
   else if (cmd === 'upgrade') {
     // Escape hatch: pull the latest bundled app and force-reinstall over this global copy. Delegates
     // to the scaffolder (which owns the install path) rather than reinstalling itself in place.
@@ -407,11 +413,12 @@ function doctor() {
     if (r.error) { say('✗ could not run ' + npx + ' — ' + r.error.message); code = 1; }
     else code = r.status === null ? 1 : r.status;
   } else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
-    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill]');
+    say('usage: pmos [<path>|status|ls|stop|doctor|upgrade|schedule|skill|proactive]');
     say('  pmos          open the current repo as a workspace (starts the server if needed)');
     say('  pmos <path>   open another repo as a workspace');
     say('  pmos schedule …  create, edit and run scheduled tasks (pmos schedule --help)');
     say('  pmos skill …     list, read, create and edit skills');
+    say('  pmos proactive … what is waiting for you, feedback, settings (pmos proactive --help)');
     say('  pmos upgrade  reinstall the workspace app from the latest published create-pmos');
     code = 0;
   } else if (cmd === 'up' || cmd === 'start' || cmd === 'open') {

package/workspace/guide/index.md

@@ -0,0 +1,40 @@
+---
+type: Guide
+title: "Guide: start here"
+timestamp: 2026-10-03
+---
+
+# Guide: start here
+
+This guide describes the PMOS workspace as it works today. It ships with the app. When a change alters how the workspace looks or behaves, the same change updates this guide.
+
+## The screen
+
+The workspace has three columns. [Layout](layout.md) explains where things open.
+
+1. **Navigation.** The repositories you added, with the list of the current mode under them. The default list is the initiatives of the selected repository. The settings and tools drawer at the bottom opens the other lists here.
+2. **The detail.** The item you selected: an initiative with its status, next steps and artifacts, or a skill, a schedule or a memory item.
+3. **Tabs.** Terminals, documents, conversations and guide pages.
+
+## The settings and tools drawer
+
+| Item | What it opens |
+|---|---|
+| today | What is waiting for you now, with your feedback and the settings of the proactive engine. |
+| memory | What the repository remembers: decisions and notes kept in its memory ledger. |
+| knowledge | The decisions, concepts and skills of the repository. |
+| portfolio | Every initiative of every repository, grouped by domain. |
+| guide | This guide. |
+| validate | Checks that one repository agrees with itself, on your machine. It can also check with TypeSafe, which sends text only after you turn it on. |
+| focus | What is waiting on you, across all repositories. |
+| skills | Built-in and user skills. A built-in is read-only. |
+| scheduled tasks | Skills that run on a schedule. |
+
+## Where to read next
+
+- [Layout](layout.md): the three columns and the rule for where a list or a detail opens.
+- [Statuses](statuses.md): what each status means, where it comes from, and what you can change.
+- [Initiatives and next steps](initiatives-and-next-steps.md): the detail, the next steps, and the artifacts.
+- [Scheduled tasks and the command line](scheduled-tasks-and-cli.md): how to make, edit and run scheduled tasks.
+- [Validate a repository](validate-with-typesafe.md): what each kind of document is compared with, how to read the verdict, and what leaves your machine.
+- [Today and the proactive engine](proactive-engine.md): what Today finds, what you can do with an item, the settings, the commands and the limits.

package/workspace/guide/initiatives-and-next-steps.md

@@ -0,0 +1,72 @@
+---
+type: Guide
+title: "Guide: initiatives and next steps"
+timestamp: 2026-10-03
+---
+
+# Guide: initiatives and next steps
+
+Select an initiative in the list. The detail opens in the detail column.
+
+## What the detail shows, top to bottom
+
+1. **Status.** The status, why it has that status, who acts now, the next thing to do, and when the status changes. If the status is Needs you, each open item is listed in its own words. If the status cannot be read, the detail says so and shows no status.
+2. **Lifecycle control.** Hold, close, cancel or reopen. Beneath it, the history of every change.
+3. **Next steps to done.** Everything between now and acceptance, in order. See below.
+4. **Phases and links.** The workflow phases and the external links.
+5. **Artifacts.** Documents, conversations and files.
+
+## Next steps
+
+The list comes from the workflow ladder, the ledgers and the running sessions. The workspace does not write it with a model. Every step names the fact it came from.
+
+The list has two parts:
+
+- **Yours.** Steps only you can do. Acceptance, approval of the contract and answers to open items belong here.
+- **Mine.** Steps the agent does.
+
+The numbers run along the whole path. The step marked **next** is the one the workflow names first. A stopped initiative lists a reopen step first. An accepted initiative has none.
+
+## Acting on a step
+
+Each step says what you can do with it. The control sits under the step.
+
+| Act | What it is | The control |
+|---|---|---|
+| `work` | An agent session can do this step. | **prepare**, then **go** |
+| `open` | The step is yours, and it points at a file you should read. | **open** the file |
+| `session` | A session is already running on it. | **switch to it** |
+| `gate` | The step is yours alone: accepting the initiative, approving the contract, answering an open item. | Words only. There is no start button. |
+| `lifecycle` | The initiative is stopped. | **reopen** |
+
+### Prepare, then go
+
+**Prepare** shows a plan and starts nothing. The plan names the branch and the folder, says whether the initiative's branch already exists (it is reused) or would be created, lists the sessions already running on the initiative, names the read-only sources the session may use, and shows the budget. It also shows the exact first input the session would receive. Preparing creates no branch, folder or session.
+
+**Go** starts one session with exactly that input. The workspace refuses if the plan changed after you read it. In that case, prepare again.
+
+A step the workflow has not reached cannot be prepared. The build cannot be prepared until you approve the contract. A stopped initiative must be reopened first. The workspace says which step comes first.
+
+### What the session may do
+
+The session proposes. It commits to the local initiative branch or writes draft files. It does not push, open a pull request, send or post anything, create a ticket, record an acceptance, approve a contract or merge. Those are yours.
+
+### The budget
+
+At most 3 prepared sessions run at once and 8 start each day. Go refuses a start over either limit and says the number. Sessions you start by hand are never counted or blocked. Change the limits with `POST /api/next-step/settings`.
+
+### Sources and the typed judgment option
+
+Choose a profile in the plan. The session may read only the sources that profile declares and that suit the step: Wispr Flow notes, Gmail, Google Calendar, Confluence, Jira and Slack. They are read-only.
+
+You can turn on the Typesafe skill for a run. It helps the session categorise, score and decide yes or no with a typed answer. It sends the question text to an outside service and needs `TYPESAFE_API_KEY` in the session. It is off by default. The session prints each answer as a `JUDGMENT` line, and the review checks its shape.
+
+### Review
+
+After the session ends, the step offers **review what it did**. The review lists the files the branch changed against trunk, shows the end of the conversation, and lists any judgments the session reported, with those that failed the shape check marked. Then choose **accept the step** or **send it back**. A send-back needs a note. Your verdict is recorded in the runtime state folder. Accepting a step does not accept the initiative. Acceptance stays at the Acceptance Gate.
+
+## Artifacts
+
+- **Documents** open in a tab. You can edit them.
+- **Conversations** are sessions bound to the initiative. A conversation is saved when its session ends. It opens read-only. It stays on this computer, in the runtime state folder. It is not in the repository.
+- **Files from git** are the files changed for the initiative. They open read-only in a tab. A file that exists only on the initiative branch opens from that branch. A file that cannot be previewed, such as a binary file, says so.

package/workspace/guide/layout.md

@@ -0,0 +1,73 @@
+---
+type: Guide
+title: "Guide: layout"
+timestamp: 2026-10-03
+---
+
+# Guide: layout
+
+The workspace has three columns. They are, from left to right, navigation, detail and tabs.
+
+## 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.
+
+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
+
+The second column shows one item in full. Choose an initiative, a skill, a schedule or a memory item, and its detail opens here.
+
+## 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
+
+Press a file anywhere in the workspace to open it in a tab. Any text file opens, whatever its extension.
+
+- **Markdown** opens as a document. You can edit it and save it.
+- **JSON** opens pretty-printed. If the file is not valid JSON, the tab shows the text as written and says why.
+- **JSONL** opens as numbered records, one for each line. The tab marks a line that is not valid JSON.
+- **Other text** opens as numbered source lines. Spreadsheets, PDFs and images open in their own views.
+
+A tab for a file that is not markdown is read-only. It has no edit, diff or save control, because the workspace saves only markdown.
+
+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
+
+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.
+
+## Folding
+
+- Choose the arrow in the header of the list to fold it to one line under the repositories. Choose the line to open it again.
+- Fold the navigation column to a thin strip. The list folds with it. Choose the strip to open it again.
+- Fold the detail column to its strip in the same way.
+
+The workspace remembers which columns are open and how wide the navigation column is.
+
+## On a phone
+
+A phone shows one panel at a time. The bottom bar moves between them.

package/workspace/guide/proactive-engine.md

@@ -0,0 +1,75 @@
+---
+type: Guide
+title: "Guide: Today and the proactive engine"
+timestamp: 2026-10-03
+---
+
+# Guide: Today and the proactive engine
+
+The today item shows what is waiting for you now. The workspace works it out by itself from the records of your repositories. You do not ask for it.
+
+## The morning brief
+
+The top of Today is the morning brief: a greeting, the day's calendar, the priorities and a list of things worth asking about. The brief is not computed by the workspace. A skill called morning-brief runs in an agent session. The session reads the sources, and then submits one brief with `pmos proactive brief submit`. The workspace server only checks the brief and stores it. It makes no model call and reaches no calendar or mailbox.
+
+- Press **schedule the morning brief** in Today to make a daily schedule at 06:45. The schedule is an ordinary scheduled task, so it runs only while the workspace server runs. A sleeping computer gets no brief. A schedule that is made after its time of day for the first time runs within a minute, so pressing the button at 10:00 starts one brief session straight away.
+- Each source is a setting: calendar, wispr, mail, jira and confluence. Mail is off by default and the skill reads only subjects and senders, never bodies. A source that is off cannot be reported as read.
+- The brief names the day it is for. If that is not today, Today says it is out of date.
+- An item the session is less than 0.5 sure about is shown under worth asking, not as a priority. The workspace sets that bucket from the confidence. The session cannot choose it.
+- The order is fixed: higher confidence first, then your items before the agent's, then by title.
+- Each item takes the same feedback as a derived item: useful, not useful and wrong priority.
+- Typed scoring is off by default. When you switch it on, the skill sends titles and metadata to the Typesafe service to score them. The brief says whether it used scoring. The workspace cannot check that claim.
+- A brief is refused, with the reason and with nothing stored, when it has a wrong shape, an unknown source, a confidence outside 0 to 1, more than 12 items or 20 events, or a text field that is too long.
+- The brief is stored in the workspace state folder on this computer. It is not committed.
+
+## What it shows
+
+Today scans for five conditions. Each one becomes one item with the reason and the evidence.
+
+| Trigger | What it finds |
+|---|---|
+| needs | A need that waits on you. |
+| returned | An initiative the PM returned at acceptance. |
+| review | An agent session that ended and has no review yet. |
+| schedule | A scheduled task whose last run failed. |
+| stalled | An active initiative with no run for the stalled threshold. The default is 5 days. |
+
+The order is fixed and you can read it: what blocks on you first, then an unreviewed session, then a failed schedule, then a stalled initiative. Inside one kind, the oldest item is first.
+
+## What you can do with an item
+
+- open takes you to the initiative or the schedule.
+- useful, not useful and wrong priority record your verdict.
+- dismiss 7 days hides the item for 7 days.
+- something was missed records a note about what Today should have shown. It needs a note.
+
+A verdict never changes a status, a lifecycle record or an acceptance. In this release a verdict is only recorded. Nothing uses it to change the order yet.
+
+## Settings
+
+| Setting | Meaning |
+|---|---|
+| engine on | Off stops automatic scans. The scan now button still works. |
+| watch: needs, returned, review, schedule, stalled | Turn one trigger off. |
+| brief sources | One switch for each of calendar, wispr, mail, jira and confluence. |
+| typed scoring | Off by default. On lets the skill send titles and metadata to the Typesafe service. |
+| name | Used in the greeting. |
+| stalled after N days | The stalled threshold, from 1 to 90 days. |
+| quiet hours | A start and an end time. No automatic scan runs between them. |
+| pause learning | Saved for later. Nothing learns from your verdicts in this release, so it changes nothing today. |
+
+## The commands
+
+- `pmos proactive today` lists the items.
+- `pmos proactive scan` scans now.
+- `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
+- `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
+- `pmos proactive feedback <id> useful|not-useful|wrong-priority|opened|dismissed` records feedback. Use `--missed "text"` for a missed item.
+
+## Limits
+
+- It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
+- The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
+- It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback.
+- An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
+- The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/guide/scheduled-tasks-and-cli.md

@@ -0,0 +1,41 @@
+---
+type: Guide
+title: "Guide: scheduled tasks and the command line"
+timestamp: 2026-10-03
+---
+
+# Guide: scheduled tasks and the command line
+
+A scheduled task runs a skill at a set time. The workspace starts a terminal session in the repository and types the skill into it.
+
+## Limits
+
+A schedule fires only while the workspace server runs. If the server is stopped, the workspace skips the missed slot. It does not catch up later. A one-time task has a 15-minute grace window.
+
+## The commands
+
+The commands talk to the running server. A change is saved when the command succeeds. A refused value names what is allowed and changes nothing. If no server runs, the command says so and exits with code 1.
+
+- `pmos schedule list` shows the schedules. Add `--all` for every repository.
+- `pmos schedule show <id|name>` shows one schedule, its next run, its last run and its status.
+- `pmos schedule add` makes a schedule. Use `--skill` and `--cadence`. Add `--from-session` or `--from-file` to make a new user skill from your work and schedule it.
+- `pmos schedule edit <id|name>` changes any field.
+- `pmos schedule run <id|name>` runs it now.
+- `pmos schedule enable <id|name>` and `pmos schedule disable <id|name>` turn it on and off.
+- `pmos schedule rm <id|name>` deletes it.
+- `pmos skill list` shows the skills.
+- `pmos skill show <name>` shows one skill.
+- `pmos skill new` makes a user skill.
+- `pmos skill edit <name> --file F` replaces a user skill's text.
+- `pmos skill copy <name>` makes an editable copy of a built-in skill.
+
+## The fields
+
+| Field | Meaning |
+|---|---|
+| `--cadence`, `--day`, `--day-of-month`, `--time`, `--date` | When it runs. Times are local to the computer. |
+| `--until`, `--max-runs` | When it stops. The schedule turns itself off when either is reached and records why. `none` clears one. |
+| `--args` | Extra instructions added to the skill. |
+| `--tier`, `--profile` | How it runs. |
+
+A skill's text never starts a session with `/`, because Claude Code would read that as a command. The workspace puts a short sentence before it.

package/workspace/guide/statuses.md

@@ -0,0 +1,53 @@
+---
+type: Guide
+title: "Guide: statuses"
+timestamp: 2026-10-03
+---
+
+# Guide: statuses
+
+Nobody types a status. The workspace works it out again each time you look. It reads the ledgers in the repository and git. Because of this, a status cannot become stale. It also means you cannot edit most statuses by hand.
+
+## The nine statuses
+
+| Status | Who acts | What it means |
+|---|---|---|
+| Needs you | You | Work is stopped on a decision or an answer only you can give. |
+| In progress | The agent | An agent run is logged and nothing is merged yet. |
+| Planning | The agent | The initiative is recorded and no run has started. |
+| Awaiting acceptance | You | The work is delivered. It waits for your acceptance. |
+| Accepted | Nobody | You accepted it. Nothing remains. |
+| On hold | You | You paused it. It is off the board. |
+| Closed | You | You closed it. It is off the board. |
+| Cancelled | You | You cancelled it. It is off the board. |
+| Unknown | Nobody | The status could not be worked out, so none is shown. |
+
+The first four are the active statuses. Choose **active only** in the list to hide the others.
+
+To read the same table in the app, choose **status** in the list, then **what do these mean?**. The app shows, for each status, the fact it is read from, what moves an initiative out of it, and what you can do.
+
+## Where each status comes from
+
+- **Needs you** comes from your latest acceptance row (a return), or from an open item in the needs queue that names the initiative.
+- **In progress** comes from `agent-runs.jsonl`: at least one run, and no merged `initiative/<id>` branch.
+- **Planning** means the record exists and `agent-runs.jsonl` has no run for it.
+- **Awaiting acceptance** comes from git: an `initiative/<id>` branch was merged, or a trunk commit names the initiative and changes build files. No acceptance row exists yet.
+- **Accepted** comes from your latest acceptance row.
+- **On hold**, **Closed** and **Cancelled** come from your latest line in `lifecycle.jsonl`.
+- **Unknown** appears when the trunk history or a ledger cannot be read. The detail gives the reason.
+
+## What you can change by hand
+
+You can hold, close, cancel or reopen an initiative. Each action writes one line to `lifecycle.jsonl` with your reason. A held, closed or cancelled initiative leaves the board and stops gating. Reopen puts it back. The detail lists every change.
+
+You cannot set any other status. To move an initiative from Awaiting acceptance to Accepted, record an acceptance. Acceptance is yours and nobody can do it for you. Tell the session that holds the initiative to record it, or run `scripts/record-acceptance.js`. The workspace never records an acceptance for you.
+
+## How a status changes
+
+A status changes when a fact changes:
+
+1. An agent logs its first run: Planning becomes In progress.
+2. A branch is merged: In progress becomes Awaiting acceptance.
+3. You return the work at acceptance: it becomes Needs you.
+4. You accept: it becomes Accepted.
+5. You hold, close or cancel: it moves to that status, whatever it was. Reopen returns it to the status its facts give.

package/workspace/guide/validate-with-typesafe.md

@@ -0,0 +1,80 @@
+---
+type: Guide
+title: "Guide: validate a repository"
+timestamp: 2026-10-03
+---
+
+# Guide: validate a repository
+
+The validate item checks the documents of one repository. It has two parts. The first part checks that the repository agrees with itself. It runs on your machine and sends nothing. The second part uses TypeSafe's Jev model for checks that need judgement. It sends text only after you turn it on.
+
+## Check that the repository agrees with itself
+
+The top of the validate page shows a verdict: *Consistent*, a number of problems, or *Not checked yet*. Press **check now** to get one.
+
+The workspace first decides what kind of document each file is. It uses the `type` in the file, an initiative record that names the file, the file name, or the headings. Then it compares the file only with what that kind of document must agree with:
+
+| Kind of document | Compared with |
+|---|---|
+| Initiative record | The PRD, rubric and explainer it points to. Each must exist and name the initiative. |
+| PRD | Its initiative record, its rubric, and the decisions it cites. |
+| Rubric | Its PRD. The dimension weights must sum to 1.00. |
+| Story | Its PRD. Each requirement the story cites must exist in the PRD. |
+| Decision record | The decisions file. The decision must be recorded there. |
+| Any other markdown file | Its own links and dates only. |
+| JSON file | Its own syntax only. |
+
+A file that nothing declares a kind for is **not classified**. The workspace never compares it with another file.
+
+Each document row shows what it was compared with. Each finding is one sentence. It names the documents and says what the source says. The groups are:
+
+- **Problems.** A statement is contradicted by its source. For example, a link points to a file that does not exist.
+- **Stale.** A source changed after the document did, or the date in the document has passed. A source must be at least one hour newer than the document to count.
+- **Worth a look.** The structure cannot decide. For example, a PRD does not name the rubric that names it.
+- **Checked and fine**, and **not classified.** Open a group to see its documents.
+
+The record of problems is the file `claims.jsonl` in the runs folder of a PMOS repository. Press its name to read it in a tab. It lists every claim that is not verified. It does not list claims that verified the first time.
+
+**Automatic checking** is off until you turn it on for a repository. When it is on, the workspace looks for changed files about every ten seconds. It waits until the files have stopped changing for about eight seconds. Then it re-checks the changed documents and the documents that cite them. It re-checks no others. The check reads only files that changed. It makes no network request.
+
+A verdict of *Consistent* means that no recorded statement contradicts its source. The workspace does not read prose. A sentence that no structure records is not checked.
+
+## Check with TypeSafe
+
+## What leaves your machine
+
+Validation is off until you turn it on. Until then, the workspace sends nothing.
+
+When you turn it on, the workspace sends document text to `api.typesafe.ai`. It sends nothing else. It does not send binary files. It does not send a document that you excluded. It does not send a document that matches a credential pattern, such as a private key or a token. It lists that document as withheld.
+
+The workspace reads the TypeSafe key only on this machine. After you save the key, the screen does not show it again. The workspace does not give the key to a terminal or to an agent.
+
+## Set it up
+
+1. Open **validate** in the settings and tools drawer.
+2. Under **TypeSafe key**, paste the key and press **save**. Press **remove** to delete a saved key.
+3. Under **this repository**, press **turn on**. This choice applies to the selected repository only.
+4. Enter the paths that the workspace must never send, one for each line. A path ends with `/` for a folder. A `*` matches any characters. Press **save excluded paths**.
+
+## Run a validation
+
+1. Press **show what would be sent**. The workspace shows the number of requests, the number of characters, and the documents it withholds. It sends nothing at this step.
+2. Press **confirm and send**. If the repository changed since the plan, the workspace refuses and asks you to read the plan again.
+
+The workspace does the local checks first. It finds links that point to a file that does not exist. It finds documents whose `stale_after` date has passed. It reads the workflow sweep. These checks send nothing.
+
+Then it asks Jev these questions about each document: Does the document contradict itself? Can a reader tell what it is for? Is the writing succinct? For an old document, it also asks if the document is out of date. For documents that link to each other, it asks if they state conflicting facts. For a document that names its sources, it asks if the source supports the claims.
+
+## Read the findings
+
+A finding has a severity, a rule, a confidence and the files it concerns. Press a finding to open the first file.
+
+- **Confidence** shows how sure the answer is. For a yes-or-no question, the workspace derives it from the probability that Jev returns. A finding with low confidence says **for your judgement**.
+- **Coverage** is the first line under **findings**. Read it first. It shows how many requests Jev answered, and how many documents were withheld, too large, excluded or failed. A short list of findings does not mean the repository is clean.
+- A finding is advice. It does not change a file. It is not an acceptance. You decide what to do.
+
+The workspace keeps the findings in `validation-findings.jsonl`. In a PMOS repository, this file is in the runs folder. In another repository, it is in the runtime folder of this machine. The file holds the answers. It does not hold document text.
+
+## Limits
+
+Jev's verdicts are advice until a person compares them with real decisions. The workspace does not yet measure how often Jev is right. Treat a high-confidence finding as a reason to look, not as proof.