@lumoai/cli 1.15.0 → 1.18.0

package/assets/skill/references/memory.md

@@ -0,0 +1,69 @@
+# Memory Management
+
+## 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`.

package/assets/skill/references/milestones.md

@@ -0,0 +1,244 @@
+# Projects & Milestones
+
+### `lumo project list` — list projects in the workspace
+
+Prints `<slug>  <Display Name>` lines. The slug column matches the `--project <ref>` argument accepted by `task create`, so users (and you) can copy a slug straight from this output into a create command.
+
+```bash
+lumo project list
+```
+
+### `lumo milestone list [--project <ref>] [--archived] [--all] [--search <text>]` — list milestones in a project
+
+Prints fixed-width rows: `<STATUS>  <HEALTH>  <target-date or ->  <name>`, sorted by target date asc (nulls last) then created asc.
+
+By default, only **non-archived** milestones are listed. Use `--archived` to show **only** archived milestones, or `--all` to show **both** archived and non-archived. Archived rows are marked with a ` (archived)` suffix on the name.
+
+Use `--search <text>` to filter to milestones whose **name or description** contains the text (case-insensitive substring match). It applies **on top of** the archive filter (e.g. `--all --search q3`). A blank/whitespace-only value is ignored (no filtering). The matched text is bounded to 120 chars server-side.
+
+| Flag              | Type    | Notes                                                                                                             |
+| ----------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--project <ref>` | string  | Required when the workspace has more than one project. Name or slug, case-insensitive.                            |
+| `--archived`      | boolean | Show **only** archived milestones (instead of the default non-archived set).                                      |
+| `--all`           | boolean | Show **both** archived and non-archived milestones.                                                               |
+| `--search <text>` | string  | Filter by **name/description** case-insensitive substring. Combines with the archive filter; blank value ignored. |
+
+`HEALTH` is the target-date risk light, server-computed from the milestone's target date + task progress:
+
+- `ON-TRACK` — on schedule (or all tasks done)
+- `AT-RISK` — completion lags elapsed time, or (no start date) the target is within ~7 days with work remaining
+- `OVERDUE` — past the target date with tasks still open
+- `-` — no light applies (status `COMPLETED`/`CANCELLED`, or no target date)
+
+```bash
+lumo milestone list                  # one-project workspace (non-archived only)
+lumo milestone list --project lumo   # multi-project workspace
+lumo milestone list --archived       # only archived milestones
+lumo milestone list --all            # archived + non-archived (archived marked "(archived)")
+lumo milestone list --search q3      # name/description contains "q3" (case-insensitive)
+lumo milestone list --all --search launch   # search across archived + non-archived
+```
+
+`--project <ref>` is required when the workspace has more than one project (consistent with `task create --project`). Match is by project name or slug, case-insensitive.
+
+### When to suggest `milestone list`
+
+- Before suggesting `task create --milestone <ref>` or `task update --milestone <ref>` to confirm the milestone exists under the expected name.
+- When the user asks "what milestones do we have", "what's on v1.0", or similar.
+- When the user wants to **find/search milestones by keyword** ("find the launch milestone", "搜索里程碑", "which milestones mention X") — use `--search <text>` rather than listing all and eyeballing.
+
+When to suggest: before `task create --project <ref>` when the workspace has more than one project and the user hasn't specified which one.
+
+### `lumo milestone create <name>` — create a milestone
+
+| Flag                   | Type   | Notes                                   |
+| ---------------------- | ------ | --------------------------------------- |
+| `--project <ref>`      | string | Required when workspace has >1 project. |
+| `-d, --description <>` | string | Optional.                               |
+| `--start <date>`       | string | YYYY-MM-DD.                             |
+| `--target <date>`      | string | YYYY-MM-DD.                             |
+
+Examples:
+
+```bash
+lumo milestone create "Q3 Launch"
+lumo milestone create "Q3 Launch" --start 2026-06-01 --target 2026-08-31
+```
+
+On success: `Created milestone "Q3 Launch"  <id>`.
+
+### `lumo milestone show <identifier>` — show milestone detail + tasks
+
+Accepts UUID or name. With a name, `--project <ref>` is required when the workspace has >1 project.
+
+Prints a key:value header (name, status, **health**, dates, project, description), task counts, and the full task table under the milestone. The `Health:` line shows the same target-date risk light as `milestone list` (`ON-TRACK` / `AT-RISK` / `OVERDUE`, or `-` when none applies).
+
+It also prints a **Sprint coverage** section (above the task table) listing which
+sprints the milestone's tasks span — each row shows the sprint number, status, name,
+and `done/total` progress — plus an `未排期` line counting milestone tasks not in any
+sprint (shown only when there are any). The section is derived from the milestone's
+tasks (no schema relation), so it needs no extra flags. When no task is in any sprint
+it prints `Sprint coverage: (no sprint coverage)`.
+
+Example coverage section:
+
+```
+Sprint coverage:
+  #3  ACTIVE  Sprint 3   4/6 done
+  #4  DRAFT   Sprint 4   0/2 done
+  未排期                  1 task
+```
+
+```bash
+lumo milestone show "Q3 Launch"
+lumo milestone show 11111111-2222-3333-4444-555555555555
+```
+
+### `lumo milestone update <identifier>` — patch a milestone
+
+| Flag                   | Type   | Notes                                                            |
+| ---------------------- | ------ | ---------------------------------------------------------------- |
+| `--project <ref>`      | string | Required when identifier is a name and workspace has >1 project. |
+| `-n, --name <text>`    | string | Cannot be empty.                                                 |
+| `-d, --description <>` | string | `--description ""` clears.                                       |
+| `-s, --status <value>` | enum   | `planned \| active \| completed \| cancelled`.                   |
+| `--start <date>`       | string | `--start ""` clears.                                             |
+| `--target <date>`      | string | `--target ""` clears.                                            |
+
+At least one field required.
+
+```bash
+lumo milestone update "Q3 Launch" --status active
+lumo milestone update "Q3 Launch" --target 2026-09-15
+lumo milestone update "Q3 Launch" --description ""
+```
+
+### `lumo milestone delete <identifier>` — delete a milestone
+
+Requires `--yes`. No interactive prompt — CLI is agent-friendly. Tasks under the milestone keep their data; their `milestoneId` is cleared.
+
+```bash
+lumo milestone delete "Q3 Launch" --yes
+```
+
+### `lumo milestone archive <identifier>` — soft-archive a milestone
+
+Soft-archives a milestone by setting `archivedAt`. The milestone is **hidden from `milestone list` by default** (use `--archived` or `--all` to see it), but its **history and task links are preserved**, and the action is **reversible** via `milestone unarchive`. This is distinct from `milestone delete`, which is a **hard delete**. While archived, the milestone **rejects edits** (`milestone update`) and **new task bindings** (`task --milestone`, `milestone add`) with a 409 until it is restored. `<identifier>` accepts a UUID or name; `--project <ref>` is required when the identifier is a name and the workspace has >1 project.
+
+```bash
+lumo milestone archive "Q3 Launch"
+lumo milestone archive 11111111-2222-3333-4444-555555555555
+```
+
+### `lumo milestone unarchive <identifier>` — restore an archived milestone
+
+Restores an archived milestone by clearing `archivedAt`. It reappears in `milestone list` and can be edited and bound to tasks again. Idempotent — unarchiving an already-active milestone is a no-op. Same identifier / `--project` rules as `milestone archive`: `<identifier>` accepts a UUID or name; `--project <ref>` is required when the identifier is a name and the workspace has >1 project.
+
+```bash
+lumo milestone unarchive "Q3 Launch"
+```
+
+### `lumo milestone add <identifier> <task...>` — bind tasks to a milestone (batch)
+
+Binds **one or more** tasks to a milestone in a single call — the batch counterpart of `task update --milestone <ref>` (which only takes one task at a time). `<identifier>` accepts a milestone name or UUID; each `<task>` accepts `LUM-N` or a task UUID. `--project <ref>` is required when the identifier is a name and the workspace has >1 project.
+
+Task refs are deduped (case-insensitive, order preserved). Each task is PATCHed independently — **partial failures do not roll back**: a task that fails (e.g. not found, or its project has no milestone of that name) is reported on its own line while the rest still bind. Exit code is non-zero if **any** task failed.
+
+```bash
+lumo milestone add "Q3 Launch" LUM-1 LUM-2 LUM-3
+lumo milestone add 11111111-2222-3333-4444-555555555555 LUM-1 LUM-2
+```
+
+Output — a tally header (zero categories omitted) plus one line per task:
+
+```
+Q3 Launch: 2 added, 1 failed
+  ✓ LUM-1
+  ✓ LUM-2
+  ✗ LUM-3  no milestone matches "Q3 Launch" in this project. Try `lumo milestone list`.
+```
+
+### `lumo milestone remove <identifier> <task...>` — unbind tasks from a milestone (batch)
+
+Unbinds **one or more** tasks from a milestone in one call. A task that is **not currently in this milestone is skipped** (idempotent) — it is never reassigned away from a different milestone. `<identifier>` accepts a name or UUID; each `<task>` accepts `LUM-N` or a task UUID. `--project <ref>` is required when the identifier is a name and the workspace has >1 project.
+
+```bash
+lumo milestone remove "Q3 Launch" LUM-1 LUM-5
+```
+
+Output — `✓` removed, `-` skipped (not in milestone), `✗` failed:
+
+```
+Q3 Launch: 1 removed, 1 skipped
+  ✓ LUM-1
+  - LUM-5  not in this milestone
+```
+
+### When to suggest `milestone add` / `milestone remove`
+
+- The user wants to attach/detach **several** tasks to a milestone at once ("挂这几个任务到 Q3", "把 LUM-1 LUM-2 LUM-3 都放进里程碑", "remove these from the milestone"). For a single task, `task update --milestone <ref>` (or `--milestone ""` to clear) is equally fine.
+- `remove` only clears the binding for tasks actually in the named milestone, so it's safe to pass a broad list — anything not in it is reported as skipped, not clobbered.
+- For one-at-a-time sprint binding see `lumo sprint add / remove` (sprint batch is not yet supported).
+
+### `lumo milestone summary <identifier> [--retry]` — fetch AI-generated milestone retro
+
+Prints the AI-generated retrospective summary for a milestone (mirrors `sprint summary`). `<identifier>` accepts a milestone name or UUID; `--project <ref>` is required when the identifier is a name and the workspace has more than one project. When no summary exists yet the command prints `(no summary generated yet)`.
+
+A summary is generated automatically when a milestone transitions to `COMPLETED` (e.g. via `lumo milestone update <id> --status completed`). The generated report has sections `## Summary`, `## Delivered`, `## Outstanding` plus a one-line `tldr`. Use `--retry` to queue regeneration (e.g. after a failed generation) before fetching — regeneration is async, so the printed result may still be the previous summary or `(no summary generated yet)`.
+
+| Flag              | Type    | Notes                                                                                                  |
+| ----------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `--project <ref>` | string  | Project name or slug. Required when identifier is a name and the workspace has >1 project.             |
+| `--retry`         | boolean | Queue a regeneration (async, server returns 202) before fetching. Only valid on a COMPLETED milestone. |
+
+```bash
+lumo milestone summary "Q3 Launch"
+lumo milestone summary "Q3 Launch" --retry
+lumo milestone summary 11111111-2222-3333-4444-555555555555
+```
+
+When to suggest: user asks "summarize the milestone", "milestone retro", "give me a summary of the Q3 milestone", "里程碑总结", "里程碑复盘".
+
+### `lumo milestone reorder <ref...> [--project <ref>]` — set the full milestone order
+
+Reorders a project's milestones. Pass **every** milestone in the project (by name, case-insensitive, or its cuid) in the desired order — the command rewrites each milestone's `sortOrder` to match. An incomplete list (not every milestone named), an unknown ref, or a duplicate is rejected **before any network mutation**, with a message naming the offending / missing milestones.
+
+```bash
+lumo milestone reorder "Q3 Launch" "Beta" "Alpha"
+lumo milestone reorder "Q3 Launch" "Beta" "Alpha" --project backend
+```
+
+`--project <ref>` is required when the workspace has more than one project.
+
+Output:
+
+```
+Reordered 3 milestones:
+  1. Q3 Launch
+  2. Beta
+  3. Alpha
+```
+
+### `lumo milestone move <ref> --before <ref> | --after <ref> [--project <ref>]` — move one milestone
+
+Moves a single milestone immediately before or after a target milestone, leaving the rest in their current relative order. `--before` and `--after` are **mutually exclusive and exactly one is required** (the CLI errors before any network call if both or neither is given). Refs resolve by cuid or case-insensitive name.
+
+```bash
+lumo milestone move "Alpha" --before "Q3 Launch"
+lumo milestone move "Alpha" --after "Beta" --project backend
+```
+
+Output:
+
+```
+Moved "Alpha" before "Q3 Launch". New order:
+  1. Alpha
+  2. Q3 Launch
+  3. Beta
+```
+
+Both commands resolve to a full ordered list client-side and call the same `PATCH /api/projects/<id>/milestones/reorder` endpoint (which requires the list to name every milestone exactly once). New milestones created via `milestone create` are appended to the bottom of the order.
+
+**Ambiguous names:** milestone names are not unique within a project (only the slug is). A ref whose name matches more than one milestone is **rejected** with an `ambiguous milestone name … re-run with the id` error listing the candidate cuids — pass the cuid instead. This applies to every name-based milestone ref (`reorder`, `move`, and also `show` / `update` / `delete` / `summary` / `add` / `remove`).
+
+When to suggest: user asks to "reorder milestones", "排序里程碑", "调整里程碑顺序", "move milestone X before/after Y", "把里程碑 X 移到 Y 前面/后面", "put this milestone first".

