wiki-graph 0.4.1 → 0.6.0

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

@@ -4,7 +4,7 @@ Command: {{ commandName }} <uri> {{ predicate }}
 URI Predicate Command
 
 Target:
-  {{ uri }}
+  {{ displayUri }}
 
 Predicate:
   {{ predicate }}
@@ -14,12 +14,13 @@ Purpose:
   Expand from the current chunk or entity object to nearby objects.
 
 Usage:
-  {{ commandName }} {{ uri }} related [--query <query>] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--role <any|subject|object|self>] [--evidence [n]] [--json|--jsonl]
+  {{ commandName }} {{ uri }} related [--query <query>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--role <any|subject|object|self>] [--evidence [n]] [--json|--jsonl]
 
 Notes:
   - Chunk targets return nearby Reading Graph chunks.
   - Entity targets return Knowledge Graph triples involving the entity.
-  - `--query` filters and ranks related results with the current FTS index.
+  - `--query` filters and ranks related results with the current search index.
+  - Add `--skip-unindexed` only with `--query` when you intentionally want to search indexed chapters and ignore uncovered chapters.
   - Without `--query`, `--reverse` reads Document Flow order backward. See `{{ commandName }} help uri`.
   - `--role` only applies to entity targets.
   - Use `{{ commandName }} {{ uri }} evidence --help` when source grounding is the main goal.
@@ -28,13 +29,15 @@ Purpose:
   Trace the current object back to source-backed evidence.
 
 Usage:
-  {{ commandName }} {{ uri }} evidence [--query <query>] [--reverse] [--all] [--limit <n>] [--context <n>] [--cursor <token>] [--json|--jsonl]
+  {{ commandName }} {{ uri }} evidence [--query <query>] [--skip-unindexed] [--reverse] [--all] [--limit <n>] [--context <n>] [--json|--jsonl]
 
 Notes:
   - Evidence is for grounding, verification, and citation support.
-  - `--query` filters and ranks evidence with the current FTS index.
+  - `--query` filters and ranks evidence with the current search index.
+  - Add `--skip-unindexed` only with `--query` when you intentionally want to search indexed chapters and ignore uncovered chapters.
   - Without `--query`, `--reverse` reads Document Flow order backward. See `{{ commandName }} help uri`.
   - Evidence previews include nearby source context by default; use `--context 0` for exact cited ranges.
+  - 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:
@@ -52,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":"..."}`.
@@ -96,11 +101,32 @@ Usage:
 
 Notes:
   - Run this before broad Reading Graph, Reading Summary, or Knowledge Graph work.
-  - The report includes content counts, FTS index readiness, generation coverage, retrieval guidance, recommended next commands, planning estimates, and concurrency hints.
+  - The report includes content counts, search index readiness, generation coverage, retrieval guidance, recommended next commands, planning estimates, and concurrency hints.
   - Use `--json` for a machine-readable report with the same recommendations.
 {% if libraryContext.isArchiveShortcut %}
   - This library archive shortcut inspects one managed archive's readiness; it is not a library-level health report.
 {% endif %}
+{% elif predicate == "build" and target.name == "chapter-index-artifact" %}
+Purpose:
+  Queue a job to build or replace this chapter index artifact.
+
+Usage:
+  {{ commandName }} {{ uri }} build [--json]
+
+Notes:
+  - This command enqueues work; it does not wait for the artifact to be built.
+  - A queued response means the artifact is not ready yet. Use the returned job id with `{{ commandName }} wikg://local/job/<job-id> watch` to follow progress.
+{% if "/index/fts" in uri %}
+  - FTS artifacts are local compilation work and do not call a provider.
+{% else %}
+  - Source and summary embedding artifacts require `wikg://local/config/embeddings` and may call the configured provider.
+  - Building an embedding artifact can immediately enqueue or run provider-backed work and may incur provider cost.
+{% endif %}
+  - Direct artifact build is an explicit build request; it does not use `--accept-cost`.
+{% if "/index/embedding/summary" in uri %}
+  - Summary embedding artifacts require an existing non-empty chapter summary.
+{% endif %}
+  - After artifacts change, sync the archive or library index cache before library query; archive-level query can create a missing archive cache from current artifacts on first use.
 {% elif predicate == "add" and target.name == "chapter-collection-scope" %}
 Purpose:
   Add a chapter to the archive.
@@ -110,19 +136,31 @@ 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 generation job.
+  Add a local build job.
 
 Usage:
