wiki-graph 0.3.0 → 0.4.0

package/{data → dist/data}/help/commands/maintenance/chapter/add.jinja

@@ -22,7 +22,7 @@ Behavior:
 
 Output shape:
   Prints the new chapter status.
-  The `Chapter: <id>` line is the new chapter id for later commands.
+  The `Chapter: <uri>` line is the new chapter URI for later commands.
   With `--json`, prints the new chapter status as one JSON object.
 
 Typical next step:
@@ -30,12 +30,12 @@ Typical next step:
 
 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
+  {{ commandName }} wikg://book.wikg/chapter add --title "Chapter 1" --input ./chapter.txt --parent wikg://book.wikg/chapter/part
   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 }} wikg://book.wikg/chapter/part/source set --help
   - {{ commandName }} help format
   - {{ commandName }} help readiness
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/list.jinja

@@ -10,7 +10,7 @@ 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>
+  wikg://chapter/<path>  <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`.
 
@@ -18,16 +18,16 @@ 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.
+  - Chapter paths are encoded in the returned `wikg://chapter/<path>` 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:
+  Discover chapter URIs and missing generated artifacts with:
     {{ commandName }} <archive-uri>/chapter
 
 See also:
-  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/part/state --help
   - {{ commandName }} help readiness
   - {{ commandName }} help uri
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/move.jinja

@@ -15,7 +15,7 @@ Usage:
   {{ 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.
+  - 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.
@@ -25,9 +25,9 @@ Behavior:
   - 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
+  {{ commandName }} wikg://book.wikg/chapter/intro move --parent wikg://book.wikg/chapter/part --first
+  {{ commandName }} wikg://book.wikg/chapter/intro move --root --last
+  {{ commandName }} wikg://book.wikg/chapter/intro move --before wikg://book.wikg/chapter/appendix
 
 See also:
   - {{ commandName }} wikg://book.wikg/chapter --help

package/{data → dist/data}/help/commands/maintenance/chapter/remove.jinja

@@ -21,6 +21,6 @@ Safety:
 
 See also:
   - {{ commandName }} wikg://book.wikg/chapter --help
-  - {{ commandName }} wikg://book.wikg/chapter/3 reset --help
+  - {{ commandName }} wikg://book.wikg/chapter/part reset --help
   - {{ commandName }} help readiness
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/reset.jinja

@@ -23,7 +23,7 @@ Behavior:
 
 See also:
   - {{ commandName }} wikg://local/job --help
-  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/part/state --help
   - {{ commandName }} help readiness
   - {{ commandName }} help runtime
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/set-source.jinja

@@ -26,8 +26,8 @@ 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://book.wikg/chapter/part/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/part reset --help
   - {{ commandName }} wikg://local/job --help
   - {{ commandName }} help format
   - {{ commandName }} help readiness

package/{data → dist/data}/help/commands/maintenance/chapter/set-summary.jinja

@@ -25,7 +25,7 @@ Behavior:
 
 See also:
   - {{ commandName }} wikg://local/job --help
-  - {{ commandName }} wikg://book.wikg/chapter/3/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/part/state --help
   - {{ commandName }} help readiness
   - {{ commandName }} help runtime
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/set-title.jinja

@@ -19,11 +19,11 @@ 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
+  {{ commandName }} wikg://book.wikg/chapter/part/title set "New Chapter Title"
+  {{ commandName }} wikg://book.wikg/chapter/part/title clear
 
 See also:
   - {{ commandName }} wikg://book.wikg/chapter --help
-  - {{ commandName }} wikg://book.wikg/chapter/12/state --help
+  - {{ commandName }} wikg://book.wikg/chapter/part/state --help
   - {{ commandName }} help uri
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter/tree.jinja

@@ -16,10 +16,10 @@ Tree JSON shape:
   {
     "chapters": [
       {
-        "id": 1,
+        "uri": "wikg://chapter/part",
         "title": "Part I",
         "children": [
-          { "id": 2, "title": null, "children": [] }
+          { "uri": "wikg://chapter/part/intro", "title": null, "children": [] }
         ]
       }
     ]
@@ -27,8 +27,8 @@ Tree JSON shape:
 
 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.
+  - Every existing chapter URI must appear exactly once.
+  - Unknown, duplicated, or missing chapter URIs are rejected.
   - `children` is required on every node.
   - `title` is optional when setting the tree.
   - Omitted `title` means keep the current title.
@@ -51,8 +51,8 @@ Examples:
   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 }} wikg://book.wikg/chapter/part move --help
+  - {{ commandName }} wikg://book.wikg/chapter/part/title set --help
   - {{ commandName }} help readiness
   - {{ commandName }} help uri
   - {{ commandName }} --help

package/{data → dist/data}/help/commands/maintenance/chapter.jinja

@@ -7,8 +7,8 @@ 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 }} <archive-uri>/chapter add [--title <title>] [--parent <chapter-path>] [--input <path|->] [--llm <json>] [--json] [--help|-h]
+  {{ 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]
@@ -26,7 +26,7 @@ Chapter stages:
 
 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`.
+  - `<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.
@@ -38,18 +38,18 @@ Input rules:
   - 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`.
+  - Append `--help` after an action for action-specific details, for example `{{ commandName }} wikg://book.wikg/chapter/part 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/part/state
+  - {{ commandName }} wikg://book.wikg/chapter/part/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/part/title set "New Title"
+  - {{ commandName }} wikg://book.wikg/chapter/part/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
+  - {{ commandName }} wikg://book.wikg/chapter/part/source set --input chapter.txt
+  - {{ commandName }} wikg://book.wikg/chapter/part/summary set --input summary.md
   - cat tree.json | {{ commandName }} wikg://book.wikg/chapter/tree set --input -
   - {{ commandName }} wikg://local/job --help
   - {{ commandName }} help format

package/{data → dist/data}/help/commands/maintenance/meta.jinja

@@ -8,12 +8,11 @@ Purpose:
 
 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> [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta set --input <path|-> [--json] [--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> <value> [--json] [--help|-h]
+  {{ commandName }} <object-uri>/meta put <key> --input <path|-> [--json] [--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]
@@ -22,7 +21,8 @@ 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.
+  - `--input <path|->` reads a value from a file or stdin.
+  - `--json` controls output shape; it is not JSON input.
   - Use `--input -` to read from stdin.
   - Metadata keys are command arguments, not URI segments.
 
@@ -42,7 +42,7 @@ Examples:
   {{ 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 put rank --json-input 7
   {{ commandName }} wikg://book.wikg/entity/Q42/meta delete note
   {{ commandName }} wikg://book.wikg/entity/Q42/meta clear
 

package/dist/data/help/commands/maintenance/upgrade.jinja

@@ -0,0 +1,35 @@
+Help Type: command
+Command: {{ commandName }} maintenance upgrade
+
+Purpose:
+  Explicitly upgrade persistent Wiki Graph data. Home state may be upgraded automatically before real commands; user archives and libraries are upgraded only through this maintenance command.
+
+Usage:
+  {{ commandName }} maintenance upgrade <target> [--json]
+  {{ commandName }} maintenance upgrade <path.sdpub> [--output <path.wikg>] [--json]
+
+Targets:
+  - Home state: ~/.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>
+
+Notes:
+  - This maintenance command accepts filesystem paths. URI-targeted archive/object commands still require Wiki Graph URIs; see `{{ commandName }} help uri`.
+  - Home state may be schema-gated automatically before real commands, but this command is the explicit recovery and batch-upgrade entry point.
+  - Internal SQLite files are part of the home target and are not user-facing upgrade targets.
+  - Standalone .wikg, home, and library targets are upgraded in place and do not support --output.
+  - Library archive member URIs such as wikg://lib/arc/<archive-id>/ are not standalone upgrade targets; upgrade the whole library.
+  - Library upgrade covers the registry and managed archive members for that library.
+
+Examples:
+  {{ commandName }} maintenance upgrade ~/.wikigraph
+  {{ commandName }} maintenance upgrade ./book.wikg
+  {{ commandName }} maintenance upgrade wikg://lib
+  {{ commandName }} maintenance upgrade ./book.sdpub --output ./book.wikg
+
+Related help:
+  - URI target forms and path conversion:
+    {{ commandName }} help uri
+  - Library upgrade scope:
+    {{ commandName }} help library

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

@@ -0,0 +1,23 @@
+Help Type: command
+Command: {{ commandName }} maintenance
+
+Purpose:
+  Run explicit maintenance operations for persistent Wiki Graph data.
+
+Usage:
+  {{ commandName }} maintenance upgrade <target> [--json]
+
+Commands:
+  upgrade    Upgrade home state, a .wikg archive, a library, or migrate .sdpub.
+
+Upgrade targets:
+  {{ commandName }} maintenance upgrade ~/.wikigraph
+  {{ commandName }} maintenance upgrade ./book.wikg
+  {{ commandName }} maintenance upgrade wikg://book.wikg
+  {{ commandName }} maintenance upgrade ./book.sdpub [--output ./book.wikg]
+  {{ commandName }} maintenance upgrade wikg://lib
+  {{ commandName }} maintenance upgrade wikg://lib/<lib-id>
+
+See Also:
+  {{ commandName }} maintenance upgrade --help
+  {{ commandName }} help format