@younndai/lyt-skills 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@younndai/lyt-skills",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Lyt harness skills — 16 skills (/lyt-plan, /lyt-progress, /lyt-result, /lyt-retro, /lyt-insight, /lyt-handoff, /lyt-decision, /lyt-pattern, /lyt-capture, /lyt-recall, /lyt-pod, /lyt-mesh-explore, /lyt-primer-context, /lyt-search, /lyt-sync, /lyt-alias) symlinked tri-runtime into ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/. Composed into the `lyt skills install` and `lyt skills list` meta-CLI verbs.",
   "homepage": "https://linkyourthink.com",
   "repository": {
@@ -49,7 +49,7 @@
     "prepublishOnly": "node ../../scripts/check-no-vendored-deps.mjs --root ../.. && node ../../scripts/public-release/scan-tarball.mjs lyt-skills"
   },
   "dependencies": {
-    "@younndai/lyt-vault": "^0.9.7",
+    "@younndai/lyt-vault": "^0.9.9",
     "commander": "^12.1.0"
   },
   "devDependencies": {

package/skills/lyt-capture/SKILL.md

@@ -27,6 +27,16 @@ When the user runs `/lyt-capture`, or says something like:
 
 If the user pastes content and only says "save it," interpret as `/lyt-capture` on the pasted content.
 
+## When NOT to invoke
+
+`/lyt-capture` writes a **plain Figment note** — not a work-management artifact. When the durable thing is a structured type, defer to the dedicated skill (each writes the same 8-field ceremony to its own home, with type-specific framing):
+
+- A distilled, durable **project lesson** ("this is an insight", "lesson learned about Lyt") → `/lyt-insight`.
+- A locked **decision** ("lock this decision", "record the decision") → `/lyt-decision`.
+- A **plan / progress / result / retro / handoff** → the matching `/lyt-plan` · `/lyt-progress` · `/lyt-result` · `/lyt-retro` · `/lyt-handoff`.
+
+Use `/lyt-capture` only for a free-form note that doesn't fit one of those work-management types. When in doubt between a plain note and a typed artifact, prefer the typed skill — it carries the right frontmatter and lands in the right folder.
+
 ## Phase 1 — Resolve the target vault
 
 Follow this chain, in order, and stop at the first success:
@@ -103,7 +113,7 @@ e.g. `lyt capture --index-only notes/2026-06-10-my-note.md --vault personal/main
 
 > Captured to `<relative-path-from-vault-root>` in `<vault-path>`.
 
-4. Do **not** run any git operations. Phase 8's sync watcher (when shipped) will handle commits.
+4. Do **not** run any git operations. Capture writes the file only — it does NOT git. Sync is a separate step: `/lyt-sync` (or the `lyt sync --watch` foreground daemon, which auto-commits watched vaults) handles commits.
 
 ## Rules
 
@@ -113,7 +123,7 @@ e.g. `lyt capture --index-only notes/2026-06-10-my-note.md --vault personal/main
 - **User Figments are plain Obsidian-flavored markdown.** Wikilinks (`[[other-note]]`), tags (`#tag`), callouts, embeds — all fine. **Do NOT write YON inside user Figments.** YON is reserved for system files (`.lyt/vault.yon`, `.lyt/memscope.yon`, pattern.yon).
 - **Never overwrite an existing Figment.** Always pick a fresh slug suffix.
 - **Never touch files outside `<vault>/notes/`** unless the user explicitly says so.
-- **Never run `git add`/`git commit`** — sync is a Phase 8 concern.
+- **Never run `git add`/`git commit`** — sync is a separate step (`/lyt-sync` or `lyt sync --watch`).
 - If the user's content references other Figments by name, use `[[wikilinks]]` so Obsidian resolves them; don't expand them yourself.
 
 ## Direct CLI path (when no content yet)

package/skills/lyt-mesh-explore/SKILL.md

@@ -35,6 +35,8 @@ When the user runs `/lyt-mesh-explore <mesh>`, or says something like:
 
 If the user wants a survey across _all_ their meshes (the pod-level view), prefer `/lyt-pod`. If the user wants to search content _inside_ the mesh's vaults, prefer `/lyt-search --mesh <name>`. This skill is the mesh-scoped drill-down between those two surfaces.
 
+**Disambiguator vs `/lyt-primer-context`.** "**structure / metadata / what's IN** mesh `<name>`" (which vaults, rid, push target) → `/lyt-mesh-explore` (this skill — static mesh shape). "**state / active arcs / what's happening / lately** in mesh `<name>`" (recent activity, top keywords, in-progress arcs) → `/lyt-primer-context --scope mesh --target <name>` (dynamic priming context). The split is static-shape-vs-live-state: if the user asks what the mesh _contains_, route here; if they ask what's _going on_ in it, route to `/lyt-primer-context`.
+
 ## Phase 1 — Resolve mesh name from user signal
 
 The CLI verb takes one required positional `<mesh>` (the mesh name). Pick by the user's wording:
@@ -135,7 +137,7 @@ Synthesis rules:
 - **MUST pass `--json`** on every invocation. Human-readable output is not a contract this skill parses.
 - **MUST resolve mesh names via `lyt mesh list --json` before passing them.** The canonical mesh-enumeration verb is `lyt mesh list`. Do not guess names.
 - **MUST reject `--`-leading resolved mesh names** before passing them to the positional `<mesh>` argument (the flag-injection defense family).
-- **MUST NOT cite `lyt mesh status`** as a verb. It does not exist. The canonical mesh-listing verb is `lyt mesh list`; the canonical single-mesh-inspection verb is `lyt mesh info` (this skill).
+- **MUST NOT cite `lyt mesh status` for single-mesh inspection.** It DOES exist, but it renders the local mesh graph (vault list grouped by parent_vault subtrees), not one mesh's metadata. The canonical mesh-listing verb is `lyt mesh list`; the canonical single-mesh-inspection verb is `lyt mesh info` (this skill).
 - **MUST NOT modify or write any vault file.** This is a read-only skill (`requires_writable_vault: false`). If the user wants the mesh overview persisted to a Figment, run `/lyt-capture` separately on the formatted output.
 - **MUST NOT pass `--remote` by default.** LOCAL is the default; pass `--remote` only on explicit user signal ("without cloning", "from GitHub", "peek at the published mesh.yon", "remote").
 - **MUST NOT invent edge or subscription bullets.** `lyt mesh info` does not emit them. For pod-wide subscription overview use `/lyt-pod`; for cross-mesh edges, inspect `.lyt/mesh.yon` directly (out of scope for this skill).

package/skills/lyt-pod/SKILL.md

@@ -37,6 +37,8 @@ Invoke this skill **proactively** as the first move whenever the user asks a pod
 
 If the user wants to drill into a single mesh (vault list + edges for one mesh), prefer `/lyt-mesh-explore`. If the user wants per-vault writable status or agent priming, use `/lyt-primer-context`.
 
+**Disambiguator vs `/lyt-search`.** A bare **inventory** request ("what's in my pod", "list my vaults", "what meshes do I have") → `/lyt-pod` (this skill — enumerates the pod's structure). A **content query with a topic** ("what's in my pod **about X**", "...about `<topic>`", "find anything on `<topic>`") → `/lyt-search` (queries figment content across the pod). The split is structure-vs-content: if the user names a subject they want found, route to `/lyt-search`, not here.
+
 ## 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:
@@ -130,6 +132,7 @@ The CLI emits stable, deterministically key-ordered JSON on stdout:
       "verifyFailCount": 0
     }
   ],
