wiki-graph 0.4.0 → 0.5.0

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" %}

package/dist/data/help/topics/config.jinja

@@ -11,6 +11,12 @@ Sections:
   `wikg://local/config/llm`
     LLM provider, model, optional base URL, client name, and API key.
 
+  `wikg://local/config/embeddings`
+    Embedding provider for Dense search index vectors and Dense query vectors:
+      - `provider`: `openai` or `openai-compatible`.
+      - `model`: embedding model name.
+      - `dimensions`: optional positive integer when the provider/model supports dimension control.
+
   `wikg://local/config/concurrent`
     Local concurrency settings:
       - `job`: simultaneous generation jobs. Default: 3.
@@ -25,17 +31,21 @@ Sections:
 Operations:
   Read a section:
     {{ commandName }} wikg://local/config/llm
+    {{ commandName }} wikg://local/config/embeddings
     {{ commandName }} wikg://local/config/concurrent
     {{ commandName }} wikg://local/config/wikispine
 
   Replace a section with a JSON object:
     {{ commandName }} wikg://local/config/llm set '{"provider":"openai","model":"gpt-4.1"}'
+    {{ commandName }} wikg://local/config/embeddings set '{"provider":"openai","model":"text-embedding-3-small"}'
     {{ commandName }} wikg://local/config/concurrent set '{"job":3,"request":6}'
     {{ commandName }} wikg://local/config/wikispine set '{"provider":"fetch"}'
 
   Update one key:
     {{ commandName }} wikg://local/config/llm put provider openai
     {{ commandName }} wikg://local/config/llm put model gpt-4.1
+    {{ commandName }} wikg://local/config/embeddings put provider openai
+    {{ commandName }} wikg://local/config/embeddings put model text-embedding-3-small
     {{ commandName }} wikg://local/config/concurrent put job 3
     {{ commandName }} wikg://local/config/concurrent put request 6
     {{ commandName }} wikg://local/config/wikispine put provider cli
@@ -43,6 +53,7 @@ Operations:
 
   Store the API key:
     {{ commandName }} wikg://local/config/llm put apiKey --secret
+    {{ commandName }} wikg://local/config/embeddings put apiKey --secret
 
 Secret handling:
   - `apiKey` is read through an interactive hidden prompt.
@@ -56,6 +67,18 @@ Minimum LLM-backed operation configuration:
   - `llm.model`
   - Provider credentials when required by the selected provider.
 
+Minimum Dense embedding configuration:
+  - `embeddings.provider`
+  - `embeddings.model`
+  - `embeddings.baseURL` when using `openai-compatible`
+  - Provider credentials when required by the selected provider.
+
+Dense search notes:
+  - FTS artifact builds do not use this section.
+  - Source and summary embedding artifact builds require this section.
+  - Index cache sync does not call the embeddings provider; it uses vectors already stored in artifacts.
+  - Query uses this section when the current index cache includes Dense vectors. If Dense query embedding fails, Hybrid query can still fall back to FTS.
+
 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`.
@@ -68,6 +91,10 @@ Examples:
   {{ commandName }} wikg://local/config/llm put model gpt-4.1
   {{ commandName }} wikg://local/config/llm put apiKey --secret
   {{ commandName }} wikg://local/config/llm test
+  {{ commandName }} wikg://local/config/embeddings put provider openai
+  {{ commandName }} wikg://local/config/embeddings put model text-embedding-3-small
+  {{ commandName }} wikg://local/config/embeddings put apiKey --secret
+  {{ commandName }} wikg://local/config/embeddings test
   {{ commandName }} wikg://local/config/wikispine put provider fetch
   {{ commandName }} wikg://local/config/wikispine test
 

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

@@ -12,7 +12,8 @@ Core model:
   - The default library is addressed as `wikg://lib`.
   - A non-default library is addressed as `wikg://lib/<lib-id>`.
   - The `arc` reserved segment keeps library ids distinct from archive member ids.
