wiki-graph-core 0.3.1

package/data/help/commands/maintenance/chapter/add.jinja

@@ -0,0 +1,41 @@
+Help Type: command
+Command: {{ commandName }} <archive-uri>/chapter add
+
+chapter add
+
+Purpose:
+  Insert a new chapter into an existing `.wikg` chapter tree.
+
+Usage:
+  {{ commandName }} <archive-uri>/chapter add [--title <title>] [--parent <chapter-uri>] [--input <path|->] [--llm <json>] [--json] [--help|-h]
+
+Behavior:
+  - Without `--input`, creates an empty planned chapter with no source, graph, or summary.
+  - Empty planned chapters can be used as chapter directories, groups, or drafting placeholders.
+  - With `--input <path>`, creates a chapter and writes normalized source text.
+  - With `--input -`, reads source text from stdin.
+  - Source input must not be empty or whitespace-only when `--input` is used.
+  - Omitting `--title` creates an untitled planned chapter.
+  - Omitting `--parent` adds the chapter at the top level.
+  - `--parent <chapter-uri>` adds the chapter under an existing chapter.
+  - Does not call an LLM provider.
+
+Output shape:
+  Prints the new chapter status.
+  The `Chapter: <id>` line is the new chapter id for later commands.
+  With `--json`, prints the new chapter status as one JSON object.
+
+Typical next step:
+  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
+
+Examples:
+  {{ commandName }} wikg://book.wikg/chapter add --title "Part I"
+  {{ commandName }} wikg://book.wikg/chapter add --title "Chapter 1" --input ./chapter.txt --parent wikg://book.wikg/chapter/3
+  cat chapter.txt | {{ commandName }} wikg://book.wikg/chapter add --title "Chapter 1" --input -
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter --help
+  - {{ commandName }} wikg://book.wikg/chapter/3/source set --help
+  - {{ commandName }} help format
+  - {{ commandName }} help readiness
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/list.jinja

@@ -0,0 +1,33 @@
+Help Type: command
+Command: {{ commandName }} <archive-uri>/chapter
+
+chapter collection
+
+Purpose:
+  List every chapter and its stored artifact readiness.
+
+Usage:
+  {{ commandName }} <archive-uri>/chapter [--all] [--limit <n>] [--cursor <token>] [--json|--jsonl] [--llm <json>] [--help|-h]
+
+Output shape:
+  wikg://chapter/<id>  <title-or-[untitled]>  source:<ready|missing> reading-graph:<ready|missing> reading-summary:<ready|missing> knowledge-graph:<ready|missing>
+
+  With machine-readable output, each chapter object includes `uri`, `title`, and `state`.
+
+Behavior:
+  - Includes sourced, generated, and unfinished chapters.
+  - Some chapters are structural table-of-contents nodes that organize child chapters; missing generated artifacts alone does not make them abnormal.
+  - Read `{{ commandName }} help uri` before choosing `--limit`, `--all`, `--json`, or `--jsonl`.
+  - Chapter ids are encoded in the returned `wikg://chapter/<id>` URIs.
+  - Does not call an LLM provider.
+  - Does not mutate chapter content or summaries.
+
+Use this before mutation:
+  Discover ids and missing generated artifacts with:
+    {{ commandName }} <archive-uri>/chapter
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} help readiness
+  - {{ commandName }} help uri
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/move.jinja

