create-pmos 0.516.0 → 0.517.0

package/workspace/guide/settings.md

@@ -1,61 +1,25 @@
 ---
 type: Guide
-title: "Settings in console3: one home for each setting"
-description: "How to open Settings in console3, what each section holds, what the scope tags and the environment notes mean, and where the settings are kept."
+title: "Settings: what each section holds"
+description: "How to open Settings from the menu, what each of its sections holds, how to update PMOS, and where the settings are kept."
 timestamp: 2026-11-03
 ---
 
-# Settings in console3: one home for each setting
+# Settings: what each section holds
 
-Settings is the page in console3 (`/`) where you change how PMOS works. Each setting has one home on this page. When another page shows a setting, it shows a link to this page and not a second control.
-
-## Open Settings
-
-Use one of these:
-
-1. Press the gear in the top bar, next to More.
-2. Press More, then **Settings**.
-3. Press ⌘K, type `settings`, and press Enter.
-4. Open `/?tab=settings`. Add `&section=recording` to open one section, for example.
-
-Settings is not a tab. While it is open, no tab is selected. Press a tab to go back to that tab.
-
-## The sections
+Press the round menu button at the bottom of any page, then the **Settings** icon. While a source is stale, Settings opens at **Connectors** with the stale source first. Settings has these sections:
 
 | Section | What it holds |
 |---|---|
