wiki-graph 0.4.1 → 0.5.0

package/dist/data/help/commands/library-predicate.jinja

@@ -106,36 +106,36 @@ Usage:
   {{ commandName }} {{ uri }} [--json]
 
 Notes:
-  - The status tells whether the library index is current, dirty, missing, or disabled.
+  - The status tells whether the library index cache is current, dirty, or missing.
   - Library-wide object `--query` and object scope enumeration require a current library index.
-  - Run `enable` when the status says the index needs to be built or rebuilt.
-{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "enable" %}
+  - Run `sync` when the status says the index cache needs to be built or rebuilt.
+{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "sync" %}
 Purpose:
-  Build or rebuild this library's aggregate search index.
+  Sync this library's aggregate index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
+  {{ commandName }} {{ uri }} sync [--jsonl]
 
 Notes:
-  - This is a full rebuild from registered present archives.
+  - This rebuilds cache from chapter index artifacts already stored in registered present archives.
+  - It does not build missing artifacts and does not call an embeddings provider.
   - Missing or unreadable library archive members are skipped and reported.
   - Progress is emitted as text by default, or line-delimited events with `--jsonl`.
-  - `--json` is not supported for enable because progress is streamed.
+  - `--json` is not supported for sync because progress is streamed.
   - Library indexes are local derived state under Wiki Graph staging, not files inside the library folder.
-  - Rebuild holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `disable`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
-  - Archive writes can mark the aggregate index dirty; rebuild again before relying on library-wide query when status reports dirty or stale.
-{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "disable" %}
+  - Sync holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `clean`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
+{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "clean" %}
 Purpose:
-  Disable this library index and remove its current local materialization.
+  Remove this library index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} disable [--json]
+  {{ commandName }} {{ uri }} clean [--json]
 
 Notes:
   - This does not delete the library registry, metadata, folder, or managed `.wikg` archives.
-  - Library-wide object `--query` and object scope enumeration will fail until the index is enabled again.
-  - Library indexes do not support archive-style `embed` or `external` modes.
-  - Disable holds the library write lock and cannot run concurrently with membership changes or index rebuild for the same library.
+  - It deletes only local derived cache under Wiki Graph staging.
+  - Library-wide object `--query` and object scope enumeration will fail until the index cache is synced again.
+  - Clean holds the library write lock and cannot run concurrently with membership changes or index sync for the same library.
 {% elif target.kind == "scope" and predicate == "add" %}
 Purpose:
   Copy a `.wikg` archive into this library folder and register it as a managed archive member.
@@ -149,7 +149,7 @@ Notes:
   - `--to` must be a relative `.wikg` path inside the library folder.
   - Parent directories for `--to` are created as needed.
   - Existing target files are not overwritten.
-  - Adding an archive marks the library index dirty.
+  - Adding an archive can make an existing library index cache stale.
   - The command holds the library write lock and cannot run concurrently with `arc scan`, library `path set`, archive path changes/removes, or index rebuild for the same library.
 {% elif target.kind == "scope" and predicate == "scan" %}
 Purpose:
@@ -162,7 +162,7 @@ Notes:
   - Scan recursively discovers `.wikg` files in the bound library folder.
   - Registered files that are no longer present remain visible as missing/stale instead of being deleted silently.
   - When a moved archive can be matched by its stable mutation token, scan preserves its archive id and updates the relative path.
-  - Scan marks the library index dirty when membership changes.
+  - Scan can make an existing library index cache stale when membership changes.
   - Scan holds the library write lock and cannot run concurrently with membership changes or index rebuild for the same library.
 {% elif target.kind == "scope" and predicate == "get" %}
 Purpose:
@@ -220,7 +220,7 @@ Notes:
   - `--confirm` is required.
   - If the registered file is already missing, the command can still clean the registry entry.
   - This does not delete empty parent directories.
-  - Removing an archive marks the library index dirty.
+  - Removing an archive can make an existing library index cache stale.
   - Remove holds the library write lock and cannot run concurrently with library scan, add, path binding, archive path changes, or index rebuild for the same library.
 {% elif target.kind == "metadata" and predicate == "set" %}
 Purpose:

