@unpolarize/knowledge-planning 0.1.0

package/README.md

@@ -0,0 +1,92 @@
+# @unpolarize/knowledge-planning
+
+A durable, git-backed, **life-wide** planning system — software, career, finances, family,
+research — over a markdown SSOT. Combines Nimbalyst (plans/tracker/session-kanban) and Vibe
+Kanban (card → agent execution) patterns, wired to the `~/docs` knowledge base (`blocked_by`
+edges) and the portable `~/.sessions` corpus (`planning_refs`).
+
+Implements the design in `~/docs/knowledge/tech/agents/knowledge-planning-design.md`.
+
+## Why
+
+Planning was scattered across a Google Doc, `notes.md`, and `tasks.md`, with no durable,
+queryable, session-linked home for ideas/plans/daily work. This makes the *work that agent
+sessions advance* first-class, in git, addressable by stable id.
+
+## Data / code split
+
+This repo is **tool source only**. The planning **data** (the SSOT) lives in the knowledge base
+at **`~/docs/planning`**, and execution **sessions** live in **`~/.sessions`** (separate git repos).
+The CLI defaults its store root to `~/docs/planning` (override with `--root` / `$KP_ROOT`).
+
+```
+~/projects/unpolarize/knowledge-planning   ← THIS repo (code)
+  src/
+    schema/            # Zod entities + frontmatter parse/serialize
+    store/             # markdown read/write, edges
+    index/             # node:sqlite projection (objects, edges, fts, blocked-by, daily board)
+    graph/             # GraphData for the CSV webview
+    kb-bridge/         # resolve KnowledgeRef → ~/docs; decision detection
+    migrate/           # Google Doc / notes.md bullets → seed objects
+    cli/               # the `kp` command
+  scripts/seed.ts      # reproducible dogfood seed (writes to ~/docs/planning)
+
+~/docs/planning                            ← the DATA store (SSOT, in the KB)
+  config.json          # domains, kb_root (~/docs), sessions_root (~/.sessions)
+  domains/ catalog/ projects/ ideas/ plans/ tasks/ daily/ reflections/ insights/
+  edges.jsonl          # explicit edges (append-only; rebuildable from frontmatter)
+  .index/planning.db   # node:sqlite projection (gitignored, rebuilt by `kp reindex`)
+```
+
+## Entities
+
+`Domain` · `Project` (wraps projects-catalog + KB folder) · `CatalogEntry` (non-repo pursuit) ·
+`Idea` (capture→refine→accepted→…) · `Plan` (speckit dev / goal+steps life) · `Task` (kanban
+lanes) · `DailyPlan` · `Reflection` (human) · `Insight` (AI). Edges via frontmatter
+(`blocked_by`, `depends_on`, `cites`, `related`, `promoted_to`, `linked_sessions`) unioned with
+`edges.jsonl`.
+
+**Knowledge blocks work:** a `blocked_by` edge points at a `~/docs` article and is only
+*resolvable* once that article records a decision (`decision:` frontmatter or a `## Decision`
+section) — so the blocker tracks a real artifact instead of rotting.
+
+## CLI
+
+No build step — Node ≥22 runs the TypeScript directly; `node:sqlite` needs no native module.
+
+```bash
+node src/cli/index.ts <command>     # or: npm run kp -- <command>
+
+reindex                         # rebuild .index/planning.db
+list [--type T] [--status S]    # list objects
+daily [--date today] [--carry-over]
+blocked                         # objects blocked_by unresolved knowledge
+graph [--json]                  # nodes/edges
+capture "<text>" [--domain D]   # quick-capture an idea
+promote <ideaId> [--to planId]  # idea → plan (+lineage)
+link-session <objectId> <uuid>  # bidirectional: linked_sessions ↔ session planning_refs
+insight <file> --source S       # ingest digest bullets → Insight
+set-status <id> <status>        # board lane / accept
+export [--date today]           # one-shot JSON snapshot (consumed by the CSV planning mode)
+doctor                          # config, counts, fts, blocked, warnings
+```
+
+`KP_ROOT` (or `--root`) overrides the store root (defaults to this package root).
+
+## Integrations
+
+- **`~/docs` agent skills:** `/planning-daily`, `/planning-capture`, `/planning-refine`,
+  `/planning-promote`, `/planning-link-session`, `/planning-blocked-by`, `/planning-insight`,
+  `/planning-reflect` (in `~/docs/.claude/commands/`).
+- **Sessions:** `code-sessions` `SessionSchema` carries `planning_refs[]` + `phase`; `kp
+  link-session` writes both sides.
+- **Code Sessions VS Code:** a **Planning** activity-bar container (Today / Inbox / Projects
+  trees, kanban board + graph webviews, status bar) reads this store via `kp export`.
+- **Daily workflow:** the Google Doc stays the mobile capture surface; planning *ingests* from
+  `raw/google-docs/personal-todo-notes.md` + `notes.md` rather than replacing it.
+
+## Tests
+
+```bash
+npm test        # vitest — schema, store, kb-bridge, migrate, index, graph, cli (29 tests)
+```

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@unpolarize/knowledge-planning",
+  "version": "0.1.0",
+  "description": "Durable, git-backed, life-wide planning system: typed entities (Domain/Project/CatalogEntry/Idea/Plan/Task/DailyPlan/Reflection/Insight/KnowledgeRef/Edge) over a markdown SSOT, a node:sqlite projection, a graph/board exporter, and a CLI. Wires ~/docs knowledge (blocked_by edges) and the portable sessions.git corpus (planning_refs).",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unpolarize/knowledge-planning.git"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "knowledge-planning": "./src/cli/index.ts",
+    "kp": "./src/cli/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "kp": "node ./src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/src/cli/commands.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { Store } from '../store/store.ts';
+import { PlanningIndex } from '../index/db.ts';
+import * as cmd from './commands.ts';
+
+let dir: string;
+let kb: string;
+let sessions: string;
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'kp-cmd-'));
+  kb = mkdtempSync(join(tmpdir(), 'kp-cmdkb-'));
+  sessions = mkdtempSync(join(tmpdir(), 'kp-cmdsess-'));
+});
+afterEach(() => {
+  for (const d of [dir, kb, sessions]) rmSync(d, { recursive: true, force: true });
+});
+
+describe('cli commands', () => {
+  it('captures an idea', () => {
+    const s = new Store(dir);
+    const res = cmd.cmdCapture(s, 'Memory maps in CB', 'tech');
+    expect(res.id).toBe('ideas/memory-maps-in-cb');
+    expect(new Store(dir).get(res.id)?.object.status).toBe('capture');
+  });
+
+  it('promotes an idea to a plan and marks lineage', () => {
+    const s = new Store(dir);
+    cmd.cmdCapture(s, 'Knowledge planning MVP', 'tech');
+    const res = cmd.cmdPromote(s, 'ideas/knowledge-planning-mvp');
+    const fresh = new Store(dir);
+    expect(fresh.get(res.planId)?.type).toBe('plan');
+    expect(fresh.get('ideas/knowledge-planning-mvp')?.data.status).toBe('done');
+    expect(fresh.get('ideas/knowledge-planning-mvp')?.data.promoted_to).toBe(res.planId);
+  });
+
+  it('links a session both ways (linked_sessions + planning_refs)', () => {
+    const s = new Store(dir);
+    s.write({ id: 'ideas/mm', type: 'idea', title: 'MM' });
+    const uuid = '4992a4a4-5632-4048-a55e-ab2be5857f2e';
+    const envDir = join(sessions, 'hosts/h1/2026-06', uuid);
+    mkdirSync(envDir, { recursive: true });
+    writeFileSync(
+      join(envDir, 'session.json'),
+      JSON.stringify({ schema: 'session-store/session@1', session_id: uuid, host: 'h1', agent: 'claude-code' }),
+    );
+
+    const res = cmd.cmdLinkSession(s, sessions, 'ideas/mm', uuid);
+    expect(res.envelopeUpdated).toBe(true);
+
+    const env = JSON.parse(readFileSync(join(envDir, 'session.json'), 'utf8'));
+    expect(env.planning_refs).toContain('ideas/mm');
+    expect(new Store(dir).get('ideas/mm')?.object.linked_sessions).toContain(uuid);
+  });
+
+  it('baselines on first run, then ingests only new substantial bullets', () => {
+    const s = new Store(dir);
+    const base = '- brainstorm a thing\n- [ ] call the contractor\n';
+    // first run: no prior snapshot → baseline, ingest nothing (never flood a brain-dump)
+    const b = cmd.cmdIngestGdoc(s, base, { prevText: null });
+    expect(b.baselined).toBe(true);
+    expect(b.created.length).toBe(0);
+    // next run: one new substantial bullet added → only it ingests ('tiny' filtered by minLen)
+    const r = cmd.cmdIngestGdoc(s, base + '- a brand new idea here\n- tiny\n', { prevText: base, domain: 'tech' });
+    expect(r.baselined).toBe(false);
+    expect(r.created).toEqual(['ideas/a-brand-new-idea-here']);
+    expect(new Store(dir).get('ideas/a-brand-new-idea-here')?.object.status).toBe('capture');
+  });
+
+  it('caps new captures per run', () => {
+    const s = new Store(dir);
+    const lines = Array.from({ length: 10 }, (_, i) => `- new substantial bullet number ${i}`).join('\n');
+    const r = cmd.cmdIngestGdoc(s, lines, { prevText: '', max: 3 });
+    expect(r.created.length).toBe(3);
+    expect(r.capped).toBe(7);
+  });
+
+  it('ingests insight bullets into an Insight object', () => {
+    const s = new Store(dir);
+    const res = cmd.cmdInsightIngest(s, '- ship the daemon\n- [ ] email outreach\n', 'daily-digest', 'raw/x.md');
+    expect(res.suggested).toBe(2);
+    expect(new Store(dir).get(res.id)?.type).toBe('insight');
+  });
+
+  it('renders list / daily / blocked / graph as strings', () => {
+    const s = new Store(dir);
+    s.write({ id: 'ideas/a', type: 'idea', title: 'A', status: 'capture' });
+    s.write({ id: 'daily/2026-06-21', type: 'daily_plan', date: '2026-06-21' }, '## Top 3\n- [ ] ship');
+    s.write({ id: 'tasks/t', type: 'task', title: 'Ship', status: 'today', daily: 'daily/2026-06-21' });
+    s.write({
+      id: 'plans/r',
+      type: 'plan',
+      title: 'R',
+      blocked_by: [{ path: 'knowledge/x.md', reason: 'decide' }],
+    });
+    const idx = new PlanningIndex(s);
+    expect(cmd.cmdList(s, { status: 'capture' })).toContain('ideas/a');
+    expect(cmd.cmdDaily(s, idx, '2026-06-21', false)).toContain('Ship');
+    expect(cmd.cmdBlocked(idx, kb)).toContain('plans/r');
+    expect(cmd.cmdGraph(s, kb, true)).toContain('"nodes"');
+  });
+});

