Fix stale FTS cache detection

data/help/commands/predicate.jinja

@@ -47,18 +47,19 @@ Notes:
   - Use `evidence` first when verification matters more than context assembly.
 {% elif predicate == "create" %}
 Purpose:
-  Create or replace the archive at this URI.
+  Create the archive at this URI.
 
 Usage:
-  wikigraph {{ uri }} create [source] [--input-format <format>] [--llm <json>] [--prompt <text>] [--json]
+  wikigraph {{ uri }} create [source] [--input-format <format>] [--llm <json>] [--prompt <text>] [--replace] [--json]
 
 Notes:
   - `source` may be EPUB, Markdown, txt, URL, or another supported input path.
   - Without `source`, an empty `.wikg` archive is created unless stdin is selected with `--input-format`.
   - Stdin is supported when `--input-format markdown` or `--input-format txt` is provided.
   - Input format is inferred from the source extension when possible; use `--input-format` when stdin or the extension is ambiguous.
   - Creating from EPUB, Markdown, txt, URL, or stdin runs only the import/source stage.
-  - This command creates or replaces the target archive file; parent directories must already exist.
+  - Existing archives are not overwritten by default. Use `--replace` only when the target archive should be discarded and recreated.
+  - Parent directories must already exist.
   - `--llm <json>` passes local LLM settings to the import pipeline when the selected input path needs them.
   - On success, text output is the archive object (`<archive>`). With `--json`, output is `{"uri":"..."}`.
 
@@ -113,6 +114,7 @@ Usage:
 Notes:
   - Generation jobs may call an LLM provider and incur cost.
   - Archive input adds jobs for all eligible chapters; chapter input adds one job.
+  - `--llm <json>` stores a job-local LLM object; it does not update `wikg://local/config/llm`.
 {% elif predicate == "move" %}
 Purpose:
   Move this chapter in the chapter tree.

data/help/commands/root.jinja

@@ -45,9 +45,9 @@ What to learn where:
     wikigraph help recipe
   - Search index, LLM, WikiSpine, and generated-data prerequisites:
     wikigraph help readiness
-  - URI grammar, scope/object routing, pagination, JSON, and JSONL:
+  - URI grammar, scope/object routing, pagination, and short URI handling:
     wikigraph help uri
-  - Input/output formats, inference, stdin, stdout, import, export, and transform:
+  - Input/output formats, inference, stdin, stdout, import, export, transform, JSON, and JSONL:
     wikigraph help format
   - Local LLM, concurrency, and WikiSpine provider configuration:
     wikigraph help config

data/help/commands/uri.jinja

@@ -226,7 +226,7 @@ Predicate commands:
 {% elif predicate == "clear" %}
   - clear: clear a writable resource or config section. Help: wikigraph {{ uri }} clear --help
 {% elif predicate == "create" %}
-  - create: create or replace the archive. Help: wikigraph {{ uri }} create --help
+  - create: create the archive; use `--replace` only when discarding an existing archive. Help: wikigraph {{ uri }} create --help
 {% elif predicate == "delete" %}
   - delete: delete a config key. Help: wikigraph {{ uri }} delete --help
 {% elif predicate == "embed" %}

data/help/topics/config.jinja

@@ -60,6 +60,8 @@ One-run overrides:
   `--llm <json>` can provide an LLM object for one invocation.
   It accepts direct LLM objects and common OpenAI-compatible aliases such as `baseUrl`.
   A base URL implies `openai-compatible` when `provider` is omitted.
+  Generation jobs may also receive `--llm <json>` at `wikigraph wikg://local/job add`;
+  that job-local LLM object is stored with the job and does not appear in `wikg://local/config/llm`.
 
 Examples:
   wikigraph wikg://local/config/llm put provider openai

data/help/topics/format.jinja

@@ -4,7 +4,7 @@ Topic: format
 Format Rules
 
 Purpose:
-  File format rules apply at archive boundaries: create/import, export, transform, stdin, and stdout.
+  Format rules cover archive file formats, stdin/stdout inference, and command output shapes for Agents and scripts.
 
 Managed archive format:
   wikg
@@ -25,11 +25,45 @@ Inference rules:
   - Stdout text export requires an explicit or inferable output format.
   - `transform --stage` is only valid when creating `.wikg` from source input.
 
+Command output shapes:
+  - Default text output is for direct human reading and quick inspection.
+  - Use `--json` when an Agent or script needs one stable machine-readable response.
+  - Use `--jsonl` when a command returns many records, streams progress, or feeds a Unix pipeline.
+  - Most read, retrieval, config, job, and maintenance commands support `--json`; unsupported commands fail explicitly.
+  - Commands that do not support `--json` or `--jsonl` say so in their command help or error message.
+
+JSON:
+  `--json` prints one JSON value to stdout.
+  It is usually the best Agent-facing format for inspecting one object, one result page, one config section, one job, or one command report.
+  Prefer it over parsing text when you need fields such as `uri`, `title`, `state`, `nextCursor`, readiness flags, or job status.
+
+JSONL:
+  `--jsonl` prints one JSON record per line.
+  Use it for object inventories, large scope traversal, progress streams, and pipe-oriented downstream processing.
+  JSONL may contain both object records and control records.
+  A paged scope can end with a control record such as:
+    {"type":"page","nextCursor":"..."}
+  Filter by `type` when a downstream program expects only archive objects.
+
+Full-scope export pattern:
+  `--jsonl` is an output shape; it does not imply `--all`.
+  Use `--all --jsonl` when intentionally exporting every object from the selected scope.
+  Prefer the narrowest useful scope before full export.
+  Avoid `--all` without `--jsonl` for large result sets because text and JSON output are buffered before printing.
+  Avoid `--all | head` as a preview pattern. Shell truncation only limits what you read.
+
+Stdout and stderr:
+  Machine-readable command results go to stdout.
+  Progress, warnings, and diagnostics go to stderr.
+  Commands that accept `--json` or `--jsonl` emit machine-readable error objects when those flags are present.
+
 Examples:
   wikigraph wikg://book.wikg create ./book.epub
   wikigraph wikg://book.wikg create ./book.md
   cat chapter.md | wikigraph wikg://book.wikg create --input-format markdown
   wikigraph wikg://book.wikg export --output-format markdown --output out.md
   cat chapter.txt | wikigraph transform --input-format txt --output-format markdown
+  wikigraph wikg://book.wikg inspect --json
+  wikigraph wikg://book.wikg/entity --all --jsonl
 
 Transforming source input usually requires LLM configuration.

data/help/topics/recipe.jinja

@@ -10,6 +10,7 @@ Purpose:
 Operating rules:
   - Never unzip a `.wikg` archive, rewrite internal files, or bypass this CLI. Use CLI commands for archive edits.
   - Use Wiki Graph URIs as stable object handles.
+  - Use `--json` when you want stable Agent-readable fields instead of human text; most commands support it and unsupported commands fail explicitly.
   - If you have a URI and need valid operations, run `wikigraph <uri> --help`.
   - If you need concrete predicate usage for that URI type, run `wikigraph <uri> <predicate> --help`.
   - Never pass a bare filesystem path to URI-targeted commands.
@@ -117,14 +118,14 @@ Finding material:
       wikigraph wikg://book.wikg/chapter/3/summary
 
   - Need an inventory for a script or Unix pipeline:
-    Enumerate object scopes with `--jsonl`, then filter with standard stream tools.
-    JSONL contains object records and may end with a control record such as `{"type":"page","nextCursor":"..."}`.
-      wikigraph wikg://book.wikg/entity --jsonl
-      wikigraph wikg://book.wikg/triple --jsonl
-      wikigraph wikg://book.wikg/chunk --jsonl
-      wikigraph wikg://book.wikg/chapter/3/entity --jsonl
-      wikigraph wikg://book.wikg/chapter/3/triple --jsonl
-      wikigraph wikg://book.wikg/chapter/3/chunk --jsonl
+    Use `--all --jsonl` to export the selected scope as line-delimited records, then filter with standard stream tools.
+    Prefer the narrowest useful scope before full export.
+      wikigraph wikg://book.wikg/entity --all --jsonl
+      wikigraph wikg://book.wikg/triple --all --jsonl
+      wikigraph wikg://book.wikg/chunk --all --jsonl
+      wikigraph wikg://book.wikg/chapter/3/entity --all --jsonl
+      wikigraph wikg://book.wikg/chapter/3/triple --all --jsonl
+      wikigraph wikg://book.wikg/chapter/3/chunk --all --jsonl
 
   - Need bounded Agent-readable context around an object:
     Use pack only after choosing a located chunk or entity URI.