package/assets/skill/references/onboarding.md

@@ -0,0 +1,102 @@
+# Onboarding, Authentication & Self-Update
+
+## Onboarding
+
+### `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill + hooks
+
+Bootstraps Lumo into a coding-agent installation. Copies the bundled skill files (`SKILL.md` **and its `references/` directory**) 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.
+
+On `--project` scope, setup also installs a `prepare-commit-msg` git hook that
+auto-appends the branch's task ID (`[LUM-N]`, parsed from a `lumo/LUM-N-...`
+branch name) to any commit subject that lacks it. The hook is pure sh + git
+(no network, no `lumo` call) and is merged idempotently between
+`# >>> lumo prepare-commit-msg >>>` / `# <<< lumo <<<` markers, preserving any
+existing hook content. When `core.hooksPath` is set (husky or a custom hooks
+dir), setup does **not** write the file — it prints the block plus instructions
+to add it manually (e.g. to `.husky/prepare-commit-msg`). `--user` scope does
+not touch git hooks.
+
+`--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; 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 files if they differ from bundled
+npx @lumoai/cli setup --agent codex      # bake agent=codex into the hook commands
+```
+
+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. An unrecognized `--agent` token aborts before writing anything.
+
+## Authentication
+
+### `lumo auth login` — paste an API key to log in
+
+Walks the user through creating an API key in the web app and pasting it back. Opens the browser to the API Keys settings page, then reads the key from stdin (must start with the `lum_` prefix). On success prints `✓ Logged in as <email>` plus workspace + key name.
+
+```bash
+lumo auth login
+```
+
+Use when:
+
+- `lumo whoami` reports "Not logged in"
+- A bearer call returns 401 (`API key invalid or revoked`) and the user wants to re-auth
+- The user switches workspaces / accounts
+
+The CLI stores credentials in `~/.lumo/credentials.json`. There's no `--token` flag — the paste-from-browser flow is the only auth path, and that's intentional.
+
+### `lumo auth logout` — remove local credentials
+
+Wipes `~/.lumo/credentials.json`. Idempotent — running twice just prints `Not logged in` the second time.
+
+```bash
+lumo auth logout
+```
+
+Use when the user says "log out", "sign out", or wants to clear credentials before switching accounts (then run `lumo auth login` to re-auth).
+
+### `lumo whoami` — show current identity
+
+Prints the logged-in email, workspace name + slug, API key name + prefix, and API URL.
+
+```bash
+lumo whoami
+# Logged in as cli@uselumo.ai
+#   Workspace: Lumo (lumo)
+#   Key: Claude Code (lum_68d4...)
+#   API: https://www.uselumo.ai
+```
+
+Use when:
+
+- The user asks "who am I", "which workspace am I in", "what account is this"
+- You need to disambiguate whether `lumo task list` would hit the user's expected workspace
+- Before suggesting a destructive command on a shared machine — confirm the identity is right
+
+## Self-Update
+
+### `lumo update` — upgrade the CLI to the latest npm release
+
+Synchronously checks `registry.npmjs.org` for the latest published version of `@lumoai/cli`. When a newer version exists, runs `npm install -g @lumoai/cli@latest` and streams npm's output. When already on the latest, exits cleanly with a "Already on the latest version (X)" message.
+
+```bash
+lumo update
+```
+
+The CLI also performs a passive check at most once every 24 hours (a detached child process refreshes a cache at `~/.lumo/update-check.json`), and prints a one-line "Update available" notice on subsequent invocations when a newer version is in the cache.
+
+Use when:
+
+- The user asks "how do I update", "upgrade lumo", "is there a new version"
+- A bug-fix or feature mentioned in conversation requires a newer CLI than the user is running
+- The passive notice has appeared and the user wants to act on it
+
+If `npm install -g` fails (permissions, npm not on PATH, alternative package manager), `lumo update` prints a fallback hint instructing the user to run the install command manually. Do not auto-retry; let the user resolve the environment issue first.

package/assets/skill/references/sessions.md

@@ -0,0 +1,157 @@
+# Session Management
+
+## Session Management
+
+### Auto-bind at session start (from local git)
+
+When a session starts **without** a bound task, the `session-start` hook tries to
+infer the task from local git before falling back to the "请告诉我任务编号" prompt:
+
+- It reads the **current branch name** first (e.g. `lumo/LUM-145-...`), then the
+  **most recent commit subjects** (e.g. `... [LUM-145]`), extracting the first
+  `LUM-<n>`.
+- On a hit it binds the session to that task automatically (same `bind-task`
+  endpoint as `session attach`) and prints a single line:
+  `已自动绑定 LUM-145 - <title>（依据分支名/最近 commit）。如果不对，回复"不是"我就帮你解绑。`
+  The freshly-bound task's memory is injected too.
+- No match (detached HEAD, a non-lumo branch with no tagged commits, not a git
+  repo) or a failed bind (unknown task) → it degrades silently to the normal
+  unbound prompt.
+
+**Agent guidance:** if the user responds "不是" / "不对" / "wrong task" to an
+auto-bind line, run `lumo session detach` to clear the binding (then `session
+attach <LUM-N>` if they name the right one). No detach is needed when the
+auto-bound task is correct.
+
+### Layer 2 project-memory review at session start
+
+When the session is bound, session-start may inject a **"🆕 待核对：上次会话自动合并的项目级记忆"** section alongside the memory / PR-review blocks (LUM-165). It lists the **PROJECT-scope** memories that the member's **immediately-preceding session** auto-consolidated (Layer 2 runs asynchronously when a task is marked `done`). Each item shows its `id`.
+
+- **Why it's here:** Layer 2 promotions land async, so they can't be reviewed in the synchronous `session wrap` panel — they're surfaced at the _next_ session-start instead, when they've definitely landed.
+- **Show-once:** the section appears only at the session that immediately follows the one that produced the memories. It does **not** re-nag on later sessions, so act on it now or it scrolls off.
+- **Agent guidance:** briefly sanity-check each listed memory against the codebase/context. If one is wrong or over-generalized, remove it with `lumo memory rm <id> --yes` (ideally confirm with the user first). If they all look right, ignore the section and continue.
+
+Attribution requires the CC session id to reach the server: `lumo task update <id> --status done` automatically sends `CLAUDE_CODE_SESSION_ID` (via an `X-Lumo-Session-Id` header) so the resulting Layer 2 memories are attributed to the session. Marking a task done from the **web UI** leaves them unattributed (they won't surface for review) — that's expected.
+
+### `lumo session attach <identifier>` — bind the current session to a task
+
+Use this whenever the user mentions a task ID. The command is the only way to bind a session to a task.
+
+```bash
+lumo session attach LUM-42
+```
+
+What it does:
+
+- Reads `CLAUDE_CODE_SESSION_ID` from the environment (Claude Code sets this automatically). If it is not set, the command errors out — it must run from inside a Claude Code session.
+- Calls `POST /api/sessions/<session_id>/bind-task` on the Lumo server, which sets the Session row's `taskId` and re-tags previously-untagged HookEvent rows in this session.
+- The binding lives entirely on the server (`Session.taskId`); subsequent hooks read it back via the session row. The CLI keeps no local sentinel.
+
+**After attaching, always run `lumo task context <identifier>` to load the task background.**
+
+#### Overwriting an existing binding (LUM-266)
+
+Re-attaching a session that's already bound to a **different** task no longer silently clobbers the binding. The server returns the current binding instead of overwriting, and the CLI decides what to do:
+
+- **On a TTY** (a human running it directly): prompts `已绑定 LUM-X，覆盖为 LUM-Y? [y/N]`. Answering `y`/`yes` re-binds to `LUM-Y`; anything else (including bare Enter) cancels and leaves `LUM-X` bound.
+- **Off a TTY** (the usual agent case — `stdin` is not interactive): the command **refuses** and prints `Session already bound to LUM-X … Re-run with --force …` without overwriting. Exit code is `0` (a safe refusal, not an error).
+- **`--force`**: skips the prompt/refusal and overwrites unconditionally. Re-attaching to the **same** task is always a no-op re-bind (never prompts).
+
+```bash
+lumo session attach LUM-42            # already on LUM-7 → prompts (TTY) / refuses (agent)
+lumo session attach LUM-42 --force    # overwrite without confirmation
+```
+
+**Agent guidance:** when `session attach` reports the session is already bound to a different task, **ask the user** whether to switch before re-running with `--force`. Don't auto-`--force` — the existing binding may be intentional (e.g. an auto-bind from the branch name). Alternatively run `lumo session detach` first, then a clean `session attach`.
+
+### Parallel sessions
+
+Each Claude Code session has its own `CLAUDE_CODE_SESSION_ID`. Two terminals running `claude code` and binding to different tasks will not interfere with each other — the bindings are scoped per session row server-side.
+
+### `lumo session status` — show current binding
+
+Prints which task the current Claude Code session is bound to, or "(no task)" if none. Requires `$CLAUDE_CODE_SESSION_ID` (i.e. must run inside Claude Code).
+
+```bash
+lumo session status
+```
+
+When to suggest: the user asks "which task am I on", "what's this session bound to", or you need to decide whether to suggest `session attach` for a mentioned task ID.
+
+### `lumo session detach` — clear the current binding
+
+Idempotent — running it twice is fine, the second call reports `already unbound`. Past hook events keep their original `taskId`; only future events on this session will be untagged.
+
+```bash
+lumo session detach
+```
+
+When to suggest: the user wants to stop tagging the current session with the active task (e.g., switching to unrelated exploratory work without binding to a different task).
+
+### `lumo session wrap [--yes] [--dry-run]` — wrap-up panel: progress comment + memory review + blocked-tag prompt
+
+Session-end wrap-up panel with **three sections, run in order**:
+
+**1. 进度评论** — reads back the current Claude Code session's per-turn
+`turnSummary` rows (the one-line Chinese summaries written each STOP), aggregates
+every turn **since the last progress comment** into one bulleted body, and — after
+a `[y] 发送 / [e] 编辑 / [s] 跳过` confirmation — posts it as a comment on the
+session's bound task. A server-side watermark (`Session.lastProgressCommentAt`)
+means re-running never re-posts the same turns.
+
+**2. 记忆审阅** — lists the Layer1 memories this session sedimented since the
+last review (deduped by a per-session watermark `Session.lastMemoryReviewAt`).
+Each new memory is shown as `[SCOPE] CATEGORY  headline`, numbered from 1. You
+curate with a single line: `d 1,3` deletes rows 1 and 3, `p 2` promotes row 2 to
+project scope, and they combine (`d 1,3 p 2`). **回车 (empty) keeps all**; `s`
+skips the section. Keeping all (回车 or `--yes`) still **advances the watermark**
+so the next wrap won't re-list reviewed memories; `s` leaves them for next time.
+Out-of-range indices are ignored. Deletes/promotes run server-side, scoped to
+memories this session created (you can't touch other sessions' memories through
+this panel). With no new memories the section prints "(无内容)" and does nothing.
+
+**3. 卡住检测 (blocked-tag prompt, LUM-153)** — if the **same kind of failure
+recurred ≥ 3 times** in this session (server-aggregated from
+`POST_TOOL_USE_FAILURE` events grouped by tool name, plus `STOP_FAILURE`
+turn-level failures), the section surfaces the dominant failure (`卡在 <tool>
+(N 次失败)` + last error summary) and prompts `[y] 标记 / [s] 跳过` whether to
+flag the bound task with a **`blocked` tag**. **Prompt-only — never auto-flips
+status.** It uses a plain tag (no `TaskStatus` enum, no board column, **no
+schema migration**). The prompt is **suppressed** when: there's no bound task,
+the threshold isn't met, or the task **already** carries a `blocked` tag (the
+idempotent gate — there's no watermark, the existing tag is what prevents
+re-nagging). The default on empty input / `s` is **do nothing** (tagging is
+opt-in), so a stray Enter never tags the task. Confirming with an explicit `y`
+attaches the tag idempotently. **`--yes` does NOT auto-tag** — tagging the
+shared board requires an interactive `y`, so `--yes` (and non-TTY) prints the
+suggestion and moves on rather than silently flipping board state. When there's
+nothing to prompt, the section prints "(无内容)".
+
+```bash
+lumo session wrap            # interactive: preview each section, choose per-section
+lumo session wrap --yes      # progress posted + memories kept; blocked tag NOT auto-applied (needs interactive y)
+lumo session wrap --dry-run  # print all drafts only; never posts, never mutates, never advances watermarks
+```
+
+- Requires `$CLAUDE_CODE_SESSION_ID` (must run inside Claude Code) and a bound
+  task (`lumo session attach <LUM-N>` first). With no bound task or no new turn
+  summaries, the 进度评论 section prints "(无内容)" and posts nothing.
+- `[e] 编辑` (进度评论) opens `$EDITOR` (fallback vi/nano) on the drafted body;
+  the edited text is posted and the watermark still advances to the turns the
+  draft covered.
+- `--yes` posts the progress comment AND keeps all memories (no
+  deletes/promotes) while advancing the memory-review watermark; for the
+  blocked-tag section it prints the suggestion but does **not** apply the tag.
+- `--dry-run` prints all drafts; never posts, never mutates memories/tags, never
+  advances either watermark.
+- Non-TTY without `--yes`: prints the drafts and does **not** post, mutate, or
+  tag (safe default).
+
+When to suggest: at the end of a working session on a bound task, to record what
+was done as a progress comment — offer `lumo session wrap` rather than composing
+a `task comment` by hand.
+
+### When to suggest session binding
+
+- If the user mentions a task ID (e.g., "let's work on LUM-42") and no session is currently bound, **suggest running `lumo session attach`**.
+- If the user switches tasks mid-session, run `attach` with the new task ID — the server overwrites the existing binding atomically.