-  - `{{ commandName }} wikg://lib` reads the default library scope; it does not list all library registries or archive memberships.
+  - `{{ commandName }} wikg://lib` reads the default library root scope.
+  - `{{ commandName }} wikg://lib --query <query>` searches library-wide objects through the library index.
 
 Registry discovery:
   - `{{ commandName }} wikg://lib/registry add --path <folder>` prints the new non-default library URI.
@@ -30,15 +31,16 @@ Library folders:
 Archive memberships:
   - `{{ commandName }} wikg://lib/arc scan` recursively discovers `.wikg` files under the default library folder and reconciles registry state.
   - `{{ commandName }} wikg://lib/arc add --input <path> [--to <relative-wikg-path>]` copies one `.wikg` file into the default library folder and registers it.
-  - `{{ commandName }} wikg://lib/arc/tree` shows the archive member file tree; use this instead of naked `wikg://lib` or `wikg://lib/arc` when you want to see archive members.
+  - `{{ commandName }} wikg://lib` and `{{ commandName }} wikg://lib/arc` separate the library root scope from archive membership management; use `{{ commandName }} wikg://lib/arc/tree` when you want a file tree visualization.
   - For a non-default library, replace `wikg://lib` with `wikg://lib/<lib-id>` in those `arc` commands.
   - `{{ commandName }} <library-archive-uri>/path set <relative-wikg-path>` moves or renames one managed archive inside the same folder.
   - `{{ commandName }} <library-archive-uri> remove --confirm` deletes one managed archive file and unregisters it.
   - Missing registered files remain visible as missing or stale until `arc scan`, archive `path set`, archive `remove`, or library `path set` resolves them.
 
 Library archive shortcuts:
-  - `wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
-  - `wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
+  - `wikg://lib/arc/<archive-id>/` addresses one archive member page in the default library.
+  - `wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive member page in a non-default library.
+  - The archive member page exposes the managed archive's business entry URIs (`/chapter`, `/entity`, `/triple`, and `inspect`) and keeps registry fields as diagnostic metadata.
   - Add normal archive object suffixes after the trailing slash to query that archive's contents:
     {{ commandName }} wikg://lib/arc/<archive-id>/chapter
     {{ commandName }} wikg://lib/arc/<archive-id>/entity --query "term"
@@ -48,9 +50,11 @@ Library archive shortcuts:
   - `{{ commandName }} <library-archive-uri>/entity --help` explains the archive object scope reached through that library shortcut.
 
 Library-wide query:
+  - `{{ commandName }} wikg://lib --query <archive-term>` searches library-wide objects through the library index.
   - `{{ commandName }} wikg://lib/entity --query <query>` searches across present archive members through the library index.
   - `{{ commandName }} wikg://lib/triple --query <query>` searches library-wide Knowledge Graph triples.
   - `{{ commandName }} wikg://lib/chunk --query <query>` searches library-wide Reading Graph chunks.
+  - Add `--skip-unindexed` only when you intentionally want to search indexed chapters and ignore uncovered chapters.
   - Library-wide object predicates such as `evidence`, `related`, and `pack` use the same aggregate library index.
   - Library-wide object URIs such as `wikg://lib/entity/<qid>` are aggregate views over matching objects from present archive members.
   - Evidence and related output should be interpreted with the returned archive/member provenance; cite the specific returned evidence or member, not just the library-wide URI.
@@ -58,18 +62,21 @@ Library-wide query:
 
 Library index lifecycle:
   - `{{ commandName }} <library-uri>/index` reads library index status.
-  - `{{ commandName }} <library-uri>/index enable` rebuilds the aggregate index from registered present archives.
-  - `{{ commandName }} <library-uri>/index disable` removes the local library index materialization.
+  - `{{ commandName }} <library-uri>/index sync` rebuilds the aggregate index cache from registered present archives' artifacts.
+  - `{{ commandName }} <library-uri>/index clean` removes the local library index cache.
   - Library indexes are local derived state under Wiki Graph staging, not files inside the library folder.
