@lumoai/cli 1.4.0 → 1.5.1

package/assets/skill.md

@@ -1,6 +1,6 @@
 ---
 name: lumo
-description: 'Use the Lumo CLI to load task context, manage session bindings, inspect projects and milestones, and create/update/list/show/comment on tasks from the terminal. Activate when: user mentions a Lumo task identifier (LUM-42, LUM-12, etc.), asks to load task background or context, wants to bind, check, or detach a Claude Code session''s task binding, is about to start development work on a specific task, wants to create a new task, list their tasks, view a task, comment on a task, list projects, list milestones, attach a task to a milestone, or update a task''s status/title/description/priority/assignee/milestone. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "bind session", "unbind session", "which task", "what task am I on", "work on LUM", "create task", "new task", "add task", "file a task", "log a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "leave a comment", "list projects", "what projects", "update task", "change task status", "rename task", "reassign task", "mark task as done", "milestone", "里程碑", "list milestones", "set milestone", "挂到 milestone", "attach milestone", "unbind milestone", "create milestone", "new milestone", "update milestone", "change milestone status", "delete milestone", "show milestone", "view milestone", "tasks in milestone", "milestone tasks", "新建里程碑", "更新里程碑", "删除里程碑", "查看里程碑", "auth login", "log in", "login", "auth logout", "log out", "logout", "sign out", "switch account", "switch identity", "whoami", "who am I", "current identity", "current user", "current workspace", "登录", "登出", "切换账号", "当前身份", "create doc", "new doc", "new document", "write doc", "写文档", "新建文档", "update doc", "edit doc", "修改文档", "更新文档", "list docs", "my docs", "我的文档", "show doc", "view doc", "查看文档", "delete doc", "删除文档", "bind doc", "attach doc to task", "把文档关联到任务", "文档绑定到任务", "unbind doc", "解绑文档", "personal doc", "workspace doc", "个人文档", "workspace 文档", "doc scope", "tag", "add tag", "remove tag", "标签", "添加标签", "移除标签", "doc tag", "task tag", "share doc", "doc share", "share document", "分享文档", "文档分享", "unshare doc", "remove share", "取消分享", "share list", "list doc shares", "who has access", "viewer", "editor", "manager", "shared with", "doc tree", "doc move", "move doc", "reparent doc", "文档树", "移动文档", "sprint", "start sprint", "close sprint", "add to sprint", "active sprints", "冲刺", "迭代", "开始冲刺", "关闭冲刺", "create sprint", "new sprint", "list sprints", "show sprint", "update sprint", "delete sprint", "sprint summary", "sprint retro", "把任务挂到冲刺", "冲刺里有什么", "lumo update", "update cli", "upgrade lumo", "update lumo", "upgrade cli", "升级 lumo", "更新 cli", "new lumo version", "是否有新版本", "lumo setup", "install lumo skill", "install lumo hooks", "wire up lumo", "set up lumo", "onboard lumo", "npx @lumoai/cli", "安装 lumo", "配置 lumo", "lumo 初始化", "task artifact", "artifact add", "artifact list", "artifact show", "artifact rm", "artifact delete", "artifact update", "update artifact", "edit artifact", "change artifact kind", "change artifact source", "remove artifact", "delete artifact", "spec artifact", "record spec", "attach spec", "attach plan", "记录 spec", "挂 spec", "查看 artifact", "编辑 artifact", "修改 artifact", "删除 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design.'
+description: 'Use the Lumo CLI to load task context, manage session bindings, inspect projects and milestones, and create/update/list/show/comment on tasks from the terminal. Activate when: user mentions a Lumo task identifier (LUM-42, LUM-12, etc.), asks to load task background or context, wants to bind, check, or detach a Claude Code session''s task binding, is about to start development work on a specific task, wants to create a new task, list their tasks, view a task, comment on a task, list projects, list milestones, attach a task to a milestone, or update a task''s status/title/description/priority/assignee/milestone. Triggers on: "LUM-", "task context", "load context", "session start", "session attach", "session status", "session detach", "bind session", "unbind session", "which task", "what task am I on", "work on LUM", "create task", "new task", "add task", "file a task", "log a task", "list tasks", "my tasks", "show task", "view task", "comment on task", "leave a comment", "list projects", "what projects", "update task", "change task status", "rename task", "reassign task", "mark task as done", "milestone", "里程碑", "list milestones", "set milestone", "挂到 milestone", "attach milestone", "unbind milestone", "create milestone", "new milestone", "update milestone", "change milestone status", "delete milestone", "show milestone", "view milestone", "tasks in milestone", "milestone tasks", "新建里程碑", "更新里程碑", "删除里程碑", "查看里程碑", "auth login", "log in", "login", "auth logout", "log out", "logout", "sign out", "switch account", "switch identity", "whoami", "who am I", "current identity", "current user", "current workspace", "登录", "登出", "切换账号", "当前身份", "create doc", "new doc", "new document", "write doc", "写文档", "新建文档", "update doc", "edit doc", "修改文档", "更新文档", "list docs", "my docs", "我的文档", "show doc", "view doc", "查看文档", "delete doc", "删除文档", "bind doc", "attach doc to task", "把文档关联到任务", "文档绑定到任务", "unbind doc", "解绑文档", "personal doc", "workspace doc", "个人文档", "workspace 文档", "doc scope", "tag", "add tag", "remove tag", "标签", "添加标签", "移除标签", "doc tag", "task tag", "share doc", "doc share", "share document", "分享文档", "文档分享", "unshare doc", "remove share", "取消分享", "share list", "list doc shares", "who has access", "viewer", "editor", "manager", "shared with", "doc tree", "doc move", "move doc", "reparent doc", "文档树", "移动文档", "sprint", "start sprint", "close sprint", "add to sprint", "active sprints", "冲刺", "迭代", "开始冲刺", "关闭冲刺", "create sprint", "new sprint", "list sprints", "show sprint", "update sprint", "delete sprint", "sprint summary", "sprint retro", "把任务挂到冲刺", "冲刺里有什么", "lumo update", "update cli", "upgrade lumo", "update lumo", "upgrade cli", "升级 lumo", "更新 cli", "new lumo version", "是否有新版本", "lumo setup", "install lumo skill", "install lumo hooks", "wire up lumo", "set up lumo", "onboard lumo", "npx @lumoai/cli", "安装 lumo", "配置 lumo", "lumo 初始化", "task artifact", "artifact add", "artifact list", "artifact show", "artifact rm", "artifact delete", "artifact update", "update artifact", "edit artifact", "change artifact kind", "change artifact source", "remove artifact", "delete artifact", "spec artifact", "record spec", "attach spec", "attach plan", "记录 spec", "挂 spec", "查看 artifact", "编辑 artifact", "修改 artifact", "删除 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design, "memory", "记忆", "remember", "record a memory", "记一条", "promote memory", "promote to project", "沉淀", "task memory", "project memory", "lumo memory", "retrieval", "取全文", "load full content", "拉全文", "task slack show", "看 thread", "看 slack thread", "show slack thread", "slack 全文", "task web show", "show web link body", "web 正文", "抓网页正文", "task figma context", "figma metadata", "figma 元数据", "figma 设计上下文", "task comments list", "list comments", "看评论", "评论流", "task pr show", "查看 PR", "show pr", "PR 详情", "pr metadata", "import google doc", "sync google doc", "google drive", "doc import-gdoc", "doc sync", "导入 google 文档", "同步 google 文档".'
 ---
 
 ## Prerequisites
