@lumoai/cli 1.28.0 → 1.29.0

package/dist/cli/src/commands/doc-section-edit.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSectionEditLine = formatSectionEditLine;
+exports.docPatch = docPatch;
+exports.docAppend = docAppend;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const doc_input_1 = require("../lib/doc-input");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
+function formatSectionEditLine(args) {
+    const escaped = (0, sanitize_1.sanitizeField)(args.title).replace(/"/g, '\\"');
+    const target = args.sectionHeading
+        ? ` § "${(0, sanitize_1.sanitizeField)(args.sectionHeading)}"`
+        : ' (document end)';
+    const rev = args.revision !== null ? `  revision ${args.revision}` : '';
+    return `${args.verb} ${args.id} "${escaped}"${target}${rev}`;
+}
+async function docSectionEdit(mode, reference, opts) {
+    const cmd = mode === 'replace' ? 'patch' : 'append';
+    if (!reference) {
+        console.error(`Error: missing <doc>. Usage: lumo doc ${cmd} <doc> ${mode === 'replace' ? '--section <heading>' : '[--section <heading>]'} [--content <md> | --file <path> | stdin] [--if-revision <n>]`);
+        return 1;
+    }
+    if (mode === 'replace' && (!opts.section || opts.section.trim() === '')) {
+        console.error('Error: --section <heading> is required for doc patch');
+        return 1;
+    }
+    let ifRevision;
+    if (opts.ifRevision !== undefined) {
+        if (!/^\d+$/.test(opts.ifRevision)) {
+            console.error(`Error: --if-revision must be a non-negative integer (got "${opts.ifRevision}")`);
+            return 1;
+        }
+        ifRevision = Number(opts.ifRevision);
+    }
+    const content = await (0, doc_input_1.resolveDocContent)({
+        content: opts.content,
+        file: opts.file,
+        stdinIsTTY: Boolean(process.stdin.isTTY),
+        readStdin: doc_input_1.readStdinToString,
+        readFile: doc_input_1.readFileUtf8,
+    });
+    if (content.kind === 'error') {
+        console.error(`Error: ${content.message}`);
+        return 1;
+    }
+    if (content.kind === 'none') {
+        console.error(`Error: doc ${cmd} needs content — pass --content, --file, or pipe stdin`);
+        return 1;
+    }
+    const creds = (0, config_1.readCredentials)();
+    if (!creds) {
+        console.error('Error: not logged in. Run `lumo auth login` first.');
+        return 1;
+    }
+    const apiUrl = (0, api_1.resolveAuthedApiUrl)(creds.apiUrl);
+    const id = await (0, resolve_doc_id_1.lookupDocId)(apiUrl, creds.token, reference);
+    if (!id) {
+        console.error(`Error: Document not found: ${reference}`);
+        return 1;
+    }
+    const body = {
+        mode,
+        contentMarkdown: content.markdown,
+    };
+    if (opts.section !== undefined && opts.section.trim() !== '') {
+        body.section = opts.section;
+    }
+    if (ifRevision !== undefined)
+        body.ifRevision = ifRevision;
+    const res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}/section`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${creds.token}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let message = text;
+        try {
+            message = JSON.parse(text).error ?? text;
+        }
+        catch {
+            // non-JSON error body — print as-is
+        }
+        if (res.status === 409) {
+            console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: re-read the section (lumo doc show ${reference}${opts.section ? ` --section "${opts.section}"` : ''}), rebase your edit on it, then retry with --if-revision <current>.`);
+            return 1;
+        }
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(message)}`);
+        return 1;
+    }
+    const { document } = (await res.json());
+    console.log(formatSectionEditLine({
+        verb: mode === 'replace' ? 'Patched' : 'Appended to',
+        id: document.id,
+        title: document.title,
+        sectionHeading: document.sectionHeading ?? opts.section ?? null,
+        revision: typeof document.contentRevision === 'number'
+            ? document.contentRevision
+            : null,
+    }));
+}
+function docPatch(reference, opts) {
+    return docSectionEdit('replace', reference, opts);
+}
+function docAppend(reference, opts) {
+    return docSectionEdit('append', reference, opts);
+}

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

@@ -5,6 +5,7 @@ exports.docShow = docShow;
 const config_1 = require("../lib/config");
 const api_1 = require("../lib/api");
 const markdown_tiptap_1 = require("../lib/markdown-tiptap");
+const markdown_sections_1 = require("../lib/markdown-sections");
 const resolve_doc_id_1 = require("../lib/resolve-doc-id");
 const sanitize_1 = require("../lib/sanitize");
 function scopeLabel(s) {
@@ -22,6 +23,7 @@ function formatShowOutput(vm) {
         `Project: ${vm.projectName ? (0, sanitize_1.sanitizeField)(vm.projectName) : '-'}`,
         `Created: ${vm.createdAt}`,
         `Updated: ${vm.updatedAt}`,
+        `Revision: ${vm.revision ?? '-'}`,
         `Mentioned tasks: ${vm.mentionedTasks.length ? vm.mentionedTasks.join(', ') : '-'}`,
     ];
     const header = lines.join('\n');
@@ -29,7 +31,11 @@ function formatShowOutput(vm) {
 }
 async function docShow(reference, opts = {}) {
     if (!reference) {
-        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw]');
+        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw | --section <heading>]');
+        return 1;
+    }
+    if (opts.raw && opts.section !== undefined) {
+        console.error('Error: --raw and --section are mutually exclusive (--raw prints the whole source)');
         return 1;
     }
     const creds = (0, config_1.readCredentials)();
@@ -73,6 +79,46 @@ async function docShow(reference, opts = {}) {
             return 1;
         }
         process.stdout.write(d.sourceMarkdown);
+        // Revision goes to stderr so stdout stays a byte-pure edit base while
+        // the agent still sees the number to pass back as --if-revision.
+        if (typeof d.contentRevision === 'number') {
+            console.error(`Revision: ${d.contentRevision}`);
+        }
+        return;
+    }
+    if (opts.section !== undefined) {
+        // Section reads slice the stored markdown source — same no-fallback rule
+        // as --raw: a rendered-output slice would not be a legal edit base.
+        if (typeof d.sourceMarkdown !== 'string') {
+            console.error(`Error: ${d.id} has no stored markdown source (last edit was HTML-direct ` +
+                `or predates markdown source storage), so --section cannot slice it. ` +
+                `Rebuild a base first: run \`lumo doc show ${d.id}\`, reconstruct the markdown ` +
+                `faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\`.`);
+            return 1;
+        }
+        const match = (0, markdown_sections_1.findSection)(d.sourceMarkdown, opts.section);
+        if (match.kind === 'not-found') {
+            const list = match.available
+                .slice(0, 30)
+                .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)}`)
+                .join('\n');
+            console.error(`Error: section not found: "${opts.section}". Available headings:\n${list || '  (none)'}`);
+            return 1;
+        }
+        if (match.kind === 'ambiguous') {
+            const list = match.candidates
+                .map(s => `  ${'#'.repeat(s.depth)} ${(0, sanitize_1.sanitizeField)(s.heading)} (line ${s.line + 1})`)
+                .join('\n');
+            console.error(`Error: section "${opts.section}" is ambiguous — ${match.candidates.length} headings match:\n${list}\n` +
+                `Disambiguate by depth, e.g. --section "${'#'.repeat(match.candidates[0].depth)} ${match.candidates[0].heading}"`);
+            return 1;
+        }
+        // Byte-faithful slice, verbatim on stdout (legal patch base); revision on
+        // stderr for the follow-up `doc patch --if-revision`.
+        process.stdout.write((0, markdown_sections_1.extractSection)(d.sourceMarkdown, match.section));
+        if (typeof d.contentRevision === 'number') {
+            console.error(`Revision: ${d.contentRevision}`);
+        }
         return;
     }
     // Server returns `contentMarkdown` derived from the HTML body (LUM-83+).
@@ -110,6 +156,7 @@ async function docShow(reference, opts = {}) {
         projectName: d.project?.name ?? null,
         createdAt: d.createdAt ?? '',
         updatedAt: d.updatedAt ?? '',
+        revision: typeof d.contentRevision === 'number' ? d.contentRevision : null,
         mentionedTasks,
         bodyMarkdown: body,
     }));

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

@@ -75,6 +75,13 @@ async function docUpdate(reference, opts) {
     }
     if (content.kind === 'ok')
         body.contentMarkdown = content.markdown;
+    if (opts.ifRevision !== undefined) {
+        if (!/^\d+$/.test(opts.ifRevision)) {
+            console.error(`Error: --if-revision must be a non-negative integer (got "${opts.ifRevision}")`);
+            return 1;
+        }
+        body.ifRevision = Number(opts.ifRevision);
+    }
     // Resolve tag refs into ids
     const deps = { apiUrl, token: creds.token };
     let tagIds;
@@ -107,7 +114,8 @@ async function docUpdate(reference, opts) {
         body.addTagIds = addTagIds;
     if (removeTagIds !== undefined)
         body.removeTagIds = removeTagIds;
-    if (Object.keys(body).length === 0) {
+    // --if-revision is a precondition, not a field — alone it's not an update.
+    if (Object.keys(body).filter(k => k !== 'ifRevision').length === 0) {
         console.error('Error: no fields to update — provide at least one flag');
         return 1;
     }
@@ -122,6 +130,19 @@ async function docUpdate(reference, opts) {
     });
     if (!res.ok) {
         const text = await res.text();
+        if (res.status === 409 && opts.ifRevision !== undefined) {
+            let message = text;
+            try {
+                message = JSON.parse(text).error ?? text;
+            }
+            catch {
+                // non-JSON error body — print as-is
+            }
+            console.error(`Error: revision conflict: ${(0, sanitize_1.sanitizeField)(message)}`);
+            console.error(`Hint: re-read the doc (lumo doc show ${reference} --raw), rebase your edit ` +
+                `on the current source, then retry with --if-revision <current>.`);
+            return 1;
+        }
         console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
         return 1;
     }

package/dist/cli/src/index.js

@@ -109,6 +109,7 @@ const doc_sync_1 = require("./commands/doc-sync");
 const doc_update_1 = require("./commands/doc-update");
 const doc_show_1 = require("./commands/doc-show");
 const doc_diff_1 = require("./commands/doc-diff");
+const doc_section_edit_1 = require("./commands/doc-section-edit");
 const doc_list_1 = require("./commands/doc-list");
 const doc_delete_1 = require("./commands/doc-delete");
 const doc_bind_1 = require("./commands/doc-bind");
@@ -671,12 +672,30 @@ doc
     .option('--add-tag-id <cuid>', 'Add tag by id (repeatable)', collect, [])
     .option('--remove-tag <name>', 'Remove tag by name (repeatable). Unknown names are find-or-create, so prefer --remove-tag-id to avoid orphan rows.', collect, [])
     .option('--remove-tag-id <cuid>', 'Remove tag by id (repeatable). Unknown ids are a no-op.', collect, [])
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show); mismatch fails with a 409 conflict')
     .action(wrap((reference, opts) => (0, doc_update_1.docUpdate)(reference, opts)));
 doc
     .command('show <doc>')
-    .description('Show document header and body (doc = title or cuid). --raw prints the byte-identical markdown source of the last markdown upload (a legal edit base); it errors when no markdown source is stored instead of falling back to the lossy HTML→markdown render.')
+    .description('Show document header and body (doc = title or cuid). --raw prints the byte-identical markdown source of the last markdown upload (a legal edit base); it errors when no markdown source is stored instead of falling back to the lossy HTML→markdown render. --section <heading> prints just that section of the markdown source (revision goes to stderr).')
     .option('--raw', 'Print the stored markdown source verbatim (no header); errors if absent')
+    .option('--section <heading>', 'Print one heading-addressed section of the markdown source (prefix with #… to pin depth, e.g. "## Status")')
     .action(wrap((reference, opts) => (0, doc_show_1.docShow)(reference, opts)));
+doc
+    .command('patch <doc>')
+    .description('Replace one heading-addressed section of the markdown source (heading line included), leaving every byte outside the section untouched. Requires the doc to have a stored markdown source. Commits conditionally on the body revision: a concurrent edit fails with 409 instead of being overwritten.')
+    .requiredOption('--section <heading>', 'Heading of the section to replace (prefix with #… to pin depth)')
+    .option('--content <text>', 'New section content (inline markdown)')
+    .option('--file <path>', 'New section content from file')
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .action(wrap((reference, opts) => (0, doc_section_edit_1.docPatch)(reference, opts)));
+doc
+    .command('append <doc>')
+    .description('Append markdown at the end of a heading-addressed section (before the next same-or-higher heading), or at the document end when --section is omitted. Pure insertion — no existing byte is modified — which makes it the safest write for running logs/ledgers. 409 on concurrent edits.')
+    .option('--section <heading>', 'Heading of the section to append into (omit to append at the document end)')
+    .option('--content <text>', 'Content to append (inline markdown)')
+    .option('--file <path>', 'Content to append from file')
+    .option('--if-revision <n>', 'Only apply if the doc body is still at this revision (from doc show)')
+    .action(wrap((reference, opts) => (0, doc_section_edit_1.docAppend)(reference, opts)));
 doc
     .command('diff <doc>')
     .description('Compare the server-side markdown source against a local file. Exit 0 when byte-identical, 1 with a unified diff when divergent. Requires the doc to have a stored markdown source.')

package/dist/cli/src/lib/markdown-sections.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSectionQuery = exports.appendToSection = exports.replaceSection = exports.extractSection = exports.findSection = exports.listSections = void 0;
+// Single source of truth lives in shared/src/markdown-sections.ts (LUM-409) —
+// the CLI must slice sections exactly like the server does.
+var markdown_sections_1 = require("../../../shared/src/markdown-sections");
+Object.defineProperty(exports, "listSections", { enumerable: true, get: function () { return markdown_sections_1.listSections; } });
+Object.defineProperty(exports, "findSection", { enumerable: true, get: function () { return markdown_sections_1.findSection; } });
+Object.defineProperty(exports, "extractSection", { enumerable: true, get: function () { return markdown_sections_1.extractSection; } });
+Object.defineProperty(exports, "replaceSection", { enumerable: true, get: function () { return markdown_sections_1.replaceSection; } });
+Object.defineProperty(exports, "appendToSection", { enumerable: true, get: function () { return markdown_sections_1.appendToSection; } });
+Object.defineProperty(exports, "parseSectionQuery", { enumerable: true, get: function () { return markdown_sections_1.parseSectionQuery; } });

package/dist/shared/src/markdown-sections.js

@@ -0,0 +1,162 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSections = listSections;
+exports.parseSectionQuery = parseSectionQuery;
+exports.findSection = findSection;
+exports.extractSection = extractSection;
+exports.replaceSection = replaceSection;
+exports.appendToSection = appendToSection;
+const markdown_it_1 = __importDefault(require("markdown-it"));
+/**
+ * Heading-addressed section slicing over a markdown source string (LUM-409).
+ *
+ * Single source of truth shared by the documents service (server-side
+ * section patch/append) and the CLI (`doc show --section`) so both sides
+ * agree byte-for-byte on where a section starts and ends.
+ *
+ * All offsets are character offsets into the ORIGINAL source string — slices
+ * are taken with `src.slice(...)`, never re-serialized, so everything
+ * outside an edited section survives byte-identical. Headings are located
+ * with markdown-it block tokens (not a regex) so `#` lines inside fenced
+ * code blocks or blockquotes are never mistaken for section boundaries.
+ */
+const md = new markdown_it_1.default({ html: false, linkify: true, breaks: false });
+/**
+ * Start offsets of each line, splitting on the same newline shapes
+ * markdown-it normalizes before tokenizing (`\r\n` / `\r` / `\n`), so a
+ * token's `map` line number indexes this array directly.
+ */
+function computeLineStarts(src) {
+    const starts = [0];
+    for (let i = 0; i < src.length; i++) {
+        const ch = src.charCodeAt(i);
+        if (ch === 13 /* \r */) {
+            if (src.charCodeAt(i + 1) === 10 /* \n */)
+                i++;
+            starts.push(i + 1);
+        }
+        else if (ch === 10 /* \n */) {
+            starts.push(i + 1);
+        }
+    }
+    return starts;
+}
+/** List every top-level heading-addressed section of a markdown source. */
+function listSections(src) {
+    if (!src)
+        return [];
+    const tokens = md.parse(src, {});
+    const lineStarts = computeLineStarts(src);
+    const heads = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        // level === 0 keeps headings nested inside blockquotes/lists from
+        // becoming section boundaries.
+        if (t?.type === 'heading_open' && t.map && t.level === 0) {
+            const inline = tokens[i + 1];
+            heads.push({
+                depth: Number(t.tag.slice(1)),
+                text: (inline?.type === 'inline' ? inline.content : '').trim(),
+                line: t.map[0],
+            });
+        }
+    }
+    return heads.map((h, idx) => {
+        let end = src.length;
+        for (let j = idx + 1; j < heads.length; j++) {
+            const next = heads[j];
+            if (next && next.depth <= h.depth) {
+                end = lineStarts[next.line] ?? src.length;
+                break;
+            }
+        }
+        return {
+            heading: h.text,
+            depth: h.depth,
+            line: h.line,
+            startOffset: lineStarts[h.line] ?? 0,
+            endOffset: end,
+        };
+    });
+}
+/**
+ * Parse a `--section` query. A leading `#`-run constrains the heading depth
+ * (`"## Status"` only matches h2 headings titled "Status"), which is how a
+ * caller disambiguates same-text headings at different levels.
+ */
+function parseSectionQuery(raw) {
+    const m = /^(#{1,6})\s+(.*)$/.exec(raw.trim());
+    if (m)
+        return { text: (m[2] ?? '').trim(), depth: (m[1] ?? '').length };
+    return { text: raw.trim() };
+}
+/**
+ * Locate a section by heading text. Exact match first, then a
+ * case-insensitive pass; more than one hit in the winning pass is reported
+ * as ambiguous rather than silently picking one.
+ */
+function findSection(src, query) {
+    const q = parseSectionQuery(query);
+    const sections = listSections(src);
+    const pool = q.depth !== undefined ? sections.filter(s => s.depth === q.depth) : sections;
+    let matches = pool.filter(s => s.heading === q.text);
+    if (matches.length === 0) {
+        const lower = q.text.toLowerCase();
+        matches = pool.filter(s => s.heading.toLowerCase() === lower);
+    }
+    const first = matches[0];
+    if (matches.length === 1 && first)
+        return { kind: 'found', section: first };
+    if (matches.length === 0)
+        return { kind: 'not-found', available: sections };
+    return { kind: 'ambiguous', candidates: matches };
+}
+/** Byte-faithful slice of one section (heading line through section end). */
+function extractSection(src, section) {
+    return src.slice(section.startOffset, section.endOffset);
+}
+function stripOuterNewlines(text) {
+    return text.replace(/^[\r\n]+/, '').replace(/[\r\n]+$/, '');
+}
+/**
+ * Replace one section (heading included) with `newText`, verbatim. Bytes
+ * before `startOffset` and from `endOffset` on are carried over untouched;
+ * only the new block's trailing newlines are padded so a following heading
+ * still starts at the beginning of a line with a blank line before it.
+ */
+function replaceSection(src, section, newText) {
+    const before = src.slice(0, section.startOffset);
+    const after = src.slice(section.endOffset);
+    let block = newText;
+    if (after.length > 0 && block.length > 0 && !block.endsWith('\n\n')) {
+        block = block.replace(/\n*$/, '\n\n');
+    }
+    return before + block + after;
+}
+/**
+ * Insert `text` at the end of a section (or at the end of the document when
+ * `section` is null). Pure insertion: every pre-existing byte is preserved;
+ * only separator newlines around the new chunk are added as needed.
+ */
+function appendToSection(src, section, text) {
+    const insertAt = section ? section.endOffset : src.length;
+    const before = src.slice(0, insertAt);
+    const after = src.slice(insertAt);
+    const chunk = stripOuterNewlines(text);
+    if (chunk.length === 0)
+        return src;
+    let lead = '';
+    if (before.length > 0) {
+        if (before.endsWith('\n\n'))
+            lead = '';
+        else if (before.endsWith('\n') || before.endsWith('\r'))
+            lead = '\n';
+        else
+            lead = '\n\n';
+    }
+    const tail = after.length > 0 ? '\n\n' : '\n';
+    return before + lead + chunk + tail + after;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumoai/cli",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",

package/assets/skill/SKILL.md

@@ -1,160 +0,0 @@
----
-name: lumo
-description: 'Use the Lumo CLI to work with Lumo (project management for dev teams) from the terminal: load task context, bind/wrap Claude Code sessions, and create/update/list/show/comment on tasks, projects, milestones, sprints, documents, artifacts, Figma links, dependencies, and team memory — plus acceptance criteria, machine verification (verify / task status), lineage audit, worktree scaffolding, and CLI setup/auth/update. Activate when the user mentions a Lumo task identifier (LUM-N) or the lumo CLI, in any language; asks to load task background or bind/check/wrap a session; manages any of the resources above in Lumo; is starting, resuming, or about to claim completion of a task; or asks what to work on next. Key triggers: "LUM-", "lumo", "task context", "session attach", "session wrap", "verify", "task status", "acceptance criteria", "milestone", "sprint", "docs", "memory", "deps", "lineage", "worktree", "design link", "what should I work on", "resume task".'
----
-
-## Prerequisites
-
-Before running any `lumo` command, verify the CLI is available and authenticated:
-
-```bash
-which lumo && lumo whoami
-```
-
-- If `lumo` is not found: tell the user to install it (`npm install -g @lumoai/cli`; for monorepo dev, `cd cli && npm install && npm link` also works)
-- If `lumo whoami` fails with an auth error: tell the user to run `lumo auth login`
-- Do NOT proceed with any lumo commands until both checks pass
-
-## How this skill is organized
-
-The command catalog below is a **map**: it lists every command grouped by domain with a one-line summary. **Detailed flags, examples, output formats, and "when to suggest" guidance live in the `references/` files** — when a user request lands in a domain, **Read the matching reference file before composing the command**. Don't run a command from memory if its flags/edge-cases matter; open the reference first.
-
-| Domain                                                                                  | Read this reference                                            |
-| --------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-| `setup`, `auth login/logout`, `whoami`, `update`                                        | [references/onboarding.md](references/onboarding.md)           |
-| `task context`, retrieval (`slack/web/figma context`, `comments list`, `pr show`)       | [references/task-context.md](references/task-context.md)       |
-| `task create/update/list/show/comment`, `next`                                          | [references/tasks.md](references/tasks.md)                     |
-| `task artifact*`, `task figma*`                                                         | [references/artifacts-figma.md](references/artifacts-figma.md) |
-| `task criteria set/list`, drafting the acceptance contract                              | [references/criteria.md](references/criteria.md)               |
-| `verify`, `task status` — machine verification loop, claim-done flow, self-check/resume | [references/verify.md](references/verify.md)                   |
-| `project list`, `milestone*`                                                            | [references/milestones.md](references/milestones.md)           |
-| `doc*`                                                                                  | [references/docs.md](references/docs.md)                       |
-| `sprint*`                                                                               | [references/sprints.md](references/sprints.md)                 |
-| `task/project memory`, `memory promote/rm`                                              | [references/memory.md](references/memory.md)                   |
-| `session attach/status/detach/wrap`, git-suggest on start, Layer-2 review               | [references/sessions.md](references/sessions.md)               |
-| `worktree add/rm/list` (local dev tooling)                                              | [references/worktree.md](references/worktree.md)               |
-
-## Command catalog
-
-**Onboarding / auth / update** — see [onboarding.md](references/onboarding.md)
-
-- `lumo setup [--user|--project] [--force] [--agent <token>]` — install skill files + hooks
-- `lumo auth login` / `lumo auth logout` — paste an API key / clear credentials
-- `lumo whoami` — show current identity (email, workspace, key)
-- `lumo update` — upgrade the CLI to the latest npm release
-
-**Task context & retrieval** — see [task-context.md](references/task-context.md)
-
-- `lumo task context <id>` — load task background (memory, source cards, PR review todos, prior sessions)
-- `lumo task slack show <id> <contextId>` — full stored Slack thread
-- `lumo task web show <id> <linkId>` — fetched web link body
-- `lumo task figma context <id> <linkId>` — Figma link metadata (v1)
-- `lumo task comments list <id>` — full comment thread (read-only; ≠ `task comment`)
-- `lumo task pr show <id> <number>` — synced PR metadata (v1)
-- `lumo task lineage <id>` — show the causal trail: fragments that fed the task + each one's outcome + the run's token/loop cost (read-only audit view); `lumo task lineage <id> --signal` also appends workspace-level usage signal-health (used distribution, per-session variance, used-vs-base merge rate)
-
-**Tasks** — see [tasks.md](references/tasks.md)
-
-- `lumo task create <title> [flags]` — create a task
-- `lumo task update <id> [flags]` — patch status/title/priority/assignee/milestone/sprint/tags
-- `lumo task list [flags]` — list tasks assigned to you
-- `lumo next [--count N]` — recommend the next task to work on (read-only)
-- `lumo task show <id>` — print one task's detail
-- `lumo task comment <id> <body>` — leave a comment
-
-**Task dependencies**
-
-- `lumo task deps list <id>` — list dependency edges in both directions, grouped CONFIRMED / SUGGESTED (pending confirmation) / DISMISSED; each row shows a short edge id `[xxxxxxxx]`, the other task, and detected evidence (`shared_files(N shared files: …)` / `task_mention(…)`); SUGGESTED rows include a copy-pasteable confirm hint
-- `lumo task deps add <id> --blocked-by <LUM-N>` — declare a manual hard dependency (created CONFIRMED, source MANUAL; if a SUGGESTED/DISMISSED edge already exists in the same direction, it is confirmed in place rather than creating a new row)
-- `lumo task deps confirm <id> <edge> [--reverse]` — confirm a detected candidate; `<edge>` is a short edge-id prefix (≥6 chars) or the other task's identifier (case-insensitive); `--reverse` flips the direction when the detector guessed it backwards
-- `lumo task deps dismiss <id> <edge>` — dismiss a candidate (never re-suggested)
-- `lumo task deps rm <id> <edge> --yes` — delete an edge (refuses without `--yes`)
-- On an ambiguous/unknown `<edge>` selector the CLI prints all candidates with short ids and exits 1 — retry with one of them
-
-**Acceptance criteria (contract)** — see [criteria.md](references/criteria.md)
-
-- `lumo task criteria set <task> --file <criteria.json> [--human] [--cause <tag>]` — submit the whole contract: default = initial agent draft (AGENT_DRAFT, locked once submitted); `--human` = a HUMAN_EDIT revision transcribed from the conversation (desired final list; items with `id` keep/update, missing ones are deleted); `--cause` (with `--human`) annotates why the contract drifted: `NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER`
-- `lumo task criteria list <task>` — print the contract (id, MACHINE/HUMAN, provenance source@round, checkpointer)
-
-**Verification (machine acceptance loop)** — see [verify.md](references/verify.md)
-
-- `lumo verify [task] [--timeout <seconds>]` — run every MACHINE criterion's checkpointer locally, report one structured PASS/FAIL verdict per criterion to the server, print next actions. Defaults to the session-bound task. Round cap 3: an all-pass round moves the task to IN_REVIEW (agent stops there); a round-3 fail escalates to a human (stop retrying). **Run this before claiming a task is done.**
-- `lumo task status [task] [--json]` — read-only acceptance self-check (no LLM, milliseconds): the contract with each criterion's latest verdict (REVIEW_ADDED provenance visible), verification history, current round, last round's failure reasons, and `nextActions` = the unmet criteria (the declarative "what's next" — no separate plan). Defaults to the session-bound task; `--json` emits a versioned payload (`version` field). **Run it first when resuming a task in a new session or after a verification round was rejected.**
-
-**Artifacts & Figma** — see [artifacts-figma.md](references/artifacts-figma.md)
-
-- `lumo task artifact add/update/list/show/rm` — record spec/plan products on a task
-- `lumo task figma add/list/rm/refresh` — attach & manage Figma designs
-
-**Projects & milestones** — see [milestones.md](references/milestones.md)
-
-- `lumo project list` — list projects (slugs feed `--project`)
-- `lumo milestone list/create/show/update/delete` — milestone CRUD (`show` includes a Sprint-coverage section)
-- `lumo milestone archive/unarchive` — soft-archive / restore
-- `lumo milestone add/remove <id> <task...>` — batch bind/unbind tasks
-- `lumo milestone summary [--retry]` — AI retro
-- `lumo milestone reorder/move` — manual ordering
-
-**Documents** — see [docs.md](references/docs.md)
-
-- `lumo doc create/update/show/list/delete` — document CRUD
-- `lumo doc show <doc> --raw` — print the byte-identical markdown source of the last markdown upload (the only legal edit base; errors when no source is stored — never falls back to the lossy HTML→md render)
-- `lumo doc diff <doc> --file <local.md>` — compare the server-side markdown source against a local file (exit 0 identical, 1 with unified diff)
-- `lumo doc move` — reparent under a parent / to root
-- `lumo doc bind/unbind <doc> <task>` — task linkage
-- `lumo doc share/unshare/share-list` — member sharing
-- `lumo doc import-gdoc` / `lumo doc sync` — Google Doc import & re-sync
-
-**Sprints** — see [sprints.md](references/sprints.md)
-
-- `lumo sprint list/create/show/update/delete` — sprint CRUD (`show` includes Progress / Health / Blockers)
-- `lumo sprint start/close` — status transitions (no `--status` flag)
-- `lumo sprint add/remove <id> <task>` — bind/unbind a task
-- `lumo sprint summary [--retry]` — AI retro
-
-**Memory** — see [memory.md](references/memory.md)
-
-- `lumo task memory add/list` · `lumo project memory add/list` — record/curate Memory (TASK vs PROJECT)
-- `lumo memory promote <id>` / `lumo memory rm <id> --yes` — TASK→PROJECT / delete
-
-**Sessions** — see [sessions.md](references/sessions.md)
-
-- `lumo session attach <id>` — bind this session to a task (then run `task context`)
-- `lumo session status` / `lumo session detach` — show / clear binding
-- `lumo session wrap [--yes] [--dry-run] [--used <indices>]` — end-of-session panel: progress comment + memory review + fragment-usage vote (`--used`, LUM-300) + blocked-tag prompt. Usage is now also audited automatically when a task reaches DONE (evidence-gated, true-only — confident fragments marked used, the rest left NULL); `session wrap --used` remains the manual override and takes precedence for a session.
-- Git-suggest at session start (suggests `session attach`, never auto-binds) + Layer-2 project-memory review — see the reference
-
-**Worktrees (local dev tooling)** — see [worktree.md](references/worktree.md)
-
-- `lumo worktree add <LUM-N> [slug]` — scaffold `.worktrees/<LUM-N>` + node_modules symlink off origin/main; run from the main checkout
-- `lumo worktree rm <LUM-N> --yes` — remove a worktree (keeps the branch unless `--delete-branch`)
-- `lumo worktree list` — list `.worktrees/` worktrees (task id, branch, dirty, node_modules link)
-
-## Commands & flags that do NOT exist (common mistakes)
-
-Measured from real agent sessions (LUM-392) — don't guess these:
-
-- No `lumo session start` — binding is `lumo session attach <LUM-N>`
-- No `lumo task delete` — tasks can't be deleted from the CLI (web UI only)
-- No `lumo task artifact edit` — it's `lumo task artifact update`
-- No `lumo auth status` — identity check is `lumo whoami`
-- No `--body` on `lumo task comment` — the body is a positional arg: `lumo task comment LUM-N "text"`
-- No `--content` on `task/project memory add` — memory is structured fields (`--category` + per-category flags), see [memory.md](references/memory.md)
-- No global `--verbose` flag on any command
-- `lumo task comments list` (plural) **reads** the thread; `lumo task comment` (singular) **writes** one
-- Status updates: `lumo task update LUM-N --status done` is one direct call — do **not** walk `in_progress → in_review → done` step by step (see [tasks.md](references/tasks.md) for the transition matrix; under the verify flow you shouldn't be setting `in_review`/`done` yourself at all)
-
-## Core workflow
-
-Typical flow when a user says "help me with LUM-42":
-
-1. `lumo session attach LUM-42` — bind this session
-2. `lumo task context LUM-42` — load background
-3. Review unresolved items, PR-review todos, and the task description
-4. **If the task has no acceptance criteria** (context shows the draft reminder instead of a contract): draft outcome-level criteria sized to the task (3–7 for a typical multi-file task; 1–2 for a micro task) and submit them with `lumo task criteria set` **before writing the first line of code** — see [criteria.md](references/criteria.md) for the drafting guide
-5. Begin working on the task
-6. **Before claiming the work is done: run `lumo verify`** — the machine half of the acceptance loop. Fix failures and re-run (round cap 3). On all-pass the task moves to IN_REVIEW and you stop; never set DONE yourself after a verify loop — that adjudication is human-only. See [verify.md](references/verify.md)
-
-**Status-first recovery:** when you pick a task back up — a new session resuming earlier work, or a task that came back after a rejected verification round / review findings — run `lumo task status` **before** re-reading code or planning. It tells you where the loop stands (current round, what passed, what's unmet and why, any REVIEW_ADDED criteria appended during review) so you don't redo finished work or miss the reason it bounced. See [verify.md](references/verify.md)
-
-**Git-suggest at start:** when the session is unbound, session-start may infer the task from the git branch / recent commits (any team prefix, e.g. `SPEC-12`, not just `LUM-N`) and print a suggestion — `Detected LUM-N (from branch name). Run lumo session attach LUM-N to bind.` (or `from recent commits`) — **without** binding. Confirm it's the right task, then run `lumo session attach <LUM-N>` yourself (binding only happens on an explicit attach). See [sessions.md](references/sessions.md) for the full session-start behavior.