+  "displayNames": { "<ridHex>": "<mesh>/<vault>" },   // ridHex → canonical qualified display name
   "rollupTombstones": { ... },        // only when --include-tombstones is passed
   "rollupThresholdDays": <int>,       // only when --include-tombstones is passed
   "rollupThresholdIso": "<iso>"       // only when --include-tombstones is passed

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

@@ -32,6 +32,8 @@ When the user runs `/lyt-primer-context`, or says something like:
 
 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.
 
+**Disambiguator vs `/lyt-mesh-explore`** (mesh-scope only). "**state / active arcs / what's happening / lately** in mesh `<name>`" (recent activity, top keywords, in-progress arcs) → `/lyt-primer-context --scope mesh --target <name>` (this skill — dynamic live state). "**structure / metadata / what's IN** mesh `<name>`" (which vaults, rid, push target) → `/lyt-mesh-explore` (static mesh shape). The split is live-state-vs-static-shape: if the user asks what's _going on_ in the mesh, route here; if they ask what the mesh _contains_, route to `/lyt-mesh-explore`.
+
 ## 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):

package/skills/lyt-recall/SKILL.md

@@ -1,9 +1,9 @@
 ---
 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.
+  Search a SINGLE Lyt vault using the tiered-cascade engine (`lyt search --vault`) — Tier 0 arcs (0.95) → Tier 1 lanes (0.90) → Tier 2 FTS5 (0.70) (single-vault scope skips Tier 3 edges), with confidence ranking. 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", "remind me what my <topic> notes say", "have I captured anything about X", or similar single-vault recall phrasing. Wraps `lyt search "<query>" --vault <name> --json`. Returns ranked Figments with path, snippet, and confidence. For a pod-wide search across every vault/mesh, use /lyt-search instead. Companion to lyt-capture.
 visibility: public
