wiki-graph 0.4.1 → 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 }}
@@ -106,36 +106,36 @@ Usage:
   {{ commandName }} {{ uri }} [--json]
 
 Notes:
-  - The status tells whether the library index is current, dirty, missing, or disabled.
+  - The status tells whether the library index cache is current, dirty, or missing.
   - Library-wide object `--query` and object scope enumeration require a current library index.
-  - Run `enable` when the status says the index needs to be built or rebuilt.
-{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "enable" %}
+  - Run `sync` when the status says the index cache needs to be built or rebuilt.
+{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "sync" %}
 Purpose:
-  Build or rebuild this library's aggregate search index.
+  Sync this library's aggregate index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} enable [--jsonl]
+  {{ commandName }} {{ uri }} sync [--jsonl]
 
 Notes:
-  - This is a full rebuild from registered present archives.
+  - This rebuilds cache from chapter index artifacts already stored in registered present archives.
+  - It does not build missing 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.
-{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "disable" %}
+  - 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.
+{% elif target.kind == "scope" and target.objectUri == "wikg://index" and predicate == "clean" %}
 Purpose:
-  Disable this library index and remove its current local materialization.
+  Remove this library index cache.
 
 Usage:
-  {{ commandName }} {{ uri }} disable [--json]
+  {{ commandName }} {{ uri }} clean [--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.
+  - It deletes only local derived cache under Wiki Graph staging.
+  - Library-wide object `--query` and object scope enumeration will fail until the index cache is synced again.
+  - Clean holds the library write lock and cannot run concurrently with membership changes or index sync for the same library.
 {% elif target.kind == "scope" and predicate == "add" %}
 Purpose:
   Copy a `.wikg` archive into this library folder and register it as a managed archive member.
@@ -149,7 +149,7 @@ Notes:
   - `--to` must be a relative `.wikg` path inside the library folder.
   - Parent directories for `--to` are created as needed.
   - Existing target files are not overwritten.
-  - Adding an archive marks the library index dirty.
+  - Adding an archive can make an existing library index cache stale.
   - The command holds the library write lock and cannot run concurrently with `arc scan`, library `path set`, archive path changes/removes, or index rebuild for the same library.
 {% elif target.kind == "scope" and predicate == "scan" %}
 Purpose:
@@ -162,7 +162,7 @@ Notes:
   - Scan recursively discovers `.wikg` files in the bound library folder.
   - Registered files that are no longer present remain visible as missing/stale instead of being deleted silently.
   - When a moved archive can be matched by its stable mutation token, scan preserves its archive id and updates the relative path.
-  - Scan marks the library index dirty when membership changes.
+  - Scan can make an existing library index cache stale when membership changes.
   - Scan holds the library write lock and cannot run concurrently with membership changes or index rebuild for the same library.
 {% elif target.kind == "scope" and predicate == "get" %}
 Purpose:
@@ -220,7 +220,7 @@ Notes:
   - `--confirm` is required.
   - If the registered file is already missing, the command can still clean the registry entry.
   - This does not delete empty parent directories.
-  - Removing an archive marks the library index dirty.
+  - Removing an archive can make an existing library index cache stale.
   - Remove holds the library write lock and cannot run concurrently with library scan, add, path binding, archive path changes, or index rebuild for the same library.
 {% elif target.kind == "metadata" and predicate == "set" %}
 Purpose:

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

@@ -153,12 +153,12 @@ Use when:
 
 Usage:
   {{ commandName }} {{ uri }} [--json]
-  {{ commandName }} {{ uri }} enable [--jsonl]
-  {{ commandName }} {{ uri }} disable [--json]
+  {{ commandName }} {{ uri }} sync [--jsonl]
+  {{ commandName }} {{ uri }} clean [--json]
 
 Predicate commands:
-  - enable: rebuild this library index from registered present archives. Help: {{ commandName }} {{ uri }} enable --help
-  - disable: remove this library index materialization. Help: {{ commandName }} {{ uri }} disable --help
+  - sync: rebuild this library index cache from registered present archives' artifacts. Help: {{ commandName }} {{ uri }} sync --help
+  - clean: remove this library index cache. Help: {{ commandName }} {{ uri }} clean --help
 
 Related help:
   - Library registry, membership, path binding, and aggregate index concepts: {{ commandName }} help library
@@ -169,8 +169,9 @@ Default behavior:
   - `{{ commandName }} {{ uri }}` reads the library-wide scope collection.
   - Use `{{ commandName }} wikg://lib/registry` to list all library registries.
   - `{{ commandName }} {{ uri }} --query <query>` searches library-wide objects through the library index.
+  - Query is strict by default; add `--skip-unindexed` only to intentionally search indexed chapters and ignore uncovered chapters.
   - `{{ commandName }} {{ uri }}/arc scan` reconciles membership with `.wikg` files currently under the library folder.
-  - Library-wide object scopes such as `/entity` and `/triple` query one object type through the library index after it is enabled.
+  - Library-wide object scopes such as `/entity` and `/triple` query one object type through the library index after it is synced.
   - Archive object search must use an explicit lens such as `/entity`, `/triple`, `/chapter`, or `/chunk`.
 
 Use when:
@@ -192,6 +193,7 @@ Usage:
 {% if target.isDefault %}
   {{ commandName }} wikg://lib [--json]
   {{ commandName }} wikg://lib --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} wikg://lib --query <query> --skip-unindexed
   {{ commandName }} wikg://lib/chapter --query <query>
   {{ commandName }} wikg://lib/chunk --query <query>
   {{ commandName }} wikg://lib/registry add --path <folder> [--json]
@@ -206,6 +208,7 @@ Usage:
 {% else %}
   {{ commandName }} {{ uri }} [--json]
   {{ commandName }} {{ uri }} --query <query> [--limit <n>] [--cursor <cursor>] [--json]
+  {{ commandName }} {{ uri }} --query <query> --skip-unindexed
   {{ commandName }} {{ uri }}/chapter --query <query>
   {{ commandName }} {{ uri }}/chunk --query <query>
   {{ commandName }} {{ uri }}/arc scan [--json|--jsonl]

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]