wiki-graph 0.5.0 → 0.6.0

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

@@ -4,7 +4,7 @@ Command: {{ commandName }} {{ uri }} {{ predicate }}
 Library Predicate Command
 
 Target:
-  {{ uri }}
+  {{ displayUri }}
 
 Predicate:
   {{ predicate }}

package/dist/data/help/commands/maintenance/chapter/add.jinja

@@ -22,8 +22,8 @@ Behavior:
 
 Output shape:
   Prints the new chapter status.
-  The `Chapter: <uri>` line is the new chapter URI for later commands.
-  With `--json`, prints the new chapter status as one JSON object.
+  `Chapter` is the archive-relative handle; `Located URI` is the complete target for later commands.
+  With `--json`, the same values are `uri` and `locatedUri`; reuse `locatedUri` for later commands.
 
 Typical next step:
   {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost

package/dist/data/help/commands/maintenance/chapter/set-source.jinja

@@ -1,31 +1,14 @@
 Help Type: command
 Command: {{ commandName }} <chapter-uri>/source set
 
-Purpose:
-  Fill a planned chapter with normalized source text.
-
-Usage:
-  {{ commandName }} <chapter-uri>/source set [text] [--input <path|->] [--llm <json>] [--json] [--help|-h]
-
-Input:
-  - Source text is read from a positional value, `--input <path>`, or `--input -` for stdin.
-
-Preconditions:
-  - The chapter must be `planned`.
-  - To replace source on a later-stage chapter, first reset it to `planned`.
-
-Behavior:
-  - Writes normalized source text.
-  - Moves the chapter to `source`.
-  - Does not generate Reading Graph data.
-  - Does not generate or modify a summary.
-  - Does not call an LLM provider.
-  - With `--json`, prints the updated chapter status as one JSON object.
+{% set uri = "<chapter-uri>/source" %}
+{% include "help/commands/shared/chapter-source-set.jinja" %}
 
 Typical next step:
   {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
 
 See also:
+  - {{ commandName }} help file-import
   - {{ commandName }} wikg://book.wikg/chapter/part/state --help
   - {{ commandName }} wikg://book.wikg/chapter/part reset --help
   - {{ commandName }} wikg://local/job --help

package/dist/data/help/commands/maintenance/chapter.jinja

@@ -11,7 +11,7 @@ Usage:
   {{ commandName }} <chapter-uri> move (--parent <chapter-path>|--root|--before <chapter-path>|--after <chapter-path>|--first|--last) [--llm <json>] [--help|-h]
   {{ commandName }} <chapter-uri> remove [--recursive] [--llm <json>] [--help|-h]
   {{ commandName }} <chapter-uri> reset --to <planned|source|reading-graph> [--llm <json>] [--help|-h]
-  {{ commandName }} <chapter-uri>/source set [text] [--input <path|->] [--llm <json>] [--json] [--help|-h]
+  {{ commandName }} <chapter-uri>/source set (<text>|--input <path|->) [--input-format jsonl] [--llm <json>] [--json] [--help|-h]
   {{ commandName }} <chapter-uri>/summary set [text] [--input <path|->] [--llm <json>] [--json] [--help|-h]
   {{ commandName }} <chapter-uri>/title set <title> [--llm <json>] [--help|-h]
   {{ commandName }} <chapter-uri>/title clear [--llm <json>] [--help|-h]
@@ -29,7 +29,8 @@ Input rules:
   - `<chapter-uri>` includes the chapter path printed by the chapter collection or `add`.
   - `add` creates an empty planned chapter. Use this for chapter directories, groups, and drafting placeholders.
   - `add --input <path>` creates a chapter and fills it from source text; use `--input -` for stdin.
-  - `<chapter-uri>/source set` and `<chapter-uri>/summary set` read a positional value, `--input <path>`, or `--input -` for stdin.
+  - `<chapter-uri>/source set` fills a planned chapter from one positional value or `--input <path|->`; use `--input-format jsonl` for externally extracted source provenance.
+  - `<chapter-uri>/summary set` reads a positional value, `--input <path>`, or `--input -` for stdin.
   - `<chapter-uri>/title set <title>` renames a chapter in the tree; `<chapter-uri>/title clear` removes the explicit title.
   - `move` changes parent/order only; it does not edit source, graph, or summary data.
   - `tree` prints the chapter tree as JSON with `title: null` for untitled chapters.

package/dist/data/help/commands/maintenance/upgrade.jinja

@@ -9,7 +9,7 @@ Usage:
   {{ commandName }} maintenance upgrade <path.sdpub> [--output <path.wikg>] [--json]
 
 Targets:
-  - Home state: ~/.wikigraph
+  - Home state: home (or ~/.wikigraph)
   - Standalone archive: ./book.wikg, /path/to/book.wikg, wikg://book.wikg, wikg:///path/to/book.wikg
   - Legacy sdpub: ./book.sdpub, optionally with --output
   - Library: wikg://lib or wikg://lib/<lib-id>
@@ -23,7 +23,7 @@ Notes:
   - Library upgrade covers the registry and managed archive members for that library.
 
 Examples:
-  {{ commandName }} maintenance upgrade ~/.wikigraph
+  {{ commandName }} maintenance upgrade home
   {{ commandName }} maintenance upgrade ./book.wikg
   {{ commandName }} maintenance upgrade wikg://lib
   {{ commandName }} maintenance upgrade ./book.sdpub --output ./book.wikg

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

@@ -11,7 +11,7 @@ Commands:
   upgrade    Upgrade home state, a .wikg archive, a library, or migrate .sdpub.
 
 Upgrade targets:
-  {{ commandName }} maintenance upgrade ~/.wikigraph
+  {{ commandName }} maintenance upgrade home
   {{ commandName }} maintenance upgrade ./book.wikg
   {{ commandName }} maintenance upgrade wikg://book.wikg
   {{ commandName }} maintenance upgrade ./book.sdpub [--output ./book.wikg]

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

@@ -4,7 +4,7 @@ Command: {{ commandName }} <uri> {{ predicate }}
 URI Predicate Command
 
 Target:
-  {{ uri }}
+  {{ displayUri }}
 
 Predicate:
   {{ predicate }}
@@ -37,6 +37,7 @@ Notes:
   - 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.
+  - To trace an evidence passage to an imported PDF or EPUB location, move its sentence fragment to `<chapter-uri>/source/locators#<range>`; read `{{ commandName }} help source-locators`.
   - Source and scope URIs are not evidence targets.
 {% elif predicate == "pack" %}
 Purpose:
@@ -54,13 +55,15 @@ Purpose:
   Create the archive at this URI.
 
 Usage:
-  {{ commandName }} {{ uri }} create [--import <epub-path>] [--replace] [--json]
+  {{ commandName }} {{ uri }} create [--import <source-file>] [--replace] [--json]
 
 Notes:
   - Without `--import`, create an empty `.wikg` archive.
-  - `--import <epub-path>` creates the archive and imports EPUB metadata, cover, chapter tree, and source text.
-  - `create` does not read stdin; `--import` only accepts EPUB input.
-  - EPUB import runs only the import/source stage and does not call an LLM provider.
+  - `--import <source-file>` creates the archive and imports the source file's metadata, structure, and source text.
+  - File import also records source provenance so normalized source text can be traced back to the imported file.
+  - The imported file itself is not embedded in the `.wikg` archive.
+  - `create` does not read stdin. Read `{{ commandName }} help file-import` for supported source files and import boundaries.
+  - File import runs only the import/source stage and does not call an LLM provider.
   - Existing archives are not overwritten by default. Use `--replace` only when the target archive should be discarded and recreated.
   - Parent directories must already exist.
   - On success, text output is the archive object (`<archive>`). With `--json`, output is `{"uri":"..."}`.
@@ -133,9 +136,16 @@ Usage:
 
 Notes:
   - Without `--input`, creates an empty planned chapter placeholder.
-  - With `--input <path>`, creates a chapter and fills source text.
-  - Use `--input -` to read source text from stdin.
-  - Source input must not be empty when `--input` is used.
+  - With `--input <path|->`, reads non-empty UTF-8 plain text, does not infer a
+    format from the file name, and creates the chapter in the `source` stage.
+  - This plain-text path does not create a source-text map or call an LLM
+    provider. Read `{{ commandName }} help file-import` for source locators.
+  - Chapter handles are opaque and are not derived from `--title`; reuse the
+    returned `locatedUri` for later commands.
+
+Output:
+  - Text output includes `Chapter`, the archive-relative handle, and `Located URI`, the complete target for later commands.
+  - With `--json`, the same values are `uri` and `locatedUri`; reuse `locatedUri` for later commands.
 {% elif predicate == "add" and target.name == "job-collection-scope" %}
 Purpose:
   Add a local build job.
@@ -150,6 +160,7 @@ Notes:
   - 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.
+  - For archive-wide indexing, use `{{ commandName }} wikg://local/job --json` to inspect the jobs and re-run archive `inspect` to verify coverage.
   - 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`.
 {% elif predicate == "move" %}
@@ -193,9 +204,13 @@ Usage:
   {{ commandName }} {{ uri }} reset --to planned|source|reading-graph [--json]
 
 Notes:
-  - `planned` deletes source text, Reading Graph data, and summary.
-  - `source` keeps source text and deletes Reading Graph data and summary.
-  - `reading-graph` keeps source text and Reading Graph data, and deletes summary.
+  - `planned` deletes source text and provenance, Reading Graph, Knowledge Graph,
+    summary, and all chapter index artifacts.
+  - `source` keeps source text and provenance, and deletes Reading Graph,
+    Knowledge Graph, summary, and all chapter index artifacts.
+  - `reading-graph` keeps source text and provenance, Reading Graph, Knowledge
+    Graph, and the source embedding artifact. It deletes summary, FTS, and the
+    summary embedding artifact.
   - `reading-summary` and `knowledge-graph` are not supported reset targets.
   - Reset is destructive and may discard generated work.
 {% elif predicate == "set" %}
@@ -211,16 +226,7 @@ Notes:
   - Use `--input -` to read the tree JSON from stdin.
   - This rewires chapter hierarchy and order; it does not rewrite chapter source text or generated graph content.
 {% elif target.name == "chapter-source-object" %}
-Purpose:
-  Replace this chapter source text.
-
-Usage:
-  {{ commandName }} {{ uri }} set [text] [--input <path|->]
-
-Notes:
-  - Source text is read from a positional value, `--input <path>`, or `--input -` for stdin.
-  - Source replacement invalidates later generated work for that chapter.
-  - Use `{{ commandName }} {{ uri }} --help` to inspect the source object before replacing it.
+{% include "help/commands/shared/chapter-source-set.jinja" %}
 {% elif target.name == "chapter-summary-object" %}
 Purpose:
   Replace this chapter summary text.
@@ -629,12 +635,20 @@ Library context:
 Related help:
   - {{ commandName }} {{ uri }} --help
   - {{ commandName }} help uri
+{% if target.name == "chapter-source-object" and predicate == "set" %}
+  - {{ commandName }} <chapter-uri>/state --help
+  - {{ commandName }} <chapter-uri> reset --help
+  - {{ commandName }} help file-import
+{% endif %}
 {% 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" %}
   - {{ commandName }} help format
 {% endif %}
+{% if predicate == "create" %}
+  - {{ commandName }} help file-import
+{% endif %}
 {% if target.name == "job-collection-scope" or target.name == "job-object" or target.name == "job-target-object" %}
   - {{ commandName }} help runtime
 {% endif %}

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

@@ -82,9 +82,11 @@ Library entry point:
 
 Help topics:
 {% for topic in helpTopics %}
+{% if topic.rootVisible is not defined or topic.rootVisible %}
   - {{ commandName }} help {{ topic.name }}
     {{ topic.summary }}
+{% endif %}
 {% endfor %}
 
-Formats:
+Built-in formats:
   {{ formats | join(", ") }}

package/dist/data/help/commands/shared/chapter-source-set.jinja

@@ -0,0 +1,21 @@
+Purpose:
+  Fill a planned chapter with its complete source text.
+
+Usage:
+  {{ commandName }} {{ uri }} set (<text>|--input <path|->) [--input-format jsonl] [--json]
+
+Input:
+  - Supply exactly one positional value or `--input`; files and stdin are UTF-8 plain text unless `--input-format jsonl` is set. File extensions are not inferred.
+  - Source input must not be empty.
+  - Plain text writes source without a source-text map.
+  - `--input-format jsonl` writes source and provenance supplied by an external extractor. Read `{{ commandName }} help file-import` for the record contract.
+
+Preconditions:
+  - The chapter must be `planned`.
+  - Read the chapter state and reset help before discarding data from a later-stage chapter.
+
+Behavior:
+  - Initializes source for a planned chapter; it does not replace source on a later-stage chapter.
+  - Writes the complete source text and moves the chapter to `source`.
+  - Does not generate Reading Graph data or a summary, and does not call an LLM provider.
+  - With `--json`, prints the updated chapter status as one JSON object. `sourceUnits` is the number of stored source processing fragments, not the number of sentences.

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

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

package/dist/data/help/topics/file-import.jinja

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

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

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

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

@@ -21,10 +21,12 @@ Archive index readiness:
 
   Artifact behavior:
     Chapter artifacts are stored inside the `.wikg` archive.
-    Build FTS artifacts with the chapter index URI or queue target `index-fts`.
+    Build FTS artifacts locally for an archive or chapter, without provider calls:
+      {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task index-fts
     Build source embedding artifacts with the chapter index URI or queue target `index-embedding-source`.
     Build summary embedding artifacts with the chapter index URI or queue target `index-embedding-summary`.
     Building embedding artifacts requires `wikg://local/config/embeddings` and may call the configured provider.
+    Archive input creates one job per eligible chapter. Re-run inspect after the jobs finish to verify query readiness.
 
   Cache behavior:
     `{{ commandName }} <archive-uri>/index sync` builds or repairs local `index.db` cache from artifacts.

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,14 +52,12 @@ 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 index artifacts or cache, inspect the index targets before syncing cache.
-    {{ commandName }} <archive-uri>/index --help
-    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/fts --help
-    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/embedding/source --help
-    {{ commandName }} <archive-uri>/chapter/<chapter-id>/index/embedding/summary --help
-    {{ commandName }} <archive-uri>/index sync --help
-    Read readiness before deciding whether artifacts or cache are missing:
-      {{ 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, stale, or not-ready index cache, inspect the library index target and sync it when appropriate.
     {{ commandName }} wikg://lib/index --help

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
@@ -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]
@@ -90,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
@@ -105,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
@@ -127,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.