wiki-graph 0.8.0 → 0.8.2

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

@@ -40,10 +40,15 @@ Archive member collection
 
 Default behavior:
   - `{{ commandName }} {{ uri }}` reads the archive collection scope; use `/tree` for member file visualization.
+  - `{{ commandName }} {{ uri }} --query <query>` searches managed archive titles through the aggregate library index.
+  - Add `--query-mode hybrid|fts|embedding`; `hybrid` is the default and explicit single-index modes are strict.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed archive titles while ignoring uncovered chapters.
   - `scan` reconciles `.wikg` files; `add` copies and registers one archive.
 
 Usage:
   {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} --query <query> [--query-mode <hybrid|fts|embedding>] [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} {{ uri }} --query <query> --skip-unindexed
   {{ commandName }} {{ uri }} add --input <path> [--to <relative-wikg-path>] [--json]
   {{ commandName }} {{ uri }} scan [--json|--jsonl]
   {{ commandName }} {{ uri }}/tree [--parent <relative-path>] [--depth <n>] [--json]
@@ -194,7 +199,7 @@ URI forms:
 Usage:
 {% if target.isDefault %}
   {{ commandName }} wikg://lib [--json]
-  {{ commandName }} wikg://lib --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} wikg://lib --query <query> [--query-mode <hybrid|fts|embedding>] [--limit <n>] [--cursor <cursor>] [--json]
   {{ commandName }} wikg://lib --query <query> --skip-unindexed
   {{ commandName }} wikg://lib/chapter --query <query>
   {{ commandName }} wikg://lib/chunk --query <query>
@@ -209,7 +214,7 @@ Usage:
   {{ commandName }} wikg://lib/meta [--json]
 {% else %}
   {{ commandName }} {{ uri }} [--json]