@@ -17,15 +17,18 @@ which lumo && lumo whoami
 
 ## Onboarding
 
-### `lumo setup [--user|--project] [--force]` — install skill + hooks
+### `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill + hooks
 
-Bootstraps Lumo into a Claude Code installation. Copies the bundled `SKILL.md` into `<scope>/.claude/skills/lumo/` and idempotently merges 25 hook entries into `<scope>/.claude/settings.json`. Existing user permissions and non-Lumo hook entries are preserved.
+Bootstraps Lumo into a coding-agent installation. Copies the bundled `SKILL.md` into `<scope>/.claude/skills/lumo/` and idempotently merges 25 hook entries into `<scope>/.claude/settings.json`. Existing user permissions and non-Lumo hook entries are preserved.
+
+`--agent <token>` records which coding agent these hooks run under and is **baked into every hook command** (`lumo hook <slug> --agent <token>`). Each hook then sends the agent to the server, where it's stored on the Session and inherited by auto-sedimented memories — so a memory is attributed to the agent that produced it instead of the default. Valid tokens: `claude-code | codex | cursor | gemini-cli | github-copilot | windsurf` (case-insensitive; `gemini` and `copilot` are accepted aliases). **Defaults to `claude-code`.** Re-running setup with a different `--agent` rewrites the token in place (no duplicate hook entries), and a legacy flagless entry is upgraded on the next run.
 
 ```bash
-npx @lumoai/cli setup           # interactive: prompts user/project
-npx @lumoai/cli setup --user    # write to ~/.claude/
-npx @lumoai/cli setup --project # write to ./.claude/
-npx @lumoai/cli setup --force   # overwrite SKILL.md if it differs from bundled
+npx @lumoai/cli setup                    # interactive: prompts user/project; agent=claude-code
+npx @lumoai/cli setup --user             # write to ~/.claude/
+npx @lumoai/cli setup --project          # write to ./.claude/
+npx @lumoai/cli setup --force            # overwrite SKILL.md if it differs from bundled
+npx @lumoai/cli setup --agent codex      # bake agent=codex into the hook commands
 ```
 
 Use when:
