wiki-graph-core 0.3.1 → 0.4.1

package/data/help/commands/uri.jinja

@@ -16,6 +16,12 @@ Default behavior:
 
 Use when:
   - You need the archive entry point before narrowing to chapters, chunks, entities, triples, source, or summaries.
+
+Common child targets:
+  - `{{ commandName }} {{ uri }}/chapter --help`: chapter tree, chapter paths, and chapter-scoped retrieval.
+  - `{{ commandName }} {{ uri }}/index --help`: archive search index status and lifecycle.
+  - `{{ commandName }} {{ uri }}/meta --help`: archive metadata.
+  - `{{ commandName }} {{ uri }}/cover --help`: raw cover resource.
 {% elif target.name == "chapter-collection-scope" %}
 URI type:
   Chapter collection scope
@@ -23,16 +29,20 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates chapters.
   - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chapter objects.
+  - 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.
 
 Use when:
-  - You need chapter ids, chapter readiness, or a starting point for chapter-scoped retrieval.
+  - You need chapter URIs, chapter readiness, or a starting point for chapter-scoped retrieval.
 {% elif target.name == "chapter-scope" %}
 URI type:
   Chapter scope
 
 Default behavior:
-  - `{{ commandName }} {{ uri }}` enumerates objects inside this chapter.
-  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval inside this chapter.
+  - `{{ commandName }} {{ uri }}` enumerates objects inside this chapter subtree.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval inside this chapter subtree.
+  - 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.
@@ -43,9 +53,16 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates Reading Graph chunks.
   - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chunks in this scope.
