manual: the pages #1545 flagged now say what dev does

docs/changes/unreleased/1639-manual-truth.md

@@ -0,0 +1,20 @@
+---
+kind: fixed
+title: the manual's standing, pool, task-card, team-start and first-run pages say what the code does
+pr: 1639
+surface: [chat, docs]
+invalidates:
+  - "The manual said a standing card's `2` changes when it wakes and `esc` says no. The card has no `2`: `1` sets it up, `3` (once) is offered on checks and watches only, `0` declines, `esc` leaves it for later, and `o Change…` (`o Change where…` on a rule) corrects it."
+  - "The manual said codeaf picks its crew against the public Model Pool and that the crew reads `own.json`. Crew routing uses its own prior and this install's outcomes and reads only the model-name aliases in the index copy built into the binary; only `codeaf pool` reads `own.json`."
+  - "The manual said `codeaf pool verify` prints a metric count (`3 metrics`). It prints the metric names: `signature good: version <n>, generated <date>, metrics <names>`."
+  - "The manual drew the task proposal's clock as `start it in 9s` on its answers row with the foot `enter take it · esc later · c change`. The clock is on the top edge beside `codeaf asks`, defaults to 15s, and the foot is `esc later · o other · ? clarify`; `c` is not a key on that card."
+  - "The manual said every task is bounded at 3 levels and 20 pieces per parent. Those bounds belong to the node belt (`CODEAF_TASK_BELT=node`); the default bash belt splits with `plandb split` under 256 tasks per batch, 1024 per run and four wakes per composite."
+  - "The manual said a manager's `team_start` always asks first on a card. It follows the conversation's approval posture: the default `◇ YOLO` starts the member with no card, and only `◇ asks` raises one."
+  - "The manual said the first run on an empty profile always opens two setup screens under a `setup · 2 of 2` header. With a provider key already in the profile or the environment, plain codeaf opens on home with no setup, and the header reads `setting up · 1 of 2` under the wordmark."
+  - "The manual said a program's `[<name>]` badge is on the landed card. Only the proposal card and the task's rows wear it; the landed card's head does not."
+---
+
+Three of the issue's rows are code defects rather than page errors and are left for their own
+issues: plain codeaf's engine road never draws `· N standing orders here — /standing`, the
+`remember` and `stand` tools both claim a stated preference, and the standing card never shows
+the grant.

internal/manual/chat/commands.md

@@ -159,32 +159,58 @@ Canonical word, the other words it answers to, its argument form, and what it do
 | `/settings` | `/set`, `/config` | — | opens the fullscreen settings panel (also ctrl+,) |
 | `/connect` | `/connections` | — | opens the connection panel; its `models` group holds model services, followed by connected accounts |
 | `/new` | `/clear`, `/clean`, `/reset` | — | closes this session and starts a fresh one |
+| `/drafts` | — | — | lists cleared drafts, newest first; enter restores one to the box and `d` lets one go; an empty ring says `no cleared draft is waiting` |
 | `/resume` | `/sessions` | — | opens the earlier-conversations picker |
 | `/compact` | — | — | summarizes the conversation now |
+
+## Home, project and file context commands — what does /workspace path do
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/home` | — | — | every project and conversation on this machine, fullscreen |
 | `/folder` | `/place`, `/dir` | — | locally opens the add context sheet for THIS conversation; on home it opens a conversation first; over `--host` says the folder chooser is unavailable |
 | `/folder` | `/place`, `/dir` | `<path>` | locally opens it with that in the box; over `--host` gives the same refusal |
+| `/workspace` | — | — | opens a local folder picker to anchor a conversation with no workspace; says `this conversation already has a workspace` once anchored, and the picker is unavailable over `--host` |
+| `/workspace` | — | `<path>` | anchors an unanchored conversation to that project; refuses a path it cannot use, or a conversation that already has a workspace |
 | `/project` | — | — | on home: the browser, opened where the next conversation would open; in a conversation it says it is home's |
 | `/project` | — | `<path>` | on home: sets the folder the next conversation opens in, with no browser |
 | `/attach` | `/upload` | — | opens the add context sheet for files, including over `--host`; enter on this row of the `/` list opens it at once |
 | `/attach` | `/upload` | `<path>` | a file goes on the tray; locally a folder is referred, while over `--host` it is refused |
 | `/land` | — | — | says what has been changed for a folder you chose and is waiting to go into it |
 | `/land` | — | `now` | …puts it in: a branch merged for a repository, files copied back for a plain folder |
 | `/land` | — | `<folder>` | …when more than one folder is waiting; `/land <folder> now` puts that one in |
+
+## Rewind, approvals and standing commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/rewind` | `/undo`, `/back` | — | opens the rewind timeline — the whole conversation as a list (esc esc is the quick inline version) |
 | `/permissions` | `/perms` | — | lists what runs without asking; `d` drops a line |
