@lythos/skill-deck 0.9.13 → 0.9.15

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck <command> [options]
+bunx @lythos/skill-deck@0.9.15 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -53,14 +53,14 @@ expires = "2026-05-01"    # ISO date; warns at ≤14 days
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.15 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.15 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.15 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.15 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.15 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.15 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.15 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.15 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -117,7 +117,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck link
+bunx @lythos/skill-deck@0.9.15 link
 ```
 
 ### Key Concepts
@@ -146,7 +146,7 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck add github.com/owner/repo/skill` or clone manually into cold pool |
+| `❌ Skill not found: <name>` | Skill declared in deck but not in cold pool | `bunx @lythos/skill-deck@0.9.15 add github.com/owner/repo/skill` or clone manually into cold pool |
 | `link` skips entries with warnings | Real files/directories exist in working set (not symlinks) | Delete the real directories in `working_set` and re-run `link`. Never create directories manually there |
 | `refresh` reports "Not a git repository" | Skill was copied (not cloned) into cold pool | Re-clone with `git clone` or use `deck add` which clones by default |
 | `deck update` prints deprecation warning | `update` was renamed to `refresh` in v0.8+ | Use `deck refresh` instead |
@@ -157,6 +157,68 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 | `deck add` fails with 404 | Locator format wrong or repo doesn't exist | Format: `github.com/owner/repo/skill-name` (path to skill directory inside repo) |
 | `skill-deck.toml not found` | Running `link` outside project tree | Run from project root, or use `--deck ./path/to/skill-deck.toml` |
 
+## K8s-Style Reconciliation: Agent as Controller
+
+Deck follows Kubernetes' reconciliation model. The agent (Claude, Cursor, etc.) is the **controller manager** — it reads state, builds a plan, shows it to the user, then executes:
+
+```
+scan (observe state)  →  plan (compute diff)  →  confirm  →  execute  →  verify
+     ↑                                                              │
+     └──────────────────── reconciliation loop ─────────────────────┘
+```
+
+| K8s Concept | Deck Equivalent |
+|-------------|-----------------|
+| Desired state (YAML manifest) | `skill-deck.toml` |
+| Actual state (running pods) | Working set (`~/.claude/skills/`) |
+| Controller manager (reconcile loop) | Agent reads state → builds plan → user confirms |
+| `kubectl apply` | `deck link` |
+| Namespace (isolation) | Per-project deck file |
+| PersistentVolume | Cold pool (`~/.agents/skill-repos/`) |
+
+The loop doesn't run automatically (no daemon). The agent is the loop — it observes, plans, confirms, and executes on demand. This is K8s-style **declarative governance**: declare what you want, reconcile to match.
+
+## Multi-Agent POSSE Syndication
+
+Not "switching between agents" — **syndicating everywhere simultaneously**. Like IndieWeb's POSSE (Publish on your Own Site, Syndicate Elsewhere):
+
+```
+Cold Pool (~/.agents/skill-repos/)     ← canonical "own site"
+    ↓ deck link --workdir
+├── .claude/skills/                    ← syndicate to Claude Code
+├── .cursor/skills/                    ← syndicate to Cursor
+├── .codex/skills/                     ← syndicate to Codex
+└── .windsurf/skills/                  ← syndicate to Windsurf
+```
+
+One cold pool, one deck declaration, synced to every agent you use. Adding a new platform is updating a key-value registry — no code changes needed. See [multi-agent-posse-syndication](https://github.com/lythos-labs/lythoskill/blob/main/cortex/wiki/01-patterns/2026-05-05-multi-agent-posse-syndication.md).
+
+## Migration: For Existing Skill Users
+
+If you already have skills installed (in working set, globally, or mixed), deck respects your existing state:
+
+```
+1. SCAN    Agent surveys: what's in ~/.claude/skills/? What's global? What's mixed?
+           curator scan helps — indexes cold pool or existing working set.
+
+2. PLAN    Agent shows: "We found 12 skills. After migration:
+           - 2 → innate (deck infrastructure)
+           - 4 → tool section
+           - 3 → cold pool (already there, just link)
+           - 3 → backup only (unused, stale)
+           All 12 backed up to ~/.agents/lythos/backups/<date>.tar.gz"
+
+3. BACKUP  Always. `link` creates tar backups for non-symlink entries before removal.
+           Use `--no-backup` only if you're certain.
+
+4. EXECUTE deck link — creates symlinks, removes undeclared, leaves real files untouched.
+
+5. VERIFY  Agent checks: all declared skills resolve? Working set clean?
+           If unhappy: tar xf backup → rollback to pre-migration state.
+```
+
+**Key principle**: existing skill users aren't beginners. They have working setups. Migration is a conversation — scan, show the plan, confirm before acting. Backup is non-negotiable.
+
 ## Architecture: Intent / Plan / Execute
 
 Deck commands separate pure logic from IO:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.9.13",
+  "version": "0.9.15",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",