package/dist/data/help/commands/library.jinja

@@ -153,12 +153,12 @@ Use when:
 
 Usage:
   {{ commandName }} {{ uri }} [--json]
-  {{ commandName }} {{ uri }} enable [--jsonl]
-  {{ commandName }} {{ uri }} disable [--json]
+  {{ commandName }} {{ uri }} sync [--jsonl]
+  {{ commandName }} {{ uri }} clean [--json]
 
 Predicate commands:
-  - enable: rebuild this library index from registered present archives. Help: {{ commandName }} {{ uri }} enable --help
-  - disable: remove this library index materialization. Help: {{ commandName }} {{ uri }} disable --help
+  - sync: rebuild this library index cache from registered present archives' artifacts. Help: {{ commandName }} {{ uri }} sync --help
+  - clean: remove this library index cache. Help: {{ commandName }} {{ uri }} clean --help
 
 Related help:
   - Library registry, membership, path binding, and aggregate index concepts: {{ commandName }} help library
@@ -169,8 +169,9 @@ Default behavior:
   - `{{ commandName }} {{ uri }}` reads the library-wide scope collection.
   - Use `{{ commandName }} wikg://lib/registry` to list all library registries.
   - `{{ commandName }} {{ uri }} --query <query>` searches library-wide objects through the library index.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
   - `{{ commandName }} {{ uri }}/arc scan` reconciles membership with `.wikg` files currently under the library folder.
-  - Library-wide object scopes such as `/entity` and `/triple` query one object type through the library index after it is enabled.
+  - Library-wide object scopes such as `/entity` and `/triple` query one object type through the library index after it is synced.
   - Archive object search must use an explicit lens such as `/entity`, `/triple`, `/chapter`, or `/chunk`.
 
 Use when:
@@ -192,6 +193,7 @@ Usage:
 {% if target.isDefault %}
   {{ commandName }} wikg://lib [--json]
   {{ commandName }} wikg://lib --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} wikg://lib --query <query> --skip-unindexed
   {{ commandName }} wikg://lib/chapter --query <query>
   {{ commandName }} wikg://lib/chunk --query <query>
   {{ commandName }} wikg://lib/registry add --path <folder> [--json]
@@ -206,6 +208,7 @@ Usage:
 {% else %}
   {{ commandName }} {{ uri }} [--json]
   {{ commandName }} {{ uri }} --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} {{ uri }} --query <query> --skip-unindexed
   {{ commandName }} {{ uri }}/chapter --query <query>
   {{ commandName }} {{ uri }}/chunk --query <query>
   {{ commandName }} {{ uri }}/arc scan [--json|--jsonl]

package/dist/data/help/commands/predicate.jinja

@@ -14,12 +14,13 @@ Purpose:
   Expand from the current chunk or entity object to nearby objects.
 
 Usage:
-  {{ commandName }} {{ uri }} related [--query <query>] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--role <any|subject|object|self>] [--evidence [n]] [--json|--jsonl]
+  {{ commandName }} {{ uri }} related [--query <query>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--role <any|subject|object|self>] [--evidence [n]] [--json|--jsonl]
 
 Notes:
   - Chunk targets return nearby Reading Graph chunks.
   - Entity targets return Knowledge Graph triples involving the entity.
-  - `--query` filters and ranks related results with the current FTS index.
+  - `--query` filters and ranks related results with the current search index.
+  - Add `--skip-unindexed` only with `--query` when you intentionally want to search indexed chapters and ignore uncovered chapters.
   - Without `--query`, `--reverse` reads Document Flow order backward. See `{{ commandName }} help uri`.
   - `--role` only applies to entity targets.
   - Use `{{ commandName }} {{ uri }} evidence --help` when source grounding is the main goal.
@@ -28,11 +29,12 @@ Purpose:
   Trace the current object back to source-backed evidence.
 
 Usage:
-  {{ commandName }} {{ uri }} evidence [--query <query>] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--json|--jsonl]
+  {{ commandName }} {{ uri }} evidence [--query <query>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--json|--jsonl]
 
 Notes:
   - Evidence is for grounding, verification, and citation support.
