wiki-graph 0.3.1 → 0.4.1

package/dist/data/help/topics/runtime.jinja

@@ -25,7 +25,7 @@ Generation job behavior:
   - Reading Graph, Reading Summary, and Knowledge Graph generation run as device-local jobs.
   - Generation jobs consume LLM tokens, may incur provider charges, and can run for minutes to hours on large archives.
   - `wikg://local/job add` requires `--accept-cost` as an explicit cost/time acknowledgement.
-  - Job records live under `~/.{{ commandName }}/jobs`.
+  - Job records live under `~/.wikigraph/jobs`.
   - `wikg://local/job add`, `wikg://local/job/<job-id> resume`, `wikg://local/job/<job-id> boost`, and `wikg://local/job/<job-id>/target set` try to start a transient worker.
   - The worker exits after idle time; it is not intended to be a permanent daemon.
   - `wikg://local/job/<job-id> watch --jsonl` is the stable agent-facing progress stream.
@@ -41,15 +41,30 @@ Progress and diagnostics:
 Workspace behavior:
   - Archive creation and EPUB import use temporary workspaces.
   - `transform --digest-dir <path>` uses the provided digest workspace for source digest runs.
-  - Generation jobs use per-job directories under `~/.{{ commandName }}/jobs/work`, `~/.{{ commandName }}/jobs/cache`, and `~/.{{ commandName }}/jobs/logs`.
+  - Generation jobs use per-job directories under `~/.wikigraph/jobs/work`, `~/.wikigraph/jobs/cache`, and `~/.wikigraph/jobs/logs`.
   - Succeeded jobs delete their workspace by default.
   - Failed and canceled jobs keep their workspace for debugging until cleanup.
   - Job events, logs, and LLM cache are kept until the job record is cleaned.
 
+Local state map:
+  - `~/.wikigraph/core.sqlite`: home registry and shared local state.
+  - `~/.wikigraph/cache/search-sessions.sqlite`: search query cache sessions used by paged search results.
+  - `~/.wikigraph/cache/continuation-cursors.sqlite`: opaque `wg next` continuation cursor records.
+  - `~/.wikigraph/cache/cache.sqlite`: Wikipedia page and other reusable local cache records.
+  - `~/.wikigraph/jobs`: durable generation job records, events, workspaces, caches, and logs.
+  - `~/.wikigraph/jobs/work`: per-job workspaces; failed and canceled jobs keep these for debugging.
+  - `~/.wikigraph/jobs/cache`: per-job LLM/cache artifacts kept with job records until cleanup.
+  - `~/.wikigraph/jobs/logs`: per-job diagnostic logs.
+  - `~/.wikigraph/staging`: archive coordinator state, materialized archive entries, local archive index staging, and library aggregate indexes.
+  - Search query caches and continuation cursors are local derived state; use `{{ commandName }} next --help` for cursor continuation and `{{ commandName }} gc --help` for cleanup.
+  - Do not manually delete active job, staging, or cursor state while commands are running; prefer `{{ commandName }} gc` and command-specific cleanup paths.
+
 In-place archive edits:
   - Mutating `.wikg` commands go through the archive coordinator.
   - Active generation jobs block destructive chapter maintenance edits for the same chapter.
-  - Archive writes are coordinated through `~/.{{ commandName }}/staging`.
+  - Archive writes are coordinated through `~/.wikigraph/staging`.
+  - Library aggregate indexes are local derived state under staging and can be removed by cleanup when orphaned.
+  - Library cursors store the library index scope and re-check index freshness before continuing.
 
 Where to go next:
   - Need the normal workflow before debugging:
@@ -60,3 +75,5 @@ Where to go next:
     {{ commandName }} help format
   - Need URI command routing:
     {{ commandName }} help uri
+  - Need library registry, membership, path binding, or index behavior:
+    {{ commandName }} help library

package/dist/data/help/topics/uri.jinja

@@ -8,7 +8,8 @@ Purpose:
   Use this page to choose a target, understand scope/object behavior, and select retrieval shape.
 
 Archive locator:
-  - Archive/object command URIs must contain a `.wikg` locator.
+  - Normal archive/object command URIs contain a `.wikg` locator.
+  - Library URIs and local runtime URIs are separate URI families and do not contain `.wikg` locators.
   - Do not pass a bare filesystem path as a command target.
     /Users/me/book.wikg -> wikg:///Users/me/book.wikg
     ./book.wikg -> wikg://book.wikg