-  - `scan`, `add`, archive `path set`, archive `remove`, and archive writes can make the aggregate index dirty.
-  - Enable the library index again when library-wide query reports that the index is missing, dirty, or stale.
-  - Library indexes do not support archive-style `embed` or `external` modes.
+  - Sync does not build missing chapter artifacts and does not call an embeddings provider.
+  - Dense query still requires `wikg://local/config/embeddings` to embed the query text.
+  - When both FTS and Dense exist, library query combines them automatically; there is no separate query mode flag.
+  - Library membership changes can make the aggregate index stale.
+  - Managed archive writes try to sync an existing library index cache immediately; if sync cannot complete, library-wide query reports the cache as stale or not ready.
+  - Sync the library index again when library-wide query reports that the index is missing, stale, or not ready.
 
 Concurrency:
   - Library registry and membership writes hold the library write lock.
-  - `arc scan`, `arc add`, library `path set`, library archive `path set`, library archive `remove`, and library index `enable` or `disable` cannot run concurrently for the same library.
-  - Library-wide `--query`, naked scope enumeration, evidence, related, and pack commands read the current aggregate index.
-  - If a write marks the aggregate index dirty, rebuild it with `{{ commandName }} <library-uri>/index enable` before relying on library-wide query results.
+  - `arc scan`, `arc add`, library `path set`, library archive `path set`, library archive `remove`, and library index `sync` or `clean` cannot run concurrently for the same library.
+  - Library-wide object `--query`, object scope enumeration, evidence, related, and pack commands read the current aggregate index.
+  - If a write cannot resync the aggregate index, rebuild it with `{{ commandName }} <library-uri>/index sync` before relying on library-wide query results.
 
 Upgrade and cleanup:
   - Upgrade a whole library with `{{ commandName }} maintenance upgrade wikg://lib` or `{{ commandName }} maintenance upgrade wikg://lib/<lib-id>`.

package/dist/data/help/topics/readiness.jinja

@@ -10,47 +10,67 @@ Purpose:
 Start with inspect:
   {{ commandName }} <archive-uri> inspect
 
-Archive FTS readiness:
-  Archive `--query` uses that archive's FTS index. Without a current index, keyword retrieval is unavailable for archive scopes, evidence, and related results.
-
-  Default behavior:
-    `{{ commandName }} <archive-uri>/index enable` enables the searchable index as local cache outside the `.wikg` archive.
-    This keeps the archive smaller, but the index does not travel with copied archive files.
-    If another user receives the `.wikg`, they usually need to enable their own local index.
-    After an index is enabled, CLI archive writes keep it synchronized automatically.
-    Do not enable the index again after every generation job.
-
-  Portable behavior:
-    `{{ commandName }} <archive-uri>/index embed` switches to an archive-embedded searchable index and ensures it is current.
-    This makes the archive more self-contained, but increases file size.
-    After embedding, CLI archive writes keep the embedded index synchronized automatically.
-    If you are unsure, enable the local index first and embed only when distribution convenience matters.
+Archive index readiness:
+  Ordinary archive source query needs chapter index artifacts. For each content chapter, at least one of these must be current:
+  - FTS artifact: `<chapter-uri>/index/fts`
+  - Source embedding artifact: `<chapter-uri>/index/embedding/source`
+
+  Summary semantic retrieval is separate:
+  - Summary embedding artifact: `<chapter-uri>/index/embedding/summary`
+  - Summary embedding alone does not satisfy ordinary archive source query readiness.
+
+  Artifact behavior:
+    Chapter artifacts are stored inside the `.wikg` archive.
+    Build FTS artifacts with the chapter index URI or queue target `index-fts`.
+    Build source embedding artifacts with the chapter index URI or queue target `index-embedding-source`.
+    Build summary embedding artifacts with the chapter index URI or queue target `index-embedding-summary`.
+    Building embedding artifacts requires `wikg://local/config/embeddings` and may call the configured provider.
+
+  Cache behavior:
+    `{{ commandName }} <archive-uri>/index sync` builds or repairs local `index.db` cache from artifacts.
+    Sync does not build missing artifacts and does not call an embeddings provider.
+    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 `{{ commandName }} <archive-uri>/index sync`; library query always requires a current library cache.
+    `{{ commandName }} <archive-uri>/index clean` deletes only the local cache.
+
+  Query behavior:
+    FTS artifact only: FTS query.
+    Source embedding artifact only: semantic/Dense-only query.
+    Both artifacts: Hybrid query with automatic fusion.
+    Broad query is grouped by result type first: chapter/title, object, chunk, then source/summary text.
+    FTS, Dense, and Hybrid ranking affect ordering inside those result groups and evidence-backed object ranking; they do not flatten the type groups into one global rerank.
+    Missing both FTS and source embedding for any content chapter in scope: ordinary query fails.
+    Add `--skip-unindexed` to a scope query, `related --query`, or `evidence --query` only when you want to search indexed chapters and ignore uncovered chapters.
+    Results produced with `--skip-unindexed` are intentionally partial; inspect coverage before treating absent chapters as negative evidence.
+    Summary embedding artifacts are for summary semantic retrieval and are not the minimum requirement for ordinary source query.
 
   Commands:
     {{ commandName }} <archive-uri>/index
