@lumoai/cli 1.15.0 → 1.17.0

package/README.md

@@ -24,7 +24,7 @@ npx @lumoai/cli setup
 
 The command interactively asks whether to install for the current user (`~/.claude/`) or just the current project (`./.claude/`), then:
 
-1. Drops the `SKILL.md` into `.claude/skills/lumo/`
+1. Drops the skill files (`SKILL.md` + `references/`) into `.claude/skills/lumo/`
 2. Idempotently merges 25 Lumo hook handlers into `.claude/settings.json` (existing hooks and permissions are preserved)
 3. Prints any remaining steps (global install, `lumo auth login`)
 
@@ -91,18 +91,18 @@ lumo task update LUM-42 --status done
 
 ## Commands
 
-| Group       | Highlights                                                             |
-| ----------- | ---------------------------------------------------------------------- |
-| `setup`     | Install SKILL.md + hooks into `~/.claude/` or `./.claude/`             |
-| `auth`      | `login`, `logout`                                                      |
-| `whoami`    | Show current identity + workspace                                      |
-| `update`    | Self-update to the latest npm release                                  |
-| `task`      | `create`, `update`, `list`, `show`, `comment`, `context`               |
-| `session`   | `attach`, `status`, `detach` (binds Claude Code sessions)              |
-| `project`   | `list`                                                                 |
-| `milestone` | `create`, `update`, `list`, `show`, `delete`                           |
-| `sprint`    | `create`, `start`, `close`, `list`, `show`, `add`, `remove`, `summary` |
-| `doc`       | `create`, `update`, `list`, `show`, `move`, `bind`, `share`            |
+| Group       | Highlights                                                                             |
+| ----------- | -------------------------------------------------------------------------------------- |
+| `setup`     | Install skill files (SKILL.md + references/) + hooks into `~/.claude/` or `./.claude/` |
+| `auth`      | `login`, `logout`                                                                      |
+| `whoami`    | Show current identity + workspace                                                      |
+| `update`    | Self-update to the latest npm release                                                  |
+| `task`      | `create`, `update`, `list`, `show`, `comment`, `context`                               |
+| `session`   | `attach`, `status`, `detach` (binds Claude Code sessions)                              |
+| `project`   | `list`                                                                                 |
+| `milestone` | `create`, `update`, `list`, `show`, `delete`                                           |
+| `sprint`    | `create`, `start`, `close`, `list`, `show`, `add`, `remove`, `summary`                 |
+| `doc`       | `create`, `update`, `list`, `show`, `move`, `bind`, `share`                            |
 
 Every command accepts `--help` for full flags and examples:
 

