wiki-graph-core 0.3.1

package/data/help/commands/uri.jinja

@@ -0,0 +1,274 @@
+Help Type: command
+Command: {{ commandName }} <uri>
+
+URI Command
+
+Target:
+  {{ uri }}
+
+{% if target.name == "archive-scope" %}
+URI type:
+  Archive scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates archive-level objects.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval across archive scopes.
+
+Use when:
+  - You need the archive entry point before narrowing to chapters, chunks, entities, triples, source, or summaries.
+{% elif target.name == "chapter-collection-scope" %}
+URI type:
+  Chapter collection scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates chapters.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chapter objects.
+
+Use when:
+  - You need chapter ids, chapter readiness, or a starting point for chapter-scoped retrieval.
+{% elif target.name == "chapter-scope" %}
+URI type:
+  Chapter scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates objects inside this chapter.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval inside this chapter.
+
+Use when:
+  - You already selected a chapter and want local source, summary, chunk, entity, or triple objects.
+{% elif target.name == "chunk-scope" %}
+URI type:
+  Chunk scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates Reading Graph chunks.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to chunks in this scope.
+
+Use when:
+  - You need candidate Reading Graph chunks before selecting a concrete chunk URI.
+{% elif target.name == "entity-scope" %}
+URI type:
+  Entity scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates Knowledge Graph entities.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to entities in this scope.
+
+Use when:
+  - You need candidate entities before selecting a concrete entity URI.
+{% elif target.name == "triple-scope" %}
+URI type:
+  Triple scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` enumerates Knowledge Graph triples matching this scope or pattern.
+  - `{{ commandName }} {{ uri }} --query <query>` applies keyword retrieval to triples in this scope.
+
+Use when:
+  - You need relation candidates or a triple pattern such as `_` placeholders.
+{% elif target.name == "chapter-source-object" %}
+URI type:
+  Chapter source object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads source text.
+  - Source 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 source reads are plain text streams and do not support `--json`; source range fragments are structured range objects and support `--json`.
+
+Use when:
+  - You need continuous original wording from a selected chapter.
+{% elif target.name == "chapter-summary-object" or target.name == "summary-object" %}
+URI type:
+  Summary object
+
+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`.
+
+Use when:
+  - You need compact readable prose before tracing source evidence.
+{% elif target.name == "chapter-title-object" %}
+URI type:
+  Chapter title object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the chapter title.
+
+Use when:
+  - You need the current title or want to set or clear it.
+{% elif target.name == "chapter-tree-object" %}
+URI type:
+  Chapter tree object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the table-of-contents tree.
+
+Use when:
+  - You need the global chapter structure before choosing scopes.
+{% elif target.name == "chapter-state-object" %}
+URI type:
+  Chapter state object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads generated artifact readiness.
+
+Use when:
+  - You need to know whether source, Reading Graph, Reading Summary, or Knowledge Graph data exists for a chapter.
+{% elif target.name == "chunk-object" %}
+URI type:
+  Chunk object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads one Reading Graph chunk.
+
+Use when:
+  - You selected a chunk and need to read, expand, verify, or pack it.
+{% elif target.name == "entity-object" %}
+URI type:
+  Entity object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads one Knowledge Graph entity.
+
+Use when:
+  - You selected an entity and need related triples, source evidence, or packed context.
+{% elif target.name == "entity-wikipage-object" %}
+URI type:
+  Entity wikipage object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads mapped Wikipedia page data for the entity.
+
+Use when:
+  - You need canonical mapped pages before considering external web lookup.
+{% elif target.name == "triple-object" %}
+URI type:
+  Triple object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads one Knowledge Graph relation.
+
+Use when:
+  - You selected a concrete subject, predicate, and object relation.
+{% elif target.name == "cover-object" %}
+URI type:
+  Cover object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` writes raw cover bytes to stdout.
+
+Use when:
+  - You need to redirect or pipe the cover resource.
+{% elif target.name == "index-object" %}
+URI type:
+  Index object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the archive FTS index policy.
+
+Use when:
+  - You need to inspect, enable, disable, embed, or externalize searchable FTS index support.
+{% elif target.name == "job-collection-scope" %}
+URI type:
+  Local job collection scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` shows local generation jobs.
+
+Use when:
+  - You need to inspect, add, or clean local generation jobs.
+{% elif target.name == "job-object" %}
+URI type:
+  Local job object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads local job status.
+
+Use when:
+  - You need job status, progress, or lifecycle control.
+{% elif target.name == "job-target-object" %}
+URI type:
+  Local job target object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` is not a retrieval shortcut. Use `set`.
+
+Use when:
+  - You need to change an active job target.
+{% elif target.name == "local-config-section" %}
+URI type:
+  Local config section
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the section.
+
+Use when:
+  - You need to read, replace, edit, clear, or test local configuration.
+{% if "/wikispine" in uri %}
+
+WikiSpine runtime guide:
+  https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
+{% endif %}
+{% endif %}
+
+Predicate commands:
+{% if target.predicates.length %}
+{% for predicate in target.predicates %}
+{% if predicate == "add" %}
+  - add: create a child object or local job. Help: {{ commandName }} {{ uri }} add --help
+{% elif predicate == "boost" %}
+  - boost: move a waiting job forward. Help: {{ commandName }} {{ uri }} boost --help
+{% elif predicate == "cancel" %}
+  - cancel: cancel a local job. Help: {{ commandName }} {{ uri }} cancel --help
+{% elif predicate == "clean" %}
+  - clean: remove completed local jobs. Help: {{ commandName }} {{ uri }} clean --help
+{% elif predicate == "clear" %}
+  - clear: clear a writable resource or config section. Help: {{ commandName }} {{ uri }} clear --help
+{% elif predicate == "create" %}
+  - create: create the archive; use `--replace` only when discarding an existing archive. Help: {{ commandName }} {{ uri }} create --help
+{% elif predicate == "delete" %}
+  - delete: delete a config key. Help: {{ commandName }} {{ uri }} delete --help
+{% elif predicate == "disable" %}
+  - disable: disable searchable index support and remove index materialization. Help: {{ commandName }} {{ uri }} disable --help
+{% elif predicate == "embed" %}
+  - embed: use archive-embedded searchable index storage. Help: {{ commandName }} {{ uri }} embed --help
+{% elif predicate == "enable" %}
+  - enable: enable searchable index support and bring it to current. Help: {{ commandName }} {{ uri }} enable --help
+{% elif predicate == "evidence" %}
+  - evidence: trace this object to source-backed evidence; supports `--reverse` without `--query`. Help: {{ commandName }} {{ uri }} evidence --help
+{% elif predicate == "export" %}
+  - export: export an archive projection. Help: {{ commandName }} {{ uri }} export --help
+{% elif predicate == "external" %}
+  - external: use local-cache searchable index storage. Help: {{ commandName }} {{ uri }} external --help
+{% elif predicate == "inspect" %}
+  - inspect: inspect archive readiness. Help: {{ commandName }} {{ uri }} inspect --help
+{% elif predicate == "move" %}
+  - move: move a chapter in the tree. Help: {{ commandName }} {{ uri }} move --help
+{% elif predicate == "pack" %}
+  - pack: assemble bounded context around this object. Help: {{ commandName }} {{ uri }} pack --help
+{% elif predicate == "pause" %}
+  - pause: pause a local job. Help: {{ commandName }} {{ uri }} pause --help
+{% elif predicate == "put" %}
+  - put: set one config key. Help: {{ commandName }} {{ uri }} put --help
+{% elif predicate == "related" %}
+  - related: expand from this object to nearby objects; supports `--reverse` without `--query`. Help: {{ commandName }} {{ uri }} related --help
+{% elif predicate == "remove" %}
+  - remove: remove a chapter. Help: {{ commandName }} {{ uri }} remove --help
+{% elif predicate == "reset" %}
+  - reset: delete later-stage chapter artifacts. Help: {{ commandName }} {{ uri }} reset --help
+{% elif predicate == "resume" %}
+  - resume: resume a local job. Help: {{ commandName }} {{ uri }} resume --help
+{% elif predicate == "set" %}
+  - set: modify this writable target. Help: {{ commandName }} {{ uri }} set --help
+{% elif predicate == "test" %}
+  - test: test local config connectivity. Help: {{ commandName }} {{ uri }} test --help
+{% elif predicate == "watch" %}
+  - watch: follow local job progress. Help: {{ commandName }} {{ uri }} watch --help
+{% endif %}
+{% endfor %}
+{% else %}
+  This URI has no additional predicate commands. Use the naked URI command shown above.
+{% endif %}

package/data/help/topics/config.jinja

@@ -0,0 +1,88 @@
+Help Type: topic
+Topic: config
+
+Configuration
+
+Purpose:
+  Configuration is managed through local Wiki Graph URIs, not by editing files directly.
+  `wikg://local/config` is a namespace; operate on a child section.
+
+Sections:
+  `wikg://local/config/llm`
+    LLM provider, model, optional base URL, client name, and API key.
+
+  `wikg://local/config/concurrent`
+    Local concurrency settings:
+      - `job`: simultaneous generation jobs. Default: 3.
+      - `request`: concurrent LLM requests. Default: 6.
+
+  `wikg://local/config/wikispine`
+    WikiSpine runtime provider for Knowledge Graph builds:
+      - `provider`: `cli` or `fetch`.
+      - `fetch` uses the built-in WikiSpine service endpoint.
+      - `cli` runs the local `wikispine` command from PATH.
+
+Operations:
+  Read a section:
+    {{ commandName }} wikg://local/config/llm
+    {{ commandName }} wikg://local/config/concurrent
+    {{ commandName }} wikg://local/config/wikispine
+
+  Replace a section with a JSON object:
+    {{ commandName }} wikg://local/config/llm set '{"provider":"openai","model":"gpt-4.1"}'
+    {{ commandName }} wikg://local/config/concurrent set '{"job":3,"request":6}'
+    {{ commandName }} wikg://local/config/wikispine set '{"provider":"fetch"}'
+
+  Update one key:
+    {{ commandName }} wikg://local/config/llm put provider openai
+    {{ commandName }} wikg://local/config/llm put model gpt-4.1
+    {{ commandName }} wikg://local/config/concurrent put job 3
+    {{ commandName }} wikg://local/config/concurrent put request 6
+    {{ commandName }} wikg://local/config/wikispine put provider cli
+    {{ commandName }} wikg://local/config/wikispine put provider fetch
+
+  Store the API key:
+    {{ commandName }} wikg://local/config/llm put apiKey --secret
+
+Secret handling:
+  - `apiKey` is read through an interactive hidden prompt.
+  - `apiKey` is masked as `****` in command output.
+  - `set --json` cannot set a real `apiKey`.
+  - `set --json` may include `"apiKey":"****"` to preserve an existing secret.
+  - Omitting `apiKey` from `set --json` removes it from the section.
+
+Minimum LLM-backed operation configuration:
+  - `llm.provider`
+  - `llm.model`
+  - Provider credentials when required by the selected provider.
+
+One-run overrides:
+  `--llm <json>` can provide an LLM object for one invocation.
+  It accepts direct LLM objects and common OpenAI-compatible aliases such as `baseUrl`.
+  A base URL implies `openai-compatible` when `provider` is omitted.
+  Generation jobs may also receive `--llm <json>` at `{{ commandName }} wikg://local/job add`;
+  that job-local LLM object is stored with the job and does not appear in `wikg://local/config/llm`.
+
+Examples:
+  {{ commandName }} wikg://local/config/llm put provider openai
+  {{ commandName }} wikg://local/config/llm put model gpt-4.1
+  {{ commandName }} wikg://local/config/llm put apiKey --secret
+  {{ commandName }} wikg://local/config/llm test
+  {{ commandName }} wikg://local/config/wikispine put provider fetch
+  {{ commandName }} wikg://local/config/wikispine test
+
+WikiSpine:
+  Knowledge Graph builds require WikiSpine. If `wikispine` is missing,
+  configure one provider and run the config test before starting Knowledge Graph work.
+  Runtime setup and recovery guide:
+    https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
+
+Where to go next:
+  - Need the normal workflow:
+    {{ commandName }} help recipe
+  - Need to understand why index, LLM, or WikiSpine blocks retrieval/generation:
+    {{ commandName }} help readiness
+  - Need URI grammar:
+    {{ commandName }} help uri
+  - Need runtime effects for generation jobs:
+    {{ commandName }} help runtime

