wiki-graph-core 0.3.1 → 0.4.1

package/data/help/commands/predicate.jinja

@@ -98,6 +98,9 @@ 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.
   - 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 == "add" and target.name == "chapter-collection-scope" %}
 Purpose:
   Add a chapter to the archive.
@@ -115,30 +118,59 @@ Purpose:
   Add a local generation job.
 
 Usage:
-  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task reading-graph|reading-summary|knowledge-graph --accept-cost [--boost] [--llm <json>] [--prompt <text>]
+  {{ commandName }} {{ uri }} add --input <archive-uri|chapter-uri> --task 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.
-  - Archive input adds jobs for all eligible chapters; chapter input adds one job.
+  - Archive input adds jobs for all eligible chapters; chapter input expands to the chapter subtree by default.
+  - 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" %}
 Purpose:
   Move this chapter in the chapter tree.
 
 Usage:
-  {{ commandName }} {{ uri }} move [--parent <chapter-uri>] [--after <chapter-uri>] [--before <chapter-uri>]
+  {{ commandName }} {{ uri }} move --parent <chapter-uri> [--first|--last] [--json]
+  {{ commandName }} {{ uri }} move --root [--first|--last] [--json]
+  {{ commandName }} {{ uri }} move --before <chapter-uri> [--json]
+  {{ commandName }} {{ uri }} move --after <chapter-uri> [--json]
+  {{ commandName }} {{ uri }} move --first [--json]
+  {{ commandName }} {{ uri }} move --last [--json]
+
+Notes:
+  - Moves only the chapter tree node. Source text, Reading Graph data, and summary stay attached to the same internal chapter record.
+  - `--parent <chapter-uri>` moves the chapter under another chapter.
+  - `--root` moves the chapter to the top level.
+  - `--before <chapter-uri>` or `--after <chapter-uri>` moves the chapter next to the target chapter.
+  - `--first` or `--last` moves within the target parent when combined with `--parent` or `--root`.
+  - Without `--parent` or `--root`, `--first` and `--last` reorder within the current parent.
+  - Cannot move a chapter into or next to its own descendant.
 {% elif predicate == "remove" %}
 Purpose:
   Remove this chapter.
 
 Usage:
-  {{ commandName }} {{ uri }} remove [--confirm]
+  {{ commandName }} {{ uri }} remove [--recursive] [--json]
+
+Notes:
+  - Removes the target chapter from the TOC tree.
+  - Removes that chapter's source text, Reading Graph data, and summary.
+  - Fails when the chapter has children unless `--recursive` is provided.
+  - With `--recursive`, removes the whole selected subtree and its stored data.
+  - This is a destructive in-place edit. Read the chapter tree first when the archive is important.
 {% elif predicate == "reset" %}
 Purpose:
   Delete later-stage artifacts for this chapter.
 
 Usage:
-  {{ commandName }} {{ uri }} reset --to source|reading-graph|reading-summary|knowledge-graph [--confirm]
+  {{ 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.
+  - `reading-summary` and `knowledge-graph` are not supported reset targets.
+  - Reset is destructive and may discard generated work.
 {% elif predicate == "set" %}
 {% if target.name == "chapter-tree-object" %}
 Purpose:
@@ -191,6 +223,21 @@ Usage:
 Notes:
   - This changes what the job will generate when resumed or picked up by a worker.
   - Use `{{ commandName }} {{ uri }} --help` to inspect the current job target first.
+{% elif target.name == "metadata-object" %}
+Purpose:
+  Replace this metadata map with a JSON object.
+
+Usage:
+  {{ commandName }} {{ uri }} set <json> [--json]
+  {{ commandName }} {{ uri }} set --input <path|-> [--json]
+  {{ commandName }} {{ uri }} set --json-input <json> [--json]
+
+Notes:
+  - Metadata shape depends on whether this is archive metadata or object metadata.
+  - `--json-input <json>` reads an inline JSON object.
+  - `--input <path|->` reads a JSON object from a file or stdin.
+  - `--json` controls output shape; it is not JSON input.
+  - `put`, `delete`, and `clear` are usually safer for single-key metadata edits.
 {% elif target.name == "local-config-section" %}
 Purpose:
   Replace this entire local config section with a JSON object.
@@ -247,19 +294,6 @@ Examples:
   {{ commandName }} {{ uri }} set '{"job":3,"request":6}'
   {{ commandName }} {{ uri }} set --json-input '{"job":2,"request":4}'
 {% endif %}
-{% elif "/meta" in uri %}
-Purpose:
-  Replace this metadata object from a JSON object or input value.
-
-Usage:
-  {{ commandName }} {{ uri }} set <json> [--json]
-  {{ commandName }} {{ uri }} set --input <path|-> [--json]
-  {{ commandName }} {{ uri }} set --json-input <json> [--json]
-
-Notes:
-  - Metadata shape depends on whether this is archive metadata or object metadata.
-  - Use `--input -` when metadata JSON should come from stdin.
-  - `put`, `delete`, and `clear` are usually safer for single-key metadata edits.
 {% else %}
 Purpose:
   This URI target has no generic `set` behavior.
@@ -271,26 +305,55 @@ 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" %}
+Purpose:
+  Remove this chapter's explicit title.
+{% elif target.name == "metadata-object" %}
+Purpose:
+  Clear this metadata map.
+{% else %}
 Purpose:
   Clear this writable resource or local config section.
+{% endif %}
 
 Usage:
-  {{ commandName }} {{ uri }} clear
+  {{ commandName }} {{ uri }} clear{% if target.name == "metadata-object" %} [--json]{% endif %}
 
-{% if target.name == "local-config-section" %}
+{% if target.name == "chapter-title-object" %}
 Notes:
-  - Clears every key in this local config section, including secrets.
-  - No confirmation prompt is shown.
-  - Success output is the now-empty JSON object: `{}`.
-{% elif "/meta" in uri %}
+  - Removes the explicit title for this chapter.
+  - This does not delete the chapter, source text, Reading Graph data, or summary.
+{% elif target.name == "metadata-object" %}
 Notes:
   - Clears all metadata keys for this metadata object.
   - No confirmation prompt is shown.
+  - This does not delete the archive object or generated graph data.
+{% elif target.name == "local-config-section" %}
+Notes:
+  - Clears every key in this local config section, including secrets.
+  - No confirmation prompt is shown.
+  - Success output is the now-empty JSON object: `{}`.
 {% else %}
 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 %}
+Purpose:
+  Build or rebuild this library's aggregate search index.
+
+Usage:
+  {{ commandName }} {{ uri }} enable [--jsonl]
+
+Notes:
+  - This is a full rebuild from registered present archives.
+  - 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.
+  - 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.
 
@@ -306,7 +369,21 @@ Notes:
   - 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.
 
@@ -317,7 +394,19 @@ 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.
+{% else %}
 Purpose:
   Use an archive-embedded searchable FTS index.
 
@@ -329,7 +418,19 @@ Notes:
   - 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.
+{% 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 %}
 Purpose:
   Use external local-cache storage for the searchable FTS index.
 
@@ -339,13 +440,23 @@ Usage:
 Notes:
   - This switches the index storage policy back to local cache outside the `.wikg` archive.
   - The archive no longer carries embedded index data.
-  - If query support is needed on this machine after externalizing, run `{{ commandName }} {{ uri }} enable`.
+  - 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 %}
 {% elif predicate == "clean" %}
 Purpose:
   Remove completed local generation jobs.
 
 Usage:
   {{ commandName }} {{ uri }} clean
+
+Notes:
+  - Removes succeeded, failed, and canceled jobs whose status has not changed for at least seven days.
+  - Deletes those job records plus their workspace, cache, log, and event files.
+  - Does not remove waiting, running, paused, or recently finished jobs.
+  - Does not stop workers or cancel active jobs.
+  - Does not support `--json`, `--jsonl`, `--dry-run`, or `--confirm`; output is a short text count.
+  - Use `{{ commandName }} gc --help` for broader runtime cleanup and dry-run support.
 {% elif predicate == "watch" %}
 Purpose:
   Follow durable local job progress.
@@ -377,14 +488,30 @@ Purpose:
 Usage:
   {{ commandName }} {{ uri }} boost
 {% elif predicate == "put" %}
+{% if target.name == "metadata-object" %}
+Purpose:
+  Set one metadata key.
+
+Usage:
+  {{ commandName }} {{ uri }} put <key> <value> [--json]
+  {{ commandName }} {{ uri }} put <key> --json-input <json> [--json]
+  {{ commandName }} {{ uri }} put <key> --input <path|-> [--json]
+
+Notes:
+  - Positional `<value>` is stored as a string.
+  - `--json-input <json>` stores a JSON value.
+  - `--input <path|->` reads a value from a file or stdin.
+  - `--json` controls output shape; it is not JSON input.
+  - Metadata keys are command arguments, not URI segments.
+{% else %}
 Purpose:
   Set one key in this local config section.
 
 Usage:
-  {{ commandName }} {{ uri }} put <key> <value>
-  {{ commandName }} {{ uri }} put <key> --json-input <json>
+  {{ commandName }} {{ uri }} put <key> <value> [--json]
+  {{ commandName }} {{ uri }} put <key> --json-input <json> [--json]
 {% if "/llm" in uri %}
-  {{ commandName }} {{ uri }} put <key> --secret
+  {{ commandName }} {{ uri }} put <key> --secret [--json]
 {% endif %}
 
 {% if target.name == "local-config-section" %}