+| `/autonomy` | — | — | prints this project's rules for questions while you are away; refuses when the conversation has no project to keep them in |
+| `/autonomy` | — | `<kind> <ask\|recommend [duration]\|decide>` | changes one project question rule; refuses an unknown kind or rule, a bad duration, and changes to confirmation or clarification that their limits forbid |
 | `/standing` | `/orders` | `<words>` | makes those words a standing order — a card to answer, never work done once |
 | `/standing` | `/orders` | — | what stands over this conversation; `p` pauses, `s` stops, `n` excepts this place |
+
+## Programs, skills and memory commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/harness` | `/harnesses` | — | lists the saved shapes of work and what they did |
 | `/subharness` | `/sub` | — | lists the programs you can run; type to filter, enter opens that one's card |
 | `/subharness` | `/sub` | `<name>` | opens that subharness's intake card straight away |
 | `/<program>` | — | `<brief>` | one row per program this build carries: starts a task that program does on its own |
+| `/senior-dev` | — | `<brief>` | when this build or far engine carries senior-dev, its named row hands the whole task to that program; with no brief, it shows the required `<brief>` usage |
 | `/skill` | `/skills` | — | opens the skill shelf under the message box; enter toggles a skill, and its chip stays attached across messages |
 | `/memory` | — | — | opens the memory panel |
 | `/memory` | `/memories` | `<query>` | prints matching memories into the conversation |
 | `/memories` | — | — | prints every memory into the conversation |
 | `/remember` | — | `<text>` | keeps one thing across conversations |
 | `/forget` | — | `<query>` | forgets the best matching memory |
+
+## Crew and task commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/crew` | — | — | opens the crew panel: the three seats, the allowed models, the providers, the per-task limit and the daily cap, changed in place |
 | `/crew` | — | `pin <seat> <model[@provider]>` | pins the worker, planner or checker to a model; `/model` stays |
 | `/crew` | — | `unpin <seat\|all>` | puts a seat back on auto |
@@ -196,18 +222,31 @@ Canonical word, the other words it answers to, its argument form, and what it do
 | `/task` | — | `solo <brief>` | starts one worker at once, with no reading of its width |
 | `/task` | — | `--best <brief>` | starts the task on the strongest crew the allowed models make, this task only |
 | `/task` | — | `--cheap <brief>` | starts the task on the cheapest crew that does the work, this task only |
+| `/stop` | — | — | asks before stopping the open task or selected work; with no target says `open a running task to stop it` |
 | `/redo` | — | `stronger` | runs the last task again on a stronger crew, and teaches the crew that kind of work needs more |
 | `/history` | — | — | opens the full-screen sessions place — every task this machine has run, filterable (also ctrl+.) |
+
+## Status, search, teams and spending commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/status` | `/info`, `/context` | — | prints every fact the status line knows, one per line |
 | `/status` | `/info`, `/context` | `--json` | prints the same facts as one JSON object, keys in the same order |
 | `/search` | none | none | opens the search place, everything said on this machine (also `alt+9`) |
 | `/spend` | none | none | opens the spend place, what this machine has cost, by the day (also `alt+5`) |
 | `/wall` | | | every open conversation at once, as a grid of live tiles, and the teams you group them into (also `alt+v`, or `▦` under the box) |
 | `/teams` | | | the teams page: your teams as a tree, what waits on you, and the selected team's manager conversation (also `alt+2`, or `teams` on the tab bar) |
 | `/cost` | `/usage`, `/tokens` | — | prints what this conversation has spent, and on what |
+| `/effort` | `/think`, `/thinking` | — | opens this conversation's thinking levels; says it is unavailable when the session has no dial |
+| `/effort` | `/think`, `/thinking` | `<rung>` | sets this conversation's thinking level; an unknown rung lists the accepted levels and changes nothing |
 | `/budget` | `/limits` | — | what codeaf may spend · every limit on one tab |
 | `/budget` | `/limits` | `<amount>` | sets the day's limit · `none` removes it |
 | `/budget` | `/limits` | `<row> <amount>` | sets one by name: `day`, `conversation`, `plan`, `practice` |
+
+## Cache, display and export commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/cache` | — | — | how big the shared build cache is, and where |
 | `/cache` | — | `clean` | asks first, then deletes the cache to free disk — confirm with `/cache clean now` |
 | `/debug` | — | — | keeps the full record of **this conversation** from here on, and says which folder it goes to |
@@ -219,6 +258,11 @@ Canonical word, the other words it answers to, its argument form, and what it do
 | `/export` | `/save` | `<path>` | …and writes it there; tab completes the path |
 | `/files` | — | — | lists what has been made for you; opens, reveals or copies one — over `--host` it opens the browse page for that machine |
 | `/files` | — | `<path>` | over `--host`, brings that one file back and opens it here |
+
+## Help and leaving commands
+
+| Command | Aliases | Argument | Effect |
+|---|---|---|---|
 | `/help` | `/?` | — | prints this list |
 | `/manual` | — | — | asks the model what codeaf can do, answered from codeaf's own manual |
 | `/manual` | — | `<question>` | puts that question to the model, answered from codeaf's own manual, naming the page |

internal/manual/chat/delegates.md

@@ -24,10 +24,13 @@ task's, shows the actions the program took, each under the step of its own proce
 program asks for, the run's own work model answers, and the raw calls name the model that
 did.
 