-    {{ commandName }} <archive-uri>/index enable --help
-    {{ commandName }} <archive-uri>/index disable --help
-    {{ commandName }} <archive-uri>/index embed --help
-    {{ commandName }} <archive-uri>/index external --help
+    {{ commandName }} <chapter-uri>/index/fts --help
+    {{ commandName }} <chapter-uri>/index/embedding/source --help
+    {{ commandName }} <chapter-uri>/index/embedding/summary --help
+    {{ commandName }} <archive-uri>/index sync --help
+    {{ commandName }} <archive-uri>/index clean --help
 
 Library index readiness:
-  Library-wide scopes use an aggregate library index instead of one standalone archive index.
-  Without a current library index, library-wide `--query`, evidence, related, pack, and scope enumeration may be unavailable.
+  Library-wide scopes use an aggregate library index cache built from member archives' artifacts.
+  Unlike a free archive, library query does not lazy-sync this cache. It must already be current.
 
   Default behavior:
-    `{{ commandName }} wikg://lib/index enable` rebuilds the default library index from registered present archives.
-    `{{ commandName }} wikg://lib/<lib-id>/index enable` rebuilds a non-default library index.
+    `{{ commandName }} wikg://lib/index sync` rebuilds the default library index cache from registered present archives.
+    `{{ commandName }} wikg://lib/<lib-id>/index sync` rebuilds a non-default library index cache.
     The index is local derived state under Wiki Graph staging, not a file inside the library folder.
+    Sync does not build missing chapter artifacts and does not call an embeddings provider.
 
-  Dirty behavior:
-    `scan`, `add`, archive `path set`, archive `remove`, archive writes, and membership changes can mark the aggregate index dirty.
-    Re-enable the library index when library-wide query reports that it is missing, dirty, or stale.
-    Library indexes do not support archive-style `embed` or `external` modes.
+  Stale behavior:
+    Library membership changes can make the aggregate index stale.
+    Managed archive writes try to sync an existing library index cache immediately.
+    Sync the library index when library-wide query reports that it is missing, stale, or not ready.
 
   Commands:
     {{ commandName }} wikg://lib/index
-    {{ commandName }} wikg://lib/index enable --help
-    {{ commandName }} wikg://lib/index disable --help
+    {{ commandName }} wikg://lib/index sync --help
+    {{ commandName }} wikg://lib/index clean --help
     {{ commandName }} help library
 
 Generation readiness:
@@ -82,6 +102,22 @@ LLM readiness:
     {{ commandName }} wikg://local/config/llm put apiKey --secret
     {{ commandName }} wikg://local/config/llm test
 
