@younndai/lyt-skills 0.9.0

package/skills/lyt-pod/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: lyt-pod
+description: >
+  Overview of the user's Lyt pod — enumerates all meshes and vaults on this machine, grouped by mesh, with orphan vaults surfaced separately and summary stats (mesh count, vault count, pushable/subscriber/orphan breakdown). Trigger when the user runs /lyt-pod, or says "what's in my pod", "show me my pod", "give me a pod overview", "list all my vaults", "what meshes do I have", "show me everything in my pod", or similar phrasing on a pod-scoped enumeration. Composes `lyt mesh list --json` (mesh-level records) + `lyt vault list --json` (vault-level records) into one agent-facing summary. Read-only; pairs with /lyt-primer-context (agent priming with active arcs + writable status) and /lyt-search (query across the pod).
+visibility: public
+lyt-version: 0.7.0
+capabilities: [read]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-pod
+
+Render an agent-facing overview of the user's Lyt **pod** — every mesh and every vault on this machine — by composing two CLI verbs:
+
+1. `lyt mesh list --json` (shipped v1.B.1) — enumerates meshes the user participates in, including each mesh's main vault, home vaults, and subscribed vaults. Canonical mesh-enumeration verb per `packages/lyt-vault/src/commands/mesh.ts:277` (`buildMeshListSubcommand`).
+2. `lyt vault list --json` (shipped pre-v1.G.1) — enumerates every registered vault on the machine, with status, path, and per-vault metadata (mesh role, parent vault, tier hint). Canonical vault-enumeration verb per `packages/lyt-vault/src/commands/list.ts:6` (`buildListCommand`).
+
+The skill is pure prose around two existing CLI verbs — there is no new CLI verb, no new helper, no lyt-vault change. Both verbs always run on every invocation (default = full pod overview); user signal can narrow the synthesis focus post-facto but does NOT change which verbs run.
+
+User-facing language uses **"pod"** throughout — never "federation". "Mesh" stays user-facing (it's the actual unit of grouping). "Federation" is reserved for internal data-layer prose.
+
+## When to invoke
+
+When the user runs `/lyt-pod`, or says something like:
+
+- "what's in my pod"
+- "show me my pod"
+- "give me a pod overview"
+- "list all my vaults"
+- "what meshes do I have"
+- "show me everything in my pod"
+- "summarize my Lyt setup"
+- "what's on this machine"
+
+Invoke this skill **proactively** as the first move whenever the user asks a pod-scoped enumeration question or seems to want a survey of what's installed. Don't bypass it and start grep'ing the filesystem — the registry is the source of truth.
+
+If the user wants to drill into a single mesh (vault list + edges for one mesh), prefer `/lyt-mesh-explore` (post-Wave-3 G.9) once it ships. If the user wants per-vault writable status or agent priming, use `/lyt-primer-context`.
+
+## Phase 1 — Determine pod-scope intent
+
+The default is **full pod overview** — both verbs run, every mesh and vault rendered. Pick by the user's wording:
+
+- **Default — full pod overview.** Use when the user says "my pod", "show me everything", "list all vaults", "what meshes do I have", or omits scope entirely. Run both verbs (Phase 2 + Phase 3) and synthesize a complete pod summary in Phase 4.
+- **Narrow framing on a single mesh.** Use when the user says "focus on the `<name>` mesh", "just show me the `<name>` mesh's vaults", "what's in the `<name>` mesh". **Still run BOTH `lyt mesh list --json` and `lyt vault list --json`** — the CLI verbs do not support `--mesh` filtering on `lyt vault list`. Apply the user's narrow framing at **synthesis time** (Phase 4) by filtering the rendered output. Do NOT invent a CLI flag.
+- **Tombstoned-vault inclusion.** Default = hide soft-tombstoned rollup aggregates (matches CLI default per `packages/lyt-vault/src/commands/list.ts:11-19`). Pass `--include-tombstones` ONLY when the user explicitly says "show tombstoned vaults too", "include deleted vaults", "show buried vaults". Hard-tombstoned vaults (`status='tombstoned'`) are included in the default `lyt vault list` output already; `--no-tombstones` filters them out (do NOT pass by default — they are part of the pod's recent history).
+
+The skill never invents mesh or vault names. If the user names one and the post-Phase-2/3 synthesis can't match it, surface the available names and stop — do not guess.
+
+## Phase 2 — Enumerate meshes
+
+Run the verb via the Bash tool (or your runtime's shell equivalent). **Pass the argv as an array; never shell-compose the command.** Precedent: lyt-sync's Phase 3 (`spawnSync("git", [..., "-m", message])`), lyt-search's Phase 2 (`spawnSync("lyt", ["search", userQuery, "--json"])`), lyt-primer-context's Phase 2 (`spawnSync("lyt", ["primer", "--scope", scope, ...])`) — same argv-array shape, cross-platform-safe.
+
+```
+# Shell-syntax (DOCUMENTATION ONLY — do NOT compose this as a string):
+lyt mesh list --json
+
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("lyt", ["mesh", "list", "--json"]);
+```
+
+The CLI emits Lock 0.3 stable-key-ordered JSON on stdout (exit 0 on success). The actual emitted shape (per `packages/lyt-vault/src/commands/mesh.ts:283-317`):
+
+```json
+{
+  "meshes": [
+    {
+      "rid": "mesh:<hex>",
+      "rid_hex": "<hex>",
+      "name": "<mesh-name>",
+      "push_target": "<gh-target>" | null,
+      "push_kind": "handle" | "org" | null,
+      "main_vault": {
+        "rid": "vault:<hex>",
+        "rid_hex": "<hex>",
+        "name": "<vault-name>"
+      } | null,
+      "home_vaults": [
+        { "rid": "vault:<hex>", "rid_hex": "<hex>", "name": "<vault-name>" }
+      ],
+      "subscribed_vaults": [
+        { "rid": "vault:<hex>", "rid_hex": "<hex>", "name": "<vault-name>" }
+      ]
+    }
+  ]
+}
+```
+
+`home_vaults` includes the main vault (it's a home vault with the additional `★` marker captured separately as `main_vault.rid_hex`). `subscribed_vaults` is the cross-mesh subscription role (mesh M subscribes to vault V owned by another mesh).
+
+Empty registry: `{ "meshes": [] }`. Surface "no meshes yet — run `lyt mesh init <name>` to create one" in Phase 4 if both meshes AND vaults arrays are empty.
+
+## Phase 3 — Enumerate vaults
+
+Same argv-array invocation pattern.
+
+```
+# Shell-syntax (DOCUMENTATION ONLY):
+lyt vault list --json
+
+# Actual exec shape:
+spawnSync("lyt", ["vault", "list", "--json"]);
+
+# Counter-case — user explicitly asked for tombstoned-rollup inclusion:
+spawnSync("lyt", ["vault", "list", "--json", "--include-tombstones"]);
+```
+
+The CLI emits Lock 0.3 stable-key-ordered JSON on stdout (per `packages/lyt-vault/src/commands/list.ts:46-49` + `packages/lyt-vault/src/flows/list.ts:32-40`):
+
+```json
+{
+  "vaults": [
+    {
+      "rid": { "0": <int>, "1": <int>, "...": <int>, "15": <int> },
+      "ridHex": "<hex>",
+      "name": "<vault-name>",
+      "path": "<absolute-path>",
+      "memscopeRid": { "0": <int>, ... } | null,
+      "memscopeRidHex": "<hex>" | null,
+      "parentVault": { "0": <int>, ... } | null,
+      "parentVaultHex": "<hex>" | null,
+      "homeMeshRid": { "0": <int>, ... } | null,
+      "homeMeshRidHex": "<hex>" | null,
+      "tierHint": "<string>" | null,
+      "status": "active" | "disconnected" | "missing" | "tombstoned" | "access_lost",
+      "gitUrl": "<url>" | null,
+      "createdAt": "<iso>" | null,
+      "registeredAt": "<iso>",
+      "lastVerifiedAt": "<iso>" | null,
+      "verifyFailCount": 0
+    }
+  ],
+  "rollupTombstones": { ... },        // only when --include-tombstones is passed
+  "rollupThresholdDays": <int>,       // only when --include-tombstones is passed
+  "rollupThresholdIso": "<iso>"       // only when --include-tombstones is passed
+}
+```
+
+**Field-type note (release review).** The four byte-typed fields (`rid`, `memscopeRid`, `parentVault`, `homeMeshRid`) are `Uint8Array` instances at the source (`packages/lyt-vault/src/registry/repo.ts:22-32`) and pass through `JSON.stringify(result, null, 2)` raw at `commands/list.ts:48`. `JSON.stringify` serializes a `Uint8Array` as a **byte-indexed object** (`{"0": 123, "1": 45, ..., "15": 254}`), NOT a hex string. **Always match on the `*Hex` companion fields** (`ridHex`, `memscopeRidHex`, `parentVaultHex`, `homeMeshRidHex`) — those are guaranteed-string and stable. Treat the raw byte-fields as opaque implementation detail.
+
+The vault-list output is the source of truth for **per-vault mesh membership** — match each vault's `homeMeshRidHex` (string) against each mesh's `rid_hex` (string) from Phase 2 to group vaults under their mesh in Phase 4. A vault with `homeMeshRidHex === null` is an **orphan** (registered but not adopted into any mesh — see Phase 4's orphan section).
+
+Empty registry: `{ "vaults": [] }`. Surface "no vaults registered yet — run `lyt vault init <name>` to create one" in Phase 4 if both meshes AND vaults arrays are empty.
+
+## Phase 4 — Synthesize pod-overview
+
+Render the pod summary as a markdown block. The handler-facing layout:
+
+```
+# Your pod
+
+**Summary:** <N> mesh<es> · <M> vault<s> (<P> pushable · <S> subscriber · <O> orphan)
+
+## Meshes
+
+### `<mesh-1-name>` (<K> home vault<s><, J subscribed>)
+
+- ★ `<main-vault-name>` — main vault · push target: `<push_kind>:<push_target>`
+- `<home-vault-name>` — home vault
+- ...
+- `<subscribed-vault-name>` — subscribed (cross-mesh)
+
+### `<mesh-2-name>` (<K> home vault<s>)
+
+- ★ `<main-vault-name>` — main vault
+- ...
+
+## Orphan vaults (no mesh role)
+
+- `<orphan-vault-name>` — heal via `lyt repair --target <orphan-vault-name> --apply --mesh <mesh>` (binds a registered vault to a mesh); `lyt mesh adopt` discovers + adopts gh clusters
+- ...
+```
+
+Synthesis rules:
+
+- **Summary line.** `N meshes` = `meshes.length` from Phase 2. `M vaults` = `vaults.length` from Phase 3 (filter out `status='tombstoned'` unless the user explicitly asked for tombstoned inclusion). The `(P pushable · S subscriber · O orphan)` breakdown counts each vault **once** by primary role, with precedence **home > subscriber > orphan** (a vault appearing in BOTH a `home_vaults` array AND any `subscribed_vaults` array is counted as **home**, not subscriber): a vault is **pushable** if it appears in any mesh's `home_vaults` AND that mesh has a non-null `push_target`; **subscriber** if it appears ONLY in `subscribed_vaults` arrays across all meshes (never as a home vault); **orphan** if its `homeMeshRidHex === null` (no mesh role at all).
+- **Mesh grouping.** Sort meshes by name (alphabetical) for stable rendering. Within each mesh: main vault first (marked `★` per `commands/mesh.ts:333` precedent), then other home vaults sorted alphabetically (exclude the main-vault entry from this alphabetic list — it already rendered above with `★`; `home_vaults` includes the main vault per Phase 2 shape, so an LLM iterating the array verbatim would otherwise double-render the main vault), then subscribed vaults grouped at the end with a "subscribed (cross-mesh)" hint.
+- **Push-target hint.** Surface `push target: <push_kind>:<push_target>` next to the main vault when `push_target !== null`. Skip the hint when null (mesh is local-only).
+- **Orphan section.** Always include the heading even when empty (rendering "(none)" under it) — handlers parsing the output can rely on the section's presence. Each orphan vault gets a one-line heal suggestion: `lyt repair --target <orphan-vault-name> --apply --mesh <mesh>` (the canonical heal — binds a registered vault to a known mesh). A vault that is _registered-but-mesh-unlinked_ (the adopt mesh-link drift) heals via `lyt repair --apply` with **no args** (`lyt doctor` flags it). `lyt mesh adopt` remains for gh **cluster-discovery** of un-registered repos — not for re-linking an already-registered vault.
+- **User narrow framing.** If the user signaled a single mesh in Phase 1, render only that mesh's section under `## Meshes` plus the orphan section. Surface a one-line "(showing 1 of N meshes — re-invoke /lyt-pod for full overview)" hint.
+- **Large pod truncation.** If the combined vault count exceeds ~50 across all meshes, render the summary line + per-mesh counts and offer a "show all with `lyt vault list`" follow-up rather than dumping every vault inline. Do not silently drop entries.
+- **Empty pod.** If both `meshes.length === 0` AND `vaults.length === 0`, render: "**Your pod is empty.** Run `lyt mesh init <name>` to create your first mesh, or `lyt vault init <name>` to register a standalone vault. See `/lyt-mesh-explore` once you have one."
+- **Use "pod" framing throughout.** Never write "federation" in handler-facing prose. "Mesh" is user-facing (the actual group). "Pod" is the user's set of meshes + vaults on this machine.
+
+## Rules
+
+- **MUST pass argv as an array** (`spawnSync("lyt", ["mesh", "list", "--json"])` and `spawnSync("lyt", ["vault", "list", "--json"])`), not template-interpolated into a shell command string. Both verbs accept simple argv with no user-supplied tokens, so the shell-injection surface is small — but argv parity matches lyt-sync + lyt-search + lyt-primer-context for cross-platform reliability.
+- **MUST pass `--json`** on every invocation. Human-readable output is not a contract this skill parses.
+- **MUST run BOTH verbs on every invocation.** The default is full pod overview; even when the user signals a narrow mesh framing, the vault list is needed to compute the orphan section and the summary-line counts. Do not skip one verb to "save time" — synthesis quality drops.
+- **MUST use "pod" framing in user-facing output.** Never write "federation" in handler-facing prose; "federation" is internal data-layer vocabulary only.
+- **MUST surface the orphan-vault section** even when empty (render "(none)" under the heading) so handlers can rely on its presence.
+- **MUST cite `lyt mesh list` as the canonical mesh-enumeration verb.** Some sibling SKILL.md files cite a different mesh-enumeration verb that does not exist; the canonical verb is `lyt mesh list` per `packages/lyt-vault/src/commands/mesh.ts:277`. Do not propagate the sibling error here.
+- **MUST cite `lyt vault info <name>` with a positional argument only.** The verb accepts a positional `<name>` per `packages/lyt-vault/src/commands/info.ts:20-26`; the only flag is `--json`. The pod skill does not call `vault info` at all (per-vault writable status is `/lyt-primer-context`'s job — pulling it here would duplicate that surface).
+- **MUST NOT pass `--include-tombstones` by default.** Pass only on explicit user signal ("show tombstoned vaults", "include deleted vaults", "show buried vaults"). Default = hide soft-tombstoned rollup aggregates per CLI default.
+- **MUST NOT pass `--no-tombstones` by default.** Hard-tombstoned vaults (`status='tombstoned'`) are part of the pod's recent history; rendering them with a `[tombstoned]` status marker is the correct default. Pass `--no-tombstones` only on explicit user signal ("hide tombstones", "skip buried vaults").
+- **MUST NOT modify or write any file.** This is a read-only skill (`requires_writable_vault: false`). If the user wants the pod overview persisted to a Figment, run `/lyt-capture` separately on the formatted output.
+- **MUST NOT shell-compose any verb invocation.** Argv-array always (parity with lyt-sync + lyt-search + lyt-primer-context).
+- **MUST NOT invent CLI flags for filtering.** The CLI verbs do not support `--mesh` filtering on `lyt vault list`; user narrow framing is synthesis-time filtering in Phase 4, not CLI-level filtering.
+
+## Companion skills
+
+- **/lyt-mesh-explore** — drill into a single mesh (vault list + edges + subscriptions). Pair after `/lyt-pod` when the user picks one mesh to investigate (post-Wave-3 G.9).
+- **/lyt-primer-context** — prime an agent with Lyt-scoped context (top keywords, active arcs, writable status). Pair after `/lyt-pod` when the user wants the agent to start working in a specific vault — use `--scope vault --target <name>` per the chosen vault.
+- **/lyt-search** — query across the pod with the tiered-cascade engine. Pair after `/lyt-pod` when the user wants to look up specific content rather than survey what exists.
+- **/lyt-sync** — pull/commit/push a vault. Run before `/lyt-pod` if the user has unpushed local edits and wants the registry to reflect them (registry rows update on vault init/adopt; `/lyt-sync` doesn't change the pod shape but does freshen `lastVerifiedAt`).

package/skills/lyt-primer-context/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: lyt-primer-context
+description: >
+  Prime an agent with Lyt-scoped context — for a vault, a mesh, or the whole pod — by composing `lyt primer` (top keywords + active arcs + recent activity + top lanes) and `lyt vault info --json` (writable status for vault-scope). Trigger when the user runs /lyt-primer-context, or says "prime me for X", "give me context on this vault", "what's been happening in my pod lately", "what arcs are active in mesh Y", "give the agent context before X", or similar phrasing on a scope they want surfaced for agent priming. Wraps `lyt primer` (v1.D.4) + `lyt vault info --json` (v1.G.2 6-reason writable contract) — composes both into an agent-facing summary. Read-only; pairs with /lyt-search (query-driven recall) and /lyt-capture (write).
+visibility: public
+lyt-version: 0.6.0
+capabilities: [read]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-primer-context
+
+Prime an agent with Lyt-scoped context for a **vault**, a **mesh**, or the whole **pod** by composing two CLI verbs:
+
+1. `lyt primer --scope <vault|mesh|federation> [--target <name>] --json --dry-run` (shipped v1.D.4) — aggregates top keywords, active arcs, recent activity, and top lanes across the scope into a Lock 0.3 stable-key-ordered JSON payload (including the full primer markdown body).
+2. `lyt vault info <name> --json` (shipped v1.G.2; 6-reason writable contract) — only for vault-scope priming, fetches `writable` + `writableDetermination` so the skill can surface a capability hint to the agent ("you can /lyt-capture here" vs reason-specific guidance).
+
+The skill is pure prose around two existing CLI verbs — there is no new CLI verb, no new helper, no lyt-vault change. The skill READS; it does not write (except the CLI's atomic primer-file write on non-dry-run, which is opt-in per Phase 2 the ratified default).
+
+## When to invoke
+
+When the user runs `/lyt-primer-context`, or says something like:
+
+- "prime me for `<vault|mesh|pod-scoped task>`"
+- "give me context on this vault"
+- "what's been happening in my pod lately"
+- "what arcs are active in mesh `<name>`"
+- "give the agent context before `<task>`"
+- "prime the agent for working in `<vault>`"
+- "what's the current state of my `<mesh>` mesh"
+
+Invoke this skill **proactively** before a knowledge-work task whenever the agent needs scope-wide situational awareness (recent activity, dominant themes, in-progress arcs). Don't bypass it and start fabricating context.
+
+## Phase 1 — Determine scope + target from user signal
+
+The `lyt primer` verb requires `--scope` and rejects ambiguity. Pick by the user's wording (default is federation when no scope signal):
+
+- **Default — federation (entire pod, every vault across every mesh).** Use when the user says "my pod", "all my vaults", "across everything", or omits scope entirely. Invocation: `lyt primer --scope federation --json --dry-run` (no `--target`; CLI ignores it for federation scope).
+- **Single mesh.** Use `--scope mesh --target <name>` when the user says "in mesh `<name>`", "for the `<name>` mesh", "across my `<name>` mesh".
+- **Single vault.** Use `--scope vault --target <name>` when the user says "in vault `<name>`", "for my `<name>` vault", "for this vault". For "this vault", resolve from the env-default chain (mirrors lyt-sync Phase 1): `$LYT_ACTIVE_VAULT` env var, then `~/lyt/vaults/<handle>/main/` convention, then ask the user — do not guess from cwd.
+
+**Resolve names before passing them.** Don't guess at mesh/vault names — when the user names one:
+
+1. Run `lyt vault list --json` (vaults) or `lyt mesh list --json` (meshes) first. `lyt mesh list` is the canonical mesh-enumeration verb (per `packages/lyt-vault/src/commands/mesh.ts:32`); both verbs emit Lock 0.3 stable-key-ordered JSON on `--json`.
+2. Match the user's term to the listed names (exact, then case-insensitive, then prefix).
+3. **Reject any resolved name that begins with `-` or `--`** before passing it to `--target <name>` — closes the flag-injection surface the same way lyt-sync (Phase 1) and lyt-search (Phase 1) do (family: G.2 CR-1 gh-flag-injection). Vault and mesh names are user-controlled at vault-init / mesh-create time; a vault literally named `--evil` would otherwise smuggle a flag-shaped token into the verb's argv.
+4. If no match (or the only match is `--`-leading), tell the user the available names and stop — do not invent a name.
+
+The `--scope federation` invocation MUST NOT pass `--target` — the CLI ignores it for federation scope but it's noise; only pass `--target` for vault/mesh scopes.
+
+## Phase 2 — Invoke `lyt primer`
+
+Run the verb via the Bash tool (or your runtime's shell equivalent). **Pass scope and target as separate argv arguments; never shell-compose the command.** The matching precedent is lyt-search's Phase 2 (`spawnSync("lyt", ["search", userQuery, "--json"])`) and lyt-sync's Phase 3 (`spawnSync("git", ["-C", vaultPath, "commit", "-m", message])`) — argv-array shape, cross-platform-safe.
+
+```
+# Shell-syntax (DOCUMENTATION ONLY — do NOT compose this as a string):
+lyt primer --scope <scope> [--target <name>] --json --dry-run
+
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("lyt", ["primer", "--scope", scope, "--target", target, "--json", "--dry-run"]);
+# or for federation scope (no --target):
+spawnSync("lyt", ["primer", "--scope", "federation", "--json", "--dry-run"]);
+```
+
+Key rules:
+
+- `--scope` is **mandatory** (CLI rejects with `error: "invalid-scope"`, exit 1, if missing or unrecognised). The skill always passes one; default to `federation` when no user signal.
+- `--target <name>` is **required** for `--scope vault` and `--scope mesh`; **omitted** for `--scope federation`. CLI rejects missing target with `error: "missing-target"`, exit 1.
+- `--json` is **mandatory** for this skill. Without it, the CLI prints human-readable output that the skill can't reliably parse.
+- `--dry-run` is the **default for this skill** (ratified default). The CLI's non-dry-run mode atomically writes the primer markdown to `<vault>/.lyt/primers/{scope}-primer.md`; the skill READS the result for agent priming and does not need that persisted file as a side-effect of every invocation. Pass `--dry-run` unless the user explicitly asks to regenerate the on-disk primer ("refresh the primer file", "regenerate the on-disk primer" — then omit `--dry-run`).
+- `--top-keywords <n>`, `--top-arcs <n>`, `--provenance-days <n>` are advanced flags. Apply only when the user explicitly signals a cap ("top 50 keywords", "last 30 days of activity"); otherwise rely on CLI defaults (20 / 10 / 7).
+
+## Phase 3 — Parse the JSON output
+
+The CLI emits Lock 0.3 stable-key-ordered JSON on stdout (exit 0 on success). The actual emitted shape (per `packages/lyt/src/commands/primer.ts:174-215`):
+
+```json
+{
+  "scope": "vault" | "mesh" | "federation",
+  "scopeTarget": "<name>" | null,
+  "primerPath": "<vault>/.lyt/primers/<scope>-primer.md" | null,
+  "dryRun": true | false,
+  "vaultsScanned": ["<vault1>", "<vault2>"],
+  "topKeywords": [
+    { "keyword": "<term>", "score": 0.92, "totalMemCount": 12, "lastSeen": "ISO8601" }
+  ],
+  "topArcs": [
+    {
+      "name": "<arc-name>",
+      "category": "<category>",
+      "lastTouched": "ISO8601",
+      "vaultName": "<vault>",
+      "memberCount": 7
+    }
+  ],
+  "recentActivity": [
+    {
+      "ts": 1717200000,
+      "tsIso": "ISO8601",
+      "targetType": "<kind>",
+      "targetId": "<rid-or-id>",
+      "src": "<source>",
+      "vaultName": "<vault>",
+      "idHex": "<rid-hex>"
+    }
+  ],
+  "topLanes": [
+    { "name": "<lane-name>", "keywords": ["<kw1>", "<kw2>"], "memCount": 5, "vaultName": "<vault>" }
+  ],
+  "markdown": "<full primer markdown body — what would be written to .lyt/primers/{scope}-primer.md>",
+  "durationMs": 47
+}
+```
+
+On `--dry-run`: `primerPath` is the path the CLI WOULD write to (not null — it's pre-computed), but no file is written. `dryRun: true` confirms this. On non-dry-run: `dryRun: false` and the file at `primerPath` is freshly written (atomic).
+
+Failure modes (CLI emits to stderr; exit non-zero):
+
+- **Invalid scope** (exit 1) → `{ "error": "invalid-scope", "value": "<bad>", "message": "..." }`. Skill-level bug if hit — Phase 1 should have prevented it; surface the message and stop.
+- **Missing target** (exit 1) → `{ "error": "missing-target", "scope": "<vault|mesh>", "message": "..." }`. Skill-level bug — Phase 1 should have resolved a name; surface and stop.
+- **Invalid `--top-keywords` / `--top-arcs` / `--provenance-days`** (exit 1) → `{ "error": "invalid-<flag>", "value": "<bad>", "message": "..." }`. Re-invoke with CLI defaults.
+- **Underlying flow throws** (exit 2) → `{ "error": "primer-generate-error", "message": "..." }`. Surface verbatim; suggest a narrower scope.
+
+## Phase 4 — Fetch writable status (vault-scope ONLY)
+
+**Skip this phase for `--scope mesh` and `--scope federation`** — those scopes span multiple vaults and there's no single writable status to surface (per the ratified default). For mesh/federation, jump to Phase 5 and present the primer summary alone. The agent can re-invoke `/lyt-primer-context` per-vault with `--scope vault --target <name>` if it needs write-action guidance for a specific vault.
+
+For `--scope vault --target <name>`, invoke `lyt vault info <name> --json` via Bash (argv-array form):
+
+```
+# Shell-syntax (DOCUMENTATION ONLY):
+lyt vault info <name> --json
+
+# Actual exec shape:
+# `vaultName` MUST be the same Phase-1-resolved name (already passed through
+# the `--`-leading rejection check); do not re-resolve from a different source
+# at Phase 4, or the flag-injection defense is dropped.
+spawnSync("lyt", ["vault", "info", vaultName, "--json"]);
+```
+
+Parse the `vault.writable` + `vault.writableDetermination` fields per the v1.G.2 read-only-awareness contract (see `packages/lyt-vault/src/flows/writability.ts:42-48`). The verdict is tri-state (`true | false | "unknown"`); the determination is one of **6 reasons** the skill must branch on explicitly in Phase 5.
+
+## Phase 5 — Synthesize agent-facing context
+
+Render the agent-priming output as a markdown block. Layout:
+
+```
+# Primer for <scope>: <target-or-pod>
+
+**Top keywords:** <keyword1> (<score1>) · <keyword2> (<score2>) · … · <keywordN> (<scoreN>)
+
+**Active arcs (top-N):**
+- <arc-name> · <category> · last touched <ISO> · vault <vault> · <memberCount> members
+- …
+
+**Active lanes (top-N):**
+- <lane-name> · keywords [<kw1>, <kw2>] · <memCount> members · vault <vault>
+- …
+
+**Recent activity (last N days):**
+- <tsIso> — <targetType> in <vaultName>: <targetId>
+- …
+
+**Capability hint (vault-scope only):**
+<one of the 6 reason-specific messages — see the table below>
+
+**Primer markdown** (full body, truncated to ≤200 lines with ellipsis if longer):
+<markdown payload from CLI>
+```
+
+### Capability hint — 6-reason writable contract (vault-scope only)
+
+For vault-scope invocations, surface a reason-specific capability hint based on `writable` + `writableDetermination`. The actual reason strings emitted by `vault info --json` (per `packages/lyt-vault/src/flows/writability.ts`) are listed in the **emitted name** column. The **semantic name** column gives the human-readable synonym some briefs use; the SKILL.md handler-facing prose uses the semantic name, but the comparison MUST be against the emitted name.
+
+| Emitted name (writableDetermination) | Semantic name               | writable    | Phase 5 capability hint                                                                                                                                                                                                                           |
+| ------------------------------------ | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gh-viewerCanPush-true`              | **home-pushable-true**      | `true`      | ✓ This vault is yours and pushable — you can `/lyt-capture` here.                                                                                                                                                                                 |
+| `gh-viewerCanPush-false`             | **home-not-pushable-false** | `false`     | ⚠ This vault is yours but you lack push permission. Request write access from the owner, or capture into a vault you own.                                                                                                                         |
+| `subscriber-default-false`           | (subscriber)                | `false`     | ⚠ This is a subscriber vault — pull-only. Capture into your home vault instead.                                                                                                                                                                   |
+| `gh-unavailable`                     | (gh-offline)                | `"unknown"` | ⚠ Writable status unknown — gh CLI offline / rate-limited. Re-check when network is available.                                                                                                                                                    |
+| `no-remote`                          | (no-remote)                 | `"unknown"` | ⚠ Writable status unknown — vault has no git remote configured. Configure with `gh repo create` or `git remote add origin <url>`.                                                                                                                 |
+| `orphan-vault`                       | (orphan)                    | `"unknown"` | ⚠ Writable status unknown — vault has no mesh role (orphan). Heal: `lyt repair --apply` (fixes the adopt mesh-link drift, no args needed); a truly un-adopted vault: `lyt repair --target <vault> --apply --mesh <mesh>`. `lyt doctor` diagnoses. |
+
+**Note on emitted vs semantic names.** The brief that authored this skill (v1.G.7 handoff) lists `home-pushable-true` / `home-not-pushable-false` as semantic aliases for the first two reasons. The actual strings emitted by `writability.ts` are `gh-viewerCanPush-true` / `gh-viewerCanPush-false`. The semantic names are kept here as documentation aliases so future renames of the underlying enum (e.g. when the gh-probe naming hardens in v1.G.2.1) don't silently break the skill prose. The 4 unchanged reason strings (`subscriber-default-false`, `gh-unavailable`, `no-remote`, `orphan-vault`) match in both surfaces. **Comparison code MUST use the emitted name; handler-facing prose uses either.**
+
+## Rules
+
+- **MUST pass `--scope`, `--target` (if applicable), and `--json` as separate argv arguments**, not template-interpolated into a shell command string. Mesh/vault names CAN contain shell metacharacters (backticks, `$()`, `;`, `&&`) — those MUST be conveyed as one argv element per name.
+- **MUST pass `--json`** on every invocation. Human-readable output is not a contract this skill parses.
+- **MUST pass `--dry-run`** UNLESS the user explicitly asks to regenerate the on-disk primer file (the ratified default counter-case). Otherwise every priming call pollutes `<vault>/.lyt/primers/`.
+- **MUST resolve mesh/vault names via `lyt vault list --json` or `lyt mesh list --json` before passing `--target`.** Do not guess names.
+- **MUST reject `--`-leading names** from `lyt vault list --json` / `lyt mesh list --json` results before passing them to `--target` (G.6 inherited defense; family: G.2 CR-1 gh-flag-injection).
+- **MUST branch on all 6 writable reasons in Phase 5 (vault-scope).** Each has a distinct capability hint; collapsing them into a generic "can't write" message loses semantic signal the agent needs to recover.
+- **MUST NOT call `lyt primer` without `--scope`.** The CLI rejects with `error: "invalid-scope"`, exit 1.
+- **MUST NOT call `lyt primer` with `--scope vault` or `--scope mesh` without `--target`.** The CLI rejects with `error: "missing-target"`, exit 1.
+- **MUST NOT call `lyt vault info` for `--scope mesh` or `--scope federation`.** Phase 4 is skipped for those scopes (the ratified default); the primer summary alone is the output.
+- **MUST NOT modify or write any file.** This is a read-only skill (`requires_writable_vault: false`). The CLI's atomic primer-file write on non-dry-run is opt-in via the the ratified default counter-case; the skill itself never writes.
+- **MUST NOT compose shell command strings.** Argv-array always (parity with lyt-sync + lyt-search).
+- **MUST NOT silently degrade `writable === "unknown"` to a "writable" hint.** Surface the reason-specific guidance.
+
+## Companion skills
+
+- **/lyt-search** — query-driven recall (NOT primer aggregation). Use after priming when the agent needs to look up specific content. Companion: prime first, then search the cued surfaces.
+- **/lyt-capture** — write a Figment. Use after priming when the Phase 5 capability hint is `home-pushable-true` (✓) and the agent has a captureable insight.
+- **/lyt-sync** — pull/commit/push a vault. Run BEFORE priming if the user has unpushed local edits and wants the primer's recent-activity surface to reflect them.

package/skills/lyt-progress/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: lyt-progress
+description: >
+  Write a mid-session progress update as a Lyt Figment. Trigger when the user runs /lyt-progress, or says "write a progress update", "log where we are", "status update", "I'm blocked". Wraps `lyt pattern run work-management progress`. Writes to <vault>/Projects/<project>/work/<date>-progress-<slug>.md.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-progress
+
+Capture mid-session status — where we are, what's done, what's in flight, blockers, next steps. Superseded by `/lyt-result` at session end.
+
+## When to invoke
+
+- `/lyt-progress` slash trigger
+- "where are we"
+- "log progress" / "checkpoint" / "status update"
+- when a session has been running >2hr OR has hit a blocker
+
+## Phase 1 — Resolve target
+
+Same chain as `/lyt-plan`: `--vault` arg → `$LYT_ACTIVE_VAULT` → cwd detect → `<handle>/main` default. Project + slug similarly resolved.
+
+## Phase 2 — Run the verb
+
+```
+lyt pattern run work-management progress --vault <vault> --project <project> --slug <slug>
+```
+
+## Phase 3 — Fill the body
+
+Sections to fill:
+
+- **Where we are** — one-paragraph state of play
+- **What's done** — bullets
+- **What's in flight** — bullets
+- **Blockers** — bullets
+- **Next steps** — bullets
+
+If this progress closes a plan, set `parent_plan:` frontmatter to the wikilink of the plan.
+
+## Companion skills
+
+- `/lyt-plan` — pre-action design (parent)
+- `/lyt-result` — post-action outcome (closes this progress)

package/skills/lyt-recall/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: lyt-recall
+description: >
+  Search a Lyt vault by keyword. Trigger when the user runs /lyt-recall <query>, or asks "what did I write about X", "find my notes on X", "recall X from my vault", "search my vault for X", or similar phrasing. Returns matching Figments with relative path, title, and 2-line snippet around each match. Wraps `lyt pattern run knowledge-capture recall` for the report artifact (optional). Companion to lyt-capture.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [search]
+runtimes: [claude, codex, agents]
+requires_writable_vault: false
+---
+
+# /lyt-recall
+
+Search a Lyt vault by keyword. A Lyt vault is a folder of markdown Figments under `<vault>/notes/` (and elsewhere). v1 search is filesystem grep; libSQL FTS5 + vector ranking lands in a later phase.
+
+## When to invoke
+
+When the user runs `/lyt-recall <query>`, or says something like:
+
+- "what did I write about <topic>"
+- "find my notes on <topic>"
+- "recall <topic> from my vault"
+- "search my vault for <topic>"
+- "have I captured anything about <topic>"
+
+If the user asks a question that depends on prior captured knowledge, invoke this skill proactively — don't fabricate; check the vault first.
+
+## Phase 1 — Resolve the target vault
+
+Same resolution chain as `/lyt-capture`:
+
+1. `--vault <path>` arg
+2. `$LYT_ACTIVE_VAULT` env var
+3. cwd-based detection via `lyt vault info --by-path <cwd>`
+4. `~/lyt/vaults/<handle>/main/` default
+
+If the resolved path is missing or has no `.lyt/vault.yon`, tell the user and stop — don't grep random directories.
+
+## Phase 2 — Search
+
+1. **Run the Grep tool** with:
+
+- `pattern`: the user's query (case-insensitive by default)
+- `path`: the resolved vault path
+- `glob`: `**/*.md`
+- `output_mode`: `content`
+- `-i`: `true`
+- `-n`: `true`
+- `-C`: `2` (two lines of context around each match)
+- `head_limit`: 30
+
+2. **If zero matches**, broaden the query:
+
+- Split into individual terms (whitespace-separated).
+- Run separate grep calls, one per term.
+- Union the results.
+- If still zero, tell the user: _"No Figments in `<vault>` match `<query>`. Try a broader term or different phrasing."_ Then stop.
+
+## Phase 3 — Present results
+
+For each unique matching file (deduplicate by path), surface:
+
+- **Path** — relative to the vault root (e.g., `notes/2026-05-24-q4-planning.md`)
+- **Title** — read the file's frontmatter `title:` if present; otherwise the filename slug
+- **Snippet** — the matched line plus 1 line of context above/below
+
+Cap at the first 10 distinct files. If there are more, mention the count and offer to narrow the query.
+
+Format example:
+
+> **Found 3 matches in `~/lyt/vaults/<handle>/main/`:**
+>
+> 1. **notes/2026-05-24-q4-planning.md** — "Q4 planning"
+>    > ...the auth rewrite is a P0 for Q4...
+> 2. **notes/2026-05-23-auth-decisions.md** — "Auth rewrite decisions"
+>    > ...moving to OAuth, deprecating session tokens by EOQ...
+
+## Optional: persist the recall report as a Figment
+
+If the user wants the recall results saved (e.g., for inclusion in a `/lyt-plan` or `/lyt-result`), run:
+
+```
+lyt pattern run knowledge-capture recall --vault <vault> --slug <query-as-slug>
+```
+
+That writes a recall-report Figment at `<vault>/notes/recall-<date>-<slug>.md` with frontmatter capturing the query. The body is then filled in with the match list.
+
+## Rules
+
+- **Never open or modify files** beyond the optional recall-report write.
+- **Stay inside the resolved vault.** Don't grep the user's filesystem at large.
+- **Don't fabricate hits.** If the grep returns nothing, say so.
+- **Don't paraphrase across Figments.** Each match shown is the literal vault content; the user gets the raw recall, not a synthesis.
+- libSQL FTS5 / vector / cross-vault search are deferred to a later phase. v1 is grep.
+
+## Companion skill
+
+To add new content to the vault, use `/lyt-capture`.

package/skills/lyt-result/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: lyt-result
+description: >
+  Write a post-action result as a Lyt Figment — the default catch-all at session end. Trigger when the user runs /lyt-result, or says "write a result", "what shipped", "wrap up the session", "log the outcome". Wraps `lyt pattern run work-management result`. Writes to <vault>/Projects/<project>/work/<date>-result-<slug>.md.
+visibility: public
+lyt-version: 0.2.0
+capabilities: [write]
+runtimes: [claude, codex, agents]
+requires_writable_vault: true
+---
+
+# /lyt-result
+
+Capture the post-action outcome — what was delivered, what changed, what didn't get done. The default catch-all artifact at the end of every meaningful session.
+
+## When to invoke
+
+- `/lyt-result` slash trigger
+- session end: "wrap this up", "log the outcome"
+- after a commit / push / deploy
+
+## Phase 1 — Resolve target
+
+Same chain as `/lyt-plan`. Slug usually matches the parent plan's slug (set `parent_plan` frontmatter wikilink).
+
+## Phase 2 — Run the verb
+
+```
+lyt pattern run work-management result --vault <vault> --project <project> --slug <slug>
+```
+
+## Phase 3 — Fill the body
+
+Sections to fill:
+
+- **Outcome** — what got delivered. Reference commits if applicable (set `commits:` frontmatter array).
+- **What changed** — files, behaviors, decisions
+- **What didn't get done** — deferred / blocked / cut
+- **Cross-references** — plan link, commits, follow-ups
+
+## Promotion
+
+If the result teaches something durable about THIS project, **rename in place** to `<date>-insight-<slug>.md` and update `type: insight` in frontmatter — no folder move, no link rot. If the lesson is project-agnostic, write a `Nuggets/<subject>/<date>-nugget-<slug>.md` instead.
+
+## Companion skills
+
+- `/lyt-plan` — pre-action design (parent of this result)
+- `/lyt-insight` — promoted result with durable project lesson
+- `/lyt-retro` — deliberate retrospective after a meaningful arc