@@ -0,0 +1,36 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri> move
+
+chapter move
+
+Purpose:
+  Move one existing chapter to a new parent or sibling position.
+
+Usage:
+  {{ commandName }} <chapter-uri> move --parent <chapter-uri> [--first|--last] [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri> move --root [--first|--last] [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri> move --before <chapter-uri> [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri> move --after <chapter-uri> [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri> move --first [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri> move --last [--llm <json>] [--help|-h]
+
+Behavior:
+  - Moves only the chapter tree node. Source text, Reading Graph data, and summary stay attached to the same chapter id.
+  - `--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.
+  - Does not call an LLM provider.
+
+Examples:
+  {{ commandName }} wikg://book.wikg/chapter/8 move --parent wikg://book.wikg/chapter/3 --first
+  {{ commandName }} wikg://book.wikg/chapter/8 move --root --last
+  {{ commandName }} wikg://book.wikg/chapter/8 move --before wikg://book.wikg/chapter/9
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter --help
+  - {{ commandName }} wikg://book.wikg/chapter/tree --help
+  - {{ commandName }} help uri
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/remove.jinja

@@ -0,0 +1,26 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri> remove
+
+chapter remove
+
+Purpose:
+  Remove a chapter from the `.wikg` chapter tree.
+
+Usage:
+  {{ commandName }} <chapter-uri> remove [--recursive] [--llm <json>] [--help|-h]
+
+Behavior:
+  - 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.
+  - Does not call an LLM provider.
+
+Safety:
+  This is a destructive in-place edit. Read `<archive-uri>/chapter` first and keep your own copy if the archive is important.
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter --help
+  - {{ commandName }} wikg://book.wikg/chapter/3 reset --help
+  - {{ commandName }} help readiness
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/reset.jinja

@@ -0,0 +1,29 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri> reset
+
+chapter reset
+
+Purpose:
+  Move a chapter backward by deleting later-stage artifacts.
+
+Usage:
+  {{ commandName }} <chapter-uri> reset --to <planned|source|reading-graph> [--llm <json>] [--help|-h]
+
+Targets:
+  planned     Delete source text, Reading Graph data, and summary.
+  source      Keep source text; delete Reading Graph data and summary.
+  reading-graph  Keep source text and Reading Graph data; delete summary.
+
+Behavior:
+  - `reading-summary` is not supported because reset is a backward operation.
+  - Reset is destructive and may discard work.
+  - Does not call an LLM provider.
+  - After resetting to `source` or `reading-graph`, use `{{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost` to generate again.
+  - After resetting to `planned`, restore source text before starting generated tasks.
+
+See also:
+  - {{ commandName }} wikg://local/job --help
+  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} help readiness
+  - {{ commandName }} help runtime
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/set-source.jinja

@@ -0,0 +1,34 @@
+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.
+
+Typical next step:
+  {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/3 reset --help
+  - {{ commandName }} wikg://local/job --help
+  - {{ commandName }} help format
+  - {{ commandName }} help readiness
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/set-summary.jinja

@@ -0,0 +1,31 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri>/summary set
+
+Purpose:
+  Fill a Reading Graph-stage chapter with a manual final summary.
+
+Usage:
+  {{ commandName }} <chapter-uri>/summary set [text] [--input <path|->] [--llm <json>] [--json] [--help|-h]
+
+Input:
+  - Summary text is read from a positional value, `--input <path>`, or `--input -` for stdin.
+  - Summary text is stored as the chapter's final summary.
+  - A common workflow is `read > /tmp/summary.md`, edit the file, then pass it back with `--input`.
+
+Preconditions:
+  - The chapter must be `reading-graph`.
+  - If the chapter is `source`, run:
+    {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task reading-graph --accept-cost
+
+Behavior:
+  - Moves the chapter to `reading-summary`.
+  - Does not generate or modify Reading Graph data.
+  - Does not call an LLM provider.
+  - With `--json`, prints the updated chapter status as one JSON object.
+
+See also:
+  - {{ commandName }} wikg://local/job --help
+  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} help readiness
+  - {{ commandName }} help runtime
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/set-title.jinja

@@ -0,0 +1,29 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri>/title set
+
+Purpose:
+  Rename an existing chapter in the archive TOC.
+
+Usage:
+  {{ commandName }} <chapter-uri>/title set <title> [--help|-h]
+  {{ commandName }} <chapter-uri>/title clear [--help|-h]
+
+Behavior:
+  - Updates only the chapter title stored in the TOC.
+  - Does not change source text, graph nodes, summaries, or metadata.
+  - `set <title>` sets the explicit title.
+  - `clear` removes the explicit title and shows `[untitled]`.
+  - Does not call an LLM provider.
+
+Output shape:
+  Prints the updated chapter object.
+
+Examples:
+  {{ commandName }} wikg://book.wikg/chapter/12/title set "New Chapter Title"
+  {{ commandName }} wikg://book.wikg/chapter/12/title clear
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter --help
+  - {{ commandName }} wikg://book.wikg/chapter/12/state --help
+  - {{ commandName }} help uri
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter/tree.jinja

@@ -0,0 +1,58 @@
+Help Type: command
+Command: {{ commandName }} <archive-uri>/chapter/tree
+
+chapter tree
+
+Purpose:
+  Get or set the complete chapter tree.
+
+Usage:
+  {{ commandName }} <archive-uri>/chapter/tree [--json] [--llm <json>] [--help|-h]
+  {{ commandName }} <archive-uri>/chapter/tree set --input <path|-> [--dry-run] [--llm <json>] [--help|-h]
+
+Tree JSON shape:
+  Reading without `--json` prints a readable tree. Add `--json` when you need editable tree JSON.
+
+  {
+    "chapters": [
+      {
+        "id": 1,
+        "title": "Part I",
+        "children": [
+          { "id": 2, "title": null, "children": [] }
+        ]
+      }
+    ]
+  }
+
+Apply rules:
+  - `set` reads tree JSON from `--input <path>` or `--input -` for stdin.
+  - Every existing chapter id must appear exactly once.
+  - Unknown, duplicated, or missing chapter ids are rejected.
+  - `children` is required on every node.
+  - `title` is optional when setting the tree.
+  - Omitted `title` means keep the current title.
+  - `title: "text"` sets or replaces the chapter title.
+  - `title: null` clears the chapter title.
+  - Extra fields are rejected.
+  - Applying a tree never creates chapters, deletes chapters, or edits source, graph, or summary data.
+
+Dry run:
+  `--dry-run` validates the input and prints moved, renamed, and unchanged counts without changing the archive.
+
+Structural chapters:
+  Some chapters are table-of-contents nodes that organize child chapters. Check this tree before treating a chapter with missing generated artifacts as abnormal.
+
+Examples:
+  {{ commandName }} wikg://book.wikg/chapter/tree
+  {{ commandName }} wikg://book.wikg/chapter/tree --json > tree.json
+  {{ commandName }} wikg://book.wikg/chapter/tree set --input tree.json --dry-run
+  {{ commandName }} wikg://book.wikg/chapter/tree set --input tree.json
+  cat tree.json | {{ commandName }} wikg://book.wikg/chapter/tree set --input -
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter/3 move --help
+  - {{ commandName }} wikg://book.wikg/chapter/3/title set --help
+  - {{ commandName }} help readiness
+  - {{ commandName }} help uri
+  - {{ commandName }} --help

package/data/help/commands/maintenance/chapter.jinja

@@ -0,0 +1,59 @@
+Help Type: command
+Command: {{ commandName }} <chapter-uri> / <archive-uri>/chapter
+
+Edit chapters inside an existing `.wikg` archive.
+
+Usage:
+  {{ commandName }} <archive-uri>/chapter [--llm <json>] [--help|-h]
+  {{ commandName }} <chapter-uri>/state [--json] [--help|-h]
+  {{ commandName }} <chapter-uri>/state/<source|reading-graph|reading-summary|knowledge-graph> [--json] [--help|-h]
+  {{ commandName }} <archive-uri>/chapter add [--title <title>] [--parent <id>] [--input <path|->] [--llm <json>] [--json] [--help|-h]
+  {{ commandName }} <chapter-uri> move (--parent <id>|--root|--before <id>|--after <id>|--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>/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]
+  {{ commandName }} <archive-uri>/chapter/tree [--json] [--llm <json>] [--help|-h]
+  {{ commandName }} <archive-uri>/chapter/tree set --input <path|-> [--dry-run] [--llm <json>] [--help|-h]
+
+Chapter stages:
+  planned     TOC chapter exists, but no source is stored.
+  source      Normalized source text is stored.
+  reading-graph  Source plus generated Reading Graph are stored.
+  reading-summary  Source, Reading Graph, and final summary are stored.
+
+Input rules:
+  - Use Wiki Graph URIs; bare `.wikg` filesystem paths are not accepted.
+  - `<chapter-uri>` includes the numeric chapter id 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>/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.
+  - `<archive-uri>/chapter/tree set --input <path|->` applies a complete chapter tree JSON. It can reorder chapters and change titles when a node includes `title`.
+  - `reset --to` accepts `planned`, `source`, or `reading-graph`.
+  - Structure edits, `/title set`, `/source set`, `/summary set`, and `reset` do not call an LLM provider.
+  - To generate reading-graph, reading-summary, or knowledge-graph, use `{{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost`.
+  - `<chapter-uri>/state` shows the aggregate chapter state. `<chapter-uri>/state/<target>` checks one target.
+  - Append `--help` after an action for action-specific details, for example `{{ commandName }} wikg://book.wikg/chapter/3 reset --help`.
+
+See also:
+  - {{ commandName }} wikg://book.wikg/chapter
+  - {{ commandName }} wikg://book.wikg/chapter/3/state
+  - {{ commandName }} wikg://book.wikg/chapter/3/state/knowledge-graph
+  - {{ commandName }} wikg://book.wikg/chapter/tree
+  - {{ commandName }} wikg://book.wikg/chapter/3/title set "New Title"
+  - {{ commandName }} wikg://book.wikg/chapter/3/title clear
+  - {{ commandName }} wikg://book.wikg/chapter add --input chapter.txt
+  - {{ commandName }} wikg://book.wikg/chapter/3/source set --input chapter.txt
+  - {{ commandName }} wikg://book.wikg/chapter/3/summary set --input summary.md
+  - cat tree.json | {{ commandName }} wikg://book.wikg/chapter/tree set --input -
+  - {{ commandName }} wikg://local/job --help
+  - {{ commandName }} help format
+  - {{ commandName }} help readiness
+  - {{ commandName }} help runtime
+  - {{ commandName }} help uri
+  - {{ commandName }} --help

package/data/help/commands/maintenance/cover.jinja

@@ -0,0 +1,28 @@
+Help Type: command
+Command: {{ commandName }} <cover-uri>
+
+cover
+
+Purpose:
+  Write the raw cover bytes stored in the archive.
+
+Usage:
+  {{ commandName }} <cover-uri> [--llm <json>] [--help|-h]
+
+Output shape:
+  - Raw binary bytes on stdout
+
+Notes:
+  - Redirect or pipe stdout.
+  - The command refuses to write binary data to an interactive terminal.
+  - The command fails if the archive has no cover.
+  - Use `{{ commandName }} <archive-uri>/meta` first when you need stored metadata.
+  - For multimodal agents, project the cover to a normal image file, then inspect that file with image/OCR tools.
+
+Examples:
+  {{ commandName }} wikg://book.wikg/cover > /tmp/cover.bin
+  {{ commandName }} wikg:///books/book.wikg/cover > ./cover.bin
+
+Related help:
+  - Runtime stdout behavior and binary-output safety:
+    {{ commandName }} help runtime

package/data/help/commands/maintenance/meta.jinja

@@ -0,0 +1,55 @@
+Help Type: command
+Command: {{ commandName }} <object-uri>/meta
+
+meta
+
+Purpose:
+  Read or edit metadata attached to any Wiki Graph object.
+
+Usage:
+  {{ commandName }} <object-uri>/meta [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta set --json <object> [--help|-h]
+  {{ commandName }} <object-uri>/meta set --json --input <path|-> [--help|-h]
+  {{ commandName }} <object-uri>/meta set --json-input <object> [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta put <key> <value> [--help|-h]
+  {{ commandName }} <object-uri>/meta put <key> --json <value> [--help|-h]
+  {{ commandName }} <object-uri>/meta put <key> --input <path|-> [--help|-h]
+  {{ commandName }} <object-uri>/meta put <key> --json-input <value> [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta delete <key> [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta clear [--json] [--help|-h]
+
+Input:
+  - `set` replaces the whole metadata map and requires a JSON object.
+  - `put` writes one key. Without `--json`, the value is stored as a string.
+  - `--json-input <json>` reads an inline JSON value.
+  - `--json --input <path>` reads JSON from a file.
+  - Use `--input -` to read from stdin.
+  - Metadata keys are command arguments, not URI segments.
+
+Behavior:
+  - Archive-level metadata is addressed as `wikg://book.wikg/meta`.
+  - Object metadata is addressed as `<object-uri>/meta`, for example `wikg://book.wikg/entity/Q42/meta`.
+  - Without `--json`, output is one `<key>: <value>` line per metadata entry.
+  - Array values are printed as space-joined item strings in text output.
+  - Add `--json` for a stable machine-readable metadata map.
+  - `--jsonl` is not supported.
+  - `<object-uri>/meta/<key>` is rejected. Read the metadata object and filter the result.
+  - Deleting an object may remove metadata attached to that object.
+  - This command does not call an LLM provider.
+
+Examples:
+  {{ commandName }} wikg://book.wikg/meta
+  {{ commandName }} wikg://book.wikg/meta --json
+  {{ commandName }} wikg://book.wikg/meta put title "New Title"
+  {{ commandName }} wikg://book.wikg/entity/Q42/meta put note "reviewed"
+  {{ commandName }} wikg://book.wikg/entity/Q42/meta put rank --json 7
+  {{ commandName }} wikg://book.wikg/entity/Q42/meta delete note
+  {{ commandName }} wikg://book.wikg/entity/Q42/meta clear
+
+Where to go next:
+  - Need chapter tree editing:
+    {{ commandName }} wikg://book.wikg/chapter/tree --help
+  - Need URI object boundaries and machine-readable output:
+    {{ commandName }} help uri
+  - Need archive-vs-source mental model:
+    {{ commandName }} --help