wiki-graph 0.4.0 → 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.
-  - Library-wide `--query` and naked 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" %}
+  - 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 `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 `--query` and naked 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

@@ -121,8 +121,9 @@ Predicate commands:
 Library archive membership
 
 Default behavior:
-  - `{{ commandName }} {{ uri }}` reads the registry entry for this library archive member.
-  - The membership entry identifies the archive id, relative path, status, and containing library.
+  - `{{ commandName }} {{ uri }}` reads the archive member page for this managed archive.
+  - The member page shows the member URI, readable label or relative path, status, and business entry URIs for `/chapter`, `/entity`, `/triple`, and `inspect`.
+  - Registry fields such as physical path, size, mtime, and mutation token are diagnostic metadata.
   - `{{ commandName }} {{ uri }} inspect` checks readiness for this managed archive's contents, not the library registry.
   - Add archive object suffixes such as `/chapter`, `/entity`, or `/triple` when you want to query the archive contents.
 
@@ -152,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
@@ -165,11 +166,13 @@ Related help:
 Library scope
 
 Default behavior:
-  - `{{ commandName }} {{ uri }}` reads this library scope.
+  - `{{ commandName }} {{ uri }}` reads the library-wide scope collection.
   - Use `{{ commandName }} wikg://lib/registry` to list all library registries.
-  - `{{ commandName }} {{ uri }} --query <query>` runs a broad library index search across indexed object types.
+  - `{{ 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:
   - You need to manage a folder of `.wikg` archives as one library.
@@ -181,15 +184,16 @@ Use when:
 {% endif %}
 
 URI forms:
-  - `{{ commandName }} wikg://lib` addresses the default library.
-  - `{{ commandName }} wikg://lib/<lib-id>` addresses a non-default library.
+  - `{{ commandName }} wikg://lib` addresses the default library root scope.
+  - `{{ commandName }} wikg://lib/<lib-id>` addresses a non-default library root scope.
   - `{{ commandName }} wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
   - `{{ commandName }} wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
 
 Usage:
 {% if target.isDefault %}
-  {{ commandName }} wikg://lib
-  {{ commandName }} wikg://lib --query <query>
+  {{ 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]
@@ -202,8 +206,9 @@ Usage:
   {{ commandName }} wikg://lib/triple --query <query>
   {{ commandName }} wikg://lib/meta [--json]
 {% else %}
-  {{ commandName }} {{ uri }}
-  {{ commandName }} {{ uri }} --query <query>
+  {{ 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 `--query` and naked 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: