@lumoai/cli 1.26.0 → 1.27.0

package/assets/skill/SKILL.md

@@ -98,6 +98,8 @@ 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 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

package/assets/skill/references/docs.md

@@ -85,17 +85,50 @@ lumo doc update RFC --tag final --add-tag oops
 - User wants to revise an existing doc.
 - After running `lumo doc list` or `doc show`, if the user wants to change a doc's scope, title, or content.
 
-### `lumo doc show <doc>` — print one document's detail
+### `lumo doc show <doc> [--raw]` — print one document's detail
 
-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, mentioned tasks) and the content rendered back to markdown.
 
 ```bash
 lumo doc show "RFC: doc CLI"
+lumo doc show cmd_xxx --raw > base.md   # byte-identical edit base
 ```
 
-Note: the markdown rendered by `doc show` is best-effort. Round-trip via `doc show > tmp.md && doc update --file tmp.md` is NOT guaranteed to be a no-op.
+**`--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.
 
-Use when the user wants the current state or content of a doc without loading full task context.
+- A web-editor (HTML-direct) edit or revision restore **invalidates** the stored source — the doc's markdown source is gone until the next markdown upload.
+- When no source is stored (legacy doc or after an HTML edit), `--raw` **fails with exit 1 and a rebuild hint** — it never silently falls back to the lossy HTML→markdown reverse render (that fallback flattened tables: LUM-349). Rebuild flow: `doc show` (rendered) → reconstruct the markdown faithfully → `doc update --file rebuilt.md` → `--raw` works from then on.
+- Raw output is verbatim (unsanitized) by design — redirect it to a file rather than reading it in a terminal when the doc's provenance is uncertain.
+
+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.
+
+### When to suggest `doc show --raw`
+
+- Before any `doc update --file` that starts from existing remote content — fetch the base with `--raw`, never from rendered `doc show` output.
+- 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.
+
+### `lumo doc diff <doc> --file <local.md>` — compare remote markdown source vs a local file
+
+Compares the server-side stored markdown source (the byte-identical last markdown upload) against a local file, making remote/local split-brain visible on demand.
+
+| Flag            | Type   | Notes                                                                              |
+| --------------- | ------ | ---------------------------------------------------------------------------------- |
+| `--file <path>` | string | Required. Local markdown file; same project-local sandbox as `doc update --file`. |
+
+Exit codes: **0** = byte-identical (prints `Clean: …`), **1** = divergent (prints a unified diff, `--- remote/<id> (sourceMarkdown)` vs `+++ local/<file>`) or error. A doc without a stored markdown source errors explicitly (upload a markdown base once, then diff works).
+
+```bash
+lumo doc diff cmd_xxx --file docs/live-docs/research-intake-ledger.md
+```
+
+### When to suggest `doc diff`
+
+- Before uploading a locally edited file with `doc update --file` — check whether the remote source moved since the local copy was taken (prevents stale-upload clobbering, the #460 incident class).
+- When a repo-tracked markdown source (e.g. `docs/live-docs/`) and the live doc may have drifted and the user asks which is current.
+- After a suspected concurrent edit: a clean diff (exit 0) proves remote and local are in sync.
 
 ### `lumo doc list [flags]` — list documents
 
@@ -298,7 +331,7 @@ Synced cmd_xxx "Quarterly Plan" from Google
 The CLI does **not** currently support:
 
 - `--from-editor` (interactive $EDITOR).
-- Lossless markdown round-trip.
+- Lossless markdown round-trip from **rendered** `doc show` output (use `doc show --raw` — lossless whenever a markdown source is stored).
 - Reordering siblings within the same parent (`--before` / `--after`); use the Web UI for that.
 
 ### When to suggest session binding for docs

package/assets/skill/references/memory.md

@@ -45,17 +45,29 @@ the bound task; `lumo project memory add ...` records onto its project.
 
 The command prints **one** of these outcome lines:
 
-| Output line | Meaning |
-|---|---|
-| `Added <CATEGORY> <SCOPE> memory …` | No near-duplicate found; stored as a new row. |
-| `Merged into existing memory <id> (near-duplicate) …` | Near-duplicate found; the existing row was refined/updated in-place (UPDATE). |
-| `Superseded an existing memory; new version <id> …` | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
-| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP). |
+| Output line                                                      | Meaning                                                                                  |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `Added <CATEGORY> <SCOPE> memory …`                              | No near-duplicate found; stored as a new row.                                            |
+| `Merged into existing memory <id> (near-duplicate) …`            | Near-duplicate found; the existing row was refined/updated in-place (UPDATE).            |
+| `Superseded an existing memory; new version <id> …`              | New content contradicts an old memory; old row invalidated, new row created (SUPERSEDE). |
+| `Skipped — duplicate of existing memory <id>, nothing written …` | Exact or near-exact duplicate; no write performed (NOOP).                                |
 
 Content is **always normalized to English** before storing — the memory store has
 a single canonical language. If you supply text in another language the CLI
 translates it automatically; the stored memory will be in English.
 
+### Lumo memory vs the harness memory tool
+
+Claude Code / the Claude API may expose a file-based **memory tool** (a
+`/memories` directory the model writes autonomously). That store is the agent's
+private scratchpad — un-grounded, free-form, invisible to the team, and outside
+Lumo's flywheel. **Project engineering lessons always go through `lumo task/project
+memory add`** — never record them only in the harness memory tool, and never bulk-copy
+harness memory files into Lumo memory (they are ungrounded drafts; Lumo's
+extract→ground→reconcile write path is the only vetted entry). The two stores are
+layered, not mirrored: transient working notes may live in the harness tool,
+durable team knowledge lives in Lumo memory.
+
 ### When to record a memory (worthiness)
 
 Record only knowledge that is **invisible in the codebase** — the _why_ behind a

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

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docDiff = docDiff;
+const config_1 = require("../lib/config");
+const api_1 = require("../lib/api");
+const resolve_doc_id_1 = require("../lib/resolve-doc-id");
+const sanitize_1 = require("../lib/sanitize");
+const doc_input_1 = require("../lib/doc-input");
+const path_guard_1 = require("../lib/path-guard");
+const unified_diff_1 = require("../lib/unified-diff");
+/**
+ * `lumo doc diff <doc> --file <local.md>` (LUM-408).
+ *
+ * Compares the server-side markdown source (Document.sourceMarkdown — the
+ * byte-identical last markdown upload) against a local file, so a
+ * remote/local split-brain is visible on demand instead of discovered from
+ * memory after a stale upload clobbers someone's edit.
+ *
+ * Exit codes: 0 = sources byte-identical, 1 = divergent (or error).
+ */
+async function docDiff(reference, opts) {
+    if (!reference) {
+        console.error('Error: missing <doc>. Usage: lumo doc diff <doc> --file <local.md>');
+        return 1;
+    }
+    if (!opts.file) {
+        console.error('Error: --file <local.md> is required for doc diff');
+        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);
+    // Same sandbox as doc create/update --file: project-local, non-sensitive.
+    const check = (0, path_guard_1.checkArtifactFilePath)(opts.file);
+    if (!check.ok) {
+        console.error(check.reason === 'unreadable'
+            ? `Error: ${(0, doc_input_1.unreadableFileMessage)(opts.file)}`
+            : `Error: refusing to read ${opts.file} — ${check.detail}. ` +
+                `--file must be a non-sensitive path inside the project directory.`);
+        return 1;
+    }
+    const localText = await (0, doc_input_1.readFileUtf8)(check.resolved);
+    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 res = await fetch(`${(0, api_1.trimTrailingSlash)(apiUrl)}/api/documents/${id}`, {
+        headers: { Authorization: `Bearer ${creds.token}` },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        console.error(`Error: ${res.status} ${res.statusText}: ${(0, sanitize_1.sanitizeField)(text)}`);
+        return 1;
+    }
+    const data = (await res.json());
+    const d = data.document;
+    if (!d) {
+        console.error('Error: server returned an empty document response');
+        return 1;
+    }
+    if (typeof d.sourceMarkdown !== 'string') {
+        console.error(`Error: ${d.id} has no stored markdown source to diff against (last edit ` +
+            `was HTML-direct or predates markdown source storage). Upload a markdown ` +
+            `base once (\`lumo doc update ${d.id} --file <base.md>\`) and diff from then on.`);
+        return 1;
+    }
+    if (d.sourceMarkdown === localText) {
+        console.log(`Clean: remote markdown source of ${d.id} matches ${opts.file} (${Buffer.byteLength(localText, 'utf8')} bytes)`);
+        return;
+    }
+    const diff = (0, unified_diff_1.formatUnifiedDiff)(d.sourceMarkdown, localText, `remote/${d.id} (sourceMarkdown)`, `local/${opts.file}`);
+    // Byte-level divergence with identical line sequences (e.g. trailing
+    // newline only) still counts as divergent — say so explicitly.
+    console.log(diff !== ''
+        ? (0, sanitize_1.sanitizeField)(diff)
+        : `Divergent: byte-level difference only (e.g. trailing newline) between remote ${d.id} and ${opts.file}`);
+    return 1;
+}

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