@@ -33,8 +36,9 @@ Use when:
 - The user asks "how do I set up lumo", "install the lumo skill", "wire up lumo hooks"
 - A fresh checkout of a project that uses Lumo doesn't have `.claude/skills/lumo/SKILL.md` yet
 - After `npm install -g @lumoai/cli`, before the first `lumo auth login`
+- Wiring Lumo into a non-Claude-Code agent (Codex / Cursor / …) — pass `--agent <token>` so its memories are attributed correctly
 
-If stdin is not a TTY (CI, piped invocation), the default scope is `project` and no prompt is shown.
+If stdin is not a TTY (CI, piped invocation), the default scope is `project` and no prompt is shown. An unrecognized `--agent` token aborts before writing anything.
 
 ## Authentication
 
@@ -129,6 +133,83 @@ The command prints a markdown document to stdout containing:
 - Focus on the **most recent 1–2 sessions** for relevant state; older sessions are for historical reference only
 - If there are **no prior sessions**, this is a fresh start — read the task description carefully and ask clarifying questions if needed
 
+## Context Retrieval (按需取全文)
+
+LUM-122 split task context injection into tiers. `lumo task context <LUM-N>`
+now emits a **cheap inline card** for each source — a short summary or just
+metadata — instead of dumping full bodies. Slack, docs, artifacts, and comments
+get an **LLM summary**; web links, Figma, and PRs get **metadata only**. Each
+card ends with the **retrieval command** you run to pull the heavy content on
+demand.
+
+**How to use it:** when the inline card is not enough and you need the full
+Slack thread, the web page body, the Figma metadata, the entire comment thread,
+or the PR detail — run the matching command below. Pass the same identifier
+(`LUM-N`) plus the id the card shows for that source (a Slack `contextId`, a web
+`linkId`, a Figma `linkId`, or a PR `number`).
+
+All five are **read-only** (no live Slack/GitHub/Figma calls except the web body
+fetch). Web/Figma/PR are v1 metadata-degraded: they print a `note:` explaining
+that live content needs an external integration.
+
+### `lumo task slack show <identifier> <contextId>` — full Slack thread snapshot
+
+Prints the **stored** thread snapshot (no live Slack call), one line per message
+as `author: text`. Author falls back to `@<userId>` when the display name is
+missing. Empty snapshot prints `(no messages in stored snapshot)`.
+
+```bash
+lumo task slack show LUM-42 ctx_abc123
+```
+
+### `lumo task web show <identifier> <linkId>` — fetched web link body
+
+Fetches the page body on demand behind the SSRF guard (cached after first read)
+and prints it as plain text. Empty body prints `(empty body)`. Fetch failures
+(blocked host, timeout) print the server's error message.
+
+```bash
+lumo task web show LUM-42 wl_abc123
+```
+
+### `lumo task figma context <identifier> <linkId>` — Figma link metadata
+
+**v1 metadata fallback.** Prints the cached design metadata as `file:` /
+`frame:` / `url:` / `synced:` (and `syncError:` if the last sync failed) lines.
+Live design context (layers, variables, code connect) requires the Figma MCP
+server, so the command ends with a `note:` saying so.
+
+```bash
+lumo task figma context LUM-42 cfl_abc123
+```
+
+### `lumo task comments list <identifier>` — full comment thread
+
+Prints the **entire** comment thread: each comment as `author · createdAt`
+followed by its plain-text body (comment bodies are stored as HTML and stripped
+to text). Replies are indented two spaces under their parent. Author falls back
+to `unknown`. No comments prints `(no comments)`.
+
+```bash
+lumo task comments list LUM-42
+```
+
+**Plural, and distinct from `task comment`.** `task comments list` _reads_ the
+whole thread (this retrieval command). `task comment <identifier> <body>`
+_writes_ a single new comment (see Task Management). Don't confuse the two —
+the plural `comments` is read-only.
+
+### `lumo task pr show <identifier> <number>` — synced PR metadata
+
+**v1 metadata fallback.** Prints the synced PR record: a `#<number> (repo)
+title` header, then `state:` (with ` · draft` when draft), `ci:`, `author:`,
+`branch: <head> → <base>`, and `url:` lines. The live diff + review comments
+require the GitHub integration, so the command ends with a `note:` saying so.
+
+```bash
+lumo task pr show LUM-42 128
+```
+
 ## Task Management
 
 ### `lumo task create <title> [flags]` — create a new task