+Embeddings readiness:
+  `wikg://local/config/embeddings` is required for source or summary embedding artifact builds and for querying an index cache that includes Dense vectors.
+  Hybrid query can still fall back to FTS if a Dense query embedding request fails.
+
+  Minimum configuration:
+    provider
+    model
+    baseURL when using openai-compatible
+    provider credentials when required
+
+  Common path:
+    {{ commandName }} wikg://local/config/embeddings put provider openai
+    {{ commandName }} wikg://local/config/embeddings put model text-embedding-3-small
+    {{ commandName }} wikg://local/config/embeddings put apiKey --secret
+    {{ commandName }} wikg://local/config/embeddings test
+
 WikiSpine readiness:
   Knowledge Graph generation also requires WikiSpine.
   WikiSpine provides entity candidate lookup for Knowledge Graph construction.
@@ -108,13 +144,14 @@ WikiSpine readiness:
     https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
 
 How to choose:
-  - Need keyword retrieval on this machine: enable local index.
-  - Need keyword retrieval across a managed folder: enable the library index.
-  - Need to send a more self-contained `.wikg`: consider embedding the index.
-  - Need to intentionally drop query support or index materialization: disable index.
+  - Need lexical retrieval: build chapter FTS artifacts, then sync cache if you do not want lazy sync.
+  - Need semantic retrieval: configure embeddings, build source embedding artifacts, then sync cache.
+  - Need both lexical and semantic retrieval: build both FTS and source embedding artifacts, then sync the archive index cache if it already exists or query reports it outdated; query can create a missing archive cache and chooses Hybrid automatically once the cache is current.
+  - Need searchable retrieval across a managed folder: sync the library index cache.
+  - Need to intentionally drop local cache: clean index cache; artifacts remain in the archive.
   - Need generated Reading Graph or summaries: configure LLM and use local jobs.
   - Need Knowledge Graph: configure LLM and WikiSpine, then use local jobs.
-  - Not sure whether to embed index or generate missing data: keep the archive external/local first, inspect again, and decide later.
+  - Not sure what is missing: run inspect and check index artifact coverage before syncing cache.
 
 Where to go next:
   - Normal workflow:

package/dist/data/help/topics/recipe.jinja

@@ -50,15 +50,18 @@ After inspect:
     {{ commandName }} wikg:///Users/me/book.wikg --query "attention memory"
     {{ commandName }} wikg:///Users/me/book.wikg/chapter/part --query "attention"
 
-  - If inspect reports missing or unavailable index support, inspect the index target before enabling anything.
+  - If inspect reports missing index artifacts or cache, inspect the index targets before syncing cache.
     {{ commandName }} <archive-uri>/index --help
-    {{ commandName }} <archive-uri>/index enable --help
-    Read readiness before deciding whether to keep the index local or embed it:
+    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/fts --help
+    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/embedding/source --help
+    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/embedding/summary --help
+    {{ commandName }} <archive-uri>/index sync --help
+    Read readiness before deciding whether artifacts or cache are missing:
       {{ commandName }} help readiness
 
-  - If library-wide query reports a missing or dirty index, inspect the library index target and rebuild it when appropriate.
+  - If library-wide query reports a missing, stale, or not-ready index cache, inspect the library index target and sync it when appropriate.
     {{ commandName }} wikg://lib/index --help
-    {{ commandName }} wikg://lib/index enable --help
+    {{ commandName }} wikg://lib/index sync --help
     {{ commandName }} help library
 
   - If Reading Graph data is missing, chunk `--query`, related expansion, and pack may be unavailable or incomplete.
@@ -83,8 +86,8 @@ Finding material:
     {{ commandName }} wikg://book.wikg/chapter/part
 
   - Need to search across all archives in a managed library:
-    Use library-wide scopes after enabling the library index.
-      {{ commandName }} wikg://lib/index enable
+    Use library-wide scopes after syncing the library index cache.
+      {{ commandName }} wikg://lib/index sync
       {{ commandName }} wikg://lib/entity --query "attention" --evidence 2
       {{ commandName }} wikg://lib/triple --query "attention memory" --evidence 2
       {{ commandName }} wikg://lib/chunk --query "attention memory" --evidence 2
