@skillcdn/console 0.3.2 → 0.4.0

package/docs/specs/cli.md

@@ -27,7 +27,7 @@ The board is a project's ([ADR-0008](../adr/0008-a-workspace-holds-projects-and-
 | `whoami` | `GET /api/v1/me` | the login, the role, the workspace, the address, and the project this directory works in; with a project, where the organization's rules are read and where the skill working-the-board is on this machine; then the command's version and where it is installed, the console's version and the range it takes, and the update to make when they differ. Keeps the workspace's time zone on the login it used, so that the moments the command prints are in it from then on ([ADR-0035](../adr/0035-who-may-see-whom-is-decided-by-one-policy-and-the-workspace-keeps-its-settings.md)) |
 | `projects` | `GET /api/v1/projects` | one line per project: key, name, what the person is in it, what waits in it |
 | `use <key> [--url <origin>] [--account <login>]` | `GET /api/v1/projects/<key>` | that the directory works in the project from now on, at which console and as which account where it binds them, and that `console rules` says what its people ask; then the sentence for the checkout's agreement (AGENTS.md, or CLAUDE.md), to be copied as it is; writes `.skillcdn-console.json` |
-| `work [--person <login>]` | `GET /api/v1/work`, `GET /api/v1/people/<id>/work` | what is on the person's plate across their projects: the open tasks they work on, the sooner due first, each with its project; and the decisions waiting. `--person` shows another person's plate, for an administrator or an owner of a project they are in: the open tasks they work on within the projects the asker may see, without the decisions. The tasks done or dropped lately, which the answer carries as `closed` for the week on the plate's page, are in `--json` only. Needs no project |
+| `work [--person <login>]` | `GET /api/v1/work`, `GET /api/v1/people/<id>/work` | what is on the person's plate across their projects: the open tasks they work on, the sooner due first, each with its project; and the decisions waiting for their answer ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)). `--person` shows another person's plate, for an administrator or an owner of a project they are in: the open tasks they work on within the projects the asker may see, without the decisions. The tasks done or dropped lately, which the answer carries as `closed` for the week on the plate's page, are in `--json` only. Needs no project |
 | `tasks [--state <state>] [--open] [--mine] [--category <key>] [--goal <id>] [--due <day\|today\|week\|overdue>] [--unassigned] [--search <words>] [--archived] [--limit <n>] [--offset <n>]` | `GET .../tasks` with the filters and the page (`--mine` and `--unassigned` not together; `--search` is `q=`, the words of a title or a number, how a task is found as a parent, [ADR-0037](../adr/0037-a-task-has-one-owner-and-any-number-of-workers-and-a-parent-or-a-goal-is-found-by-search.md)) | one line per task: number, state, priority, title, owner, workers, category, due day, what waits on it, and whether it is put away; the tasks put away are left out unless `--archived` asks for them alone; a page at a time |
 | `task <number\|id>` | `GET .../tasks/<ref>`, the decisions about it, the runs on it, `GET .../tasks/<id>/comments` | the task in full, with its plan and its moments, and the discussion on it: each comment whole, with its files and the command that reads each |
 | `task new <title> [--body <markdown>\|--file <path>] [--state <state>] [--priority <priority>] [--category <key>] [--goal <id>] [--starts <day>] [--due <day>] [--worker <login\|me\|none>]... [--parent <number\|id>]` | `POST .../tasks` | the number and the id; `--worker` given again, or with commas between, names several, in place of the workers there were, and `none` alone nobody |
@@ -57,8 +57,8 @@ The board is a project's ([ADR-0008](../adr/0008-a-workspace-holds-projects-and-
 | `members` | `GET .../members` | one line per member: login, role, since when; in a project open to the workspace, everyone of it ([ADR-0035](../adr/0035-who-may-see-whom-is-decided-by-one-policy-and-the-workspace-keeps-its-settings.md)) |
 | `member add <login> [--role owner\|member] [--project <key>[,<key>...]]`, `member role <login> <owner\|member>`, `member remove <login>` | `GET /api/v1/people?login=` for the id, then `POST .../members` (once per project when `--project` names several with commas), `PATCH .../members/<id>`, `DELETE .../members/<id>` | the member as they are now, or that they are no longer listed; with several projects, one line per project, a person listed already said so; for an owner. In a project open to the workspace everyone is a member already: `add` lists an owner with `--role owner` and refuses a member (`member.open_project`), `role <login> owner` lists one and `role <login> member` takes the listing away, `remove` takes a listing away and the person stays a member |
 | `category new <key> <name> [--color <name>]`, `category edit <key> [--name <name>] [--color <name>]`, `category remove <key>` | `POST /api/v1/categories`, `PATCH .../categories/<key>`, `DELETE .../categories/<key>` | the category as it is now, or that it is gone; for an administrator |