package/data/help/topics/format.jinja

@@ -0,0 +1,72 @@
+Help Type: topic
+Topic: format
+
+Format Rules
+
+Purpose:
+  Format rules cover archive file formats, explicit stdin/stdout behavior, and command output shapes for Agents and scripts.
+
+Managed archive format:
+  wikg
+
+Archive create/import input:
+  epub via `{{ commandName }} <archive-uri> create --import <epub-path>`
+
+Export formats:
+  txt, markdown, epub
+
+Transform input/output formats:
+  input: wikg, epub, txt, markdown
+  output: wikg, txt, markdown
+
+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`.
+  - Stdout text export requires an explicit or inferable output format.
+  - `transform --stage` is only valid when creating `.wikg` from source input.
+
+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`.
+  - 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.
+
+JSON:
+  `--json` prints one JSON value to stdout.
+  It is usually the best Agent-facing format for inspecting one object, one result page, one config section, one job, or one command report.
+  Prefer it over parsing text when you need fields such as `uri`, `title`, `state`, `nextCursor`, readiness flags, or job status.
+
+JSONL:
+  `--jsonl` prints one JSON record per line.
+  Use it for object inventories, large scope traversal, progress streams, and pipe-oriented downstream processing.
+  JSONL may contain both object records and control records.
+  A paged scope can end with a control record such as:
+    {"type":"page","nextCursor":"..."}
+  Filter by `type` when a downstream program expects only archive objects.
+
+Full-scope export pattern:
+  `--jsonl` is an output shape; it does not imply `--all`.
+  Use `--all --jsonl` when intentionally exporting every object from the selected scope.
+  Prefer the narrowest useful scope before full export.
+  Avoid `--all` without `--jsonl` for large result sets because text and JSON output are buffered before printing.
+  Avoid `--all | head` as a preview pattern. Shell truncation only limits what you read.
+
+Stdout and stderr:
+  Machine-readable command results go to stdout.
+  Progress, warnings, and diagnostics go to stderr.
+  Commands that accept `--json` or `--jsonl` emit machine-readable error objects when those flags are present.
+
+Examples:
+  {{ commandName }} wikg://book.wikg create
+  {{ commandName }} wikg://book.wikg create --import ./book.epub
+  {{ commandName }} wikg://book.wikg export --output-format markdown --output out.md
+  cat chapter.txt | {{ commandName }} transform --input-format txt --output-format markdown
+  {{ commandName }} wikg://book.wikg inspect --json
+  {{ commandName }} wikg://book.wikg/entity --all --jsonl
+
+Transforming source input usually requires LLM configuration.