+## Where a program's badge appears — and where it does not
+
 **Every program's tasks wear its name as a badge**: `[<name>]` after the task's title on
-the side list, the card, the task's page, the `@` list, the tasks place and home, and its
+the side list, the proposal card, the task's page, the `@` list, the tasks place and home, and its
 initials (`[sd]` for senior-dev) where a list is narrow. A task codeaf's own worker does
 wears none, and a program added to codeaf later gets its own badge from its name.
+The landed card's head shows the title and outcome without a program badge.
 
 This is different from a harness or a subharness, which are built out of codeaf's own
 parts. A program codeaf carries has an engine of its own.

internal/manual/chat/getting-started.md

@@ -12,19 +12,29 @@ terminal* page, under *How do I install or update codeaf*.
 
 ## Getting started — first time setup, what happens the first time I run codeaf
 
-The first time `codeaf` opens on a profile with nothing in it, the chat does not open on
-an empty prompt and a provider error. It opens in the chat itself, on **two screens** —
-under a minute, nothing else on the frame:
+The first time `codeaf` opens a new local conversation on a profile with nothing in it,
+setup appears in the chat instead of an empty prompt and a provider error. When the
+default provider needs a key and no daily limit is configured, it has **two screens** — under a minute,
+nothing else on the frame:
 
 1. **connect openrouter** — the default service; `enter` signs in in your browser, and pasting an existing key also works
 2. **Models and spending** — one screen with two controls on it, **Daily limit** and
    **Chat model**, each already showing the value that is in force
 
+**With a key already found, there is no setup screen.** When a provider key is saved in
+the profile or set in the environment, such as `OPENROUTER_API_KEY`, a plain launch opens
+straight on home: no connection screen and no **Models and spending**. `/budget` sets a
+daily limit later. A `--no-host` launch on such a profile skips only the connection screen,
+and still opens **Models and spending** while no daily limit is set. A resumed conversation,
+or one on another machine, never opens first-run setup.
+
 The second screen's way out is **`Start a conversation`**. Every control on it opens on
 the value you already have, so pressing `enter` there agrees to exactly what is on the
 screen. Its heading is `Models and spending` and the line under it is
 `Keep these choices or change them.`
 
+## Skipping setup and reading its header
+
 `esc` on the first screen skips the setup: the flow is marked seen and it does not open
 again. `esc` on the controls screen goes **back** to the connection when there is one
 behind it, and skips when the controls are the whole of the setup. A skip leaves one dim
@@ -39,8 +49,8 @@ Codex is deliberately not another first-run step. After setup, its browser sign-
 available from the Codex row in `/connect`, or from `codeaf connect codex` without
 opening the chat.
 
-The header reads `codeaf` on the left and `setup · 2 of 2` on the right; with only one
-screen to show there is no count at all. The foot names the keys that work on the row you
+The header reads `codeaf`, with `setting up · 1 of 2` under the wordmark on the first of two
+steps. With only one step it reads `setting up`, without a count. The foot names the keys that work on the row you
 are standing on — `tab` walks the rows, `?` opens a control's detail — and on a narrow
 window it is cut by whole clauses rather than mid-word.
 

internal/manual/chat/questions.md

@@ -78,15 +78,17 @@ Most of them wait. A wait that ended is not a no: an approval question, a
 standing card and a page waiting to be approved carry no clock at all, and they
 stay up until somebody answers them.
 
-**A task proposal and a reversible recommendation may carry a clock.** The answers
-row says which answer is about to be taken and when — `start it in 9s` — and when
+**A task proposal and a reversible recommendation may carry a clock.** The card's
+top edge, beside who is asking, says which answer is about to be taken and when —
+`start it in 15s` at the task proposal's default — and when
 the time runs out the work STARTS. It is your chance to correct it, not a gate the
 work waits on. Any key you press stops that clock, and a proposal you hold loses
-its deadline and then waits like everything else, with `waiting` on the end of the
-row instead of a countdown.
+its deadline and then waits like everything else, showing `waiting` instead of a countdown.
+
+## What a question's clock says before it acts
 
 **A clock says what it is going to do, in that shape's own words.** Where there
-is a recommended answer the tail is that answer — `start it in 9s`. Where there
+is a recommended answer the clock names that answer — `start it in 9s`. Where there
 is not, the words depend on the shape: a proposal reads `starts on its own in 9s`
 because something begins when it runs out, and an assumptions card reads
 `goes on in 9s`, because nothing begins — the asker simply stops waiting for you
@@ -744,7 +746,7 @@ Almost nothing does. A wait that ended is not a no, and nothing on the block
 answers in your place if you say nothing.
 
 There is exactly one thing that decides by itself: **a task proposal**, whose
-card says which answer it is going to take and when — `start it in 9s`. That
+card says which answer it is going to take and when — `start it in 15s` at the default. That
 card is your chance to redirect the work, not a gate the work waits on, and it
 starts on its own if nobody says otherwise. Nothing else on this surface acts
 without you, and nothing that cannot be taken back ever will.