wiki-graph 0.4.1 → 0.6.0

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

@@ -10,7 +10,7 @@ Purpose:
 Operating rules:
   - Never unzip a `.wikg` archive, rewrite internal files, or bypass this CLI. Use CLI commands for archive edits.
   - Use Wiki Graph URIs as stable object handles.
-  - Use `--json` when you want stable Agent-readable fields instead of human text. Whole `source` and `summary` objects are text streams, while ranged fragments such as `/source#20..30` support `--json`.
+  - Use `--json` when you want stable Agent-readable fields instead of human text. Whole and ranged `source` and `summary` reads return `uri` and `text`.
   - If you have a URI and need valid operations, run `{{ commandName }} <uri> --help`.
   - If you need concrete predicate usage for that URI type, run `{{ commandName }} <uri> <predicate> --help`.
   - Never pass a bare filesystem path to URI-targeted commands.
@@ -32,9 +32,11 @@ Choose your starting point:
       {{ 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.
+    Create an empty archive and add UTF-8 chapter text, or create one while importing EPUB.
       {{ commandName }} wikg://book.wikg create
+      {{ commandName }} wikg://book.wikg/chapter add --title "Part" --input ./chapter.txt
       {{ commandName }} wikg://book.wikg create --import ./book.epub
+    Read `{{ commandName }} help file-import` for EPUB or source-locator JSONL.
 
   - User needs one-shot conversion without keeping an archive:
     Use transform. Source input usually requires LLM configuration.
@@ -50,15 +52,16 @@ After inspect:
     {{ commandName }} wikg:///Users/me/book.wikg --query "attention memory"
     {{ commandName }} wikg:///Users/me/book.wikg/chapter/part --query "attention"
 
-  - If inspect reports missing or unavailable index support, inspect the index target before enabling anything.
-    {{ commandName }} <archive-uri>/index --help
-    {{ commandName }} <archive-uri>/index enable --help
-    Read readiness before deciding whether to keep the index local or embed it:
-      {{ commandName }} help readiness
+  - If inspect reports query blockers, build the free local FTS artifacts, then inspect again.
+    {{ commandName }} wikg://local/job add --input <archive-uri> --task index-fts
+    {{ commandName }} <archive-uri> inspect
+    If artifacts are ready but only the local cache is missing or outdated, sync it:
+      {{ commandName }} <archive-uri>/index sync
+    Read `{{ commandName }} help readiness` for artifact and cache alternatives.
 
-  - If library-wide query reports a missing or dirty index, inspect the library index target and rebuild it when appropriate.
+  - If library-wide query reports a missing, stale, or not-ready index cache, inspect the library index target and sync it when appropriate.
     {{ commandName }} wikg://lib/index --help
-    {{ commandName }} wikg://lib/index enable --help
+    {{ commandName }} wikg://lib/index sync --help
     {{ commandName }} help library
 
   - If Reading Graph data is missing, chunk `--query`, related expansion, and pack may be unavailable or incomplete.
@@ -83,8 +86,8 @@ Finding material:
     {{ commandName }} wikg://book.wikg/chapter/part
 
   - Need to search across all archives in a managed library:
-    Use library-wide scopes after enabling the library index.
-      {{ commandName }} wikg://lib/index enable
+    Use library-wide scopes after syncing the library index cache.
+      {{ commandName }} wikg://lib/index sync
       {{ commandName }} wikg://lib/entity --query "attention" --evidence 2
       {{ commandName }} wikg://lib/triple --query "attention memory" --evidence 2
       {{ commandName }} wikg://lib/chunk --query "attention memory" --evidence 2
@@ -168,7 +171,7 @@ When to read deeper:
     {{ commandName }} help format
   - LLM, concurrency, and WikiSpine provider setup:
     {{ commandName }} help config
-  - FTS index, LLM, WikiSpine, and generated-data prerequisites:
+  - Search index, embeddings, LLM, WikiSpine, and generated-data prerequisites:
     {{ commandName }} help readiness
   - Library registry, membership, path binding, and aggregate index:
     {{ commandName }} help library

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

@@ -8,7 +8,7 @@ Purpose:
 
 Archive-first streams:
   - `{{ commandName }} <archive-uri> create` creates an empty archive; it does not read stdin.
-  - `{{ commandName }} <archive-uri> create --import <epub-path>` imports EPUB source into a new archive.
+  - `{{ commandName }} <archive-uri> create --import <source-file>` imports a source file into a new archive; read `{{ commandName }} help file-import` for the import contract.
   - `{{ commandName }} <archive-uri> export --output-format markdown|txt` can write text projections to stdout.
   - `{{ commandName }} transform --input-format markdown|txt --output-format markdown|txt` runs direct one-shot stream digest/export and usually requires LLM configuration.
   - Retrieval commands print human-readable text by default and support `--json` where documented.

package/dist/data/help/topics/source-locators.jinja

@@ -0,0 +1,45 @@
+Help Type: topic
+Topic: source-locators
+
+Source Artifacts and Locator Scope
+
+Purpose:
+  Trace a returned source passage back to the imported file location that
+  produced it.
+
+Artifact URIs:
+  - A source artifact identifies an imported PDF or EPUB by the SHA-256 digest
+    of its file bytes. Output uses its stable archive-local short UID:
+    `wikg://artifact/<short-uid>`.
+  - A short UID starts with the first 12 digest characters and lengthens only
+    when needed for uniqueness. The full digest form remains valid:
+    `wikg://artifact/<sha256-digest>`.
+  - The short UID belongs to the archive, not to one chapter. Add the archive
+    locator when opening a returned short URI. Use the full `digest` from the
+    artifact details as its content identity across archives.
+  - A fragment selects a location inside that artifact. PDF uses
+    `#page=21&bbox=left,bottom,right,top`; EPUB uses `#epubcfi(...)`.
+  - PDF pages are 1-based. Bounding boxes use normalized `[0,1]` coordinates
+    in left,bottom,right,top order with a lower-left origin.
+
+Locator scope:
+  {{ commandName }} <chapter-uri>/source/locators
+  {{ commandName }} <chapter-uri>/source/locators#4..8
+  - Source and evidence reads contain text only. Use this scope when provenance
+    details are needed.
+  - The fragment selects source sentences. Returned `range` values count Unicode
+    characters within the selected source text; both are 1-based and inclusive.
+  - Plain output is `3..13 -> <artifact-locator-uri>`. JSON and JSONL items are
+    `{"range":[3,13],"uri":"<artifact-locator-uri>"}`.
+  - Missing ranges mean those characters have no stored source locator.
+  - Use `--limit <n>` and `{{ commandName }} next <cursor>` for paging, or `--all`
+    for the complete collection.
+
+Reading details:
+  {{ commandName }} <chapter-uri>/source/locators --json
+  {{ commandName }} wikg://book.wikg/artifact/<short-uid>
+  {{ commandName }} 'wikg://book.wikg/artifact/<short-uid>#page=21&bbox=0.1,0.2,0.9,0.35'
+
+See also:
+  - {{ commandName }} help file-import
+  - {{ commandName }} help uri

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

@@ -31,6 +31,7 @@ Library locators:
     wikg://lib/arc/<archive-id>/chapter
     wikg://lib/arc/<archive-id>/entity
     wikg://lib/arc/<archive-id>/triple
+    wikg://lib/arc/<archive-id>/artifact/<sha256-digest>
   - Library-wide scopes such as `wikg://lib/entity` query the aggregate library index.
   - Read `{{ commandName }} help library` before managing registry, membership, path binding, or library index lifecycle.
 
@@ -38,6 +39,8 @@ Short and located URIs:
   Commands may return short object URIs without local file paths:
     wikg://chapter/part/title
     wikg://chapter/part/source#4..8
+    wikg://chapter/part/source/locators#4..8
+    wikg://artifact/<sha256-digest>#epubcfi(...)
     wikg://chunk/12
     wikg://entity/Q8018
     wikg://triple/Q8018/discusses/Q123
@@ -48,7 +51,7 @@ Short and located URIs:
 
 Command routing:
   - `{{ commandName }} <scope-uri>` enumerates objects.
-  - `{{ commandName }} <scope-uri> --query <query>` applies keyword retrieval within that scope.
+  - `{{ commandName }} <scope-uri> --query <query>` applies search index retrieval within that scope.
   - `{{ commandName }} <object-uri>` reads one object.
   - `{{ commandName }} <uri> --help` explains that URI target and its supported predicates.
   - `{{ commandName }} <uri> <predicate> --help` explains a URI-bound predicate.
@@ -61,7 +64,8 @@ Common command shapes:
   {{ commandName }} <entity|triple|chunk-uri> evidence
   {{ commandName }} <located-chunk-uri|located-entity-uri> pack
   {{ commandName }} next <cursor>
-  {{ commandName }} <archive-uri> create [--import <epub-path>]
+  {{ commandName }} <archive-uri> create [--import <source-file>]
+  {{ commandName }} help file-import
   {{ commandName }} <archive-uri> export --output-format <format>
   {{ commandName }} <archive-uri> inspect
   {{ commandName }} transform [options]
@@ -69,12 +73,16 @@ Common command shapes:
   {{ commandName }} wikg://lib/entity --query <query>
   {{ commandName }} wikg://lib/arc/<archive-id>/entity --query <query>
   {{ commandName }} wikg://local/job
-  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost
+  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <index-fts|index-embedding-source|index-embedding-summary|reading-graph|reading-summary|knowledge-graph> [--accept-cost]
   {{ commandName }} wikg://local/job/<job-id>
 
 Scope URIs:
-  Scope URIs enumerate objects by default. With `--query <query>`, they apply keyword retrieval within that scope.
+  Scope URIs enumerate objects by default. With `--query <query>`, they apply search index retrieval within that scope.
   A chapter URI used as a scope covers that chapter's full subtree by default.
+  Query is strict by default: every chapter in scope must have a current FTS artifact or source embedding artifact.
+  Add `--skip-unindexed` only when you intentionally want to search indexed chapters and ignore uncovered chapters.
+  Broad query is grouped by result type before ranking within each group. Use `/chunk`, `/entity`, or `/triple` lenses when you want one object family instead of the mixed broad result. Query an archive or chapter scope to find source or summary text, then read the returned `/source` or `/summary` object.
+  Search uses FTS-only, Dense-only, or Hybrid automatically from the current artifacts and index cache; use `{{ commandName }} help readiness` to inspect what must exist.
   Add `--depth <N>` to limit chapter subtree expansion:
     - no `--depth`: full subtree
     - `--depth 0`: only the current chapter, or root-level chapters for `<archive-uri>/chapter`
@@ -86,6 +94,7 @@ Scope URIs:
     wikg://book.wikg/chapter/part/chunk
     wikg://book.wikg/chapter/part/entity
     wikg://book.wikg/chapter/part/triple
+    wikg://book.wikg/chapter/part/source/locators
     wikg://book.wikg/chunk
     wikg://book.wikg/entity
     wikg://book.wikg/triple
@@ -101,6 +110,7 @@ Object URIs:
     wikg://book.wikg/chapter/part/source#4..8
     wikg://book.wikg/chapter/part/summary
     wikg://book.wikg/chapter/part/summary#4..8
+    wikg://book.wikg/artifact/<sha256-digest>
     wikg://book.wikg/chapter/part/chunk/12
     wikg://book.wikg/chapter/part/entity/Q8018
     wikg://book.wikg/chapter/part/triple/Q8018/discusses/Q123
@@ -123,10 +133,12 @@ Object boundaries:
   - `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.
+  - `<chapter-uri>/source/locators` is a collection scope. Its optional fragment selects source sentences before their locator mappings are listed.
   - Chapter-qualified scope URIs such as `<chapter-uri>/chunk`, `<chapter-uri>/entity`, and `<chapter-uri>/triple` expand to the chapter subtree and support `--depth`.
   - Chapter-qualified resource and object URIs such as `/source`, `/summary`, `/title`, `/state`, `/chunk/<id>`, `/entity/<qid>`, and complete `/triple/<subject>/<predicate>/<object>` do not expand to subtrees and do not support `--depth`.
   - `move`, `remove`, and `reset` are chapter node maintenance predicates; they target the chapter node itself, not the subtree. Use `remove --recursive` for explicit recursive deletion.
   - Ranged fragments such as `/source#4..8` and `/summary#4..8` are structured range objects.
+  - In `/source/locators#4..8`, the fragment belongs to the locator scope and selects the same source sentence range.
   - Source and summary range numbers are 1-based and inclusive. `/source#1..2` means the first two source sentences.
   - Source text is the grounding material. `evidence` is not available for source, summary, or chapter scope URIs.
   - `chunk`, `entity`, and `triple` can return source-backed evidence.
@@ -156,6 +168,7 @@ Literal source passages:
   Use `--query` on the narrowest useful scope when the task is to find source wording or passages mentioning a literal term:
     {{ commandName }} <archive-uri> --query "term"
     {{ commandName }} <archive-uri>/chapter/<path> --query "term"
+    {{ commandName }} <archive-uri> --query "term" --skip-unindexed
     {{ commandName }} <archive-uri>/chapter/<path>/source#20..30
 
 Entity-grounded evidence:
@@ -178,6 +191,8 @@ Recovery hints:
     {{ commandName }} <archive-uri>/chapter/tree
     {{ commandName }} help readiness
   - Missing generated objects: start the relevant generation job for the chapter.
+    {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task index-fts
+    {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task index-embedding-source --accept-cost
     {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
     {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-summary --accept-cost
     {{ commandName }} help readiness