-| About you | Your name, your role, what you do and your job description. First-run setup does not ask for them. |
-| Workspaces | Your workspaces: rename, remove, add one by its folder. Which workspace opens on start, and what the Briefing covers. The list shows each repository once. A git worktree of a repository, such as an initiative branch folder, is not listed. Remove forgets the repository and its worktrees together. No folder is deleted. |
-| Boards and workflows | The workflow templates for new boards and the default template. The rules that move a card. To change the workflow of one board, open that board in Initiatives. |
-| Connectors | How your Claude session reaches Google Calendar, Jira, Wispr Flow and a sender. The import window, the refresh time, how private events show, and attendee names. The report finder is the last block. |
-| Recording | The live transcript: what to listen to, the Whisper model, the language, the echo removal, the final pass after Stop, the words to recognize, and how long kept audio stays. A card at the top says what recording uses now. |
-| Day and time | The time zone, the first day of the week, your working hours, the free time before a meeting with prep, the buffer between meetings, and the time-of-day tint and daylight strip. |
-| Sharing | How a report is shared: off, a link, or sent by the sender. The audiences of the workspace. Schedules are not here. Each report has its own schedule, in Reports, under Set up. |
-| Access and devices | Use from a phone or another computer: the host, the tunnel and the people who may open it. |
-| Claude sessions | What a new session starts with: the CLI, the model, the Claude profile and the launch flags for sessions you start, and the flags for automatic sessions. The session limits. Validate consent for this workspace. |
-| Privacy and data | A list of what leaves this computer and when. Whether a TypeSafe key is saved, the local model that answers when there is no key (Off, Winnow or Laya), and the data folder. |
-| Appearance | The theme (Same as system, Light or Dark) and the page that opens first. |
-| Claude | The Claude profile that new Claude sessions start with, the Anthropic API key for Claude's own runs on the API, and Sharpen prompts (see below). |
-| Claude's checks | When Claude grills an initiative by itself (Full, Only at stage exits, or Off) and the monthly credit for its checks ($5, $10, $20 or $50), with what this month used. See below. |
-| Updates | The version of the app and of each workspace's kit, the check for updates, and what changed in each week's kits (what's new). See below. |
-
-Type in **Search settings** to find a setting in any section. Press **Open section** to go to its section.
-
-## Read a row
-
-Each row has a label, a help line and a control.
-
-- **This computer** means the setting applies to every workspace on this computer.
-- **Workspace · name** means the setting applies only to the workspace in the **Workspace** list at the top of the page. Pick another workspace to see or change its value.
-- A dot after the scope tag means the value is not the default. **Reset** puts the default back. The section name in the list on the left shows how many of its settings you changed.
-- A yellow note with a name such as `PMOS_WHISPER_LANG=en` means a variable in the environment where PMOS starts sets this value. The variable wins over the page. Remove it from your shell profile, then restart PMOS.
-- A lock means the value is fixed or is set somewhere else. The row says where.
-
-A change is saved when you make it. A message at the bottom of the page says **Saved** and the setting's name. Press **Undo** in the message to put the old value back. If a value is refused, the row shows why.
-
-When a section has changed settings, **Reset section** at the top of the section puts all of them back to the default.
-
-Some rows show a feature that PMOS does not have yet, such as choosing calendars, mapping Jira projects, pairing a phone, the device list, and export or reset of every setting. The control on these rows is off, and the row says why.
+| General | The theme (Light, Dark or Auto), whether the Viewer opens as a column or a popup, the products Home, the Board and Intelligence read, when Your day ends, the Your impact switch, and that agents write to Jira only after you press Commit. When a new PMOS is ready, a card here says so. |
+| Claude | The Claude profile that new sessions start with, the Anthropic API key for Claude's own runs, and Sharpen prompts. |
+| Claude's checks | When Claude grills an initiative by itself and the monthly credit for its checks, with what this month used. |
+| Jev and Laya | The TypeSafe key for Jev, the local model Laya, and the switches for each repository: whether Jev may read it, sort documents, check claims and label notes. |
+| Adler | How much of Adler you see (Full, Face only or Off), motion, celebrations, Quiet after, and Dress for the day. |
+| Connectors | Every connector your Claude session has. A switch chooses only what PMOS reads on its own. PMOS reads and never posts. |
+| Workspaces | The repositories PMOS works in. Remove forgets the address only; the folder is not deleted. Add one by its folder path. |
+| Workflows | Opens its own page: the stages each kind of initiative goes through. See [Workflows](workflows.md). |
+| Updates | The version of the app and of each workspace's kit, the check for updates, and what changed. |
 
 ## Update PMOS and the kit
 
@@ -65,7 +29,7 @@ Open **Updates**. PMOS asks the npm registry for the latest version at once, and
 - When PMOS runs from a PMOS checkout, the row says to update it with `git pull`. There is no Update button.
 - **Update** on a workspace row updates the kit in that repository. It replaces the kit files in its `pmos/` folder (AGENTS.md, skills, scripts, templates, `okf/core`, the mod and KIT-VERSION). It does not change `state/`, `planning/` or `okf/product/`, and it does not commit. Review the change in the repository as a normal pull request.
 
-### What's new
+## What's new
 
 Under the update card, **Updates** shows what changed in the published kits. **This week** is open: it is the one you need. A week runs Monday to Sunday. The heading gives the dates and the number of changes. When there is nothing for this week yet, the newest week with changes is the open one.
 
@@ -77,7 +41,7 @@ Under the update card, **Updates** shows what changed in the published kits. **T
 - **Archive** holds every earlier week, last week included. Press **Archive** to list them, then press a week to read it.
 - A week shows **Ready to install** when one of its kits is newer than the version you run.
 - A change published before Claude wrote stories shows the pull request's title and its sentence instead.
-- **What's new** is not a section of its own any more. The button on the update card in **General** opens **Updates**.
+- The card in **General** that says a new PMOS is ready opens **Updates**.
 
 ## Claude: the profile and the API key
 
@@ -97,21 +61,4 @@ Claude grills an initiative by itself and files what it finds under the initiati
 
 ## Where the settings are kept
 
-The settings that had a home before this page keep it. For example, the recording engine is kept by the notes engine, Validate consent by the validate route, and the theme and the new-session defaults in this browser.
-
-The other settings are kept in the PMOS state directory, in `settings.json` for this computer and in `settings-ws/<workspace>.json` for each workspace. Only you can read these files. `GET /api/settings` returns every setting with its value and default. A change goes through `POST /api/settings` and must come from the workspace page.
-
-## Limits
-
-- A setting changes what the page stores. Some features read their setting in a later release. Until then, the feature uses its default.
-- Settings changes templates and defaults for boards. It does not change an existing board.
-- Nothing on this page sends a message or shares a dashboard by itself.
-
-## The report finder
-
-The report finder is the last block of **Connectors**. It looks for reports that you send already, and shows what it found on the Reports tab and on the Briefing.
-
-- **Look for reports you send.** Choose **Weekly** or **Off**. Weekly looks every Monday. Off stops it.
-- **Sources.** The finder reads Calendar, Slack and Drive. It reads the subjects and the recipient counts of mail you sent, only when you turn **Sent mail subjects** on. It never reads a message body. Sent mail subjects are off until you turn them on.
-
-See [Set up a report by asking](reports-set-up.md).
+Each setting is saved when you change it. The settings are kept in the PMOS state directory, in `settings.json` for this computer and in `settings-ws/<workspace>.json` for each workspace. Only you can read these files. `GET /api/settings` returns every setting with its value and default. A change goes through `POST /api/settings` and must come from the workspace page. A variable in the environment where PMOS starts, such as `PMOS_GRILL=off`, wins over the page, and the row says so.

package/workspace/guide/today.md

@@ -1,200 +1,24 @@
 ---
 type: Guide
-title: "Today: what needs you"
-description: "The Agenda month and the calendar it remembers, the meeting notes of a meeting, the two-column day (your jobs and the agent's jobs), the eight kinds of card on Today, the one button on each card, the count, the empty state, and the pmos today command."
-timestamp: 2026-11-02
+title: "What waits for you, and pmos today"
+description: "Where the workspace shows what waits for you (Your day in Home) and how pmos today prints the same kind of list from a terminal."
+timestamp: 2026-11-03
 ---
 
-# Today: what needs you
+# What waits for you, and pmos today
 
-## The day
+In the workspace, what waits for you is in **Your day** on Home. Press **Good morning** at the top of Home's list to open it in the Viewer.
 
-Above the cards, Today shows the day in two columns.
+- **Your move** lists the items that wait on you, with their count.
+- **New for you** shows what is new since you last looked: tasks given to you, and work that finished while you were away.
+- **Drafted for you** lists what Claude drafted today.
+- **This week** opens the weekly review.
 
-- **You.** The jobs only you can do, and the meetings of the day, each with its purpose, what to prepare, and the steps before, during and after it.
-- **Agents.** The jobs an agent does for you. Each job shows where it stands: waiting, working, review, sending, sent, done or failed.
-
-Press **Prepare my day** to start the day. It runs from the brief to the delivery of each agent job, and you do not press anything else until a draft is ready for you. The page [Guide: Today and the proactive engine](proactive-engine.md) describes each step.
-
-The bar at the top of the day is one line. It shows the greeting, the date and **Prepare my day** (**Prepare again** when the day is prepared). While **Prepare my day** runs, it also shows the four steps (Read, Sort, Agents work, You approve) as a small progress bar; press a step to see its detail. The **⋯** menu holds the rest: when the day was last prepared, how many agent jobs are in each state, the next daytime check, **Check now**, **Settings** (the sources) and, when Today shows one repository, **Show items with no repository**.
-
-If the morning-brief session stops before it submits a brief, the Read step says so and gives the reason. **Prepare my day** is then ready again, so press it to try once more. If the session says that its folder is not there, open the repository again from its current folder first.
-
-Each agent job runs in its own session, so you can open any job and follow or steer it. The workspace types the job's prompt into the session when the agent is ready to read, and presses Enter for you. When you approve or revise a job and its session is still open, the workspace uses that same session again. Prepare again works the same way: when the morning-brief session is still open and has finished its read, or has printed nothing for two minutes, the workspace types the read into that session and runs it again.
-
-An agent job can stop with its session still open, for example when the agent asks a question or stops without a draft. When a job's session prints nothing for five minutes and has no draft, the job fails with that reason, so the other jobs can start. Press **Open session** to see what the agent waits on, or **Run it again** to start the job in a new session. **Prepare again** also starts each of these jobs again in a new session. If the first session still delivers its draft, the job takes it.
-
-### What Prepare again, Check now and deleting a session change
-
-- **Prepare again** reads every source again. For each source it reads, the new read replaces that source's items, digests and, for the calendar, the events. The notes of a meeting stay with the meeting. A source it cannot read this time keeps what it gave before. Your goals and every job stay: a job that has a draft, an approval or a result keeps it, and a new item becomes a new job.
-- **Check now** adds what is new since the last read. It also looks once at each open item: it takes off an item that is done or no longer true, and updates an item whose facts changed, for example a new ask or a new due date. It replaces nothing else, and every job stays.
-- **Deleting a session** does not delete its job. A job that was working fails with "the session ended without a draft", so press **Run it again** to start it in a new session. A job that has a draft keeps it. A job that was sending after your approval fails too, so check the place it was for before you run it again: the workspace cannot tell whether it sent.
-
-Each job session is named "Job ·" and the first words of the job, so the session list stays short.
-
-The left column shows one section at a time. A row of tabs at the top chooses it: **Agenda**, **Goals**, **Jobs** and **Mentions**. Agenda is the first one shown. The column remembers your last choice in this browser. When you select a job, a goal or a mention, the column goes to its tab. The Agenda tab holds the day's meetings and, on a press, the month. A finished job shows its draft summary, or the reason it failed, inside the job. The **Goals** tab holds your goals, and each goal lists its jobs (see [Goals own jobs](#goals-own-jobs)). The day is open when you go to Agenda, also before you press **Prepare my day**. The other things that wait for you, such as outcome checks, report drafts and sessions, are jobs too. Each one is a row of **Needs you** in the jobs. Press it to see its card, with its own buttons (for example **Draft now**), in the detail column. When the day is folded, they show as cards under it.
-
-### The Agenda month
-
-The menu calls this page **Agenda**. It opens on the meetings of the day, with the arrows to go to another day. The month is hidden. Press **Calendar** to show it across the full width, and **Hide calendar** to put it away. Picking a day closes the month and shows that day's meetings. The page does not remember the day you picked or whether the month was open. When a day shows no meetings yet, press **Prepare my day** (or **Prepare again**): the morning-brief session reads your calendar and fills the month. Each week starts with its number, for example W41.
-
-- Press a week number to see the agenda of that week, day by day.
-- Press a meeting to see its memory in the right column. The month marks every day of the same meeting, so you see when it happens again.
-
-Meetings that repeat and have nothing for you fold into one line, for example "+4 repeating, nothing for you". Press it to see them.
-
-A day in the month holds three things: the day number, a tint that is darker when the day has more meetings, and a ★ when the day has a key meeting. A meeting matters when you present or decide, when people from outside the company or leadership join, or when 8 people or more join. Meeting titles, the prep badge and the notes count are in the day's agenda, not in the month.
-
-A meeting's detail shows one focus. Under the title is one line: the time, how many people join, and a star when the meeting is key. Under it are the goal of the meeting and, for a meeting with prep, one line of progress (the steps done, a bar, the free minutes before the meeting). Only the first open step is expanded, with what its source says, its link and, for a note step, a box for your note. The one primary button follows it: **I have read it**, **Mark done** or **Done**, then **Mark ready** when every step is done, then **Take notes** once the meeting has started. Press the arrow at the end of another step to open it. **More** holds the rare presses: **Mark ready** while steps are left, **Remind me**, **Skip prep**, the key mark and **Add as a goal for today**. **Details** holds the people, the kind of meeting and how often it met, the initiative, During and After, the mail and the links. When the meeting has a goal, the detail also shows what the goal is done when and the goal's jobs, with the buttons to add a job and to link one.
-
-A meeting's detail ends with **Meeting notes**. Press **Take notes** to start a note linked to the meeting, and to its initiative when the brief names one. PMOS starts to listen at once and shows the note in Notes. When the meeting has a note, the detail shows its summary and **Open notes**, which shows it in Notes, and the meeting's row shows **notes**. See [Notes](notes.md).
-
-The memory of a meeting says what kind of meeting it is (one-to-one, onboarding or group), how many times it was held, how many are to come, and why it matters.
-
-To mark a meeting yourself, open it. Press **Mark as key** to make this time a key meeting, or **Key every time** for every time it happens. On a meeting that is key already, press **Not key** or **Never key**. Your mark is used before what the calendar says. Press **Remove my mark** to go back to what the calendar says. The marks are kept in `calendar-marks.json` in the state folder. **Before this meeting** lists the prep. **Last time** is folded: open it to read the notes and what stayed open.
-
-The month comes from the calendar memory. The morning-brief session reads your calendar 90 days back and 31 days ahead the first time, and from today to 31 days ahead after that, and sends it with the brief. The workspace keeps 100 days back and 45 days ahead, in `calendar-memory.json` in the state folder. Nothing on the Agenda writes to your calendar. To see what the memory holds, run `pmos proactive calendar`.
-
-### One day for every repository
-
-The day is yours, not a repository's. Every repository shows the same calendar, goals, jobs and mentions. To narrow the day, use the **Show** switch at the top of Today:
-
-- **All repositories** shows the whole day. A job, mention, goal or watched place that belongs to a repository carries its name.
-- **Repository** shows the items of the repository you opened Today from, and the items that belong to no repository. The calendar always shows.
-
-To tie an item to a repository:
-
-1. For a goal, open it and pick a **Repository**. A goal you add while Today shows one repository belongs to that repository.
-2. For a Slack channel, Jira project or Confluence space, open **Sources**, open the service, and pick a repository next to the place.
-
-A job takes the repository of its goal. A job with no goal takes the repository of the initiative it names, then of the place it came from. A goal tied to an initiative takes that initiative's repository when you pick none. A job with none of these belongs to no repository.
-
-When **Repository** hides a goal of another repository, the goals say how many it hides. Press **Show all repositories** to see them.
-
-A job's agent session runs in the folder of the job's repository, so it can read that repository's files. A job with no repository runs in the repository where you pressed **Prepare my day**.
-
-Your goals stay until you mark them done or drop them. A new day starts with the goals that were still open on the last day you had goals.
-
-Each job has one of three kinds.
-
-| Kind | Who does it | What you do |
-|---|---|---|
-| you | Only you. | Do it, then mark it. See [Jobs you do and meetings you prepare for](#jobs-you-do-and-meetings-you-prepare-for). |
-| approve | An agent prepares one draft. | Read the draft. Press **Approve** to let the one outward step happen, or **Revise** with a note. |
-| auto | An agent does it, and nothing leaves the computer. | Read the result. Press **Revise** if it is wrong. |
-
-A draft that waits for you shows its summary, its text and the link of the place it is for. **Approve** sends only that text, to that place. **Revise** takes a note of at most 500 characters and asks for a new draft. You can revise a job 3 times. A fourth revise is refused, so do the job yourself or drop it. A failed job shows its reason and **Retry**.
-
-### Goals own jobs
-
-A goal is something you want to finish. Add one in the **Goals** tab: type it and press Enter. **Add context** is optional and takes three fields: what is true when the goal is done (**done when**), what the goal serves (a key result or a health budget), and when it is due. A goal with no **done when** shows **Add done when**.
-
-Each goal lists its jobs. A job belongs to one goal at most, and a job can have no goal. A job comes from a step of the goal, from preparing, from a mention, or from you. Its detail names where it came from and has a **Goal** list: pick a goal to link the job, or **No goal** to unlink it. The **Goals** tab ends with **Jobs without a goal**, each with the same list. To add a job to a goal, type it in the goal and press **Add job**. A job you add this way is yours: you check it and remove it, and no agent works on it.
-
-The goal row shows how many jobs are done, for example "2 of 4 jobs done". That is information only. A goal is never closed for you. Press **Done** when the goal is finished, or **Drop** to give it up. **Add as a goal** in a meeting's **More** menu makes a goal from the meeting.
-
-### Who acts on a job
-
-Each job says who acts: **Waiting on you**, **Agent is working** or **Agent finished**. A filled square marks the agent and an open square marks you. Every button on a job has a small **YOU** or **AGENT** tag. A button with **AGENT** starts the agent in a session, for example **Have the agent draft it**, **Revise** and **Retry**. A button with **YOU** is a press that you do yourself, for example **Approve** and **Mark done**. When a job has a session, whoever acted last, **Open session** opens it. A finished job shows its result inside the job.
-
-### Mentions
-
-The **Mentions** tab lists what people asked of you. A mention from Slack, Confluence or Figma shows as a card in the layout of that service: a Slack message with the sender and the text; a Confluence comment with the page and, when the brief has one, the passage it is about; a Figma comment with the file it is on. The card shows only what the brief has. It never invents a reaction, a reply count or a picture. Press a mention to open its job. **Open in …** opens the conversation in the service. Nothing in PMOS posts to Slack, Confluence or Figma, resolves a comment or reacts. Mentions from other places show as a plain row.
-
-### Jobs you do and meetings you prepare for
-
-A job that only you can do starts with a verb, such as **Reply**, **Review** or **Sign off**, and one sentence that says what to do. Under the sentence are who asked, why it is for today, and the steps. Check each step when you finish it. The first button opens the place where you do the job, for example **Reply in Slack**. **Have the agent draft it** gives the job to an agent. The draft then waits for your approval, as for any approve job.
-
-A job card holds what you need to do the job without opening another file. **The conversation** shows the last messages, up to 4. A step that reads a source shows what the source says, in a few lines, under the step. **What the sources say** shows the other sources. **Open the source** opens the source itself when you want more.
-
-When the job is a reply or a review, you can finish it in the card. Write your answer in the box, or press a suggestion to start from it. For a review, choose **Approve** or **Ask for changes**. Then press **Send to …**. An agent posts exactly your text, as you, to the place the button names. Nothing else is sent, and nothing is sent before you press. The job then shows **Sending**, and **Sent** when it is posted. If the send fails, the job shows the reason and **Retry**, which sends the same text again.
-
-A meeting that needs prep is a row of **Needs you**, with the verb **Prepare**. Its detail shows the prep, how many steps are ready, the free time before the meeting, and the steps before it. A step that reads a source shows what the source says under it. A step that asks for your view, such as **Write your recommendation**, has a box for your note. The note is saved when you leave the box. It stays with the meeting on this computer and is not sent. A step that the brief already marked done stays checked.
-
-When a meeting ends, its detail stays as it was. A line at the top says **ended** and the time it ended. The prep and the steps stay, in a quieter box, so you can still read what you prepared. The meeting leaves **Needs you**, and its notes show under it.
-
-When you finish or put off a job or a meeting, mark it:
-
-| Press | What it does |
-|---|---|
-| **Mark done** (a meeting: **Mark ready**) | Moves it to **Done today**. |
-| **Snooze** (a meeting: **Remind me**) | Moves it to **Snoozed** until a time later today. At that time it comes back to **Needs you**. |
-| **Waiting on…** | Puts a job on hold. Write who or what you wait on, and when to ask again today. It shows in **Waiting on others** until that time. |
-| **Not mine** (a meeting: **Skip prep**) | Takes it off **Needs you**, with a reason. |
-
-Each press shows **Undo**. **Bring it back now** or **Reopen** puts a marked item back in **Needs you**. A mark lasts for the day. A mark does not send anything and does not change the source. Only **Send to …** sends, and only your text. **Snoozed**, **Waiting on others** and **Done today** are folded. Press a group to open it.
-
-The page also shows which sources were read and how many items each gave, and the next daytime check. **Check now** starts a check at once.
-
-## What waits for you
-
-Today lists only what waits for you. Each card is one thing that only you can close. When nothing waits, Today says so and names the next scheduled draft, for example "Nothing needs you. Next: biweekly draft Fri 16 Oct."
-
-A session that you did not start yourself, for example a schedule, a day task, or a note's summary, never makes a card, even when its agent has stopped and is "waiting". Only a session you started is waiting for you.
-
-Press **Today** in the top bar, or press `g` and then `t`, to open it. The number on the Today button is the number of cards in the scope you chose: the repository, or All repositories. It is the same number that Today shows at the top of the list.
-
-## A card
-
-Every card has four parts.
-
-- **Cause.** One sentence: why the card is here.
-- **Evidence.** The record that shows it, for example a run id, a file or a date.
-- **One button.** The act that closes the card. The verb comes first, for example **Review**, **Keep** or **Open**.
-- **The three dots.** A menu with **Open the initiative**, **Copy the command** and **Why is this here?**. The menu has the same items on every card. A touch screen and a keyboard reach them as a mouse does.
-
-When you finish the act, the card leaves and the count goes down by one. You do not dismiss a card. A card leaves only when its cause is gone.
-
-## The eight kinds
-
-Today puts the cards in this order. Within a kind, the cards keep a fixed order, so a card does not move while you read.
-
-| Kind | What it is | The button |
-|---|---|---|
-| 1. A gate is owed | A run waits for your acceptance, an outcome check is due, or a report is ready to issue. | Review, Check or Issue |
-| 2. A session is waiting | A session in a terminal asked you a question and waits for the answer. | Open |
-| 3. A step you returned | You returned an acceptance and the initiative has not been accepted since. | Open |
-| 4. Work to check | An item is in Review, or an item is Done with no evidence. | Open |
-| 5. Keep an agent breakdown | Retired by D98: an agent's items are live at once, so this card no longer shows. | — |
-| 6. A triaged capture | A capture was triaged and waits for you to add it or dismiss it. | Open |
-| 7. Cycle review | The cycle review is due: an agent proposal to keep or drop, or a check-by date that passed. | Open |
-| 8. Needs repair | A schedule left no output, a line from the PM has no attestation, or a record has no anchor. Today shows the card until it is fixed. | Open |
-
-A stalled initiative is not a card. It shows as a health reason on the initiative, in the list and in its detail.
-
-A source that cannot be read is not a card either. It shows in the notice at the top of Today, so a source that fails never looks like an empty list.
-
-## Close a gate on a run
-
-A card of kind 1 for a run has the button **Review**. The steps are:
-
-1. Press **Review** on the card. The card opens in place and shows what the evaluator said.
-2. Press **Right** or **Wrong** to say whether the evaluator was right.
-3. Optional: press **Add a note** and write one line on why.
-4. Press **Accept** to accept the run, or **Return** to send it back.
-
-That is four taps, or three taps without the note. The workspace records your act in the acceptance ledger. The note and your label are part of that record. If the workspace cannot record the act, the card stays and a message says that nothing was recorded.
-
-## The scope
-
-The switch at the top of Today has two choices.
-
-- **Repository.** The cards of the repository you chose. The number on the Today button counts these cards.
-- **All repositories.** The cards of every repository. The count at the top says how many repositories it counts across.
-
-The number on the Today button and the number at the top of the list are the same in both choices.
-
-## Short lists
-
-Today shows the first three cards. Press **Show more** to see the rest, and **Show fewer** to fold them again. The count always includes every card.
-
-## A source that cannot be read
-
-When Today cannot read a source, for example a broken needs file, it says so in a notice at the top of the list. It does not show an empty list and it does not say that nothing needs you. The notice names the source and the reason. Today still shows the cards of the sources it could read.
+A session that waits on you has a blue dot in Home's list, under its initiative. [Home](home.md) explains each part. When a conversation in Mentions waits on your answer, Your day names the oldest one.
 
 ## From a terminal
 
-`pmos today` prints the same list as Today, in the same order, with the kind first.
+`pmos today` prints what waits for you, ranked, with the kind first.
 
 ```
 pmos today                  # the repository you are in
@@ -205,4 +29,4 @@ pmos today --root <dir>     # read a repository folder without a server
 
 With the workspace server running, the command asks the server, so it also lists the sessions that wait for you. Without the server it reads the repository files and prints a line that says it did not read the sessions. The command prints "Nothing needs you" and the next draft when the list is empty. It exits with 0 when it read the list, 1 when it could not read it, and 2 when you gave it an option it does not have.
 
-The page and the command read the route `GET /api/today?ws=<id>`. The route changes nothing.
+The command reads the route `GET /api/today?ws=<id>`. The route changes nothing.

package/workspace/lib/report-checks.js

@@ -33,6 +33,9 @@ function hasFigure(line) {
 const hasSource = (line) => /\b[A-Z][A-Z0-9]+-\d+\b/.test(line) || /\]\(https?:\/\/[^)]+\)/.test(line) || new RegExp(`[\\[(](?:${LABELS.join('|')})[\\])]`, 'i').test(line) || /\bsource:/i.test(line);
 
 function numbersSourced(text) {
+  // a document the report engine rendered (lib/report-engine.js): its figures are readings, each bound to its source and date by construction,
+  // and the engine's own checks refuse a figure that is not one. Its lines are not the PM's prose, so they are not flagged (design R item 5).
+  if (/^---\r?\n(?:[\s\S]*?\n)?engine: e\d+\r?\n(?:[\s\S]*?\n)?---/.test(String(text || ''))) return { id: 'numbers-sourced', pass: true, reason: 'every figure is a reading with its source and date (the report engine bound them)' };
   const claims = body(text).split('\n').map(lineOf).filter((l) => l && !/^#/.test(l) && !/^\|?[\s:|-]+\|?$/.test(l) && !/^```/.test(l) && hasFigure(l));
   if (!claims.length) return { id: 'numbers-sourced', pass: true, reason: 'no line carries a figure' };
   const bare = claims.filter((l) => !hasSource(l));

package/workspace/lib/report-cli.js

@@ -37,8 +37,23 @@ const actorLib = require('./actor.js');
 const RS = require('./report-setups.js');
 const { parseArgs } = require('./schedule-cli');
 
-const COMMANDS = { report: ['draft', 'issue', 'list', 'propose', 'definitions', 'setups', 'finder'] };
+const COMMANDS = { report: ['make', 'read', 'find', 'write', 'check', 'rule', 'draft', 'issue', 'list', 'propose', 'definitions', 'setups', 'finder'] };
 const USAGE = [
+  'usage: pmos report make|read|find|write|check|rule — the report engine: brief, read, find, answer, render (any report, any shape)',
+  '  pmos report make <id> [--ask "<the question>"] [--readers "<who>"] [--source <kind:ref>,…] [--slot <date>]',
+  '      Steps 1 to 3: derive the brief (readers, question, window, sources; no section list), read every source PMOS reaches,',
+  '      and find what changed. An ad hoc report needs --ask. Sources: pmos · pack:<state file of readings> · connector:<name> · document:<path>.',
+  '  pmos report read <id> [--slot <date>] --from <file|->',
+  '      File the readings you read through a connector or a document: {"readings":[{id,value,unit,at,source,how,label,n,of,target}],',
+  '      "gaps":[{source,reason}]}. Every reading has a source of the brief, a date and how it was read.',
+  '  pmos report find <id> [--slot <date>] --from <file|->',
+  '      File the findings that answer the question: {"findings":[{text,readings:[ids],kind,question}]}. Each cites readings.',
+  '  pmos report write <id> [--slot <date>] --from <file|->',
+  '      Step 4 to 6: check the report.json you wrote (the outline is yours), render the document and the deck, write the checks.',
+  '      Refused when there is no answer with a reading, or when a figure is not a reading {{r:<id>}}.',
+  '  pmos report check <id> [--slot <date>]       the checks of the last write: substance first, then form',
+  '  pmos report rule <id> list | add <voice|wording|off|keep> "<text or part>" | remove <n>',
+  '      What the readers taught this report: a voice or wording rule, or a part beyond the ask turned off or kept.',
   'usage: pmos report draft|issue|list — cadence reports (for example the biweekly)',
   '  pmos report draft <cadence> [<slot>] [--now <time>] [--redraft]',
   '      Write the draft for a slot (default: today) with every number. Refuses a slot that has a draft;',
@@ -59,8 +74,9 @@ const USAGE = [
   '  every command: [--json] [--root <dir>]. The cadence is the report skill id without "report-", for example biweekly.',
 ];
 const BOOL = new Set(['json', 'redraft', 'help']);
-const VALUE = new Set(['now', 'root']);
-const ALLOWED = { draft: ['json', 'redraft', 'now', 'root'], issue: ['root'], list: ['json', 'root'], propose: ['json', 'root'], definitions: ['json', 'root'], setups: ['json', 'root'], finder: ['json', 'root'] };
+const VALUE = new Set(['now', 'root', 'ask', 'readers', 'source', 'slot', 'from']);
+const ALLOWED = { make: ['json', 'now', 'root', 'ask', 'readers', 'source', 'slot'], read: ['json', 'now', 'root', 'slot', 'from', 'source'], find: ['json', 'now', 'root', 'slot', 'from'],
+  write: ['json', 'now', 'root', 'slot', 'from'], check: ['json', 'root', 'slot'], rule: ['json', 'root'], draft: ['json', 'redraft', 'now', 'root'], issue: ['root'], list: ['json', 'root'], propose: ['json', 'root'], definitions: ['json', 'root'], setups: ['json', 'root'], finder: ['json', 'root'] };
 const CADENCE_RE = /^[a-z][a-z0-9-]{0,39}$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 
@@ -129,6 +145,7 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
     return 0;
   }
 
+  if (['make', 'read', 'find', 'write', 'check', 'rule'].includes(verb)) return engineVerb(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now });
   if (verb === 'definitions' || verb === 'setups' || verb === 'propose' || verb === 'finder') return reportWorkspace(verb, { pos, flags, root, json, say, fail, cwd, isTTY, env, stdin, now });
 
   const [cadence, slot] = pos;
