@nuucognition/ops-cli 0.0.0-stage → 0.1.0-dev.1

package/README.md

@@ -1,3 +1,915 @@
-# Temporary Holding Version
+# ops — the NUU Operations CLI for agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`ops` gives an agent full access to the NUU Operations web app through the
+**agent gateway** ((Task) 297). It uses the nuu CLI credential. The gateway
+sends each op to the same public Convex function that the web app calls, so
+access checks, validators, dependency gates, the Waybill log, and
+notifications are the same as in the UI.
+
+The CLI is agent-first:
+
+- Every command is `ops <noun> <verb>`.
+- Every command takes `--json`. Then stdout holds exactly one JSON document.
+- Text output is short and stable, and always shows IDs.
+- Errors go to stderr as `error <code>: <message>`, then indented hints that
+  name the next step, with a non-zero exit code. With `--json`, stderr holds
+  exactly one JSON document `{"error": {code, message, exitCode, hints, ...}}`
+  instead, and stdout stays empty.
+- A usage error names the help command (`ops <noun> <verb> --help`). An extra
+  argument (for example an unquoted comment body) is a usage error. A command
+  group with no subcommand (`ops task`) is a usage error that lists the
+  subcommands; it prints no help text on stderr.
+- With `DEBUG=1`, the stack trace follows the error lines; with `--json`, it is
+  the `stack` field of the JSON error document.
+- An op that a deployment does not have yet (for example a new op on dev only)
+  fails with `agent_unknown_operation`, and the message says that the op is
+  not deployed there yet.
+- Wherever a command needs a record, it takes an ID, an address, a web URL,
+  a title, or a path (`"Alpha › v1 › Backend"`).
+- Every command prints the address of each thing that it shows or makes
+  (`@v1/<org>/<kind>/<key>#ops`). An agent keeps the address, not the title.
+
+## The model of Ops
+
+The revamp of ops-command-1021 (2026-10-21) gives Ops this model:
+
+```
+org
+└── project                         (hidden context)
+    ├── section (role backlog)      the backlog of the project
+    ├── section                     a list of tasks with no deliverable yet
+    ├── deliverable                 done when a person marks it done
+    │   └── section ─ task ─ subtask ─ subtask …   (a tree of at most 6 levels)
+    └── deployment (live, paused, retired; a free version label)
+        └── section (role inbox)    the tasks that come up while it runs
+section (role backlog) of the org   the master backlog
+```
+
+- A **section** holds tasks. It has one home: a deliverable, a project, a
+  deployment, or the org. A section is done when all its root tasks are
+  done. The former word is **subsection**: `ops subsection …` and
+  `--subsection` still work, hidden.
+- **No closer and no "Delivered" task.** `ops deliverable done|reopen`.
+- **The backlog is a section** (role `backlog`). The backlog folders of
+  before the revamp became sections (Main became the backlog, Queue a section
+  with the role `queue`). `ops folder` stays hidden for old callers.
+- **Subtasks** are full tasks with a parent. A list shows root tasks with a
+  count (`1/3 subtasks`). A move takes the subtree. A delete of a task with
+  subtasks needs `--with-subtasks`.
+- **Deployments are abstract.** A live deployment has an **inbox**. Inbox
+  tasks have a tag: `feedback`, `hotfix`, `ongoing`, or `recurring`. A check
+  schedule (`ops deployment schedule`) makes a task "Check <deployment>" in
+  the inbox each period. `ops deployment start-deliverable` moves inbox tasks
+  into a new deliverable that comes from the deployment. The version chain is
+  deprecated.
+- **Hidden context.** Projects, deliverables, sections, and deployments have
+  a Markdown context (`ops <kind> context set|show`) that the page does not
+  show. Search and the route decision read it.
+- **The map and the route.** `ops headers` prints every place of the org
+  with its address. `ops route "<text>"` gives the ranked places for a text
+  (with the decision model Jev when Smart suggestions are on, else the text
+  match). `ops task create --route` uses the top place.
+
+## A first session for an agent
+
+```bash
+ops whoami                                          # the user, the data mode, the active org
+ops headers --project Alpha                         # the places of a project, with addresses
+ops task context <task>                             # read a task before you work on it
+ops route "Fix the login bug on Safari"             # where a new task belongs
+ops task create "Fix the login bug on Safari" --route
+ops task create "Write the tests" --parent <task>   # a subtask
+ops task move <task> --to section:"Alpha › v1 › Backend"
+ops task done <task>
+ops deployment inbox Production --open              # what came up while it runs
+ops deliverable done "Alpha › v1 launch"            # a person decides; ask first
+```
+
+Keep the address that a command prints (`@v1/<org>/<kind>/<key>#ops`) and
+name the record by it in the next command: an address never needs a scope
+and never matches two records.
+
+## Install
+
+### From npm (the published package)
+
+```bash
+npm install -g @nuucognition/ops-cli   # the `ops` command: the prod build, prod data
+ops --version                          # the version of the package
+nuu login                              # or `flint login`, or `ops login`: one NUU sign-in for all three
+ops whoami
+```
+
+The package needs Node.js 24 or newer. On an older Node.js, `ops` prints one
+refusal (`error node_too_old`) and exits 1. The package has one command,
+`ops`. It is the prod build, so it always uses prod data (see Modes). The
+bundle (`dist/index.js`) holds every package that the CLI uses, so the
+package has no runtime dependency. An installed package has no source, so
+the launcher runs no check against a source checkout. `RELEASE.md` tells how
+to publish a new version.
+
+### From the monorepo (ndv)
+
+The package is `@nuucognition/ops-cli` in `apps/cli-ops`. ndv builds and
+links it:
+
+```bash
+ndv scan
+ndv use ops dev        # builds dist-dev/ and links ~/.nuucognition/ndv/bin/ops -> bin/ops.js
+ndv build ops prod     # builds dist/ without a change to the active link
+```
+
+ndv names its link after the tool (`ops`) in both profiles. After
+`ndv use ops dev`, the `ops` command on PATH runs the **dev build**. After
+`ndv use ops prod`, it runs the prod build. Inside the monorepo, pnpm also
+links both bins (`ops` → `bin/ops-prod.js`, `ops-dev` → `bin/ops.js`). Do not
+expect `ops-dev` on PATH outside the monorepo. The published package has only
+`ops`.
+
+### Before the first write: which build and which data
+
+**The `ops` on PATH can be the prod build.** A prod build always uses prod
+data and ignores `OPS_DATA_MODE`: `OPS_DATA_MODE=dev ops task create …` with a
+prod build **writes to prod data**. So, before the first write:
+
+1. Run `ops mode` and read two lines: `build mode` (`prod` or `dev`) and
+   `data mode`. Write only when the data mode is the data that the work needs.
+2. Check that the build has the revamp: `ops --help` lists `headers`,
+   `route`, `search`, and `section`. When it does not, the build is of before
+   the revamp.
+
+For DEV data, run the dev launcher of the checkout:
+
+```bash
+OPS_DATA_MODE=dev node "<monorepo>/apps/cli-ops/bin/ops.js" mode    # build mode dev, data mode dev (env)
+OPS_DATA_MODE=dev node "<monorepo>/apps/cli-ops/bin/ops.js" headers --org me
+```
+
+The dev launcher (`bin/ops.js`) runs `dist-dev/`. When `dist-dev/` is older
+than the source of this checkout (`src`, `bin`, `package.json`, also
+uncommitted changes), it runs the TypeScript source and prints one note on
+stderr (`note: the ops-dev bundle … is older than its source`; no note with
+`--json`). It also runs the source when there is no build, or with
+`OPS_CLI_FORCE_SOURCE=1`. The prod launcher (`bin/ops-prod.js`) always runs
+`dist/`; when `dist/` is older than the source, it prints one warning on
+stderr (`warning: the ops bundle … is older than the source`). Rebuild with
+`ndv build ops` (dev) or `ndv build ops prod`. `OPS_CLI_NO_STALE_CHECK=1`
+turns the check off.
+
+## Modes
+
+`ops` follows the Strike rule. There are two modes, and they always move
+together:
+
+| | Build mode | Data mode |
+|---|---|---|
+| Says | which code runs | which deployment and which credential |
+| Prod build (`bin/ops-prod.js`, `dist/`) | prod | always prod |
+| Dev build (`bin/ops.js`, `dist-dev/`, source) | dev | dev by default |
+
+| Data mode | Gateway site | Credential | Web links |
+|---|---|---|---|
+| dev | `https://next-dalmatian-912.convex.site` | `~/.nuucognition/auth.local.json` | `http://localhost:3088` |
+| prod | `https://acoustic-weasel-248.convex.site` | `~/.nuucognition/auth.json` | `https://ops.nuucognition.com` |
+
+A dev build reads its data mode in this order:
+
+1. `OPS_DATA_MODE=dev|prod` (one run; a prod build ignores it).
+2. `~/.nuucognition/ops-dev-data.json` (set with `ops mode dev|prod`).
+3. `dev`.
+
+A test run (`node --test`) stays on dev data unless `OPS_DATA_MODE` says
+otherwise. A prod build reads neither the variable nor the file.
+
+```bash
+ops mode                 # build mode, data mode, site, credential file
+ops mode prod            # dev build only: use prod data from now on
+ops mode dev             # dev build only: back to dev data
+OPS_DATA_MODE=prod node apps/cli-ops/bin/ops.js whoami   # the dev launcher, prod data, this run only
+```
+
+## Auth
+
+`ops` uses the one NUU sign-in of this machine. It reads the same credential
+files as the flint CLI and the nuu CLI, in the NUU home (`~/.nuucognition`,
+or `$NUU_HOME`):
+
+| Data mode | Credential | Account service | Sign in with |
+|---|---|---|---|
+| prod | `~/.nuucognition/auth.json` | `https://account.nuucognition.com` | `nuu login`, `flint login`, or `ops login` |
+| dev | `~/.nuucognition/auth.local.json` | `http://localhost:3000` | a dev login, or `ops login` of a dev build in dev data |
+
+So a machine that ran `nuu login` or `flint login` needs no other step for
+the published `ops`. The code is
+`requireValidAuth(resolveEnv("ops", { mode: dataMode() }))` of cli-core.
+`ops login` runs the browser sign-in of cli-core (the same flow as
+`flint login`) and writes the credential file of the current data mode.
+When the short session token expires, `ops` refreshes it through the
+account service of that mode and writes the new token to the same file.
+The format of the file is the format of cli-core. The CLI never prints the
+token.
+
+```bash
+ops login                # browser sign-in for the current data mode (a person only)
+ops whoami               # user, email, data mode, active org
+ops mode                 # the credential file and who is signed in
+```
+
+When the credential is missing or does not refresh, a command fails with
+`error auth_required: …` and exit code 3, and names the login command. An
+agent cannot sign in: it asks the operator to run `nuu login` (or
+`ops login`).
+
+## Orgs
+
+Every command works in one org. The active org is:
+
+1. `--org <slug|name|me>` on the command line,
+2. else the stored default of the data mode (`~/.nuucognition/ops/<mode>.json`),
+3. else the personal workspace (its slug is your Clerk user ID).
+
+A command on an existing record (given by ID or URL) works in the record's
+own org. It refuses a `--org` that names another org (`org_mismatch`).
+
+## References
+
+A record argument takes any of these forms:
+
+| Form | Example | How it resolves |
+|---|---|---|
+| Convex ID | `k57b2m4x9q8r7t6y5u4i3o2p1a0s9d8f` | `agent.resolve` (kind, org, title, breadcrumb) |
+| Web URL | `https://ops.nuucognition.com/me/tasks/<t>`, `…/projects/<p>/deliverables/<d>?task=<t>` | the ID in the path or query, then `agent.resolve` |
+| Ops address | `@v1/acme/task/<id>#ops`, `@v1/acme/task.dev/<id>#ops`, `@v1/acme/section/<id>#ops`, `@v1/acme/deployment/<id>#ops`, `@v1/acme/project/alpha#ops`, `@v1/acme/project/alpha/deliverable/v1#ops`, `@v1/acme/taskgroup/<id>#ops`, `@v1/acme/notepad/<id>#ops` | `agent.resolve` (the object that the address names now); other text that starts with `@` is a title |
+| Title | `"Write the docs"` | `agent.searchTasks` for tasks; the headers of the org (`headers.forOrg`) for projects, deliverables, sections, and deployments; the list queries for the other kinds |
+| Path | `"Alpha › v1 › Backend"`, `"Alpha > v1"`, `"Alpha / Backlog"` | the path of a place in the headers (`›`, `>`, and `/` are the same separator) |
+
+A title matches in this order: an exact title (any case), then an exact
+path, then a unique ID prefix of 4 or more characters (the short IDs of
+`plan show`), then a unique partial title, then a unique partial path. When
+more than one record matches, the command fails with `error <kind>_ambiguous`
+(exit 2) and lists each candidate with its ID and its path. Pass the ID or
+a longer path. Never guess between candidates.
+
+A step title needs `--plan`. A deployment name needs `--project` only on a
+deployment of Ops of before the revamp (the headers name every deployment).
+An ID, URL, or address never needs a scope.
+
+`agent.resolve` reads each kind of record: a project, a deliverable, a
+section, a task, a task group, a backlog folder, a plan, a step, a deadline,
+a day label, a deployment, a blocker, and a notepad (a blocker and a notepad
+from fleet ops-cli-publish-1023; a deleted notepad, and a personal notepad of
+another person, are not found). Five kinds have an address row: a project, a
+deliverable, a task, a task group, and a notepad (the display address is the
+alias, else the id form). A section and a deployment have the id form only.
+A plan, a step, a deadline, a day label, and a blocker have no address: use
+the ID. `ops address <record>` prints the address of a record, and the
+record that an address names now.
+
+### Places (`--to` of `task move`)
+
+| Form | The place |
+|---|---|
+| `section:<ref>` | the section |
+| `project:<ref>` | the backlog section of the project (made on first need) |
+| `deliverable:<ref>` | the first open section of the deliverable (made when none) |
+| `deployment:<ref>` | the inbox section of the deployment |
+| `parent:<task>` (or `task:<task>`) | under the task, as a subtask |
+| `backlog` | the backlog section of the project of the task |
+| `master` | the backlog section of the org (the master backlog) |
+| `unplaced` | no home |
+| an ID, a URL, or an address | the place of that kind |
+| a bare title or path | a place of any kind in the headers; two matches fail with `place_ambiguous` and their `kind:<id>` forms |
+
+A **link spec** (deadline links, step links, title links, blocker links) is
+`kind:ref`, a URL, an address, or an ID: `task:"Write docs"`, `step:<id>`,
+`project:Alpha`, `https://…/plans/<id>`, `@v1/acme/task/<id>#ops`. A title
+needs the kind prefix.
+
+## Output and errors
+
+```bash
+ops task list --json | jq '.[0]._id'
+ops task show "Write docs"
+```
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | The gateway or the record refused the operation |
+| 2 | Usage error, ambiguous reference, or a guard refused (for example `--yes` missing) |
+| 3 | Not signed in (`auth_required`, `unauthenticated`) |
+| 4 | Network error |
+
+Gateway codes pass through: `unauthenticated`, `org_unauthorized`,
+`org_frozen`, `agent_unknown_operation`, `agent_wrong_endpoint`,
+`agent_invalid_input`, `*_not_found`, `*_conflict`, `waybill_stale`,
+`waybill_conflict`. Client codes include `usage`, `auth_required`,
+`network`, `bad_response`, `<kind>_ambiguous`, `<kind>_not_found`,
+`wrong_kind`, `org_mismatch`, `undo_state_changed`, `undo_conflict`,
+`expect_required`, `nothing_to_undo`, `nothing_to_redo`,
+`reorder_anchor_outside`, `position_unknown`, `confirm_required`,
+`place_ambiguous`, `place_not_found`, `deployment_no_inbox`. Codes of the
+revamp from the service: `task_has_subtasks` (a delete needs
+`--with-subtasks`), `subtask_too_deep` (6 levels), `subtask_cycle`.
+
+An op that a deployment of Ops does not have yet fails with
+`agent_unknown_operation` and names the deploy. Where a former op can do the
+work (a section of a deliverable, a move to a section or a backlog), the
+command uses it on such a deployment.
+
+The guards exit 2: `confirm_required` (a delete that removes other records
+or cannot be undone needs `--yes`: project, deliverable, section, deployment, plan, blocker),
+`expect_required` and `undo_state_changed` (a replay without the right
+`--expect <seq>`). A list with no rows prints one `no <things>` line; with
+`--json` it prints `[]`.
+
+## Command reference
+
+Global options (on every command): `--json`, `--org <slug|name|me>`.
+Dates take `YYYY-MM-DD`, `today`, `tomorrow`, or an offset such as `+3d` or
+`-1w`. Where a value can be cleared, pass `none`. A text argument of `-`
+reads stdin.
+
+### Session and raw access
+
+| Command | Example |
+|---|---|
+| `ops login [--verbose]` | `ops login` |
+| `ops whoami` | `ops whoami --json` |
+| `ops mode [dev\|prod]` | `ops mode prod` |
+| `ops ops [--area <area\|module>]` — the gateway manifest (no credential needed); `--area` matches the manifest area (`history`) or the op module (`waybill`) | `ops ops --area waybill` |
+| `ops call <op> [json\|-] [--query\|--mutation\|--action] [--inject-org]` — any allowlisted op; always prints JSON; the manifest gives the kind (`--action` is for `route.suggest`) | `ops call plans.listLite '{}' --inject-org` |
+
+### headers, route, search
+
+| Command | Example |
+|---|---|
+| `ops headers [--project <p>] [--archived]` — the map of the org (`headers.forOrg`): each project, its sections, its deliverables and their sections, its deployments and their sections, then the sections and deployments of the org; each with its id, role, done mark, and address | `ops headers --project Alpha` |
+| `ops route <text> [--want task\|idea\|any] [--no-smart] [--limit 1-8]` — the route decision: `route.suggest` (an action: Jev with a limit of 1.5 s, else the text match), or with `--no-smart` the query twin `route.candidates`; each line: the score, the `kind:<id>` form, the path, the reason, and the address; `--json`: `{orgSlug, op, model, latencyMs, intent, candidates[]}`, where `op` is the op that answered (`route.suggest` or `route.candidates`) and each candidate has `place {kind, id, title, path}`, `score`, `confidence` (the confidence of the decision model, when it gave one), `reason`, and `address`. **A score below 0.3, or a reason that is only "A recent project", means that no place fits**: name a place, or make one (see the skill `create_task` of the Ops shard) | `ops route "Fix the login bug on Safari"` |
+| `ops search <text> [--type task,section,deliverable,project,deployment] [--include-done] [--limit 1-50]` — `opsSearch.search`: tasks and places in one list, each with its path and address | `ops search billing --type section,deliverable` |
+| `ops address <record> [--kind project\|deliverable\|section\|task\|deployment\|taskgroup\|notepad\|plan\|step\|deadline\|blocker]` — the address of a record: `addresses.of` gives the display address, the id address, the `nuu://ops/<type>/<id>` URI, and `canRename` (the owner rights) of a project, a deliverable, a task, a task group, or a notepad; a section and a deployment have the id form (from the headers); the other kinds print `none`. For an address, `addresses.find` sets `moved` when the text is an old alias or an old form. A title needs `--kind`; `--json`: `{kind, id, orgSlug, title, address, idAddress, uri, canRename, moved}` | `ops address @v1/acme/project/alpha#ops` |
+| `ops people search <text> [--limit 1-50]` and `ops people show <@handle\|email\|user_…>` — `people.search`, `people.getByHandle`, `people.getByEmail`, and `people.get` in the scope of the active org: the name, the handle, the email, and the Clerk user id of each person that the caller can see (the personal workspace shows only the caller); none is `person_not_found`. `ops member list` gives the `users` rows (the owners and assignees of tasks) | `ops people search ada` |
+
+### org, member
+
+| Command | Example |
+|---|---|
+| `ops org list` — `*` marks the active org | `ops org list` |
+| `ops org use <slug\|name\|me>` — the default of this data mode | `ops org use "NUU Cognition"` |
+| `ops org show [org]` | `ops org show me` |
+| `ops member list` — members of the active org, for assignees | `ops member list --json` |
+
+### project
+
+| Command | Example |
+|---|---|
+| `ops project list [--status active\|paused\|archived\|all]` — each with its address | `ops project list --status active` |
+| `ops project show <project>` — its sections (the backlog first), its deliverables and deployments with their sections, and the root tasks, each with its address; a deployment of before the revamp gives the former snapshot (deliverables, sections, the backlog folders) | `ops project show Alpha` |
+| `ops project create <name> [--description] [--kind project\|operation] [--start] [--end] [--next-update] [--context <md>] [--deployment <d>]` — `--deployment` is the deployment that the project ships to (`originDeploymentId`, a link: the two records stay independent) | `ops project create "Alpha" --next-update +7d` |
+| `ops project update <project> [--name] [--description] [--next-update <date\|none>] [--status] [--kind] [--start <date\|none>] [--end <date\|none>] [--deployment <d\|none>]` | `ops project update Alpha --status paused` |
+| `ops project link <project> <uri...>` / `ops project unlink <project> <uri>` — the linked things of a project: NUU Connect URIs (`nuu://<app>/<type>/<id>`) of other NUU apps (`projectLinks.link`, `projectLinks.unlink`); each URI is stored once, at most 50; a bad URI refuses with `connect_bad_request`; `--json` gives `{id,connectRefs}` | `ops project link Alpha nuu://chat/thread/abc` |
+| `ops project context show <project>` / `ops project context set <project> (<md\|-> \| --file <path> \| --clear)` — `projects.setContext` | `ops project context set Alpha --file context.md` |
+| `ops project delete <project> --yes` — deletes everything in it; only an owner or an admin of the org (in the personal workspace: its person) can delete it; an org member gets `owner-only`, and then archives it (`--status archived`) | `ops project delete Alpha --yes` |
+
+### deliverable
+
+| Command | Example |
+|---|---|
+| `ops deliverable list [--project <project>] [--open]` — each with its done mark and address | `ops deliverable list --project Alpha --open` |
+| `ops deliverable show <deliverable> [--project]` — the done mark, the deployment it ships to and comes from, its sections and their root tasks | `ops deliverable show "Alpha › v1 launch"` |
+| `ops deliverable status (<deliverable> [--project <p>] \| --project <p>)` — the derived status (`open`, `in-progress`, `blocked`, `completed`) from `deliverableStatus.forDeliverable`, with the status of each section (`blocked`, `ready`, `in-progress`, `done`) and the done upstream sections; `--project` alone gives each deliverable of the project with its status (`deliverableStatus.forProject`) and its last activity (`deliverables.lastActivityForProject`); `partial: true` when the read budget stopped a read | `ops deliverable status "Alpha › v1 launch" --json` |
+| `ops deliverable create <title> --project <project> [--due <date>] [--section <title>] [--deployment <d>] [--context <md>]` — no closer and no task; `--section` adds a first section | `ops deliverable create "v1 launch" --project Alpha --section Backend` |
+| `ops deliverable update <deliverable> [--title] [--deployment <d\|none>] [--from-deployment <d\|none>]` — `deliverables.setDeployment` | `ops deliverable update "v1.1" --deployment Production` |
+| `ops deliverable done <deliverable>` / `ops deliverable reopen <deliverable>` — `deliverables.setDone`: a person decides; the sections do not | `ops deliverable done "Alpha › v1 launch"` |
+| `ops deliverable rename <deliverable> <title>` | `ops deliverable rename "v1 launch" "v1.0 launch"` |
+| `ops deliverable context show\|set <deliverable> …` — `deliverables.setContext` | `ops deliverable context set "v1 launch" "The first public release"` |
+| `ops deliverable delete <deliverable> --yes` — deletes its sections and tasks; refuses without `--yes`; only an owner or an admin of the org can delete it (an org member gets `owner-only`) | `ops deliverable delete "v1.0 launch" --yes` |
+| `ops deliverable flint set <deliverable> <address> [--flint-id <uuid\|none>] [--project]` — the one Flint place (`deliverables.setFlintPlace`); `deliverable show` prints it | `ops deliverable flint set "v1 launch" @v1//flint/nuu-operations` |
+| `ops deliverable flint clear <deliverable> [--project]` — removes the address and the id | `ops deliverable flint clear "v1 launch"` |
+
+### section
+
+`ops subsection …` is a hidden alias of `ops section …`.
+
+| Command | Example |
+|---|---|
+| `ops section list [--project <p> \| --deliverable <d> \| --deployment <d>] [--archived]` — `--project`: grouped by home (`sections.listForProject`); no scope: every section of the org with its path | `ops section list --project Alpha` |
+| `ops section show <section> [--project\|--deliverable\|--deployment]` — the home, the address, the web link, and the root tasks with their subtask counts (`sections.get`, `sections.tasks`) | `ops section show "Alpha › v1 › Backend"` |
+| `ops section create <title> (--project <p> \| --deliverable <d> \| --deployment <d> \| --org-wide) [--after <section>] [--context <md>] [--due <date>]` — `sections.create`; `--org-wide` is a section of the org (`--org` picks the org) | `ops section create Ideas --project Alpha` |
+| `ops section update <section> [--title] [--due <date\|none>]` | `ops section update Backend --due none` |
+| `ops section move <section> --to <project:<p>\|deliverable:<d>\|deployment:<d>\|org>` — `sections.moveHome`; the tasks go with it; a section with a role does not move | `ops section move Ideas --to deliverable:"Alpha › v2"` |
+| `ops section reorder <section> (--before <s>\|--after <s>\|--top\|--bottom)` — inside its home (`sections.reorder` takes every section of the home) | `ops section reorder Backend --top` |
+| `ops section deps set\|add\|remove <section> [deps...]` — the sections it comes after | `ops section deps set QA Backend Frontend` |
+| `ops section priority <section> on\|off` | `ops section priority Backend on` |
+| `ops section archive\|unarchive <sections...>` — `sections.archive` | `ops section archive Backend` |
+| `ops section context show\|set <section> …` — `sections.update` | `ops section context set Backend "The API and the queue"` |
+| `ops section delete <section> --yes` — deletes its tasks; refuses without `--yes` | `ops section delete Backend --yes` |
+| `ops section to-task <section> [--into <section>]` — an empty section becomes a task | `ops section to-task "Tiny fix"` |
+
+### task
+
+| Command | Example |
+|---|---|
+| `ops task list [--project \| --deliverable \| --section \| --deployment \| --master \| --mine [--all-orgs]] [--backlog] [--status open\|todo\|doing\|done\|all] [--priority <p\|none>] [--owner <me\|member\|none>] [--type <type>] [--stage <stage>] [--limit n]` — root tasks, each with its place and address; `--section` keeps the order of the section and gives the subtask counts (`sections.tasks`); `--deployment` lists the inbox (`deployments.inbox`); default `--status open`; more than one scope flag is a usage error | `ops task list --section "Alpha › v1 › Backend" --status all` |
+| `ops task list --all [--type <type>] [--stage <stage>] [--status …] [--limit n]` — every task of the org, placed and unplaced, newest first, as task summaries (address, type, stage, home label); `--limit` is the total (default 200) | `ops task list --all --type task.dev --stage reviewed --json` |
+| `ops task list --unplaced [--type <type>] [--stage <stage>]` — the tasks with no home; when the tasks need more bytes than one read (`task_read_too_large`), the CLI reads the pages of `tasks.listAllPage`; a page that is not the last and does not move the cursor stops the list (`pagination_stalled`, exit 1, no rows) | `ops task list --unplaced` |
+| `ops task show <task>` — also the address, the parent, the subtasks (the tree with the done count; `--json`: `subtasks`), the type and the stage, the outcome, the fields, the lineage, the task groups, the related links, the attachments, and the stage history; when the incoming lineage stops at its byte budget, `--json` has `linksCut: true` and the text says so; a task with a Flint task note gives the lines `note` (the label, else the address) and `note link` (the open link), and `--json` has `note`, `noteLabel`, and `noteUrl` at the top (each `null` when the task has no note) | `ops task show @v1/test/task.dev/<id>#ops` |
+| `ops task search <query> [--limit 1-100]` | `ops task search docs --limit 5` |
+| `ops task create <title> [--section <s> \| --project <p> \| --deliverable <d> \| --deployment <d> \| --parent <task> \| --route [text] \| --master \| --unplaced] [--tag feedback\|hotfix\|ongoing\|recurring] [--every day\|week\|month] [--type <type> [--stage <stage>]] [--repo <name>] [--note <address> [--note-label <text>]] [--body <md\|-> \| --body-file <path>] [--priority low\|medium\|high\|urgent] [--assign <me\|member>] [--top]` — default: the master backlog, at the end; `--project` is its backlog section, `--deliverable` its first open section, `--deployment` its inbox, `--parent` a subtask; `--route` asks `route.suggest` with the text (default: the title) and prints the place, the score, and the reason; `--stage` is the first stage of a typed task (default: the first stage of the type; an unknown stage refuses with `task_stage_unknown`); the output gives the stored title (a trailing digit of the title is the rarity: "Fix login 1" is stored as "Fix login"), the address, and the section | `ops task create "Login fails on Safari" --deployment Production --tag hotfix` |
+| `ops task update <task> [--title] [--body <md\|-> \| --body-file <path>] [--priority <p\|none>] [--assign <member\|none>] [--rarity <1-7\|none>] [--tag <tag\|none>] [--every day\|week\|month\|none]` — `--tag` and `--every` need `tasks.update` with `tag` and `recurrence` (MODEL; a deployment without them refuses with `agent_invalid_input`) | `ops task update "Write docs" --body-file notes.md` |
+| `ops task start <task>` — doing | `ops task start "Write docs"` |
+| `ops task done <task>` — the same as `close` with the outcome `completed` | `ops task done "Write docs"` |
+| `ops task reopen <task>` — doing; the outcome goes, the stage stays | `ops task reopen "Write docs"` |
+| `ops task move <tasks...> --to <place> [--priority <p\|none>]` — one task: `tasks.move`; more tasks: `tasks.moveMany`; each takes its subtree; the places are in [Places](#places---to-of-task-move); the former `--subsection`, `--backlog`, and `--folder` still work, hidden | `ops task move <a> <b> --to section:"Alpha › v1 › Backend"` |
+| `ops task reorder <task> (--before <t>\|--after <t>\|--top\|--bottom)` | `ops task reorder "Write docs" --after "Draft outline"` |
+| `ops task delete <task> [--with-subtasks]` — the service refuses a task with subtasks without the flag (`task_has_subtasks`) | `ops task delete "Write docs"` |
+| `ops task to-section <task> [--deliverable <d>]` — `to-subsection` is its former name | `ops task to-section "Big item" --deliverable "v1 launch"` |
+
+#### Subtasks and the task map
+
+| Command | Example |
+|---|---|
+| `ops task subtask add <parent> <title> [--body <md\|-> \| --body-file <path>]` — `subtasks.create`; it gets the home of the root task | `ops task subtask add <taskId> "Write the tests"` |
+| `ops task subtask list <task>` — the subtree with the done count (`subtasks.tree`; cut at 200 tasks) | `ops task subtask list <taskId>` |
+| `ops task subtask move <task> (--under <parent> \| --root) [--index n]` — `subtasks.reparent`; `--root`: a root task in the home of its old root | `ops task subtask move <taskId> --under <parentId>` |
+| `ops task subtask reorder <task> --index n` — its place among its siblings (0 is first) | `ops task subtask reorder <taskId> --index 0` |
+| `ops task subtask indent\|outdent <task>` — under the sibling above it, or one level up | `ops task subtask outdent <taskId>` |
+| `ops task map <task>` — `taskMap.get`: the root and the subtree, the home (project, deliverable, deployment, section), the task groups with their members, the lineage (split, merged, continues, after, before), the related links, each with its address, and the web page of the map | `ops task map <taskId> --json` |
+
+A task order bucket is one section **and** one priority band (before the
+revamp: one subsection, or one backlog folder; no folder is Main). `tasks.reorder` takes the complete bucket,
+so `ops task reorder` reads the container, computes the new order of the
+bucket, and posts it. An anchor in another band or folder is refused
+(`reorder_anchor_outside`). `task create --top` creates the task and then
+reorders it to the top of its bucket (two writes, two undo entries). An
+unplaced task has no order bucket: `ops task reorder` refuses it
+(`task_unplaced`).
+
+#### The task primitive v0.1 ((Task) 1287 of the NUU Flint)
+
+A task has one status (`todo`, `doing`, `done`). A done task has one
+outcome: `completed`, `dropped`, or `superseded`. A task type (for example
+`task.dev@0.1`) adds fields and stages. The stages are a second layer: any
+stage can follow any stage. A typed task closes as `completed` only at a
+stage that can close (for `task.dev`: `reviewed` or `verified`). Only a
+person sets `verified`. A write is by an agent when `ORBH_SESSION_ID` is
+set (the CLI sends it as `X-Agent-Session`). A task has 0 or 1 home and 0
+or more related links. A task with no home is **unplaced**, and that is
+normal.
+
+| Command | Example |
+|---|---|
+| `ops task stage <task> <stage> [--note <text>]` — `taskStages.set` | `ops task stage <task> reviewed --note "No high finding"` |
+| `ops task retype <task> (<type>[@<version>] \| --none) [--type-version <v>]` — `tasks.setType` (amendment 6); a new type takes its active version; the stage and the fields stay only when the new type defines them (the same name and kind); `--none` makes the task untyped; the same type and version changes nothing; a done task refuses with `task_type_done` (reopen it first) | `ops task retype <task> task.dev` |
+| `ops task close <task> [--outcome completed\|dropped\|superseded] [--result <md\|->]` — `tasks.close`; default `completed` | `ops task close <task> --outcome dropped` |
+| `ops task result <task> <md\|->` — `""` clears it | `ops task result <task> "The pin works on dev."` |
+| `ops task note <task> <address> [--label <text>]` / `ops task note <task> --clear` — `tasks.setNote` ((Task) 1291): the Flint task note holds the content, and Ops keeps its address, `@v1/<org>/task/<note id>#flint/<flint>` (`flint resolve @v1//task/<n> --json` gives it); a new address with no `--label` clears the label; `--json` gives `{taskId, address, note, noteLabel, noteUrl}`; `noteUrl` is `obsidian://nuu-flint?address=` and the encoded note address, and the NUU Flint plugin opens it; a wrong address refuses with `task_note_invalid` | `ops task note <task> @v1/nuucognition/task/<uuid>#flint/nuu-flint --label "Task 1291 · NUU Flint"` |
+| `ops task field <task> <name> <value> [--append \| --remove]` — `tasks.setFields`; `""` clears the field; a list field gets the value as its one item; `--append` adds one item, once; `--remove` (amendment 6) deletes each item equal to the value from a list field in one write, so an append of another person at the same time stays (an item that is not in the list is no change); `--append` and `--remove` together are a usage error | `ops task field <task> wipCommits 1a2b3c4 --remove` |
+| `ops task commit <task> <sha> [--repo <name>]` — appends `<sha>` or `<sha> (<repo>)` to `wipCommits` | `ops task commit <task> 1a2b3c4d --repo flint` |
+| `ops task home <task> (--section <s> \| --backlog [--project <p>] [--folder <f>] \| --none)` — `tasks.home`; `--project` and `--folder` imply `--backlog`; `--backlog` alone is the master backlog; `--none` unplaces the task; for a deliverable, a deployment, or a parent, use `ops task move --to` | `ops task home <task> --backlog --project Alpha` |
+| `ops task relate <task> <kind> <ref> [--label <text>]` — kinds: `project`, `deliverable` (an ID, URL, or title), `repo` (a name), `flint` (a Flint id), `address` (a v1 address); a second relate changes only the label | `ops task relate <task> repo main` |
+| `ops task unrelate <task> <kind> <ref>` | `ops task unrelate <task> project Alpha` |
+| `ops task related <kind> <ref>` — `taskRelations.listForRef`: the tasks with a related link to a `project`, a `deliverable` (an ID, URL, or title), a `repo`, a `flint`, or an `address`, as task summaries | `ops task related repo main` |
+| `ops task hints [--flint <id>] [--repo <name>] [--text <text>]` — proposed homes from a Flint, a repository, or a text, best first; each line ends with the flags for `ops task home`; for a text, `ops route` is the decision of the revamp | `ops task hints --text "Fix the login page"` |
+| `ops task split <task> --part <title> [--part <title> ...] [--keep-open]` — the parts get the home, the type, and the related links; the old task closes as `superseded` | `ops task split <task> --part Backend --part Frontend` |
+| `ops task merge <task> <task>... (--into <task> \| --title <title>)` — the open absorbed tasks close as `superseded` | `ops task merge <a> <b> --into <c>` |
+| `ops task continue <task> [--title <title>]` — default title `<old title> (continued)`; an open old task closes as `superseded` | `ops task continue <task>` |
+| `ops task chain <task> <task> [<task>...]` — in order; a task is ready when the task before it is done | `ops task chain <first> <second> <third>` |
+| `ops task unchain <task>` — removes the `after` link of the task | `ops task unchain <task>` |
+| `ops task link <task> <previous>` — `taskLinks.link`: two tasks that exist; `<task>` continues from `<previous>` (kind `continues-from`); a new link replaces the old one; no task closes (`ops task continue` makes a new task) | `ops task link <task> <previous>` |
+| `ops task unlink <task> [--kind continues-from\|after]` — `taskLinks.unlink`: removes the link that the task holds; default `continues-from`; no task closes | `ops task unlink <task> --kind after` |
+| `ops task attach <target> <kind> <ref> [--session-id <id>] [--label <text>] [--state <state>]` — the target is a task or a task group (an ID or an address; a title names a task); kinds: `session`, `fleet`, `note`, `repo`; a second attach updates the label and the state | `ops task attach <address> session <session address> --session-id <id> --state working` |
+| `ops task detach <target> <kind> <ref>` — the row stays as history | `ops task detach <task> repo main` |
+| `ops task session-state <session-id> <state>` — `taskAttachments.setState`: the last known state of an Orbh session on each of its live attachments in the org; gives the count | `ops task session-state <session id> waiting` |
+| `ops task launch accept <launch-id> --station <address> --machine-id <id> (--text-file <path> \| --text-hash <hex>)` — `taskLaunches.accept` (D11): the station workflow accepts a NUU Network launch once, before any work; `--text-file` sends the sha-256 of the exact bytes of the item text; gives the task and the org, and the agent works only on them; refusals: `network_launch_not_found`, `network_launch_stale`, `network_launch_already_accepted`, `network_launch_text_mismatch`, `network_launch_wrong_target` | `ops task launch accept <id> --station <address> --machine-id <id> --text-file item.txt --json` |
+
+`--json` output: `show` gives the C6 detail with `address` at the top
+level, and the present keys (`breadcrumb`, `orgSlug`, `url`). `create`,
+`split`, `merge`, and `continue` give the new ids and their addresses.
+`retype` gives `{taskId, address, type, typeVersion, stage, fields}` after
+the write (`null` for an absent value): the address follows the type
+(`task.dev/<id>` or `task/<id>`), and an old address still resolves. When
+the read of an address after a write fails, the result keeps the new id with
+`address: null` (exit 0), and stderr names the read to run again: do not run
+the write again.
+`attach` gives `{attachmentId, target: {kind: "task"|"taskgroup", id,
+address}}`. A deployment without an op of the task primitive refuses a new
+verb with `agent_unknown_operation`; `show`, `done`, and `reopen` then keep
+their present behaviour.
+
+### task group
+
+A task group is a set of tasks that are done together, usually in one
+session. Each task stays a full task. A task can be in more than one task
+group. A group is open while one of its tasks is open (an empty group is
+open). The attachments of a group show on each of its tasks.
+
+| Command | Example |
+|---|---|
+| `ops task group create <title> [--task <task> ...] [--body <md\|->]` — gives the group id and its address | `ops task group create "Login fixes" --task <a> --task <b>` |
+| `ops task group update <group> [--title <title>] [--body <md\|->]` — `taskGroups.update`; give one or both; an empty body clears it | `ops task group update "Login fixes" --title "Login fixes, part 2"` |
+| `ops task group add <group> <task>...` | `ops task group add "Login fixes" <c>` |
+| `ops task group remove <group> <task>...` — the tasks stay | `ops task group remove "Login fixes" <c>` |
+| `ops task group show <group>` — `--json`: `{address, group, tasks, open, attachments, url}`; `url` is the web page of the group (the Groups view of the Tasks page); the address is the field `address` of `taskGroups.get` (a warning on stderr when it is null); when the tasks stop at their byte budget, `--json` has `tasksCut: true` after `tasks` and the text says so | `ops task group show @v1/test/taskgroup/<id>#ops --json` |
+| `ops task group list [--open]` | `ops task group list --open` |
+| `ops task group delete <group>` — deletes the group and its members, not the tasks | `ops task group delete "Login fixes"` |
+
+### task type
+
+| Command | Example |
+|---|---|
+| `ops task type list` — the active types | `ops task type list` |
+| `ops task type show <type>[@<version>] [--type-version <v>]` — the fields and the stages; with no version, the latest active version. The program owns `--version` (it prints the version of the CLI anywhere on the line), so a type version is `<type>@<version>` or `--type-version` | `ops task type show task.dev@0.1` |
+
+### comment
+
+| Command | Example |
+|---|---|
+| `ops comment list <task> [--events] [--limit n]` | `ops comment list "Write docs" --events` |
+| `ops comment add <task> <body\|->` | `ops comment add "Write docs" "First draft is up."` |
+| `ops comment edit <task> <commentId> <body\|->` | `ops comment edit "Write docs" <commentId> "Second draft."` |
+| `ops comment delete <task> <commentId>` | `ops comment delete "Write docs" <commentId>` |
+| `ops comment react <task> <commentId> <emoji>` | `ops comment react "Write docs" <commentId> 👍` |
+| `ops comment unreact <task> <commentId> <emoji>` | `ops comment unreact "Write docs" <commentId> 👍` |
+| `ops comment count <tasks...>` — the comment count of each task (`updates.counts`, at most 200 tasks, one call for each org); `--json`: `[{taskId, title, count}]` | `ops comment count <taskId> <taskId>` |
+
+### backlog
+
+| Command | Example |
+|---|---|
+| `ops backlog show [--project <p>] [--all]` — the backlog section of the project (or of the org) by priority band, each task with its address; on a deployment of before the revamp, the former view by folder and band | `ops backlog show --project Alpha` |
+
+`ops folder list|create|rename|reorder|delete` (the backlog folders of
+before the revamp) stays hidden for old callers. The migration of the revamp
+turns each folder into a section.
+
+### deadline
+
+| Command | Example |
+|---|---|
+| `ops deadline list [--all-orgs] [--mine] [--status open\|todo\|doing\|done\|all]` | `ops deadline list --all-orgs --mine` |
+| `ops deadline show <deadline>` | `ops deadline show "Beta"` |
+| `ops deadline create <title> --due <date> [--after <deadline>]... [--scope <tag>]... [--link <spec>]... [--title-link <spec>] [--assign <member>]...` — `--date` is the hidden former name of `--due` | `ops deadline create Beta --due "2026-11-01 17:00" --link project:Alpha --assign me` |
+| `ops deadline insert [title] --between <earlier> <later> [--due] [--scope]... [--assign]...` | `ops deadline insert "Code freeze" --between Alpha-start Beta` |
+| `ops deadline update <deadline> [--title] [--description] [--due] [--status todo\|doing\|done] [--scope <tag>]... [--clear-scopes] [--title-link <spec\|none>] [--nudge <n>]` | `ops deadline update Beta --status doing` |
+| `ops deadline shift <deadline> (--by <±days\|Nw> \| --to <date>) [--with-downstream]` — one `setDates` call | `ops deadline shift Beta --by 3 --with-downstream` |
+| `ops deadline links set <deadline> [specs...]` | `ops deadline links set Beta project:Alpha` |
+| `ops deadline links add <deadline> <specs...>` | `ops deadline links add Beta task:"Write docs"` |
+| `ops deadline links remove <deadline> <specs...>` | `ops deadline links remove Beta task:"Write docs"` |
+| `ops deadline requires set <deadline> [deadlines...]` | `ops deadline requires set Beta Alpha-start` |
+| `ops deadline requires add <deadline> <deadlines...>` | `ops deadline requires add Beta "Code freeze"` |
+| `ops deadline requires remove <deadline> <deadlines...>` | `ops deadline requires remove Beta "Code freeze"` |
+| `ops deadline assign <deadline> (<members...> [--add\|--remove] \| none)` — `--none` is the hidden former form of `none` | `ops deadline assign Beta me --add` |
+| `ops deadline delete <deadline>` | `ops deadline delete Beta` |
+
+### blocker
+
+A blocker says why work waits (Task 376 of the NUU Operations Flint): a
+title, who or what the work waits on, the next step, an owner, and one date,
+the next check-up. It links any number of records (project, deliverable,
+section, task, step). It gates no status. A blocker has no address: a
+`<blocker>` argument is an ID, or a title that matches one blocker of the org
+(two matches fail with `blocker_ambiguous`, exit 2, and list the IDs). An
+open blocker is **due** when its check-up date is today or earlier in local
+time. The CLI sends local dates, also the default check-up date (tomorrow),
+as the web app does.
+
+| Command | Example |
+|---|---|
+| `ops blocker list [--open] [--due] [--on <record>]` — `blockers.list` (the open ones by check-up date, then the 50 newest closed ones), or with `--on` `blockers.forRecord`; each line: the check-up date, the title, the status (`open, due` when due), the owner name, the delays, and the linked records | `ops blocker list --due` |
+| `ops blocker show <blocker>` — the fields, each link with its path and status (or `broken`), and the log with the actor names | `ops blocker show "No API key"` |
+| `ops blocker create <title> [--check <date>] [--waiting-on <text>] [--next <text>] [--owner <member>] [--on <record>]...` — default check-up: tomorrow; default owner: you; an ID, URL, or address in `--on` names the org of the blocker | `ops blocker create "No API key" --check +3d --on <taskId>` |
+| `ops blocker update <blocker> [--title] [--waiting-on <text\|none>] [--next <text\|none>] [--owner <member\|none>]` | `ops blocker update <blockerId> --next "Call the vendor"` |
+| `ops blocker attach <blocker> <record>` — a record that is attached changes nothing | `ops blocker attach <blockerId> section:"Alpha › v1 › Backend"` |
+| `ops blocker detach <blocker> <record>` — the ID of a broken link works too | `ops blocker detach <blockerId> <taskId>` |
+| `ops blocker delay <blocker> <date> [--note <text>]` — a new check-up date (counts as a delay); the same date with a note only logs the note; a closed blocker gives `blocker_closed` | `ops blocker delay <blockerId> +1w --note "Legal needs a week"` |
+| `ops blocker resolve <blocker> [--note <text>]` — the work can go on | `ops blocker resolve <blockerId> --note "The key came"` |
+| `ops blocker drop <blocker> [--note <text>]` — not a real blocker, or no longer matters | `ops blocker drop <blockerId>` |
+| `ops blocker reopen <blocker> [--check <date>]` — default check-up: tomorrow; an open blocker stays as it is | `ops blocker reopen <blockerId> --check +2d` |
+| `ops blocker delete <blocker> --yes` — removes the blocker and its log; refuses without `--yes` (`confirm_required`); `resolve` or `drop` keeps the log | `ops blocker delete <blockerId> --yes` |
+
+Codes from the service: `blocker_not_found`, `blocker_closed`,
+`blocker_check_invalid`, `blocker_title_required`, `blocker_text_too_long`
+(500 characters for the title, the texts, and a note),
+`blocker_link_not_found` (a link must be a record of the org of the blocker),
+`assignee_not_found`, and `assignee_not_member` (the owner). The ops are new
+on dev data: on a deployment without them, the error says that they are not
+deployed yet.
+
+### plan
+
+| Command | Example |
+|---|---|
+| `ops plan list [--status active\|completed\|all]` | `ops plan list` |
+| `ops plan show <plan> [--format text\|mermaid]` — `--json` prints the raw `plans.get` result | `ops plan show Launch --format mermaid` |
+| `ops plan create <title> [--description]` | `ops plan create Launch` |
+| `ops plan rename <plan> <title>` | `ops plan rename Launch "Launch v1"` |
+| `ops plan update <plan> [--title] [--description]` | `ops plan update Launch --description "Q4 launch"` |
+| `ops plan complete <plan>` | `ops plan complete Launch` |
+| `ops plan reopen <plan>` | `ops plan reopen Launch` |
+| `ops plan delete <plan> --yes` — every step goes; an undo cannot bring it back; refuses without `--yes` | `ops plan delete Launch --yes` |
+| `ops plan expand-all <plan>` — unfold every folded step | `ops plan expand-all Launch` |
+| `ops plan history <plan>` — your undo and redo stacks with seq numbers | `ops plan history Launch` |
+| `ops plan undo <plan> (--expect <seq> \| --dry-run)` | `ops plan undo Launch --expect 42` |
+| `ops plan redo <plan> (--expect <seq> \| --dry-run)` | `ops plan redo Launch --dry-run` |
+
+`ops plan show` prints the Start sentinel, then every step in topological
+order, then the End sentinel:
+
+```
+plan <id>  Launch  [active]  3 steps
+start @ -300,0  -> k57b2m
+k57b2m [ ] Design  @ 0,0  id k57b2m4x9q8r7t6y5u4i3o2p1a0s9d8f
+    requires: start
+k57c9a [~] Build  (optional)  @ 300,0  id k57c9a…
+    requires: k57b2m
+    links: task k57…  "Implement API"
+    assignee: Ana Lee (<usersId>)
+    deadline: 2026-11-01 Beta <deadlineId>
+    then: end
+end @ (auto)  <- k57c9a
+```
+
+Each step line shows the short ID (a unique ID prefix; step commands accept
+it with `--plan`), `[ ]` / `[~]` / `[x]`, the title, the optional and folded
+flags, the stored position `x,y` (`(auto)` when the step has none), and the
+full ID.
+
+**Undo safety.** `plan undo` and `plan redo` act as you: Waybill replays
+*your* last gesture in the scope `plan:<id>`, whoever made it (the web app,
+another agent, this CLI). The CLI reads the stack first
+(`plans.historyState`), names the gesture, and passes its seq as
+`expectSeq`. Without `--expect <seq>` (and without `--dry-run`) it refuses
+with `expect_required`, names the head, and prints the exact command. With
+`--expect <seq>` it refuses unless that gesture is still the head. The
+server refuses a stale seq too. A refusal is `undo_state_changed` (exit 2),
+and nothing changes. `ops history`, `ops undo`, and `ops redo` do the same
+for any other scope (below).
+
+### step
+
+Steps take an ID or URL alone, or a title or short ID with `--plan`.
+
+| Command | Example |
+|---|---|
+| `ops step add <plan> <title> [--after <step>]... \| [--before <step>] \| [--between <a> <b>] [--description] [--x --y]` — no flag: a new root. No `--x --y`: the server places the step | `ops step add Launch "Deploy" --after Build` |
+| `ops step update <step> [--plan] [--title] [--description] [--done\|--undone] [--optional\|--required] [--collapse\|--expand]` | `ops step update Build --plan Launch --done` |
+| `ops step assign <step> <member\|none> [--plan]` | `ops step assign Build me --plan Launch` |
+| `ops step requires set <step> [steps...] [--plan]` — no steps: a root | `ops step requires set Deploy Build Test --plan Launch` |
+| `ops step requires add <step> <steps...> [--plan]` | `ops step requires add Deploy Test --plan Launch` |
+| `ops step requires remove <step> <steps...> [--plan]` | `ops step requires remove Deploy Test --plan Launch` |
+| `ops step links set <step> [specs...] [--plan]` — kinds: task, section, deliverable, plan | `ops step links set Build task:"Implement API" --plan Launch` |
+| `ops step links add <step> <specs...> [--plan]` | `ops step links add Build section:Backend --plan Launch` |
+| `ops step links remove <step> <specs...> [--plan]` | `ops step links remove Build section:Backend --plan Launch` |
+| `ops step move <step> (--x <x> --y <y> \| --dx <dx> --dy <dy>) [--with-downstream] [--plan]` | `ops step move Build --dx 120 --with-downstream --plan Launch` |
+| `ops step move start\|end --plan <plan> (--x --y \| --dx --dy)` — the sentinels | `ops step move end --plan Launch --x 1400 --y 0` |
+| `ops step delete <step> [--plan]` — soft; `plan undo` revives it | `ops step delete Deploy --plan Launch` |
+
+**The drag rule.** `--with-downstream` matches the web canvas
+(`onNodeDragStop` in `src/components/plans/plan-view.tsx`): the step lands
+on its new spot, and every step after it (its whole branch, folded steps
+included) moves by the same offset, in **one** `plans.setPositions` call. A
+zero-length move writes nothing. A downstream step with no stored position
+stays where it is and is reported as `kept` (the UI moves it from a
+fallback layout that the CLI does not compute).
+
+### notify
+
+| Command | Example |
+|---|---|
+| `ops notify list [--unread] [--this-org] [--limit n] [--cursor c]` | `ops notify list --unread` |
+| `ops notify count [--this-org]` | `ops notify count` |
+| `ops notify read <ids...>` | `ops notify read <notificationId>` |
+| `ops notify unread <ids...>` | `ops notify unread <notificationId>` |
+| `ops notify read-all [--this-org]` | `ops notify read-all` |
+| `ops notify dismiss <id>` | `ops notify dismiss <notificationId>` |
+| `ops notify read-key <key>` — mark every notification with one collapse key read (`notifications.markKeyRead`) | `ops notify read-key <key>` |
+| `ops notify prefs list` | `ops notify prefs list` |
+| `ops notify prefs set <category> on\|off [--channel <c>]` — categories: tasks, deadlines, plans, updates | `ops notify prefs set plans off --channel push` |
+
+### activity
+
+| Command | Example |
+|---|---|
+| `ops activity list [--on <id\|url> \| --scope <scope>] [--mine] [--action <a>]... [--text <t>] [--limit n] [--cursor c]` — the Waybill feed of the org, or of one scope | `ops activity list --on <planId> --limit 10` |
+| `ops activity row <record> [--limit n] [--cursor c]` — the Waybill history of one row (`waybill.rowHistory`): each event that changed the record, newest first, with actor names. A record is an ID, an address, or a URL of a project, deliverable, section, task, backlog folder, plan, step, deadline, day label, deployment, task group, blocker, or notepad | `ops activity row <deadlineId> --json` |
+| `ops activity facets [--on <id\|url> \| --scope <scope>] [--limit n]` — the counts of the actors (with names), actions, tables, kinds, and scopes of the newest events (`waybill.facets`); use them as filters of `activity list` | `ops activity facets --on <planId>` |
+
+Scopes are `org:<slug>`, `project:<id>`, `deliverable:<id>`,
+`subsection:<id>`, `backlog:<projectId>`, `backlog:org:<slug>`, and
+`plan:<id>`. `org:me` and `backlog:org:me` name the personal workspace.
+`--on` maps a record to its scope (a task to its section or backlog, a
+step to its plan, a deadline, day label, or deployment to `org:<slug>`).
+
+### history, undo, redo (any scope)
+
+| Command | Example |
+|---|---|
+| `ops history (--on <id\|url\|address> \| --scope <scope>)` — your undo and redo stacks in the scope (`waybill.peek`); the scope of a section is `subsection:<id>` (the word of the service) | `ops history --on <taskId> --json` |
+| `ops undo (--on <id\|url> \| --scope <scope>) (--expect <seq> \| --dry-run)` | `ops undo --on <taskId> --expect 12` |
+| `ops redo (--on <id\|url> \| --scope <scope>) (--expect <seq> \| --dry-run)` | `ops redo --scope org:me --dry-run` |
+
+The guard is the one of `ops plan undo`. A deliverable maps to
+`deliverable:<id>` (its sections); a change of the deliverable row itself
+is in `project:<projectId>`.
+
+### favourite
+
+| Command | Example |
+|---|---|
+| `ops favourite list` — your favourites in the active org, in star order (`home.favourites`) | `ops favourite list --json` |
+| `ops favourite add <record> [--kind project\|deliverable\|section]` — star a record; a title needs `--kind`, an ID or URL does not | `ops favourite add <deliverableId>` |
+| `ops favourite remove <record> [--kind]` — remove the star; the ID of a deleted record works too | `ops favourite remove <recordId>` |
+
+A record of another kind gives `wrong_kind`. Both ops are idempotent. More
+than 100 favourites in one org gives `favourites_full`. The ops come from
+(Task) 316: on a deployment without them, the error says that they are not
+deployed yet.
+
+### day-label
+
+| Command | Example |
+|---|---|
+| `ops day-label list` | `ops day-label list` |
+| `ops day-label create <label> --start <date> [--end <date>] [--color water\|fire\|earth\|air\|sun\|moon\|muted]` | `ops day-label create Offsite --start 2026-10-12 --end 2026-10-14 --color sun` |
+| `ops day-label update <day-label> [--label] [--start] [--end] [--color]` | `ops day-label update Offsite --color moon` |
+| `ops day-label delete <day-label>` | `ops day-label delete Offsite` |
+
+### home
+
+The homepage reads of the active org. They come from fleet
+ops-cli-publish-1023 ((Task) 381): on a deployment without them, the error
+says that they are not deployed yet.
+
+| Command | Example |
+|---|---|
+| `ops home stats` — your task counts (`home.taskStats`): todo, doing, done, done this week (the week starts on Monday 00:00 local), overdue, due in 7 days, and the next due tasks. The CLI sends the local time of this machine, as the web app does | `ops home stats --org acme --json` |
+| `ops home recents` — the sections that you visited last in the web app, newest first (`home.recents`) | `ops home recents` |
+| `ops home activity [--limit n] [--cursor c]` — your own recent actions as homepage rows (`home.activity`, at most 50 a page) | `ops home activity --limit 10` |
+| `ops home brief <project>` — the brief notepad of a project (`brief.forProject`), or none. The web app writes a brief; read its text with `ops notepad show <notepadId>` | `ops home brief Alpha` |
+
+### notepad
+
+| Command | Example |
+|---|---|
+| `ops notepad list [--general \| --personal] [--section s \| --deliverable d \| --project p]` | `ops notepad list --general` |
+| `ops notepad show <notepad> [--md]` — the blocks, the mentioned tasks, the scope, and the rev | `ops notepad show "Standup notes"` |
+| `ops notepad create <title> [--general] [--body <md\|->] [--section s]` — personal unless `--general` | `ops notepad create Ideas --body - < ideas.md` |
+| `ops notepad rename <notepad> <title>` | `ops notepad rename <notepadId> "Weekly standup"` |
+| `ops notepad scope <notepad> (<section> \| --clear)` — link the notepad to one section | `ops notepad scope <notepadId> Backend` |
+| `ops notepad share <notepad> (--general \| --personal)` — share it with the org or make it personal (`notepads.setScope`); only its owner can, and a notepad of the personal workspace stays personal | `ops notepad share <notepadId> --general` |
+| `ops notepad mentions <task>` — the notepads that hold a chip of the task (`notepads.mentioning`) | `ops notepad mentions <taskId>` |
+| `ops notepad append <notepad> [<md\|->] [--task <task>]` | `ops notepad append <notepadId> --task <taskId>` |
+| `ops notepad write <notepad> <md\|-> (--expected-rev n \| --force)` | `ops notepad write <notepadId> - --expected-rev 3 < notes.md` |
+| `ops notepad to-task <notepad> <text> [--section s \| --project p [--folder f] \| --backlog] [--title t] [--keep]` — make a task from a text; a task chip replaces the text | `ops notepad to-task <notepadId> "Plan the demo"` |
+| `ops notepad move-to-task <notepad> <task> <text> [--copy]` — move a text to the end of a task description | `ops notepad move-to-task <notepadId> <taskId> "The budget is 4k."` |
+| `ops notepad delete <notepad>` — a soft delete | `ops notepad delete <notepadId>` |
+
+A `<notepad>` is a web URL (`.../notepads/<id>`), an Ops address
+(`@v1/<org>/notepad/<id>#ops`), an ID, or a title in the active org. Only
+the owner of a shared (general) notepad can delete it; make it personal
+first with `ops notepad share <notepad> --personal`, or ask the owner.
+
+The block ops (`notepads.addBlock`, `updateBlock`, `removeBlock`,
+`moveBlock`, `setBlocks`, `insertTask`, `makeTask`, `undoMakeTask`,
+`undoGesture`) have no typed command: use `ops call <op> '<json>'`.
+
+### day
+
+The day plan is personal: each command acts on your own plan, with tasks of
+any of your orgs. A date is `YYYY-MM-DD`, `today`, `tomorrow`, `yesterday`,
+or an offset like `+1d`.
+
+| Command | Example |
+|---|---|
+| `ops day show [date]` — the done count and the tasks in plan order | `ops day show tomorrow` |
+| `ops day add <task...> [--date d] [--top] [--source-org o]` | `ops day add <taskId> --date tomorrow` |
+| `ops day remove <task...> [--date d]` | `ops day remove <taskId>` |
+| `ops day reorder <task> (--before t \| --after t \| --top \| --bottom) [--date d]` | `ops day reorder <taskId> --top` |
+| `ops day carry [--date d]` — add the unfinished tasks of the 7 days before the date | `ops day carry` |
+| `ops day candidates [--date d]` — the open tasks that you can plan (`dayPlans.candidates`): your own tasks of every org and the tasks of your personal workspace; `--date` marks the planned ones | `ops day candidates --date today --json` |
+
+### deployment
+
+A deployment is abstract: a name, a free version label, a status (`live`,
+`paused`, `retired`), notes, a hidden context, an optional project, and an
+optional check schedule. A live deployment has an inbox section.
+
+| Command | Example |
+|---|---|
+| `ops deployment list [--project <p>] [--status live\|paused\|retired]` — `deployments.list`: each with its status, version label, schedule, open inbox count, project, and address | `ops deployment list --status live` |
+| `ops deployment show <deployment> [--project]` — `deployments.get`: the schedule, the notes, the inbox with its open tasks, the deliverables that ship to it and the ones that came from its inbox | `ops deployment show Production` |
+| `ops deployment inbox <deployment> [--open]` — `deployments.inbox`: the open tasks in order, then the done ones; add a task with `ops task create --deployment <d> --tag <tag>` | `ops deployment inbox Production --open` |
+| `ops deployment add <deployment> <title> [--body <text>] [--tag feedback\|hotfix\|ongoing\|recurring] [--every day\|week\|month]` — `deployments.addTask`: the Add of the inbox in the web app; the inbox is made when it is absent (also on a paused or retired deployment); `--every` alone gives the tag `recurring` | `ops deployment add Production "Login fails on Safari" --tag hotfix` |
+| `ops deployment sections <deployment> [--open]` — `deployments.sections`: the sections of the deployment other than its inbox (a section that a move put there), in order, each with its root tasks (open first) and addresses; archived sections are left out | `ops deployment sections Production` |
+| `ops deployment create <name> [--project <p>] [--version-label <label>] [--notes] [--context <md>] [--status live\|paused\|retired]` — live by default, so the inbox is made at once | `ops deployment create Production --project Alpha --version-label 1.4` |
+| `ops deployment update <deployment> [--name] [--version-label <label\|none>] [--notes] [--status] [--move-to-project <p\|none>]` | `ops deployment update Production --version-label 1.5` |
+| `ops deployment status <deployment> live\|paused\|retired` — `deployments.setStatus`; `live` makes the inbox | `ops deployment status Production paused` |
+| `ops deployment schedule <deployment> day\|week\|month\|off` — `deployments.setSchedule`; prints the next check | `ops deployment schedule Production week` |
+| `ops deployment check <deployment>` — `deployments.checkNow`: the check-up task now (none when an open one is there) | `ops deployment check Production` |
+| `ops deployment start-deliverable <deployment> <title> (<tasks...> \| --all-open) [--project <p>]` — `deployments.startDeliverable`: a new deliverable that comes from (and ships to) the deployment, with one section that holds the moved tasks; the service names that section "From the inbox" (rename it: `ops section update <section> --title <title>`) | `ops deployment start-deliverable Production "1.5 fixes" --all-open` |
+| `ops deployment context show\|set <deployment> …` — through `deployments.update` | `ops deployment context set Production "The web app at ops.example.com"` |
+| `ops deployment delete <deployment> --yes` — its inbox stays as a plain section | `ops deployment delete Beta --yes` |
+
+The program owns `--version` (it prints the version of the CLI anywhere on
+the line), so the label is `--version-label`. The version chain of before the
+revamp is deprecated: `--previous`, `--url`, `--identifier`, `--not-owned`,
+`list --chains`, `end-chain`, and `reopen-chain` stay hidden, print a note,
+and work while the service keeps them.
+
+### query
+
+The general read query (fleet ops-cli-publish-1023, (Task) 381): read the
+rows of one table of the active org when no typed command answers the
+question. It is read only. It calls `agentQuery.tables`,
+`agentQuery.describe`, and `agentQuery.run`.
+
+| Command | Example |
+|---|---|
+| `ops query tables` — the readable tables, with the rule of each (`org`, `user`: only your rows, `notepad`: a personal notepad only for its writer) | `ops query tables` |
+| `ops query describe <table>` — the fields with their types (from the schema; `?` marks an optional field), the indexes of the org, and the org field | `ops query describe tasks` |
+| `ops query <table> [--where <condition>]... [--index <name>] [--order asc\|desc] [--limit 1-500] [--cursor <c>] [--all] [--fields a,b.c] [--count]` — the rows that match every condition, as a compact table; `--json`: `{table, orgSlug, index, rows[], cursor, isDone}` | `ops query tasks --where checkbox=done --where 'priority in high,urgent' --fields title,priority` |
+
+The forms of `--where` (quote a condition that has `<`, `>`, `!`, `?`, or a
+space): `field=value`, `field!=value`, `field<value`, `field<=value`,
+`field>value`, `field>=value`, `field~text` (contains: a part of a string or
+an element of an array, no case), `field?` (the field exists), `!field?`
+(the field does not exist), and `field in a,b,c`. A value is a number,
+`true`, `false`, `null`, or a string; a value in double quotes stays a
+string (`'code="42"'`). A field is a name of the schema, or a dotted path
+into a nested object (`context.kind`).
+
+The rules:
+
+- The names are the names of the schema, not the words of the CLI: a
+  section is `deliverable_subsections`, and the section of a task is
+  `subsectionId`. Run `ops query describe <table>` first.
+- Each row belongs to the org. A table that holds a secret, a token, a
+  credential, a push subscription, or a Strike sync internal is not
+  readable, and neither is a table with no org field (`users`, `day_plans`,
+  `task_types`). Use the typed commands for them (`ops member list`,
+  `ops day`, `ops task type`).
+- A page holds at most `--limit` rows (default 50, max 500), and one call
+  reads at most 5000 documents. When the output ends with `more: --cursor
+  <c>`, give that cursor to read the next page, or use `--all`. `--all` and
+  `--count` follow the cursor up to 5000 rows.
+- A `contains` condition runs after the read. The CLI then reads pages of
+  500 until it has `--limit` rows; when more rows match, it gives no cursor
+  (use `--all` or `--count`).
+- An `=` condition on the fields of an index of the org uses that index
+  (`--index` names one); the other conditions filter the rows of the index.
+- A time such as `createdAt` is a number (epoch ms); a date such as
+  `dueDate` is a `YYYY-MM-DD` string.
+
+## The gateway
+
+- `POST <site>/agent/query`, `POST <site>/agent/mutate`, and (for an action
+  such as `route.suggest`) `POST <site>/agent/action`, body `{op, args}`,
+  header `Authorization: Bearer <nuu CLI JWT>`.
+- Response `{ok:true, result}` or `{ok:false, error:{code, message, data?}}`.
+- `GET <site>/agent/manifest` returns `{version, ops:[{op, kind, area, summary}]}`
+  (`kind` is `query`, `mutation`, or `action`) and needs no credential.
+  `ops ops` prints it.
+- The op name is the Convex path with a dot (`plans.createNode`); its args
+  are that function's args. Gateway read ops live in `agent.*`:
+  `agent.getTask`, `agent.searchTasks`, `agent.resolve`.
+
+`ops call` reaches every allowlisted op, also the ones with no dedicated
+command (for example `people.search`, `waybill.rowHistory`,
+`deadlines.linkIndex`).
+
+## Development
+
+```bash
+pnpm --filter @nuucognition/ops-cli typecheck
+pnpm --filter @nuucognition/ops-cli lint
+pnpm --filter @nuucognition/ops-cli test        # node:test, a mocked gateway
+pnpm --filter @nuucognition/ops-cli live-check  # every family against DEV data, then cleanup
+```
+
+`scripts/live-check.mjs` runs every command family against the dev
+deployment in the personal workspace. It stops unless `ops mode` reports dev
+data, forces `OPS_DATA_MODE=dev`, and deletes every record it creates, also
+after a failure. No check writes or toggles a record that the run did not
+create, and notification reads use `--this-org`. Its last check counts the
+records whose title starts with the run's tag (the tag holds a unique run
+id) and shows each deployment of the run; it must be 0. It also checks the `--json` error rule,
+`history`, `undo --dry-run` and the `expect_required` guard (no replay), the
+`confirm_required` guard of each delete, `--body-file`, `deliverable flint
+set` and `clear` on the run's own deliverable, and the reads of `favourite`,
+`notepad`, and `day` (on a deployment without these ops, the not-deployed
+error passes). To verify a rebuild on
+prod data, in the personal workspace only:
+
+```bash
+OPS_BIN=ops node scripts/live-check.mjs --prod --yes-prod              # the build on PATH
+OPS_CLI_FORCE_SOURCE=1 node scripts/live-check.mjs --prod --yes-prod   # the source
+```
+
+Source map: `src/modes.ts` (the two modes), `src/context.ts` (auth, orgs),
+`src/gateway.ts` (the client), `src/refs.ts` (references), `src/headers.ts`
+(the headers of an org, paths, and addresses), `src/places.ts` (the places of
+`--to` and of a create), `src/reorder.ts` (bucket reorders),
+`src/plan-graph.ts` (graph, Mermaid, drag rule), `src/undo.ts` (undo guard),
+`src/commands/*` (the command tree). `node --import tsx scripts/help-tree.ts`
+prints the help of every command.