@lumoai/cli 1.2.0 → 1.3.0

package/README.md

@@ -91,18 +91,18 @@ lumo task update LUM-42 --status done
 
 ## Commands
 
-| Group           | Highlights                                                    |
-| --------------- | ------------------------------------------------------------- |
-| `setup`         | Install SKILL.md + hooks into `~/.claude/` or `./.claude/`    |
-| `auth`          | `login`, `logout`                                             |
-| `whoami`        | Show current identity + workspace                             |
-| `update`        | Self-update to the latest npm release                         |
-| `task`          | `create`, `update`, `list`, `show`, `comment`, `context`      |
-| `session`       | `attach`, `status`, `detach` (binds Claude Code sessions)     |
-| `project`       | `list`                                                        |
-| `milestone`     | `create`, `update`, `list`, `show`, `delete`                  |
-| `sprint`        | `create`, `start`, `close`, `list`, `show`, `add`, `remove`, `summary` |
-| `doc`           | `create`, `update`, `list`, `show`, `move`, `bind`, `share`   |
+| Group       | Highlights                                                             |
+| ----------- | ---------------------------------------------------------------------- |
+| `setup`     | Install SKILL.md + hooks into `~/.claude/` or `./.claude/`             |
+| `auth`      | `login`, `logout`                                                      |
+| `whoami`    | Show current identity + workspace                                      |
+| `update`    | Self-update to the latest npm release                                  |
+| `task`      | `create`, `update`, `list`, `show`, `comment`, `context`               |
+| `session`   | `attach`, `status`, `detach` (binds Claude Code sessions)              |
+| `project`   | `list`                                                                 |
+| `milestone` | `create`, `update`, `list`, `show`, `delete`                           |
+| `sprint`    | `create`, `start`, `close`, `list`, `show`, `add`, `remove`, `summary` |
+| `doc`       | `create`, `update`, `list`, `show`, `move`, `bind`, `share`            |
 
 Every command accepts `--help` for full flags and examples:
 

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 初始化".'
+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", "remove artifact", "delete artifact", "spec artifact", "record spec", "attach spec", "attach plan", "记录 spec", "挂 spec", "查看 artifact", "删除 artifact", figma, attach figma, figma link, 关联 figma, 设计稿, figma design.'
 ---
 
 ## Prerequisites
@@ -187,7 +187,7 @@ Pure flag-driven update. Provide at least one of:
 | `-p, --priority <lvl>`   | enum                | `low \| medium \| high \| urgent`.                                                                                                                                                                                                                                    |
 | `-a, --assignee <ref>`   | string              | `me`, an email, or a member name. `--assignee ""` clears the field.                                                                                                                                                                                                   |
 | `--milestone <ref>`      | string              | Milestone name (case-insensitive) within the task's project. `--milestone ""` unbinds.                                                                                                                                                                                |
-| `--sprint <ref>`         | string              | Sprint number or UUID to bind the task to. `--sprint ""` clears the current sprint binding (idempotent when already unbound).                                                                                                                                          |
+| `--sprint <ref>`         | string              | Sprint number or UUID to bind the task to. `--sprint ""` clears the current sprint binding (idempotent when already unbound).                                                                                                                                         |
 | `--tag <name>`           | string (repeatable) | **Bulk replace** the tag set by name. Creates tag if missing. Max 20. Mutually exclusive with `--add-tag*` / `--remove-tag*`.                                                                                                                                         |
 | `--tag-id <cuid>`        | string (repeatable) | **Bulk replace** the tag set by id. Max 20. Mutually exclusive with `--add-tag*` / `--remove-tag*`.                                                                                                                                                                   |
 | `--add-tag <name>`       | string (repeatable) | Attach tag by name (find-or-create). Max 20.                                                                                                                                                                                                                          |
@@ -295,6 +295,114 @@ lumo task comment LUM-42 "Reproduced the redirect bug on staging — Safari only
 
 The CLI does not support @-mention chip syntax. If the user wants to ping someone, they should comment from the web UI.
 