@@ -19,17 +20,31 @@ Archive locator:
   - Home archive locators may start with `wikg://~/`; `~` is expanded only in that leading form.
   - The first path segment ending in `.wikg` is the archive/object boundary.
 
+Library locators:
+  - `wikg://lib` addresses the default library.
+  - `wikg://lib/<lib-id>` addresses a non-default library.
+  - Naked library scopes enumerate library-wide objects; `--query` on a naked library scope searches library-wide objects through the library index.
+  - Use explicit object lenses such as `/entity`, `/triple`, `/chapter`, or `/chunk` for archive object search.
+  - `wikg://lib/arc/<archive-id>/` addresses one archive membership in the default library.
+  - `wikg://lib/<lib-id>/arc/<archive-id>/` addresses one archive membership in a non-default library.
+  - Add ordinary archive object suffixes after the trailing slash to query a managed archive:
+    wikg://lib/arc/<archive-id>/chapter
+    wikg://lib/arc/<archive-id>/entity
+    wikg://lib/arc/<archive-id>/triple
+  - Library-wide scopes such as `wikg://lib/entity` query the aggregate library index.
+  - Read `{{ commandName }} help library` before managing registry, membership, path binding, or library index lifecycle.
+
 Short and located URIs:
   Commands may return short object URIs without local file paths:
-    wikg://chapter/3/title
-    wikg://chapter/3/source#4..8
+    wikg://chapter/part/title
+    wikg://chapter/part/source#4..8
     wikg://chunk/12
     wikg://entity/Q8018
     wikg://triple/Q8018/discusses/Q123
   Returned short URIs are archive-relative handles, not complete command targets.
   Add the archive locator before passing them back to commands:
     wikg://book.wikg/entity/Q8018
-    wikg:///books/book.wikg/chapter/3/source#4..8
+    wikg:///books/book.wikg/chapter/part/source#4..8
 
 Command routing:
   - `{{ commandName }} <scope-uri>` enumerates objects.
@@ -50,21 +65,27 @@ Common command shapes:
   {{ commandName }} <archive-uri> export --output-format <format>
   {{ commandName }} <archive-uri> inspect
   {{ commandName }} transform [options]
+  {{ commandName }} wikg://lib --help
+  {{ commandName }} wikg://lib/entity --query <query>
+  {{ commandName }} wikg://lib/arc/<archive-id>/entity --query <query>
   {{ commandName }} wikg://local/job
   {{ commandName }} wikg://local/job add --input <archive-uri|chapter-uri> --task <reading-graph|reading-summary|knowledge-graph> --accept-cost
   {{ commandName }} wikg://local/job/<job-id>
-  {{ commandName }} <object-uri> related
-  {{ commandName }} <object-uri> evidence
-  {{ commandName }} <object-uri> pack --budget 5000
 
 Scope URIs:
   Scope URIs enumerate objects by default. With `--query <query>`, they apply keyword retrieval within that scope.
+  A chapter URI used as a scope covers that chapter's full subtree by default.
+  Add `--depth <N>` to limit chapter subtree expansion:
+    - no `--depth`: full subtree
+    - `--depth 0`: only the current chapter, or root-level chapters for `<archive-uri>/chapter`
+    - `--depth 1`: current/root-level chapters plus direct children
+  `--depth` must include a non-negative integer value; naked `--depth`, negative values, and non-integers are invalid.
     wikg://book.wikg
     wikg://book.wikg/chapter
-    wikg://book.wikg/chapter/3
-    wikg://book.wikg/chapter/3/chunk
-    wikg://book.wikg/chapter/3/entity
-    wikg://book.wikg/chapter/3/triple
+    wikg://book.wikg/chapter/part
+    wikg://book.wikg/chapter/part/chunk
+    wikg://book.wikg/chapter/part/entity
+    wikg://book.wikg/chapter/part/triple
     wikg://book.wikg/chunk
     wikg://book.wikg/entity
     wikg://book.wikg/triple
@@ -74,15 +95,15 @@ Scope URIs:
 
 Object URIs:
   Object URIs read one object by default.
