create-pmos 0.55.4 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.55.4",
+  "version": "0.56.0",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@46269fd
+kernel-source: pmos@b024452
 assembled: 2026-10-06
 mode: vendor

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-06T09:30:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T10:33:25Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-06T09:30:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T10:33:25Z"}
 status: stable
 ---
 

package/payload/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-06T09:30:22Z"}
+generated: {by: process:create-pmos, at: "2026-10-06T10:33:25Z"}
 status: stable
 ---
 

package/workspace/guide/docs.md

@@ -0,0 +1,96 @@
+---
+type: Guide
+title: "Docs: is each document the same as its Google Docs and Confluence copy, and which version to use"
+timestamp: 2026-10-06
+---
+
+# Docs
+
+Open Docs from ⌘K (**Docs**) or press `g d`.
+
+Docs lists every document in the repository that has a copy in Google Docs or Confluence. For each copy, it shows whether the repository version (PMOS) or the copy is newer. You can then use one version over the other, one copy at a time.
+
+Nothing syncs by itself. A copy changes only when you press a button for that copy.
+
+## The list
+
+The copies are grouped by initiative. Copies of files that no initiative owns are under **Other**.
+
+**Needs you** shows the copies that are not the same. **All** shows every copy.
+
+Each copy is one line:
+
+- a status dot;
+- the document title, and a link that opens the copy in a new tab;
+- one sentence, for example "PMOS is newer · You, today 09:12";
+- at most one button.
+
+| Sentence | Means | Button |
+|---|---|---|
+| Same | The last compare found the same text, and neither side changed since. | none |
+| PMOS is newer | The repository file changed since the two sides last matched. The copy did not. | Use PMOS version |
+| Confluence is newer (or Google Docs) | The copy changed since the two sides last matched. The repository file did not. | Use Confluence version |
+| Edited on both sides | Both changed since the two sides last matched. | Choose… |
+| Not compared yet | No compare has read the copy. | none |
+| Can't open in Confluence | The compare could not read the copy. The reason is shown. | none |
+| Not found in Confluence | The copy is deleted or in the trash. | none |
+| Not in PMOS any more | The repository file is not there. | none |
+| Sync failed | The last sync of this copy wrote nothing. The reason is shown. | as before the sync |
+
+"by date" after a sentence means that the two sides have never matched. The newer modified date then decides.
+
+Frontmatter is not part of the text. A change to the frontmatter only does not change the sentence.
+
+## The details
+
+Click a line to see its details:
+
+- **PMOS**: the repository path and its last edit;
+- the copy: its address and its last edit;
+- a **Use … version** button for each side;
+- the first difference that the compare found, when it found one;
+- **Compare again** and **Stop tracking this copy**.
+
+**Stop tracking this copy** removes the link. The copy is not deleted. Press **Undo** in the message to link it again.
+
+## Use a version
+
+**Use PMOS version** writes the repository text to the copy. **Use Confluence version** (or Google Docs) writes the copy's text to the repository file.
+
+1. Press the button. The line says "Updating Confluence…" and a message shows **Undo**.
+2. To cancel, press **Undo** within five seconds. Nothing is changed.
+3. After five seconds, PMOS starts a session with the `doc-sync` skill. The session writes one side only, with your own Google Drive or Atlassian connector. If PMOS asks you to allow the write, allow it in the session.
+4. When the session finishes, the line says **Same**.
+
+A sync never creates, moves or deletes a page or a file. When the copy's text is written to the repository file, the file's frontmatter stays as it is. The session does not commit: use Sync in the bar to commit and push the change.
+
+## Compare
+
+PMOS cannot read Google Docs or Confluence itself. **↻** next to "Compared … ago" starts a session that reads every copy with your own connectors. The session reads only. The sentences change when it finishes.
+
+A compare runs only when you press it. There is no schedule. An edit to a repository file changes its sentence at once, without a compare.
+
+## Add a copy
+
+Type in **Find a document**. The search finds every markdown file in the repository by its title or path, also files that have no copy. A file with no copy shows **No copy** and **Add copy**.
+
+Press **Add copy**, paste the address of the Google Doc or Confluence page, and press Enter. A document can have one Google Doc and one Confluence page.
+
+A link that you add in an initiative's artifacts is the same link and shows here too.
+
+## From a terminal
+
+| Command | Does |
+|---|---|
+| `pmos docs list` | Each linked document and its signal per copy. `--attention` lists only what is not the same. |
+| `pmos docs find [words]` | The repository's markdown files that match, and their copies. |
+| `pmos docs link <file> <address>` | Links a repository file to a Google Doc or a Confluence page. |
+| `pmos docs unlink <file> google` | Removes the link (`google` or `confluence`). The copy is not touched. |
+| `pmos docs check-start` | Used by the compare session: opens a compare and lists what to read. |
+| `pmos docs record <check> --file <readings.json>` | Used by the compare session: records what it read. |
+| `pmos docs check-finish <check>` | Used by the compare session: closes the compare. |
+| `pmos docs sync-start <file> confluence --use pmos` | Used by the sync session: opens a sync of one copy (`--use copy` for the other direction). |
+| `pmos docs sync-finish <sync> --version <v>` | Used by the sync session: closes the sync. The two sides are now the same. |
+| `pmos docs sync-fail <sync> --reason "…"` | Used by the sync session: closes the sync. Nothing was written. |
+
+The session commands must name who read or wrote. In a workspace session that is the session. Outside the workspace, add `--by <profile>`.