-lyt-version: 0.2.0
+lyt-version: 0.9.8
 capabilities: [search]
 runtimes: [claude, codex, agents]
 requires_writable_vault: false
@@ -11,88 +11,112 @@ 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.
+Recall content from a **single** Lyt vault using the tiered-cascade search engine. The skill is a thin LLM-driven wrapper around the `lyt search` CLI verb with `--vault` scope; the heavy lifting — arc/lane/FTS5/edge cascade, confidence scoring, deterministic JSON — already lives in the CLI. The skill resolves which one vault to search, invokes `lyt search "<query>" --vault <name> --json`, parses the stable output, and presents ranked results.
+
+`/lyt-recall` is the **single-vault** member of the search pair; `/lyt-search` is the **pod-wide** member (federation/mesh/vault scope). They share one engine — recall just always pins `--vault`.
+
+> **Do NOT use filesystem search.** Never answer a recall with the `Grep`/`rg`/`find`/`Get-ChildItem` tools, or by walking the vault directory yourself. The vault's libSQL FTS5 index (whole-vault since 0.9.7, not just `notes/`) is the source of truth, and `lyt search` is the only sanctioned access path. Filesystem grep bypasses the engine's ranking, tier provenance, and confidence scoring, and misses index-only signal. Read a specific file directly ONLY after `lyt search` has returned it as a hit (to quote it in full), or when the user gives an explicit path.
 
 ## When to invoke
 
 When the user runs `/lyt-recall <query>`, or says something like:
 
-- "what did I write about <topic>"
+- "what did I write about <topic>" — _single-vault case; if the user's pod has multiple vaults and they want all of them, prefer `/lyt-search`_
 - "find my notes on <topic>"
 - "recall <topic> from my vault"
-- "search my vault for <topic>"
+- "remind me what my <topic> notes say"
 - "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.
+If the user's question depends on prior captured knowledge, invoke this skill proactively — don't fabricate; check the vault first.
 
-## Phase 1 — Resolve the target vault
+## Phase 1 — Resolve the single target vault
 
-Same resolution chain as `/lyt-capture`:
+Recall always searches exactly one vault. Resolve which one, in order:
 