@@ -168,7 +171,7 @@ When to read deeper:
     {{ commandName }} help format
   - LLM, concurrency, and WikiSpine provider setup:
     {{ commandName }} help config
-  - FTS index, LLM, WikiSpine, and generated-data prerequisites:
+  - Search index, embeddings, LLM, WikiSpine, and generated-data prerequisites:
     {{ commandName }} help readiness
   - Library registry, membership, path binding, and aggregate index:
     {{ commandName }} help library

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

@@ -23,6 +23,8 @@ Archive locator:
 Library locators:
   - `wikg://lib` addresses the default library.
   - `wikg://lib/<lib-id>` addresses a non-default library.
+  - Naked library scopes enumerate library-wide objects; `--query` on a naked library scope searches library-wide objects through the library index.
+  - Use explicit object lenses such as `/entity`, `/triple`, `/chapter`, or `/chunk` for archive object search.
   - `wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
   - `wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
   - Add ordinary archive object suffixes after the trailing slash to query a managed archive:
@@ -46,7 +48,7 @@ Short and located URIs:
 
 Command routing:
   - `{{ commandName }} <scope-uri>` enumerates objects.
-  - `{{ commandName }} <scope-uri> --query <query>` applies keyword retrieval within that scope.
+  - `{{ commandName }} <scope-uri> --query <query>` applies search index retrieval within that scope.
   - `{{ commandName }} <object-uri>` reads one object.
   - `{{ commandName }} <uri> --help` explains that URI target and its supported predicates.
   - `{{ commandName }} <uri> <predicate> --help` explains a URI-bound predicate.
@@ -67,12 +69,16 @@ Common command shapes:
   {{ commandName }} wikg://lib/entity --query <query>
   {{ commandName }} wikg://lib/arc/<archive-id>/entity --query <query>
   {{ commandName }} wikg://local/job
-  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost
+  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <index-fts|index-embedding-source|index-embedding-summary|reading-graph|reading-summary|knowledge-graph> [--accept-cost]
   {{ commandName }} wikg://local/job/<job-id>
 
 Scope URIs:
-  Scope URIs enumerate objects by default. With `--query <query>`, they apply keyword retrieval within that scope.
+  Scope URIs enumerate objects by default. With `--query <query>`, they apply search index retrieval within that scope.
   A chapter URI used as a scope covers that chapter's full subtree by default.
+  Query is strict by default: every chapter in scope must have a current FTS artifact or source embedding artifact.
+  Add `--skip-unindexed` only when you intentionally want to search indexed chapters and ignore uncovered chapters.
+  Broad query is grouped by result type before ranking within each group. Use `/chunk`, `/entity`, or `/triple` lenses when you want one object family instead of the mixed broad result. Query an archive or chapter scope to find source or summary text, then read the returned `/source` or `/summary` object.
+  Search uses FTS-only, Dense-only, or Hybrid automatically from the current artifacts and index cache; use `{{ commandName }} help readiness` to inspect what must exist.
   Add `--depth <N>` to limit chapter subtree expansion:
     - no `--depth`: full subtree
     - `--depth 0`: only the current chapter, or root-level chapters for `<archive-uri>/chapter`
@@ -154,6 +160,7 @@ Literal source passages:
   Use `--query` on the narrowest useful scope when the task is to find source wording or passages mentioning a literal term:
     {{ commandName }} <archive-uri> --query "term"
     {{ commandName }} <archive-uri>/chapter/<path> --query "term"
+    {{ commandName }} <archive-uri> --query "term" --skip-unindexed
     {{ commandName }} <archive-uri>/chapter/<path>/source#20..30
 
 Entity-grounded evidence:
@@ -176,6 +183,8 @@ Recovery hints:
     {{ commandName }} <archive-uri>/chapter/tree
     {{ commandName }} help readiness
   - Missing generated objects: start the relevant generation job for the chapter.
+    {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task index-fts
+    {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task index-embedding-source --accept-cost
     {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
     {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-summary --accept-cost
     {{ commandName }} help readiness