@lumoai/cli 1.28.0 → 1.29.1

package/assets/skill/SKILL.md

@@ -97,8 +97,11 @@ The command catalog below is a **map**: it lists every command grouped by domain
 
 **Documents** — see [docs.md](references/docs.md)
 
-- `lumo doc create/update/show/list/delete` — document CRUD
+- `lumo doc create/update/show/list/delete` — document CRUD; `doc show` prints the body revision, `doc update` takes `--if-revision <n>` (mismatch → 409 conflict, re-read and retry — no silent overwrite)
 - `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 show <doc> --section "<heading>"` — print just one heading-addressed section of the markdown source (byte-faithful slice, subsections included; revision on stderr; prefix `#…` pins depth)
+- `lumo doc patch <doc> --section "<heading>" --content/--file/stdin [--if-revision N]` — replace ONLY that section (heading line included); every byte outside it is untouched; concurrent edits 409 instead of clobbering
+- `lumo doc append <doc> [--section "<heading>"] --content/--file/stdin [--if-revision N]` — append at section end (or doc end without `--section`); pure insertion, no existing byte modified — the safest write for running logs/ledgers
 - `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

package/assets/skill/references/docs.md

@@ -64,6 +64,8 @@ The `Tags:` line is omitted when no tags were attached.
 | `--remove-tag <name>`    | string (repeatable) | Detach tag by name. `--remove-tag <name>` resolves the name via find-or-create on the workspace. If the name was unknown, a new Tag row is created (orphan, no attachments) before the detach runs as a no-op. Use `--remove-tag-id <cuid>` to avoid orphans. Max 20. |
 | `--remove-tag-id <cuid>` | string (repeatable) | Detach tag by id. Unknown ids are a no-op (no side effects). Max 20.                                                                                                                                                                                                  |
 
+Optimistic concurrency (LUM-409): `--if-revision <n>` only applies the update if the doc body is still at revision `n` (from `doc show`). Mismatch → 409 conflict, nothing written — re-read, rebase, retry. `--if-revision` alone is not an update (still errors "no fields to update").
+
 `--tag` / `--tag-id` (bulk replace) are mutually exclusive with `--add-tag` / `--add-tag-id` / `--remove-tag` / `--remove-tag-id`. The CLI errors before any network call if both families are mixed.
 
 Like `doc create`, `--file` is sandboxed: the CLI rejects paths that resolve outside the project directory or match the sensitive-file denylist (`.env*`, private keys, `credentials`, …). No override flag.
@@ -82,16 +84,19 @@ lumo doc update RFC --tag final --add-tag oops
 
 ### When to suggest `doc update`
 
-- User wants to revise an existing doc.
+- User wants to revise an existing doc **as a whole** (title, scope, or a full-body rewrite).
 - After running `lumo doc list` or `doc show`, if the user wants to change a doc's scope, title, or content.
+- For a small edit inside one section, prefer `doc patch` / `doc append` (below) — full `doc update` has the maximum clobber radius.
+- When replacing the body from a previously fetched base, pass `--if-revision` so a concurrent edit fails loudly (409) instead of being overwritten.
 
-### `lumo doc show <doc> [--raw]` — print one document's detail
+### `lumo doc show <doc> [--raw | --section <heading>]` — print one document's detail
 
-Default mode prints a key:value header (id, title, scope, project, created/updated timestamps, mentioned tasks) and the content rendered back to markdown.
+Default mode prints a key:value header (id, title, scope, project, created/updated timestamps, **revision**, mentioned tasks) and the content rendered back to markdown. `Revision:` is the body's optimistic-concurrency counter — feed it back as `--if-revision` on `doc update` / `doc patch` / `doc append`.
 
 ```bash
 lumo doc show "RFC: doc CLI"