-    wikg://book.wikg/chapter/3/title
-    wikg://book.wikg/chapter/3/state
-    wikg://book.wikg/chapter/3/source
-    wikg://book.wikg/chapter/3/source#4..8
-    wikg://book.wikg/chapter/3/summary
-    wikg://book.wikg/chapter/3/summary#4..8
-    wikg://book.wikg/chapter/3/chunk/12
-    wikg://book.wikg/chapter/3/entity/Q8018
-    wikg://book.wikg/chapter/3/triple/Q8018/discusses/Q123
+    wikg://book.wikg/chapter/part/title
+    wikg://book.wikg/chapter/part/state
+    wikg://book.wikg/chapter/part/source
+    wikg://book.wikg/chapter/part/source#4..8
+    wikg://book.wikg/chapter/part/summary
+    wikg://book.wikg/chapter/part/summary#4..8
+    wikg://book.wikg/chapter/part/chunk/12
+    wikg://book.wikg/chapter/part/entity/Q8018
+    wikg://book.wikg/chapter/part/triple/Q8018/discusses/Q123
     wikg://book.wikg/chunk/12
     wikg://book.wikg/entity/Q8018
     wikg://book.wikg/entity/Q8018/wikipage
@@ -99,9 +120,12 @@ Triple pattern scopes:
   A complete triple URI with concrete subject, predicate, and object is an object URI.
 
 Object boundaries:
-  - `chapter/<id>` is a scope, not an object.
-  - `chapter/<id>/title` is the queryable chapter title object.
+  - `chapter/<path>` is a scope, not an object.
+  - `chapter/<path>/title` is the queryable chapter title object.
   - Whole `source` and `summary` objects are readable text streams, not collection scopes.
+  - Chapter-qualified scope URIs such as `<chapter-uri>/chunk`, `<chapter-uri>/entity`, and `<chapter-uri>/triple` expand to the chapter subtree and support `--depth`.
+  - Chapter-qualified resource and object URIs such as `/source`, `/summary`, `/title`, `/state`, `/chunk/<id>`, `/entity/<qid>`, and complete `/triple/<subject>/<predicate>/<object>` do not expand to subtrees and do not support `--depth`.
+  - `move`, `remove`, and `reset` are chapter node maintenance predicates; they target the chapter node itself, not the subtree. Use `remove --recursive` for explicit recursive deletion.
   - Ranged fragments such as `/source#4..8` and `/summary#4..8` are structured range objects.
   - Source and summary range numbers are 1-based and inclusive. `/source#1..2` means the first two source sentences.
   - Source text is the grounding material. `evidence` is not available for source, summary, or chapter scope URIs.
@@ -126,13 +150,13 @@ Lens selection:
   - `/chunk` targets Reading Graph chunks.
   - `/entity` targets grounded entities.
   - `/triple` targets Knowledge Graph relations.
-  - `chapter/<id>` is a scope; `--query` over chapter titles returns `chapter/<id>/title` objects.
+  - `chapter/<path>` is a scope; `--query` over chapter titles returns `chapter/<path>/title` objects.
 
 Literal source passages:
   Use `--query` on the narrowest useful scope when the task is to find source wording or passages mentioning a literal term:
     {{ commandName }} <archive-uri> --query "term"
-    {{ commandName }} <archive-uri>/chapter/<id> --query "term"
-    {{ commandName }} <archive-uri>/chapter/<id>/source#20..30
+    {{ commandName }} <archive-uri>/chapter/<path> --query "term"
+    {{ commandName }} <archive-uri>/chapter/<path>/source#20..30
 
 Entity-grounded evidence:
   Use entity evidence when you already have an entity URI or QID and need grounded mentions, aliases, translations, variants, or source-backed support:
@@ -143,6 +167,7 @@ Entity-grounded evidence:
 Pagination:
   - Use default paging or `--limit <n>` while exploring.
   - Use `{{ commandName }} next <cursor>` to continue a paged result.
+  - Use `{{ commandName }} next <uri> <cursor>` when you want the cursor's stored index scope checked against the archive or library URI you expect.
   - Use `--all` only when you intentionally need every item from the selected scope.
   - Prefer the narrowest scope before using `--all`.
   - Read `{{ commandName }} help format` before choosing text, `--json`, `--jsonl`, or `--all --jsonl` for machine consumption.
@@ -158,6 +183,7 @@ Recovery hints:
     {{ commandName }} help readiness
     {{ commandName }} help runtime
   - URI rejected: convert bare filesystem paths to Wiki Graph URIs, and prepend the archive locator to short object URIs.
+  - Library URI rejected: non-default libraries use wikg://lib/<lib-id>; archive members use <lib-scope>/arc/<archive-id>.
   - Help did not appear: append `--help` to the URI or URI-bound predicate you are trying to inspect.
 
 Job URIs:
@@ -176,3 +202,5 @@ Related help:
     {{ commandName }} help format
   - Local jobs, cache, logs, and runtime debugging:
     {{ commandName }} help runtime
+  - Library registry, membership, path binding, and aggregate index:
+    {{ commandName }} help library

package/dist/gc-worker.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node