package/data/help/topics/readiness.jinja

@@ -0,0 +1,99 @@
+Help Type: topic
+Topic: readiness
+
+Readiness
+
+Purpose:
+  Use this when `inspect` reports missing `--query` support, generated data, or provider configuration.
+  Readiness explains what must exist before `--query`, Reading Graph, summaries, and Knowledge Graph retrieval can work.
+
+Start with inspect:
+  {{ commandName }} <archive-uri> inspect
+
+FTS readiness:
+  `--query` uses the archive FTS index. Without a current index, keyword retrieval is unavailable for scopes, evidence, and related results.
+
+  Default behavior:
+    `{{ commandName }} <archive-uri>/index enable` enables the searchable index as local cache outside the `.wikg` archive.
+    This keeps the archive smaller, but the index does not travel with copied archive files.
+    If another user receives the `.wikg`, they usually need to enable their own local index.
+    After an index is enabled, CLI archive writes keep it synchronized automatically.
+    Do not enable the index again after every generation job.
+
+  Portable behavior:
+    `{{ commandName }} <archive-uri>/index embed` switches to an archive-embedded searchable index and ensures it is current.
+    This makes the archive more self-contained, but increases file size.
+    After embedding, CLI archive writes keep the embedded index synchronized automatically.
+    If you are unsure, enable the local index first and embed only when distribution convenience matters.
+
+  Commands:
+    {{ commandName }} <archive-uri>/index
+    {{ commandName }} <archive-uri>/index enable --help
+    {{ commandName }} <archive-uri>/index disable --help
+    {{ commandName }} <archive-uri>/index embed --help
+    {{ commandName }} <archive-uri>/index external --help
+
+Generation readiness:
+  Reading Graph, Reading Summary, and Knowledge Graph data are generated artifacts.
+  They do not appear just because source text exists.
+
+  All generation jobs require LLM configuration:
+    {{ commandName }} wikg://local/config/llm
+    {{ commandName }} wikg://local/config/llm test
+
+  Inspect job commands before starting expensive work:
+    {{ commandName }} wikg://local/job --help
+    {{ commandName }} wikg://local/job add --help
+
+LLM readiness:
+  `wikg://local/config/llm` is required for generating:
+  - Reading Graph
+  - Reading Summary
+  - Knowledge Graph
+
+  Minimum configuration:
+    provider
+    model
+    provider credentials when required
+
+  Common path:
+    {{ commandName }} wikg://local/config/llm put provider openai
+    {{ commandName }} wikg://local/config/llm put model gpt-4.1
+    {{ commandName }} wikg://local/config/llm put apiKey --secret
+    {{ commandName }} wikg://local/config/llm test
+
+WikiSpine readiness:
+  Knowledge Graph generation also requires WikiSpine.
+  WikiSpine provides entity candidate lookup for Knowledge Graph construction.
+
+  Provider choices:
+  - `fetch`: use the built-in WikiSpine HTTP service. This is usually easier for Agents and hosted setups.
+  - `cli`: run the local `wikispine` command from PATH. This is useful for offline or locally controlled environments, but requires local runtime setup and data.
+
+  Configure one provider, then test it:
+    {{ commandName }} wikg://local/config/wikispine put provider fetch
+    {{ commandName }} wikg://local/config/wikispine test
+
+    {{ commandName }} wikg://local/config/wikispine put provider cli
+    {{ commandName }} wikg://local/config/wikispine test
+
+  Runtime setup and recovery guide:
+    https://raw.githubusercontent.com/oomol-lab/wiki-graph/refs/heads/main/docs/wikispine-runtime.md
+
+How to choose:
+  - Need keyword retrieval on this machine: enable local index.
+  - Need to send a more self-contained `.wikg`: consider embedding the index.
+  - Need to intentionally drop query support or index materialization: disable index.
+  - Need generated Reading Graph or summaries: configure LLM and use local jobs.
+  - Need Knowledge Graph: configure LLM and WikiSpine, then use local jobs.
+  - Not sure whether to embed index or generate missing data: keep the archive external/local first, inspect again, and decide later.
+
+Where to go next:
+  - Normal workflow:
+    {{ commandName }} help recipe
+  - Exact config fields and secret handling:
+    {{ commandName }} help config
+  - Job runtime, logs, cache, and failures:
+    {{ commandName }} help runtime
+  - URI and predicate help for index/job/config targets:
+    {{ commandName }} <uri> --help