+### Task ↔ Spec Artifacts
+
+Record Claude Code spec-engineering products (spec / plan / design …) on a task. The artifacts show up in the task detail "规格" (definition) layer and are injected into `lumo task context`.
+
+#### `lumo task artifact add <task> --kind <kind> --title <title> --file <path> [--source <source>]`
+
+Attaches an artifact to a task. `--kind`, `--title`, `--source` are stored verbatim — **`kind` is opaque** (no enumeration; `spec` / `plan` / `requirements` / anything is accepted). `--file` supplies the body (file contents). `--source` defaults to `claude-code`. 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.
+
+```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 superpowers
+```
+
+Output: `Added [spec] "Spec" to LUM-42`
+
+#### `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.
+
+```bash
+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`.
+
+```bash
+lumo task artifact show LUM-42 cma_xxx
+```
+
+#### `lumo task artifact rm <task> <artifact-id> --yes`
+
+Deletes an artifact from a task. Irreversible — `--yes` is required and there is no interactive prompt (agent-friendly). On success prints `Removed <artifact-id> from <task>`. A 404 (task or artifact missing in this workspace) prints the server message and exits 1.
+
+```bash
+lumo task artifact rm LUM-42 cma_xxx --yes
+```
+
+When to suggest: after running a spec/plan workflow in Claude Code, offer to record the product(s) with `task artifact add` (one call per artifact). Use `task artifact list` to see what's already recorded, `task artifact show` to inspect a single artifact's content, and `task artifact rm` to drop one that's wrong or stale.
+
+### Task ↔ Figma Designs
+
+#### `lumo task figma add <task> <url>` — attach a Figma file/frame
+
+Fetches file name, frame name, and thumbnail via Figma OAuth and stores them
+on the task.
+
+```bash
+lumo task figma add LUM-42 "https://www.figma.com/design/abc123/Onboarding?node-id=1-234"
+```
+
+If the URL omits `node-id`, the link is stored as file-level; the CLI prints
+a `(file-level, thumbnail from "...")` note showing the auto-picked
+representative frame.
+
+Idempotent — re-adding the same URL within 7 days returns the existing row
+without re-calling Figma.
+
+**Not connected?** Errors with:
+
+```
+✗ You haven't connected Figma yet.
+  Run: open https://www.uselumo.ai/settings/integrations
+```
+
+#### `lumo task figma list <task>` — list attachments
+
+```
+$ lumo task figma list LUM-42
+cfl_xxx1  Onboarding       Welcome screen       2026-05-28
+cfl_xxx2  Design System    Button / Primary     2026-05-27
+cfl_xxx3  Onboarding       (file-level)         2026-05-20  ⚠ thumbnail stale
+```
+
+`⚠ thumbnail stale` appears when `thumbnailFetchedAt > 25 days`.
+
+#### `lumo task figma rm <task> <link-id-or-url>` — remove an attachment
+
+Accepts a `cfl_*` cuid or the original URL. Idempotent (`Not linked: ...` + exit 0 when no match).
+
+#### `lumo task figma refresh <task>` — manual refresh
+
+Re-fetches metadata + thumbnail for every Figma link on the task. Per-link
+failures are isolated.
+
+```
+$ lumo task figma refresh LUM-42
+Refreshed 3 Figma links on LUM-42
+  ✓ Onboarding · Welcome screen
+  ✓ Onboarding · Sign-up form
+  ✗ Design System · Button (file not accessible)
+```
+
+### When to suggest the `task figma` commands
+
+- User pastes a Figma URL or mentions a design ("here's the mock", "the
+  Figma is at...").
+- User asks "what designs are linked to this task" or "show me the Figma
+  for LUM-42".
+- After implementing a UI change, suggest `lumo task figma refresh <task>`
+  if the user mentioned updating the Figma source.
+
+OAuth connection lives in the Web UI at
+`/settings/integrations`. The CLI does **not** have a `figma auth`
+command; if the user tries `task figma add` without connecting, the error
+message directs them to the Web UI.
+
 ### `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.
@@ -629,11 +737,11 @@ If user creates a doc with `--task LUM-N` and the current Claude Code session is
 
 Prints fixed-width rows: `<NUMBER>  <STATUS>  <start>  <end>  <name>`, sorted newest-first (server sort).
 
-| Flag                   | Type    | Notes                                              |
-| ---------------------- | ------- | -------------------------------------------------- |
+| Flag                   | Type    | Notes                                                 |
+| ---------------------- | ------- | ----------------------------------------------------- |
 | `--team <ref>`         | string  | Team name or slug. Required in multi-team workspaces. |
-| `-s, --status <value>` | enum    | `draft \| active \| closed`.                       |
-| `-n, --limit <count>`  | integer | Cap output to the first N rows.                    |
+| `-s, --status <value>` | enum    | `draft \| active \| closed`.                          |
+| `-n, --limit <count>`  | integer | Cap output to the first N rows.                       |
 
 ```bash
 lumo sprint list
@@ -645,12 +753,12 @@ When to suggest: user asks "what sprints do we have", "which sprint is active",
 
 ### `lumo sprint create [flags]` — create a sprint
 
-| Flag              | Type   | Notes                                                   |
-| ----------------- | ------ | ------------------------------------------------------- |
-| `--team <ref>`    | string | Team name or slug. Required in multi-team workspaces.   |
-| `--start <date>`  | string | **Required.** YYYY-MM-DD.                               |
-| `--end <date>`    | string | **Required.** YYYY-MM-DD.                               |
-| `-n, --name <>`   | string | Optional. Server fills a default name when omitted.     |
+| Flag             | Type   | Notes                                                 |
+| ---------------- | ------ | ----------------------------------------------------- |
+| `--team <ref>`   | string | Team name or slug. Required in multi-team workspaces. |
+| `--start <date>` | string | **Required.** YYYY-MM-DD.                             |
+| `--end <date>`   | string | **Required.** YYYY-MM-DD.                             |
+| `-n, --name <>`  | string | Optional. Server fills a default name when omitted.   |
 
 ```bash
 lumo sprint create --start 2026-06-01 --end 2026-06-14
@@ -679,12 +787,12 @@ When to suggest: user asks "what's in sprint 3", "show me the current sprint", "
 
 Updates sprint metadata. At least one flag required. **No `--status` flag** — use `lumo sprint start` / `lumo sprint close` to transition status.
 
-| Flag              | Type   | Notes                                                         |
-| ----------------- | ------ | ------------------------------------------------------------- |
-| `--team <ref>`    | string | Required when identifier is a number in a multi-team workspace. |
-| `-n, --name <>`   | string | New name. Cannot be empty.                                    |
-| `--start <date>`  | string | YYYY-MM-DD. `--start ""` clears.                              |
-| `--end <date>`    | string | YYYY-MM-DD. `--end ""` clears.                                |
+| Flag             | Type   | Notes                                                           |
+| ---------------- | ------ | --------------------------------------------------------------- |
+| `--team <ref>`   | string | Required when identifier is a number in a multi-team workspace. |
+| `-n, --name <>`  | string | New name. Cannot be empty.                                      |
+| `--start <date>` | string | YYYY-MM-DD. `--start ""` clears.                                |
+| `--end <date>`   | string | YYYY-MM-DD. `--end ""` clears.                                  |
 
 ```bash
 lumo sprint update 3 --name "Sprint 4 (extended)"
@@ -717,11 +825,11 @@ When to suggest: user says "start the sprint", "开始冲刺", "kick off sprint
 
 Handles unfinished tasks based on flags. Without flags: closes only if all tasks are done; otherwise prints a list of unfinished tasks and refuses.
 
-| Flag           | Type    | Notes                                                                     |
-| -------------- | ------- | ------------------------------------------------------------------------- |
-| `--move-all`   | boolean | Move all unfinished tasks to the next sprint. Requires `--yes`.           |
-| `--backlog-all`| boolean | Remove all unfinished tasks from the sprint (send to backlog). Requires `--yes`. |
-| `--yes`        | boolean | Required when `--move-all` or `--backlog-all` is given.                   |
+| Flag            | Type    | Notes                                                                            |
+| --------------- | ------- | -------------------------------------------------------------------------------- |
+| `--move-all`    | boolean | Move all unfinished tasks to the next sprint. Requires `--yes`.                  |
+| `--backlog-all` | boolean | Remove all unfinished tasks from the sprint (send to backlog). Requires `--yes`. |
+| `--yes`         | boolean | Required when `--move-all` or `--backlog-all` is given.                          |
 
 ```bash
 lumo sprint close 3                          # fails if unfinished tasks exist
@@ -735,9 +843,9 @@ When to suggest: user says "close the sprint", "关闭冲刺", "end sprint 3", "
 
 Prints the AI-generated retrospective summary for the sprint. A 404 response means no summary has been generated yet ("no summary yet").
 
-| Flag      | Type    | Notes                                                |
-| --------- | ------- | ---------------------------------------------------- |
-| `--retry` | boolean | Queue a regeneration (async, server returns 202).    |
+| Flag      | Type    | Notes                                             |
+| --------- | ------- | ------------------------------------------------- |
+| `--retry` | boolean | Queue a regeneration (async, server returns 202). |
 
 ```bash
 lumo sprint summary 3

package/dist/cli/src/commands/setup.js

@@ -148,7 +148,9 @@ function isLumoOnPath() {
     try {
         // `command -v` is a POSIX shell builtin (`execSync` defaults to /bin/sh
         // on Unix). `where` is a cmd.exe builtin on Windows.
-        (0, child_process_1.execSync)(process.platform === 'win32' ? 'where lumo' : 'command -v lumo', { stdio: 'pipe' });
+        (0, child_process_1.execSync)(process.platform === 'win32' ? 'where lumo' : 'command -v lumo', {
+            stdio: 'pipe',
+        });
         return true;
     }
     catch {

package/dist/cli/src/commands/task-artifact-add.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskArtifactAdd = taskArtifactAdd;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_input_1 = require("../lib/doc-input");
+async function taskArtifactAdd(identifier, options) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task artifact add <LUM-42> --kind spec --title "Spec" --file spec.md');
+        return 1;
+    }
+    const kind = options.kind?.trim();
+    const title = options.title?.trim();
+    if (!kind) {
+        console.error('Error: --kind is required and cannot be empty.');
+        return 1;
+    }
+    if (!title) {
+        console.error('Error: --title is required and cannot be empty.');
+        return 1;
+    }
+    if (!options.file) {
+        console.error('Error: --file <path> is required.');
+        return 1;
+    }
+    let content;
+    try {
+        content = await (0, doc_input_1.readFileUtf8)(options.file);
+    }
+    catch {
+        console.error(`Error: could not read file ${options.file}`);
+        return 1;
+    }
+    if (content.trim().length === 0) {
+        console.error(`Error: file ${options.file} is empty.`);
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        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 base = (0, api_1.trimTrailingSlash)(apiUrl);
+    const payload = { kind, title, content };
+    if (options.source?.trim())
+        payload.source = options.source.trim();
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/artifacts`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${creds.token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(payload),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        console.error(`Error: task ${identifier} not found in workspace ${creds.workspaceSlug}`);
+        return 1;
+    }
+    if (res.status !== 201) {
+        let serverMsg = null;
+        try {
+            const errBody = (await res.json());
+            if (typeof errBody.error === 'string')
+                serverMsg = errBody.error;
+        }
+        catch {
+            /* not JSON */
+        }
+        console.error(serverMsg
+            ? `Error: ${serverMsg}`
+            : `Error: artifact add failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const data = (await res.json());
+    process.stdout.write(`Added [${data.artifact.kind}] "${data.artifact.title}" to ${identifier}\n`);
+}

package/dist/cli/src/commands/task-artifact-list.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskArtifactList = taskArtifactList;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+async function taskArtifactList(identifier) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task artifact list <LUM-42>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        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 base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/artifacts`, { headers: { Authorization: `Bearer ${creds.token}` } });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        console.error(`Error: task ${identifier} not found in workspace ${creds.workspaceSlug}`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: artifact list failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const { artifacts } = (await res.json());
+    if (artifacts.length === 0) {
+        process.stdout.write(`No artifacts on ${identifier}\n`);
+        return;
+    }
+    for (const a of artifacts) {
+        process.stdout.write(`${a.id}  ${a.kind.padEnd(10)}  ${a.source.padEnd(12)}  ${a.title}\n`);
+    }
+}

package/dist/cli/src/commands/task-artifact-rm.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskArtifactRm = taskArtifactRm;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+async function taskArtifactRm(identifier, artifactId, options) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task artifact rm <LUM-42> <artifact-id> --yes');
+        return 1;
+    }
+    if (!artifactId) {
+        console.error('Error: missing <artifact-id>. Usage: lumo task artifact rm <LUM-42> <artifact-id> --yes');
+        return 1;
+    }
+    if (!options.yes) {
+        console.error('Error: --yes is required (artifact deletion is irreversible).');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        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 base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/artifacts/${encodeURIComponent(artifactId)}`, {
+            method: 'DELETE',
+            headers: { Authorization: `Bearer ${creds.token}` },
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        let serverMsg = `task ${identifier} or artifact ${artifactId} not found in workspace ${creds.workspaceSlug}`;
+        try {
+            const errBody = (await res.json());
+            if (typeof errBody.error === 'string')
+                serverMsg = errBody.error;
+        }
+        catch {
+            /* not JSON */
+        }
+        console.error(`Error: ${serverMsg}`);
+        return 1;
+    }
+    if (res.status !== 204) {
+        let serverMsg = null;
+        try {
+            const errBody = (await res.json());
+            if (typeof errBody.error === 'string')
+                serverMsg = errBody.error;
+        }
+        catch {
+            /* not JSON */
+        }
+        console.error(serverMsg
+            ? `Error: ${serverMsg}`
+            : `Error: artifact rm failed (HTTP ${res.status})`);
+        return 1;
+    }
+    process.stdout.write(`Removed ${artifactId} from ${identifier}\n`);
+}

package/dist/cli/src/commands/task-artifact-show.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskArtifactShow = taskArtifactShow;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+async function taskArtifactShow(identifier, artifactId) {
+    if (!identifier) {
+        console.error('Error: missing <task>. Usage: lumo task artifact show <LUM-42> <artifact-id>');
+        return 1;
+    }
+    if (!artifactId) {
+        console.error('Error: missing <artifact-id>. Usage: lumo task artifact show <LUM-42> <artifact-id>');
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        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 base = (0, api_1.trimTrailingSlash)(apiUrl);
+    let res;
+    try {
+        res = await fetch(`${base}/api/tasks/${encodeURIComponent(identifier)}/artifacts/${encodeURIComponent(artifactId)}`, { headers: { Authorization: `Bearer ${creds.token}` } });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: could not reach Lumo API at ${apiUrl} (${msg})`);
+        return 1;
+    }
+    if (res.status === 401) {
+        console.error('Error: API key invalid or revoked. Run `lumo auth login`.');
+        return 1;
+    }
+    if (res.status === 404) {
+        let serverMsg = `task ${identifier} or artifact ${artifactId} not found in workspace ${creds.workspaceSlug}`;
+        try {
+            const errBody = (await res.json());
+            if (typeof errBody.error === 'string')
+                serverMsg = errBody.error;
+        }
+        catch {
+            /* not JSON */
+        }
+        console.error(`Error: ${serverMsg}`);
+        return 1;
+    }
+    if (!res.ok) {
+        console.error(`Error: artifact show failed (HTTP ${res.status})`);
+        return 1;
+    }
+    const { artifact } = (await res.json());
+    process.stdout.write(`id:     ${artifact.id}\n`);
+    process.stdout.write(`kind:   ${artifact.kind}\n`);
+    process.stdout.write(`title:  ${artifact.title}\n`);
+    process.stdout.write(`source: ${artifact.source}\n`);
+    process.stdout.write(`order:  ${artifact.order}\n`);
+    process.stdout.write(`task:   ${identifier}\n`);
+    process.stdout.write(`\n${artifact.content}\n`);
+}