-  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task reading-graph|reading-summary|knowledge-graph --accept-cost [--depth <N>] [--boost] [--llm <json>] [--prompt <text>]
+  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task index-fts|index-embedding-source|index-embedding-summary|reading-graph|reading-summary|knowledge-graph [--accept-cost] [--depth <N>] [--boost] [--llm <json>] [--prompt <text>]
 
 Notes:
-  - Generation jobs may call an LLM provider and incur cost.
+  - `index-fts` builds chapter FTS artifacts locally and does not require `--accept-cost`.
+  - `index-embedding-source` and `index-embedding-summary` build Dense artifacts with `wikg://local/config/embeddings` and require `--accept-cost`.
+  - Reading Graph, Reading Summary, and Knowledge Graph jobs may call an LLM provider and require `--accept-cost`.
+  - Reading Graph and Knowledge Graph jobs require a current FTS artifact for the chapter.
+  - Summary embedding jobs require an existing non-empty summary.
   - Archive input adds jobs for all eligible chapters; chapter input expands to the chapter subtree by default.
+  - 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" %}
@@ -166,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" %}
@@ -184,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.
@@ -261,6 +294,23 @@ Notes:
   - If current output shows `"apiKey":"****"`, passing the same masked value preserves the existing secret.
   - To add or replace the secret, use `{{ commandName }} {{ uri }} put apiKey --secret`.
   - To remove the secret, use `{{ commandName }} {{ uri }} delete apiKey`.