package/workspace/guide/index.md

@@ -13,7 +13,7 @@ This guide describes the PMOS workspace as it works today. It ships with the app
 On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 
 1. **The top bar.** Repository ▾, the four places, search (⌘K), Sync when the repository is not in sync, and Settings.
-2. **The place.** One of Today, Initiatives, Board or Reports. It fills the screen under the bar.
+2. **The place.** One of Today, Initiatives, Board or Reports, or Docs (⌘K or `g d`). It fills the screen under the bar.
 3. **The detail.** The item you opened: an initiative with its status, next steps and artifacts, or the profiles. It opens beside the place and closes with ×.
 4. **The agent dock.** Terminals, documents, conversations and web pages. It is open on Today and a thin rail elsewhere.
 
@@ -26,6 +26,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 | The sessions of a repository, by initiative | The agent dock. ⌘K → **Branches and sessions** lists the branches. |
 | The items of an initiative | Board, or Breakdown in the initiative detail |
 | Run reports | Reports |
+| Whether a document is the same as its Google Docs or Confluence copy | Docs: ⌘K → **Docs**, or press `g d` |
 | Repositories, Profiles, New sessions (the default CLI and model), Validate consent, Theme | Settings |
 | Validate | Settings, under Validate consent: **Open Validate** |
 | A document, a decision record, a memory entry, a page of this guide | ⌘K, with its scope: Knowledge, Memory or Guide |
@@ -35,6 +36,7 @@ On a desktop the workspace is one frame. [Layout](layout.md) explains each part.
 ## Where to read next
 
 - [Start the workspace without a terminal](launcher.md): the PMOS app, the login item and `pmos launcher`.
+- [Docs](docs.md): whether each linked document is the same as, ahead of or behind its Google Docs and Confluence copy.
 - [Layout](layout.md): the frame, the keys and the rule for where a list or a detail opens.
 - [Statuses](statuses.md): what each status means, where it comes from, and what you can change.
 - [Initiatives and next steps](initiatives-and-next-steps.md): the detail, the next steps, and the artifacts.

package/workspace/guide/today.md

@@ -20,7 +20,21 @@ If the morning-brief session stops before it submits a brief, the Read step says
 
 Each agent job runs in its own session, so you can open any job and follow or steer it. The workspace types the job's prompt into the session when the agent is ready to read, and presses Enter for you. When you approve or revise a job and its session is still open, the workspace uses that same session again. Prepare again works the same way: when the morning-brief session is still open and has finished its read, or has printed nothing for two minutes, the workspace types the read into that session and runs it again.
 