@@ -135,9 +136,9 @@ Finding material:
       wikigraph next <cursor>
 
 When to read deeper:
-  - URI details, scope/object routing, pagination, JSON, JSONL, and short URI handling:
+  - URI details, scope/object routing, pagination, and short URI handling:
     wikigraph help uri
-  - Format inference, stdin/stdout, create/import, export, and transform:
+  - Format inference, stdin/stdout, create/import, export, transform, JSON, JSONL, and pipe output:
     wikigraph help format
   - LLM, concurrency, and WikiSpine provider setup:
     wikigraph help config

data/help/topics/uri.jinja

@@ -5,7 +5,7 @@ Wiki Graph URIs
 
 Purpose:
   URI targets are the address and routing layer for Wiki Graph commands.
-  Use this page to choose a target, understand scope/object behavior, select retrieval shape, and choose object result format.
+  Use this page to choose a target, understand scope/object behavior, and select retrieval shape.
 
 Archive locator:
   - Archive/object command URIs must contain a `.wikg` locator.
@@ -109,8 +109,7 @@ Retrieval order:
   1. Choose the narrowest URI scope that can answer the task.
   2. Choose the object lens that matches the question.
   3. Start with a bounded page.
-  4. Choose object result format by how the result will be consumed.
-  5. Use `--all` only for an intentional full export or bounded inventory.
+  4. Use `--all` only for an intentional full export or bounded inventory.
 
 Lens selection:
   - Use `<archive-uri>` when the whole archive is the right retrieval scope.
@@ -132,19 +131,12 @@ Entity-grounded evidence:
     wikigraph <archive-uri>/entity/<qid> evidence
     wikigraph <archive-uri>/entity/<qid> related --query "aspect" --evidence 2
 
-Pagination and object result format:
+Pagination:
   - Use default paging or `--limit <n>` while exploring.
   - Use `wikigraph next <cursor>` to continue a paged result.
   - Use `--all` only when you intentionally need every item from the selected scope.
   - Prefer the narrowest scope before using `--all`.
-  - Default text is for reading and inspection.
-  - `--json` is for one stable machine-readable page.
-  - `--jsonl` is for streamed records, shell pipelines, or full exports.
-  - JSONL contains object records and may include control records such as `{"type":"page","nextCursor":"..."}`.
-  - Filter JSONL by `type` when a pipeline expects only archive objects.
-  - `--jsonl` is only an output format; it does not imply `--all`.
-  - Avoid `--all` without `--jsonl` for large results because text and JSON output are buffered before printing.
-  - Avoid `--all | head` as a preview pattern. Shell truncation only limits what you read.
+  - Read `wikigraph help format` before choosing text, `--json`, `--jsonl`, or `--all --jsonl` for machine consumption.
 
 Recovery hints:
   - No `--query` results: try fewer keywords, use a broader scope URI, or inspect chapter readiness and structure.
@@ -171,7 +163,7 @@ Archive internals:
 Related help:
   - Search index, generated data, and provider prerequisites:
     wikigraph help readiness
-  - Stdin/stdout, create/import, export, and transform formats:
+  - Stdin/stdout, create/import, export, transform, JSON, JSONL, and pipe-oriented output:
     wikigraph help format
   - Local jobs, cache, logs, and runtime debugging:
     wikigraph help runtime

src/archive/query/archive-view.ts

