wiki-graph-core 0.3.1

package/data/help/commands/predicate.jinja

@@ -0,0 +1,460 @@
+Help Type: command
+Command: {{ commandName }} <uri> {{ predicate }}
+
+URI Predicate Command
+
+Target:
+  {{ uri }}
+
+Predicate:
+  {{ predicate }}
+
+{% if predicate == "related" %}
+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]
+
+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.
+  - 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.
+{% elif predicate == "evidence" %}
+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]
+
+Notes:
+  - Evidence is for grounding, verification, and citation support.
+  - `--query` filters and ranks evidence with the current FTS index.
+  - 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.
+  - Source and scope URIs are not evidence targets.
+{% elif predicate == "pack" %}
+Purpose:
+  Build bounded Agent-readable context around the current chunk or entity object.
+
+Usage:
+  {{ commandName }} {{ uri }} pack [--budget <chars>] [--json|--jsonl]
+
+Notes:
+  - Default budget is 5000 characters.
+  - Use this after selecting a useful chunk or entity.
+  - Use `evidence` first when verification matters more than context assembly.
+{% elif predicate == "create" %}
+Purpose:
+  Create the archive at this URI.
+
+Usage:
+  {{ commandName }} {{ uri }} create [--import <epub-path>] [--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.
+  - 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":"..."}`.
+
+Examples:
+  {{ commandName }} {{ uri }} create --json
+  {{ commandName }} {{ uri }} create --import ./book.epub
+
+Next:
+  {{ commandName }} {{ uri }} inspect
+{% elif predicate == "export" %}
+Purpose:
+  Export a projection from this archive.
+
+Usage:
+  {{ commandName }} {{ uri }} export [--output-format markdown|txt|epub] [--output <path>]
+
+Notes:
+  - Default output format is markdown when omitted by the parser, but explicit `--output-format` is recommended.
+  - Without `--output`, exported content is written to stdout.
+  - `--json` and `--jsonl` are not supported; the output stream is the exported projection.
+  - Text exports depend on available source/summary content. Missing summaries produce an error that points to the generation command.
+  - Export does not build Reading Graph or Knowledge Graph coverage.
+  - Projections are portable views; they do not replace the `.wikg` archive.
+
+Examples:
+  {{ commandName }} {{ uri }} export --output-format markdown --output book.md
+  {{ commandName }} {{ uri }} export --output-format txt > book.txt
+{% elif predicate == "inspect" %}
+Purpose:
+  Inspect archive readiness before `--query`, retrieval, or starting generated work.
+
+Usage:
+  {{ commandName }} {{ uri }} inspect [--json]
+
+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.
+{% elif predicate == "add" and target.name == "chapter-collection-scope" %}
+Purpose:
+  Add a chapter to the archive.
+
+Usage:
+  {{ commandName }} {{ uri }} add [--parent <chapter-uri>] [--title <title>] [--input <path|->] [--json]
+
+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.
+{% elif predicate == "add" and target.name == "job-collection-scope" %}
+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>]
+
+Notes:
+  - Generation jobs may call an LLM provider and incur cost.
+  - Archive input adds jobs for all eligible chapters; chapter input adds one job.
+  - `--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>]
+{% elif predicate == "remove" %}
+Purpose:
+  Remove this chapter.
+
+Usage:
+  {{ commandName }} {{ uri }} remove [--confirm]
+{% elif predicate == "reset" %}
+Purpose:
+  Delete later-stage artifacts for this chapter.
+
+Usage:
+  {{ commandName }} {{ uri }} reset --to source|reading-graph|reading-summary|knowledge-graph [--confirm]
+{% elif predicate == "set" %}
+{% if target.name == "chapter-tree-object" %}
+Purpose:
+  Replace the chapter tree with a JSON tree document.
+
+Usage:
+  {{ commandName }} {{ uri }} set --input <tree.json|->
+
+Notes:
+  - The input is a chapter tree JSON document produced by the chapter tree view.
+  - 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.
+{% elif target.name == "chapter-summary-object" %}
+Purpose:
+  Replace this chapter summary text.
+
+Usage:
+  {{ commandName }} {{ uri }} set [text] [--input <path|->]
+
+Notes:
+  - The input is plain summary text from a positional value, `--input <path>`, or `--input -` for stdin.
+  - This sets the summary resource directly; it does not call an LLM provider.
+{% elif target.name == "chapter-title-object" %}
+Purpose:
+  Replace this chapter title.
+
+Usage:
+  {{ commandName }} {{ uri }} set <title>
+
+Notes:
+  - Use `clear` on the same title URI to remove an explicit title.
+{% elif target.name == "job-target-object" %}
+Purpose:
+  Change the generation target for this local job.
+
+Usage:
+  {{ commandName }} {{ uri }} set reading-graph|reading-summary|knowledge-graph
+
+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 == "local-config-section" %}
+Purpose:
+  Replace this entire local config section with a JSON object.
+
+Usage:
+  {{ commandName }} {{ uri }} set <json> [--json]
+  {{ commandName }} {{ uri }} set --json-input <json> [--json]
+
+{% if "/llm" in uri %}
+Schema:
+  {
+    "provider": "openai|openai-compatible|anthropic|google",
+    "model": "<model-name>",
+    "baseURL": "<url>",
+    "name": "<display-name>"
+  }
+
+Notes:
+  - Allowed keys: provider, model, baseURL, name, 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`.
+{% elif "/wikispine" in uri %}
+Schema:
+  {
+    "provider": "fetch|cli"
+  }
+
+Notes:
+  - `fetch` uses the built-in WikiSpine service endpoint.
+  - `cli` runs the local `wikispine` command from PATH.
+{% elif "/concurrent" in uri %}
+Schema:
+  {
+    "job": 3,
+    "request": 6
+  }
+
+Notes:
+  - Allowed keys: job, request.
+  - Values must be positive integers.
+{% endif %}
+
+Examples:
+{% if "/llm" in uri %}
+  {{ 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 "/wikispine" in uri %}
+  {{ commandName }} {{ uri }} set '{"provider":"fetch"}'
+  {{ commandName }} {{ uri }} set '{"provider":"cli"}'
+{% elif "/concurrent" in uri %}
+  {{ 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.
+
+Usage:
+  {{ commandName }} {{ uri }} --help
+
+Notes:
+  - `set` is target-specific. Use the URI help page to find the writable child resource or supported predicate.
+{% endif %}
+{% elif predicate == "clear" %}
+Purpose:
+  Clear this writable resource or local config section.
+
+Usage:
+  {{ commandName }} {{ uri }} clear
+
+{% if 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: `{}`.
+{% elif "/meta" in uri %}
+Notes:
+  - Clears all metadata keys for this metadata object.
+  - No confirmation prompt is shown.
+{% else %}
+Notes:
+  - This predicate is only available on URI targets that explicitly support clearing.
+{% endif %}
+{% elif predicate == "enable" %}
+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.
+{% elif predicate == "disable" %}
+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.
+{% elif predicate == "embed" %}
+Purpose:
+  Use an archive-embedded searchable FTS index.
+
+Usage:
+  {{ commandName }} {{ uri }} embed [--json]
+
+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.
+{% elif predicate == "external" %}
+Purpose:
+  Use external local-cache storage for the searchable FTS index.
+
+Usage:
+  {{ commandName }} {{ uri }} external [--json]
+
+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`.
+{% elif predicate == "clean" %}
+Purpose:
+  Remove completed local generation jobs.
+
+Usage:
+  {{ commandName }} {{ uri }} clean
+{% elif predicate == "watch" %}
+Purpose:
+  Follow durable local job progress.
+
+Usage:
+  {{ commandName }} {{ uri }} watch [--jsonl] [--from beginning|now]
+{% elif predicate == "pause" %}
+Purpose:
+  Pause this local job.
+
+Usage:
+  {{ commandName }} {{ uri }} pause
+{% elif predicate == "resume" %}
+Purpose:
+  Resume this local job.
+
+Usage:
+  {{ commandName }} {{ uri }} resume
+{% elif predicate == "cancel" %}
+Purpose:
+  Cancel this local job.
+
+Usage:
+  {{ commandName }} {{ uri }} cancel
+{% elif predicate == "boost" %}
+Purpose:
+  Move this local job forward in the local job scheduler.
+
+Usage:
+  {{ commandName }} {{ uri }} boost
+{% elif predicate == "put" %}
+Purpose:
+  Set one key in this local config section.
+
+Usage:
+  {{ commandName }} {{ uri }} put <key> <value>
+  {{ commandName }} {{ uri }} put <key> --json-input <json>
+{% if "/llm" in uri %}
+  {{ commandName }} {{ uri }} put <key> --secret
+{% endif %}
+
+{% if target.name == "local-config-section" %}
+{% if "/llm" in uri %}
+Keys:
+  - provider: openai, openai-compatible, anthropic, or google
+  - model: non-empty model name
+  - baseURL: non-empty provider base URL string
+  - name: non-empty display name
+  - apiKey: secret; use `--secret`
+{% elif "/wikispine" in uri %}
+Keys:
+  - provider: fetch or cli
+{% elif "/concurrent" in uri %}
+Keys:
+  - job: positive integer
+  - request: positive integer
+{% endif %}
+
+Notes:
+  - Positional `<value>` is stored as a string.
+  - `--json-input` stores a JSON value and is useful for numeric config sections.
+{% 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 %}
+{% elif predicate == "delete" %}
+Purpose:
+  Delete one key from this local config section.
+
+Usage:
+  {{ commandName }} {{ uri }} delete <key>
+
+{% if target.name == "local-config-section" %}
+Notes:
+  - Deletes the key if present; deleting an absent key leaves the section unchanged.
+  - Success output is the full section JSON after deletion.
+  - Key aliases are normalized where supported, for example `api-key` to `apiKey`.
+{% endif %}
+{% elif predicate == "test" %}
+Purpose:
+  Test connectivity for this local config section.
+
+Usage:
+  {{ commandName }} {{ uri }} test [--json]
+
+Notes:
+  - For `llm`, this sends a small request to the configured model.
+  - For `wikispine`, this checks the built-in fetch service or local `wikispine` command.
+  - 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.
+{% if "/wikispine" in uri %}
+  - Runtime setup and recovery guide: https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
+{% endif %}
+{% endif %}
+
+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" %}
+  - {{ commandName }} help readiness
+{% endif %}
+{% if predicate == "create" or predicate == "export" %}
+  - {{ commandName }} help format
+{% endif %}
+{% if target.name == "job-collection-scope" or target.name == "job-object" or target.name == "job-target-object" %}
+  - {{ commandName }} help runtime
+{% endif %}
+{% if target.name == "local-config-section" %}
+  - {{ commandName }} help config
+{% endif %}

package/data/help/commands/root.jinja

@@ -0,0 +1,83 @@
+Help Type: command
+Command: {{ commandName }}
+
+Wiki Graph CLI
+
+Alias:
+  `{{ fullCommandName }}` is also installed as the full command name. Use it when `{{ commandName }}` conflicts with another local tool.
+
+Purpose:
+  Operate `.wikg` knowledge-base archives through stable Wiki Graph objects.
+  A `.wikg` archive is managed storage for source text and generated knowledge structures.
+  Use CLI commands to inspect, retrieve, generate, edit, and export it.
+
+Do not edit archive internals:
+  A `.wikg` file is a zip-based archive, but Agents must not unzip it, rewrite internal files, or bypass this CLI.
+  Direct internal edits can break consistency and damage the archive.
+  Use the CLI's retrieval, generation, metadata, chapter, config, and maintenance commands to modify it.
+
+Knowledge-base contents:
+  A `.wikg` archive can contain:
+  - Knowledge Graph: entity and predicate networks for concepts, relations, and claims.
+  - 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.
+
+Required first step for Agents:
+  If you receive an unfamiliar archive, inspect it before querying, generating, or editing:
+    {{ commandName }} <archive-uri> inspect
+
+Recommended next page:
+  Read the workflow recipe after this root page:
+    {{ commandName }} help recipe
+  It contains the practical flow: create/import, inspect, retrieve, choose objects, notice index/job blockers, and export.
+
+Core concepts:
+  - Archive: a `.wikg` file addressed by an archive URI.
+  - Scope: a URI target that can enumerate objects and accept `--query`.
+  - Object: a URI target that reads one concrete archive object.
+  - Predicate: an operation bound to a URI target, such as `create`, `set`, `evidence`, `related`, or `pack`.
+  - Cursor: a continuation token consumed by `{{ commandName }} next`.
+
+Important object families:
+  chapter, chunk, entity, triple, summary, index, job, config, meta.
+
+What to learn where:
+  - Normal workflow, object choice, and practical Agent behavior:
+    {{ commandName }} help recipe
+  - Search index, LLM, WikiSpine, and generated-data prerequisites:
+    {{ commandName }} help readiness
+  - URI grammar, scope/object routing, pagination, and short URI handling:
+    {{ commandName }} help uri
+  - Input/output formats, inference, stdin, stdout, import, export, transform, JSON, and JSONL:
+    {{ commandName }} help format
+  - Local LLM, concurrency, and WikiSpine provider configuration:
+    {{ commandName }} help config
+  - Advanced runtime behavior, workers, cache, logs, and debugging:
+    {{ commandName }} help runtime
+
+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 }} 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.
+
+Non-predicate command entry points:
+  {{ commandName }} transform --help
+  {{ commandName }} next --help
+  {{ commandName }} gc --help
+  {{ commandName }} legacy --help
+  {{ commandName }} help [topic] [--help|-h]
+
+Help topics:
+{% for topic in helpTopics %}
+  - {{ commandName }} help {{ topic.name }}
+    {{ topic.summary }}
+{% endfor %}
+
+Formats:
+  {{ formats | join(", ") }}

package/data/help/commands/transform.jinja

@@ -0,0 +1,34 @@
+Help Type: command
+Command: {{ commandName }} transform
+
+Purpose:
+  Run a direct one-shot digest/export.
+  This is not a plain file-format converter; source inputs usually require LLM-backed digest work, and `--output-format wikg` can create a reusable `.wikg` archive.
+
+Usage:
+  {{ commandName }} transform [--input <path>] [--output <path>] [--input-format <format>] [--output-format <format>] [--digest-dir <path>] [--llm <json>] [--prompt <text>] [--stage <planned|source|reading-graph|reading-summary>] [--verbose|-v]
+
+Behavior:
+  - Reads from `--input <path>`, or from stdin when `--input` is omitted.
+  - Writes to `--output <path>`, or to stdout when `--output` is omitted.
+  - Source inputs (`epub`, `txt`, `markdown`) call an LLM unless `--output-format wikg --stage planned|source` is used.
+  - Existing `.wikg` input can be exported to text without running digest generation.
+  - Does not leave a managed archive unless `--output-format wikg` is selected.
+
+LLM-backed source examples:
+  cat chapter.txt | {{ commandName }} transform --input-format txt --output-format markdown
+  {{ commandName }} transform --input book.epub --output digest.md --output-format markdown
+
+Existing archive export example:
+  {{ commandName }} transform --input book.wikg --output digest.md --output-format markdown
+
+Where to go next:
+  - Prefer reusable archives:
+    {{ commandName }} wikg://book.wikg create
+    {{ commandName }} wikg://book.wikg create --import ./book.epub
+  - Configure LLM defaults:
+    {{ commandName }} wikg://local/config/llm
+  - Format inference, stdin, stdout, and legal conversions:
+    {{ commandName }} help format
+  - Runtime behavior for stdin/stdout, logs, and failures:
+    {{ commandName }} help runtime