-| `skills`, `skills <folder>`, `skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]` | `GET .../skills`; `GET .../skills/browse?path=&cursor=`, page after page to the end; `GET .../skills/find?query=&path=&cursor=&limit=`, one page | the project's pack, or the organization's ([ADR-0031](../adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md)): where it is, at a deployment or on the console's machine, and how the read went; what a client is told of it on connect, as the deployment tells one, with the reads named as the console's commands; every skill with the path of its `SKILL.md` and every document, as a search without words lists them; where a person connects an agent of its own, and where the console's own skills are on this machine. With a folder (`.` for the root; `/` is taken too, but a Windows shell rewrites it into a path before the command sees it), what it holds, whole, as `browse_repo` lays it out for a model. With `--search`, one page of what the words find, as `search_repo` does: skills first with the files of theirs that matched, then documents, in relevance order, within the folder when one is named, ten unless `--limit` says otherwise (up to 25), and a `nextCursor` line when more matched, which `--cursor` continues. `--json` is the console's answer: what the pack answered, in the shapes of the main repository's REST API, the pages of a folder joined |
-| `skill <path>`, `skill --file <path>` | `GET .../skills`, then `GET .../skills/one?path=&cursor=`, page after page until `complete`; with `--file`, `GET .../skills/file?path=&offset=` until the end | the skill whole, as `load_skill` lays it out for a model: the rules of the repository from its root to the nearest manifest, the instructions, the included files, then its supporting files and what it refers to, rendered by the main repository's own renderers with the reads named as the console's commands; or the file whole, or what a folder holds; a private pack through the pack token the project holds ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)). `<path>` is the path of the SKILL.md from the repository's root, or the URI the pack names it by (`skill://<host>/<owner>/<name>/<path>`); a URI of another pack is not understood. `--file` takes no skill's path beside it: the two given together are not understood. A read the pack refused prints its status and the pack's own words, and exits with `0` |
+| `skills`, `skills <folder\|file>`, `skills --search <words> [<folder>] [--limit <n>] [--cursor <cursor>]` | `GET .../skills`; `GET .../skills/browse?path=&cursor=`, page after page to the end; `GET .../skills/find?query=&path=&cursor=&limit=`, one page | the project's pack, or the organization's ([ADR-0031](../adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md)): where it is, at a deployment or on the console's machine, and how the read went; what a client is told of it on connect, as the deployment tells one, with the reads named as the console's commands; every skill with the path of its `SKILL.md` and every document, as a search without words lists them; where a person connects an agent of its own, and where the console's own skills are on this machine. With a folder (`.` for the root; `/` is taken too, but a Windows shell rewrites it into a path before the command sees it), what it holds, whole, as `browse_repo` lays it out for a model. With a file's path, the file's outline, whole: every heading with its level and the offset and limit that read its section with `skill --file`; a file that is not Markdown has none, and the line says so (SkillCDN 0.4). With `--search`, one page of what the words find, as `search_repo` does: skills first with the files of theirs that matched, then documents, each with the sections of it that matched and the offset and limit that read each, in relevance order, within the folder when one is named, ten unless `--limit` says otherwise (up to 25), a line on how the page was ranked where the deployment searches by meaning too, and a `nextCursor` line when more matched, which `--cursor` continues. `--json` is the console's answer: what the pack answered, in the shapes of the main repository's REST API, the pages of a folder or an outline joined |
+| `skill <path>`, `skill --file <path> [--offset <n>] [--limit <n>]` | `GET .../skills`, then `GET .../skills/one?path=&cursor=`, page after page until `complete`; with `--file`, `GET .../skills/file?path=&offset=` until the end, or, with `--offset` or `--limit`, `GET .../skills/file?path=&offset=&limit=` once | the skill whole, as `load_skill` lays it out for a model: the rules of the repository from its root to the nearest manifest, the instructions, the included files, then its supporting files and what it refers to, rendered by the main repository's own renderers with the reads named as the console's commands; or the file whole, or what a folder holds; or, with `--offset` (0 or more) or `--limit` (1 to 100,000), one page of the file as asked, the section a search or an outline named, with where the file continues; a private pack through the pack token the project holds ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)). `<path>` is the path of the SKILL.md from the repository's root, or the URI the pack names it by (`skill://<host>/<owner>/<name>/<path>`); a URI of another pack is not understood. `--file` takes no skill's path beside it, and `--offset` and `--limit` go with `--file` only: otherwise not understood. A read the pack refused prints its status and the pack's own words, and exits with `0` |
 | `rules` | `GET .../rules`, or `GET /api/v1/rules` without a project named, and `GET /api/v1/me` | the rules that hold, as they read for the person (`{language}` is the language they chose, or the task's) ([ADR-0023](../adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)): the workspace's, the console's own until an administrator writes the organization's, with its version and who wrote it when written; then this project's own, or that it adds none |
 | `rules write --body <markdown>\|--file <path>\|-\|none [--workspace] [--base <version>]` | `PUT .../docs/rules` or `POST .../docs/rules/archive`; with `--workspace`, `PUT /api/v1/rules` or `POST /api/v1/rules/archive` | the version written, that the console's own rules sent as they are wrote nothing, or that the rules are put away; for an owner of the project, or an administrator for the workspace's |
 | `take <number\|id> [--agent <name>]` | `GET .../tasks/<ref>`, then `POST .../runs`, then `GET .../rules`, `GET /api/v1/me`, `GET .../tasks/<ref>` again, `GET .../tasks/<id>/comments` and `GET .../runs?open=true&mine=true` | the run that began, with the run's id and the task's id on a line of their own, the task in full as it stands taken with the discussion on it, the rules that hold as they read for the person, and what to do next; a run open on the task is taken over, and that is said when it happened ([ADR-0020](../adr/0020-the-console-does-not-claim-an-agent-is-at-work-a-run-says-when-it-was-last-heard-from-and-a-new-run-takes-over.md)); another run of the token open in the project is named, with the `--run <id>` to say on every command on a run from here |
@@ -66,9 +66,10 @@ The board is a project's ([ADR-0008](../adr/0008-a-workspace-holds-projects-and-
 | `hand-in <https url \| file path> [--label <words>] [--run <id>]` | `POST .../runs/<id>/artifacts` for a link; `POST .../runs/<id>/files` for a file, sent as a form with its name and its media type by extension | how many artifacts; a picture handed in is shown on the task, and where a report names it as `![words](its name)` |
 | `comment <number\|id> "<markdown>" [--attach <path>]...`, `comment <number\|id> --file <path>`, `comment <number\|id> -` | `GET .../tasks/<ref>`, then `POST .../tasks/<id>/comments`: as JSON, or as one form with the part `body` and a part `file` per file attached, its media type by extension | the comment as written, with its files and the command that reads each; a word to the task's people, which needs no run ([ADR-0024](../adr/0024-a-task-carries-a-discussion-of-comments-with-their-files-read-as-one-thread-with-the-runs-and-the-decisions.md)) |
 | `file <id> [--out <path>]` | `GET .../files/<id>` | that the file is saved, where, with its size and type: under its own name in the working directory, at the path, or into the directory named; a file a run handed in, one put in a comment, or one attached to a page, so that an agent looks at a picture a person put on the board |
-| `ask "<question>" --option "<label>" ... [--body <markdown>\|--file <path>] [--wait <seconds>] [--run <id>]` | `POST .../decisions` with `runId`, then `GET .../decisions/<id>?wait=` | the decision raised, its id on a line of its own, its options; then the answer, or that it still waits |
+| `ask "<question>" --option "<label>" ... [--body <markdown>\|--file <path>] [--to <login\|me>] [--wait <seconds>] [--run <id>]` | `POST .../decisions` with `runId` and, for `--to`, `deciderId`, then `GET .../decisions/<id>?wait=` | the decision raised, its id on a line of its own, whom it waits for, its options; then the answer, or that it still waits. It is for the person the agent works for unless `--to` names another of the project ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)) |
 | `decision <id> [--wait <seconds>]` | `GET .../decisions/<id>`, with `?wait=` while waiting | the decision; with a wait, the answer or that it still waits |
-| `decisions [--open] [--limit <n>] [--offset <n>]` | `GET .../decisions` | one line per decision; a page at a time |
+| `answer <id> --option <n>\|--own "<answer>" [--note <markdown>\|--file <path>]` | `POST .../decisions/<id>/answer` | the decision with its answer: a person's answer written in their name through the agent, as they gave it in chat or in passing, with where and when in the note, so that the record is whole and a run that waited goes on ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)) |
+| `decisions [--open] [--limit <n>] [--offset <n>]`, `decisions --mine\|--raised [--open] [--limit <n>] [--offset <n>]` | `GET .../decisions`; `GET /api/v1/decisions` for `--mine`, with `raised=true` for `--raised`, neither needing a project | one line per decision, the waiting first; with `--mine`, the decisions addressed to the person across the projects they may see, with `--raised` those they asked of someone else, each with its project's key; a page at a time |
 | `finish [--summary <markdown>\|--file <path>] [--run <id>]`, `fail [...]` | `POST .../runs/<id>/end` | how the run ended |
 | `abandon [<run id>] [--summary <markdown>]` | `POST .../runs/<id>/end`, as `abandoned` | the same |
 | `runs [--task <number\|id>] [--open] [--mine] [--limit <n>] [--offset <n>]` | `GET .../runs` | one line per run, with when an open one was last heard from; a page at a time |

package/docs/specs/rest.md

@@ -38,6 +38,7 @@ The API is the board as its members see it: the people, the projects, and in eac
 | 400 | `decision.invalid_task` | The decision is about a task that is not one of the project's. |
 | 400 | `decision.no_such_option` | The answer names an option the decision does not have. |
 | 400 | `decision.invalid_run` | A decision raised from a run that is not the asker's, or is over. |
+| 400 | `decision.invalid_decider` | The person named to decide may not work in the project ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)). |
 | 400 | `token.expiry_at_most` | A token that would not expire, or would outlast `TOKEN_DAYS_AT_MOST`, where the organization requires an expiry. |
 | 400 | `document.invalid_path` | The path a page is written at is not one: segments of lowercase letters, digits and hyphens, separated by slashes. |
 | 400 | `run.too_many_reports`, `run.too_many_artifacts` | The run carries as many as one may (`MAX_REPORTS_PER_RUN`, `MAX_ARTIFACTS_PER_RUN`). |