-lumo doc show cmd_xxx --raw > base.md   # byte-identical edit base
+lumo doc show cmd_xxx --raw > base.md            # byte-identical edit base (revision on stderr)
+lumo doc show cmd_xxx --section "D 状态表" > sec.md  # one section only (revision on stderr)
 ```
 
 **`--raw` (LUM-408)** prints the byte-identical markdown source of the last markdown upload — no header, no trailing newline added. The server stores the raw markdown (`sourceMarkdown`) alongside the rendered HTML on every markdown write (`doc create/update --content/--file/stdin`, gdoc import/sync), so `--raw` output IS a legal edit base: `doc show --raw > base.md`, edit, `doc update --file base.md` round-trips losslessly.
@@ -102,13 +107,74 @@ lumo doc show cmd_xxx --raw > base.md   # byte-identical edit base
 
 Note: the markdown rendered by **default-mode** `doc show` is still best-effort (tables flatten). Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT a no-op — use `--raw` as the edit base instead.
 
-Use default mode when the user wants to read a doc; use `--raw` whenever the output will be edited and uploaded back.
+**`--section <heading>` (LUM-409)** prints just one heading-addressed section of the markdown source — a byte-faithful slice from the heading line through (not including) the next same-or-higher-level heading, subsections included. No header on stdout (the slice is a legal `doc patch` base); the current revision is printed to **stderr** as `Revision: N`. Mutually exclusive with `--raw`.
+
+- Section addressing: pass the heading text (`--section "D 状态表"`), case-insensitive fallback after an exact pass. Prefix with `#…` to pin the level when the same text exists at several depths (`--section "## Status"`).
+- Missing heading → exit 1 listing the available headings; ambiguous heading → exit 1 with a depth-disambiguation hint.
+- Requires a stored markdown source — same no-fallback rule and rebuild flow as `--raw`.
+- Heading detection is markdown-aware: `#` lines inside fenced code blocks or blockquotes are never section boundaries.
+
+Use default mode when the user wants to read a doc; use `--raw` whenever the full output will be edited and uploaded back; use `--section` when only one part matters (keeps the context window small and the patch radius smaller).
 
-### When to suggest `doc show --raw`
+### When to suggest `doc show --raw` / `--section`
 
 - Before any `doc update --file` that starts from existing remote content — fetch the base with `--raw`, never from rendered `doc show` output.
+- Before a `doc patch` — read the section with `--section` first, note the `Revision:` line, edit, patch back with `--if-revision`.
 - User asks "what's the exact source of this doc", or an agent needs a faithful local copy of a live doc.
-- If `--raw` errors (no stored source), walk the rebuild flow above instead of editing the rendered output.
+- User asks "what's in section X" of a long doc — `--section` avoids pulling the whole body into context.
+- If `--raw`/`--section` errors (no stored source), walk the rebuild flow above instead of editing the rendered output.
+
+### `lumo doc patch <doc> --section <heading>` — replace one section
+
+Replaces the **whole addressed section** (heading line included, subsections included) with the provided content, server-side, leaving every byte outside the section untouched. The new content comes from `--content`, `--file`, or piped stdin (one required; `--file` is sandboxed like `doc update`).
+
+| Flag                  | Type   | Notes                                                                                               |
+| --------------------- | ------ | --------------------------------------------------------------------------------------------------- |
+| `--section <heading>` | string | Required. Heading text addressing the section; prefix `#…` pins the depth.                          |
+| `--content <text>`    | string | New section content (include the heading line — the whole section is replaced verbatim).            |
+| `--file <path>`       | string | New section content from file (project-local sandbox).                                              |
+| `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`. Recommended whenever the edit base was read earlier. |
+
+Concurrency: the splice always commits **conditionally** on the revision the server read the source at — even without `--if-revision`, a concurrent body edit between read and write returns 409 instead of clobbering. On 409 the CLI prints the server reason plus a re-read-and-retry hint and exits 1.
+
+Requires a stored markdown source (same rule as `--raw`); errors with the rebuild hint otherwise. Replacement is verbatim — if the new content omits the heading line, the heading is gone (that is an explicit choice, not a merge).
+
+```bash
+lumo doc show cmd_xxx --section "D 状态表" > sec.md   # stderr: Revision: 6
+# … edit sec.md …
+lumo doc patch cmd_xxx --section "D 状态表" --file sec.md --if-revision 6
+# → Patched cmd_xxx "登记册" § "D 状态表"  revision 7
+```
+
+### When to suggest `doc patch`
+
+- User wants to change one section of a live doc ("update the status table", "rewrite section D") — patch beats full `doc update` on clobber radius and context size.
+- Live-doc status updates that used to be read-whole/edit/upload-whole round-trips.
+- If the patch 409s: re-read the section, rebase the edit, retry — never fall back to a full-body upload from the stale base.
+
+### `lumo doc append <doc> [--section <heading>]` — append to a section (or the doc)
+
+Inserts the new content at the **end of the addressed section** (just before the next same-or-higher-level heading), or at the end of the document when `--section` is omitted. Pure insertion: no pre-existing byte is modified, which makes it the natural write for running logs, ledgers and queues. Content channels and sandbox are the same as `doc patch`; separator blank lines are added automatically.
+
+| Flag                  | Type   | Notes                                                                       |
+| --------------------- | ------ | --------------------------------------------------------------------------- |
+| `--section <heading>` | string | Optional. Omit to append at the document end.                               |
+| `--content <text>`    | string | Content to append.                                                          |
+| `--file <path>`       | string | Content from file (project-local sandbox).                                  |
+| `--if-revision <n>`   | int    | Only apply if the body is still at revision `n`; 409 + retry hint otherwise. |
+
+Same concurrency contract as `doc patch` (always a conditional commit; 409 on conflict). Requires a stored markdown source.
+
+```bash
+lumo doc append cmd_xxx --section "F 待办队列" --content "- [ ] 评估 XYZ 论文"
+# → Appended to cmd_xxx "登记册" § "F 待办队列"  revision 8
+echo "## 2026-06-10\n吸收了 3 篇" | lumo doc append cmd_xxx   # document end
+```
+
+### When to suggest `doc append`
+
+- User wants to add an entry/row/log line to a section ("把 X 加进待办队列", "append today's notes") — this is the killer op for ledger-style live docs: zero clobber risk by construction.
+- Whenever the alternative would be re-uploading the whole doc just to add lines at the end of one section.
 
 ### `lumo doc diff <doc> --file <local.md>` — compare remote markdown source vs a local file
 

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