+{% 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.
+{% endif %}
 
 Use when:
   - You need candidate Reading Graph chunks before selecting a concrete chunk URI.
+{% if libraryContext.isLibraryWide %}
+  - Open returned chunk object URIs for `evidence`, `related`, or `pack`.
+{% endif %}
 {% elif target.name == "entity-scope" %}
 URI type:
   Entity scope
@@ -53,9 +70,16 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates Knowledge Graph entities.
   - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to entities in this scope.
+{% 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.
+{% endif %}
 
 Use when:
   - You need candidate entities before selecting a concrete entity URI.
+{% if libraryContext.isLibraryWide %}
+  - Open returned entity object URIs for `evidence`, `related`, or `pack`.
+{% endif %}
 {% elif target.name == "triple-scope" %}
 URI type:
   Triple scope
@@ -63,9 +87,16 @@ 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.
+{% 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.
+{% endif %}
 
 Use when:
   - You need relation candidates or a triple pattern such as `_` placeholders.
+{% if libraryContext.isLibraryWide %}
+  - Open returned triple object URIs for `evidence`; expand related context through the subject or object entity.
+{% endif %}
 {% elif target.name == "chapter-source-object" %}
 URI type:
   Chapter source object
@@ -78,6 +109,17 @@ Default behavior:
 
 Use when:
   - You need continuous original wording from a selected chapter.
+{% elif target.name == "chapter-source-range-object" %}
+URI type:
+  Chapter source range object
+
+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`.
+
+Use when:
+  - You need bounded original wording with machine-readable range metadata.
 {% elif target.name == "chapter-summary-object" or target.name == "summary-object" %}
 URI type:
   Summary object
@@ -90,6 +132,17 @@ Default behavior:
 
 Use when:
   - You need compact readable prose before tracing source evidence.
+{% elif target.name == "chapter-summary-range-object" %}
+URI type:
+  Summary range object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads a structured summary sentence range.
+  - Range sentence numbers are 1-based. `#1` is the first sentence; `#1..2` is the first two sentences.
+  - Summary range fragments support `--json`.
+
+Use when:
+  - You need a bounded summary excerpt with machine-readable range metadata.
 {% elif target.name == "chapter-title-object" %}
 URI type:
   Chapter title object
@@ -167,10 +220,11 @@ URI type:
   Index object
 
 Default behavior:
-  - `{{ commandName }} {{ uri }}` reads the archive FTS index policy.
+  - `{{ 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.
 
 Use when:
-  - You need to inspect, enable, disable, embed, or externalize searchable FTS index support.
+  - You need to inspect currentness, enable, disable, embed, or externalize searchable FTS index support.
 {% elif target.name == "job-collection-scope" %}
 URI type:
   Local job collection scope
@@ -180,6 +234,9 @@ Default behavior:
 
 Use when:
   - You need to inspect, add, or clean local generation jobs.
+  - Read `{{ commandName }} {{ uri }} add --help` before enqueueing work; generation jobs can consume model/runtime cost and require `--accept-cost`.
+  - Use `{{ commandName }} wikg://local/job/<job-id> watch --jsonl` for stable progress streaming.
+  - Use `{{ commandName }} help runtime` for worker, log, and local state behavior.
 {% elif target.name == "job-object" %}
 URI type:
   Local job object
@@ -198,6 +255,21 @@ Default behavior:
 
 Use when:
   - You need to change an active job target.
+{% elif target.name == "local-config-namespace" %}
+URI type:
+  Local config namespace
+
+Default behavior:
+  - `{{ commandName }} {{ uri }} --help` lists available local config sections.
+  - `{{ commandName }} {{ uri }}` is not a readable config object; operate on a child section.
+
+Use when:
+  - You need to discover configurable sections before reading or editing one.
+
+Sections:
+  - `{{ commandName }} wikg://local/config/llm --help`
+  - `{{ commandName }} wikg://local/config/concurrent --help`
+  - `{{ commandName }} wikg://local/config/wikispine --help`
 {% elif target.name == "local-config-section" %}
 URI type:
   Local config section
@@ -212,13 +284,77 @@ Use when:
 WikiSpine runtime guide:
   https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
 {% endif %}
+{% elif target.name == "metadata-object" %}
+URI type:
+  Metadata object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads metadata attached to this archive or object.
+  - Use `--json` for a stable machine-readable metadata map.
+
+Use when:
+  - You need to read, replace, edit, clear, or delete metadata without changing the underlying source or generated graph data.
+
+Input notes:
+  - `put <key> <value>` stores a string value.
+  - `put <key> --json-input <json>` stores a JSON value.
+  - `--json` controls output shape; it is not JSON input.
+{% endif %}
+
+{% if libraryContext.isLibraryUri %}
+Library context:
+  - This target is addressed through a library URI, not a standalone `.wikg` locator.
+{% if target.name == "chapter-collection-scope" or target.name == "chapter-scope" or target.name == "chapter-source-object" or target.name == "chapter-source-range-object" or target.name == "chapter-summary-object" or target.name == "chapter-summary-range-object" or target.name == "chapter-title-object" or target.name == "chapter-tree-object" or target.name == "chapter-state-object" %}
+{% if libraryContext.isLibraryWide %}
+  - Library-wide chapter URIs are read-only aggregate views over present archive members.
+{% 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 == "triple-scope" or target.name == "triple-object" %}
+{% if libraryContext.isLibraryWide %}
+  - Library-wide scopes such as `wikg://lib/triple` use the aggregate library index.
+{% endif %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/triple` query one managed archive through its membership id.
+{% if target.name == "triple-object" and libraryContext.isLibraryWide %}
+  - Library-wide triple object URIs are aggregate views over matching triples from present archive members.
+  - Interpret evidence with the returned archive/member provenance; use a library archive shortcut when you need one member only.
+{% endif %}
+{% elif target.name == "chunk-scope" or target.name == "chunk-object" %}
+{% if libraryContext.isLibraryWide %}
+  - Library-wide scopes such as `wikg://lib/chunk` use the aggregate library index.
+{% endif %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/chunk` query one managed archive through its membership id.
+{% if target.name == "chunk-object" and libraryContext.isLibraryWide %}
+  - Library-wide chunk object URIs are aggregate views over matching chunks from present archive members.
+  - Interpret related and pack output with the returned archive/member provenance; use a library archive shortcut when you need one member only.
+{% endif %}
+{% else %}
+{% if libraryContext.isLibraryWide %}
+  - Library-wide scopes such as `wikg://lib/entity` use the aggregate library index.
+{% endif %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/entity` query one managed archive through its membership id.
+{% if target.name == "entity-object" and libraryContext.isLibraryWide %}
+  - Library-wide entity object URIs are aggregate views over matching entities from present archive members.
+  - Interpret evidence, related, and pack output with the returned archive/member provenance; use a library archive shortcut when you need one member only.
+{% endif %}
+{% endif %}
+  - Read `{{ commandName }} help library` for registry, membership, path binding, and aggregate index behavior.
 {% endif %}
 
 Predicate commands:
+{% if libraryContext.isLibraryWide and (target.name == "chapter-collection-scope" or target.name == "chapter-scope" or target.name == "chapter-source-object" or target.name == "chapter-source-range-object" or target.name == "chapter-summary-object" or target.name == "chapter-summary-range-object" or target.name == "chapter-title-object" or target.name == "chapter-tree-object") %}
+  This library-wide chapter target is read-only. Use a standalone archive URI or a library archive shortcut such as `wikg://lib/arc/<archive-id>/chapter/...` for chapter maintenance.
+{% else %}
 {% if target.predicates.length %}
 {% for predicate in target.predicates %}
 {% if predicate == "add" %}
-  - add: create a child object or local job. Help: {{ commandName }} {{ uri }} add --help
+{% if target.name == "job-collection-scope" %}
+  - add: enqueue a local generation job. Help: {{ commandName }} {{ uri }} add --help
+{% elif target.name == "chapter-collection-scope" %}
+  - add: create a chapter. Help: {{ commandName }} {{ uri }} add --help
+{% else %}
+  - add: create a child object. Help: {{ commandName }} {{ uri }} add --help
+{% endif %}
 {% elif predicate == "boost" %}
   - boost: move a waiting job forward. Help: {{ commandName }} {{ uri }} boost --help
 {% elif predicate == "cancel" %}
@@ -226,11 +362,19 @@ Predicate commands:
 {% elif predicate == "clean" %}
   - clean: remove completed local jobs. Help: {{ commandName }} {{ uri }} clean --help
 {% elif predicate == "clear" %}
+{% if target.name == "metadata-object" %}
+  - clear: clear this metadata map. Help: {{ commandName }} {{ uri }} clear --help
+{% else %}
   - clear: clear a writable resource or config section. Help: {{ commandName }} {{ uri }} clear --help
+{% endif %}
 {% 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" %}
+  - 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" %}
@@ -252,7 +396,11 @@ Predicate commands:
 {% elif predicate == "pause" %}
   - pause: pause a local job. Help: {{ commandName }} {{ uri }} pause --help
 {% elif predicate == "put" %}
+{% if target.name == "metadata-object" %}
+  - put: set one metadata key. Help: {{ commandName }} {{ uri }} put --help
+{% else %}
   - put: set one config key. Help: {{ commandName }} {{ uri }} put --help
+{% endif %}
 {% elif predicate == "related" %}
   - related: expand from this object to nearby objects; supports `--reverse` without `--query`. Help: {{ commandName }} {{ uri }} related --help
 {% elif predicate == "remove" %}
@@ -262,7 +410,17 @@ Predicate commands:
 {% elif predicate == "resume" %}
   - resume: resume a local job. Help: {{ commandName }} {{ uri }} resume --help
 {% elif predicate == "set" %}
+{% if target.name == "local-config-section" %}
+  - 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
+{% else %}
+{% if target.name == "metadata-object" %}
+  - set: replace this metadata map. Help: {{ commandName }} {{ uri }} set --help
+{% else %}
   - set: modify this writable target. Help: {{ commandName }} {{ uri }} set --help
+{% endif %}
+{% endif %}
 {% elif predicate == "test" %}
   - test: test local config connectivity. Help: {{ commandName }} {{ uri }} test --help
 {% elif predicate == "watch" %}
@@ -272,3 +430,4 @@ Predicate commands:
 {% else %}
   This URI has no additional predicate commands. Use the naked URI command shown above.
 {% endif %}
+{% endif %}

package/data/help/topics/config.jinja

@@ -47,9 +47,9 @@ Operations:
 Secret handling:
   - `apiKey` is read through an interactive hidden prompt.
   - `apiKey` is masked as `****` in command output.
-  - `set --json` cannot set a real `apiKey`.
-  - `set --json` may include `"apiKey":"****"` to preserve an existing secret.
-  - Omitting `apiKey` from `set --json` removes it from the section.
+  - `set <json>` and `set --json-input <json>` cannot set a real `apiKey`.
+  - Those JSON inputs may include `"apiKey":"****"` to preserve an existing secret.
+  - Omitting `apiKey` from those JSON inputs removes it from the section.
 
 Minimum LLM-backed operation configuration:
   - `llm.provider`
@@ -74,6 +74,13 @@ Examples:
 WikiSpine:
   Knowledge Graph builds require WikiSpine. If `wikispine` is missing,
   configure one provider and run the config test before starting Knowledge Graph work.
+  - `fetch` uses the built-in service endpoint and requires network access to that service.
+  - `cli` requires a `wikispine` executable on PATH and any local runtime/data it needs.
+  - Test `cli` from the same shell that runs Wiki Graph; a different terminal or service environment may have a different PATH.
+  - If `{{ commandName }} wikg://local/config/wikispine test` fails for `cli`, check PATH first or switch to `fetch`.
+  - If the test fails for `fetch`, check network access or switch to `cli` in environments with a prepared local runtime.
+  - CLI help does not install the local WikiSpine runtime; use `fetch` unless the local runtime is already prepared.
+  - Knowledge Graph jobs should not be started until this test succeeds.
   Runtime setup and recovery guide:
     https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
 

package/data/help/topics/library.jinja

@@ -0,0 +1,90 @@
+Help Type: topic
+Topic: library
+
+Library Management
+
+Purpose:
+  Libraries let Wiki Graph manage a folder of `.wikg` archives and query them through one aggregate index.
+  Use this page to distinguish library registries, folder path binding, archive memberships, library archive shortcuts, and library index lifecycle.
+
+Core model:
+  - A library registry records one managed folder, its public id, metadata, default marker, and local staging identity.
+  - 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 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.
+  - With `--json`, create output includes the public id, URI, folder path, default marker, and staging path.
+  - Keep that emitted URI or public id in your workflow if you need to address a non-default library later.
+  - The current CLI exposes the default library as `wikg://lib` and known non-default libraries as `wikg://lib/<lib-id>`.
+  - Use `{{ commandName }} wikg://lib/registry` to list all library registries.
+
+Library folders:
+  - `{{ commandName }} wikg://lib/registry add --path <folder>` creates a non-default library registry and an empty folder.
+  - `{{ commandName }} wikg://lib/path set <existing-directory>` binds the default library to an existing folder without copying or deleting files.
+  - `{{ commandName }} wikg://lib/<lib-id>/path set <existing-directory>` binds that non-default library to an existing folder.
+  - Use `path set` after a manual move, sync restore, or mount path change.
+
+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` 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 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"
+    {{ commandName }} wikg://lib/arc/<archive-id>/triple --query "term"
+  - Run `{{ commandName }} wikg://lib/arc/<archive-id> inspect` to inspect that one managed archive's readiness; this is not a library-level health report.
+  - `{{ commandName }} <library-archive-uri> --help` explains membership actions such as `path set` and `remove`.
+  - `{{ 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.
+  - 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.
+  - To force one managed archive member, use a library archive shortcut such as `wikg://lib/arc/<archive-id>/entity/<qid>`.
+
+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.
+  - 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.
+
+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 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.
+
+Upgrade and cleanup:
+  - Upgrade a whole library with `{{ commandName }} maintenance upgrade wikg://lib` or `{{ commandName }} maintenance upgrade wikg://lib/<lib-id>`.
+  - Library archive member URIs such as `wikg://lib/arc/<archive-id>/` are not standalone upgrade targets.
+  - Runtime cleanup may remove orphaned local index staging, but it does not delete managed `.wikg` files.
+
+Where to go next:
+  - Concrete library scope and predicate commands:
+    {{ commandName }} wikg://lib --help
+  - URI grammar, library archive shortcuts, and pagination:
+    {{ commandName }} help uri
+  - Archive and library index readiness:
+    {{ commandName }} help readiness
+  - Local staging, cursor scope, and cleanup behavior:
+    {{ commandName }} help runtime

package/data/help/topics/readiness.jinja

@@ -10,8 +10,8 @@ Purpose:
 Start with inspect:
   {{ commandName }} <archive-uri> inspect
 
-FTS readiness:
-  `--query` uses the archive FTS index. Without a current index, keyword retrieval is unavailable for scopes, evidence, and related results.
+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.
@@ -33,6 +33,26 @@ FTS readiness:
     {{ commandName }} <archive-uri>/index embed --help
     {{ commandName }} <archive-uri>/index external --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.
+
+  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.
+    The index is local derived state under Wiki Graph staging, not a file inside the library folder.
+
+  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.
+
+  Commands:
+    {{ commandName }} wikg://lib/index
+    {{ commandName }} wikg://lib/index enable --help
+    {{ commandName }} wikg://lib/index disable --help
+    {{ commandName }} help library
+
 Generation readiness:
   Reading Graph, Reading Summary, and Knowledge Graph data are generated artifacts.
   They do not appear just because source text exists.
@@ -77,11 +97,19 @@ WikiSpine readiness:
     {{ commandName }} wikg://local/config/wikispine put provider cli
     {{ commandName }} wikg://local/config/wikispine test
 
+  Recovery:
+    Use `fetch` when network access to the built-in service is available.
+    Use `cli` only when a local `wikispine` executable and its runtime/data are prepared.
+    Test `cli` from the same shell that runs Wiki Graph so PATH and runtime files match the job environment.
+    CLI help does not install the local WikiSpine runtime; use the guide below when preparing a local setup.
+    If the selected provider fails its config test, fix that provider or switch providers before starting Knowledge Graph jobs.
+
   Runtime setup and recovery guide:
     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 generated Reading Graph or summaries: configure LLM and use local jobs.
@@ -97,3 +125,5 @@ Where to go next:
     {{ commandName }} help runtime
   - URI and predicate help for index/job/config targets:
     {{ commandName }} <uri> --help
+  - Library registry, membership, and aggregate index lifecycle:
+    {{ commandName }} help library

package/data/help/topics/recipe.jinja

@@ -24,6 +24,13 @@ Choose your starting point:
     Inspect before querying, generating, or editing.
       {{ commandName }} wikg://book.wikg inspect
 
+  - User gave you a folder of `.wikg` archives:
+    Bind or create a library, scan memberships, then inspect the library index before library-wide query.
+      {{ commandName }} wikg://lib/path set ./library-folder
+      {{ commandName }} wikg://lib/arc scan
+      {{ commandName }} wikg://lib/index --help
+      {{ commandName }} help library
+
   - User gave you source content and needs a reusable knowledge-base archive:
     Create an empty `.wikg` archive, or create one while importing an EPUB.
       {{ commandName }} wikg://book.wikg create
@@ -35,13 +42,13 @@ Choose your starting point:
 
   - User needs a chapter-level file:
     Read the chapter object and use Unix pipes or redirection. `/source` prints original source text; `/summary` prints the chapter summary.
-      {{ commandName }} wikg://book.wikg/chapter/3/source > chapter-3-source.md
-      {{ commandName }} wikg://book.wikg/chapter/3/summary > chapter-3-summary.md
+      {{ commandName }} wikg://book.wikg/chapter/part/source > chapter-part-source.md
+      {{ commandName }} wikg://book.wikg/chapter/part/summary > chapter-part-summary.md
 
 After inspect:
   - If the archive is ready for retrieval, use `--query` on a scope or open the URI that inspect suggests.
     {{ commandName }} wikg:///Users/me/book.wikg --query "attention memory"
-    {{ commandName }} wikg:///Users/me/book.wikg/chapter/3 --query "attention"
+    {{ 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.
     {{ commandName }} <archive-uri>/index --help
@@ -49,6 +56,11 @@ After inspect:
     Read readiness before deciding whether to keep the index local or embed it:
       {{ commandName }} help readiness
 
+  - If library-wide query reports a missing or dirty index, inspect the library index target and rebuild it when appropriate.
+    {{ commandName }} wikg://lib/index --help
+    {{ commandName }} wikg://lib/index enable --help
+    {{ commandName }} help library
+
   - If Reading Graph data is missing, chunk `--query`, related expansion, and pack may be unavailable or incomplete.
     Inspect job help before starting generated work.
       {{ commandName }} wikg://local/job --help
@@ -68,12 +80,21 @@ Finding material:
 
   - Need document structure, chapter readiness, or chapter-local scope:
     {{ commandName }} wikg://book.wikg/chapter
-    {{ commandName }} wikg://book.wikg/chapter/3
+    {{ 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
+      {{ 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
+    Use a library archive shortcut when one member archive is the right scope.
+      {{ commandName }} wikg://lib/arc/<archive-id>/entity --query "attention"
 
   - Need to understand a concept, person, place, term, or object:
     Use `--query` on entity scopes with source evidence, then ground, expand, or pack from the entity URI.
       {{ commandName }} wikg://book.wikg/entity --query "attention" --evidence 2
-      {{ commandName }} wikg://book.wikg/chapter/3/entity --query "attention" --evidence 2
+      {{ commandName }} wikg://book.wikg/chapter/part/entity --query "attention" --evidence 2
       {{ commandName }} wikg://book.wikg/entity/Q8018
       {{ commandName }} wikg://book.wikg/entity/Q8018 evidence
       {{ commandName }} wikg://book.wikg/entity/Q8018 related --query "memory"
@@ -84,7 +105,7 @@ Finding material:
   - Need to trace a relation, claim, or subject-predicate-object connection:
     Use `--query` on triple scopes with source evidence, then open or ground the triple object.
       {{ commandName }} wikg://book.wikg/triple --query "attention memory" --evidence 2
-      {{ commandName }} wikg://book.wikg/chapter/3/triple --query "attention memory" --evidence 2
+      {{ commandName }} wikg://book.wikg/chapter/part/triple --query "attention memory" --evidence 2
       {{ commandName }} wikg://book.wikg/triple/Q8018/discusses/Q123
       {{ commandName }} wikg://book.wikg/triple/Q8018/discusses/Q123 evidence
     Triple scopes can be archive-wide (`<archive-uri>/triple`) or chapter-limited (`<chapter-uri>/triple`).
@@ -94,9 +115,9 @@ Finding material:
   - Need literal source wording:
     Use `--query` on the narrowest useful scope.
       {{ commandName }} wikg:///Users/me/book.wikg --query "attention memory"
-      {{ commandName }} wikg:///Users/me/book.wikg/chapter/3 --query "attention"
-      {{ commandName }} wikg://book.wikg/chapter/3/source#20..30
-      {{ commandName }} wikg://book.wikg/chapter/3/source#23..45
+      {{ commandName }} wikg:///Users/me/book.wikg/chapter/part --query "attention"
+      {{ commandName }} wikg://book.wikg/chapter/part/source#20..30
+      {{ commandName }} wikg://book.wikg/chapter/part/source#23..45
 
   - Need the latest source evidence for a known object:
     Use `--reverse` without `--query`; read `{{ commandName }} help uri` for Document Flow order.
@@ -104,21 +125,21 @@ Finding material:
 
   - Need summary wording:
     Read summary objects or summary ranges, then verify important claims through related chunk, entity, or triple evidence.
-      {{ commandName }} wikg://book.wikg/chapter/3/summary
-      {{ commandName }} wikg://book.wikg/chapter/3/summary#23..45
-      {{ commandName }} wikg://book.wikg/chapter/3/chunk --query "attention" --evidence 2
+      {{ commandName }} wikg://book.wikg/chapter/part/summary
+      {{ commandName }} wikg://book.wikg/chapter/part/summary#23..45
+      {{ commandName }} wikg://book.wikg/chapter/part/chunk --query "attention" --evidence 2
 
   - Need Reading Graph chunks:
     Use `--query` on chunk scopes with source evidence, then open or expand from useful chunk objects.
       {{ commandName }} wikg://book.wikg/chunk --query "attention memory" --evidence 2
-      {{ commandName }} wikg://book.wikg/chapter/3/chunk --query "attention" --evidence 2
+      {{ commandName }} wikg://book.wikg/chapter/part/chunk --query "attention" --evidence 2
       {{ commandName }} wikg://book.wikg/chunk
       {{ commandName }} wikg://book.wikg/chunk/123 evidence
       {{ commandName }} wikg://book.wikg/chunk/123 related --query "attention" --evidence 2
 
   - Need quick compressed understanding before returning to source evidence:
     Read summaries, then verify important claims with evidence.
-      {{ commandName }} wikg://book.wikg/chapter/3/summary
+      {{ commandName }} wikg://book.wikg/chapter/part/summary
 
   - Need an inventory for a script or Unix pipeline:
     Use `--all --jsonl` to export the selected scope as line-delimited records, then filter with standard stream tools.
@@ -126,9 +147,9 @@ Finding material:
       {{ commandName }} wikg://book.wikg/entity --all --jsonl
       {{ commandName }} wikg://book.wikg/triple --all --jsonl
       {{ commandName }} wikg://book.wikg/chunk --all --jsonl
-      {{ commandName }} wikg://book.wikg/chapter/3/entity --all --jsonl
-      {{ commandName }} wikg://book.wikg/chapter/3/triple --all --jsonl
-      {{ commandName }} wikg://book.wikg/chapter/3/chunk --all --jsonl
+      {{ commandName }} wikg://book.wikg/chapter/part/entity --all --jsonl
+      {{ commandName }} wikg://book.wikg/chapter/part/triple --all --jsonl
+      {{ commandName }} wikg://book.wikg/chapter/part/chunk --all --jsonl
 
   - Need bounded Agent-readable context around an object:
     Use pack only after choosing a located chunk or entity URI.
@@ -137,6 +158,8 @@ Finding material:
   - Need more results from a paged response:
     Continue with the cursor returned by the previous command.
       {{ commandName }} next <cursor>
+    Add the archive or library URI when you want a cursor scope safety check.
+      {{ commandName }} next wikg://lib <cursor>
 
 When to read deeper:
   - URI details, scope/object routing, pagination, and short URI handling:
@@ -147,5 +170,7 @@ When to read deeper:
     {{ commandName }} help config
   - FTS index, LLM, WikiSpine, and generated-data prerequisites:
     {{ commandName }} help readiness
+  - Library registry, membership, path binding, and aggregate index:
+    {{ commandName }} help library
   - Workers, cache, logs, workspaces, failures, and JSONL progress:
     {{ commandName }} help runtime