@@ -407,12 +534,25 @@ Keys:
 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 %}
   - `--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" %}
+Purpose:
+  Delete one metadata key.
+
+Usage:
+  {{ commandName }} {{ uri }} delete <key> [--json]
+
+Notes:
+  - Deletes the key if present; deleting an absent key leaves the metadata map unchanged.
+  - Metadata keys are command arguments, not URI segments.
+{% else %}
 Purpose:
   Delete one key from this local config section.
 
@@ -425,16 +565,27 @@ Notes:
   - Success output is the full section JSON after deletion.
   - Key aliases are normalized where supported, for example `api-key` to `apiKey`.
 {% endif %}
+{% endif %}
 {% elif predicate == "test" %}
+{% if "/concurrent" in uri %}
+Purpose:
+  Validate this local concurrency config section.
+{% else %}
 Purpose:
   Test connectivity for this local config section.
+{% endif %}
 
 Usage:
   {{ commandName }} {{ uri }} test [--json]
 
 Notes:
+{% if "/concurrent" in uri %}
+  - Validates that configured `job` and `request` limits are positive integers.
+  - This does not contact an external service.
+{% else %}
   - For `llm`, this sends a small request to the configured model.
   - For `wikispine`, this checks the built-in fetch service or local `wikispine` command.
+{% endif %}
   - Text success output is intentionally short.
   - With `--json`, success and failure both return `{ "ok": true|false, ... }`; failures set a non-zero exit code.
   - Without `--json`, failures print the command error. Use `{{ commandName }} help readiness` and `{{ commandName }} help config` to recover.
@@ -443,6 +594,28 @@ Notes:
 {% endif %}
 {% endif %}
 
+{% if libraryContext.isLibraryUri %}
+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.
+  - 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" %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/chapter/part` apply the predicate to one managed archive.
+{% elif target.name == "triple-object" or target.name == "triple-scope" %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/triple/Q8018/discusses/Q123` apply the predicate to one managed archive.
+{% elif target.name == "chunk-object" or target.name == "chunk-scope" %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/chunk/12` apply the predicate to one managed archive.
+{% elif target.name == "index-object" and libraryContext.isLibraryWide %}
+  - Library index shortcuts such as `wikg://lib/index` apply the predicate to the aggregate library index.
+{% elif target.name == "index-object" %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/index` apply the predicate to one managed archive.
+{% else %}
+  - Library archive shortcuts such as `wikg://lib/arc/<archive-id>/entity/Q8018` apply the predicate to one managed archive.
+{% endif %}
+{% endif %}
+
 Related help:
   - {{ commandName }} {{ uri }} --help
   - {{ commandName }} help uri
@@ -458,3 +631,6 @@ Related help:
 {% if target.name == "local-config-section" %}
   - {{ commandName }} help config
 {% endif %}
+{% if libraryContext.isLibraryUri %}
+  - {{ commandName }} help library
+{% endif %}

package/data/help/commands/root.jinja

@@ -41,7 +41,7 @@ Core concepts:
   - Cursor: a continuation token consumed by `{{ commandName }} next`.
 
 Important object families:
-  chapter, chunk, entity, triple, summary, index, job, config, meta.
+  chapter, chunk, entity, triple, summary, index, library, job, config, meta.
 
 What to learn where:
   - Normal workflow, object choice, and practical Agent behavior:
@@ -50,6 +50,8 @@ What to learn where:
     {{ commandName }} help readiness
   - URI grammar, scope/object routing, pagination, and short URI handling:
     {{ commandName }} help uri
+  - Library registries, managed archive folders, path binding, and aggregate indexes:
+    {{ commandName }} help library
   - Input/output formats, inference, stdin, stdout, import, export, transform, JSON, and JSONL:
     {{ commandName }} help format
   - Local LLM, concurrency, and WikiSpine provider configuration:
@@ -61,18 +63,23 @@ Help contract:
   The CLI help system is part of the product contract. When you do not know what a target or operation supports, ask the CLI for the next document.
   - Use `{{ commandName }} <uri> --help` to inspect a URI command, its default behavior, and supported predicates.
   - Use `{{ commandName }} <uri> <predicate> --help` to inspect a URI-bound predicate command.
-  - Use `{{ commandName }} <non-predicate-command> --help` for non-predicate commands such as `transform`, `gc`, `legacy`, and `next`.
+  - Use `{{ commandName }} <non-predicate-command> --help` for non-predicate commands such as `transform`, `gc`, `maintenance`, `legacy`, and `next`.
   - Use `{{ commandName }} help <topic>` for cross-command concepts, constraints, and runtime behavior.
   - Treat `{{ commandName }} --help` as the root page of the same help system.
-  - Use `{{ commandName }} legacy migrate --help` only when upgrading an `.sdpub` archive.
+  - Use `{{ commandName }} maintenance upgrade --help` for home, `.wikg`, library, and `.sdpub` upgrades.
+  - `{{ commandName }} legacy migrate --help` is a deprecated compatibility alias for `.sdpub` migration.
 
 Non-predicate command entry points:
   {{ commandName }} transform --help
   {{ commandName }} next --help
   {{ commandName }} gc --help
+  {{ commandName }} maintenance --help
   {{ commandName }} legacy --help
   {{ commandName }} help [topic] [--help|-h]
 
+Library entry point:
+  {{ commandName }} wikg://lib --help
+
 Help topics:
 {% for topic in helpTopics %}
   - {{ commandName }} help {{ topic.name }}