wiki-graph 0.4.1 → 0.6.0

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

@@ -4,7 +4,7 @@ Command: {{ commandName }} <uri>
 URI Command
 
 Target:
-  {{ uri }}
+  {{ displayUri }}
 
 {% if target.name == "archive-scope" %}
 URI type:
@@ -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,19 +43,28 @@ 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.
 
 Use when:
   - You already selected a chapter and want local source, summary, chunk, entity, or triple objects.
+
+Common child targets:
+  - `{{ commandName }} {{ uri }}/source --help`: normalized source text and source ranges.
+  - `{{ commandName }} {{ uri }}/summary --help`: chapter summary text and ranges.
+  - `{{ commandName }} {{ uri }}/state --help`: current stage and readiness.
+  - `{{ commandName }} {{ uri }}/title --help`: explicit chapter title.
 {% elif target.name == "chunk-scope" %}
 URI type:
   Chunk scope
 
 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 +81,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 +99,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.
@@ -97,6 +111,31 @@ Use when:
 {% if libraryContext.isLibraryWide %}
   - Open returned triple object URIs for `evidence`; expand related context through the subject or object entity.
 {% endif %}
+{% elif target.name == "artifact-object" %}
+URI type:
+  Source artifact object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the imported file identity and available metadata.
+  - An artifact fragment selects one stored PDF page box or EPUB CFI; it is not a separate object.
+
+Use when:
+  - A source passage returns an artifact locator URI and you need to inspect its source location.
+  - Read `{{ commandName }} help source-locators` for the mapping syntax.
+{% elif target.name == "chapter-source-locator-scope" %}
+URI type:
+  Source locator collection scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` lists mappings from source-text character ranges to artifact locator URIs.
+  - Add a fragment such as `#4..8` to select source sentences 4 through 8 before listing their mappings.
+  - Returned character ranges are 1-based, inclusive, and local to the selected source text.
+  - Use `--limit <n>` for a bounded page, `{{ commandName }} next <cursor>` to continue, or `--all` for the complete collection.
+  - JSON and JSONL items have the shape `{"range":[1,23],"uri":"wikg://artifact/<short-uid>#..."}`.
+
+Use when:
+  - You need to trace source text back to an imported PDF or EPUB location.
+  - Read `{{ commandName }} help source-locators` for artifact fragments and range semantics.
 {% elif target.name == "chapter-source-object" %}
 URI type:
   Chapter source object
@@ -104,11 +143,13 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` reads source text.
   - Source range fragments such as `#4..8` read sentence numbers 4 through 8, inclusive.
+  - Range fragments are read-only; `set` fills the complete source object of a planned chapter.
   - Range sentence numbers are 1-based. `#1` is the first sentence; `#1..2` is the first two sentences.
-  - Whole source reads are plain text streams and do not support `--json`; source range fragments are structured range objects and support `--json`.
+  - Whole and ranged source reads print text by default. With `--json`, they return one object containing `uri` and `text`.
 
 Use when:
   - You need continuous original wording from a selected chapter.
+  - Open `{{ commandName }} {{ uri }}/locators --help` to trace this text to an imported source file.
 {% elif target.name == "chapter-source-range-object" %}
 URI type:
   Chapter source range object
@@ -116,10 +157,12 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` reads a structured source sentence range.
   - Range sentence numbers are 1-based. `#1` is the first sentence; `#1..2` is the first two sentences.
-  - Source range fragments support `--json`.
+  - Range numbers address the current stored source revision and may change after source is reset and written again.
+  - Source range fragments support `--json`; the result contains `uri` and `text`.
 
 Use when:
   - You need bounded original wording with machine-readable range metadata.
+  - Move the fragment after `/locators`, as in `<chapter-uri>/source/locators#4..8`, to trace the selected sentences to an imported source file.
 {% elif target.name == "chapter-summary-object" or target.name == "summary-object" %}
 URI type:
   Summary object
@@ -128,7 +171,8 @@ Default behavior:
   - `{{ commandName }} {{ uri }}` reads summary text.
   - 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`.
+  - Whole and ranged summary reads print text by default. With `--json`, they return one object containing `uri` and `text`.
+  - 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 +214,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 +272,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 +324,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 +336,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:
@@ -310,6 +370,8 @@ Library context:
 {% endif %}
   - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/chapter` query or maintain one managed archive through its membership id.
   - Use a standalone archive URI or library archive shortcut for chapter maintenance writes.
+{% elif target.name == "artifact-object" %}
+  - A source artifact belongs to one archive. Use a library archive shortcut such as `wikg://lib/arc/<archive-id>/artifact/<short-uid>` to open it through library membership.
 {% elif target.name == "triple-scope" or target.name == "triple-object" %}
 {% if libraryContext.isLibraryWide %}
   - Library-wide scopes such as `wikg://lib/triple` use the aggregate library index.
@@ -357,10 +419,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 +438,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" %}
@@ -414,6 +478,8 @@ Predicate commands:
   - set: replace this local config section with a JSON object. Help: {{ commandName }} {{ uri }} set --help
 {% elif target.name == "job-target-object" %}
   - set: change this local job target. Help: {{ commandName }} {{ uri }} set --help