package/src/cli/commands.ts

@@ -0,0 +1,341 @@
+import { join } from 'node:path';
+import { Store } from '../store/store.ts';
+import { PlanningIndex, persistIndex } from '../index/db.ts';
+import { buildGraph } from '../graph/graph.ts';
+import { extractBullets, toSeeds, slugify } from '../migrate/gdoc.ts';
+import { findSessionEnvelope, addPlanningRef } from './sessions.ts';
+import { inspectKnowledgeRef, resolveKnowledgeRef, readTitle } from '../kb-bridge/kb-bridge.ts';
+import { existsSync } from 'node:fs';
+import type { Config } from '../types.ts';
+
+export const today = (): string => new Date().toISOString().slice(0, 10);
+
+export interface ListOpts {
+  status?: string;
+  type?: string;
+}
+
+export function cmdList(store: Store, opts: ListOpts): string {
+  let rows = store.all();
+  if (opts.type) rows = rows.filter((d) => d.type === opts.type);
+  if (opts.status) rows = rows.filter((d) => (d.object as { status?: string }).status === opts.status);
+  if (rows.length === 0) return '(no matching objects)';
+  return rows
+    .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id))
+    .map((d) => {
+      const o = d.object as { title?: string; status?: string };
+      return `${pad(d.type, 12)} ${pad(o.status ?? '-', 10)} ${d.id}${o.title ? `  — ${o.title}` : ''}`;
+    })
+    .join('\n');
+}
+
+export function cmdDaily(store: Store, idx: PlanningIndex, date: string, carryOver: boolean): string {
+  const board = idx.dailyBoard(date);
+  const lines: string[] = [`# Daily — ${date}`];
+  if (!board.daily_id) lines.push(`(no daily plan file at daily/${date}; run /planning-daily or 'kp capture')`);
+  if (board.body.trim()) lines.push('', board.body.trim());
+  lines.push('', '## Tasks by lane');
+  for (const [lane, rows] of Object.entries(board.lanes)) {
+    if (rows.length === 0) continue;
+    lines.push(`  ${lane}:`);
+    for (const r of rows) lines.push(`    - [${r.status === 'done' ? 'x' : ' '}] ${r.title ?? r.id}  (${r.id})`);
+  }
+  if (carryOver) {
+    const prev = previousDay(date);
+    const prevBoard = idx.dailyBoard(prev);
+    const unfinished = [...prevBoard.lanes.today, ...prevBoard.lanes.in_progress, ...prevBoard.lanes.inbox];
+    if (unfinished.length) {
+      lines.push('', `## Carry-over from ${prev}`);
+      for (const r of unfinished) lines.push(`    - ${r.title ?? r.id}  (${r.id})`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export function cmdBlocked(idx: PlanningIndex, kbRoot: string): string {
+  const blocked = idx.blockedByKnowledge(kbRoot).filter((b) => b.status !== 'resolved');
+  if (blocked.length === 0) return '(nothing blocked by knowledge)';
+  return blocked
+    .map((b) => {
+      const flag = !b.exists ? 'MISSING' : b.resolvable ? 'RESOLVABLE (decision recorded)' : 'open';
+      return `${flag.padEnd(30)} ${b.id}\n    → ${b.path}${b.reason ? `\n    reason: ${b.reason}` : ''}`;
+    })
+    .join('\n');
+}
+
+export function cmdGraph(store: Store, kbRoot: string, json: boolean): string {
+  const g = buildGraph(store, kbRoot);
+  if (json) return JSON.stringify(g, null, 2);
+  return `graph: ${g.nodes.length} nodes, ${g.edges.length} edges\n  by type: ${countBy(g.nodes.map((n) => n.type))}`;
+}
+
+export function cmdReindex(store: Store, root: string): string {
+  const res = persistIndex(store, join(root, '.index/planning.db'));
+  const warnings = store.getWarnings();
+  return `reindexed → ${join(root, '.index/planning.db')}\n  ${res.objects} objects, ${res.edges} edges${
+    warnings.length ? `\n  ${warnings.length} warning(s):\n    ${warnings.join('\n    ')}` : ''
+  }`;
+}
+
+export interface CaptureResult {
+  id: string;
+}
+
+export function cmdCapture(store: Store, text: string, domain?: string): CaptureResult {
+  const id = uniqueId(store, `ideas/${slugify(text)}`);
+  store.write({ id, type: 'idea', title: text, status: 'capture', domain, created: today() });
+  return { id };
+}
+
+export interface PromoteResult {
+  ideaId: string;
+  planId: string;
+}
+
+export function cmdPromote(store: Store, ideaId: string, toId?: string): PromoteResult {
+  const idea = store.get(ideaId);
+  if (!idea || idea.type !== 'idea') throw new Error(`not an idea: ${ideaId}`);
+  const o = idea.object as {
+    title?: string;
+    domain?: string;
+    project?: string;
+    blocked_by?: unknown[];
+    cites?: string[];
+  };
+  const planId = toId ?? uniqueId(store, `plans/${ideaId.split('/').pop()}`);
+  const isLife = o.domain && o.domain !== 'tech';
+  store.write(
+    {
+      id: planId,
+      type: 'plan',
+      title: o.title ?? planId,
+      status: 'plan',
+      kind: isLife ? 'life' : 'dev',
+      domain: o.domain,
+      project: o.project,
+      promoted_from: ideaId,
+      blocked_by: o.blocked_by ?? [],
+      cites: o.cites ?? [],
+      created: today(),
+    },
+    `# ${o.title ?? planId}\n\n## Goal\n\n_(promoted from [[${ideaId}]])_\n\n## Steps\n\n- [ ] …\n`,
+  );
+  store.patch(ideaId, (d) => {
+    d.status = 'done';
+    d.promoted_to = planId;
+  });
+  store.appendEdge({ kind: 'promoted_to', from: ideaId, to: planId, created_at: new Date().toISOString() });
+  return { ideaId, planId };
+}
+
+export interface LinkResult {
+  objectId: string;
+  uuid: string;
+  envelopeUpdated: boolean;
+  envelopePath?: string;
+}
+
+export function cmdLinkSession(store: Store, sessionsRoot: string, objectId: string, uuid: string): LinkResult {
+  const obj = store.get(objectId);
+  if (!obj) throw new Error(`object not found: ${objectId}`);
+  store.patch(objectId, (d) => {
+    const refs = new Set((d.linked_sessions as string[]) ?? []);
+    refs.add(uuid);
+    d.linked_sessions = [...refs];
+  });
+  store.appendEdge({ kind: 'evidence', from: `session:${uuid}`, to: objectId, created_at: new Date().toISOString() });
+  const envelopePath = findSessionEnvelope(sessionsRoot, uuid);
+  let envelopeUpdated = false;
+  if (envelopePath) envelopeUpdated = addPlanningRef(envelopePath, objectId);
+  return { objectId, uuid, envelopeUpdated, envelopePath };
+}
+
+export interface InsightResult {
+  id: string;
+  suggested: number;
+}
+
+/** Ingest digest/brief bullets (a markdown file) into an Insight with suggested tasks. */
+export function cmdInsightIngest(store: Store, text: string, source: string, sourceRef?: string): InsightResult {
+  const bullets = extractBullets(text).filter((b) => b.text.length > 3);
+  const date = today();
+  const id = uniqueId(store, `insights/${date}-${slugify(source)}`);
+  const suggested = bullets.map((b) => b.text);
+  store.write(
+    {
+      id,
+      type: 'insight',
+      title: `${source} — ${date}`,
+      source,
+      source_ref: sourceRef,
+      generated_at: new Date().toISOString(),
+      status: 'new',
+    },
+    `# ${source} — ${date}\n\n## Suggested\n\n${suggested.map((s) => `- [ ] ${s}`).join('\n')}\n`,
+  );
+  return { id, suggested: suggested.length };
+}
+
+/** Rich detail for one object: body + resolved references + parent/children + lineage. */
+export function cmdShow(store: Store, kbRoot: string, id: string): unknown {
+  const doc = store.get(id);
+  if (!doc) throw new Error(`object not found: ${id}`);
+  const o = doc.object as Record<string, unknown>;
+  const all = store.all();
+  const ref = (oid: string) => {
+    const d = store.get(oid);
+    return d ? { id: d.id, type: d.type, title: (d.object as { title?: string }).title ?? d.id, status: (d.object as { status?: string }).status } : { id: oid, missing: true };
+  };
+  const cites = (o.cites as string[] | undefined ?? []).map((p) => {
+    const abs = resolveKnowledgeRef(p, kbRoot);
+    return { path: p, exists: existsSync(abs), title: existsSync(abs) ? readTitle(abs) : undefined };
+  });
+  const blocked_by = (doc.object.blocked_by ?? []).map((r) => inspectKnowledgeRef(id, r, kbRoot));
+  // children: objects that point at this one as their project or plan parent
+  const children = all
+    .filter((d) => {
+      const c = d.object as Record<string, unknown>;
+      return d.id !== id && (c.project === id || c.plan === id || c.daily === id);
+    })
+    .map((d) => ref(d.id));
+  const parentId = (o.plan as string) || (o.project as string) || undefined;
+  return {
+    id: doc.id,
+    type: doc.type,
+    relpath: doc.relpath,
+    path: doc.path,
+    frontmatter: o,
+    title: o.title ?? doc.id,
+    status: o.status,
+    domain: o.domain,
+    body: doc.body,
+    cites,
+    blocked_by,
+    depends_on: (o.depends_on as string[] | undefined ?? []).map(ref),
+    related: (o.related as string[] | undefined ?? []).map(ref),
+    linked_sessions: (o.linked_sessions as string[] | undefined ?? []),
+    parent: parentId ? ref(parentId) : null,
+    children,
+    promoted_to: o.promoted_to ? ref(o.promoted_to as string) : null,
+    promoted_from: o.promoted_from ? ref(o.promoted_from as string) : null,
+  };
+}
+
+/** One-shot JSON snapshot for external consumers (the CSV planning mode). */
+export function cmdExport(store: Store, idx: PlanningIndex, config: Config, date: string): unknown {
+  return {
+    generated_at: new Date().toISOString(),
+    root: store.root,
+    kb_root: config.kb_root,
+    sessions_root: config.sessions_root,
+    counts: idx.counts(),
+    objects: idx.all(),
+    inbox: idx.listByStatus('capture'),
+    board: idx.dailyBoard(date),
+    blocked: idx.blockedByKnowledge(config.kb_root).filter((b) => b.status !== 'resolved'),
+    graph: buildGraph(store, config.kb_root),
+  };
+}
+
+/** Set an object's status (board lane moves, idea accept/park). */
+export function cmdSetStatus(store: Store, id: string, status: string): void {
+  if (!store.get(id)) throw new Error(`object not found: ${id}`);
+  store.patch(id, (d) => {
+    d.status = status;
+    d.updated = today();
+  });
+}
+
+export interface IngestResult {
+  created: string[];
+  skipped: number;
+  newBullets: number;
+  baselined: boolean;
+  capped: number;
+}
+
+/**
+ * Ingest the synced Google-Doc todo mirror into the planning inbox: checkbox items →
+ * inbox tasks, plain bullets → capture ideas.
+ *
+ * Safe by construction for a large brain-dump outline (the real doc is thousands of
+ * nested bullets), per the design's "diff triggers append of NEW bullets, human approves":
+ *  - **Diff-based:** ingests only bullets absent from `prevText` (the prior snapshot).
+ *  - **Baseline first run:** when `prevText` is null (no snapshot yet), ingest nothing —
+ *    just establish the baseline so a years-long doc never floods the store.
+ *  - **Filtered:** only substantial (`minLen`) top-level bullets (`depth <= 2`).
+ *  - **Capped:** at most `max` new captures per run (the rest wait for the next run).
+ *  - **Deduped:** an id that already exists is skipped.
+ * Captures land as `capture`/`inbox` (triage state); the human promotes/parks them.
+ */
+export function cmdIngestGdoc(
+  store: Store,
+  text: string,
+  opts: { domain?: string; source?: string; prevText?: string | null; max?: number; minLen?: number } = {},
+): IngestResult {
+  const minLen = opts.minLen ?? 12;
+  const max = opts.max ?? 25;
+  const source = opts.source ?? 'gdoc';
+  if (opts.prevText == null) {
+    return { created: [], skipped: 0, newBullets: 0, baselined: true, capped: 0 };
+  }
+  const prevSet = new Set(extractBullets(opts.prevText).map((b) => b.text));
+  const fresh = extractBullets(text).filter((b) => b.text.length >= minLen && b.depth <= 2 && !prevSet.has(b.text));
+  const seeds = toSeeds(fresh.slice(0, max), { domain: opts.domain, source });
+  const created: string[] = [];
+  let skipped = 0;
+  for (const seed of seeds) {
+    if (store.get(seed.id)) {
+      skipped++;
+      continue;
+    }
+    store.write(
+      { id: seed.id, type: seed.type, title: seed.title, status: seed.status, domain: seed.domain, source: seed.source, created: today() },
+      seed.title,
+    );
+    created.push(seed.id);
+  }
+  return { created, skipped, newBullets: fresh.length, baselined: false, capped: Math.max(0, fresh.length - seeds.length) };
+}
+
+export function cmdDoctor(store: Store, idx: PlanningIndex, config: Config): string {
+  const counts = idx.counts();
+  const blocked = idx.blockedByKnowledge(config.kb_root).filter((b) => b.status !== 'resolved');
+  const warnings = store.getWarnings();
+  return [
+    `store root: ${store.root}`,
+    `kb_root:    ${config.kb_root}`,
+    `sessions:   ${config.sessions_root}`,
+    `objects:    ${Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(' ') || '(none)'}`,
+    `fts5:       ${idx.fts ? 'yes' : 'no (LIKE fallback)'}`,
+    `blocked:    ${blocked.length} (${blocked.filter((b) => b.resolvable).length} resolvable, ${blocked.filter((b) => !b.exists).length} missing)`,
+    `warnings:   ${warnings.length}${warnings.length ? '\n  ' + warnings.join('\n  ') : ''}`,
+  ].join('\n');
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function pad(s: string, n: number): string {
+  return (s ?? '').padEnd(n).slice(0, n);
+}
+
+function countBy(items: string[]): string {
+  const m: Record<string, number> = {};
+  for (const i of items) m[i] = (m[i] ?? 0) + 1;
+  return Object.entries(m)
+    .map(([k, v]) => `${k}=${v}`)
+    .join(' ');
+}
+
+function uniqueId(store: Store, base: string): string {
+  if (!store.get(base)) return base;
+  let n = 2;
+  while (store.get(`${base}-${n}`)) n++;
+  return `${base}-${n}`;
+}
+
+function previousDay(date: string): string {
+  const d = new Date(date + 'T00:00:00Z');
+  d.setUTCDate(d.getUTCDate() - 1);
+  return d.toISOString().slice(0, 10);
+}