package/dist/cli/src/commands/task-context.js

@@ -60,8 +60,9 @@ function formatTaskContextMarkdown(data, now) {
             : '';
         lines.push(`**Milestone**: ${data.task.milestone.name} (${data.task.milestone.status}${target})`);
     }
-    if (data.task.description && data.task.description.trim().length > 0) {
-        lines.push(`**Description**: ${data.task.description}`);
+    const body = data.task.descriptionMarkdown ?? data.task.description;
+    if (body && body.trim().length > 0) {
+        lines.push(`**Description**: ${body}`);
     }
     lines.push('');
     // Frontload memory before sessions: it's cold context the agent should see
@@ -78,6 +79,14 @@ function formatTaskContextMarkdown(data, now) {
         lines.push(data.webLinkSection.trimEnd());
         lines.push('');
     }
+    if (data.figmaSection && data.figmaSection.trim().length > 0) {
+        lines.push(data.figmaSection.trimEnd());
+        lines.push('');
+    }
+    if (data.artifactSection && data.artifactSection.trim().length > 0) {
+        lines.push(data.artifactSection.trimEnd());
+        lines.push('');
+    }
     if (data.sessions.length === 0) {
         lines.push('## Previous Sessions (0)');
         lines.push('');

package/dist/cli/src/commands/task-figma-add.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskFigmaAdd = taskFigmaAdd;
+const figma_api_1 = require("../lib/figma-api");
+async function taskFigmaAdd(args) {
+    try {
+        const { link } = await (0, figma_api_1.addFigmaLink)(args.identifier, args.url);
+        const label = link.frameName
+            ? `${link.fileName} · ${link.frameName}`
+            : `${link.fileName}${link.nodeId === '' ? ' (file-level)' : ''}`;
+        console.log(`Linked ${args.identifier} ↔ Figma "${label}"`);
+        console.log(`  ${link.url}`);
+        return 0;
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === 'figma_not_connected') {
+            console.error(`✗ You haven't connected Figma yet.`);
+            console.error(`  Run: open https://www.uselumo.ai/settings/integrations`);
+            return 1;
+        }
+        if (err.code === 'figma_needs_reauth') {
+            console.error(`✗ Your Figma token is no longer valid. Please reconnect.`);
+            console.error(`  Run: open https://www.uselumo.ai/settings/integrations`);
+            return 1;
+        }
+        throw e; // let wrap() in cli/src/index.ts log and exit 1
+    }
+}

package/dist/cli/src/commands/task-figma-list.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskFigmaList = taskFigmaList;
+const figma_api_1 = require("../lib/figma-api");
+const STALE_MS = 25 * 24 * 3600 * 1000;
+function formatRow(id, fileName, frame, synced, stale) {
+    return [
+        id.padEnd(10),
+        fileName.padEnd(20),
+        frame.padEnd(24),
+        synced.padEnd(12),
+        stale ? '⚠ thumbnail stale' : '',
+    ]
+        .join(' ')
+        .trimEnd();
+}
+async function taskFigmaList(args) {
+    const { links } = await (0, figma_api_1.listFigmaLinks)(args.identifier);
+    if (links.length === 0) {
+        console.log('No Figma links attached.');
+        return 0;
+    }
+    for (const link of links) {
+        const frame = link.frameName ?? '(file-level)';
+        const synced = link.lastSyncedAt.slice(0, 10);
+        const stale = link.thumbnailFetchedAt === null ||
+            Date.now() - new Date(link.thumbnailFetchedAt).getTime() > STALE_MS;
+        console.log(formatRow(link.id, link.fileName, frame, synced, stale && !!link.thumbnailUrl));
+    }
+    return 0;
+}

package/dist/cli/src/commands/task-figma-refresh.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskFigmaRefresh = taskFigmaRefresh;
+const figma_api_1 = require("../lib/figma-api");
+async function taskFigmaRefresh(args) {
+    try {
+        const { links } = await (0, figma_api_1.listFigmaLinks)(args.identifier);
+        const byId = new Map(links.map(l => [l.id, l]));
+        const { results } = await (0, figma_api_1.refreshFigmaLinks)(args.identifier);
+        if (results.length === 0) {
+            console.log(`No Figma links attached to ${args.identifier}.`);
+            return 0;
+        }
+        console.log(`Refreshed ${results.length} Figma links on ${args.identifier}`);
+        for (const r of results) {
+            const link = byId.get(r.id);
+            const label = link
+                ? link.frameName
+                    ? `${link.fileName} · ${link.frameName}`
+                    : `${link.fileName} (file-level)`
+                : r.id;
+            if (r.ok)
+                console.log(`  ✓ ${label}`);
+            else
+                console.log(`  ✗ ${label} (${r.error})`);
+        }
+        return 0;
+    }
+    catch (e) {
+        const err = e;
+        if (err.code === 'figma_not_connected' ||
+            err.code === 'figma_needs_reauth') {
+            console.error(`✗ Figma is not connected (or token expired). Reconnect:`);
+            console.error(`  open https://www.uselumo.ai/settings/integrations`);
+            return 1;
+        }
+        throw e;
+    }
+}

package/dist/cli/src/commands/task-figma-rm.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.taskFigmaRm = taskFigmaRm;
+const figma_api_1 = require("../lib/figma-api");
+async function taskFigmaRm(args) {
+    const { links } = await (0, figma_api_1.listFigmaLinks)(args.identifier);
+    const match = links.find(l => l.id === args.linkIdOrUrl || l.url === args.linkIdOrUrl);
+    if (!match) {
+        console.log(`Not linked: ${args.linkIdOrUrl}`);
+        return 0;
+    }
+    await (0, figma_api_1.removeFigmaLink)(args.identifier, match.id);
+    const label = match.frameName
+        ? `${match.fileName} · ${match.frameName}`
+        : `${match.fileName} (file-level)`;
+    console.log(`Removed Figma link from ${args.identifier}: "${label}"`);
+    return 0;
+}

package/dist/cli/src/commands/task-show.js

@@ -24,10 +24,11 @@ function formatTaskShow(task) {
         lines.push('Assignee:  (unassigned)');
     }
     lines.push(`URL:       ${task.url}`);
-    if (task.description && task.description.trim().length > 0) {
+    const body = task.descriptionMarkdown ?? task.description;
+    if (body && body.trim().length > 0) {
         lines.push('');
         lines.push('Description:');
-        for (const line of task.description.split('\n')) {
+        for (const line of body.split('\n')) {
             lines.push(`  ${line}`);
         }
     }

package/dist/cli/src/index.js

@@ -51,6 +51,14 @@ const task_update_1 = require("./commands/task-update");
 const task_list_1 = require("./commands/task-list");
 const task_show_1 = require("./commands/task-show");
 const task_comment_1 = require("./commands/task-comment");
+const task_figma_add_1 = require("./commands/task-figma-add");
+const task_figma_list_1 = require("./commands/task-figma-list");
+const task_figma_rm_1 = require("./commands/task-figma-rm");
+const task_figma_refresh_1 = require("./commands/task-figma-refresh");
+const task_artifact_add_1 = require("./commands/task-artifact-add");
+const task_artifact_list_1 = require("./commands/task-artifact-list");
+const task_artifact_show_1 = require("./commands/task-artifact-show");
+const task_artifact_rm_1 = require("./commands/task-artifact-rm");
 const project_list_1 = require("./commands/project-list");
 const milestone_list_1 = require("./commands/milestone-list");
 const milestone_create_1 = require("./commands/milestone-create");
@@ -206,6 +214,52 @@ task
     .option('--tag-id <cuid>', 'Attach tag by id (repeatable)', collect, [])
     .option('--sprint <ref>', 'Sprint number or UUID to add the task to after creation')
     .action(wrap((title, options) => (0, task_create_1.taskCreate)(title, options)));
+const taskFigma = task
+    .command('figma')
+    .description('Attach Figma file/frame links to a task');
+taskFigma
+    .command('add <task> <url>')
+    .description('Attach a Figma file or frame URL to the given task. Fetches file/frame name + thumbnail via Figma OAuth.')
+    .action(wrap((taskId, url) => (0, task_figma_add_1.taskFigmaAdd)({ identifier: taskId, url: url })));
+taskFigma
+    .command('list <task>')
+    .description('List Figma links attached to a task')
+    .action(wrap((taskId) => (0, task_figma_list_1.taskFigmaList)({ identifier: taskId })));
+taskFigma
+    .command('rm <task> <link-id-or-url>')
+    .description('Remove a Figma link from a task (idempotent)')
+    .action(wrap((taskId, linkIdOrUrl) => (0, task_figma_rm_1.taskFigmaRm)({
+    identifier: taskId,
+    linkIdOrUrl: linkIdOrUrl,
+})));
+taskFigma
+    .command('refresh <task>')
+    .description('Re-fetch Figma metadata + thumbnail for every link on this task. Per-link failures isolated.')
+    .action(wrap((taskId) => (0, task_figma_refresh_1.taskFigmaRefresh)({ identifier: taskId })));
+const taskArtifact = task
+    .command('artifact')
+    .description('Record spec-engineering artifacts (spec / plan / design …) on a task');
+taskArtifact
+    .command('add <task>')
+    .description('Attach an artifact to a task. --kind/--title/--source are stored verbatim; --file supplies the content.')
+    .requiredOption('--kind <kind>', 'Artifact kind, e.g. spec | plan | design (opaque)')
+    .requiredOption('--title <title>', 'Artifact title')
+    .requiredOption('--file <path>', 'File whose contents become the artifact body')
+    .option('--source <source>', 'Producer label (default: claude-code)')
+    .action(wrap((taskId, options) => (0, task_artifact_add_1.taskArtifactAdd)(taskId, options)));
+taskArtifact
+    .command('list <task>')
+    .description('List artifacts attached to a task, in order')
+    .action(wrap((taskId) => (0, task_artifact_list_1.taskArtifactList)(taskId)));
+taskArtifact
+    .command('show <task> <artifact-id>')
+    .description('Show one artifact (key:value header + content body). Find <artifact-id> in `artifact list` column 1.')
+    .action(wrap((taskId, artifactId) => (0, task_artifact_show_1.taskArtifactShow)(taskId, artifactId)));
+taskArtifact
+    .command('rm <task> <artifact-id>')
+    .description('Delete an artifact from a task. Irreversible — requires --yes.')
+    .option('--yes', 'Confirm deletion (required, no interactive prompt)')
+    .action(wrap((taskId, artifactId, options) => (0, task_artifact_rm_1.taskArtifactRm)(taskId, artifactId, options)));
 const projectCmd = program
     .command('project')
     .description('Inspect projects from the terminal');

package/dist/cli/src/lib/figma-api.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addFigmaLink = addFigmaLink;
+exports.listFigmaLinks = listFigmaLinks;
+exports.removeFigmaLink = removeFigmaLink;
+exports.refreshFigmaLinks = refreshFigmaLinks;
+const api_1 = require("./api");
+const config_1 = require("./config");
+function buildErr(status, body) {
+    const err = Object.assign(new Error(body.error ?? `HTTP ${status}`), {
+        status,
+    });
+    if (body.code !== undefined)
+        err.code = body.code;
+    return err;
+}
+async function call(path, init) {
+    const creds = (0, config_1.readCredentials)();
+    if (!creds)
+        throw new Error('Not logged in. Run: lumo auth login');
+    const apiUrl = (0, api_1.resolveApiUrl)();
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}${path}`, {
+        ...init,
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+            ...(init.headers ?? {}),
+        },
+    });
+    if (!res.ok) {
+        let parsed = {};
+        try {
+            parsed = (await res.json());
+        }
+        catch {
+            /* non-JSON body */
+        }
+        throw buildErr(res.status, parsed);
+    }
+    return (await res.json());
+}
+async function addFigmaLink(identifier, url) {
+    return call(`/api/tasks/${encodeURIComponent(identifier)}/figma`, {
+        method: 'POST',
+        body: JSON.stringify({ url }),
+    });
+}
+async function listFigmaLinks(identifier) {
+    return call(`/api/tasks/${encodeURIComponent(identifier)}/figma`, {
+        method: 'GET',
+    });
+}
+async function removeFigmaLink(identifier, linkId) {
+    return call(`/api/tasks/${encodeURIComponent(identifier)}/figma/${encodeURIComponent(linkId)}`, { method: 'DELETE' });
+}
+async function refreshFigmaLinks(identifier) {
+    return call(`/api/tasks/${encodeURIComponent(identifier)}/figma/refresh`, {
+        method: 'POST',
+    });
+}

package/dist/cli/src/lib/hooks-template.js

@@ -49,7 +49,9 @@ function buildLumoHookFragment() {
     return { hooks };
 }
 function mergeLumoHooks(existing) {
-    const base = existing ? JSON.parse(JSON.stringify(existing)) : {};
+    const base = existing
+        ? JSON.parse(JSON.stringify(existing))
+        : {};
     if (!base.hooks)
         base.hooks = {};
     const stats = { addedEvents: [], alreadyPresent: [] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",
@@ -40,9 +40,11 @@
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "markdown-it": "^14.1.1"
   },
   "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
     "@types/node": "^25",
     "typescript": "^5"
   }