@@ -51,7 +51,7 @@ async function docList(opts) {
     }
     else {
         const params = new URLSearchParams();
-        if (opts.scope && opts.scope !== 'all') {
+        if (opts.scope && opts.scope.toLowerCase() !== 'all') {
             const v = (0, doc_create_1.normalizeScope)(opts.scope);
             if (!v) {
                 console.error(`Error: invalid scope "${opts.scope}". Allowed: personal, workspace, all`);
@@ -74,7 +74,7 @@ async function docList(opts) {
     }
     const { documents } = (await res.json());
     let rows = documents;
-    if (opts.task && opts.scope && opts.scope !== 'all') {
+    if (opts.task && opts.scope && opts.scope.toLowerCase() !== 'all') {
         const v = (0, doc_create_1.normalizeScope)(opts.scope);
         if (v)
             rows = rows.filter(r => r.visibility === v);

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");
@@ -255,7 +256,7 @@ task
 task
     .command('list')
     .description('List tasks assigned to you. Filter with --status, --project, --milestone, --limit.')
-    .option('-s, --status <value>', 'Filter by status: todo | in_progress | in_review | done')
+    .option('-s, --status <value>', 'Filter by status: todo | in_progress | in_review | done (case-insensitive)')
     .option('-p, --project <ref>', 'Filter by project name (case-insensitive)')
     .option('-n, --limit <count>', 'Show only the first N tasks')
     .option('-m, --milestone <ref>', 'Filter by milestone name or UUID (scopes to my tasks under that milestone)')
@@ -277,7 +278,7 @@ task
     .command('create <title>')
     .description('Create a task. --project required when workspace has >1 project; defaults: priority=low, assignee=me.')
     .option('-d, --description <text>', 'Task description')
-    .option('-p, --priority <level>', 'Priority: low | medium | high | urgent (default: low)')
+    .option('-p, --priority <level>', 'Priority: low | medium | high | urgent (case-insensitive; default: low)')
     .option('-a, --assignee <ref>', 'Assignee email, name, or "me" (default: me)')
     .option('--project <ref>', 'Project name or slug')
     .option('--milestone <ref>', 'Milestone name (case-insensitive)')
@@ -376,7 +377,7 @@ const taskMemory = task
 taskMemory
     .command('list [task]')
     .description("List a task's memories. <task> defaults to the session-bound task.")
-    .option('--category <cat>', 'Filter by trap|decision|convention|procedural')
+    .option('--category <cat>', 'Filter by trap|decision|convention|procedural (case-insensitive)')
     .option('-n, --limit <count>', 'Cap output to the first N rows')
     .action(wrap((taskArg, opts) => (0, memory_task_list_1.memoryTaskList)(taskArg, opts)));
 taskMemory
@@ -384,7 +385,7 @@ taskMemory
     .description('Record a memory on a task (<task> defaults to the bound session). ' +
     'Record only knowledge invisible in the codebase (the why, a runtime gotcha, a non-obvious failure, a non-trivial workflow); skip routine work. ' +
     'Pick --category then its fields.')
-    .requiredOption('--category <cat>', 'trap | decision | convention | procedural')
+    .requiredOption('--category <cat>', 'trap | decision | convention | procedural (case-insensitive)')
     .option('--trigger <text>', 'trap/procedural: the situation that triggers it')
     .option('--outcome <text>', 'trap: what goes wrong')
     .option('--workaround <text>', 'trap: optional fix')
@@ -396,7 +397,7 @@ taskMemory
     .option('--applies <text>', 'convention: where the rule applies')
     .option('--workflow <text>', 'procedural: the workflow name')
     .option('--step <text>', 'procedural: a step (repeatable)', collect, [])
-    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)')
+    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive; default claude-code)')
     .action(wrap((taskArg, opts) => (0, memory_task_add_1.memoryTaskAdd)(taskArg, opts)));
 const taskCriteria = task
     .command('criteria')
@@ -406,7 +407,7 @@ taskCriteria
     .description('Submit the whole acceptance contract from a JSON file. Default = initial agent draft (locked once submitted); --human records a HUMAN_EDIT revision (desired final list; items with "id" keep/update, missing ones are deleted).')
     .requiredOption('--file <path>', 'JSON array of criteria: [{"statement","verifierType":"MACHINE"|"HUMAN","checkpointer?","evidenceRequired?","id?"}]')
     .option('--human', 'Record a human contract revision (HUMAN_EDIT) transcribed from the conversation, with session provenance')
-    .option('--cause <tag>', 'Why the contract drifted (with --human): NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER')
+    .option('--cause <tag>', 'Why the contract drifted (with --human): NEW_INFO | SCOPE_CHANGE | DRAFT_BLIND_SPOT | GRANULARITY | OTHER (case-insensitive)')
     .action(wrap((taskId, options) => (0, task_criteria_set_1.taskCriteriaSet)(taskId, options)));
 taskCriteria
     .command('list <task>')
@@ -422,7 +423,7 @@ taskArtifact
     .requiredOption('--title <title>', 'Artifact title')
     .requiredOption('--file <path>', 'File whose contents become the artifact body')
     .requiredOption('--source <source>', 'Spec-gen framework, formal name e.g. Superpowers | "Spec Kit" | BMad | OpenSpec | GSD (opaque; quote names with spaces)')
-    .requiredOption('--agent <agent>', 'Coding tool that produced the artifact: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf')
+    .requiredOption('--agent <agent>', 'Coding tool that produced the artifact: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive)')
     .action(wrap((taskId, options) => (0, task_artifact_add_1.taskArtifactAdd)(taskId, options)));
 taskArtifact
     .command('update <task> <artifact-id>')
@@ -430,7 +431,7 @@ taskArtifact
     .option('--kind <kind>', 'New artifact kind (opaque)')
     .option('--title <title>', 'New artifact title')
     .option('--source <source>', 'New spec-gen framework, formal name e.g. Superpowers | "Spec Kit" | BMad | OpenSpec | GSD (quote names with spaces)')
-    .option('--agent <agent>', 'New coding tool: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf')
+    .option('--agent <agent>', 'New coding tool: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive)')
     .action(wrap((taskId, artifactId, options) => (0, task_artifact_update_1.taskArtifactUpdate)(taskId, artifactId, options)));
 taskArtifact
     .command('list <task>')
@@ -458,13 +459,13 @@ const projectMemory = projectCmd
 projectMemory
     .command('list [project]')
     .description("List a project's PROJECT-scope memories. <project> defaults to the bound task's project.")
-    .option('--category <cat>', 'Filter by trap|decision|convention|procedural')
+    .option('--category <cat>', 'Filter by trap|decision|convention|procedural (case-insensitive)')
     .option('-n, --limit <count>', 'Cap output to the first N rows')
     .action(wrap((p, opts) => (0, memory_project_list_1.memoryProjectList)(p, opts)));
 projectMemory
     .command('add [project]')
     .description("Record a PROJECT-scope memory. Use PROJECT scope only when the lesson helps any task in the project. <project> defaults to the bound task's project.")
-    .requiredOption('--category <cat>', 'trap | decision | convention | procedural')
+    .requiredOption('--category <cat>', 'trap | decision | convention | procedural (case-insensitive)')
     .option('--trigger <text>', 'trap/procedural trigger')
     .option('--outcome <text>', 'trap outcome')
     .option('--workaround <text>', 'trap optional workaround')
@@ -476,7 +477,7 @@ projectMemory
     .option('--applies <text>', 'convention: where it applies')
     .option('--workflow <text>', 'procedural workflow')
     .option('--step <text>', 'procedural step (repeatable)', collect, [])
-    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (default claude-code)')
+    .option('--agent <agent>', 'Producing agent: claude-code | codex | cursor | gemini-cli | github-copilot | windsurf (case-insensitive; default claude-code)')
     .action(wrap((p, opts) => (0, memory_project_add_1.memoryProjectAdd)(p, opts)));
 const memoryCmd = program
     .command('memory')
@@ -520,7 +521,7 @@ milestoneCmd
     .option('--project <ref>', 'Project name or slug (when identifier is a name)')
     .option('-n, --name <text>', 'New name')
     .option('-d, --description <text>', 'New description (empty string to clear)')
-    .option('-s, --status <value>', 'New status: planned | active | completed | cancelled')
+    .option('-s, --status <value>', 'New status: planned | active | completed | cancelled (case-insensitive)')
     .option('--start <date>', 'Start date YYYY-MM-DD (empty string to clear)')
     .option('--target <date>', 'Target date YYYY-MM-DD (empty string to clear)')
     .action(wrap((identifier, options) => (0, milestone_update_1.milestoneUpdate)(identifier, options)));
@@ -640,7 +641,7 @@ doc
     .description('Create a new document. Body comes from --content, --file, or piped stdin (pick one). --scope defaults to personal. Use --task LUM-N to bind the new doc to a task, --parent to file it under another doc.')
     .option('--content <text>', 'Inline markdown content')
     .option('--file <path>', 'Read markdown content from file')
-    .option('--scope <scope>', 'personal | workspace (default: personal)')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive; default: personal)')
     .option('--project <ref>', 'Project name or slug to file under')
     .option('--task <LUM-N>', 'Bind to this task after creation')
     .option('--parent <doc>', 'File under this parent doc (cuid or title)')
@@ -650,7 +651,7 @@ doc
 doc
     .command('import-gdoc <url>')
     .description('Import a Google Doc as a Lumo doc (one-way Google → Lumo)')
-    .option('--scope <scope>', 'personal | workspace (default: personal)')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive; default: personal)')
     .option('--task <LUM-N>', 'Bind the imported doc to this task')
     .action(wrap((url, opts) => (0, doc_import_gdoc_1.docImportGdoc)(url, opts)));
 doc
@@ -663,7 +664,7 @@ doc
     .option('--title <text>', 'New title')
     .option('--content <text>', 'Replace content (inline)')
     .option('--file <path>', 'Replace content from file')
-    .option('--scope <scope>', 'personal | workspace')
+    .option('--scope <scope>', 'personal | workspace (case-insensitive)')
     .option('--project <ref>', 'Project name/slug; pass "" to clear')
     .option('--tag <name>', 'Set tags by name (bulk replace, repeatable)', collect, [])
     .option('--tag-id <cuid>', 'Set tags by id (bulk replace, repeatable)', collect, [])
@@ -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.')
@@ -685,7 +704,7 @@ doc
 doc
     .command('list')
     .description('List documents visible to the current user')
-    .option('--scope <scope>', 'personal | workspace | all (default: all)')
+    .option('--scope <scope>', 'personal | workspace | all (case-insensitive; default: all)')
     .option('--project <ref>', 'Filter by project name/slug')
     .option('--task <LUM-N>', 'Only docs bound to this task')
     .option('--limit <n>', 'Cap output to first N rows')
@@ -713,7 +732,7 @@ doc
 doc
     .command('share <doc> <member>')
     .description('Share a document with a workspace member. PRIVATE docs are auto-promoted to SHARED. <member> accepts "me", an email, or a display name.')
-    .option('--role <role>', 'viewer | editor | manager (default: viewer)')
+    .option('--role <role>', 'viewer | editor | manager (case-insensitive; default: viewer)')
     .action(wrap((docRef, member, opts) => (0, doc_share_1.docShare)(docRef, member, opts)));
 doc
     .command('unshare <doc> <member>')
@@ -728,8 +747,8 @@ task
     .description('Update a task. Provide at least one of --title, --description, --status, --priority, --assignee, --milestone, --sprint, or tag flags. Use "" to clear description, assignee, milestone, or sprint binding. --tag/--tag-id (bulk replace) cannot be combined with --add-tag/--add-tag-id/--remove-tag/--remove-tag-id.')
     .option('-t, --title <text>', 'New title')
     .option('-d, --description <text>', 'New description (empty string to clear)')
-    .option('-s, --status <value>', 'New status: todo | in_progress | in_review | done')
-    .option('-p, --priority <level>', 'New priority: low | medium | high | urgent')
+    .option('-s, --status <value>', 'New status: todo | in_progress | in_review | done (case-insensitive)')
+    .option('-p, --priority <level>', 'New priority: low | medium | high | urgent (case-insensitive)')
     .option('-a, --assignee <ref>', 'New assignee: email, name, or "me" (empty string to clear)')
     .option('--milestone <ref>', 'Milestone name (case-insensitive); empty string to unbind')
     .option('--sprint <ref>', 'Sprint number or UUID to bind the task to; empty string to unbind from current sprint')

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.1",
   "description": "Lumo CLI — manage tasks and sessions from the terminal",
   "license": "MIT",
   "author": "cli@uselumo.ai",