@@ -140,7 +141,11 @@ The rules of the board ([ADR-0023](../adr/0023-the-rules-of-a-board-are-pages-th
 
 ### `GET /api/v1/work`
 
-`{ "tasks": [{ "project": { "key", "name", "color", "symbol", "icon" }, "task" }, ...], "closed": [{ "project", "task" }, ...], "decisions": [{ "project", "decision" }, ...] }`: what is on the asker's plate across the projects they may see ([ADR-0019](../adr/0019-a-task-is-planned-in-days-the-board-keeps-its-moments-and-goals-and-categories-give-the-work-its-shape.md)): the open tasks they are at work on, the sooner due first and those with no day last; `closed`, the tasks they are at work on that are done or dropped and not yet put away, the last closed first, so that the week on the plate's page shows them on their days as a project's calendar does; and the decisions that wait for a person, the longest waiting first; each with the project it belongs to, so that a page says and links it. A task put away is in neither list ([ADR-0030](../adr/0030-a-task-is-put-away-from-any-state.md)). At most `LIST_LIMIT` of each.
+`{ "tasks": [{ "project": { "key", "name", "color", "symbol", "icon" }, "task" }, ...], "closed": [{ "project", "task" }, ...], "decisions": [{ "project", "decision" }, ...] }`: what is on the asker's plate across the projects they may see ([ADR-0019](../adr/0019-a-task-is-planned-in-days-the-board-keeps-its-moments-and-goals-and-categories-give-the-work-its-shape.md)): the open tasks they are at work on, the sooner due first and those with no day last; `closed`, the tasks they are at work on that are done or dropped and not yet put away, the last closed first, so that the week on the plate's page shows them on their days as a project's calendar does; and the decisions that wait for the asker's answer ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)), the longest waiting first; each with the project it belongs to, so that a page says and links it. A task put away is in neither list ([ADR-0030](../adr/0030-a-task-is-put-away-from-any-state.md)). At most `LIST_LIMIT` of each.
+
+### `GET /api/v1/decisions?open=&raised=&limit=&offset=`
+
+`{ "items": [{ "project": { "key", "name", "color", "symbol", "icon" }, "decision" }, ...], "more": boolean }`: the decisions addressed to the asker ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)) across the projects they may see, a page at a time as the tasks are (`limit`, `offset`, `more`): the ones that wait first, the longest waiting first among them, then the answered, newest first, as the record; `open=true` keeps only those that wait, and `raised=true` answers instead the decisions the asker raised, through their agent or themselves, for someone else. Each decision comes with the project it belongs to, as the plate's things do, so that a page says and links it. What a person's own page of decisions reads, in both kinds, and `console decisions --mine` and `--raised`.
 
 ### `GET /api/v1/tokens` and `POST /api/v1/tokens`
 
@@ -216,11 +221,11 @@ Writing one, for whoever may work in the project, with a session or a token, is
 
 ### `GET /api/v1/projects/<key>/decisions?open=&task=&limit=&offset=`
 
-`{ "items": [decision, ...], "more": boolean }`: the project's, the ones that wait first, newest first within each, a page at a time as the tasks are (`limit`, `offset`, `more`); `open=true` keeps only those that wait, `task=<id>` only those about one task. A decision carries its `question`, `body` (Markdown: the context it rests on), `options` (each an `id` and a `label`; the last carries `own: true` when it is the person's own answer, written instead of choosing, and the options given carry no `own`), `taskId` and `taskNumber` (or `null`), `raisedBy`, `run` (the `id` and `agent` of the run that raised it, when an agent asked, or `null`), `answer`: `null` while it waits, else the chosen `option`, a `note` or `null` (the rationale given with it), `by` and `at`; and `outcome`, what followed, in Markdown, or `null` until someone writes it. Context, rationale and outcome make the decision a record ([ADR-0009](../adr/0009-documents-are-pages-of-markdown-in-a-project-addressed-by-path-versioned-and-linked-both-ways.md)); a link in any of them to a document's path is kept both ways, so that the document says the decision refers to it.
+`{ "items": [decision, ...], "more": boolean }`: the project's, the ones that wait first, newest first within each, a page at a time as the tasks are (`limit`, `offset`, `more`); `open=true` keeps only those that wait, `task=<id>` only those about one task. A decision carries its `question`, `body` (Markdown: the context it rests on), `options` (each an `id` and a `label`; the last carries `own: true` when it is the person's own answer, written instead of choosing, and the options given carry no `own`), `taskId` and `taskNumber` (or `null`), `raisedBy`, `decider` (whom it is for, [ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md): the raiser, unless another person of the project was named), `run` (the `id` and `agent` of the run that raised it, when an agent asked, or `null`), `answer`: `null` while it waits, else the chosen `option`, a `note` or `null` (the rationale given with it), `by` and `at`; and `outcome`, what followed, in Markdown, or `null` until someone writes it. Context, rationale and outcome make the decision a record ([ADR-0009](../adr/0009-documents-are-pages-of-markdown-in-a-project-addressed-by-path-versioned-and-linked-both-ways.md)); a link in any of them to a document's path is kept both ways, so that the document says the decision refers to it.
 
 ### `POST /api/v1/projects/<key>/decisions`
 
-Takes `question`, `options` (two to `MAX_OPTIONS` labels), and optionally `body`, and either `taskId` or `runId`. Options are numbered from `1`. From a run, which must be the asker's and open (`decision.invalid_run`), the decision is about the run's task, `taskId` is not looked at, and the run waits (`status: waiting`) until the answer. Answers `201` with the decision and writes a `decision.raised` event, with the `agent` when a run asked.
+Takes `question`, `options` (two to `MAX_OPTIONS` labels), and optionally `body`, and either `taskId` or `runId`. `deciderId` names whom the decision is for ([ADR-0042](../adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)): a person who may work in the project, as a worker of a task must (`decision.invalid_decider` otherwise); left out, the asker, which from a run is the person the agent works for. Anyone of the project may still answer. Options are numbered from `1`. From a run, which must be the asker's and open (`decision.invalid_run`), the decision is about the run's task, `taskId` is not looked at, and the run waits (`status: waiting`) until the answer. Answers `201` with the decision and writes a `decision.raised` event, with the `agent` when a run asked.
 
 ### `GET .../decisions/<id>?wait=` and `POST .../decisions/<id>/answer`
 
@@ -242,7 +247,7 @@ One goal, for whoever may see the project. The patch, for an owner, takes any of
 
 ### `GET /api/v1/projects/<key>/runs?task=&open=&mine=&limit=&offset=` and `GET .../runs/<id>`
 
-`{ "items": [run, ...], "more": boolean }`: the project's runs, newest first, a page at a time as the tasks are (`limit`, `offset`, `more`); `task=<id>` keeps those on one task, `open=true` those not over (`running` or `waiting`) and `open=false` those over, `mine=true` the asker's own: with a token, the runs begun with that token, which is one agent's; on a session, the runs for the person. A run is one agent's work on one task for one person: `taskId` and `taskNumber` (the one people say), `person` (whom the agent acts for), `agent` (what it calls itself), `status` (`running`, that is open, `waiting` for a decision, `finished`, `failed`, `abandoned`), `startedAt`, `endedAt` or `null`, `lastHeardAt` (when the agent was last heard from through the run: its start, then its latest report, hand-in or question; the console knows nothing of an agent but what it sends, and claims nothing more, [ADR-0020](../adr/0020-the-console-does-not-claim-an-agent-is-at-work-a-run-says-when-it-was-last-heard-from-and-a-new-run-takes-over.md)), `summary` (Markdown, what the agent said at the end, or `null`), `reports` (each `id`, `body` in Markdown, `createdAt`; oldest first), `artifacts` (each `id`, `kind`, `url` for a link or `null`, `label` or `null`, `file` for a file or `null`, and `createdAt`; a file is its `name`, `size` in bytes, `contentType` and `sha256`), and `waitingFor`, the id of the decision the run waits for, or `null`.
+`{ "items": [run, ...], "more": boolean }`: the project's runs, newest first, a page at a time as the tasks are (`limit`, `offset`, `more`); `task=<id>` keeps those on one task, `open=true` those not over (`running` or `waiting`) and `open=false` those over, `mine=true` the asker's own: with a token, the runs begun with that token, which is one agent's; on a session, the runs for the person. A run is one agent's work on one task for one person: `taskId` and `taskNumber` (the one people say), `person` (whom the agent acts for), `agent` (what it calls itself), `status` (`running`, that is open, `waiting` for a decision, `finished`, `failed`, `abandoned`), `startedAt`, `endedAt` or `null`, `lastHeardAt` (when the agent was last heard from through the run: its start, then its latest report, hand-in or question; the console knows nothing of an agent but what it sends, and claims nothing more, [ADR-0020](../adr/0020-the-console-does-not-claim-an-agent-is-at-work-a-run-says-when-it-was-last-heard-from-and-a-new-run-takes-over.md); a run `running` and not heard from for twelve hours, or the hours the deployment sets, is ended by the console as `abandoned`, its `summary` saying so and `run.ended` naming no actor and `reason: "unheard"`, while a run `waiting` for an answer waits on, [ADR-0041](../adr/0041-a-run-not-heard-from-for-twelve-hours-is-ended-by-the-console.md)), `summary` (Markdown, what the agent said at the end, or `null`), `reports` (each `id`, `body` in Markdown, `createdAt`; oldest first), `artifacts` (each `id`, `kind`, `url` for a link or `null`, `label` or `null`, `file` for a file or `null`, and `createdAt`; a file is its `name`, `size` in bytes, `contentType` and `sha256`), and `waitingFor`, the id of the decision the run waits for, or `null`.
 
 ### `POST /api/v1/projects/<key>/runs`
 
@@ -260,7 +265,7 @@ The bytes of any file of the project, handed in by a run, put in a comment or at
 
 ### `POST .../runs/<id>/end`
 
-Takes `status` (`finished`, `failed` or `abandoned`) and optionally a `summary` (Markdown, `MAX_SUMMARY_LENGTH`: what was done and what is left), ends the run (`run.ended`), and answers it. A finished run puts a task that was `in_progress` up for review (`in_review`); the rest leave the task as it is. The run's person ends it, as `finished` or `failed` from their agent; `abandoned` is a person giving up on a run that will not come back: their own, or anyone's as an owner of the project, signed in or through their agent (`run.not_yours` otherwise). A run that is over is `run.over`.
+Takes `status` (`finished`, `failed` or `abandoned`) and optionally a `summary` (Markdown, `MAX_SUMMARY_LENGTH`: what was done and what is left), ends the run (`run.ended`), and answers it. A finished run puts a task that was `in_progress` up for review (`in_review`); the rest leave the task as it is. The run's person ends it, as `finished` or `failed` from their agent; `abandoned` is a person giving up on a run that will not come back: their own, or anyone's as an owner of the project, signed in or through their agent (`run.not_yours` otherwise); the console gives up on a run itself when it has not heard from it for twelve hours ([ADR-0041](../adr/0041-a-run-not-heard-from-for-twelve-hours-is-ended-by-the-console.md)). A run that is over is `run.over`.
 
 ### `GET /api/v1/projects/<key>/skills`
 
@@ -268,7 +273,7 @@ The project's pack, read by address ([ADR-0028](../adr/0028-the-console-reads-a-
 
 ### `GET /api/v1/projects/<key>/skills/one?path=&cursor=`, `.../skills/file?path=&offset=&limit=`, `.../skills/browse?path=&cursor=&limit=` and `.../skills/find?query=&path=&cursor=&limit=`
 
-One skill of the pack, a file of it, what a folder holds and what words find, read by the console from the pack for whoever may see the project, with the SkillCDN token the pack is read with, the project's own or the workspace's ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)), and answered as the pack answered them ([ADR-0031](../adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md)): `{ "address", "source", "page", "status", "refusal", "read" }`, the envelope as above, and `read` the body of the matching route of the main repository's REST API, as `@skillcdn/core` spells it, or `null` unless `ready`. `skills/one` is `load_skill`: `read` is a `RestSkill`, a page of the skill's context, the rules from the repository's root to the nearest manifest, the body and the included files, which `complete` and `nextCursor` say to continue, and `commit`, the commit it was read from. `skills/file` is `read_repo_file`: `read` is a `RestFile`, a page of the file in characters (`offset`, `nextOffset`, `totalLength`; `limit` 1 to 100,000) or, when the path names a folder, its entries. `skills/browse` is `browse_repo`: `read` is a `RestBrowse`, a page of what the folder holds (`limit` 1 to 200, 50 unless given; `cursor` continues). `skills/find` is `search_repo`: `read` is a `RestFind`, a page of what the words find in relevance order (`query` 1 to 500 characters, required; `limit` 1 to 25, 10 unless given). `path` is a path from the repository's root, up to 500 characters, the mounted folder when `browse` and `find` leave it out; a query out of bounds is `request.invalid`. Each read is logged with who read what of which pack, never with what was read or the words searched for. What the pack refuses is the status with the pack's own `refusal`: a skill or a file that is not there is `not_found`, a file the pack will not carry, too large or not text, is `failed` with where it is at its source. `@skillcdn/core` reads every `read` back as the result it was made from (`skillResultOf`, `fileResultOf`, `directoryResultOf`, `browseResultOf`, `findResultOf`, at the `mountSummaryOf` of the listing's `mount`) and renders what a model is given; the command does exactly that.
+One skill of the pack, a file of it, what a folder holds and what words find, read by the console from the pack for whoever may see the project, with the SkillCDN token the pack is read with, the project's own or the workspace's ([ADR-0028](../adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md)), and answered as the pack answered them ([ADR-0031](../adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md)): `{ "address", "source", "page", "status", "refusal", "read" }`, the envelope as above, and `read` the body of the matching route of the main repository's REST API, as `@skillcdn/core` spells it, or `null` unless `ready`. `skills/one` is `load_skill`: `read` is a `RestSkill`, a page of the skill's context, the rules from the repository's root to the nearest manifest, the body and the included files, which `complete` and `nextCursor` say to continue, and `commit`, the commit it was read from. `skills/file` is `read_repo_file`: `read` is a `RestFile`, a page of the file in characters (`offset`, `nextOffset`, `totalLength`; `limit` 1 to 100,000) or, when the path names a folder, its entries. `skills/browse` is `browse_repo`: `read` is a `RestBrowse`, a page of what the folder holds (`limit` 1 to 200, 50 unless given; `cursor` continues); given a file's path, the file's `outline`, every heading with its level and the `offset` and `length` that read its section through `skills/file`, paged the same way, with `entries` empty (SkillCDN 0.4). `skills/find` is `search_repo`: `read` is a `RestFind`, a page of what the words find in relevance order (`query` 1 to 500 characters, required; `limit` 1 to 25, 10 unless given); a document among the results names the `sections` of it that matched, each with its heading path, the `offset` and `limit` that read it and an excerpt, and `ranking` says how the page was ranked where the deployment searches by meaning as well as by words. `path` is a path from the repository's root, up to 500 characters, the mounted folder when `browse` and `find` leave it out; a query out of bounds is `request.invalid`. Each read is logged with who read what of which pack, never with what was read or the words searched for. What the pack refuses is the status with the pack's own `refusal`: a skill or a file that is not there is `not_found`, a file the pack will not carry, too large or not text, is `failed` with where it is at its source. `@skillcdn/core` reads every `read` back as the result it was made from (`skillResultOf`, `fileResultOf`, `directoryResultOf`, `browseResultOf`, `findResultOf`, at the `mountSummaryOf` of the listing's `mount`) and renders what a model is given; the command does exactly that.
 
 ### `PUT /api/v1/projects/<key>/pack-token` and `DELETE .../pack-token`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillcdn/console",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "What a custom SkillCDN console is built from: the API client and schemas, the components, the composition of the default console, and the console command agents work the board with.",
   "license": "MIT",
   "homepage": "https://github.com/skillcdn/console#readme",