@@ -27,9 +27,9 @@ function formatShowOutput(vm) {
     const header = lines.join('\n');
     return vm.bodyMarkdown ? `${header}\n\n${(0, sanitize_1.sanitizeField)(vm.bodyMarkdown)}` : header;
 }
-async function docShow(reference) {
+async function docShow(reference, opts = {}) {
     if (!reference) {
-        console.error('Error: missing <doc>. Usage: lumo doc show <doc>');
+        console.error('Error: missing <doc>. Usage: lumo doc show <doc> [--raw]');
         return 1;
     }
     const creds = (0, config_1.readCredentials)();
@@ -58,6 +58,23 @@ async function docShow(reference) {
         console.error('Error: server returned an empty document response');
         return 1;
     }
+    if (opts.raw) {
+        // Byte-identical markdown source of the last markdown upload (LUM-408).
+        // Written verbatim (no header, no sanitization, no added newline) so the
+        // output is a legal edit base: `doc show --raw > base.md` round-trips.
+        // No silent fallback to the lossy HTML→markdown reverse render — that
+        // fallback is exactly what flattened tables in LUM-349.
+        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). --raw refuses to fall back to the ` +
+                `lossy HTML→markdown render. Rebuild a base instead: run \`lumo doc show ${d.id}\`, ` +
+                `reconstruct the markdown faithfully, then \`lumo doc update ${d.id} --file <rebuilt.md>\` ` +
+                `— from then on --raw works.`);
+            return 1;
+        }
+        process.stdout.write(d.sourceMarkdown);
+        return;
+    }
     // Server returns `contentMarkdown` derived from the HTML body (LUM-83+).
     // Fall back to parsing the raw content as legacy Tiptap JSON for docs
     // written before the storage shape changed.