-**Agent results**, at the top of the left column, counts the jobs and lists each finished one with its draft summary or the reason it failed. The other things that wait for you, such as outcome checks, report drafts and sessions, are in **Also waiting for you** at the end of the left column. When the day is folded, they show under it.
+**Agent results**, at the top of the left column, counts the jobs and lists each finished one with its draft summary or the reason it failed. Your goals for today come under it, above the calendar. The other things that wait for you, such as outcome checks, report drafts and sessions, are in **Also waiting for you** at the end of the left column. When the day is folded, they show under it.
+
+### One day for every repository
+
+The day is yours, not a repository's. Every repository shows the same calendar, goals, jobs and mentions. To narrow the day, use the **Show** switch at the top of Today:
+
+- **All repositories** shows the whole day. A job, mention, goal or watched place that belongs to a repository carries its name.
+- **Repository** shows the items of the repository you opened Today from, and the items that belong to no repository. The calendar always shows.
+
+To tie an item to a repository:
+
+1. For a goal, open it and pick a **Repository**. A goal you add while Today shows one repository belongs to that repository.
+2. For a Slack channel, Jira project or Confluence space, open **Sources**, open the service, and pick a repository next to the place.
+
+A job takes the repository of its goal. A job with no goal takes the repository of the place it came from. A job with neither belongs to no repository.
 
 Each job has one of three kinds.
 

package/workspace/lib/doc-sync-store.js