-  {{ commandName }} {{ uri }} --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} {{ uri }} --query <query> [--query-mode <hybrid|fts|embedding>] [--limit <n>] [--cursor <cursor>] [--json]
   {{ commandName }} {{ uri }} --query <query> --skip-unindexed
   {{ commandName }} {{ uri }}/chapter --query <query>
   {{ commandName }} {{ uri }}/chunk --query <query>

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>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--role <any|subject|object|self>] [--evidence [n]] [--json|--jsonl]
+  {{ commandName }} {{ uri }} related [--query <query>] [--query-mode <hybrid|fts|embedding>] [--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 search index.
+  - `--query-mode` requires `--query`; `hybrid` is the default, while `fts` and `embedding` are strict.
   - 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.
@@ -29,11 +30,12 @@ Purpose:
   Trace the current object back to source-backed evidence.
 
 Usage:
-  {{ commandName }} {{ uri }} evidence [--query <query>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--json|--jsonl]
+  {{ commandName }} {{ uri }} evidence [--query <query>] [--query-mode <hybrid|fts|embedding>] [--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 search index.
+  - `--query-mode` requires `--query`; `hybrid` is the default, while `fts` and `embedding` are strict.
   - 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.
@@ -237,9 +239,9 @@ Usage:
 Notes:
   - The input is plain summary text from a positional value, `--input <path>`, or `--input -` for stdin.
   - This sets the summary resource directly; it does not call an LLM provider.
-{% elif target.name == "chapter-title-object" %}
+{% elif target.name == "chapter-title-object" or target.name == "archive-title-object" %}
 Purpose:
-  Replace this chapter title.
+  Replace this {% if target.name == "archive-title-object" %}archive{% else %}chapter{% endif %} title.
 
 Usage:
   {{ commandName }} {{ uri }} set <title>
@@ -392,9 +394,9 @@ Notes:
   - `set` is target-specific. Use the URI help page to find the writable child resource or supported predicate.
 {% endif %}
 {% elif predicate == "clear" %}
-{% if target.name == "chapter-title-object" %}
+{% if target.name == "chapter-title-object" or target.name == "archive-title-object" %}
 Purpose:
-  Remove this chapter's explicit title.
+  Remove this {% if target.name == "archive-title-object" %}archive's{% else %}chapter's{% endif %} explicit title.
 {% elif target.name == "metadata-object" %}
 Purpose:
   Clear this metadata map.
@@ -406,10 +408,10 @@ Purpose:
 Usage:
   {{ commandName }} {{ uri }} clear{% if target.name == "metadata-object" %} [--json]{% endif %}
 
-{% if target.name == "chapter-title-object" %}
+{% if target.name == "chapter-title-object" or target.name == "archive-title-object" %}
 Notes:
-  - Removes the explicit title for this chapter.
-  - This does not delete the chapter, source text, Reading Graph data, or summary.
+  - Removes the explicit title for this {% if target.name == "archive-title-object" %}archive{% else %}chapter{% endif %}.
+  - This does not delete the {% if target.name == "archive-title-object" %}archive.{% else %}chapter, source text, Reading Graph data, or summary.{% endif %}
 {% elif target.name == "metadata-object" %}
 Notes:
   - Clears all metadata keys for this metadata object.

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

@@ -13,6 +13,7 @@ URI type:
 Default behavior:
   - `{{ commandName }} {{ uri }}` enumerates archive-level objects.
   - `{{ commandName }} {{ uri }} --query <query>` applies search index retrieval across archive scopes.
+  - Add `--query-mode hybrid|fts|embedding`; `hybrid` is the default and explicit single-index modes are strict.
   - 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.
 
@@ -20,6 +21,7 @@ Use when:
   - You need the archive entry point before narrowing to chapters, chunks, entities, triples, source, or summaries.
 
 Common child targets:
+  - `{{ commandName }} {{ uri }}/title --help`: archive title object and title edits.
   - `{{ 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.
@@ -196,6 +198,17 @@ Default behavior:
 
 Use when:
   - You need the current title or want to set or clear it.
+{% elif target.name == "archive-title-object" %}
+URI type:
+  Archive title object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the archive title.
+  - For a managed archive, use its library archive URI with `/title`; do not expose or substitute its filesystem path.
+  - Archive title objects are searchable through archive and library scopes when their corresponding FTS index is current.
+
+Use when:
+  - You need the current title or want to set or clear it for one archive.
 {% elif target.name == "chapter-tree-object" %}
 URI type:
   Chapter tree object

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

@@ -14,6 +14,7 @@ Core model:
   - 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.
+  - Add `--query-mode hybrid|fts|embedding` to select hybrid, FTS-only, or embedding-only retrieval.
 
 Registry discovery:
   - `{{ commandName }} wikg://lib/registry add --path <folder>` prints the new non-default library URI.
@@ -51,6 +52,7 @@ Library archive shortcuts:
 
 Library-wide query:
   - `{{ commandName }} wikg://lib --query <archive-term>` searches library-wide objects through the library index.
+  - `{{ commandName }} wikg://lib/arc --query <archive-title>` searches only managed archive title objects.
   - `{{ 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.
@@ -67,7 +69,7 @@ Library index lifecycle:
   - Library indexes are local derived state under Wiki Graph staging, not files inside the library folder.
   - 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.
+  - `--query-mode hybrid` combines FTS and Dense when both exist; use `fts` or `embedding` to require one index type.
   - 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.

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

@@ -36,9 +36,9 @@ Archive index readiness:
     `{{ 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.
+    `--query-mode hybrid` is the default and uses every available compatible index with automatic fusion.
+    `--query-mode fts` requires current FTS coverage and never calls an embeddings provider.
+    `--query-mode embedding` requires current source embedding coverage and a compatible embeddings provider; it never falls back to FTS.
     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.

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

@@ -79,7 +79,7 @@ After inspect:
     Check the chapter or archive readiness before relying on summaries.
 
 Finding material:
-  `--query` uses indexed full-text retrieval. Treat it like grep/find with Google-like keyword input.
+  `--query` uses indexed retrieval and defaults to hybrid FTS + embedding search. Use `--query-mode fts` for strict keyword retrieval or `--query-mode embedding` for strict semantic retrieval.
 
   - Need document structure, chapter readiness, or chapter-local scope:
     {{ commandName }} wikg://book.wikg/chapter

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

@@ -52,6 +52,7 @@ Short and located URIs:
 Command routing:
   - `{{ commandName }} <scope-uri>` enumerates objects.
   - `{{ commandName }} <scope-uri> --query <query>` applies search index retrieval within that scope.
+  - Add `--query-mode hybrid|fts|embedding` to choose the allowed index. `hybrid` is the default.
   - `{{ commandName }} <object-uri>` reads one object.
   - `{{ commandName }} <uri> --help` explains that URI target and its supported predicates.
   - `{{ commandName }} <uri> <predicate> --help` explains a URI-bound predicate.
@@ -59,6 +60,7 @@ Command routing:
 Common command shapes:
   {{ commandName }} <scope-uri>
   {{ commandName }} <scope-uri> --query <query>
+  {{ commandName }} <scope-uri> --query <query> --query-mode fts
   {{ commandName }} <object-uri>
   {{ commandName }} <chunk-uri|entity-uri> related
   {{ commandName }} <entity|triple|chunk-uri> evidence
@@ -82,7 +84,7 @@ Scope URIs:
   Query is strict by default: every chapter in scope must have a current FTS artifact or source embedding artifact.
   Add `--skip-unindexed` only when you intentionally want to search indexed chapters and ignore uncovered chapters.
   Broad query is grouped by result type before ranking within each group. Use `/chunk`, `/entity`, or `/triple` lenses when you want one object family instead of the mixed broad result. Query an archive or chapter scope to find source or summary text, then read the returned `/source` or `/summary` object.
-  Search uses FTS-only, Dense-only, or Hybrid automatically from the current artifacts and index cache; use `{{ commandName }} help readiness` to inspect what must exist.
+  Search uses Hybrid by default. `--query-mode fts` and `--query-mode embedding` are strict and never fall back to the other index; use `{{ commandName }} help readiness` to inspect what must exist.
   Add `--depth <N>` to limit chapter subtree expansion:
     - no `--depth`: full subtree
     - `--depth 0`: only the current chapter, or root-level chapters for `<archive-uri>/chapter`
@@ -104,6 +106,7 @@ Scope URIs:
 
 Object URIs:
   Object URIs read one object by default.
+    wikg://book.wikg/title
     wikg://book.wikg/chapter/part/title
     wikg://book.wikg/chapter/part/state
     wikg://book.wikg/chapter/part/source
@@ -130,6 +133,7 @@ Triple pattern scopes:
   A complete triple URI with concrete subject, predicate, and object is an object URI.
 
 Object boundaries:
+  - An archive URI is a scope; `<archive-uri>/title` is its queryable title object.
   - `chapter/<path>` is a scope, not an object.
   - `chapter/<path>/title` is the queryable chapter title object.
   - Whole `source` and `summary` objects are readable text streams, not collection scopes.
@@ -154,6 +158,7 @@ Document Flow order:
   Document Flow order means `/chapter/tree` preorder chapter traversal, then source or summary ranges from the start of each chapter to the end.
   Use `--reverse` when you need the same flow backward, for example to find the latest source occurrence of a known object.
   `--reverse` cannot be combined with `--query`; query results use indexed match ranking instead.
+  `--query-mode` requires `--query`.
 
 Lens selection:
   - Use `<archive-uri>` when the whole archive is the right retrieval scope.