@lumoai/cli 1.28.0 → 1.29.0

package/assets/skill/references/memory.md

@@ -1,103 +0,0 @@
-# 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.
-
-### Reconcile-on-write & deduplication
-
-`memory add` does **not** unconditionally insert a new row. Before writing it:
-
-1. Retrieves the nearest existing memories in the store (embedding similarity).
-2. If a near-duplicate is found — including a **cross-language match** (e.g. you
-   supply content in Chinese but an equivalent English memory already exists) —
-   an LLM decides the outcome; otherwise the new memory is inserted directly.
-
-The command prints **one** of these outcome lines:
-
-| Output line                                                      | Meaning                                                                                  |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `Added <CATEGORY> <SCOPE> memory …`                              | No near-duplicate found; stored as a new row.                                            |
-| `Merged into existing memory <id> (near-duplicate) …`            | Near-duplicate found; the existing row was refined/updated in-place (UPDATE).            |
-| `Superseded an existing memory; new version <id> …`              | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
-| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP).                                |
-
-Content is **always normalized to English** before storing — the memory store has
-a single canonical language. If you supply text in another language the CLI
-translates it automatically; the stored memory will be in English.
-
-### Lumo memory vs the harness memory tool
-
-Claude Code / the Claude API may expose a file-based **memory tool** (a
-`/memories` directory the model writes autonomously). That store is the agent's
-private scratchpad — un-grounded, free-form, invisible to the team, and outside
-Lumo's flywheel. **Project engineering lessons always go through `lumo task/project
-memory add`** — never record them only in the harness memory tool, and never bulk-copy
-harness memory files into Lumo memory (they are ungrounded drafts; Lumo's
-extract→ground→reconcile write path is the only vetted entry). The two stores are
-layered, not mirrored: transient working notes may live in the harness tool,
-durable team knowledge lives in Lumo memory.
-
-### 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 (`--trigger`, `--outcome`); put a **one-line fix** inline via `--workaround`. Only when the fix is a genuine multi-step workflow, omit `--workaround` and add a separate `procedural` instead — never both (a `procedural` that just restates a trap's `--workaround` is a double-write).
-- `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

@@ -1,244 +0,0 @@
-# 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 `Unscheduled` 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
-  Unscheduled             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 ("attach these tasks to Q3", "put LUM-1 LUM-2 LUM-3 into the milestone", "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", "put this milestone first".

package/assets/skill/references/onboarding.md

@@ -1,102 +0,0 @@
-# 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.