package/assets/skill/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: lumo
+description: 'Use the Lumo CLI to load task context, manage session bindings, and run tasks / projects / milestones / sprints / docs / memory from the terminal. Activate when: the user mentions a Lumo task identifier (LUM-42 etc.), asks to load task background/context, wants to bind/check/detach a Claude Code session''s task, is about to start work on a task, or wants to create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, or memory. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "which task", "what task am I on", "work on LUM", "session wrap", "wrap up session", "进度评论", "卡住检测", "create task", "new task", "file a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "update task", "change task status", "rename task", "reassign task", "mark task as done", "lumo next", "next task", "what should I work on", "推荐下一个任务", "list projects", "what projects", "milestone", "里程碑", "list/create/update/delete/show milestone", "set milestone", "attach/unbind milestone", "tasks in milestone", "search milestones", "find milestone", "milestone health", "at-risk", "overdue", "archive/unarchive milestone", "归档里程碑", "milestone summary", "里程碑复盘", "reorder/move milestone", "排序里程碑", "milestone add/remove", "挂任务到里程碑", "auth login", "log in", "logout", "sign out", "switch account", "whoami", "who am I", "current workspace", "登录", "切换账号", "create/update/list/show/delete doc", "write doc", "写文档", "新建文档", "修改文档", "查看文档", "bind/unbind doc", "把文档关联到任务", "doc scope", "personal/workspace doc", "tag", "add/remove tag", "标签", "share/unshare doc", "分享文档", "doc share-list", "viewer/editor/manager", "doc tree", "doc move", "move/reparent doc", "移动文档", "sprint", "冲刺", "迭代", "create/list/show/update/delete sprint", "start/close sprint", "开始/关闭冲刺", "add to sprint", "active sprints", "sprint summary", "冲刺总结", "把任务挂到冲刺", "sprint health", "sprint risk", "is this sprint at risk", "冲刺风险", "冲刺健康度", "sprint blockers", "冲刺阻塞", "lumo update", "upgrade lumo", "升级 lumo", "new lumo version", "lumo setup", "install lumo skill/hooks", "wire up lumo", "set up lumo", "安装 lumo", "配置 lumo", "task artifact", "artifact add/list/show/update/rm", "spec artifact", "record/attach spec", "attach plan", "记录 spec", "查看 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design, "memory", "记忆", "remember", "record a memory", "记一条", "promote memory", "promote to project", "沉淀", "task/project memory", "retrieval", "取全文", "拉全文", "task slack show", "看 thread", "show slack thread", "task web show", "web 正文", "task figma context", "figma metadata", "task comments list", "list comments", "看评论", "task pr show", "查看 PR", "show pr", "PR 详情", "import google doc", "sync google doc", "google drive", "doc import-gdoc", "doc sync", "导入/同步 google 文档", "mark blocked", "blocked tag", "标记 blocked", "stuck", "repeatedly failing".'
+---
+
+## Prerequisites
+
+Before running any `lumo` command, verify the CLI is available and authenticated:
+
+```bash
+which lumo && lumo whoami
+```
+
+- If `lumo` is not found: tell the user to install it (`npm install -g @lumoai/cli`; for monorepo dev, `cd cli && npm install && npm link` also works)
+- If `lumo whoami` fails with an auth error: tell the user to run `lumo auth login`
+- Do NOT proceed with any lumo commands until both checks pass
+
+## How this skill is organized
+
+The command catalog below is a **map**: it lists every command grouped by domain with a one-line summary. **Detailed flags, examples, output formats, and "when to suggest" guidance live in the `references/` files** — when a user request lands in a domain, **Read the matching reference file before composing the command**. Don't run a command from memory if its flags/edge-cases matter; open the reference first.
+
+| Domain                                                                            | Read this reference                                            |
+| --------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `setup`, `auth login/logout`, `whoami`, `update`                                  | [references/onboarding.md](references/onboarding.md)           |
+| `task context`, retrieval (`slack/web/figma context`, `comments list`, `pr show`) | [references/task-context.md](references/task-context.md)       |
+| `task create/update/list/show/comment`, `next`                                    | [references/tasks.md](references/tasks.md)                     |
+| `task artifact*`, `task figma*`                                                   | [references/artifacts-figma.md](references/artifacts-figma.md) |
+| `project list`, `milestone*`                                                      | [references/milestones.md](references/milestones.md)           |
+| `doc*`                                                                            | [references/docs.md](references/docs.md)                       |
+| `sprint*`                                                                         | [references/sprints.md](references/sprints.md)                 |
+| `task/project memory`, `memory promote/rm`                                        | [references/memory.md](references/memory.md)                   |
+| `session attach/status/detach/wrap`, auto-bind, Layer-2 review                    | [references/sessions.md](references/sessions.md)               |
+
+## Command catalog
+
+**Onboarding / auth / update** — see [onboarding.md](references/onboarding.md)
+
+- `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill files + hooks
+- `lumo auth login` / `lumo auth logout` — paste an API key / clear credentials
+- `lumo whoami` — show current identity (email, workspace, key)
+- `lumo update` — upgrade the CLI to the latest npm release
+
+**Task context & retrieval** — see [task-context.md](references/task-context.md)
+
+- `lumo task context <id>` — load task background (memory, source cards, PR review todos, prior sessions)
+- `lumo task slack show <id> <contextId>` — full stored Slack thread
+- `lumo task web show <id> <linkId>` — fetched web link body
+- `lumo task figma context <id> <linkId>` — Figma link metadata (v1)
+- `lumo task comments list <id>` — full comment thread (read-only; ≠ `task comment`)
+- `lumo task pr show <id> <number>` — synced PR metadata (v1)
+
+**Tasks** — see [tasks.md](references/tasks.md)
+
+- `lumo task create <title> [flags]` — create a task
+- `lumo task update <id> [flags]` — patch status/title/priority/assignee/milestone/sprint/tags
+- `lumo task list [flags]` — list tasks assigned to you
+- `lumo next [--count N]` — recommend the next task to work on (read-only)
+- `lumo task show <id>` — print one task's detail
+- `lumo task comment <id> <body>` — leave a comment
+
+**Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
+
+- `lumo task artifact add/update/list/show/rm` — record spec/plan products on a task
+- `lumo task figma add/list/rm/refresh` — attach & manage Figma designs
+
+**Projects & milestones** — see [milestones.md](references/milestones.md)
+
+- `lumo project list` — list projects (slugs feed `--project`)
+- `lumo milestone list/create/show/update/delete` — milestone CRUD (`show` includes a Sprint-coverage section)
+- `lumo milestone archive/unarchive` — soft-archive / restore
+- `lumo milestone add/remove <id> <task...>` — batch bind/unbind tasks
+- `lumo milestone summary [--retry]` — AI retro
+- `lumo milestone reorder/move` — manual ordering
+
+**Documents** — see [docs.md](references/docs.md)
+
+- `lumo doc create/update/show/list/delete` — document CRUD
+- `lumo doc move` — reparent under a parent / to root
+- `lumo doc bind/unbind <doc> <task>` — task linkage
+- `lumo doc share/unshare/share-list` — member sharing
+- `lumo doc import-gdoc` / `lumo doc sync` — Google Doc import & re-sync
+
+**Sprints** — see [sprints.md](references/sprints.md)
+
+- `lumo sprint list/create/show/update/delete` — sprint CRUD (`show` includes Progress / Health / Blockers)
+- `lumo sprint start/close` — status transitions (no `--status` flag)
+- `lumo sprint add/remove <id> <task>` — bind/unbind a task
+- `lumo sprint summary [--retry]` — AI retro
+
+**Memory** — see [memory.md](references/memory.md)
+
+- `lumo task memory add/list` · `lumo project memory add/list` — record/curate Memory (TASK vs PROJECT)
+- `lumo memory promote <id>` / `lumo memory rm <id> --yes` — TASK→PROJECT / delete
+
+**Sessions** — see [sessions.md](references/sessions.md)
+
+- `lumo session attach <id>` — bind this session to a task (then run `task context`)
+- `lumo session status` / `lumo session detach` — show / clear binding
+- `lumo session wrap [--yes] [--dry-run]` — end-of-session panel: progress comment + memory review + blocked-tag prompt
+- Auto-bind at session start + Layer-2 project-memory review — see the reference
+
+## Core workflow
+
+Typical flow when a user says "help me with LUM-42":
+
+1. `lumo session attach LUM-42` — bind this session
+2. `lumo task context LUM-42` — load background
+3. Review unresolved items, PR-review todos, and the task description
+4. Begin working on the task
+
+**Auto-bind:** session-start may already bind the task from the git branch / recent commits and print `已自动绑定 LUM-N …`. If the user says "不是"/"不对"/"wrong task", run `lumo session detach` (then `session attach <LUM-N>` if they name the right one). See [sessions.md](references/sessions.md) for the full session-start behavior.

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

@@ -0,0 +1,124 @@
+# 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) 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/docs.md

@@ -0,0 +1,306 @@
+# 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", "起一篇 RFC", "新建文档", 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>` — print one document's detail
+
+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"
+```
+
+Note: the markdown rendered by `doc show` is best-effort. Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT guaranteed to be a no-op.
+
+Use when the user wants the current state or content of a doc without loading full task context.
+
+### `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", "把文档 X 挂到 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", "把文档分享给 Y"
+- 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", "把这篇 Google 文档导入".
+- 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", "更新一下从 Google 导入的文档".
+- 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.
+- 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.