@@ -0,0 +1,322 @@
+'use strict';
+/* doc-sync-store.js — the file side of the docs sync signal (initiative docs-three-way-sync).
+ *
+ * lib/doc-sync.js decides; this module reads and appends. Both the `pmos docs` verb and the /api/docs routes call it,
+ * so the terminal and the Docs place can never hold two opinions about a link.
+ *
+ *   view(root)                                 → { ok, docs, summary, open, last, file }
+ *   addLink(root, { path, kind, target })      → the artifact-link row (four-panel's store — one link store, not two)
+ *   removeLink(root, { path, kind })           → a `retracted` row; nothing is deleted
+ *   checkStart(root, { by, now })              → { ok, run, links } — what the session must read, with each file's hash
+ *   record(root, { run, by, readings, now })   → { ok, recorded, refused }
+ *   checkFinish(root, { run, by, summary, now })
+ *   syncStart(root, { path, kind, use, by, now })     → { ok, run, … } — one open sync per copy (amended 2026-10-06)
+ *   syncFinish(root, { run, by, version, modified_at, url, title, now }) → the reading that makes the copy read Same
+ *   syncFail(root, { run, by, reason, now })
+ *   findFiles(root, q)                         → the repository's markdown files that match, for search and Add copy
+ *   repoInfo(root, rel) · bodyHash(text) · titleOf(text, rel)
+ *
+ * Local git only (log, status): no fetch, no network. Every write is an append through doc-sync.js#checkRow or
+ * four-panel.js's validators, so a refused row is never on disk.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const D = require('./doc-sync');
+const fourPanel = require('./four-panel');
+const consoleState = require('./console-state');
+
+const LEDGER = 'doc-checks.jsonl';
+// A check left open this long is taken to have ended without saying so (the session closed). A new one may start.
+const OPEN_RUN_MS = 2 * 60 * 60 * 1000;
+// A sync left open this long is taken to have ended (the session closed without finishing). The copy may be synced again.
+const OPEN_SYNC_MS = 30 * 60 * 1000;
+
+function stateDir(root) {
+  const e = consoleState.loadEngine();
+  if (!e.ok) return { ok: false, error: e.error };
+  const dir = fourPanel.storeDir(e.engine, root);
+  return dir ? { ok: true, dir } : { ok: false, error: 'this repository has no file-mode state directory' };
+}
+
+/** The body a copy is compared with: the file without its leading frontmatter, line endings and trailing spaces normalised. */
+function bodyOf(text) {
+  let t = String(text || '').replace(/\r\n?/g, '\n');
+  const m = /^---\n[\s\S]*?\n---[ \t]*(?:\n|$)/.exec(t);
+  if (m) t = t.slice(m[0].length);
+  return t.split('\n').map((l) => l.replace(/[ \t]+$/, '')).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+}
+function bodyHash(text) {
+  return crypto.createHash('sha256').update(bodyOf(text)).digest('hex').slice(0, 16);
+}
+function titleOf(text, rel) {
+  const t = String(text || '');
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(t);
+  if (fm) {
+    const m = /^title:\s*(.+?)\s*$/m.exec(fm[1]);
+    if (m) return m[1].replace(/^["']|["']$/g, '').slice(0, 200);
+  }
+  const h = /^#\s+(.+)$/m.exec(bodyOf(t));
+  if (h) return h[1].trim().slice(0, 200);
+  return path.basename(rel).replace(/\.[^.]+$/, '');
+}
+
+function git(root, args) {
+  try { return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', timeout: 10000, stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  catch { return null; }
+}
+
+/** The repository file now: whether it exists, its body hash, its title and when it last changed. */
+function repoInfo(root, rel) {
+  if (!D.okPath(rel)) return { exists: false };
+  const full = path.join(root, rel);
+  let text;
+  try { text = fs.readFileSync(full, 'utf8'); } catch { return { exists: false }; }
+  // The last commit time, unless the file has changes not yet committed: then its own file time is the truth.
+  // Who: the last commit's author, or "You" when that is this repository's git user or the change is not committed yet.
+  let modified_at = null;
+  let modified_by = null;
+  const dirty = git(root, ['status', '--porcelain', '--', rel]);
+  if (!dirty) {
+    const c = git(root, ['log', '-1', '--format=%cI%x09%an', '--', rel]);
+    if (c) {
+      const [when, who] = c.split('\t');
+      modified_at = new Date(when).toISOString();
+      const me = git(root, ['config', 'user.name']);
+      modified_by = who && me && who === me ? 'You' : (who || null);
+    }
+  }
+  if (!modified_at) {
+    try { modified_at = fs.statSync(full).mtime.toISOString(); modified_by = 'You'; } catch { /* none */ }
+  }
+  return { exists: true, hash: bodyHash(text), title: titleOf(text, rel), modified_at, modified_by };
+}
+
+function readRows(root) {
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error, rows: [] };
+  const r = fourPanel.readDeclarations(s.dir, LEDGER);
+  return { ...r, dir: s.dir };
+}
+function append(root, row) {
+  const c = D.checkRow(row);
+  if (!c.ok) return { ok: false, error: c.error };
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error };
+  return fourPanel.appendDeclaration(s.dir, LEDGER, c.row);
+}
+
+/** The links the signal is about: the PM's artifact links to Google Docs and Confluence, latest row per pair. */
+function links(root) {
+  const s = stateDir(root);
+  if (!s.ok) return { ok: false, error: s.error, links: [] };
+  const r = fourPanel.readDeclarations(s.dir, fourPanel.ARTIFACT_LINKS);
+  if (!r.ok) return { ok: false, error: r.error, links: [] };
+  return { ok: true, links: fourPanel.linkView(r.rows).filter((l) => D.KINDS.includes(l.kind) && D.okPath(l.artifact_path)) };
+}
+
+function view(root, { now = Date.now() } = {}) {
+  const L = links(root);
+  if (!L.ok) return { ok: false, error: L.error };
+  const rows = readRows(root);
+  if (!rows.ok) return { ok: false, error: rows.error };
+  const readings = D.readingsByLink(rows.rows);
+  const { open, last, syncs } = D.runsOf(rows.rows);
+  const byPath = new Map();
+  for (const l of L.links) {
+    let doc = byPath.get(l.artifact_path);
+    if (!doc) {
+      const repo = repoInfo(root, l.artifact_path);
+      doc = { path: l.artifact_path, title: repo.title || path.basename(l.artifact_path), initiative_id: l.initiative_id || null,
+        repo: { exists: !!repo.exists, modified_at: repo.modified_at || null, modified_by: repo.modified_by || null }, links: [], _repo: repo };
+      byPath.set(l.artifact_path, doc);
+    }
+    const mine = readings.get(D.keyOf(l.artifact_path, l.kind)) || [];
+    const sig = D.signal({ kind: l.kind, target: l.target }, mine, doc._repo);
+    const st = syncState(syncs, l.artifact_path, l.kind, mine, now);
+    doc.links.push({ ...sig, target: l.target, linked_at: l.at, ...st });
+  }
+  const docs = [...byPath.values()].map(({ _repo, ...d }) => ({
+    ...d, attention: d.links.some((x) => D.ATTENTION.includes(x.signal)),
+  }));
+  const all = docs.flatMap((d) => d.links);
+  const count = (s) => all.filter((x) => x.signal === s).length;
+  const summary = {
+    documents: docs.length, links: all.length,
+    same: count('same'), ahead: count('ahead'), behind: count('behind'), diverged: count('diverged'),
+    unchecked: count('unchecked'), problems: count('unreadable') + count('missing-remote') + count('missing-repo'),
+    attention: docs.filter((d) => d.attention).length,
+  };
+  return { ok: true, docs, summary, open: openRun(open), last, file: rows.file || null };
+}
+const openRun = (open, now = Date.now()) => (open && now - Date.parse(open.started_at) < OPEN_RUN_MS ? open : null);
+
+/** A copy's sync, as the line shows it: one still open (`syncing`), or the last one that failed after the last reading. */
+function syncState(syncs, rel, kind, readings, now = Date.now()) {
+  const mine = (syncs || []).filter((x) => x.path === rel && x.kind === kind);
+  const open = mine.filter((x) => x.state === 'started' && now - Date.parse(x.started_at) < OPEN_SYNC_MS).pop() || null;
+  const lastAt = readings.length ? readings[readings.length - 1].at : '';
+  const failed = mine.filter((x) => x.state === 'failed' && x.ended_at > lastAt).pop() || null;
+  return {
+    syncing: open ? { run: open.run, use: open.use, started_at: open.started_at } : null,
+    sync_failed: !open && failed ? { use: failed.use, reason: failed.reason, at: failed.ended_at } : null,
+  };
+}
+
+function addLink(root, { path: rel, kind, target, initiative_id } = {}) {
+  if (!D.KINDS.includes(kind)) return { ok: false, error: `choose ${D.KINDS.map((k) => D.KIND_LABEL[k]).join(' or ')}` };
+  if (!D.okPath(rel)) return { ok: false, error: 'give the file as a path inside the repository' };
+  if (!fs.existsSync(path.join(root, rel))) return { ok: false, error: `${rel} is not in the repository` };
+  if (!D.remoteIdOf(kind, target)) return { ok: false, error: `that is not a ${D.KIND_LABEL[kind]} link — paste the page's address` };
+  const built = fourPanel.artifactLinkRow({ artifact_path: rel, kind, target, origin: 'typed', initiative_id: initiative_id || null });
+  if (!built.ok) return built;
+  const s = stateDir(root);
+  if (!s.ok) return s;
+  return fourPanel.appendDeclaration(s.dir, fourPanel.ARTIFACT_LINKS, built.row);
+}
+
+function removeLink(root, { path: rel, kind } = {}) {
+  const L = links(root);
+  if (!L.ok) return L;
+  const cur = L.links.find((l) => l.artifact_path === rel && l.kind === kind);
+  if (!cur) return { ok: false, error: `${rel} has no ${D.KIND_LABEL[kind] || kind} link` };
+  const built = fourPanel.artifactLinkRow({ artifact_path: rel, kind, target: cur.target, origin: 'typed', state: 'retracted',
+    initiative_id: cur.initiative_id || null });
+  if (!built.ok) return built;
+  const s = stateDir(root);
+  if (!s.ok) return s;
+  return fourPanel.appendDeclaration(s.dir, fourPanel.ARTIFACT_LINKS, built.row);
+}
+
+function newRunId() { return 'r-' + crypto.randomBytes(6).toString('hex'); }
+
+/** Open a check. Refused while another is open (and not stale). Returns every link with what the session needs. */
+function checkStart(root, { by, now = new Date() } = {}) {
+  if (!by) return { ok: false, error: 'a check must name the session or profile that runs it' };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const open = openRun(D.runsOf(rows.rows).open, now.getTime());
+  if (open) return { ok: false, error: `a check is already running (${open.run}, started ${open.started_at})`, open };
+  const L = links(root);
+  if (!L.ok) return L;
+  const run = newRunId();
+  const wrote = append(root, { ev: 'run', run, state: 'started', by, at: now.toISOString() });
+  if (!wrote.ok) return wrote;
+  const list = L.links.map((l) => {
+    const repo = repoInfo(root, l.artifact_path);
+    return { path: l.artifact_path, kind: l.kind, target: l.target, remote_id: D.remoteIdOf(l.kind, l.target),
+      repo_exists: !!repo.exists, repo_hash: repo.hash || null, title: repo.title || null };
+  });
+  return { ok: true, run, links: list };
+}
+
+/** Record what the session read. Each reading is checked on its own; a refused one is reported and not written. */
+function record(root, { run, by, readings, now = new Date() } = {}) {
+  if (!Array.isArray(readings)) return { ok: false, error: 'readings is a list' };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const known = D.runsOf(rows.rows).runs.find((r) => r.run === run);
+  if (!known) return { ok: false, error: `${run || 'that'} is not a check that was started — run pmos docs check-start first` };
+  if (known.finished_at) return { ok: false, error: `${run} is finished — start a new check` };
+  const recorded = []; const refused = [];
+  for (const r of readings) {
+    const wrote = append(root, { ...r, ev: 'reading', run, by, at: now.toISOString() });
+    if (wrote.ok) recorded.push(`${r.path}|${r.kind}`); else refused.push({ path: r && r.path, kind: r && r.kind, error: wrote.error });
+  }
+  return { ok: refused.length === 0, recorded, refused, error: refused.length ? `${refused.length} reading(s) refused` : undefined };
+}
+
+function checkFinish(root, { run, by, summary, now = new Date() } = {}) {
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const known = D.runsOf(rows.rows).runs.find((r) => r.run === run);
+  if (!known) return { ok: false, error: `${run || 'that'} is not a check that was started` };
+  if (known.finished_at) return { ok: true, already: true };
+  return append(root, { ev: 'run', run, state: 'finished', by, summary: summary || null, at: now.toISOString() });
+}
+
+/** Open a sync of one copy, in the direction the PM pressed. Refused while another sync of that copy is open. */
+function syncStart(root, { path: rel, kind, use, by, now = new Date() } = {}) {
+  if (!by) return { ok: false, error: 'a sync must name the session or profile that runs it' };
+  if (!D.USES.includes(use)) return { ok: false, error: 'say which version to use: pmos or copy' };
+  const L = links(root);
+  if (!L.ok) return L;
+  const l = L.links.find((x) => x.artifact_path === rel && x.kind === kind);
+  if (!l) return { ok: false, error: `${rel} has no ${D.KIND_LABEL[kind] || kind} copy` };
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const st = syncState(D.runsOf(rows.rows).syncs, rel, kind, [], now.getTime());
+  if (st.syncing) return { ok: false, error: `that copy is already being synced (${st.syncing.run}, started ${st.syncing.started_at})`, open: st.syncing };
+  const repo = repoInfo(root, rel);
+  if (!repo.exists) return { ok: false, error: `${rel} is not in the repository` };
+  const run = newRunId();
+  const wrote = append(root, { ev: 'run', mode: 'sync', run, state: 'started', by, path: rel, kind, use, at: now.toISOString() });
+  if (!wrote.ok) return wrote;
+  return { ok: true, run, path: rel, kind, label: D.KIND_LABEL[kind], use, target: l.target, remote_id: D.remoteIdOf(kind, l.target),
+    repo_hash: repo.hash, title: repo.title };
+}
+
+function openSync(root, run) {
+  const rows = readRows(root);
+  if (!rows.ok) return rows;
+  const s = D.runsOf(rows.rows).syncs.find((x) => x.run === run);
+  if (!s) return { ok: false, error: `${run || 'that'} is not a sync that was started — run pmos docs sync-start first` };
+  if (s.state !== 'started') return { ok: false, error: `${run} is already ${s.state}` };
+  return { ok: true, sync: s };
+}
+
+/**
+ * Close a sync that wrote one side. The session names the copy's version after the write; the repository hash is read
+ * here, now, so the reading says what is on disk and not what the session thinks it wrote.
+ */
+function syncFinish(root, { run, by, version, modified_at, modified_by, url, title, now = new Date() } = {}) {
+  const o = openSync(root, run);
+  if (!o.ok) return o;
+  const s = o.sync;
+  const repo = repoInfo(root, s.path);
+  if (!repo.exists) return { ok: false, error: `${s.path} is not in the repository — record the sync as failed` };
+  const label = D.KIND_LABEL[s.kind];
+  const reading = { ev: 'reading', run, by, at: now.toISOString(), path: s.path, kind: s.kind,
+    remote_id: null, exists: true, version: version == null ? null : String(version), same: true, repo_hash: repo.hash,
+    modified_at: modified_at || null, modified_by: modified_by || null, url: url || null, title: title || null,
+    note: s.use === 'pmos' ? `PMOS version written to ${label}` : `${label} version written to PMOS` };
+  const L = links(root);
+  const l = L.ok ? L.links.find((x) => x.artifact_path === s.path && x.kind === s.kind) : null;
+  if (l) reading.remote_id = D.remoteIdOf(s.kind, l.target);
+  const r = append(root, reading);
+  if (!r.ok) return r;
+  return append(root, { ev: 'run', mode: 'sync', run, state: 'finished', by, path: s.path, kind: s.kind, use: s.use, at: now.toISOString() });
+}
+
+function syncFail(root, { run, by, reason, now = new Date() } = {}) {
+  const o = openSync(root, run);
+  if (!o.ok) return o;
+  const s = o.sync;
+  return append(root, { ev: 'run', mode: 'sync', run, state: 'failed', by, path: s.path, kind: s.kind, use: s.use,
+    summary: reason || null, at: now.toISOString() });
+}
+
+/** The repository's markdown files whose path or title matches `q`: what search and Add copy offer. */
+function findFiles(root, q, { limit = 20 } = {}) {
+  const words = String(q || '').toLowerCase().split(/\s+/).filter(Boolean);
+  const out = git(root, ['ls-files', '-co', '--exclude-standard', '--', '*.md']);
+  const files = (out ? out.split('\n') : []).filter((f) => f && D.okPath(f) && !/(^|\/)node_modules\//.test(f));
+  const found = [];
+  for (const f of files) {
+    if (found.length >= limit) break;
+    const low = f.toLowerCase();
+    let title = null;
+    const hit = (t) => words.every((w) => t.includes(w));
+    if (!words.length || hit(low)) { found.push(f); continue; }
+    try { title = titleOf(fs.readFileSync(path.join(root, f), 'utf8').slice(0, 4000), f); } catch { continue; }
+    if (hit(title.toLowerCase())) found.push(f);
+  }
+  return found.map((f) => {
+    let title = path.basename(f);
+    try { title = titleOf(fs.readFileSync(path.join(root, f), 'utf8').slice(0, 4000), f); } catch { /* keep the name */ }
+    return { path: f, title };
+  });
+}
+
+module.exports = { LEDGER, OPEN_RUN_MS, OPEN_SYNC_MS, syncStart, syncFinish, syncFail, findFiles, view, addLink, removeLink, checkStart, record, checkFinish, repoInfo, bodyHash, bodyOf, titleOf, links };