@@ -68,7 +68,7 @@
     "vitest": "^5.0.3"
   },
   "dependencies": {
-    "@skillcdn/core": "^0.3.1",
+    "@skillcdn/core": "^0.4.0",
     "react-markdown": "^10.1.0",
     "remark-gfm": "^4.0.1",
     "zod": "^4.6.5"

package/skills/building-a-console/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: A shell with Node.js 24 or newer and npm or pnpm, and an agent that reads and writes files. For looking at the pages against a board, the console command signed in by a person. A browser the agent can drive is optional. No key of the agent's own is needed, and it never sees a token.
 metadata:
   author: skillcdn
-  version: "1.5"
+  version: "1.7"
 skillcdn:
   translations:
     ko:
@@ -50,8 +50,8 @@ Nothing here restates them: they are the contract, current at the version instal
 | Which kind | Asked when the request does not say: "Is this console for you alone, served from your machine with your token; for the whole organization, in place of the default pages in the image; or a script against the API?" A member usually wants their own. |
 | Where the organization's build goes | Asked for the organization's: "How is the console run: with the deployment repository that deploying-a-console made, with an image you build yourselves, or from a directory mounted into it?" The answer places the result: the source in `console-ui/` of that repository, which its workflow builds on every push; a repository of its own whose build goes beside the Dockerfile of [deploy/README.md](/deploy/README.md) "A custom console in the image"; or the build in the directory. |
 | What it must show or do | From the request: a page, a component, a language, a brand, a column, a filter, a report. Asked for its missing half: "What should it show or do that the default console does not?" Everything else is the default console's and stays. |
-| The marks | From the organization's website when the request, or deploying-a-console, names one: its symbol and wordmark read from the site as [the-look-from-a-website.md](references/the-look-from-a-website.md) says, the light version or, with the person's word, the one-colour mark recoloured, shown at the plan. Else asked for a console that shows marks of its own, for the half the request leaves open: "Which picture should the pages show beside the board's name: a small square mark, the name as lettering, or both? Where is the file? The pages are dark, so it should be a light one." `brand` takes either or both. The symbol's slot is a square of one line's height (`.sc-brand-symbol`, 1rem): a wide mark, a lettermark of three or four times its height, is a wordmark and goes in as one, alone or beside a square symbol. A mark drawn in a dark colour vanishes on the dark pages: ask for a light version, or, with the person's word, recolour it when it is one colour. Default without a site: the board's name alone and no marks, which is the honest console. |
-| The colour | From the website's own colours when one is named, as the reference says, its primary colour read from the theme colour, the stylesheet's properties or the primary button. Else asked when the request names none and marks are wanted: "Which colour, or which mood?" A colour comes as words or a value; the value is the mark's own fill when it has one, else chosen and shown. A light colour becomes the accent (`--sc-color-accent` and its family); a dark one tints the field and its light (`--sc-color-field`, `--sc-color-light-*`), with a lighter shade of it as the accent, since an accent must read on the dark field. The mapping is shown at the plan, with the contrast checked. |
+| The marks | From the organization's website when the request, or deploying-a-console, names one: its symbol and wordmark read from the site as [the-look-from-a-website.md](references/the-look-from-a-website.md) says, the dark version or, with the person's word, the one-colour mark recoloured, shown at the plan. Else asked for a console that shows marks of its own, for the half the request leaves open: "Which picture should the pages show beside the board's name: a small square mark, the name as lettering, or both? Where is the file? The pages are light, so it should be a dark one." `brand` takes either or both. The symbol's slot is a square of one line's height (`.sc-brand-symbol`, 1rem): a wide mark, a lettermark of three or four times its height, is a wordmark and goes in as one, alone or beside a square symbol. A mark drawn in a light colour vanishes on the light pages: ask for a dark version, or, with the person's word, recolour it when it is one colour. Default without a site: the board's name alone and no marks, which is the honest console. |
+| The colour | From the website's own colours when one is named, as the reference says, its primary colour read from the theme colour, the stylesheet's properties or the primary button. Else asked when the request names none and marks are wanted: "Which colour, or which mood?" A colour comes as words or a value; the value is the mark's own fill when it has one, else chosen and shown. A dark or saturated colour becomes the accent (`--sc-color-accent` and its family); a pale one tints the field (`--sc-field-gradient`), with a darker shade of it as the accent, since an accent must read on the light field. The mapping is shown at the plan, with the contrast checked. |
 | The languages | Asked when the organization's language is not among the packs: "Which languages should the pages speak?" Default: the packs the package ships, chosen by the browser; a Korean organization gets Pretendard loaded, as the default console does. |
 | The name | Not asked: the server names the board (`WORKSPACE_NAME`, conventionally the organization or the person it is for, then Console: `Acme Console`), and `title` is only what the page says until the server answers. `index.html` gets the organization's `<title>` and `lang`. |
 | The console's address | For running one's own, what `console whoami` says. A script takes `CONSOLE_URL` and `CONSOLE_TOKEN` from the environment, never from a file in the repository. |

package/skills/building-a-console/references/the-default-console.md

@@ -10,7 +10,7 @@ The four files of the default UI, `apps/console/web/` in the console's repositor
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="color-scheme" content="dark" />
+    <meta name="color-scheme" content="light" />
     <title>Console</title>
   </head>
   <body>
@@ -24,9 +24,9 @@ The four files of the default UI, `apps/console/web/` in the console's repositor
 
 ```tsx
 // The marks of the brand come from the main repository's package, never from a copy here
-// (ADR-0013); the build gives back their addresses. The pages are dark, so the wordmark is white.
+// (ADR-0013); the build gives back their addresses. The pages are light, so the wordmark is black.
 import symbol from "@skillcdn/brand/symbol.svg";
-import wordmark from "@skillcdn/brand/wordmark-white.svg";
+import wordmark from "@skillcdn/brand/wordmark-black.svg";
 import { createConsole } from "@skillcdn/console";
 // The styles ship with the package; the build bundles them next to the script.
 import "@skillcdn/console/console.css";
@@ -137,4 +137,4 @@ export default defineConfig({
 }
 ```
 
-What a console of one's own changes. In the page: its `<title>` and `lang`, and its icons, linked directly in the page or through the plugin, for its own. In the script: the `title` it passes; the two `@skillcdn/brand` imports, for its own symbol and wordmark (a light one, since the pages are dark), or none; the face it loads, for its languages (`npm install pretendard` for Korean). In the build: the proxy's target, `http://127.0.0.1:11197` with `changeOrigin: true` for `console serve`; the default console's own proxy points at the `api` role's development port, which a console of one's own does not have, and its plugin reads the icons from the brand package, which a console of one's own replaces with files of its own. In the compiler's settings: `jsx`, `moduleResolution` and the `vite/client` types stay, which make an imported picture a module; `extends` and `references` are the repository's and go, with `"strict": true` of the console's own in their place. One thing to add in the build: `build: { assetsInlineLimit: 0 }`, so that every picture and font stays a file; Vite inlines an asset under 4 KB as a `data:` address, which the policy allows for a picture and refuses for a font (`font-src 'self'`), and the default console gets by only because none of its assets is that small.
+What a console of one's own changes. In the page: its `<title>` and `lang`, and its icons, linked directly in the page or through the plugin, for its own. In the script: the `title` it passes; the two `@skillcdn/brand` imports, for its own symbol and wordmark (a dark one, since the pages are light), or none; the face it loads, for its languages (`npm install pretendard` for Korean). In the build: the proxy's target, `http://127.0.0.1:11197` with `changeOrigin: true` for `console serve`; the default console's own proxy points at the `api` role's development port, which a console of one's own does not have, and its plugin reads the icons from the brand package, which a console of one's own replaces with files of its own. In the compiler's settings: `jsx`, `moduleResolution` and the `vite/client` types stay, which make an imported picture a module; `extends` and `references` are the repository's and go, with `"strict": true` of the console's own in their place. One thing to add in the build: `build: { assetsInlineLimit: 0 }`, so that every picture and font stays a file; Vite inlines an asset under 4 KB as a `data:` address, which the policy allows for a picture and refuses for a font (`font-src 'self'`), and the default console gets by only because none of its assets is that small.

package/skills/building-a-console/references/the-look-from-a-website.md

@@ -12,17 +12,17 @@ Fetch the homepage as HTML, with the agent's own tools, and read, in this order:
 | The wordmark | The same header: the name as lettering, wide, often an SVG beside or instead of the symbol | `brand.wordmark`, alone or beside the symbol. A mark three or four times wider than high is a wordmark, not a symbol. |
 | The colours | `<meta name="theme-color">`; custom properties on `:root` in the site's stylesheet (`--color-primary`, `--brand`, `--accent` and their kin); the fill of the primary button and the colour of links | One primary colour, as a value; a second where the site plainly has two. |
 | The type | `font-family` of the body and of the headings, in the stylesheet | The names, to tell the person; a face is loaded only as the rules below allow. |
-| The mood | The site itself: dark or light, flat or glassy, round or square corners | Whether the field stays dark (the pages are dark, and stay so), and whether the radii follow the site (`--sc-radius-*`). |
+| The mood | The site itself: dark or light, flat or glassy, round or square corners | Whether the field stays light (the pages are light by default, ADR-0040; a dark site is said at the plan, and darkening the pages is the person's word, not the default), and whether the radii follow the site (`--sc-radius-*`). |
 
 A site that cannot be fetched (a login wall, a block, no site after all) ends the reading: say so in one line and ask the person for the files, or keep the honest default.
 
 ## Mapping onto the pages
 
-The pages are dark: a field with a light in it, and panes of glass over it. The mapping is shown at the plan as a table, value by value, before a file is written.
+The pages are light: a pale field, and panes of frosted glass over it. The mapping is shown at the plan as a table, value by value, before a file is written.
 
-- **A mark drawn in a dark colour vanishes** on the dark pages. Look for the site's light or white variant first (a footer, a dark-mode asset, a `prefers-color-scheme` rule). Found none, and the mark is one colour: recolour it to the pages' text colour, with the person's word, since the mark is theirs. A mark of several colours on a dark fill: keep its fill as a rounded square behind it.
-- **A light primary colour** becomes the accent: `--sc-color-accent` and its family (`-hover`, `-subtle`, the point), as the package's README lists them.
-- **A dark primary colour** tints the field and its light: `--sc-color-field` and `--sc-color-light-*`, with a lighter shade of it as the accent, since an accent must read on the dark field.
+- **A mark drawn in a light colour vanishes** on the light pages. Take the site's dark or black variant first (its header on a light page, a light-mode asset, a `prefers-color-scheme` rule). Found none, and the mark is one colour: recolour it to the pages' text colour, with the person's word, since the mark is theirs. A mark of several colours on a light fill: keep its fill as a rounded square behind it.
+- **A dark or saturated primary colour** becomes the accent: `--sc-color-accent` and its family (`-solid`, `-contrast`, `-subtle`, the point), as the package's README lists them.
+- **A pale primary colour** tints the field: `--sc-field-gradient`, with a darker shade of it as the accent, since an accent must read on the light field.
 - **Contrast is checked**, not assumed: the accent on the field, and text on the panes, at the 4.5:1 of WCAG AA for text; a shade is moved until it passes, and the plan says which.
 - **The type follows the rules of the skill**: scripts, styles and fonts are bundled, never loaded from a CDN or written inline. A face the organization owns, or one under a license that allows bundling, is put in the repository and named in `--sc-font-sans`; otherwise the system faces stay, and the plan says that the site's face was not taken and why. Pretendard stays for Korean, as the default console has it.
 - **The name** stays the server's (`WORKSPACE_NAME`): the look is the marks, the colours and the type, never the words.

package/skills/working-the-board/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Needs a shell with the console command on the PATH (npm install -g @skillcdn/console, Node.js 24 or newer), signed in by a person. Nothing else; the command needs no key of its own and the agent never sees a token.
 metadata:
   author: skillcdn
-  version: "1.21"
+  version: "1.25"
 skillcdn:
   translations:
     ko:
@@ -22,6 +22,8 @@ A task of the board goes in, named by its number; a run comes out: the task take
 - **Checkpoints:** on the board, as decisions (phase 4), which a person answers from wherever they are; the reports say what was done at each milestone, and need no answer.
 - **Go-ahead:** the task's body is the go-ahead. A task that says what the agent may decide alone is followed within that; everything else that would change scope, cost or a trade-off is a decision.
 - **Changes mid-run:** a person changes the task or answers a decision on the board; the run takes it from there and says so in its next report. A report is never rewritten.
+- **A choice made elsewhere:** a decision is the record of a choice that is the person's to make, not the place it has to be made. An answer they give in chat, in a meeting or by changing the task is written on the decision in their name, `console answer <id> --option <n>|--own "<their words>" --note "<where and when>"`, before the work goes on: the run waits on the record, and the board shows as waiting only what is still open. What was decided is not asked again.
+- **A briefing:** asked what is on their plate, what is next, or for a briefing, the agent starts from `console work`: the decisions waiting for the person's answer come first, each with what waits on it and since when, since a waiting decision holds a run; then the tasks by their days. `console decisions --mine` and `--raised` read the rest of their decisions, the answered ones as the record.
 - **The discussion:** what people say about the task is in its comments, which `console task <number>` and `console take` print with the task; a picture they put in is saved with `console file <id>` and looked at with the agent's own tools. An answer to what they asked there, a question that is not a decision, a remark on what was handed in, is a comment of the agent's own: `console comment <number> "<markdown>" [--attach <file>]`, which needs no run. A report is the run's record; a comment is a word to people.
 - **Work given in chat:** when a person gives work in chat, in a directory that works in a project, the agent writes it on the board first (`console task new`), tells the person the number the command printed, never one assumed, since other agents write on the same board and the next number is nobody's to guess, takes it by that number and works it as below, so that the board holds the work and its record, and the person decides on the board.
 - **Language:** what people read, the reports, the questions, the pages and the summaries, is in the language the rules name for the person (`console take` prints them with the task), else the task's, so that the people of the board read as they wrote.
@@ -41,7 +43,7 @@ The full contract is the [specification of the command line](/docs/specs/cli.md)
 | Input | Source |
 |---|---|
 | The task | Its number (`#7`) or its id, from what the person said. Told to pick one, `console work` lists what is on the person's plate across their projects, the sooner due first (`--person <login>` another person's, for an administrator or an owner of a project they are in), and `console tasks --state ready --mine` what is ready and theirs in this one (`--due overdue`, `--due week`, `--category <key>` and `--goal <id>` narrow it further; `--search <words>` finds a task by the words of its title, or by its number); a task is never taken without being told which, or that any ready one may be. |
-| The work | The task's body, read with `console task <number>`: what to make, where, the milestones, what to ask; the comments on it, which are the discussion so far, printed with the task, their pictures saved with `console file <id>`; with its plan, the category, the goal it works towards (`console goal <id>` says what reaching it means, its category and the days it starts and is meant to be reached by) and the days it starts and is due, which the reports and the summary keep to. The pages it links to (`console doc <path>`) and the project's pack (`console skills` says where the pack is, what a client is told of it on connect, and every skill and document; `console skills <folder>` shows what a folder of it holds, `console skills --search <words>` what the words find in it; `console skill <path>` reads one whole through the console, its rules first, as an MCP client's model is given it, a private pack through the pack token the project holds, [ADR-0028](/docs/adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md), and a pack on the console's own machine from its directory, [ADR-0031](/docs/adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md); `console skill --file <file>` a file of it; a host that lists skills through a connection of its own loads them by their URI, which means nothing elsewhere for a pack on the console's machine) say the rest. |
+| The work | The task's body, read with `console task <number>`: what to make, where, the milestones, what to ask; the comments on it, which are the discussion so far, printed with the task, their pictures saved with `console file <id>`; with its plan, the category, the goal it works towards (`console goal <id>` says what reaching it means, its category and the days it starts and is meant to be reached by) and the days it starts and is due, which the reports and the summary keep to. The pages it links to (`console doc <path>`) and the project's pack (`console skills` says where the pack is, what a client is told of it on connect, and every skill and document; `console skills <folder>` shows what a folder of it holds, `console skills --search <words>` what the words find in it; `console skill <path>` reads one whole through the console, its rules first, as an MCP client's model is given it, a private pack through the pack token the project holds, [ADR-0028](/docs/adr/0028-the-console-reads-a-projects-pack-through-the-deployments-rest-api-with-a-pack-token-for-a-private-one.md), and a pack on the console's own machine from its directory, [ADR-0031](/docs/adr/0031-the-console-reads-a-pack-as-the-skillcdn-command-does-and-a-local-one-from-a-directory.md); `console skill --file <file>` a file of it, `console skills <file>` the outline of a document and `console skill --file <file> --offset <n> --limit <n>` one section of it, as a search or the outline names them; a host that lists skills through a connection of its own loads them by their URI, which means nothing elsewhere for a pack on the console's machine) say the rest. |
 | The rules | The workspace's, the console's own until an administrator writes the organization's, and this project's own when it has them: which skills to load first, where the work lives, the pages, what may be decided alone, how to report ([ADR-0023](/docs/adr/0023-the-rules-of-a-board-are-pages-the-workspace-and-its-projects-keep-read-first-by-every-agent.md)). `console take` prints them with the task, so they are read once, there; `console rules` reads them without taking, as when a task is still to be chosen. They hold over this skill's defaults where they differ. |
 
 ## Workflow
@@ -54,7 +56,7 @@ Told which task, go to phase 2: `console take` prints the rules of the board wit
 
 ### Phase 2: Take
 
-`console take <number>`. A run begins, and the command says its id and the task's on a line of their own (`run id:`, `task id:`; a task has a number for people and an id for the API, a run, a decision and a goal have ids alone, and every command that makes one prints it so, `--json` the whole answer; an id is read from there, never assumed): the task is in progress and the person's, and every report, hand-in, question and ending from here acts on this run. With another run of the person's open in the project, which `console take` says, each of those commands names the run: `--run <id>`. Taken by mistake, `console abandon` leaves it and the task stays as it was.
+`console take <number>`. A run begins, and the command says its id and the task's on a line of their own (`run id:`, `task id:`; a task has a number for people and an id for the API, a run, a decision and a goal have ids alone, and every command that makes one prints it so, `--json` the whole answer; an id is read from there, never assumed): the task is in progress and the person's, and every report, hand-in, question and ending from here acts on this run. With another run of the person's open in the project, which `console take` says, each of those commands names the run: `--run <id>`. Taken by mistake, `console abandon` leaves it and the task stays as it was. A run the board has not heard from for twelve hours (what the deployment sets), and that is not waiting for an answer, is ended by the board itself as abandoned (ADR-0041): report at the milestones, wait for a decision with `--wait` or come back for it, and, refused with `run.over` on a run ended that way, take the task again.
 
 ### Phase 3: Work, and report at the milestones
 
@@ -62,7 +64,7 @@ The work happens where it happens: in the repository, the document, the tool. At
 
 ### Phase 4: Ask when a person must decide
 
-A choice the body does not settle, a trade-off, a cost, a change of scope: `console ask "<question>" --option "<one>" --option "<another>" --body "<what they need to know>"`. The run waits for the answer; the command waits a minute and exits with `3` while it is still to come. Keep waiting with `console decision <id> --wait 100`, as often as needed, and meanwhile do only what does not depend on the answer. Act on the answer as given, which may be the person's own words rather than one of the options, marked as theirs; what was answered is not asked again. Once acted on, `console decision <id> --outcome "<what followed>"` makes the decision read as a record.
+A choice the body does not settle, a trade-off, a cost, a change of scope: `console ask "<question>" --option "<one>" --option "<another>" --body "<what they need to know>"`. The decision is for the person you work for, who finds it among their decisions; `--to <login>` addresses it to another person of the project when the task or the rules name who decides such things (ADR-0042). The run waits for the answer; the command waits a minute and exits with `3` while it is still to come. Keep waiting with `console decision <id> --wait 100`, as often as needed, and meanwhile do only what does not depend on the answer. Act on the answer as given, which may be the person's own words rather than one of the options, marked as theirs; what was answered is not asked again. An answer that reaches you anywhere but the board, in chat, in a comment, in the task changed, is written on the decision in the person's name first, `console answer <id> --option <n>|--own "<their words>" --note "<where and when they said it>"`, and acted on from there; a question the work overtook is answered the same way, with the person's word on it, however short. Once acted on, `console decision <id> --outcome "<what followed>"` makes the decision read as a record.
 
 ### Phase 5: Hand in
 

package/skills/working-the-board/references/terms.md

@@ -4,7 +4,7 @@
 - **Goal**: what the project works towards, on its roadmap, with the day it is meant to be reached by; its progress is its tasks.
 - **Category**: a kind of work, the workspace's word for it, by key.
 - **Run**: one agent at work on one task for one person, with its reports, what it handed in, and what it waits for.
-- **Decision**: a question with options, which a person answers on the board.
+- **Decision**: a choice that is a person's to make, kept as a record on the board: the question, the options, whom it is for ([ADR-0042](/docs/adr/0042-a-decision-is-addressed-to-a-person-its-raiser-unless-another-is-named.md)), the answer with who gave it and when, and what followed. It is answered on the board whoever decided it where: a person who answers in chat, in a meeting or by changing the task has decided, and the agent writes that answer down for them (`console answer`), so that the board shows as waiting only what is still open.
 - **Page**: a document of the project, Markdown at a path that does not change.
 - **Project**: a board of its own, with its members and its skills address.
 - **SkillCDN token**: what the console reads a private pack with, `pack-token` in the API and the command: a project's own, or the workspace's for the organization's pack, which a project reads when it names no address of its own; connected with a code a person approves at SkillCDN, or made there by hand, and shown to nobody.

package/src/api.ts

@@ -191,6 +191,7 @@ export {
   type RestMemberPatch,
   type RestMembers,
   type RestMePatch,
+  type RestMyDecisions,
   type RestOrganization,
   type RestPackConnect,
   type RestPackConnectStarted,
@@ -286,6 +287,7 @@ export {
   restMembersSchema,
   restMePatchSchema,
   restMeSchema,
+  restMyDecisionsSchema,
   restOrganizationSchema,
   restPackConnectSchema,
   restPackConnectStartedSchema,

package/src/cli/cli.ts

@@ -1172,8 +1172,37 @@ const skills: Command = async (args, io) => {
   return EXIT.ok;
 };
 
+/** The most characters one read of a file asks for: what the console's API allows on one page. */
+const MAX_FILE_LIMIT = 100_000;
+
+/** A count given as a flag, within its bounds, or nothing; anything else is not understood. */
+function countOf(
+  given: string | undefined,
+  name: string,
+  bounds: { readonly least: number; readonly most?: number },
+): number | undefined {
+  if (given === undefined) {
+    return undefined;
+  }
+  const count = Number(given);
+  if (
+    !Number.isInteger(count) ||
+    count < bounds.least ||
+    (bounds.most !== undefined && count > bounds.most)
+  ) {
+    const range =
+      bounds.most === undefined ? `${bounds.least} or more` : `${bounds.least} to ${bounds.most}`;
+    throw misuse(`Not a number for --${name}, ${range}: ${given}`);
+  }
+  return count;
+}
+
 const skill: Command = async (args, io) => {
-  const { values, positionals } = parse(args, { file: { type: "string" } });
+  const { values, positionals } = parse(args, {
+    file: { type: "string" },
+    offset: { type: "string" },
+    limit: { type: "string" },
+  });
   const file = text(values, "file");
   // A file is read by its own path from the repository's root; a skill's path beside it would be
   // ignored, which reads as if it mattered, so the two together are not understood.
@@ -1182,6 +1211,17 @@ const skill: Command = async (args, io) => {
       "Say one: console skill <path of its SKILL.md> for a skill, or console skill --file <path> for a file of the pack.",
     );
   }
+  // A section is a page of a file read as asked (SkillCDN 0.4): the flags mean nothing without one.
+  if (
+    file === undefined &&
+    (text(values, "offset") !== undefined || text(values, "limit") !== undefined)
+  ) {
+    throw misuse(
+      "--offset and --limit go with --file: console skill --file <path> [--offset <n>] [--limit <n>]",
+    );
+  }
+  const offset = countOf(text(values, "offset"), "offset", { least: 0 });
+  const limit = countOf(text(values, "limit"), "limit", { least: 1, most: MAX_FILE_LIMIT });
   const session = await open(io, values);
   const project = await session.project();
   const { listing, summary } = await packOf(project);
@@ -1189,6 +1229,16 @@ const skill: Command = async (args, io) => {
     answer(io, session, listing, () => formatSkills(listing, io.skillsDir));
     return EXIT.ok;
   }
+  if (file !== undefined && (offset !== undefined || limit !== undefined)) {
+    // One page as asked, the section a search or an outline named; the result says where the
+    // file continues, and asks for nothing.
+    const page = await project.skillFile(file, { offset, limit });
+    const section = page.read === null ? undefined : joinFile([page], summary, limit);
+    answer(io, session, { ...page, read: section === undefined ? null : bodyOfFile(section) }, () =>
+      formatSkillFile(page, section),
+    );
+    return EXIT.ok;
+  }
   if (file !== undefined) {
     // The file whole, page after page, as the console reads it from the pack.
     const pages: RestSkillFile[] = [];
@@ -1800,11 +1850,16 @@ const ask: Command = async (args, io) => {
     file: { type: "string" },
     run: { type: "string" },
     wait: { type: "string" },
+    to: { type: "string" },
   });
   const question = theOne(
     positionals,
     'Say the question: console ask "<question>" --option "<label>" --option "<label>"',
   );
+  const to = text(values, "to");
+  if (to === "none") {
+    throw misuse("Say whom the decision is for: --to <login|me>.");
+  }
   const options = texts(values, "option");
   if (options.length < MIN_OPTIONS || options.length > MAX_OPTIONS) {
     throw misuse(`Give ${MIN_OPTIONS} to ${MAX_OPTIONS} options, one --option each.`);
@@ -1814,21 +1869,58 @@ const ask: Command = async (args, io) => {
   const session = await open(io, values);
   const project = await session.project();
   const runId = await currentRun(project, values);
+  // Whom the decision is for (ADR-0042): the person the agent works for, unless --to names another.
+  const deciderId = await personIdOf(session, to);
   const raised = await project.raiseDecision({
     question,
     options: options.map((label) => ({ label })),
     runId,
     ...(body === undefined ? {} : { body }),
+    ...(typeof deciderId === "string" ? { deciderId } : {}),
   });
   // The id is printed before any waiting, so that a wait cut short loses nothing.
   io.stdout(
     session.json
       ? `${JSON.stringify(raised, null, 2)}\n`
-      : `Decision ${raised.id} raised on run ${runId}; the run waits for a person.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
+      : `Decision ${raised.id} raised on run ${runId}; the run waits for ${raised.decider.login}.\ndecision id: ${raised.id}\n${formatOptions(raised)}\n`,
   );
   return settle(io, session, project, raised, seconds, true);
 };
 
+/**
+ * Writes a person's answer on a decision, in their name through the agent (ADR-0021): the
+ * option they chose, or their own words, and a note about it, so that a choice made in chat
+ * or in passing reaches the record the run waits on.
+ */
+const answering: Command = async (args, io) => {
+  const { values, positionals } = parse(args, {
+    option: { type: "string" },
+    own: { type: "string" },
+    note: { type: "string" },
+    file: { type: "string" },
+  });
+  const id = theOne(
+    positionals,
+    'Say which decision: console answer <id> --option <n>|--own "<answer>" [--note <markdown>|--file <path>]',
+  );
+  const option = text(values, "option");
+  const own = text(values, "own");
+  if ((option === undefined) === (own === undefined)) {
+    throw misuse(
+      'Say the option chosen, --option <n>, or the person\'s own answer, --own "<words>": one of the two.',
+    );
+  }
+  const note = await bodyOf(io, values, text(values, "note"));
+  const session = await open(io, values);
+  const project = await session.project();
+  const answered = await project.answerDecision(id, {
+    ...(own === undefined ? { option } : { own }),
+    ...(note === undefined ? {} : { note }),
+  });
+  answer(io, session, answered, () => formatDecision(answered));
+  return EXIT.ok;
+};
+
 const decision: Command = async (args, io) => {
   const { values, positionals } = parse(args, {
     wait: { type: "string" },
@@ -2139,14 +2231,37 @@ const goal: Command = async (args, io) => {
 };
 
 const decisions: Command = async (args, io) => {
-  const { values } = parse(args, { open: { type: "boolean" }, ...PAGE_OPTIONS }, false);
+  const { values } = parse(
+    args,
+    {
+      open: { type: "boolean" },
+      mine: { type: "boolean" },
+      raised: { type: "boolean" },
+      ...PAGE_OPTIONS,
+    },
+    false,
+  );
   const page = pageOf(values);
   const session = await open(io, values);
+  const open_ = on(values, "open") ? { open: true } : {};
+  if (on(values, "mine") || on(values, "raised")) {
+    // One's own across the projects (ADR-0042), addressed to the person or raised by them for
+    // someone else: the waiting first, each with its project's key.
+    const raised = on(values, "raised");
+    const found = await session.client.myDecisions({ ...open_, raised, ...page });
+    answer(io, session, found, () =>
+      found.items.length === 0
+        ? raised
+          ? "No decisions you asked of others."
+          : "No decisions of yours."
+        : found.items
+            .map(({ project, decision }) => `${project.key}  ${formatDecisionLine(decision)}`)
+            .join("\n") + formatMore(found.more, page.limit, page.offset),
+    );
+    return EXIT.ok;
+  }
   const project = await session.project();
-  const found = await project.decisions({
-    ...(on(values, "open") ? { open: true } : {}),
-    ...page,
-  });
+  const found = await project.decisions({ ...open_, ...page });
   answer(io, session, found, () =>
     found.items.length === 0
       ? "No decisions."
@@ -2869,6 +2984,7 @@ const COMMANDS: Readonly<Record<string, Command>> = {
   comment,
   file,
   ask,
+  answer: answering,
   decision,
   decisions,
   finish: ending("finished"),

package/src/cli/format.ts

@@ -386,7 +386,10 @@ export function formatWork(work: RestWork): string {
       lines.push(`  ${project.key}  ${formatTaskLine(task)}`);
     }
   }
-  lines.push("", work.decisions.length === 0 ? "decisions waiting: none" : "decisions waiting:");
+  lines.push(
+    "",
+    work.decisions.length === 0 ? "decisions waiting for you: none" : "decisions waiting for you:",
+  );
   for (const { project, decision } of work.decisions) {
     lines.push(`  ${project.key}  ${formatDecisionLine(decision)}`);
   }
@@ -404,9 +407,13 @@ export function formatPersonWork(person: RestPerson, work: RestPersonWork): stri
   ].join("\n");
 }
 
+/** Whom a decision is for, where that is not the one who asked (ADR-0042). */
+const addressed = (decision: RestDecision): string =>
+  decision.decider.id === decision.raisedBy.id ? "" : `, for ${decision.decider.login}`;
+
 export function formatDecisionLine(decision: RestDecision): string {
   const state = decision.answer === null ? "waiting" : `answered ${decision.answer.option}`;
-  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)})`;
+  return `${decision.id}  ${state}  ${decision.question}  (asked by ${asker(decision)}${addressed(decision)})`;
 }
 
 /** The options, one a line; the person's own answer, when they wrote one, is the last and says so. */
@@ -423,7 +430,7 @@ export function formatOptions(decision: RestDecision): string {
 export function formatAnswer(decision: RestDecision): string {
   const { answer } = decision;
   if (answer === null) {
-    return "waits for a person.";
+    return `waits for ${decision.decider.login}.`;
   }
   const chosen = decision.options.find((option) => option.id === answer.option);
   const lines = [
@@ -438,7 +445,7 @@ export function formatAnswer(decision: RestDecision): string {
 export function formatDecision(decision: RestDecision): string {
   const lines = [
     `decision ${decision.id}: ${decision.question}`,
-    `asked by ${asker(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
+    `asked by ${asker(decision)}${addressed(decision)}${decision.taskNumber === null ? "" : `, about task #${decision.taskNumber}`}`,
   ];
   if (decision.body.trim().length > 0) {
     lines.push("", decision.body.trimEnd());