+{% elif "/embeddings" in uri %}
+Schema:
+  {
+    "provider": "openai|openai-compatible",
+    "model": "<embedding-model-name>",
+    "baseURL": "<url>",
+    "name": "<display-name>",
+    "dimensions": 1536
+  }
+
+Notes:
+  - Allowed keys: provider, model, baseURL, name, dimensions, apiKey.
+  - `apiKey` is sensitive and cannot be set from JSON.
+  - If current output shows `"apiKey":"****"`, passing the same masked value preserves the existing secret.
+  - To add or replace the secret, use `{{ commandName }} {{ uri }} put apiKey --secret`.
+  - To remove the secret, use `{{ commandName }} {{ uri }} delete apiKey`.
+  - `dimensions` must be a positive integer and is sent only to providers/models that support dimension control.
 {% elif "/wikispine" in uri %}
 Schema:
   {
@@ -287,6 +337,10 @@ Examples:
   {{ commandName }} {{ uri }} set '{"provider":"openai","model":"gpt-4.1"}'
   {{ commandName }} {{ uri }} set --json-input '{"provider":"openai-compatible","model":"model-name"}'
   {{ commandName }} {{ uri }} set '{"provider":"google","model":"gemini-2.5-pro"}' --json
+{% elif "/embeddings" in uri %}
+  {{ commandName }} {{ uri }} set '{"provider":"openai","model":"text-embedding-3-small"}'
+  {{ commandName }} {{ uri }} set --json-input '{"provider":"openai-compatible","model":"embedding-model","baseURL":"https://api.example.com/v1"}'
+  {{ commandName }} {{ uri }} put dimensions 1536
 {% elif "/wikispine" in uri %}
   {{ commandName }} {{ uri }} set '{"provider":"fetch"}'
   {{ commandName }} {{ uri }} set '{"provider":"cli"}'
@@ -337,112 +391,50 @@ Notes:
 Notes:
   - This predicate is only available on URI targets that explicitly support clearing.
 {% endif %}
-{% elif predicate == "enable" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
+{% elif predicate == "sync" and target.name == "index-object" %}
+{% if libraryContext.isLibraryWide %}
 Purpose:
-  Build or rebuild this library's aggregate search index.
+  Sync this library index cache from registered archives' chapter index artifacts.
 
 Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
+  {{ commandName }} {{ uri }} sync [--jsonl]
 
 Notes:
-  - This is a full rebuild from registered present archives.
+  - This is a cache rebuild from artifacts already stored inside member `.wikg` archives.
+  - It does not build missing chapter artifacts and does not call an embeddings provider.
   - Missing or unreadable library archive members are skipped and reported.
   - Progress is emitted as text by default, or line-delimited events with `--jsonl`.
-  - `--json` is not supported for enable because progress is streamed.
+  - `--json` is not supported for sync because progress is streamed.
   - Library indexes are local derived state under Wiki Graph staging, not files inside the library folder.
-  - Rebuild holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `disable`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
-  - Archive writes can mark the aggregate index dirty; rebuild again before relying on library-wide query when status reports dirty or stale.
-{% else %}
-Purpose:
-  Enable searchable FTS index support for this archive on this machine.
-
-Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
-
-Notes:
-  - This initializes or repairs the local searchable index and may take time on large archives.
-  - After the index is enabled, CLI archive writes keep it synchronized automatically.
-  - Do not run this after every generation job; run it when `inspect` says query support is unavailable or the index needs repair.
-  - By default the index is stored as local cache outside the `.wikg` archive. Use `embed` when the index should travel with the archive.
-  - Enabling uses local CPU and disk only; it does not call an LLM provider.
-  - Text success output is a short status summary.
-  - With `--jsonl`, progress is emitted as line-delimited event records such as step/status/error records.
-  - After enable succeeds, `--query`, `related --query`, and `evidence --query` become available.
-{% endif %}
-{% elif predicate == "disable" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  Disable this library index and remove its current local materialization.
-
-Usage:
-  {{ commandName }} {{ uri }} disable [--json]
-
-Notes:
-  - This does not delete the library registry, metadata, folder, or managed `.wikg` archives.
-  - Library-wide object `--query` and object scope enumeration will fail until the index is enabled again.
-  - Library indexes do not support archive-style `embed` or `external` modes.
-  - Disable holds the library write lock and cannot run concurrently with membership changes or index rebuild for the same library.
-{% else %}
-Purpose:
-  Disable searchable FTS index support for this archive and remove the current index materialization.
-
-Usage:
-  {{ commandName }} {{ uri }} disable [--json]
-
-Notes:
-  - Disabling removes the current local or embedded index materialization.
-  - After disable succeeds, `--query`, `related --query`, and `evidence --query` are unavailable until `enable` or `embed` is run again.
-  - Use this when intentionally dropping index state, not as routine cleanup after generation.
-{% endif %}
-{% elif predicate == "embed" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  This library index does not support embedded archive index storage.
-
-Usage:
-  {{ commandName }} {{ uri }} enable --help
-
-Notes:
-  - Library indexes are local derived state under Wiki Graph staging.
-  - Use `enable` to build the library index or `disable` to remove it.
+  - Sync holds the library write lock; concurrent `arc scan`, `arc add`, `path set`, `clean`, archive `path set`, or archive `remove` commands for the same library cannot run at the same time.
+  - Library query requires a current library index cache.
 {% else %}
 Purpose:
-  Use an archive-embedded searchable FTS index.
+  Sync this archive index cache from chapter index artifacts.
 
 Usage:
-  {{ commandName }} {{ uri }} embed [--json]
+  {{ commandName }} {{ uri }} sync [--jsonl] [--skip-unindexed]
 
 Notes:
-  - This switches the index storage policy to the `.wikg` archive and ensures the embedded index is current.
-  - After embedding, CLI archive writes keep the embedded index synchronized automatically.
-  - This makes the archive more portable, but increases archive size.
-  - Use it when distributing a `.wikg` with keyword retrieval ready for another machine.
+  - This initializes or repairs the local `index.db` cache outside the `.wikg` archive.
+  - It reads chapter index artifacts from the archive and does not call an embeddings provider.
+  - If required chapter artifacts are missing, sync reports that artifact readiness problem instead of building them.
+  - Add `--skip-unindexed` only when you intentionally want the cache to include indexed chapters and ignore uncovered chapters.
+  - Archive-level query can create a missing cache from current artifacts on first use, but explicit sync avoids the first-query delay.
+  - If query reports a missing or outdated cache, run this sync command before retrying.
+  - With `--jsonl`, progress is emitted as line-delimited event records.
 {% endif %}
-{% elif predicate == "external" %}
-{% if target.name == "index-object" and libraryContext.isLibraryWide %}
-Purpose:
-  This library index does not support archive externalization.
-
-Usage:
-  {{ commandName }} {{ uri }} enable --help
-
-Notes:
-  - Library indexes are already local derived state under Wiki Graph staging.
-  - Use `enable` to build the library index or `disable` to remove it.
-{% else %}
+{% elif predicate == "clean" and target.name == "index-object" %}
 Purpose:
-  Use external local-cache storage for the searchable FTS index.
+  Delete this index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} external [--json]
+  {{ commandName }} {{ uri }} clean [--json]
 
 Notes:
-  - This switches the index storage policy back to local cache outside the `.wikg` archive.
-  - The archive no longer carries embedded index data.
-  - Externalizing does not guarantee a current local materialization on this machine.
-  - Run `{{ commandName }} {{ uri }} enable` to build or repair local query support after switching to external storage.
-{% endif %}
+  - This removes local `index.db` cache data only.
+  - It does not delete chapter index artifacts, Knowledge Graph, Reading Graph, Summary, source text, or library membership.
+  - Archive query can recreate an archive cache from artifacts when the selected scope supports lazy cache creation.
 {% elif predicate == "clean" %}
 Purpose:
   Remove completed local generation jobs.
@@ -475,6 +467,11 @@ Purpose:
 
 Usage:
   {{ commandName }} {{ uri }} resume
+
+Notes:
+  - Paused jobs move back to queued.
+  - Queued jobs are already resumable work; `resume` leaves them queued and asks the local worker to pick up the queue.
+  - Finished, failed, canceled, and canceling jobs cannot be resumed.
 {% elif predicate == "cancel" %}
 Purpose:
   Cancel this local job.
@@ -522,6 +519,14 @@ Keys:
   - baseURL: non-empty provider base URL string
   - name: non-empty display name
   - apiKey: secret; use `--secret`
+{% elif "/embeddings" in uri %}
+Keys:
+  - provider: openai or openai-compatible
+  - model: non-empty embedding model name
+  - baseURL: non-empty provider base URL string
+  - name: non-empty display name
+  - dimensions: positive integer; numeric strings are normalized to numbers
+  - apiKey: secret; use `--secret`
 {% elif "/wikispine" in uri %}
 Keys:
   - provider: fetch or cli
@@ -535,14 +540,24 @@ Notes:
   - Positional `<value>` is stored as a string.
   - `--json-input` stores a JSON value and is useful for numeric config sections.
   - `--json` controls output shape; it is not JSON input.
-{% if "/llm" in uri %}
+{% if "/llm" in uri or "/embeddings" in uri %}
   - `--secret` reads the value from an interactive terminal without echoing it; use it for `apiKey`.
 {% endif %}
   - Success output is the full section JSON with sensitive values masked.
 {% endif %}
 {% endif %}
 {% elif predicate == "delete" %}
-{% if target.name == "metadata-object" %}
+{% if target.name == "chapter-index-artifact" %}
+Purpose:
+  Delete this chapter index artifact.
+
+Usage:
+  {{ commandName }} {{ uri }} delete [--json]
+
+Notes:
+  - This deletes the stored artifact from the `.wikg` archive.
+  - It does not clean external `index.db` cache by itself; sync or clean the archive/library index cache after deleting artifacts.
+{% elif target.name == "metadata-object" %}
 Purpose:
   Delete one metadata key.
 
@@ -584,6 +599,7 @@ Notes:
   - This does not contact an external service.
 {% else %}
   - For `llm`, this sends a small request to the configured model.
+  - For `embeddings`, this sends a small embedding request and reports the returned vector dimensions.
   - For `wikispine`, this checks the built-in fetch service or local `wikispine` command.
 {% endif %}
   - Text success output is intentionally short.
@@ -598,7 +614,7 @@ Notes:
 Library context:
   - This predicate runs through a library URI, not a standalone `.wikg` locator.
 {% if libraryContext.isLibraryWide %}
-  - Library-wide object predicates use the aggregate library index and may fail when that index is missing, dirty, or stale.
+  - Library-wide object predicates use the aggregate library index and may fail when that index is missing, stale, or not ready.
   - Interpret results with the returned archive/member provenance; cite the specific returned evidence or member.
 {% endif %}
 {% if target.name == "chapter-collection-scope" or target.name == "chapter-scope" or target.name == "chapter-source-object" or target.name == "chapter-summary-object" or target.name == "chapter-title-object" or target.name == "chapter-tree-object" or target.name == "chapter-state-object" %}
@@ -619,12 +635,20 @@ Library context:
 Related help:
   - {{ commandName }} {{ uri }} --help
   - {{ commandName }} help uri
-{% if predicate == "related" or predicate == "evidence" or predicate == "pack" or predicate == "enable" or predicate == "disable" or predicate == "embed" or predicate == "external" or target.name == "index-object" or target.name == "job-collection-scope" %}
+{% if 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

@@ -22,7 +22,7 @@ Knowledge-base contents:
   - Reading Graph: attention chunks that preserve source-backed reading context.
   - Summaries: compressed reading outputs for chapters or archive scopes.
   - Source text: original chapter content and source ranges.
-  These structures are URI-addressed and can be retrieved efficiently with keywords.
+  These structures are URI-addressed and can be retrieved through the search index.
 
 Required first step for Agents:
   If you receive an unfamiliar archive, inspect it before querying, generating, or editing:
@@ -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.