-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
+1. **Explicit `--vault <name>` arg** the user supplied.
+2. **`$LYT_ACTIVE_VAULT`** env var, if set.
+3. **cwd-based detection** via `lyt vault info --by-path <cwd> --json` — if the cwd is inside a registered vault, use it.
+4. **Sole vault** — run `lyt vault list --json`; if the pod has exactly one active vault, use it.
+5. **Ambiguous** (multiple vaults, no signal) — surface the vault names from `lyt vault list --json` and ask which one, or suggest `/lyt-search` for a pod-wide search. Do NOT guess.
 
-If the resolved path is missing or has no `.lyt/vault.yon`, tell the user and stop — don't grep random directories.
+**Resolve + sanitize the name before passing it.** Match the user's term to a listed vault name (exact, then case-insensitive, then prefix). **Reject any resolved name that begins with `-` or `--`** before passing it to `--vault <name>` — closes the flag-injection surface (same defense as `/lyt-search` Phase 1 and `/lyt-sync` Phase 1). If no match, list the available names and stop — do not invent a name.
 
-## Phase 2 — Search
+## Phase 2 — Invoke the CLI verb
 
-1. **Run the Grep tool** with:
+Run the verb via the Bash tool (or your runtime's shell equivalent). **Pass the query as a single quoted argv argument; never shell-compose the command** — the query CAN contain shell metacharacters (backticks, `$()`, `;`, `&&`), which MUST travel as one argv element, not template-interpolated into a shell string.
 
-- `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
+```
+# Shell-syntax (DOCUMENTATION ONLY — do NOT compose this as a string):
+lyt search "<user-query>" --vault <name> --json [--limit <n>]
 
-2. **If zero matches**, broaden the query:
+# Actual exec shape (argv array; cross-platform-safe):
+spawnSync("lyt", ["search", userQuery, "--vault", vaultName, "--json"]);
+```
 
-- 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.
+Key rules:
+
+- The first positional argument is the query — a single string. Multi-word queries are implicit AND. Quote it so the shell treats it as one argv element.
+- `--vault <name>` is **mandatory for recall** (that is what makes this single-vault). Never run bare `lyt search` from this skill (that searches the whole pod — that's `/lyt-search`'s job).
+- `--json` is **mandatory**. It yields the deterministic, stable key-ordered output parsed below.
+- `--limit <n>` defaults to 20 (CLI default), capped at 1000. Apply a caller cap only on explicit signal ("top 5"); else rely on the default.
+
+## Phase 3 — Parse the JSON output
+
+The CLI emits stable, deterministically key-ordered JSON on stdout (exit 0 on success). Expected shape (scope = `vault`):
+
+```json
+{
+  "query": "<the query>",
+  "scope": "vault",
+  "scopeTarget": "<vault-name>",
+  "limit": 20,
+  "results": [
+    {
+      "confidence": 0.70,
+      "tier": 2,
+      "vault_name": "<vault>",
+      "mesh_name": "<mesh>",
+      "figment_path": "<relative/path.md>",
+      "snippet": "<snippet with <mark>…</mark> highlights>"
+    }
+  ],
+  "trace": { "tiersRun": [0, 1, 2], "perTierHitCount": [0, 0, 4, 0], "vaultsSearched": ["<vault>"] },
+  "durationMs": 41
+}
+```
 
-## Phase 3 — Present results
+Failure modes (CLI emits to stderr; exit non-zero):
 
-For each unique matching file (deduplicate by path), surface:
+- **Empty query** (exit 1) → `{ "error": "empty-query", "message": "..." }`. Surface verbatim; ask the user to refine.
+- **Invalid limit** (exit 1) → `{ "error": "invalid-limit", ... }`. Re-invoke with the CLI default.
+- **Cascade error** (exit 2) → `{ "error": "cascade-error", "message": "..." }`. Surface verbatim. Only if `lyt search` itself fails this way may you fall back to reading files directly — and you MUST label the answer as a fallback, not engine-ranked.
 
-- **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
+## Phase 4 — Present results
 
-Cap at the first 10 distinct files. If there are more, mention the count and offer to narrow the query.
+Order by descending confidence (the CLI emits them ranked). One line per result. Show each as `[<confidence>] <figment_path> — <snippet>`; strip the `<mark>…</mark>` tags or render them as emphasis; truncate snippets to ~80 characters.
 
-Format example:
+Format:
 
-> **Found 3 matches in `~/lyt/vaults/<handle>/main/`:**
+> **Found N matches for `"<query>"` in `<vault-name>` (<durationMs>ms):**
 >
-> 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...
+> - `[0.95]` `writing/publication-voice.md` — _…the voice inside it is mine. I write jazz…_
+> - `[0.70]` `writing/voice-guides.md` — _…copy-paste prompts for authorship-voice and publication-voice…_
 
-## 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>
-```
+On **empty results**: surface _"No matches for `"<query>"` in `<vault-name>`."_ and offer to widen with `/lyt-search` (pod-wide) or try a broader term. If you expected a hit, the vault's FTS index may be stale — suggest rebuilding it with `lyt vault rebuild-index <vault-name>` (or `lyt reindex`), then re-running the recall.
 
-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.
+To quote a hit in full, read the returned `figment_path` directly **after** the engine has surfaced it (that is sanctioned — it's reading a known source, not discovery-by-grep).
 
 ## 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.
+- **MUST search via `lyt search "<query>" --vault <name> --json`.** MUST NOT discover content with `Grep`/`rg`/`find`/`Get-ChildItem` or by walking the vault tree. Filesystem grep is only an explicit, labeled fallback after a `cascade-error`.
+- **MUST pass the query as a single quoted argv argument**, not interpolated into a shell string.
+- **MUST pass `--vault <name>` and `--json`** on every invocation. Bare `lyt search` (pod-wide) is `/lyt-search`, not this skill.
+- **MUST resolve + sanitize the vault name** via `lyt vault list --json`; reject any `--`-leading name; never guess a name.
+- **MUST NOT widen scope silently.** If the named vault is missing, surface the miss and stop — do not fall back to a pod-wide search without the user.
+- **MUST NOT modify or write any vault file.** Read-only (`requires_writable_vault: false`). To persist results to a Figment, run `/lyt-capture` on the formatted output.
+- **MUST NOT re-interpret confidence tiers.** Display the CLI's confidence verbatim (`0.95 / 0.90 / 0.70` — the Tier-3 `0.50` only appears in pod/mesh scope, never single-vault); do not round or invent a derived score.
 
-## Companion skill
+## Companion skills
 
-To add new content to the vault, use `/lyt-capture`.
+- **`/lyt-search`** — the pod-wide sibling (federation/mesh/vault scope) using the same cascade engine. Use it when the user wants every vault, a whole mesh, or hasn't pinned a single vault.
+- **`/lyt-capture`** — write a Figment. Pair with `/lyt-recall` to persist what you found.

package/skills/lyt-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lyt-search
 description: >
-  Search a Lyt pod (or a single mesh or vault) using the tiered-cascade engine — Tier 0 arcs (0.95) → Tier 1 lanes (0.90) → Tier 2 FTS5 (0.70) → Tier 3 edges (0.50) — with confidence ranking. Trigger when the user runs /lyt-search <query>, or says "search my pod for X", "find anything about X across my vaults", "search across all meshes for X", "what's in my pod about X", or similar phrasing on a query wider than a single vault. Wraps the `lyt search` CLI verb — federation scope by default; --vault / --mesh narrow scope; --limit caps results. Returns ranked Figments with vault, mesh, snippet, and confidence. Companion to lyt-recall (single-vault keyword grep) for narrower local searches.
+  Search a Lyt pod (or a single mesh or vault) using the tiered-cascade engine — Tier 0 arcs (0.95) → Tier 1 lanes (0.90) → Tier 2 FTS5 (0.70) → Tier 3 edges (0.50) — with confidence ranking. Trigger when the user runs /lyt-search <query>, or says "search my pod for X", "find anything about X across my vaults", "search across all meshes for X", "what's in my pod about X", or similar phrasing on a query wider than a single vault. Wraps the `lyt search` CLI verb — federation scope by default; --vault / --mesh narrow scope; --limit caps results. Returns ranked Figments with vault, mesh, snippet, and confidence. Companion to lyt-recall (single-vault scope) for narrower local searches.
 visibility: public
 lyt-version: 0.5.0
 capabilities: [search]
@@ -21,12 +21,14 @@ When the user runs `/lyt-search <query>`, or says something like:
 - "search across all my vaults for <topic>"
 - "find anything about <topic>"
 - "what's in my pod about <topic>"
-- "what did I write about <topic>" — _if the user's pod has multiple vaults_; for a single-vault keyword grep, prefer `/lyt-recall`
+- "what did I write about <topic>" — _if the user's pod has multiple vaults_; for single-vault recall, prefer `/lyt-recall`
 - "search the `<mesh-name>` mesh for <topic>"
 - "search vault `<vault-name>` for <topic>"
 
 If the user's question depends on prior captured knowledge across multiple vaults, invoke this skill proactively — don't fabricate; check the pod first.
 
+**Disambiguator vs `/lyt-pod`.** A **content query with a topic** ("what's in my pod **about X**", "...about `<topic>`", "find anything on `<topic>`") → `/lyt-search` (this skill — queries figment content). A bare **inventory** request ("what's in my pod", "list my vaults", "what meshes do I have") → `/lyt-pod` (enumerates the pod's structure, no content query). The split is content-vs-structure: if the user names a subject they want found, this is the right skill; if they want a survey of what exists, route to `/lyt-pod`.
+
 ## Phase 1 — Determine scope from user signal
 
 The CLI verb supports three mutually-exclusive scope flags; the default (no flag) is federation. Pick by the user's wording:
@@ -124,7 +126,49 @@ Format:
 
 Show each result as `[<confidence>] <vault>/<figment_path> — <snippet>`. Truncate snippets to ~80 characters with an ellipsis. The top-of-output tier-hit summary uses the CLI's `trace.perTierHitCount` map (`{0:N, 1:M, 2:K, 3:L}`) so the handler sees confidence distribution at a glance.
 
-On **empty results**: surface _"No matches for `"<query>"` across <scope>."_ and offer scope-widening hints (`--mesh` → federation; `--vault` → `--mesh`).
+On **empty results**: surface _"No matches for `"<query>"` across <scope>."_ and offer scope-widening hints (`--mesh` → federation; `--vault` → `--mesh`). If a vault that should contain the figment still returns nothing, its FTS index may be stale — suggest rebuilding it with `lyt vault rebuild-index <name>` (or `lyt reindex` across the pod), then re-running the search.
+
+## Phase 5 — Concept-search discovery nudge (only when `trace.nudge.eligible` is true)
+
+The `--json` output may carry a `trace.nudge` block. It is the signal for a one-time offer to enable **concept search** — finding notes by meaning, not just keywords. Read it; only voice the offer when it explicitly says to.
+
+```json
+"trace": {
+  "nudge": {
+    "eligible": true,
+    "state": "not-yet-asked",
+    "reason": null,
+    "declines": 0,
+    "daysSince": null,
+    "searchesSince": 1
+  }
+}
+```
+
+- **`eligible: true`** → voice the offer once (see below). A null `reason` confirms it.
+- **`eligible: false`** → say nothing about it. The `reason` explains why (`model-present` = already set up; `disabled` = the user chose never to be asked; `auto-quiet` = declined enough times; `cadence` = asked recently). Never override an ineligible verdict.
+- **`trace.nudge` absent** → nothing to do; proceed normally.
+
+### Voicing the offer (only when eligible)
+
+Relay it to the user in plain language, **framed as a benefit to them — never "to help improve Lyt"**:
+
+> _"I can also search your notes by meaning, not just keywords. It needs a one-time local setup (nothing leaves your machine). Want me to set it up?"_
+
+Then **capture an explicit yes or no** before doing anything else.
+
+### Response-capture contract — map the reply to exactly one verb
+
+| User reply | Do |
+|---|---|
+| **Yes** (set it up) | `lyt model fetch` — runs the one-time local setup and marks the offer resolved. |
+| **No** (explicit decline) | `lyt model nudge --decline` — records ONE decline (three declines → auto-quiet). |
+| **"Never ask again"** | `lyt model nudge --never` — turns the offer off permanently. |
+| **Surfaced / bookkeeping only** | `lyt model nudge --asked` — records that the offer was shown (stamps the ask, resets the cadence counter) when you voiced it without yet capturing a yes/no. |
+
+- **A non-response is NOT a decline.** If the user doesn't answer the offer, record nothing — do not run `nudge --decline`. Only an explicit "no" counts as a decline.
+- **Inspect anytime** with `lyt model nudge --status` (read-only; prints the current offer-state).
+- Honor a `disabled` / `auto-quiet` state — once the user has opted out, never re-raise the offer.
 
 ## Rules
 
@@ -133,12 +177,14 @@ On **empty results**: surface _"No matches for `"<query>"` across <scope>."_ and
 - **MUST resolve mesh/vault names via `lyt vault list --json` or `lyt mesh list --json` before passing `--vault` or `--mesh`.** Do not guess names.
 - **MUST NOT pass `--all` explicitly.** Federation is the default; `--all` is a redundant alias. Use no scope flag instead.
 - **MUST NOT combine `--vault` and `--mesh`.** The CLI exits 1 with `conflicting-scope-flags`.
+- **`--no-self-heal` is a no-op under `--json`** — the empty-result self-heal (reindex stale vaults + re-query on 0 hits) is auto-disabled whenever `--json` is set, so passing `--no-self-heal` alongside the mandatory `--json` changes nothing. (`--no-semantic`, which forces the pure lexical cascade, is NOT auto-disabled under `--json` — pass it explicitly if you need to suppress dense-embedding fusion.)
 - **MUST NOT re-interpret confidence tiers.** The CLI emits them as `0.95 / 0.90 / 0.70 / 0.50` per Tier 0/1/2/3 spec. Display verbatim; do not "smooth" or "round" or invent a derived score.
 - **MUST NOT modify or write any vault file.** This is a read-only skill (`requires_writable_vault: false`). If the user wants results persisted to a Figment, run `/lyt-capture` separately on the formatted output.
 - **MUST NOT widen scope without user signal.** If the user said "in my work vault", do not silently fall back to federation when the named vault is missing — surface the miss and stop.
+- **MUST voice the concept-search offer ONLY when `trace.nudge.eligible` is true**, and MUST capture an explicit yes/no before acting. A non-response records nothing — never run `lyt model nudge --decline` on silence. Honor a `disabled` / `auto-quiet` state and never re-raise.
 
 ## Companion skills
 
-- **`/lyt-recall`** — single-vault keyword grep. Use when the user has only one vault in mind and wants filesystem-level grep semantics rather than the tiered-cascade engine.
+- **`/lyt-recall`** — single-vault recall. Use when the user has only one vault in mind; same tiered-cascade engine as `/lyt-search`, pinned to `--vault` scope.
 - **`/lyt-sync`** — pull-then-push a vault. Run before `/lyt-search` if the user has unpushed local edits and wants the FTS5 index reflect them (the cascade reads the local vault's libSQL state).
 - **`/lyt-capture`** — write a Figment. Pair with `/lyt-search` if the user wants the recall results persisted.

package/skills/lyt-sync/SKILL.md

@@ -26,6 +26,8 @@ When the user runs `/lyt-sync`, or says something like:
 
 If the user says "save and sync" or "/lyt-capture then sync", run /lyt-capture first, then /lyt-sync on the destination vault.
 
+**Pod-wide sync: the `lyt sync` verb.** This skill's per-vault git flow (below) is the documented default for a **single named vault**. When the user wants to **sync everything** ("sync all my vaults", "sync my whole pod", "sync everything"), there is a real pod-wide CLI verb: `lyt sync` (no vault argument) syncs all registered active vaults — commit + push + pull --rebase — and also runs the federation publish pass. `lyt sync --watch` is a foreground daemon that auto-commits watched vaults (event-driven). `lyt sync --check` reports per-vault freshness without writing. There is **no** `lyt sync --mesh` flag; mesh-scoped sync is not a current verb.
+
 ## Phase 1 — Resolve the target vault
 
 Follow this chain, in order, and stop at the first success (mirrors /lyt-capture Phase 1):
@@ -111,7 +113,7 @@ The actual reason strings emitted by `vault info --json` are listed in the **emi
 | `subscriber-default-false`           | (subscriber)                | `false`     | Skip push. Report: _"Skipped push: this is a subscriber vault. Subscriber vaults pull but don't push. Capture into your home vault instead."_                  |
 | `gh-unavailable`                     | (gh-offline)                | `"unknown"` | Skip push. Report: _"Skipped push: gh CLI is unavailable (offline / rate-limited / not authenticated). Re-try when network is available."_                     |
 | `no-remote`                          | (no-remote)                 | `"unknown"` | Skip push. Report: _"Skipped push: vault has no git remote configured. Configure a remote with `gh repo create` or `git remote add origin <url>`."_            |
-| `orphan-vault`                       | (orphan)                    | `"unknown"` | Skip push. Report: _"Skipped push: vault has no mesh role (orphan). Adopt into a mesh with `lyt mesh adopt --cluster <name>`."_                                |
+| `orphan-vault`                       | (orphan)                    | `"unknown"` | Skip push. Report: _"Skipped push: vault has no mesh role (orphan). Re-attach it with `lyt repair --target <vault> --apply --mesh <mesh>` (the single-orphan-vault verb; `lyt mesh adopt --cluster` is for orphan-MESH clusters, not one vault)."_                                |
 
 **Note on emitted vs semantic names.** The semantic names `home-pushable-true` and `home-not-pushable-false` are documentation aliases for the actual emitted strings `gh-viewerCanPush-true` and `gh-viewerCanPush-false`, kept so future renames of the underlying enum don't silently break the skill prose. The 4 other reason strings (`subscriber-default-false`, `gh-unavailable`, `no-remote`, `orphan-vault`) are identical in both surfaces.
 
@@ -135,7 +137,7 @@ Final handler-facing result shape:
 - **MUST gate push on `vault.writable` / `vault.writableDetermination`.** Never `git push` unless `writableDetermination === "gh-viewerCanPush-true"` (equivalently, `writable === true`). The other 5 reasons all skip push.
 - **MUST branch on all 6 reasons.** Each has a distinct handler-facing message; collapsing them into a generic "can't push" message loses semantic signal the handler needs to recover.
 - **MUST NOT add a `Co-Authored-By` trailer** to the auto-commit. Per the project's `CLAUDE.md` commit conventions, unless the user explicitly requests one.
-- **MUST NOT touch any vault other than the resolved target.** Sync is single-vault. A multi-vault sweep is `mesh clone-all` / a future `lyt sync --mesh` verb, not this skill.
+- **MUST NOT touch any vault other than the resolved target.** This skill's per-vault flow is single-vault. A pod-wide multi-vault sweep is the `lyt sync` verb (no vault argument — see "Pod-wide sync" above) or `mesh clone-all`, not this skill's per-vault path. There is no `lyt sync --mesh` flag.
 - **MUST NOT modify `.lyt/vault.yon`, `.lyt/mesh.yon`, ledger YONs, or `@STAMP` blocks.** Those are runner / writer concerns; sync only commits handler-authored content as-is.
 - **MUST NOT silently degrade `writable === "unknown"` to push.** Surface the reason to the handler.