@@ -170,6 +187,98 @@ async function run(argv, { say = (s) => console.log(s), cwd = process.cwd(), isT
   return 0;
 }
 
+/** The report engine's verbs (lib/report-engine.js). An agent session and the PM may run them; issuing stays the PM's (`pmos report issue`). */
+function engineVerb(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now }) {
+  const RE = require('./report-engine.js');
+  const id = pos[0];
+  if (!id || !RE.ID_RE.test(id)) { say(`usage: pmos report ${verb} <id> …   (the id is lower case letters, digits and dashes, for example scarlet-assessment)`); return 2; }
+  let clock = now == null ? Date.now() : now;
+  if (flags.now !== undefined) { clock = Date.parse(flags.now); if (!Number.isFinite(clock)) return fail('--now must be a time, for example 2026-10-16T09:00:00Z', 2); }
+  const slot = flags.slot !== undefined ? flags.slot : undefined;
+  if (slot !== undefined && !isDate(slot)) return fail('--slot must be a date, YYYY-MM-DD', 2);
+  const day = slot || new Date(clock).toISOString().slice(0, 10);
+  const who = actorLib.fromCli({ ...(isTTY === undefined ? {} : { isTTY }), ...(env === undefined ? {} : { env }) });
+  const readFrom = () => {
+    const src = flags.from;
+    if (!src) return { error: `--from <file|-> is required: the JSON to file` };
+    let text;
+    try { text = src === '-' ? (typeof stdin === 'string' ? stdin : fs.readFileSync(0, 'utf8')) : fs.readFileSync(path.resolve(src), 'utf8'); } catch { return { error: `could not read ${src === '-' ? 'standard input' : src}` }; }
+    try { const o = JSON.parse(text); return o && typeof o === 'object' ? { body: o } : { error: 'the JSON is an object' }; } catch { return { error: 'that is not JSON' }; }
+  };
+  const sources = flags.source ? String(flags.source).split(',').map((x) => x.trim()).filter(Boolean) : [];
+  const bad = sources.find((x) => !RE.parseSource(x));
+  if (bad) return fail(`--source ${bad}: write pmos, pack:<file>, connector:<name> or document:<path>`, 2);
+  const summary = (m) => {
+    const f = m.findings; const g = m.readings.gaps;
+    if (json) { say(JSON.stringify({ ok: true, brief: m.brief, readings: m.readings.readings.length, gaps: g, findings: f.findings, none: f.none, paths: m.paths })); return 0; }
+    say(`✓ Brief ${m.paths.brief}: for ${m.brief.readers}. Question: ${m.brief.question}`);
+    say(`  ${m.readings.readings.length} reading(s); ${g.length ? `${g.length} gap(s): ${g.map((x) => `${x.source} (${x.reason})`).join('; ')}` : 'no gap'}.`);
+    say(f.none ? '  No finding, so no draft: nothing to report yet. Read the sources the gaps name and file the readings: pmos report read ' + id + ' --from <file>'
+      : `  ${f.findings.length} finding(s): ${f.findings.slice(0, 3).map((x) => x.text).join(' · ')}`);
+    if (!f.none) say(`  Next: write ${m.paths.report} (the outline is yours) and run: pmos report write ${id}${slot ? ' --slot ' + slot : ''} --from <file>`);
+    return 0;
+  };
+  if (verb === 'make') {
+    const m = RE.make(root, id, { slot: day, ask: flags.ask, readers: flags.readers, sources, now: clock });
+    if (!m.ok) return fail(m.error);
+    return summary(m);
+  }
+  if (verb === 'read' || verb === 'find') {
+    const r = readFrom(); if (r.error) return fail(r.error, 2);
+    const add = verb === 'read' ? { add: r.body.readings || [], gaps: r.body.gaps || [] } : { addFindings: r.body.findings || [] };
+    const m = RE.make(root, id, { slot: day, sources, ...add, now: clock });
+    if (!m.ok) return fail(m.error);
+    return summary(m);
+  }
+  if (verb === 'write') {
+    const r = readFrom(); if (r.error) return fail(r.error, 2);
+    const w = RE.write(root, id, day, r.body, { actor: who, now: clock });
+    if (!w.ok) {
+      if (json) { say(JSON.stringify({ ok: false, error: w.error, checks: w.checks || null, none: !!w.none })); return 1; }
+      say(`✗ ${w.error}`);
+      return 1;
+    }
+    if (json) { say(JSON.stringify({ ok: true, path: w.path, report: w.report, checks: w.checks })); return 0; }
+    say(`✓ Wrote ${w.path} from ${w.report}. The deck is drawn from the same model.`);
+    for (const c of w.checks) say(`  ${c.pass ? '✓' : '✗'} ${c.id}: ${c.reason}`);
+    return 0;
+  }
+  if (verb === 'check') {
+    let P; try { P = RE.paths(root, id, day); } catch (e) { return fail(e.message, 2); }
+    let c; try { c = JSON.parse(fs.readFileSync(P.checks.abs, 'utf8')); } catch { return fail(`${id} ${day} has no checks yet: pmos report write ${id} --from <file>`); }
+    if (json) { say(JSON.stringify({ ok: true, ...c })); return 0; }
+    for (const x of c.checks) say(`${x.pass ? '✓' : '✗'} ${x.id}: ${x.reason}`);
+    return 0;
+  }
+  // rule
+  const act = pos[1] || 'list';
+  if (act === 'list') {
+    const rules = RE.rulesOf(root, id);
+    if (json) { say(JSON.stringify({ ok: true, rules })); return 0; }
+    if (!rules.length) say(`${id} has no rule yet; the default voice applies.`);
+    for (const x of rules) say(`${x.n}  ${x.kind}  ${x.text || x.part}${x.from ? `  (from ${x.from})` : ''}`);
+    return 0;
+  }
+  if (!actorLib.isPm(who) && !actorLib.isAgent(who)) return fail('only the PM or an agent session can change a report\'s rules');
+  if (act === 'add') {
+    const kind = pos[2]; const text = pos.slice(3).join(' ');
+    const r = RE.addRule(root, id, { kind, text: kind === 'off' || kind === 'keep' ? null : text, part: kind === 'off' || kind === 'keep' ? text : null, from: actorLib.isPm(who) ? 'the PM' : 'the writer', by: who.by, now: clock });
+    if (!r.ok) return fail(r.error);
+    if (json) { say(JSON.stringify({ ok: true, rule: r.rule })); return 0; }
+    say(`✓ Rule ${r.rule.n} kept for ${id}: ${r.rule.text || `${r.rule.kind} ${r.rule.part}`}`);
+    return 0;
+  }
+  if (act === 'remove') {
+    const r = RE.removeRule(root, id, Number(pos[2]), { by: who.by, now: clock });
+    if (!r.ok) return fail(r.error);
+    if (json) { say(JSON.stringify({ ok: true })); return 0; }
+    say(`✓ Rule ${pos[2]} removed.`);
+    return 0;
+  }
+  say('usage: pmos report rule <id> list | add <kind> "<text>" | remove <n>');
+  return 2;
+}
+
 /** The report workspace's verbs. `propose` is the one an agent run may call; `finder` is the PM's. */
 function reportWorkspace(verb, { pos, flags, root, json, say, fail, isTTY, env, stdin, now }) {
   const E = env === undefined ? process.env : env;