@@ -50,9 +50,10 @@ import {
   type SearchTripleHitInput,
 } from "./search-cache.js";
 import {
+  createSearchIndexFingerprint,
   ensureSearchIndex,
-  isSearchIndexCurrent,
   querySearchIndex,
+  readSearchIndexStatus,
   SEARCH_OBJECT_PROPERTY_KIND,
   SEARCH_OBJECT_PROPERTY_OWNER_KIND,
   TEXT_SENTENCE_KIND,
@@ -1046,13 +1047,44 @@ export async function rebuildArchiveSearchIndex(
   document: Document,
   progress?: SearchIndexProgressReporter,
 ): Promise<void> {
-  await ensureSearchIndex(
+  const input = await createSearchIndexRecords(document, progress);
+
+  if ((await readSearchIndexStatus(document, input)) === "dirty") {
+    await document.deleteSearchIndexDatabase();
+  }
+
+  await ensureSearchIndex(document, input, progress);
+}
+
+export async function isArchiveSearchIndexCurrent(
+  document: ReadonlyDocument,
+): Promise<boolean> {
+  return (await readArchiveSearchIndexStatus(document)) === "current";
+}
+
+export async function readArchiveSearchIndexStatus(
+  document: ReadonlyDocument,
+): Promise<"current" | "dirty" | "missing"> {
+  return await readSearchIndexStatus(
     document,
-    await createSearchIndexRecords(document, progress),
-    progress,
+    await createSearchIndexRecords(document),
   );
 }
 
+export async function clearDirtyArchiveSearchIndex(
+  document: Document,
+): Promise<void> {
+  if ((await readArchiveSearchIndexStatus(document)) === "dirty") {
+    await document.deleteSearchIndexDatabase();
+  }
+}
+
+export async function createArchiveSearchIndexFingerprint(
+  document: ReadonlyDocument,
+): Promise<string> {
+  return createSearchIndexFingerprint(await createSearchIndexRecords(document));
+}
+
 export async function grepArchiveObjects(
   document: ReadonlyDocument,
   query: string,
@@ -1096,7 +1128,7 @@ async function findArchiveObjectsIndexed(
     }
   | undefined
 > {
-  if (!(await isSearchIndexCurrent(document))) {
+  if (!(await isArchiveSearchIndexCurrent(document))) {
     throw new Error(
       "Wiki Graph search index is missing or outdated. Run `<archive-uri>/index build` before searching.",
     );
@@ -1125,7 +1157,7 @@ async function queryRequiredSearchIndex(
   query: string,
   options: Parameters<typeof querySearchIndex>[2],
 ): Promise<SearchIndexQueryResult | undefined> {
-  if (!(await isSearchIndexCurrent(document))) {
+  if (!(await isArchiveSearchIndexCurrent(document))) {
     throw new Error(
       "Wiki Graph search index is missing or outdated. Run `<archive-uri>/index build` before searching.",
     );

src/archive/query/index.ts

@@ -6,6 +6,10 @@ export {
   formatSummaryId,
   getArchiveIndex,
   grepArchiveObjects,
+  createArchiveSearchIndexFingerprint,
+  clearDirtyArchiveSearchIndex,
+  isArchiveSearchIndexCurrent,
+  readArchiveSearchIndexStatus,
   listAllArchiveLinks,
   listArchiveCollection,
   listArchiveEvidence,

src/archive/search-index/index.ts

@@ -1,8 +1,11 @@
 export {
+  createSearchIndexFingerprint,
   ensureSearchIndex,
   isSearchIndexCurrent,
   querySearchIndex,
   readArchiveIndexSettings,
+  readSearchIndexFingerprintFromDatabase,
+  readSearchIndexStatus,
   SEARCH_INDEX_FTS_HIT_LIMIT,
   SEARCH_OBJECT_PROPERTY_KIND,
   SEARCH_OBJECT_PROPERTY_OWNER_KIND,
@@ -17,6 +20,7 @@ export type {
   SearchIndexProgressPhase,
   SearchIndexProgressReporter,
   SearchIndexQueryResult,
+  SearchIndexStatus,
   SearchIndexTextHit,
   SearchObjectPropertyKind,
   SearchObjectPropertyOwnerKind,