harnery 0.34.1 → 0.36.0

package/src/commands/backup.ts

@@ -108,10 +108,10 @@ export function registerBackupCommand(program: Command, emit: EmitContext): void
   backup
     .command("init")
     .description("Create the restic repository + password file (one-time).")
-    .option("--repo <path>", `Repository path (default: ${defaultRepo()})`)
+    .option("--repo <path>", "Repository path (default: configured backup.repo)")
     .option(
       "--password-file <path>",
-      `Password file (default: ${defaultPasswordFile()}, autogenerated)`,
+      "Password file (default: configured backup.password_file; autogenerated)",
     )
     .action((opts: BaseOpts) => {
       if (!checkRestic(emit)) {
@@ -257,24 +257,27 @@ export function registerBackupCommand(program: Command, emit: EmitContext): void
   // -- prune --
   // Prune-policy defaults come from backup.keep_* in config.jsonc (falling back
   // to 7/4/6); an explicit --keep-* flag still overrides per invocation.
-  const prunePolicy = backupConfig();
   backup
     .command("prune")
-    .description(
-      `Forget + prune snapshots (default policy: keep ${prunePolicy.keepDaily} daily / ${prunePolicy.keepWeekly} weekly / ${prunePolicy.keepMonthly} monthly).`,
+    .description("Forget + prune snapshots (default policy comes from backup.keep_* config).")
+    .option("--keep-daily <n>", "Daily snapshots to keep (default: configured backup.keep_daily)")
+    .option(
+      "--keep-weekly <n>",
+      "Weekly snapshots to keep (default: configured backup.keep_weekly)",
+    )
+    .option(
+      "--keep-monthly <n>",
+      "Monthly snapshots to keep (default: configured backup.keep_monthly)",
     )
-    .option("--keep-daily <n>", "Daily snapshots to keep", String(prunePolicy.keepDaily))
-    .option("--keep-weekly <n>", "Weekly snapshots to keep", String(prunePolicy.keepWeekly))
-    .option("--keep-monthly <n>", "Monthly snapshots to keep", String(prunePolicy.keepMonthly))
     .option("--dry-run", "Show what would be pruned without actually pruning")
     .option("--repo <path>", "Repository path")
     .option("--password-file <path>", "Password file")
     .action(
       (
         opts: BaseOpts & {
-          keepDaily: string;
-          keepWeekly: string;
-          keepMonthly: string;
+          keepDaily?: string;
+          keepWeekly?: string;
+          keepMonthly?: string;
           dryRun?: boolean;
         },
       ) => {
@@ -282,14 +285,15 @@ export function registerBackupCommand(program: Command, emit: EmitContext): void
           emit.setExitCode(1);
           return;
         }
+        const prunePolicy = backupConfig();
         const args = [
           "forget",
           "--keep-daily",
-          opts.keepDaily,
+          opts.keepDaily ?? String(prunePolicy.keepDaily),
           "--keep-weekly",
-          opts.keepWeekly,
+          opts.keepWeekly ?? String(prunePolicy.keepWeekly),
           "--keep-monthly",
-          opts.keepMonthly,
+          opts.keepMonthly ?? String(prunePolicy.keepMonthly),
         ];
         if (!opts.dryRun) args.push("--prune");
         else args.push("--dry-run");

package/src/commands/browse-session.ts

@@ -28,6 +28,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("status")
+    .description("Report whether the opted-in browser session is reachable")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "status", {}));
 
@@ -43,6 +44,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("screenshot")
+    .description("Capture the active tab to a new PNG file")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .requiredOption("--out <path>", "New PNG path in an existing directory")
     .action((opts: ControlFileOpts & { out: string }) =>
@@ -51,11 +53,13 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("tabs")
+    .description("List open tabs with stable session-local indexes")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "tabs", {}));
 
   session
     .command("select-tab")
+    .description("Select an open tab by its stable session-local index")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .requiredOption("--index <n>", "Stable session-local tab index", parseIndex)
     .action((opts: ControlFileOpts & { index: number }) =>
@@ -64,6 +68,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("open-tab <url>")
+    .description("Open a URL in a new tab and select it")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((url: string, opts: ControlFileOpts) =>
       runAction(emit, opts.controlFile, "open_tab", { url }),
@@ -71,6 +76,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("close-tab")
+    .description("Close an open tab by its stable session-local index")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .requiredOption("--index <n>", "Stable session-local tab index", parseIndex)
     .action((opts: ControlFileOpts & { index: number }) =>
@@ -79,6 +85,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("goto <url>")
+    .description("Navigate the active tab to a URL")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((url: string, opts: ControlFileOpts) =>
       runAction(emit, opts.controlFile, "goto", { url }),
@@ -86,12 +93,14 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("reload")
+    .description("Reload the active tab")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "reload", {}));
 
   addLocatorOptions(
     session
       .command("click")
+      .description("Click one strict locator in the active tab")
       .requiredOption("--control-file <path>", "Owner-only session descriptor"),
   ).action((opts: LocatorOpts) =>
     runAction(emit, opts.controlFile, "click", { locator: parseLocatorOptions(opts, true) }),
@@ -112,6 +121,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("press <key>")
+    .description("Press a keyboard key in the active tab")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((key: string, opts: ControlFileOpts) =>
       runAction(emit, opts.controlFile, "press", { key }),
@@ -120,6 +130,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
   addLocatorOptions(
     session
       .command("wait")
+      .description("Wait for one strict locator in the active tab")
       .requiredOption("--control-file <path>", "Owner-only session descriptor"),
   ).action((opts: LocatorOpts) =>
     runAction(emit, opts.controlFile, "wait", { locator: parseLocatorOptions(opts, true) }),
@@ -127,6 +138,7 @@ export function registerBrowseSessionCommand(program: Command, emit: EmitContext
 
   session
     .command("close")
+    .description("Close the opted-in browser session")
     .requiredOption("--control-file <path>", "Owner-only session descriptor")
     .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "close", {}));
 }

package/src/commands/browse.ts

@@ -24,6 +24,7 @@ import {
   parseAssertSpec,
   type RuntsResult,
   runCritique,
+  type StandaloneHtmlResult,
   type TargetSizeProfile,
   type TargetSizeResult,
   tilesFromFullPage,
@@ -229,6 +230,7 @@ export function registerBrowseCommand(
   program: Command,
   emitParam: EmitContext,
   context?: HarneryProgramContext,
+  binName = resolveBinName(),
 ): void {
   emit = emitParam;
   program
@@ -245,7 +247,7 @@ export function registerBrowseCommand(
     .option("--snapshot", "Print body innerText to stdout (skips file writes)")
     .option(
       "--html",
-      `Print raw outer HTML to stdout (skips file writes; pair with \`${resolveBinName()} read -\`)`,
+      `Print raw outer HTML to stdout (skips file writes; pair with \`${binName} read -\`)`,
     )
     .option("--json", "Print full JSON envelope to stdout (skips file writes)")
     .option("--selector <css>", "Scope --html / --snapshot to one element")
@@ -931,12 +933,10 @@ async function runBrowse(
     let critiqueTiles: CritiqueTile[] | undefined;
     let critiqueFullPage: Buffer | undefined;
     if (opts.checkCritique !== undefined) {
+      const critiqueProvider =
+        context?.critiqueProvider ?? (await context?.critiqueProviderLoader?.());
       const rubric = opts.checkCritiqueRubric ?? DEFAULT_CRITIQUE_RUBRIC;
-      const captured = await captureCritiqueTiles(
-        browser,
-        opts,
-        context?.critiqueProvider?.tileBudgetPx,
-      );
+      const captured = await captureCritiqueTiles(browser, opts, critiqueProvider?.tileBudgetPx);
       critiqueTiles = captured.tiles;
       critiqueFullPage = captured.fullPage;
       let tilesToReview = captured.tiles;
@@ -983,7 +983,7 @@ async function runBrowse(
         url: navResult.url,
         rubric,
         tiles: tilesToReview,
-        provider: context?.critiqueProvider,
+        provider: critiqueProvider,
       });
     }
     // Persist the QA baseline AFTER critique so a passing run's verdicts ride
@@ -1529,9 +1529,22 @@ async function runTrioMode(
     throw new Error("--capture-evaluate requires a screenshot; remove --no-screenshot.");
   }
 
+  // A trio `.html` is opened in a browser later — from the files origin, from
+  // another machine, from disk — so it has to carry its own CSS and media. A
+  // selector capture is a DOM fragment, not a document, and stays raw.
   const htmlPath = `${prefix}.html`;
-  const html = await browser.htmlContent(opts.selector);
-  writeFileSync(htmlPath, html);
+  let snapshot: StandaloneHtmlResult | undefined;
+  if (opts.selector) {
+    writeFileSync(htmlPath, await browser.htmlContent(opts.selector));
+  } else {
+    try {
+      snapshot = await browser.standaloneHtml();
+      writeFileSync(htmlPath, snapshot.html);
+    } catch {
+      // Inlining is best-effort; a raw serialization beats no snapshot at all.
+      writeFileSync(htmlPath, await browser.htmlContent());
+    }
+  }
   written.push(htmlPath);
 
   const diag = browser.diagnostics();
@@ -1548,6 +1561,15 @@ async function runTrioMode(
     ...summarizeDiagnostics(diag),
   };
   if (pngBytes !== undefined) envelope.screenshotBytes = pngBytes;
+  if (snapshot) {
+    envelope.htmlSnapshot = {
+      stylesheetsInlined: snapshot.stylesheetsInlined,
+      stylesheetsLinked: snapshot.stylesheetsLinked,
+      resourcesInlined: snapshot.resourcesInlined,
+      resourcesLinked: snapshot.resourcesLinked,
+      inlinedBytes: snapshot.inlinedBytes,
+    };
+  }
   if (opts.evaluate) envelope.eval = evalResult;
   if (opts.captureEvaluate) {
     envelope.captureEval = captureEvalResult;

package/src/commands/conversations.ts

@@ -0,0 +1,279 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import type { HarneryConversationCatalog } from "../core/conversations/catalog.ts";
+import { buildConversationContextPack } from "../core/conversations/context-pack.ts";
+import type {
+  HarneryConversationQueryRequest,
+  HarneryConversationRecordV1,
+  HarneryConversationRole,
+} from "../core/conversations/contract.ts";
+import {
+  type HarneryConversationPurgePlan,
+  planConversationPurge,
+  validatePurgeExecutionRequest,
+} from "../core/conversations/lifecycle.ts";
+import { queryConversationCatalog } from "../core/conversations/query.ts";
+
+export interface RegisterConversationsOptions {
+  project_scope_id: string;
+  records?: () => readonly HarneryConversationRecordV1[];
+}
+
+export function registerConversationsCommand(
+  program: Command,
+  emit: EmitContext,
+  catalog?: HarneryConversationCatalog,
+  dependencies?: RegisterConversationsOptions,
+): void {
+  const pendingPlans = new Map<string, HarneryConversationPurgePlan>();
+  const conversations = program.command("conversations").description("Query conversation evidence");
+
+  conversations
+    .command("list")
+    .option("--provider <id>")
+    .option("--project <id>")
+    .option("--json")
+    .action(async (options: { provider?: string; project?: string; json?: boolean }) => {
+      await run(emit, async () => {
+        const configured = requireConversations(catalog, dependencies);
+        const project = exactProject(configured.dependencies.project_scope_id, options.project);
+        const providers = options.provider
+          ? [configured.catalog.require(options.provider)]
+          : configured.catalog.list();
+        const rows = (
+          await Promise.all(
+            providers.map(async (provider) =>
+              provider.capabilities.can_list ? provider.list(project) : [],
+            ),
+          )
+        ).flat();
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data({ schema: "harnery.conversation-list/v1", project_scope_id: project, rows });
+        } else emit.rows(rows as unknown as Record<string, unknown>[]);
+      });
+    });
+
+  addQueryOptions(conversations.command("query"))
+    .option("--json")
+    .action(async (options: QueryOptions) => {
+      await run(emit, async () => {
+        const configured = requireConversations(catalog, dependencies);
+        const result = await queryConversationCatalog(
+          configured.catalog,
+          request(configured.dependencies, options),
+        );
+        if (options.json) {
+          emit.config({ format: "json" });
+          emit.data(result);
+        } else {
+          emit.rows(
+            result.hits.map(({ record, citation }) => ({
+              ...citation,
+              content: record.content,
+            })),
+          );
+        }
+      });
+    });
+
+  addQueryOptions(conversations.command("context"))
+    .option("--max-tokens <count>", "Token ceiling", parsePositive, 2_000)
+    .option("--max-bytes <count>", "Byte ceiling", parsePositive, 16_000)
+    .option("--json")
+    .action(
+      async (options: QueryOptions & { maxTokens: number; maxBytes: number; json?: boolean }) => {
+        await run(emit, async () => {
+          const configured = requireConversations(catalog, dependencies);
+          const result = await queryConversationCatalog(
+            configured.catalog,
+            request(configured.dependencies, options),
+          );
+          const pack = buildConversationContextPack(result, {
+            max_tokens: options.maxTokens,
+            max_bytes: options.maxBytes,
+          });
+          if (options.json) emit.config({ format: "json" });
+          emit.data(pack);
+        });
+      },
+    );
+
+  conversations
+    .command("archive")
+    .requiredOption("--mode <mode>", "off | source | archive")
+    .option("--authority <mode>", "shadow | cutover | rollback", "shadow")
+    .option("--yes", "Reserved for a future checked capture transaction")
+    .action((options: { mode: string; authority: string; yes?: boolean }) => {
+      const validMode = ["off", "source", "archive"].includes(options.mode);
+      const validAuthority = ["shadow", "cutover", "rollback"].includes(options.authority);
+      if (!validMode || !validAuthority) {
+        emit.error({ code: "conversation_archive_mode_invalid", message: "invalid archive mode" });
+        emit.setExitCode(1);
+        return;
+      }
+      emit.data({
+        schema: "harnery.conversation-archive-plan/v1",
+        access_mode: options.mode,
+        authority_mode: options.authority,
+        dry_run: true,
+        writes: false,
+        execution_enabled: false,
+      });
+    });
+
+  conversations
+    .command("purge")
+    .option("--conversation <id>")
+    .option("--before <time>")
+    .option("--transaction <id>")
+    .option("--yes")
+    .option("--json")
+    .action(
+      (options: {
+        conversation?: string;
+        before?: string;
+        transaction?: string;
+        yes?: boolean;
+        json?: boolean;
+      }) => {
+        try {
+          const configured = requireConversations(catalog, dependencies);
+          if (options.transaction) {
+            const plan = pendingPlans.get(options.transaction);
+            if (!plan) throw new Error(`unknown purge transaction: ${options.transaction}`);
+            const result = validatePurgeExecutionRequest(
+              plan,
+              options.transaction,
+              options.yes ?? false,
+            );
+            if (options.json) emit.config({ format: "json" });
+            emit.data({ schema: "harnery.conversation-purge-result/v1", ...result });
+            if (result.reason_code !== "execution_disabled") emit.setExitCode(1);
+            return;
+          }
+          const plan = planConversationPurge({
+            records: configured.dependencies.records?.() ?? [],
+            project_scope_id: configured.dependencies.project_scope_id,
+            ...(options.conversation ? { conversation_id: options.conversation } : {}),
+            ...(options.before ? { before: options.before } : {}),
+          });
+          pendingPlans.set(plan.transaction_id, plan);
+          if (options.json) emit.config({ format: "json" });
+          emit.data(plan);
+        } catch (error) {
+          emit.error({
+            code: "conversation_purge_failed",
+            message: error instanceof Error ? error.message : String(error),
+          });
+          emit.setExitCode(1);
+        }
+      },
+    );
+}
+
+function requireConversations(
+  catalog?: HarneryConversationCatalog,
+  dependencies?: RegisterConversationsOptions,
+): {
+  catalog: HarneryConversationCatalog;
+  dependencies: RegisterConversationsOptions;
+} {
+  if (!catalog || !dependencies)
+    throw new Error("conversation providers are not configured by this host");
+  return { catalog, dependencies };
+}
+
+interface QueryOptions {
+  text?: string;
+  regex?: string;
+  role?: string;
+  since?: string;
+  until?: string;
+  project?: string;
+  provider?: string;
+  session?: string;
+  conversation?: string;
+  record?: string;
+  limit: number;
+  contextBefore: number;
+  contextAfter: number;
+  json?: boolean;
+}
+
+function addQueryOptions(command: Command): Command {
+  return command
+    .option("--text <literal>")
+    .option("--regex <pattern>")
+    .option("--role <role>")
+    .option("--since <time>")
+    .option("--until <time>")
+    .option("--project <id>")
+    .option("--provider <id>")
+    .option("--session <id>")
+    .option("--conversation <id>")
+    .option("--record <id>")
+    .option("--limit <count>", "Match ceiling", parsePositive, 20)
+    .option("--context-before <count>", "Earlier neighbors", parseNonnegative, 0)
+    .option("--context-after <count>", "Later neighbors", parseNonnegative, 0);
+}
+
+function request(
+  dependencies: RegisterConversationsOptions,
+  options: QueryOptions,
+): HarneryConversationQueryRequest {
+  const role = options.role as HarneryConversationRole | undefined;
+  return {
+    project_scope_id: exactProject(dependencies.project_scope_id, options.project),
+    limit: options.limit,
+    context_before: options.contextBefore,
+    context_after: options.contextAfter,
+    budgets: {
+      max_source_records: 10_000,
+      max_decoded_bytes: 16 * 1_024 * 1_024,
+      max_matches: options.limit,
+      max_wall_ms: 5_000,
+      max_regex_chars: 256,
+    },
+    ...(options.text ? { text: options.text } : {}),
+    ...(options.regex ? { regex: options.regex } : {}),
+    ...(role ? { role } : {}),
+    ...(options.since ? { since: options.since } : {}),
+    ...(options.until ? { until: options.until } : {}),
+    ...(options.provider ? { provider_id: options.provider } : {}),
+    ...(options.session ? { session_id: options.session } : {}),
+    ...(options.conversation ? { conversation_id: options.conversation } : {}),
+    ...(options.record ? { record_id: options.record } : {}),
+  };
+}
+
+function exactProject(expected: string, requested?: string): string {
+  if (requested && requested !== expected)
+    throw new Error("cross-project conversation access denied");
+  return expected;
+}
+
+function parsePositive(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed <= 0) throw new Error("expected a positive integer");
+  return parsed;
+}
+
+function parseNonnegative(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0)
+    throw new Error("expected a nonnegative integer");
+  return parsed;
+}
+
+async function run(emit: EmitContext, action: () => Promise<void>): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    emit.error({
+      code: "conversation_command_failed",
+      message: error instanceof Error ? error.message : String(error),
+    });
+    emit.setExitCode(1);
+  }
+}

package/src/commands/decision.ts

@@ -1,7 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
-import { emitEventV3, monorepoRoot, normalizeAdapter, resolveOwner } from "../core/agents/index.ts";
+import {
+  emitEventV3,
+  monorepoRoot,
+  nativeSessionIdentity,
+  normalizeAdapter,
+  resolveOwner,
+} from "../core/agents/index.ts";
 import { readLiveCoordinationRow } from "../core/agents/state/live-coordination-view.ts";
 import { resolveBinName } from "../core/config.ts";
 import {
@@ -442,7 +448,7 @@ function emitDecisionEvent(
   const hb = root ? readLiveCoordinationRow(root, owner) : null;
   emitEventV3({
     owner,
-    session: hb?.session_id ?? owner,
+    session: nativeSessionIdentity(hb, owner),
     adapter: normalizeAdapter(hb?.platform),
     observation: {
       event_type: "decision.state_changed",

package/src/commands/deinit.ts

@@ -35,6 +35,7 @@ import type { EmitContext } from "../commander.ts";
 import { DEFAULT_BIN_NAME } from "../core/config.ts";
 import { ADAPTER_SPECS, type AdapterId } from "../core/hooks/adapter/events.ts";
 import type { SettingsFile } from "../core/hooks/adapter/wiring.ts";
+import { removeIndexerExclusions } from "../lib/indexer-exclusions.ts";
 import { removeInstructions } from "../lib/instructions/apply.ts";
 import { removeGitHooks } from "../lib/instructions/git-hooks.ts";
 import { unwireHooks } from "./init.ts";
@@ -136,6 +137,11 @@ export function registerDeinitCommand(program: Command, emit: EmitContext, binNa
         }
       }
 
+      // ── 1a′. editor indexer exclusions ─────────────────────────────────────
+      // Reverse only what init wrote: the managed .cursorindexingignore entry
+      // and the files.watcherExclude key. Consumer-authored entries stay.
+      actions.push(...removeIndexerExclusions(projectRoot, dryRun));
+
       // ── 1b. agent-facing instructions block + skills ───────────────────────
       const removed = removeInstructions(projectRoot, { adapter, dryRun });
       actions.push(...removed.actions, ...removed.warnings.map((w) => `! ${w}`));

package/src/commands/docs.ts

@@ -92,10 +92,14 @@ export function registerDocsCommand(
     .command("validate")
     .description("Validate every managed Markdown file against harnery-doc/v2")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
-    .action(async (opts: { repo?: string }) => {
+    .option("--cached", "Read paths and contents from the Git index")
+    .action(async (opts: { repo?: string; cached?: boolean }) => {
       try {
         ensureContext(context);
-        const rows = await runDocsMetadataAudit(opts);
+        const rows = await runDocsMetadataAudit({
+          repo: opts.repo,
+          source: opts.cached ? "index" : "worktree",
+        });
         const errors = rows
           .flatMap((row) => row.issues)
           .filter((issue) => issue.severity === "error");
@@ -128,9 +132,13 @@ export function registerDocsCommand(
     .argument("[files...]", "Explicit repository-relative Markdown files; defaults to staged files")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
     .option("--check", "Report timestamp drift without writing")
+    .option("--cached", "Read current contents from the Git index (requires --check)")
     .option("--reviewed", "Record an explicit runbook review and move its due date")
     .action(
-      async (files: string[], opts: { repo?: string; check?: boolean; reviewed?: boolean }) => {
+      async (
+        files: string[],
+        opts: { repo?: string; check?: boolean; cached?: boolean; reviewed?: boolean },
+      ) => {
         try {
           ensureContext(context);
           const rows = await runDocsMetadataSync({ ...opts, files });
@@ -194,8 +202,9 @@ export function registerDocsCommand(
     )
     .option("--fast", "Skip content-reading checks; filename/structure only (for pre-commit)")
     .option("--repo <name>", "Limit to one submodule or '.' for parent")
+    .option("--cached", "Read paths and contents from the Git index")
     .option("--format <type>", "Output format: human, json", "human")
-    .action(async (opts: { fast?: boolean; repo?: string; format: string }) => {
+    .action(async (opts: { fast?: boolean; repo?: string; cached?: boolean; format: string }) => {
       try {
         ensureContext(context);
         await handleLint(opts);
@@ -311,8 +320,17 @@ async function handleDocs(opts: {
 
 // --- `harn docs lint` ---
 
-async function handleLint(opts: { fast?: boolean; repo?: string; format: string }): Promise<void> {
-  const violations = await runLint({ fast: opts.fast, repo: opts.repo });
+async function handleLint(opts: {
+  fast?: boolean;
+  repo?: string;
+  cached?: boolean;
+  format: string;
+}): Promise<void> {
+  const violations = await runLint({
+    fast: opts.fast,
+    repo: opts.repo,
+    source: opts.cached ? "index" : "worktree",
+  });
   const errors = violations.filter((v) => v.severity === "error");
   const warnings = violations.filter((v) => v.severity === "warning");
   const cold = await countColdHandoffs();
@@ -320,6 +338,7 @@ async function handleLint(opts: { fast?: boolean; repo?: string; format: string
   emit.data({
     fast: !!opts.fast,
     repo: opts.repo ?? null,
+    source: opts.cached ? "index" : "worktree",
     error_count: errors.length,
     warning_count: warnings.length,
     cold_handoffs: cold,