package/dist/cli/src/index.js

@@ -107,6 +107,7 @@ const doc_import_gdoc_1 = require("./commands/doc-import-gdoc");
 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_list_1 = require("./commands/doc-list");
 const doc_delete_1 = require("./commands/doc-delete");
 const doc_bind_1 = require("./commands/doc-bind");
@@ -665,8 +666,14 @@ doc
     .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)')
-    .action(wrap(reference => (0, doc_show_1.docShow)(reference)));
+    .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.')
+    .option('--raw', 'Print the stored markdown source verbatim (no header); errors if absent')
+    .action(wrap((reference, opts) => (0, doc_show_1.docShow)(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.')
+    .requiredOption('--file <path>', 'Local markdown file to compare against')
+    .action(wrap((reference, opts) => (0, doc_diff_1.docDiff)(reference, opts)));
 doc
     .command('list')
     .description('List documents visible to the current user')

package/dist/cli/src/lib/unified-diff.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Minimal line-based unified diff (LUM-408, `lumo doc diff`).
+ *
+ * Pure and dependency-free: the CLI ships only commander + markdown-it, and
+ * shelling out to system `diff` would not be portable. Equality (the exit
+ * code) is decided on raw bytes by the caller — this renderer only has to
+ * make the divergence readable, so a plain LCS with a size guard is enough.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatUnifiedDiff = formatUnifiedDiff;
+const CONTEXT_LINES = 3;
+/** Above this old×new line product the LCS table is too big — degrade to a single whole-block hunk. */
+const MAX_LCS_CELLS = 4_000_000;
+function splitLines(text) {
+    return text.split('\n');
+}
+/** LCS-based op list for the (already prefix/suffix-trimmed) middle section. */
+function diffOps(oldLines, newLines) {
+    const n = oldLines.length;
+    const m = newLines.length;
+    if (n * m > MAX_LCS_CELLS) {
+        return [
+            ...oldLines.map(text => ({ type: 'del', text })),
+            ...newLines.map(text => ({ type: 'add', text })),
+        ];
+    }
+    // lcs[i][j] = LCS length of oldLines[i:] vs newLines[j:]
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            lcs[i][j] =
+                oldLines[i] === newLines[j]
+                    ? lcs[i + 1][j + 1] + 1
+                    : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+        }
+    }
+    const ops = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (oldLines[i] === newLines[j]) {
+            ops.push({ type: 'ctx', text: oldLines[i] });
+            i++;
+            j++;
+        }
+        else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+            ops.push({ type: 'del', text: oldLines[i] });
+            i++;
+        }
+        else {
+            ops.push({ type: 'add', text: newLines[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        ops.push({ type: 'del', text: oldLines[i++] });
+    while (j < m)
+        ops.push({ type: 'add', text: newLines[j++] });
+    return ops;
+}
+/**
+ * Render a unified diff between two texts. Returns '' when the line
+ * sequences are identical (callers decide byte-equality separately —
+ * e.g. a trailing-newline-only difference still flips the exit code).
+ */
+function formatUnifiedDiff(oldText, newText, oldLabel, newLabel) {
+    const oldAll = splitLines(oldText);
+    const newAll = splitLines(newText);
+    // Trim the common prefix/suffix so the LCS only sees the changed middle.
+    let prefix = 0;
+    while (prefix < oldAll.length &&
+        prefix < newAll.length &&
+        oldAll[prefix] === newAll[prefix]) {
+        prefix++;
+    }
+    let suffix = 0;
+    while (suffix < oldAll.length - prefix &&
+        suffix < newAll.length - prefix &&
+        oldAll[oldAll.length - 1 - suffix] === newAll[newAll.length - 1 - suffix]) {
+        suffix++;
+    }
+    const middleOps = diffOps(oldAll.slice(prefix, oldAll.length - suffix), newAll.slice(prefix, newAll.length - suffix));
+    if (!middleOps.some(op => op.type !== 'ctx'))
+        return '';
+    // Re-attach trimmed context so hunks can carry CONTEXT_LINES around edits.
+    const ops = [
+        ...oldAll.slice(0, prefix).map(text => ({ type: 'ctx', text })),
+        ...middleOps,
+        ...oldAll
+            .slice(oldAll.length - suffix)
+            .map(text => ({ type: 'ctx', text })),
+    ];
+    // Group ops into hunks: a change plus up to CONTEXT_LINES of context on
+    // each side; nearby changes merge into one hunk.
+    const lines = [`--- ${oldLabel}`, `+++ ${newLabel}`];
+    let oldLineNo = 1;
+    let newLineNo = 1;
+    let idx = 0;
+    while (idx < ops.length) {
+        if (ops[idx].type === 'ctx') {
+            oldLineNo++;
+            newLineNo++;
+            idx++;
+            continue;
+        }
+        // Found a change — open a hunk starting CONTEXT_LINES back.
+        let hunkStart = idx;
+        let ctxBack = 0;
+        while (hunkStart > 0 && ops[hunkStart - 1].type === 'ctx' && ctxBack < CONTEXT_LINES) {
+            hunkStart--;
+            ctxBack++;
+        }
+        // Extend forward: include changes separated by ≤ 2×CONTEXT_LINES context.
+        let hunkEnd = idx;
+        let scan = idx;
+        while (scan < ops.length) {
+            if (ops[scan].type !== 'ctx') {
+                hunkEnd = scan;
+                scan++;
+                continue;
+            }
+            let run = 0;
+            while (scan + run < ops.length && ops[scan + run].type === 'ctx')
+                run++;
+            if (scan + run < ops.length && run <= CONTEXT_LINES * 2) {
+                scan += run;
+                continue;
+            }
+            break;
+        }
+        const tail = Math.min(hunkEnd + CONTEXT_LINES, ops.length - 1);
+        const hunkOps = ops.slice(hunkStart, tail + 1);
+        const oldStart = oldLineNo - ctxBack;
+        const newStart = newLineNo - ctxBack;
+        const oldCount = hunkOps.filter(o => o.type !== 'add').length;
+        const newCount = hunkOps.filter(o => o.type !== 'del').length;
+        lines.push(`@@ -${oldStart}${oldCount === 1 ? '' : `,${oldCount}`} +${newStart}${newCount === 1 ? '' : `,${newCount}`} @@`);
+        for (const op of hunkOps) {
+            const marker = op.type === 'ctx' ? ' ' : op.type === 'del' ? '-' : '+';
+            lines.push(`${marker}${op.text}`);
+        }
+        // Advance the line counters across everything the hunk consumed.
+        for (let k = idx; k <= tail; k++) {
+            const t = ops[k].type;
+            if (t !== 'add')
+                oldLineNo++;
+            if (t !== 'del')
+                newLineNo++;
+        }
+        idx = tail + 1;
+    }
+    return lines.join('\n');
+}

package/package.json

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