@@ -299,32 +380,35 @@ The CLI does not support @-mention chip syntax. If the user wants to ping someon
 
 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>`
+#### `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.
 
-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.
+`--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
-lumo task artifact add LUM-42 --kind plan --title "Implementation plan" --file docs/plan.md --source "Spec Kit"
+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>]`
+#### `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`, and `source`** only — **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`.
+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>  <source>  <title>`. Prints `No artifacts on <task>` when there are none.
+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
@@ -332,7 +416,7 @@ lumo task artifact list LUM-42
 
 #### `lumo task artifact show <task> <artifact-id>`
 
-Prints one artifact's key:value header (id, kind, title, source, order, task) followed by the full content body. The `<artifact-id>` is the cuid in column 1 of `artifact list`.
+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
@@ -515,7 +599,7 @@ Use this when the user wants to write a new document from the terminal. Title is
 | `--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.
+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:
 
@@ -563,6 +647,8 @@ The `Tags:` line is omitted when no tags were attached.
 
 `--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
@@ -731,6 +817,63 @@ lumo doc share-list "RFC"
 - 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:
@@ -886,6 +1029,74 @@ lumo sprint remove 3 LUM-48
 
 When to suggest: user says "remove LUM-48 from the sprint", "take this task out of sprint 3", "move task to backlog".
 
+## Memory management
+
+Record and curate the long-term Memory that Claude reads on future sessions.
+Memories are scoped **TASK** (useful only for one task) or **PROJECT** (useful
+across the whole project). Automated extraction (layer1) and promotion (layer2,
+on task→done) already run; these commands are the manual override.
+
+### Commands
+
+```bash
+# List
+lumo task memory list [LUM-N] [--category trap|decision|convention|procedural] [-n N]
+lumo project memory list [<project>] [--category ...] [-n N]
+
+# Add (per-category fields; <task>/<project> default to the session-bound task)
+lumo task memory add [LUM-N] --category trap --trigger "..." --outcome "..." [--workaround "..."] [--agent <agent>]
+lumo task memory add [LUM-N] --category decision --what "..." --why "..." [--alternatives "..."] [--implications "..."] [--agent <agent>]
+lumo task memory add [LUM-N] --category convention --rule "..." --applies "..." [--agent <agent>]
+lumo task memory add [LUM-N] --category procedural --workflow "..." --trigger "..." [--step "..." --step "..."] [--agent <agent>]
+lumo project memory add [<project>] --category ... [--agent <agent>]   # same flags; records at PROJECT scope
+
+# --agent values: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)
+# Aliases: gemini → gemini-cli, copilot → github-copilot (case-insensitive)
+# Omitting --agent records the memory as produced by Claude Code.
+
+# Single-memory ops (memoryId from `... memory list` column 1)
+lumo memory promote <memoryId>     # TASK → PROJECT
+lumo memory rm <memoryId> --yes    # hard delete
+```
+
+When the session is bound (`lumo session attach <LUM-N>`), omit the identifier:
+`lumo task memory add --category trap --trigger ... --outcome ...` records onto
+the bound task; `lumo project memory add ...` records onto its project.
+
+### When to record a memory (worthiness)
+
+Record only knowledge that is **invisible in the codebase** — the _why_ behind a
+choice, a gotcha that only surfaces at runtime, a rule that lives in people's
+heads, a non-obvious failure cause, a non-trivial workflow. **Skip** routine work
+(reading files, plain edits, normal git, successful builds) and anything a
+developer could learn from the source, git log, or docs. When unsure, don't.
+
+### Which category
+
+- `trap` — a pitfall. Describe the PROBLEM ONLY (`--trigger`, `--outcome`); put any fix in a separate `procedural`.
+- `decision` — an engineering decision (`--what` + `--why`, optional `--alternatives`/`--implications`).
+- `convention` — a team rule (`--rule` + `--applies` = where it applies).
+- `procedural` — a reusable workflow (`--workflow` + `--trigger` + `--step`…).
+
+### TASK vs PROJECT (at add time)
+
+Default to **TASK** (`lumo task memory add`). Record directly to **PROJECT**
+(`lumo project memory add`) only when it helps _any_ task in the project: a
+toolchain/environment trap, a team-wide convention, a cross-task decision. When
+unsure → TASK.
+
+### When to promote (TASK → PROJECT)
+
+`lumo memory promote <id>` only when the lesson **recurs across 2+ different
+tasks**, would help a _different_ task, and no equivalent PROJECT memory exists.
+A wrong promotion is costly (every agent sees it forever) — prefer leaving it at TASK.
+
+### When to reach for this
+
+After a non-trivial debugging session, a pitfall you hit, or establishing a
+convention → consider `lumo task memory add`. When you notice a lesson recurring
+across multiple tasks → consider `lumo memory promote`.
+
 ## Session Management
 
 ### `lumo session attach <identifier>` — bind the current session to a task

package/dist/cli/src/commands/auth-login.js

@@ -5,6 +5,7 @@ const prompt_1 = require("../lib/prompt");
 const browser_1 = require("../lib/browser");
 const api_1 = require("../lib/api");
 const config_1 = require("../lib/config");
+const sanitize_1 = require("../lib/sanitize");
 const KEY_PREFIX = 'lum_';
 async function authLogin() {
     const apiUrl = (0, api_1.resolveApiUrl)();
@@ -49,7 +50,7 @@ async function authLogin() {
         apiKeyPrefix: resp.apiKey.prefix,
     });
     console.log('');
-    console.log(`✓ Logged in as ${resp.user.email}`);
-    console.log(`  Workspace: ${resp.workspace.name}`);
-    console.log(`  Key: ${resp.apiKey.name} (${resp.apiKey.prefix})`);
+    console.log(`✓ Logged in as ${(0, sanitize_1.sanitizeField)(resp.user.email)}`);
+    console.log(`  Workspace: ${(0, sanitize_1.sanitizeField)(resp.workspace.name)}`);
+    console.log(`  Key: ${(0, sanitize_1.sanitizeField)(resp.apiKey.name)} (${resp.apiKey.prefix})`);
 }

package/dist/cli/src/commands/auth-logout.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.authLogout = authLogout;
 const config_1 = require("../lib/config");
+const sanitize_1 = require("../lib/sanitize");
 async function authLogout() {
     const creds = (0, config_1.readCredentials)();
     if (!creds) {
@@ -10,5 +11,5 @@ async function authLogout() {
     }
     const email = creds.email;
     (0, config_1.deleteCredentials)();
-    console.log(`✓ Logged out (${email})`);
+    console.log(`✓ Logged out (${(0, sanitize_1.sanitizeField)(email)})`);
 }

package/dist/cli/src/commands/doc-bind.js

@@ -5,6 +5,7 @@ exports.docBind = docBind;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
 function formatBindOutput(args) {
     if (args.alreadyBound)
         return `Already bound ${args.docId} ↔ ${args.identifier}`;
@@ -21,8 +22,7 @@ async function docBind(docRef, task) {
         console.error('Error: not logged in. Run `lumo auth login` first.');
         return 1;
     }
-    const envUrl = process.env.LUMO_API_URL?.trim();
-    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
     const docId = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, docRef);
     if (!docId) {
         console.error(`Error: Document not found: ${docRef}`);
@@ -39,7 +39,7 @@ async function docBind(docRef, task) {
     });
     if (!res.ok) {
         const text = await res.text();
-        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }
     const { mention } = (await res.json());

package/dist/cli/src/commands/doc-create.js

@@ -8,6 +8,7 @@ const api_1 = require("../lib/api");
 const doc_input_1 = require("../lib/doc-input");
 const tag_resolver_1 = require("../lib/tag-resolver");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
 /** personal → PRIVATE, workspace → WORKSPACE. Null on unknown. */
 function normalizeScope(value) {
     const lower = (value ?? '').toLowerCase();
@@ -18,10 +19,10 @@ function normalizeScope(value) {
     return null;
 }
 function formatCreatedDocLine(doc) {
-    const escaped = doc.title.replace(/"/g, '\\"');
+    const escaped = (0, sanitize_1.sanitizeField)(doc.title).replace(/"/g, '\\"');
     const head = `Created ${doc.id} "${escaped}"  ${doc.url}`;
     if (doc.tags && doc.tags.length > 0) {
-        return `${head}\nTags: ${doc.tags.join(', ')}`;
+        return `${head}\nTags: ${doc.tags.map(sanitize_1.sanitizeField).join(', ')}`;
     }
     return head;
 }
@@ -54,8 +55,7 @@ async function docCreate(title, opts) {
         console.error(`Error: ${content.message}`);
         return 1;
     }
-    const envUrl = process.env.LUMO_API_URL?.trim();
-    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
     const url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents`;
     let tagIds;
     if ((opts.tag && opts.tag.length > 0) ||
@@ -106,7 +106,7 @@ async function docCreate(title, opts) {
     }
     if (!res.ok) {
         const text = await res.text();
-        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }
     const { document } = (await res.json());

package/dist/cli/src/commands/doc-delete.js

@@ -5,6 +5,7 @@ const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const resolve_doc_1 = require("../lib/resolve-doc");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
 async function docDelete(reference, opts) {
     if (!reference) {
         console.error('Error: missing <doc>. Usage: lumo doc delete <doc> --yes');
@@ -19,8 +20,7 @@ async function docDelete(reference, opts) {
         console.error('Error: not logged in. Run `lumo auth login` first.');
         return 1;
     }
-    const envUrl = process.env.LUMO_API_URL?.trim();
-    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
     // For a cuid reference we don't have the title; for a title we look up id+title at once.
     let id;
     let title = '';
@@ -44,9 +44,9 @@ async function docDelete(reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
-        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }
-    const escaped = title.replace(/"/g, '\\"');
+    const escaped = (0, sanitize_1.sanitizeField)(title).replace(/"/g, '\\"');
     console.log(`Deleted ${id}${title ? ` "${escaped}"` : ''}`);
 }

package/dist/cli/src/commands/doc-import-gdoc.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatImportedLine = formatImportedLine;
+exports.docImportGdoc = docImportGdoc;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const sanitize_1 = require("../lib/sanitize");
+function formatImportedLine(doc) {
+    const escaped = (0, sanitize_1.sanitizeField)(doc.title).replace(/"/g, '\\"');
+    return (`Imported ${doc.id} "${escaped}"  ${doc.url}\n` +
+        `Note: imported content follows Lumo sharing and is no longer gated by Google permissions.`);
+}
+function normalizeScope(value) {
+    if (value === undefined)
+        return undefined;
+    const lower = value.toLowerCase();
+    if (lower === 'personal')
+        return 'PRIVATE';
+    if (lower === 'workspace')
+        return 'WORKSPACE';
+    return undefined;
+}
+async function docImportGdoc(url, opts) {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    if (!url || url.trim().length === 0) {
+        console.error('Error: a Google Doc URL or id is required.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const base = (0, api_1.trimTrailingSlash)(apiUrl);
+    const body = { url: url.trim() };
+    const scope = normalizeScope(opts.scope);
+    if (scope)
+        body.visibility = scope;
+    let res;
+    try {
+        res = await fetch(`${base}/api/documents/import-google`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        console.error(`Error: network failure: ${err.message}`);
+        return 1;
+    }
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
+        return 1;
+    }
+    const { document } = (await res.json());
+    const fullUrl = `${base}/workspace/${creds.workspaceSlug ?? 'lumo'}/documents/${document.slug}`;
+    console.log(formatImportedLine({
+        id: document.id,
+        title: document.title,
+        url: fullUrl,
+    }));
+    if (opts.task) {
+        const bindRes = await fetch(`${base}/api/documents/${document.id}/mentions`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ taskIdentifier: opts.task }),
+        });
+        if (!bindRes.ok) {
+            const text = await bindRes.text();
+            console.error(`Warning: imported but bind to ${opts.task} failed: ${bindRes.status} ${(0, sanitize_1.sanitizeField)(text)}`);
+            return 1;
+        }
+        console.log(`Bound ${document.id} ↔ ${opts.task}`);
+    }
+}

package/dist/cli/src/commands/doc-list.js

@@ -7,6 +7,7 @@ const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const doc_create_1 = require("./doc-create");
 const doc_tree_1 = require("../lib/doc-tree");
+const sanitize_1 = require("../lib/sanitize");
 function visibilityLabel(v) {
     if (v === 'PRIVATE')
         return 'PERSONAL';
@@ -17,8 +18,8 @@ function formatDocListRows(rows) {
         return [];
     return rows.map(r => {
         const label = visibilityLabel(r.visibility).padEnd(10, ' ');
-        const project = (r.project?.name ?? '-').padEnd(14, ' ');
-        return `${r.id}  ${label}  ${project}  ${r.title}`;
+        const project = (0, sanitize_1.sanitizeField)(r.project?.name ?? '-').padEnd(14, ' ');
+        return `${r.id}  ${label}  ${project}  ${(0, sanitize_1.sanitizeField)(r.title)}`;
     });
 }
 function formatDocListRowsAsTree(rows) {
@@ -28,9 +29,9 @@ function formatDocListRowsAsTree(rows) {
     const flat = (0, doc_tree_1.flattenWithDepth)(tree);
     return flat.map(({ row, depth }) => {
         const label = visibilityLabel(row.visibility).padEnd(10, ' ');
-        const project = (row.project?.name ?? '-').padEnd(14, ' ');
+        const project = (0, sanitize_1.sanitizeField)(row.project?.name ?? '-').padEnd(14, ' ');
         const indent = '  '.repeat(depth);
-        return `${row.id}  ${label}  ${project}  ${indent}${row.title}`;
+        return `${row.id}  ${label}  ${project}  ${indent}${(0, sanitize_1.sanitizeField)(row.title)}`;
     });
 }
 async function docList(opts) {
@@ -39,8 +40,7 @@ async function docList(opts) {
         console.error('Error: not logged in. Run `lumo auth login` first.');
         return 1;
     }
-    const envUrl = process.env.LUMO_API_URL?.trim();
-    const apiUrl = envUrl && envUrl.length > 0 ? envUrl : creds.apiUrl;
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
     let url;
     if (opts.task) {
         url = `${(0, api_1.trimTrailingSlash)(apiUrl)}/api/tasks/${opts.task}/documents`;
@@ -65,7 +65,7 @@ async function docList(opts) {
     });
     if (!res.ok) {
         const text = await res.text();
-        console.error(`Error: ${res.status} ${res.statusText}: ${text}`);
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }
     const { documents } = (await res.json());