-  - `--query` filters and ranks evidence with the current FTS index.
+  - `--query` filters and ranks evidence with the current search index.
+  - Add `--skip-unindexed` only with `--query` when you intentionally want to search indexed chapters and ignore uncovered chapters.
   - Without `--query`, `--reverse` reads Document Flow order backward. See `{{ commandName }} help uri`.
   - Evidence previews include nearby source context by default; use `--context 0` for exact cited ranges.
   - Source and scope URIs are not evidence targets.
@@ -96,11 +98,32 @@ Usage:
 
 Notes:
   - Run this before broad Reading Graph, Reading Summary, or Knowledge Graph work.
-  - The report includes content counts, FTS index readiness, generation coverage, retrieval guidance, recommended next commands, planning estimates, and concurrency hints.
+  - The report includes content counts, search index readiness, generation coverage, retrieval guidance, recommended next commands, planning estimates, and concurrency hints.
   - Use `--json` for a machine-readable report with the same recommendations.
 {% if libraryContext.isArchiveShortcut %}
   - This library archive shortcut inspects one managed archive's readiness; it is not a library-level health report.
 {% endif %}
+{% elif predicate == "build" and target.name == "chapter-index-artifact" %}
+Purpose:
+  Queue a job to build or replace this chapter index artifact.
+
+Usage:
+  {{ commandName }} {{ uri }} build [--json]
+
+Notes:
+  - This command enqueues work; it does not wait for the artifact to be built.
+  - A queued response means the artifact is not ready yet. Use the returned job id with `{{ commandName }} wikg://local/job/<job-id> watch` to follow progress.
+{% if "/index/fts" in uri %}
+  - FTS artifacts are local compilation work and do not call a provider.
+{% else %}
+  - Source and summary embedding artifacts require `wikg://local/config/embeddings` and may call the configured provider.
+  - Building an embedding artifact can immediately enqueue or run provider-backed work and may incur provider cost.
+{% endif %}
+  - Direct artifact build is an explicit build request; it does not use `--accept-cost`.
+{% if "/index/embedding/summary" in uri %}
+  - Summary embedding artifacts require an existing non-empty chapter summary.
+{% endif %}
+  - After artifacts change, sync the archive or library index cache before library query; archive-level query can create a missing archive cache from current artifacts on first use.
 {% elif predicate == "add" and target.name == "chapter-collection-scope" %}
 Purpose:
   Add a chapter to the archive.
@@ -115,13 +138,17 @@ Notes:
   - Source input must not be empty when `--input` is used.
 {% elif predicate == "add" and target.name == "job-collection-scope" %}
 Purpose:
-  Add a local generation job.
+  Add a local build job.
 
 Usage:
-  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task reading-graph|reading-summary|knowledge-graph --accept-cost [--depth <N>] [--boost] [--llm <json>] [--prompt <text>]
+  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task index-fts|index-embedding-source|index-embedding-summary|reading-graph|reading-summary|knowledge-graph [--accept-cost] [--depth <N>] [--boost] [--llm <json>] [--prompt <text>]
 
 Notes:
-  - Generation jobs may call an LLM provider and incur cost.
+  - `index-fts` builds chapter FTS artifacts locally and does not require `--accept-cost`.
+  - `index-embedding-source` and `index-embedding-summary` build Dense artifacts with `wikg://local/config/embeddings` and require `--accept-cost`.
+  - Reading Graph, Reading Summary, and Knowledge Graph jobs may call an LLM provider and require `--accept-cost`.
+  - Reading Graph and Knowledge Graph jobs require a current FTS artifact for the chapter.
+  - Summary embedding jobs require an existing non-empty summary.
   - Archive input adds jobs for all eligible chapters; chapter input expands to the chapter subtree by default.
   - Use `--depth <N>` with archive or chapter input to limit affected chapters. For archive input, depth is measured from the archive's root chapters; for chapter input, it is measured from the specified chapter. `--depth 0` means only the relevant root chapters or specified chapter.
   - `--llm <json>` stores a job-local LLM object; it does not update `wikg://local/config/llm`.
@@ -261,6 +288,23 @@ Notes:
   - If current output shows `"apiKey":"****"`, passing the same masked value preserves the existing secret.
   - To add or replace the secret, use `{{ commandName }} {{ uri }} put apiKey --secret`.
   - To remove the secret, use `{{ commandName }} {{ uri }} delete apiKey`.
+{% elif "/embeddings" in uri %}
+Schema:
+  {
+    "provider": "openai|openai-compatible",
+    "model": "<embedding-model-name>",
+    "baseURL": "<url>",
+    "name": "<display-name>",
+    "dimensions": 1536
+  }
+
+Notes:
+  - Allowed keys: provider, model, baseURL, name, dimensions, apiKey.
+  - `apiKey` is sensitive and cannot be set from JSON.
+  - If current output shows `"apiKey":"****"`, passing the same masked value preserves the existing secret.
+  - To add or replace the secret, use `{{ commandName }} {{ uri }} put apiKey --secret`.
+  - To remove the secret, use `{{ commandName }} {{ uri }} delete apiKey`.
+  - `dimensions` must be a positive integer and is sent only to providers/models that support dimension control.
 {% elif "/wikispine" in uri %}
 Schema:
   {
@@ -287,6 +331,10 @@ Examples:
   {{ commandName }} {{ uri }} set '{"provider":"openai","model":"gpt-4.1"}'
   {{ commandName }} {{ uri }} set --json-input '{"provider":"openai-compatible","model":"model-name"}'
   {{ commandName }} {{ uri }} set '{"provider":"google","model":"gemini-2.5-pro"}' --json
+{% elif "/embeddings" in uri %}
+  {{ commandName }} {{ uri }} set '{"provider":"openai","model":"text-embedding-3-small"}'
+  {{ commandName }} {{ uri }} set --json-input '{"provider":"openai-compatible","model":"embedding-model","baseURL":"https://api.example.com/v1"}'
+  {{ commandName }} {{ uri }} put dimensions 1536
 {% elif "/wikispine" in uri %}
   {{ commandName }} {{ uri }} set '{"provider":"fetch"}'
   {{ commandName }} {{ uri }} set '{"provider":"cli"}'
@@ -337,112 +385,50 @@ Notes:
 Notes:
   - This predicate is only available on URI targets that explicitly support clearing.
 {% endif %}
-{% elif predicate == "enable" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
+{% elif predicate == "sync" and target.name == "index-object" %}
+{% if libraryContext.isLibraryWide %}
 Purpose:
-  Build or rebuild this library's aggregate search index.
+  Sync this library index cache from registered archives' chapter index artifacts.
 
 Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
+  {{ commandName }} {{ uri }} sync [--jsonl]
 
 Notes:
-  - This is a full rebuild from registered present archives.
+  - This is a cache rebuild from artifacts already stored inside member `.wikg` archives.
+  - It does not build missing chapter artifacts and does not call an embeddings provider.
   - Missing or unreadable library archive members are skipped and reported.
   - Progress is emitted as text by default, or line-delimited events with `--jsonl`.
-  - `--json` is not supported for enable because progress is streamed.
+  - `--json` is not supported for sync because progress is streamed.
   - Library indexes are local derived state under Wiki Graph staging, not files inside the library folder.
-  - Rebuild holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `disable`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
-  - Archive writes can mark the aggregate index dirty; rebuild again before relying on library-wide query when status reports dirty or stale.
-{% else %}
-Purpose:
-  Enable searchable FTS index support for this archive on this machine.
-
-Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
-
-Notes:
-  - This initializes or repairs the local searchable index and may take time on large archives.
-  - After the index is enabled, CLI archive writes keep it synchronized automatically.
-  - Do not run this after every generation job; run it when `inspect` says query support is unavailable or the index needs repair.
-  - By default the index is stored as local cache outside the `.wikg` archive. Use `embed` when the index should travel with the archive.
-  - Enabling uses local CPU and disk only; it does not call an LLM provider.
-  - Text success output is a short status summary.
-  - With `--jsonl`, progress is emitted as line-delimited event records such as step/status/error records.
-  - After enable succeeds, `--query`, `related --query`, and `evidence --query` become available.
-{% endif %}
-{% elif predicate == "disable" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  Disable this library index and remove its current local materialization.
-
-Usage:
-  {{ commandName }} {{ uri }} disable [--json]
-
-Notes:
-  - This does not delete the library registry, metadata, folder, or managed `.wikg` archives.
-  - Library-wide object `--query` and object scope enumeration will fail until the index is enabled again.
-  - Library indexes do not support archive-style `embed` or `external` modes.
-  - Disable holds the library write lock and cannot run concurrently with membership changes or index rebuild for the same library.
-{% else %}
-Purpose:
-  Disable searchable FTS index support for this archive and remove the current index materialization.
-
-Usage:
-  {{ commandName }} {{ uri }} disable [--json]
-
-Notes:
-  - Disabling removes the current local or embedded index materialization.
-  - After disable succeeds, `--query`, `related --query`, and `evidence --query` are unavailable until `enable` or `embed` is run again.
-  - Use this when intentionally dropping index state, not as routine cleanup after generation.
-{% endif %}
-{% elif predicate == "embed" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  This library index does not support embedded archive index storage.
-
-Usage:
-  {{ commandName }} {{ uri }} enable --help
-
-Notes:
-  - Library indexes are local derived state under Wiki Graph staging.
-  - Use `enable` to build the library index or `disable` to remove it.
+  - Sync holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `clean`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
+  - Library query requires a current library index cache.
 {% else %}
 Purpose:
-  Use an archive-embedded searchable FTS index.
+  Sync this archive index cache from chapter index artifacts.
 
 Usage:
-  {{ commandName }} {{ uri }} embed [--json]
+  {{ commandName }} {{ uri }} sync [--jsonl] [--skip-unindexed]
 
 Notes:
-  - This switches the index storage policy to the `.wikg` archive and ensures the embedded index is current.
-  - After embedding, CLI archive writes keep the embedded index synchronized automatically.
-  - This makes the archive more portable, but increases archive size.
-  - Use it when distributing a `.wikg` with keyword retrieval ready for another machine.
+  - This initializes or repairs the local `index.db` cache outside the `.wikg` archive.
+  - It reads chapter index artifacts from the archive and does not call an embeddings provider.
+  - If required chapter artifacts are missing, sync reports that artifact readiness problem instead of building them.
+  - Add `--skip-unindexed` only when you intentionally want the cache to include indexed chapters and ignore uncovered chapters.
+  - Archive-level query can create a missing cache from current artifacts on first use, but explicit sync avoids the first-query delay.
+  - If query reports a missing or outdated cache, run this sync command before retrying.
+  - With `--jsonl`, progress is emitted as line-delimited event records.
 {% endif %}
-{% elif predicate == "external" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  This library index does not support archive externalization.
-
-Usage:
-  {{ commandName }} {{ uri }} enable --help
-
-Notes:
-  - Library indexes are already local derived state under Wiki Graph staging.
-  - Use `enable` to build the library index or `disable` to remove it.
-{% else %}
+{% elif predicate == "clean" and target.name == "index-object" %}
 Purpose:
-  Use external local-cache storage for the searchable FTS index.
+  Delete this index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} external [--json]
+  {{ commandName }} {{ uri }} clean [--json]
 
 Notes:
-  - This switches the index storage policy back to local cache outside the `.wikg` archive.
-  - The archive no longer carries embedded index data.
-  - Externalizing does not guarantee a current local materialization on this machine.
-  - Run `{{ commandName }} {{ uri }} enable` to build or repair local query support after switching to external storage.
-{% endif %}
+  - This removes local `index.db` cache data only.
+  - It does not delete chapter index artifacts, Knowledge Graph, Reading Graph, Summary, source text, or library membership.
+  - Archive query can recreate an archive cache from artifacts when the selected scope supports lazy cache creation.
 {% elif predicate == "clean" %}
 Purpose:
   Remove completed local generation jobs.
@@ -475,6 +461,11 @@ Purpose:
 
 Usage:
   {{ commandName }} {{ uri }} resume
+
+Notes:
+  - Paused jobs move back to queued.
+  - Queued jobs are already resumable work; `resume` leaves them queued and asks the local worker to pick up the queue.
+  - Finished, failed, canceled, and canceling jobs cannot be resumed.
 {% elif predicate == "cancel" %}
 Purpose:
   Cancel this local job.
@@ -522,6 +513,14 @@ Keys:
   - baseURL: non-empty provider base URL string
   - name: non-empty display name
   - apiKey: secret; use `--secret`
+{% elif "/embeddings" in uri %}
+Keys:
+  - provider: openai or openai-compatible
+  - model: non-empty embedding model name
+  - baseURL: non-empty provider base URL string
+  - name: non-empty display name
+  - dimensions: positive integer; numeric strings are normalized to numbers
+  - apiKey: secret; use `--secret`
 {% elif "/wikispine" in uri %}
 Keys:
   - provider: fetch or cli
@@ -535,14 +534,24 @@ Notes:
   - Positional `<value>` is stored as a string.
   - `--json-input` stores a JSON value and is useful for numeric config sections.
   - `--json` controls output shape; it is not JSON input.
-{% if "/llm" in uri %}
+{% if "/llm" in uri or "/embeddings" in uri %}
   - `--secret` reads the value from an interactive terminal without echoing it; use it for `apiKey`.
 {% endif %}
   - Success output is the full section JSON with sensitive values masked.
 {% endif %}
 {% endif %}
 {% elif predicate == "delete" %}
-{% if target.name == "metadata-object" %}
+{% if target.name == "chapter-index-artifact" %}
+Purpose:
+  Delete this chapter index artifact.
+
+Usage:
+  {{ commandName }} {{ uri }} delete [--json]
+
+Notes:
+  - This deletes the stored artifact from the `.wikg` archive.
+  - It does not clean external `index.db` cache by itself; sync or clean the archive/library index cache after deleting artifacts.
+{% elif target.name == "metadata-object" %}
 Purpose:
   Delete one metadata key.
 
@@ -584,6 +593,7 @@ Notes:
   - This does not contact an external service.
 {% else %}
   - For `llm`, this sends a small request to the configured model.
+  - For `embeddings`, this sends a small embedding request and reports the returned vector dimensions.
   - For `wikispine`, this checks the built-in fetch service or local `wikispine` command.
 {% endif %}
   - Text success output is intentionally short.
@@ -598,7 +608,7 @@ Notes:
 Library context:
   - This predicate runs through a library URI, not a standalone `.wikg` locator.
 {% if libraryContext.isLibraryWide %}
-  - Library-wide object predicates use the aggregate library index and may fail when that index is missing, dirty, or stale.
+  - Library-wide object predicates use the aggregate library index and may fail when that index is missing, stale, or not ready.
   - Interpret results with the returned archive/member provenance; cite the specific returned evidence or member.
 {% endif %}
 {% if target.name == "chapter-collection-scope" or target.name == "chapter-scope" or target.name == "chapter-source-object" or target.name == "chapter-summary-object" or target.name == "chapter-title-object" or target.name == "chapter-tree-object" or target.name == "chapter-state-object" %}
@@ -619,7 +629,7 @@ Library context:
 Related help:
   - {{ commandName }} {{ uri }} --help
   - {{ commandName }} help uri
-{% if predicate == "related" or predicate == "evidence" or predicate == "pack" or predicate == "enable" or predicate == "disable" or predicate == "embed" or predicate == "external" or target.name == "index-object" or target.name == "job-collection-scope" %}
+{% if predicate == "related" or predicate == "evidence" or predicate == "pack" or target.name == "index-object" or target.name == "chapter-index-artifact" or target.name == "job-collection-scope" %}
   - {{ commandName }} help readiness
 {% endif %}
 {% if predicate == "create" or predicate == "export" %}

package/dist/data/help/commands/root.jinja

@@ -22,7 +22,7 @@ Knowledge-base contents:
   - Reading Graph: attention chunks that preserve source-backed reading context.
   - Summaries: compressed reading outputs for chapters or archive scopes.
   - Source text: original chapter content and source ranges.
-  These structures are URI-addressed and can be retrieved efficiently with keywords.
+  These structures are URI-addressed and can be retrieved through the search index.
 
 Required first step for Agents:
   If you receive an unfamiliar archive, inspect it before querying, generating, or editing:

package/dist/data/help/commands/uri.jinja

@@ -12,7 +12,9 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates archive-level objects.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval across archive scopes.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval across archive scopes.
+  - Broad query results are bucketed by object family: chapter/title hits, graph objects, chunks, then text streams.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
 
 Use when:
   - You need the archive entry point before narrowing to chapters, chunks, entities, triples, source, or summaries.
@@ -28,7 +30,8 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates chapters.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chapter objects.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval to chapter objects.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
   - Chapter collection scope covers the full chapter tree by default; use `--depth 0` for root-level chapters only.
   - Chapter path URIs are the public CLI handles; internal chapter ids are not command targets.
 
@@ -40,7 +43,9 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates objects inside this chapter subtree.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval inside this chapter subtree.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval inside this chapter subtree.
+  - Broad query results are bucketed by object family: chapter/title hits, graph objects, chunks, then text streams.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
   - Use `--depth 0` to restrict the scope to this chapter only; `--depth 1` includes direct children.
   - The path in this URI is the public CLI handle for the chapter; internal chapter ids are not command targets.
 
@@ -52,7 +57,8 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates Reading Graph chunks.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chunks in this scope.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval to chunks in this scope.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
 {% if uriContext.isChapterQualified %}
   - This chapter-qualified scope covers the selected chapter subtree by default.
   - Use `--depth 0` for only the selected chapter, or `--depth 1` for the selected chapter plus direct children.
@@ -69,7 +75,8 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates Knowledge Graph entities.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to entities in this scope.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval to entities in this scope.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
 {% if uriContext.isChapterQualified %}
   - This chapter-qualified scope covers the selected chapter subtree by default.
   - Use `--depth 0` for only the selected chapter, or `--depth 1` for the selected chapter plus direct children.
@@ -86,7 +93,8 @@ URI type:
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates Knowledge Graph triples matching this scope or pattern.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to triples in this scope.
+  - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval to triples in this scope.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
 {% if uriContext.isChapterQualified %}
   - This chapter-qualified scope covers the selected chapter subtree by default.
   - Use `--depth 0` for only the selected chapter, or `--depth 1` for the selected chapter plus direct children.
@@ -129,6 +137,7 @@ Default behavior:
   - Summary range fragments such as `#4..8` read sentence numbers 4 through 8, inclusive.
   - Range sentence numbers are 1-based. `#1` is the first sentence; `#1..2` is the first two sentences.
   - Whole summary reads are plain text streams and do not support `--json`; summary range fragments are structured range objects and support `--json`.
+  - Summary readiness means a summary object exists and is current for the chapter source. It does not guarantee the prose answers every question about the chapter.
 
 Use when:
   - You need compact readable prose before tracing source evidence.
@@ -170,6 +179,17 @@ Default behavior:
 
 Use when:
   - You need to know whether source, Reading Graph, Reading Summary, or Knowledge Graph data exists for a chapter.
+{% elif target.name == "chapter-index-artifact" %}
+URI type:
+  Chapter index artifact object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads this chapter index artifact status and summary.
+
+Use when:
+  - You need to build or delete one chapter-level index artifact stored in the `.wikg` archive.
+  - Use `/index/fts` for lexical retrieval, `/index/embedding/source` for Dense source retrieval, or `/index/embedding/summary` for Dense summary retrieval.
+  - Build enqueues a local job; read the returned job status or watch the job before assuming the artifact is ready.
 {% elif target.name == "chunk-object" %}
 URI type:
   Chunk object
@@ -217,20 +237,21 @@ Use when:
   - You need to redirect or pipe the cover resource.
 {% elif target.name == "index-object" %}
 URI type:
-  Index object
+  Index cache object
 
 Default behavior:
-  - `{{ commandName }} {{ uri }}` reads archive FTS index status, readiness, storage policy, and materialization state.
-  - Use this page when `inspect`, `--query`, `related`, or `evidence` reports missing, stale, or unavailable index support.
+  - `{{ commandName }} {{ uri }}` reads index cache status and capabilities.
+  - Chapter-level `/index/...` URIs manage index artifacts. Archive and library `/index` URIs manage derived cache.
 
 Use when:
-  - You need to inspect currentness, enable, disable, embed, or externalize searchable FTS index support.
+  - You need to inspect, sync, or clean query cache materialization.
 {% elif target.name == "job-collection-scope" %}
 URI type:
   Local job collection scope
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` shows local generation jobs.
+  - Use `--json` for a machine-readable job list. Job list does not support `--jsonl`; `watch --jsonl` is the streaming job interface.
 
 Use when:
   - You need to inspect, add, or clean local generation jobs.
@@ -268,6 +289,7 @@ Use when:
 
 Sections:
   - `{{ commandName }} wikg://local/config/llm --help`
+  - `{{ commandName }} wikg://local/config/embeddings --help`
   - `{{ commandName }} wikg://local/config/concurrent --help`
   - `{{ commandName }} wikg://local/config/wikispine --help`
 {% elif target.name == "local-config-section" %}
@@ -279,6 +301,9 @@ Default behavior:
 
 Use when:
   - You need to read, replace, edit, clear, or test local configuration.
+{% if "/embeddings" in uri %}
+  - This section is used by Dense embedding artifact builds and Dense query embeddings.
+{% endif %}
 {% if "/wikispine" in uri %}
 
 WikiSpine runtime guide:
@@ -357,10 +382,16 @@ Predicate commands:
 {% endif %}
 {% elif predicate == "boost" %}
   - boost: move a waiting job forward. Help: {{ commandName }} {{ uri }} boost --help
+{% elif predicate == "build" %}
+  - build: build or replace this chapter index artifact. Help: {{ commandName }} {{ uri }} build --help
 {% elif predicate == "cancel" %}
   - cancel: cancel a local job. Help: {{ commandName }} {{ uri }} cancel --help
 {% elif predicate == "clean" %}
+{% if target.name == "index-object" %}
+  - clean: remove derived index cache materialization. Help: {{ commandName }} {{ uri }} clean --help
+{% else %}
   - clean: remove completed local jobs. Help: {{ commandName }} {{ uri }} clean --help
+{% endif %}
 {% elif predicate == "clear" %}
 {% if target.name == "metadata-object" %}
   - clear: clear this metadata map. Help: {{ commandName }} {{ uri }} clear --help
@@ -370,23 +401,19 @@ Predicate commands:
 {% elif predicate == "create" %}
   - create: create the archive; use `--replace` only when discarding an existing archive. Help: {{ commandName }} {{ uri }} create --help
 {% elif predicate == "delete" %}
-{% if target.name == "metadata-object" %}
+{% if target.name == "chapter-index-artifact" %}
+  - delete: delete this chapter index artifact. Help: {{ commandName }} {{ uri }} delete --help
+{% elif target.name == "metadata-object" %}
   - delete: delete one metadata key. Help: {{ commandName }} {{ uri }} delete --help
 {% else %}
   - delete: delete a config key. Help: {{ commandName }} {{ uri }} delete --help
 {% endif %}
-{% elif predicate == "disable" %}
-  - disable: disable searchable index support and remove index materialization. Help: {{ commandName }} {{ uri }} disable --help
-{% elif predicate == "embed" %}
-  - embed: use archive-embedded searchable index storage. Help: {{ commandName }} {{ uri }} embed --help
-{% elif predicate == "enable" %}
-  - enable: enable searchable index support and bring it to current. Help: {{ commandName }} {{ uri }} enable --help
 {% elif predicate == "evidence" %}
   - evidence: trace this object to source-backed evidence; supports `--reverse` without `--query`. Help: {{ commandName }} {{ uri }} evidence --help
 {% elif predicate == "export" %}
   - export: export an archive projection. Help: {{ commandName }} {{ uri }} export --help
-{% elif predicate == "external" %}
-  - external: use local-cache searchable index storage. Help: {{ commandName }} {{ uri }} external --help
+{% elif predicate == "sync" %}
+  - sync: rebuild derived index cache from chapter index artifacts. Help: {{ commandName }} {{ uri }} sync --help
 {% elif predicate == "inspect" %}
   - inspect: inspect archive readiness. Help: {{ commandName }} {{ uri }} inspect --help
 {% elif predicate == "move" %}