@davidorex/pi-context 0.28.1 → 0.30.0

package/skills/pi-context/SKILL.md

@@ -46,6 +46,62 @@ Append a closure-table relation (edge: parent, child, relation_type, optional or
 | `child` | string | yes | Canonical id of the child endpoint |
 | `relation_type` | string | yes | Registered relation_type canonical_id / hierarchy edge type / lens id |
 | `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="remove-relation">
+Remove the single closure-table relation (edge) matching parent+child+relation_type from relations.json. Matches on the SAME (parent, child, relation_type) dedup identity append-relation uses, so it is the symmetric inverse of append-relation (ordinal is NOT part of identity). An absent edge is an idempotent no-op. Reference integrity is NOT checked here — run context-validate after if the removal changes resolvability.
+
+*Remove a relation/edge between two items (the inverse of append-relation)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `parent` | string | yes | Canonical id (or lens bin name) of the parent endpoint |
+| `child` | string | yes | Canonical id of the child endpoint |
+| `relation_type` | string | yes | Registered relation_type canonical_id / hierarchy edge type / lens id |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="replace-relation">
+Atomically replace one closure-table relation with another in a SINGLE write (no half-state: the old edge and the new edge never coexist on disk). The old edge is matched on the (parent, child, relation_type) dedup identity; the new edge is written with its optional ordinal. If the old edge is absent the call is effectively an append of the new edge. Reference integrity is NOT checked here — run context-validate after.
+
+*Atomically swap one relation/edge for another in a single write*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `old_parent` | string | yes | Parent endpoint selector of the edge to remove |
+| `old_child` | string | yes | Child endpoint selector of the edge to remove |
+| `old_relation_type` | string | yes | relation_type of the edge to remove |
+| `parent` | string | yes | Parent endpoint selector of the replacement edge |
+| `child` | string | yes | Child endpoint selector of the replacement edge |
+| `relation_type` | string | yes | relation_type of the replacement edge |
+| `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) for the new edge |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="append-relations">
+Append MANY closure-table relations to relations.json in a single write. Each edge is an object { parent, child, relation_type, ordinal? }. Per-(parent, child, relation_type) duplicates are skipped (against on-disk edges AND earlier edges in the same batch). Returns appended/skipped counts. Reference integrity is NOT checked here — run context-validate after. Creates relations.json if absent.
+
+*Create many relations/edges between items in one write*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `edges` | unknown | yes | JSON array of { parent, child, relation_type, ordinal? } selector objects (parent/child are id/lens-bin selectors) |
+| `dryRun` | boolean | no | Preview without writing relations.json |
+</tool>
+
+<tool name="upsert-block-item">
+Append-or-replace an item in a project block array by id: if an item with the same idField value exists it is REPLACED (full-shape replacement, not shallow-merge — use update-block-item for merge); otherwise the item is appended. Schema validation is automatic. idField defaults to 'id'.
+
+*Append-or-replace a full block item by id (replacement, not merge)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
+| `arrayKey` | string | yes | Array key in the block (e.g., 'issues', 'decisions') |
+| `item` | unknown | yes | Full item object to upsert — must conform to block schema |
+| `idField` | string | no | Field used as the upsert key (default 'id') |
+| `dryRun` | boolean | no | Preview the upsert without writing |
 </tool>
 
 <tool name="promote-item">
@@ -201,9 +257,9 @@ Derive 'where are we + what's next' purely from the substrate — focus, in-flig
 </tool>
 
 <tool name="context-bootstrap-state">
-Derive the substrate bootstrap state for the cwd, purely from the filesystem: 'no-pointer' | 'no-config' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.
+Derive the substrate bootstrap state for the cwd, purely from the filesystem: 'no-pointer' | 'no-config' | 'skeleton' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Bootstrap (/context init or /context switch -c <new-dir>) now writes a minimal schema-valid config empty of vocabulary, so a freshly-bootstrapped substrate lands at 'skeleton' — onward via /context accept-all (adopt the packaged catalog, then /context install) OR amend-config / edit (build a custom vocabulary). Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.
 
-*Derive substrate bootstrap state — no-pointer | no-config | not-installed | ready (never throws pre-bootstrap)*
+*Derive substrate bootstrap state — no-pointer | no-config | skeleton | not-installed | ready (never throws pre-bootstrap)*
 
 </tool>
 
@@ -275,9 +331,9 @@ Declare a schema version-bump migration into substrate (migrations.json). operat
 </tool>
 
 <tool name="context-init">
-Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate).
+Initialize the substrate dir: bootstrap pointer + dirs + a minimal schema-valid SKELETON config empty of vocabulary. Lands at the 'skeleton' bootstrap state — onward via accept-all (adopt the packaged catalog, then install) OR amend-config / edit (build a custom vocabulary).
 
-*Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate)*
+*Initialize the substrate dir (bootstrap pointer + dirs + skeleton config; onward via accept-all OR amend-config/edit)*
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -285,7 +341,7 @@ Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + in
 </tool>
 
 <tool name="context-accept-all">
-Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Idempotent: never overwrites an existing config.
+Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Skeleton-aware: overwrites a SKELETON config (the empty-of-vocabulary config init / switch -c writes) but never a POPULATED one.
 
 *Adopt the canonical conception as config (accept-all)*
 
@@ -299,7 +355,7 @@ Flip the bootstrap pointer to a different substrate dir (parallel to git switch)
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `target_dir` | string | yes | Substrate dir name to switch to (e.g. '.context'). Required for default + create_new modes; ignored for to_previous mode. |
-| `create_new` | boolean | no | When true, bootstrap target_dir as a fresh substrate AND flip the pointer in one operation (parallel to 'git switch -c <branch>'). Default false (flip to existing substrate; fails if target_dir lacks config.json). |
+| `create_new` | boolean | no | When true, bootstrap target_dir as a fresh substrate (dirs + a minimal schema-valid SKELETON config empty of vocabulary — onward via accept-all OR amend/edit) AND flip the pointer in one operation (parallel to 'git switch -c <branch>'). Default false (flip to existing substrate; fails if target_dir lacks config.json). |
 | `to_previous` | boolean | no | When true, flip the pointer back to its previous_contextDir (parallel to 'git switch -'). Requires the pointer to carry a previous_contextDir (a prior switch must have populated it). When true, target_dir is ignored. |
 | `writer` | object | no | DispatchContext.writer — stamped by auth-gate on operator confirm; in-body trusts the stamped value. |
 </tool>
@@ -319,7 +375,6 @@ Move a non-active substrate dir to archive/<dir>/. Refuses to archive the active
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `target_dir` | string | yes | Substrate dir name to archive (e.g. '.project'). Refused if it is the active substrate. |
-| `writer` | object | no | DispatchContext.writer — stamped by auth-gate on operator confirm. |
 </tool>
 
 <tool name="filter-block-items">