@lumoai/cli 1.28.0 → 1.29.0

package/assets/skill/references/artifacts-figma.md

@@ -1,124 +0,0 @@
-# Task Artifacts & Figma Designs
-
-### Task ↔ Spec Artifacts
-
-Record Claude Code spec-engineering products (spec / plan / design …) on a task. The artifacts show up in the task detail definition ("spec") layer and are injected into `lumo task context`.
-
-#### `lumo task artifact add <task> --kind <kind> --title <title> --file <path> --source <source> --agent <agent>`
-
-Attaches an artifact to a task. `--kind`, `--title`, `--source` are stored verbatim — **`kind` is opaque** (no enumeration; `spec` / `plan` / `requirements` / anything is accepted). `--source` is **required** and names the spec-generation framework that produced the artifact, written as its **formal name** (`Superpowers` / `Spec Kit` / `BMad` / `OpenSpec` / `GSD` / …) — it is also opaque (no enumeration), but there is **no default**, so you must pass it. Quote names that contain spaces (`--source "Spec Kit"`). `--file` supplies the body (file contents). Each call appends to the end of the task's artifact list — call once per artifact (e.g. Superpowers: one `spec`, one `plan`). The `<task>` (e.g. `LUM-42`) is resolved server-side. **`--file` is sandboxed:** the CLI rejects any path that resolves **outside the current project directory** (parent-traversal, absolute paths, escaping symlinks) or that matches a **sensitive-file denylist** (`.env*`, `id_rsa`/`id_ed25519`, `*.pem`/`*.key`, `.aws`/`.ssh` contents, `credentials`, `.npmrc`, …). There is no override flag — pass only project-local, non-secret files (e.g. `docs/spec.md`). To record an out-of-tree file, copy it into the project first.
-
-`--agent` is **required** and names the coding tool that produced the artifact (enum). Valid values: `claude-code | codex | cursor | gemini-cli | github-copilot | windsurf` (case-insensitive; `gemini` and `copilot` are accepted aliases).
-
-```bash
-lumo task artifact add LUM-42 --kind spec --title "Spec" --file docs/spec.md --source Superpowers --agent claude-code
-lumo task artifact add LUM-42 --kind plan --title "Implementation plan" --file docs/plan.md --source "Spec Kit" --agent claude-code
-```
-
-Output: `Added [spec] "Spec" to LUM-42`
-
-#### `lumo task artifact update <task> <artifact-id> [--kind <kind>] [--title <title>] [--source <source>] [--agent <agent>]`
-
-Patches an existing artifact's metadata in place. Editable fields are **`kind`, `title`, `source`, and `agent`** — **content is immutable** (to change the body, `rm` the artifact and `add` it again). At least one flag is required; passing none errors before any network call. Empty values (`--kind ""`) are rejected. The `<artifact-id>` is the cuid in column 1 of `artifact list`. `--agent` accepts the same valid values and aliases as `artifact add`: `claude-code | codex | cursor | gemini-cli | github-copilot | windsurf` (case-insensitive; `gemini` and `copilot` are accepted aliases).
-
-```bash
-lumo task artifact update LUM-42 cma_xxx --kind plan              # re-classify spec → plan
-lumo task artifact update LUM-42 cma_xxx --source "Spec Kit"      # fix the framework label
-lumo task artifact update LUM-42 cma_xxx --title "Final spec" --source OpenSpec
-lumo task artifact update LUM-42 cma_xxx --agent cursor           # fix the agent label
-```
-
-Output: `Updated [plan] "Final spec" (OpenSpec) on LUM-42`. A 404 (task or artifact missing in this workspace) prints the server message and exits 1.
-
-#### `lumo task artifact list <task>`
-
-Lists artifacts on the task in order: `<id>  <kind>  <agent>  <source>  <title>`. Prints `No artifacts on <task>` when there are none.
-
-```bash
-lumo task artifact list LUM-42
-```
-
-#### `lumo task artifact show <task> <artifact-id>`
-
-Prints one artifact's key:value header (id, kind, title, agent, source, order, task) followed by the full content body. The `<artifact-id>` is the cuid in column 1 of `artifact list`.
-
-```bash
-lumo task artifact show LUM-42 cma_xxx
-```
-
-#### `lumo task artifact rm <task> <artifact-id> --yes`
-
-Deletes an artifact from a task. Irreversible — `--yes` is required and there is no interactive prompt (agent-friendly). On success prints `Removed <artifact-id> from <task>`. A 404 (task or artifact missing in this workspace) prints the server message and exits 1.
-
-```bash
-lumo task artifact rm LUM-42 cma_xxx --yes
-```
-
-When to suggest: after running a spec/plan workflow in Claude Code, offer to record the product(s) with `task artifact add` (one call per artifact) — always pass `--source` with the framework you used. Use `task artifact list` to see what's already recorded, `task artifact show` to inspect a single artifact's content, `task artifact update` to fix a wrong kind/title/source without re-uploading, and `task artifact rm` to drop one that's wrong or stale.
-
-### Task ↔ Figma Designs
-
-#### `lumo task figma add <task> <url>` — attach a Figma file/frame
-
-Fetches file name, frame name, and thumbnail via Figma OAuth and stores them
-on the task.
-
-```bash
-lumo task figma add LUM-42 "https://www.figma.com/design/abc123/Onboarding?node-id=1-234"
-```
-
-If the URL omits `node-id`, the link is stored as file-level; the CLI prints
-a `(file-level, thumbnail from "...")` note showing the auto-picked
-representative frame.
-
-Idempotent — re-adding the same URL within 7 days returns the existing row
-without re-calling Figma.
-
-**Not connected?** Errors with:
-
-```
-✗ You haven't connected Figma yet.
-  Run: open https://www.uselumo.ai/settings/integrations
-```
-
-#### `lumo task figma list <task>` — list attachments
-
-```
-$ lumo task figma list LUM-42
-cfl_xxx1  Onboarding       Welcome screen       2026-05-28
-cfl_xxx2  Design System    Button / Primary     2026-05-27
-cfl_xxx3  Onboarding       (file-level)         2026-05-20  ⚠ thumbnail stale
-```
-
-`⚠ thumbnail stale` appears when `thumbnailFetchedAt > 25 days`.
-
-#### `lumo task figma rm <task> <link-id-or-url>` — remove an attachment
-
-Accepts a `cfl_*` cuid or the original URL. Idempotent (`Not linked: ...` + exit 0 when no match).
-
-#### `lumo task figma refresh <task>` — manual refresh
-
-Re-fetches metadata + thumbnail for every Figma link on the task. Per-link
-failures are isolated.
-
-```
-$ lumo task figma refresh LUM-42
-Refreshed 3 Figma links on LUM-42
-  ✓ Onboarding · Welcome screen
-  ✓ Onboarding · Sign-up form
-  ✗ Design System · Button (file not accessible)
-```
-
-### When to suggest the `task figma` commands
-
-- User pastes a Figma URL or mentions a design ("here's the mock", "the
-  Figma is at...").
-- User asks "what designs are linked to this task" or "show me the Figma
-  for LUM-42".
-- After implementing a UI change, suggest `lumo task figma refresh <task>`
-  if the user mentioned updating the Figma source.
-
-OAuth connection lives in the Web UI at
-`/settings/integrations`. The CLI does **not** have a `figma auth`
-command; if the user tries `task figma add` without connecting, the error
-message directs them to the Web UI.

package/assets/skill/references/criteria.md

@@ -1,160 +0,0 @@
-# Acceptance criteria (contract)
-
-The acceptance contract is a small set of structured criteria the task's work
-will be verified against (Acceptance v1, LUM-341/342). The agent drafts it;
-the server validates and stores it; verification rounds (`lumo verify`,
-Slice 1 task #3) judge against it. Criteria are injected at session start and
-in `lumo task context` as the `## Acceptance criteria (contract)` section.
-
-## When to draft — the golden rule
-
-**Attach → read context → draft criteria → THEN write the first line of code.**
-
-If `lumo task context` / session-start shows the draft reminder ("This task
-has no acceptance criteria yet. …") instead of a
-contract, you MUST draft and submit criteria before starting implementation:
-
-1. Read the task description, comments, linked resources, and memory first —
-   the contract distills what "done" means, so understand the task before
-   writing it.
-2. Draft **3–7 criteria** for a typical multi-file task (soft range — the
-   server warns outside it but never rejects; if you genuinely need more,
-   merge related checks instead). **Scale the count down for small tasks** —
-   see "Scale the contract to the task size" below.
-3. Submit with `lumo task criteria set <task> --file <criteria.json>`.
-   Submission **locks the contract for agent edits** — get it right before
-   submitting, because afterwards only human revisions (`--human`) can change it.
-
-Once you (the agent) have started work, you can NOT change your own contract.
-That's by design: the contract is what your work gets judged against, not a
-to-do list you trim to fit what you built.
-
-## Scale the contract to the task size
-
-The 3–7 range is calibrated for typical multi-file tasks. The criterion count
-must track the size of the work — it is not a fixed ritual:
-
-- **Micro task** (expected to fit a single session, blast radius of one or
-  two files — a docs tweak, a copy change, a small targeted fix): **1–2
-  criteria IS a complete contract** — one targeted MACHINE criterion plus at
-  most one HUMAN criterion.
-- **Never pad toward the soft floor.** A filler criterion (a restated
-  baseline, a third angle on the same check) dilutes the contract and taxes
-  every verification round. For a micro task the below-minimum warning is
-  expected — ignore it.
-- **Shrink the contract, never skip it.** Every task still drafts and locks a
-  contract before the first line of code; task size only changes how many
-  criteria that takes.
-
-## How to write good criteria
-
-- **Outcome-level definition of done, not micro-steps.** A criterion states a
-  verifiable result ("`lumo task criteria set` rejects a second agent draft
-  with 409"), not a task step ("add a check in the service").
-- **Repo-wide baselines don't take slots.** Tests pass / `tsc --noEmit` clean /
-  i18n locale parity / lint are already required by the repo's PR checklist —
-  never spend one of your 3–7 criteria on them.
-- **MACHINE vs HUMAN:**
-  - `MACHINE` = an executable check exists. It **must** carry a `checkpointer`
-    (the runnable check: a test command, script, probe…). The checkpointer
-    runs on the agent's machine; the structured verdict is reported back to
-    the server (execution on the client, adjudication on the server).
-  - `HUMAN` = needs human judgment (UX feel, copy tone, design fidelity).
-  - **If you can't attach a checkpointer to a MACHINE criterion, demote it to
-    HUMAN** — the server rejects checkpointer-less MACHINE criteria rather
-    than silently rewriting them. Don't invent a fake checkpointer to keep it
-    MACHINE.
-- `evidenceRequired: true` marks criteria whose verdict must point at proof
-  (a MACHINE PASS always requires evidence regardless of this flag).
-
-## JSON file format
-
-`criteria.json` is a JSON array; one object per criterion:
-
-```json
-[
-  {
-    "statement": "PUT /api/tasks/[id]/criteria rejects a second AGENT_DRAFT submission with 409",
-    "verifierType": "MACHINE",
-    "checkpointer": "npx jest __tests__/task-criteria.service.test.ts -t 'agent lock'"
-  },
-  {
-    "statement": "The criteria section reads naturally as part of the task statement",
-    "verifierType": "HUMAN"
-  },
-  {
-    "statement": "Session-start injection shows the contract ahead of memory",
-    "verifierType": "MACHINE",
-    "checkpointer": "npx jest __tests__/cli/hook-runner-session-start-stdout.test.ts",
-    "evidenceRequired": true
-  }
-]
-```
-
-Fields: `statement` (required, ≤2000 chars), `verifierType` (`"MACHINE"` |
-`"HUMAN"`), `checkpointer` (required for MACHINE), `evidenceRequired`
-(optional, default false), `id` (only in `--human` revisions — see below).
-
-## Commands
-
-### `lumo task criteria set <task> --file <criteria.json>`
-
-Initial agent draft. Creates the whole contract as `AGENT_DRAFT` at round 0.
-Rejected with 409 once **any** criteria exist on the task — the agent lock.
-Echoes the stored criteria (with ids) plus the 3–7 soft-cap warning if
-outside range.
-
-### `lumo task criteria set <task> --file <criteria.json> --human`
-
-Record a **human contract revision** (HUMAN_EDIT), e.g. when the user changes
-the contract in conversation — you transcribe their decision. Allowed at any
-time, even after the agent lock. The file is the **desired final list**:
-
-- items carrying an `id` (from `criteria list`) keep that criterion — changed
-  fields update it and stamp it `HUMAN_EDIT`; identical fields leave it (and
-  its provenance) untouched
-- items without `id` are created as `HUMAN_EDIT`
-- existing criteria missing from the file are **deleted** — refused with 409
-  if the criterion already has verification runs (reword it instead)
-
-The revision is auto-recorded as a task comment with the session origin
-(`X-Lumo-Session-Id`). **Transcribing the contract is allowed; transcribing a
-verdict is never** — human verdicts only enter through human-initiated paths
-(web UI / Slack action), and the agent has no write path to them.
-
-Only use `--human` for decisions a human actually made (in conversation, in a
-comment, in review). Never use it to work around your own lock.
-
-Optionally annotate **why** the contract drifted with
-`--cause <NEW_INFO|SCOPE_CHANGE|DRAFT_BLIND_SPOT|GRANULARITY|OTHER>` — pick
-the tag from the human's stated reason (new information, scope moved, the
-draft missed it, wrong granularity). The tag lands in the drift record
-(TaskActivity payload), feeding the Slice-3 drift-cause distribution. Every
-criteria add/update/delete is mirrored as a structured `CRITERION_CHANGED`
-activity automatically; `--cause` just enriches it.
-
-### `lumo task criteria list <task>`
-
-Print the contract: `<id>  [MACHINE|HUMAN]  SOURCE@rN  [evidence]  statement`
-plus an indented `↳ check:` line for checkpointers. Use it to fetch ids
-before a `--human` revision. Empty contract prints a drafting pointer.
-
-## Injection behavior
-
-- **Session start** (bound task): the contract is the highest-priority
-  section in the injection budget — ahead of memory/PR/Slack/Figma/web. If a
-  still-open task has no criteria, the draft reminder is injected instead.
-- **`lumo session attach`**: prints the contract (or the draft reminder) right after
-  binding.
-- **`lumo task context`**: the `## Acceptance criteria (contract)` section appears after the
-  task description, before memory.
-- Review-time gap findings are appended at the round they surface and show up
-  in the contract automatically — `REVIEW_ADDED` provenance via human review
-  paths; findings a human raises in conversation are transcribed with
-  `--human` + `--cause` (see verify.md "Review-time drift habits").
-
-## After the contract: the verification loop
-
-The contract is judged by `lumo verify` — run it before claiming the task is
-done. See [verify.md](verify.md) for the loop (round cap 3, IN_REVIEW on
-all-pass, escalation on a round-3 fail).

package/assets/skill/references/docs.md

@@ -1,339 +0,0 @@
-# Document Management
-
-## Document Management
-
-### `lumo doc create [title] [flags]` — create a new document
-
-Use this when the user wants to write a new document from the terminal. Title is positional and optional. When omitted, the doc title defaults to empty (server renders as "Untitled" via i18n).
-
-| Flag               | Type                | Notes                                                                                                            |
-| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `--content <text>` | string              | Inline markdown body.                                                                                            |
-| `--file <path>`    | string              | Read markdown body from file.                                                                                    |
-| (stdin)            | —                   | Pipe markdown; treated as content when stdin is not a TTY.                                                       |
-| `--scope <scope>`  | enum                | `personal` (default) or `workspace`. Maps to PRIVATE / WORKSPACE.                                                |
-| `--project <ref>`  | string              | Project name or slug to file under. Default null. (Note: v1 does not server-resolve names; pass a cuid or omit.) |
-| `--task <LUM-N>`   | string              | Bind to this task immediately after create.                                                                      |
-| `--tag <name>`     | string (repeatable) | Attach tag by name. Creates tag if missing. Max 20 per call.                                                     |
-| `--tag-id <cuid>`  | string (repeatable) | Attach tag by id. Combines with `--tag`. Max 20 per call.                                                        |
-| `--parent <doc>`   | string              | cuid or case-insensitive title. Files the new doc under this parent. Omit for root.                              |
-
-The three content channels (`--content`, `--file`, stdin) are mutually exclusive — specify at most one. **`--file` is sandboxed:** the CLI rejects a path that resolves outside the current project directory (parent-traversal, absolute, escaping symlinks) or matches a sensitive-file denylist (`.env*`, private keys, `*.pem`/`*.key`, `credentials`, `.ssh`/`.aws` contents, …). Pass only project-local, non-secret files; there is no override flag.
-
-Examples:
-
-```bash
-lumo doc create "RFC: doc CLI" --scope workspace --file scratch/rfc.md --task LUM-66
-lumo doc create "RFC: tags" --tag rfc --tag draft
-lumo doc create "Design spec" --tag-id clm_abc123 --tag draft
-lumo doc create "Sub-doc" --parent "RFC"
-```
-
-Success output:
-
-```
-Created cmd_xxx "RFC: doc CLI"  https://www.uselumo.ai/workspace/lumo/documents/rfc-doc-cli-42
-Tags: rfc, draft
-```
-
-The cuid (`cmd_xxx`) is still printed as a stable identifier you can pass back into other `lumo doc ...` commands; the URL switched to the per-workspace slug shape (`slugify(title)-<number>`) and the cuid is no longer a valid web URL.
-
-The `Tags:` line is omitted when no tags were attached.
-
-### When to suggest `doc create`
-
-- User says "write a doc", "draft an RFC", "new document" (in any language), or describes a deliverable that should live as a document.
-- After a discussion that needs a write-up, offer to create the doc with a title and the right scope.
-
-### `lumo doc update <doc> [flags]` — update a document
-
-`<doc>` accepts a cuid or a case-insensitive title. Ambiguous titles fail with a candidate list — re-run with the cuid.
-
-| Flag                     | Type                | Notes                                                                                                                                                                                                                                                                 |
-| ------------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--title <text>`         | string              | New title (cannot be empty).                                                                                                                                                                                                                                          |
-| `--content <text>`       | string              | Replace content (inline).                                                                                                                                                                                                                                             |
-| `--file <path>`          | string              | Replace content from file.                                                                                                                                                                                                                                            |
-| (stdin)                  | —                   | Pipe to replace content.                                                                                                                                                                                                                                              |
-| `--scope <scope>`        | enum                | `personal` / `workspace`.                                                                                                                                                                                                                                             |
-| `--project <ref>`        | string              | Project name/slug. `--project ""` clears the filing.                                                                                                                                                                                                                  |
-| `--tag <name>`           | string (repeatable) | **Bulk replace** the tag set by name. Creates tag if missing. Max 20. Mutually exclusive with `--add-tag*` / `--remove-tag*`.                                                                                                                                         |
-| `--tag-id <cuid>`        | string (repeatable) | **Bulk replace** the tag set by id. Max 20. Mutually exclusive with `--add-tag*` / `--remove-tag*`.                                                                                                                                                                   |
-| `--add-tag <name>`       | string (repeatable) | Attach tag by name (find-or-create). Max 20.                                                                                                                                                                                                                          |
-| `--add-tag-id <cuid>`    | string (repeatable) | Attach tag by id. Max 20.                                                                                                                                                                                                                                             |
-| `--remove-tag <name>`    | string (repeatable) | Detach tag by name. `--remove-tag <name>` resolves the name via find-or-create on the workspace. If the name was unknown, a new Tag row is created (orphan, no attachments) before the detach runs as a no-op. Use `--remove-tag-id <cuid>` to avoid orphans. Max 20. |
-| `--remove-tag-id <cuid>` | string (repeatable) | Detach tag by id. Unknown ids are a no-op (no side effects). Max 20.                                                                                                                                                                                                  |
-
-`--tag` / `--tag-id` (bulk replace) are mutually exclusive with `--add-tag` / `--add-tag-id` / `--remove-tag` / `--remove-tag-id`. The CLI errors before any network call if both families are mixed.
-
-Like `doc create`, `--file` is sandboxed: the CLI rejects paths that resolve outside the project directory or match the sensitive-file denylist (`.env*`, private keys, `credentials`, …). No override flag.
-
-Examples:
-
-```bash
-lumo doc update "RFC: doc CLI" --scope personal
-lumo doc update cmd_xxx --title "RFC v2"
-lumo doc update cmd_xxx --file rfc-v2.md
-lumo doc update RFC --add-tag urgent --remove-tag draft
-lumo doc update cmd_xxx --tag final --tag approved   # replace entire tag set
-lumo doc update RFC --tag final --add-tag oops
-# Error: --tag/--tag-id are mutually exclusive with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id
-```
-
-### When to suggest `doc update`
-
-- User wants to revise an existing doc.
-- After running `lumo doc list` or `doc show`, if the user wants to change a doc's scope, title, or content.
-
-### `lumo doc show <doc> [--raw]` — print one document's detail
-
-Default mode prints a key:value header (id, title, scope, project, created/updated timestamps, mentioned tasks) and the content rendered back to markdown.
-
-```bash
-lumo doc show "RFC: doc CLI"
-lumo doc show cmd_xxx --raw > base.md   # byte-identical edit base
-```
-
-**`--raw` (LUM-408)** prints the byte-identical markdown source of the last markdown upload — no header, no trailing newline added. The server stores the raw markdown (`sourceMarkdown`) alongside the rendered HTML on every markdown write (`doc create/update --content/--file/stdin`, gdoc import/sync), so `--raw` output IS a legal edit base: `doc show --raw > base.md`, edit, `doc update --file base.md` round-trips losslessly.
-
-- A web-editor (HTML-direct) edit or revision restore **invalidates** the stored source — the doc's markdown source is gone until the next markdown upload.
-- When no source is stored (legacy doc or after an HTML edit), `--raw` **fails with exit 1 and a rebuild hint** — it never silently falls back to the lossy HTML→markdown reverse render (that fallback flattened tables: LUM-349). Rebuild flow: `doc show` (rendered) → reconstruct the markdown faithfully → `doc update --file rebuilt.md` → `--raw` works from then on.
-- Raw output is verbatim (unsanitized) by design — redirect it to a file rather than reading it in a terminal when the doc's provenance is uncertain.
-
-Note: the markdown rendered by **default-mode** `doc show` is still best-effort (tables flatten). Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT a no-op — use `--raw` as the edit base instead.
-
-Use default mode when the user wants to read a doc; use `--raw` whenever the output will be edited and uploaded back.
-
-### When to suggest `doc show --raw`
-
-- Before any `doc update --file` that starts from existing remote content — fetch the base with `--raw`, never from rendered `doc show` output.
-- User asks "what's the exact source of this doc", or an agent needs a faithful local copy of a live doc.
-- If `--raw` errors (no stored source), walk the rebuild flow above instead of editing the rendered output.
-
-### `lumo doc diff <doc> --file <local.md>` — compare remote markdown source vs a local file
-
-Compares the server-side stored markdown source (the byte-identical last markdown upload) against a local file, making remote/local split-brain visible on demand.
-
-| Flag            | Type   | Notes                                                                              |
-| --------------- | ------ | ---------------------------------------------------------------------------------- |
-| `--file <path>` | string | Required. Local markdown file; same project-local sandbox as `doc update --file`. |
-
-Exit codes: **0** = byte-identical (prints `Clean: …`), **1** = divergent (prints a unified diff, `--- remote/<id> (sourceMarkdown)` vs `+++ local/<file>`) or error. A doc without a stored markdown source errors explicitly (upload a markdown base once, then diff works).
-
-```bash
-lumo doc diff cmd_xxx --file docs/live-docs/research-intake-ledger.md
-```
-
-### When to suggest `doc diff`
-
-- Before uploading a locally edited file with `doc update --file` — check whether the remote source moved since the local copy was taken (prevents stale-upload clobbering, the #460 incident class).
-- When a repo-tracked markdown source (e.g. `docs/live-docs/`) and the live doc may have drifted and the user asks which is current.
-- After a suspected concurrent edit: a clean diff (exit 0) proves remote and local are in sync.
-
-### `lumo doc list [flags]` — list documents
-
-Default behavior: lists every document the current user can see, as fixed-width rows: `<cuid>  <SCOPE>  <project|->  <title>`.
-
-| Flag              | Type    | Notes                                                                                  |
-| ----------------- | ------- | -------------------------------------------------------------------------------------- |
-| `--scope <scope>` | enum    | `personal`, `workspace`, or `all`. Default `all`.                                      |
-| `--project <ref>` | string  | Filter by project.                                                                     |
-| `--task <LUM-N>`  | string  | Only docs bound to this task. Routes through `GET /api/tasks/<id>/documents`.          |
-| `--limit <n>`     | int     | Cap output to the first N rows.                                                        |
-| `--tree`          | boolean | Render as an indented tree (two spaces per depth level) instead of the flat row table. |
-
-`--tree` plus the existing filters work together: the CLI fetches with the filters applied, then builds the tree from whatever rows came back. Docs whose parent is **not** in the result (e.g. filtered out by `--task LUM-N`) render as top-level rows. `--limit N --tree` truncates the flat list to N rows _before_ the tree is built, so a deeply nested subtree may not appear contiguously.
-
-When `--task` is combined with `--scope` / `--project`, those become client-side filters on the task-scoped result.
-
-Examples:
-
-```bash
-lumo doc list --scope workspace
-lumo doc list --task LUM-42
-lumo doc list --scope workspace --tree
-```
-
-### When to suggest `doc list`
-
-- The user asks "what docs do I have", "show me workspace docs", "what's on LUM-42".
-- Before suggesting `doc update` or `doc delete` when no doc ID is in context — run `doc list` first to surface candidates.
-
-### `lumo doc move <doc> [flags]` — move a doc under a different parent or to root
-
-Reparents a doc. `<doc>` accepts a cuid or a case-insensitive title; ambiguous titles fail with a candidate list — re-run with the cuid.
-
-| Flag             | Type    | Notes                                            |
-| ---------------- | ------- | ------------------------------------------------ |
-| `--parent <doc>` | string  | New parent doc (cuid or case-insensitive title). |
-| `--root`         | boolean | Move to top level (`parentId = null`).           |
-
-`--parent` and `--root` are **mutually exclusive** and one of them is **required**. CLI errors before any network call if both or neither is supplied.
-
-The new `sortOrder` is computed CLI-side as `max(sibling.sortOrder) + 1` — the moved doc lands at the end of its new sibling list. Reordering among siblings (`--before` / `--after`) is not yet supported; for now use the Web UI to reorder.
-
-Examples:
-
-```bash
-lumo doc move "Sub-doc" --parent "Roadmap"
-lumo doc move "Sub-doc" --root
-lumo doc move cmd_xxx --parent cmd_yyy
-```
-
-Output:
-
-```
-Moved cmd_xxx "Sub-doc" → "Roadmap"
-Moved cmd_xxx "Sub-doc" → root
-```
-
-### When to suggest `doc move`
-
-- User says "move doc X under Y", "reparent X to root", "promote X to top level".
-- After `doc create`, if the user realizes the new doc should live elsewhere in the tree — suggest `doc move` rather than recreating.
-
-### `lumo doc delete <doc> --yes` — delete a document
-
-Requires `--yes`; no interactive prompt (agent-friendly).
-
-```bash
-lumo doc delete cmd_xxx --yes
-```
-
-### `lumo doc bind <doc> <task>` — bind a doc to a task
-
-Adds an explicit DocumentMention row. Survives content edits in the Web UI. If a CONTENT-derived mention already exists for the same pair, it's upgraded to EXPLICIT so a later `unbind` can remove it.
-
-Output:
-
-```
-Bound cmd_xxx ↔ LUM-42
-Bound cmd_xxx ↔ LUM-42 (upgraded from content)   # when upgrading a CONTENT row
-Already bound cmd_xxx ↔ LUM-42                   # idempotent
-```
-
-### `lumo doc unbind <doc> <task>` — unbind a doc from a task
-
-Removes EXPLICIT mentions only. A purely CONTENT-derived mention can't be unbound from CLI — fails with 409 and a message instructing the user to remove the @LUM-N from the doc body in the Web UI.
-
-```bash
-lumo doc unbind cmd_xxx LUM-42
-```
-
-### `lumo doc share <doc> <member> [--role viewer|editor|manager]` — share with a workspace member
-
-Adds (or updates) a DocumentShare row for the given member. `<member>` resolves the same way as `task --assignee`: `me`, an email, or a display name (case-insensitive). Role defaults to `viewer`.
-
-**Auto-promotion**: when invoked on a PRIVATE doc, server-side transactionally flips the doc's visibility to SHARED before upserting the share row. No flag needed — sharing a doc is treated as expressing the intent that it should be SHARED.
-
-Examples:
-
-```bash
-lumo doc share "RFC" alice@example.com --role editor
-lumo doc share cmd_xxx "Alice Wong" --role manager
-lumo doc share cmd_xxx me                        # share with yourself (rare; mostly for testing)
-```
-
-Output:
-
-```
-Shared cmd_xxx ↔ Alice Wong (EDITOR)
-```
-
-A second invocation with a different role updates the existing row in place (upsert semantics).
-
-### `lumo doc unshare <doc> <member>` — remove a member's share
-
-Idempotent. If the member has no share row, prints `Not shared with <name>` and exits 0.
-
-```bash
-lumo doc unshare "RFC" alice@example.com
-# → Unshared cmd_xxx ↔ Alice Wong
-```
-
-Unshare does **not** flip visibility back to PRIVATE — that has to be done explicitly via `lumo doc update --scope personal`.
-
-### `lumo doc share-list <doc>` — list current shares
-
-Prints fixed-width rows: `<displayName>  <ROLE>`. Empty output means the doc has no shares (it may still be WORKSPACE-visible).
-
-```bash
-lumo doc share-list "RFC"
-# Alice Wong   EDITOR
-# Bob Chan     VIEWER
-```
-
-### When to suggest the doc share commands
-
-- User says "share doc X with Y", "give Y access to X"
-- After `doc create --scope personal`, if the user mentions teammates needing access, suggest `doc share` rather than `doc update --scope workspace` when only specific members should see it
-- Before `doc unshare`, run `doc share-list` if the user hasn't named a specific member
-
-### `lumo doc import-gdoc <url> [--scope personal|workspace] [--task LUM-N]` — import a Google Doc
-
-One-way import of a Google Doc into Lumo. The doc is exported from Google as markdown and turned into a native Lumo document (markdown → HTML), storing the source `googleDocId` and importer so it can be re-synced later (`lumo doc sync`). `<url>` accepts a Google Doc URL or a bare doc id.
-
-| Flag              | Type   | Notes                                                                                      |
-| ----------------- | ------ | ------------------------------------------------------------------------------------------ |
-| `--scope <scope>` | enum   | `personal` (→ PRIVATE) or `workspace` (→ WORKSPACE). Omit to use the server default scope. |
-| `--task <LUM-N>`  | string | Bind the imported doc to this task immediately after import.                               |
-
-**Over-share note:** once imported, the content follows **Lumo's** sharing model (PRIVATE / SHARED / WORKSPACE) and is **no longer gated by Google permissions**. Importing a `workspace`-scoped doc can therefore expose it to everyone in the workspace even if the Google Doc was restricted — the command prints this reminder on success.
-
-Requires a connected Google Drive integration; connect it in the Web UI at `/settings/integrations`. There is no CLI `google auth` command.
-
-```bash
-lumo doc import-gdoc "https://docs.google.com/document/d/<id>/edit"
-lumo doc import-gdoc "https://docs.google.com/document/d/<id>/edit" --scope workspace --task LUM-127
-```
-
-Output:
-
-```
-Imported cmd_xxx "Quarterly Plan"  https://www.uselumo.ai/workspace/lumo/documents/quarterly-plan-42
-Note: imported content follows Lumo sharing and is no longer gated by Google permissions.
-Bound cmd_xxx ↔ LUM-127
-```
-
-The `Bound ... ↔ LUM-N` line appears only when `--task` is supplied.
-
-### When to suggest `doc import-gdoc`
-
-- User pastes a Google Doc URL or says "import this Google Doc", "pull this gdoc into Lumo".
-- User wants a Google Doc tracked alongside Lumo tasks/docs — suggest import (with `--task LUM-N` if a task is in context) and remind them about the over-share semantics for `--scope workspace`.
-
-### `lumo doc sync <doc>` — re-sync an imported doc from Google
-
-Re-imports a previously imported Google Doc and **overwrites the Lumo body** with the current Google content. **One-way and destructive** — any edits made to the doc inside Lumo are discarded; Google is the source of truth for synced docs.
-
-Sync always runs as the **importer** (owner model): it re-exports using the importer's stored Google token, not the token of whoever runs the command. If the importer has lost access to the Google Doc, sync fails with a clear error.
-
-`<doc>` accepts a doc cuid or a case-insensitive title; ambiguous titles fail with a candidate list — re-run with the cuid.
-
-```bash
-lumo doc sync cmd_xxx
-lumo doc sync "Quarterly Plan"
-```
-
-Output:
-
-```
-Synced cmd_xxx "Quarterly Plan" from Google
-```
-
-### When to suggest `doc sync`
-
-- User says "re-sync the Google Doc", "pull the latest from Google", "refresh the imported doc".
-- After the user mentions the Google Doc changed upstream. Warn first that local Lumo edits to that doc will be overwritten (one-way, destructive).
-
-### Out of scope (CLI v1)
-
-The CLI does **not** currently support:
-
-- `--from-editor` (interactive $EDITOR).
-- Lossless markdown round-trip from **rendered** `doc show` output (use `doc show --raw` — lossless whenever a markdown source is stored).
-- Reordering siblings within the same parent (`--before` / `--after`); use the Web UI for that.
-
-### When to suggest session binding for docs
-
-If user creates a doc with `--task LUM-N` and the current Claude Code session is not bound, suggest `lumo session attach LUM-N` so subsequent hook events also tag that task.