+{% elif target.name == "chapter-source-object" %}
+  - set: initialize source for a planned chapter. Help: {{ commandName }} {{ uri }} set --help
 {% else %}
 {% if target.name == "metadata-object" %}
   - set: replace this metadata map. Help: {{ commandName }} {{ uri }} set --help

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/file-import.jinja

@@ -0,0 +1,49 @@
+Help Type: topic
+Topic: file-import
+
+Source Files and Provenance
+
+Purpose:
+  Put source-file content into a `.wikg` archive while keeping normalized text
+  traceable to the file and location that produced it.
+
+Built-in EPUB import:
+  {{ commandName }} wikg://book.wikg create --import ./book.epub
+  - `create --import` currently accepts EPUB and creates its chapter structure,
+    source text, and source-text map.
+
+External extractor input:
+  {{ commandName }} wikg://book.wikg/chapter add --title "Part" --json
+  {{ commandName }} <locatedUri>/source set --input ./source.jsonl --input-format jsonl
+  - Use this path for PDF, or when another extractor handles EPUB.
+  - Chapter paths are returned handles, not title-derived slugs. Reuse `locatedUri`
+    from the first command; the selected chapter must be `planned`.
+
+JSONL contract:
+  - Each non-empty line is one `artifact` or `text` object. At least one of each is required.
+  - An artifact record is `{"type":"artifact","digest":"<64 hex SHA-256 of source file bytes>","mediaType":"application/pdf|application/epub+zip","name":"<optional>","identifier":"<optional>"}`.
+  - A text record is `{"type":"text","text":"...","locator":{...}}` and belongs to the most recently declared artifact.
+  - PDF locators are `{"pageIndex":1,"bbox":[left,bottom,right,top]}`; page indexes are 1-based and bbox coordinates are ordered numbers in `[0,1]`.
+  - EPUB locators are `{"cfi":"epubcfi(...)"}`.
+  - Text records are concatenated exactly in order. WG computes their Unicode character offsets; offsets are not input fields.
+
+Minimal PDF example:
+  {"type":"artifact","digest":"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef","mediaType":"application/pdf","name":"book.pdf"}
+  {"type":"text","text":"Source text\n","locator":{"pageIndex":1,"bbox":[0,0,1,1]}}
+
+Verification:
+  {{ commandName }} <chapter-uri>/source/locators --json
+  - This independent scope lists the stored source-text mappings. Read `{{ commandName }} help source-locators` for its range syntax.
+
+Boundaries:
+  - OCR, layout analysis, and format-specific extraction belong to the importer; WG consumes the contract above.
+  - WG stores normalized source text and its source-text map, not the original PDF or EPUB file.
+  - Source text remains usable without a source-text map, but evidence cannot point back to a PDF page or EPUB CFI.
+  - Source-file input does not generate Reading Graph, Summary, or Knowledge Graph
+    data.
+
+See also:
+  - {{ commandName }} wikg://book.wikg create --help
+  - {{ commandName }} <chapter-uri>/source set --help
+  - {{ commandName }} help format
+  - {{ commandName }} help source-locators

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

@@ -10,7 +10,7 @@ Managed archive format:
   wikg
 
 Archive create/import input:
-  epub via `{{ commandName }} <archive-uri> create --import <epub-path>`
+  source files via `{{ commandName }} <archive-uri> create --import <source-file>`
 
 Export formats:
   txt, markdown, epub
@@ -23,7 +23,8 @@ Inference rules:
   - File paths use their extension when the format flag is omitted.
   - Transform stdin requires an explicit `--input-format`.
   - Commands that accept content input use `--input <path>` for files and `--input -` for stdin.
-  - Archive chapter/source text commands read plain source text and do not use `--input-format`.
+  - Archive chapter/source text commands read plain source text by default; `chapter/<path>/source set` also accepts `--input-format jsonl` for source provenance input.
+  - Read `{{ commandName }} help file-import` for source-file import behavior and provenance boundaries.
   - Stdout text export requires an explicit or inferable output format.
   - `transform --stage` is only valid when creating `.wikg` from source input.
 
@@ -31,8 +32,9 @@ 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.
-  - Whole `source` and `summary` text objects are plain text streams and do not support `--json`.
-  - Ranged fragments such as `/source#20..30` and `/summary#20..30` are structured range objects and support `--json`.
+  - Whole `source` and `summary` objects print plain text by default; with `--json`, both return `uri` and `text`.
+  - `<chapter-uri>/source/locators` is a paged collection whose JSON and JSONL items contain `range` and artifact locator `uri`.
+  - Ranged fragments such as `/source#20..30` and `/summary#20..30` use the same output choices and retain the requested range in `uri`.
   - Source and summary range numbers are 1-based and inclusive.
   - Commands that do not support `--json` or `--jsonl` say so in their command help or error message.
 

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

@@ -54,6 +54,7 @@ Library-wide query:
   - `{{ 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.
@@ -61,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.
+  - `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 marks the aggregate index dirty, rebuild it with `{{ commandName }} <library-uri>/index enable` before relying on library-wide query results.
+  - 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,69 @@ 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 locally for an archive or chapter, without provider calls:
+      {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task 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.
+    Archive input creates one job per eligible chapter. Re-run inspect after the jobs finish to verify query readiness.
+
+  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 +104,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 +146,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: