wiki-graph-core 0.3.1 → 0.4.0

package/data/help/commands/library.jinja

@@ -0,0 +1,235 @@
+Help Type: command
+Command: {{ commandName }} {{ uri }}
+
+{% if target.kind == "registry" %}
+Library registry collection
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` lists all library registries.
+  - `{{ commandName }} {{ uri }} add --path <folder>` creates a non-default library registry.
+
+Usage:
+  {{ commandName }} wikg://lib/registry [--json]
+  {{ commandName }} wikg://lib/registry add --path <folder> [--json]
+
+Predicate commands:
+  - add: create a non-default library registry and an empty folder. Help: {{ commandName }} wikg://lib/registry add --help
+
+Related help:
+  - {{ commandName }} wikg://lib --help
+  - {{ commandName }} help library
+{% elif target.kind == "path" %}
+Library path object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the library folder path.
+  - `{{ commandName }} {{ uri }} set <folder>` binds the library folder path and scans archive membership.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} set <folder> [--json|--jsonl]
+
+Predicate commands:
+  - set: bind this library to an existing folder and reconcile `.wikg` files. Help: {{ commandName }} {{ uri }} set --help
+
+Related help:
+  - {{ commandName }} wikg://lib --help
+  - {{ commandName }} help library
+{% elif target.kind == "archive-collection" %}
+Archive member collection
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the archive collection scope; use `/tree` for member file visualization.
+  - `scan` reconciles `.wikg` files; `add` copies and registers one archive.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} add --input <path> [--to <relative-wikg-path>] [--json]
+  {{ commandName }} {{ uri }} scan [--json|--jsonl]
+  {{ commandName }} {{ uri }}/tree [--parent <relative-path>] [--depth <n>] [--json]
+
+Predicate commands:
+  - add: copy one `.wikg` file into the library folder. Help: {{ commandName }} {{ uri }} add --help
+  - scan: reconcile registered archive memberships with files under the folder. Help: {{ commandName }} {{ uri }} scan --help
+  - tree: inspect the managed archive file tree. Help: {{ commandName }} {{ uri }}/tree --help
+
+Related help:
+  - {{ commandName }} wikg://lib --help
+  - {{ commandName }} help library
+{% elif target.kind == "archive-tree" %}
+Archive member tree object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` shows the archive member file tree.
+  - `--parent` filters to a directory or `.wikg` file while preserving ancestors.
+  - `--depth` is calculated from the library scope root.
+  - This object is read-only and does not support `set` or `apply`.
+
+Usage:
+  {{ commandName }} {{ uri }} [--parent <relative-path>] [--depth <n>] [--json]
+
+Related help:
+  - {{ commandName }} help library
+{% elif target.kind == "archive-path" %}
+Archive member path object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads this archive member's relative `.wikg` path.
+  - `{{ commandName }} {{ uri }} set <relative-wikg-path>` moves or renames the member.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} set <relative-wikg-path> [--json]
+
+Predicate commands:
+  - set: move or rename this archive inside the same library folder. Help: {{ commandName }} {{ uri }} set --help
+
+Related help:
+  - {{ commandName }} help library
+{% elif target.kind == "metadata" %}
+Library metadata object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads this library metadata map.
+  - Metadata keys are free-form user fields.
+  - System registry fields such as id, public id, folder path, default marker, and staging path are not metadata.
+
+Use when:
+  - You need to read or edit user metadata attached to a library scope.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} set <json> [--json]
+  {{ commandName }} {{ uri }} set --json-input <json> [--json]
+  {{ commandName }} {{ uri }} set --input <path|-> [--json]
+  {{ commandName }} {{ uri }} put <key> <value> [--json]
+  {{ commandName }} {{ uri }} put <key> --json-input <value> [--json]
+  {{ commandName }} {{ uri }} put <key> --input <path|-> [--json]
+  {{ commandName }} {{ uri }} delete <key> [--json]
+  {{ commandName }} {{ uri }} clear [--json]
+
+Input notes:
+  - `--json` controls output shape; it is not JSON input.
+  - Use `--json-input` when a metadata value itself is JSON.
+
+Predicate commands:
+  - set: replace the whole metadata map. Help: {{ commandName }} {{ uri }} set --help
+  - put: write one metadata key. Help: {{ commandName }} {{ uri }} put --help
+  - delete: delete one metadata key. Help: {{ commandName }} {{ uri }} delete --help
+  - clear: clear the metadata map. Help: {{ commandName }} {{ uri }} clear --help
+{% elif target.kind == "archive" %}
+Library archive membership
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads the registry entry for this library archive member.
+  - The membership entry identifies the archive id, relative path, status, and containing library.
+  - `{{ commandName }} {{ uri }} inspect` checks readiness for this managed archive's contents, not the library registry.
+  - Add archive object suffixes such as `/chapter`, `/entity`, or `/triple` when you want to query the archive contents.
+
+Use when:
+  - You need to inspect readiness, change the relative path of, or remove one archive that is already managed by a library.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} inspect [--json]
+  {{ commandName }} {{ uri }}/path set <relative-wikg-path> [--json]
+  {{ commandName }} {{ uri }} remove --confirm [--json]
+
+Predicate commands:
+  - inspect: inspect this managed archive's archive readiness. Help: {{ commandName }} {{ uri }} inspect --help
+  - path set: move or rename this archive inside the same library folder without changing its archive id. Help: {{ commandName }} {{ uri }}/path set --help
+  - remove: delete this archive file from the library folder and unregister it. Help: {{ commandName }} {{ uri }} remove --help
+{% elif target.kind == "scope" and target.objectUri == "wikg://index" %}
+Library index object
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads this library index status.
+  - Library index data is stored in local Wiki Graph staging state, not in the library folder.
+  - Library-wide `--query`, scope enumeration, evidence, related, and pack commands require a current library index.
+
+Use when:
+  - You need to build, inspect, or drop the aggregate search index for a library.
+
+Usage:
+  {{ commandName }} {{ uri }} [--json]
+  {{ commandName }} {{ uri }} enable [--jsonl]
+  {{ commandName }} {{ uri }} disable [--json]
+
+Predicate commands:
+  - enable: rebuild this library index from registered present archives. Help: {{ commandName }} {{ uri }} enable --help
+  - disable: remove this library index materialization. Help: {{ commandName }} {{ uri }} disable --help
+
+Related help:
+  - Library registry, membership, path binding, and aggregate index concepts: {{ commandName }} help library
+{% else %}
+Library scope
+
+Default behavior:
+  - `{{ commandName }} {{ uri }}` reads this library scope.
+  - Use `{{ commandName }} wikg://lib/registry` to list all library registries.
+  - `{{ commandName }} {{ uri }} --query <query>` runs a broad library index search across indexed object types.
+  - `{{ commandName }} {{ uri }}/arc scan` reconciles membership with `.wikg` files currently under the library folder.
+  - Library-wide object scopes such as `/entity` and `/triple` query one object type through the library index after it is enabled.
+
+Use when:
+  - You need to manage a folder of `.wikg` archives as one library.
+  - You already moved or prepared a library folder and need Wiki Graph to bind this library to that existing directory.
+{% if target.isDefault %}
+  - You need to create another library registry.
+{% else %}
+  - You need to address a specific non-default library.
+{% endif %}
+
+URI forms:
+  - `{{ commandName }} wikg://lib` addresses the default library.
+  - `{{ commandName }} wikg://lib/<lib-id>` addresses a non-default library.
+  - `{{ commandName }} wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
+  - `{{ commandName }} wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
+
+Usage:
+{% if target.isDefault %}
+  {{ commandName }} wikg://lib
+  {{ commandName }} wikg://lib --query <query>
+  {{ commandName }} wikg://lib/chapter --query <query>
+  {{ commandName }} wikg://lib/chunk --query <query>
+  {{ commandName }} wikg://lib/registry add --path <folder> [--json]
+  {{ commandName }} wikg://lib/arc scan [--json|--jsonl]
+  {{ commandName }} wikg://lib/arc add --input <path> [--to <relative-wikg-path>] [--json]
+  {{ commandName }} wikg://lib/path set <existing-directory> [--json|--jsonl]
+  {{ commandName }} wikg://lib/arc/tree [--parent <relative-path>] [--depth <n>] [--json]
+  {{ commandName }} wikg://lib/index [--json]
+  {{ commandName }} wikg://lib/entity --query <query>
+  {{ commandName }} wikg://lib/triple --query <query>
+  {{ commandName }} wikg://lib/meta [--json]
+{% else %}
+  {{ commandName }} {{ uri }}
+  {{ commandName }} {{ uri }} --query <query>
+  {{ commandName }} {{ uri }}/chapter --query <query>
+  {{ commandName }} {{ uri }}/chunk --query <query>
+  {{ commandName }} {{ uri }}/arc scan [--json|--jsonl]
+  {{ commandName }} {{ uri }}/arc add --input <path> [--to <relative-wikg-path>] [--json]
+  {{ commandName }} {{ uri }}/path set <existing-directory> [--json|--jsonl]
+  {{ commandName }} {{ uri }}/arc/tree [--parent <relative-path>] [--depth <n>] [--json]
+  {{ commandName }} {{ uri }} remove --confirm [--json]
+  {{ commandName }} {{ uri }}/index [--json]
+  {{ commandName }} {{ uri }}/entity --query <query>
+  {{ commandName }} {{ uri }}/triple --query <query>
+  {{ commandName }} {{ uri }}/meta [--json]
+{% endif %}
+
+Predicate commands:
+{% if target.isDefault %}
+  - registry add: create a non-default library registry and an empty folder. Help: {{ commandName }} wikg://lib/registry add --help
+  - arc scan: reconcile registered archive memberships with `.wikg` files under the library folder. Help: {{ commandName }} wikg://lib/arc scan --help
+  - arc add: copy a `.wikg` file into the library folder and register it. Help: {{ commandName }} wikg://lib/arc add --help
+  - path set: bind the default library to an existing directory, then scan/reconcile its `.wikg` files. Help: {{ commandName }} wikg://lib/path set --help
+{% else %}
+  - arc scan: reconcile registered archive memberships with `.wikg` files under the library folder. Help: {{ commandName }} {{ uri }}/arc scan --help
+  - arc add: copy a `.wikg` file into the library folder and register it. Help: {{ commandName }} {{ uri }}/arc add --help
+  - path set: bind this library to an existing directory, then scan/reconcile its `.wikg` files. Help: {{ commandName }} {{ uri }}/path set --help
+  - remove: remove this library registry without deleting its folder. Help: {{ commandName }} {{ uri }} remove --help
+{% endif %}
+
+Related help:
+  - Library registry, membership, path binding, and aggregate index concepts: {{ commandName }} help library
+{% endif %}

package/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/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/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/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/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/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/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/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/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/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/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/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/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