@lythos/skill-deck 0.9.31 → 0.9.33

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.31 <command> [options]
+bunx @lythos/skill-deck@0.9.33 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,14 +55,17 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 | Situation | Command |
 |-----------|---------|
-| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.31 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.31 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.31 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.31 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.31 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.31 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.31 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.31 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.33 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.33 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.33 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.33 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.33 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.33 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.33 prune` |
+| Switch skill from snapshot to sync mode | `bunx @lythos/skill-deck@0.9.33 sync tdd` |
+| Switch skill from sync to snapshot mode | `bunx @lythos/skill-deck@0.9.33 freeze tdd` |
+| Check cold pool for drift vs lock file | `bunx @lythos/skill-deck@0.9.33 reconcile` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.33 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -74,6 +77,9 @@ prompt = "Search for latest info, then generate professional document with diagr
 | `refresh` | `[<fq|alias>] [--deck <path>]` | Pull latest versions of declared skills from upstream git repos. Pass a name to refresh one skill. |
 | `remove` | `<fq|alias> [--deck <path>]` | Remove skill from deck.toml and working set. Cold pool untouched. |
 | `prune` | `[--yes] [--deck <path>]` | GC cold pool repos no longer referenced. Interactive confirm (skip with `--yes`). |
+| `sync` | `<alias> [--deck <path>] [--workdir <dir>]` | Switch skill from snapshot (real dir) to sync (symlink) — live mode. |
+| `freeze` | `<alias> [--deck <path>] [--workdir <dir>]` | Switch skill from sync (symlink) to snapshot (real dir) — pin current HEAD. |
+| `reconcile` | `[--apply] [--deck <path>] [--workdir <dir>]` | Compare lock vs cold pool, report drift (missing/behind/extra). Plan-first. |
 
 ### Options
 
@@ -84,10 +90,13 @@ prompt = "Search for latest info, then generate professional document with diagr
 
 | `--alias <alias>` | Explicit alias for the skill (default: basename of path) | — |
 | `--type <type>` | Target section for `add`: `innate`, `tool`, or `transient` | `tool` |
+| `--mode <mode>` | Link mode for `add`/`link`: `symlink` (default) or `snapshot` (copy, for Codex compat) | `symlink` |
 
 ### Safety guards
 
-`link` refuses to operate if `working_set` resolves to your home directory or root (`/`). It also only removes **symlinks** from the working set — real files or directories are skipped with a warning.
+`link` refuses to operate if `working_set` resolves to your home directory or root (`/`).
+
+**Snapshot mode** (`--mode snapshot` or `link --mode snapshot`): copies the source directory into the working set instead of symlinking. This is needed for agents that don't support symlinks (e.g. Codex #11314). Snapshots are pinned to the cold pool version at link time. Use `deck sync <alias>` to switch back to live symlink mode, or `deck freeze <alias>` to pin a symlink as a snapshot.
 
 ### Exit codes
 
@@ -119,7 +128,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.31 link
+bunx @lythos/skill-deck@0.9.33 link
 ```
 
 ### Key Concepts
@@ -129,7 +138,7 @@ bunx @lythos/skill-deck@0.9.31 link
 | **Cold Pool** | All downloaded skills (`~/.agents/skill-repos/`). Agent cannot see here. |
 | **skill-deck.toml** | Declares desired state: "this project uses these skills." |
 | **`deck link`** | Reconciler. Makes the working set match the declaration. |
-| **Working Set** | Symlinks only. Default: `.claude/skills/` — where agents scan for skills. |
+| **Working Set** | Per-skill mode: symlink (live) or snapshot (pinned copy). Default: `.claude/skills/`. |
 | **deny-by-default** | Undeclared skills are physically absent from the working set. |
 
 ### Agent skill scan locations
@@ -148,7 +157,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@0.9.31 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.33 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 |
@@ -213,7 +222,7 @@ If you already have skills installed (in working set, globally, or mixed), deck
 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.
+4. EXECUTE deck link — creates symlinks (default) or snapshots (--mode snapshot), removes undeclared entries.
 
 5. VERIFY  Agent checks: all declared skills resolve? Working set clean?
            If unhappy: tar xf backup → rollback to pre-migration state.

package/package.json

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

package/src/cli.ts

@@ -7,6 +7,9 @@ import { updateDeck } from './update.js'
 import { migrateSchema } from './migrate-schema.js'
 import { removeSkill } from './remove.js'
 import { pruneDeck } from './prune.js'
+import { syncSkill, freezeSkill } from './sync-freeze.js'
+import { reconcileDeck } from './reconcile.js'
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from './resolve-deck.js'
 import { formatHelp } from './help.js'
 
 const args = process.argv.slice(2)
@@ -20,7 +23,22 @@ function flagValue(name: string): string | undefined {
   return idx >= 0 ? args[idx + 1] : undefined
 }
 
-const deckPath = flagValue('--deck')
+const cliDeck = flagValue('--deck')
+// URL deck: fetch first at the CLI dispatch layer, then pass local path to commands.
+// Commands stay sync; URL I/O is handled once here.
+let deckPath: string | undefined
+if (cliDeck && isUrl(cliDeck)) {
+  try {
+    deckPath = await fetchDeckUrl(cliDeck)
+  } catch (e: any) {
+    console.error(`❌ ${e.message}`)
+    process.exit(1)
+  }
+} else if (cliDeck) {
+  deckPath = resolveDeckPathSync(cliDeck).path
+} else {
+  deckPath = undefined
+}
 const workdir = flagValue('--workdir')
 const alias = flagValue('--alias')
 const type = flagValue('--type')
@@ -41,6 +59,9 @@ const HELP_CONFIG = {
     { name: 'validate', description: 'Validate deck configuration', args: '[deck.toml]' },
     { name: 'remove', description: 'Remove a skill from deck.toml and working set', args: '<fq|alias>' },
     { name: 'prune', description: 'GC cold pool repos no longer referenced by any deck', args: '[--yes]' },
+    { name: 'sync', description: 'Switch skill from snapshot (cp) to sync (symlink)', args: '<alias>' },
+    { name: 'freeze', description: 'Switch skill from sync (symlink) to snapshot (cp), pinning current HEAD', args: '<alias>' },
+    { name: 'reconcile', description: 'Compare lock file (desired) vs cold pool (actual), report drift', args: '[--apply]' },
     { name: 'migrate-schema', description: 'Convert string-array deck.toml to alias-as-key dict', args: '[--dry-run]' },
   ],
   options: [
@@ -100,6 +121,29 @@ switch (command) {
     removeSkill(removeTarget, deckPath, workdir)
     break
   }
+  case 'sync': {
+    const syncTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    if (!syncTarget) {
+      console.error('❌ Missing target. Usage: deck sync <alias>')
+      process.exit(1)
+    }
+    syncSkill(syncTarget, deckPath, workdir)
+    break
+  }
+  case 'freeze': {
+    const freezeTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    if (!freezeTarget) {
+      console.error('❌ Missing target. Usage: deck freeze <alias>')
+      process.exit(1)
+    }
+    freezeSkill(freezeTarget, deckPath, workdir)
+    break
+  }
+  case 'reconcile': {
+    const apply = args.includes('--apply')
+    reconcileDeck(deckPath, workdir, apply)
+    break
+  }
   case 'prune': {
     await pruneDeck(deckPath, workdir, yes)
     break

package/src/link.ts

@@ -23,6 +23,7 @@ import {
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
 } from "./schema.js";
 import { parseDeck } from "./parse-deck.js";
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from "./resolve-deck.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
@@ -129,33 +130,19 @@ export async function linkDeck(cliDeckPath?: string, cliWorkdir?: string, opts?:
 const MODE = opts?.mode ?? 'symlink'
 const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
 
-// If --deck is a URL, fetch it first (discovered via quick-agent.sh dogfooding)
-let DECK_PATH: string
-if (cliDeck && (cliDeck.startsWith('http://') || cliDeck.startsWith('https://'))) {
-  let url = cliDeck
-  if (url.includes('github.com/') && url.includes('/blob/')) {
-    url = url.replace('github.com/', 'raw.githubusercontent.com/').replace('/blob/', '/')
-  }
-  const dest = resolve(process.cwd(), 'skill-deck.toml')
-  console.log(`📥 Fetching deck: ${url}`)
-  try {
-    const res = await fetch(url, { signal: AbortSignal.timeout(30_000) })
-    if (!res.ok) {
-      console.error(`❌ Failed to fetch deck (HTTP ${res.status}): ${url}`)
+  // URL deck: fetch first, then proceed as local
+  let DECK_PATH: string
+  if (cliDeck && isUrl(cliDeck)) {
+    try {
+      DECK_PATH = await fetchDeckUrl(cliDeck)
+    } catch (e: any) {
+      console.error(`❌ ${e.message}`)
       process.exit(1)
     }
-    writeFileSync(dest, await res.text())
-    console.log(`   → saved to ${dest}`)
-    DECK_PATH = dest
-  } catch (e: any) {
-    console.error(`❌ Failed to fetch deck: ${e.message || e}`)
-    process.exit(1)
+  } else {
+    DECK_PATH = resolveDeckPathSync(cliDeck).path
   }
-} else {
-  DECK_PATH = cliDeck
-    ? resolve(cliDeck)
-    : findDeckToml(process.cwd()) || resolve("skill-deck.toml");
-}
+
 
 if (!existsSync(DECK_PATH)) {
   console.error(`❌ skill-deck.toml not found in ${process.cwd()}`);
@@ -469,6 +456,7 @@ for (const item of declared) {
     type: item.type,
     source: sourceRel,
     dest: relative(PROJECT_DIR, dest),
+    mode: MODE,
     content_hash: contentHash,
     linked_at: new Date().toISOString(),
     ...(item.expires ? { expires: item.expires } : {}),

package/src/prune-plan.test.ts

@@ -10,7 +10,7 @@ cold_pool = "./cold-pool"
 path = "github.com/foo/bar/skill-a"
 
 [tool.skills.skill-b]
-path = "localhost/skill-b"
+path = "localhost/me/skill-b"
 `
 
 describe('resolvePruneConfig', () => {
@@ -82,7 +82,7 @@ describe('buildPrunePlan', () => {
   test('empty candidates when all repos declared', () => {
     const pool = join('/tmp', 'prune-all-declared-' + Date.now())
     mkdirSync(join(pool, 'github.com', 'foo', 'bar', 'skill-a'), { recursive: true })
-    mkdirSync(join(pool, 'localhost', 'skill-b'), { recursive: true })
+    mkdirSync(join(pool, 'localhost', 'me', 'skill-b'), { recursive: true })
 
     const plan = buildPrunePlan(deckToml, { coldPool: pool })
     expect(plan.candidates).toHaveLength(0)

package/src/reconcile.ts

@@ -0,0 +1,115 @@
+#!/usr/bin/env bun
+/**
+ * deck reconcile — k8s-style desired vs actual convergence.
+ *
+ * Per ADR-20260507021957847: reads skill-deck.lock (desired state),
+ * compares against cold pool filesystem (actual state), reports diff.
+ * By default plan-first (report only); --apply executes convergence.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve, dirname, join } from 'node:path'
+import { findDeckToml, expandHome } from './link.js'
+import { parse as parseToml } from '@iarna/toml'
+import { ColdPool, buildReconcilePlan, type ReconcileDesiredState } from '@lythos/cold-pool'
+import { SkillDeckLockSchema } from './schema.js'
+
+export function reconcileDeck(cliDeckPath?: string, cliWorkdir?: string, apply?: boolean): void {
+  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === '--deck')
+  const DECK_PATH = cliDeck
+    ? resolve(cliDeck)
+    : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
+
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found`)
+    process.exit(1)
+  }
+
+  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : process.cwd()
+  const LOCK_PATH = resolve(PROJECT_DIR, 'skill-deck.lock')
+
+  if (!existsSync(LOCK_PATH)) {
+    console.error(`❌ No lock file found. Run 'deck link' first.`)
+    process.exit(1)
+  }
+
+  // Read lock
+  let lock: any
+  try {
+    lock = JSON.parse(readFileSync(LOCK_PATH, 'utf-8'))
+  } catch {
+    console.error(`❌ Failed to parse lock file: ${LOCK_PATH}`)
+    process.exit(1)
+  }
+
+  const parsed = SkillDeckLockSchema.safeParse(lock)
+  if (!parsed.success) {
+    console.error(`❌ Lock file schema mismatch. Run 'deck link' to regenerate.`)
+    process.exit(1)
+  }
+
+  const lockData = parsed.data
+  const coldPoolRaw = lockData.cold_pool || '~/.agents/skill-repos'
+  const COLD_POOL = expandHome(coldPoolRaw, PROJECT_DIR)
+
+  // Build desired state from lock
+  const desired: ReconcileDesiredState = {
+    deckPath: DECK_PATH,
+    skills: lockData.skills.map(s => ({
+      locator: s.source, // source is relative to cold pool, in FQ format
+      alias: s.alias,
+    })),
+  }
+
+  // Run reconcile plan
+  const pool = new ColdPool(COLD_POOL)
+  const plan = buildReconcilePlan(pool, desired)
+
+  // Report
+  console.log(`\n📊 Reconcile Report`)
+  console.log(`   Deck: ${lockData.deck_source.path}`)
+  console.log(`   Skills declared: ${lockData.skills.length}`)
+  console.log(`   Cold pool: ${COLD_POOL}`)
+
+  if (plan.missing.length === 0 && plan.behind.length === 0 && plan.extra.length === 0) {
+    console.log(`\n✅ No drift detected — cold pool matches desired state.`)
+    pool.metadata.close()
+    return
+  }
+
+  console.log(`\n🔍 Drift detected:`)
+  console.log(`   ❌ Missing: ${plan.missing.length}`)
+  console.log(`   ⚠️  Behind:  ${plan.behind.length}`)
+  console.log(`   📦 Extra:   ${plan.extra.length}`)
+
+  for (const entry of plan.missing) {
+    console.log(`\n   ❌ Missing: ${entry.host}/${entry.owner}/${entry.repo}`)
+    console.log(`      Reason: ${entry.reason}`)
+    console.log(`      Skills: ${entry.aliases.join(', ')}`)
+  }
+
+  for (const entry of plan.behind) {
+    console.log(`\n   ⚠️  Behind: ${entry.host}/${entry.owner}/${entry.repo}`)
+    console.log(`      ${entry.reason}`)
+    console.log(`      Skills: ${entry.aliases.join(', ')}`)
+  }
+
+  for (const entry of plan.extra) {
+    console.log(`\n   📦 Extra: ${entry.host}/${entry.owner}/${entry.repo}`)
+    console.log(`      Reason: ${entry.reason}`)
+  }
+
+  if (apply) {
+    console.log(`\n🏗️  --apply: convergence not yet implemented.`)
+    console.log(`   For missing: use 'deck add <locator>'`)
+    console.log(`   For behind: use 'deck refresh'`)
+    console.log(`   For extra: use 'cold-pool prune'`)
+  } else {
+    console.log(`\n💡 Plan-first. Use --apply to converge, or handle individually:`)
+    console.log(`   deck add <locator>   → restore missing`)
+    console.log(`   deck refresh         → update behind`)
+    console.log(`   cold-pool prune      → GC extras`)
+  }
+
+  pool.metadata.close()
+}

package/src/refresh-plan.test.ts

@@ -11,7 +11,7 @@ cold_pool = "./cold-pool"
 path = "github.com/foo/bar/skill-a"
 
 [tool.skills.skill-b]
-path = "localhost/skill-b"
+path = "localhost/me/skill-b"
 `
 
 describe('resolveRefreshConfig', () => {
@@ -111,7 +111,7 @@ describe('buildRefreshPlan', () => {
     // Without a real cold pool, source resolution may fail → 'missing'
     // Plan structure is what matters; type depends on actual filesystem
     expect(localhost).toBeDefined()
-    expect(localhost!.path).toBe('localhost/skill-b')
+    expect(localhost!.path).toBe('localhost/me/skill-b')
   })
 
   test('derives coldPool from deck toml when not in opts', () => {

package/src/resolve-deck.ts

@@ -0,0 +1,55 @@
+/**
+ * resolveDeckPath — shared deck URL/path resolution.
+ *
+ * Per ADR-20260508075301691: --deck accepts http/https URL.
+ * Extracted from link.ts so all commands (validate, add, refresh, etc.)
+ * inherit URL support without duplicating fetch logic.
+ *
+ * T1 of EPIC-20260508082810062 (Everything-from-URL).
+ */
+
+import { existsSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { findDeckToml } from './link.js'
+
+export interface ResolvedDeck {
+  path: string
+  source: 'url' | 'local' | 'default'
+}
+
+export function isUrl(s: string): boolean {
+  return s.startsWith('http://') || s.startsWith('https://')
+}
+
+function normalizeUrl(url: string): string {
+  try {
+    const u = new URL(url)
+    if (u.hostname === 'github.com' && u.pathname.includes('/blob/')) {
+      return `https://raw.githubusercontent.com${u.pathname.replace('/blob/', '/')}`
+    }
+  } catch {}
+  return url
+}
+
+/** Sync: resolve local path or default. URL case handled separately. */
+export function resolveDeckPathSync(cliArg?: string): ResolvedDeck {
+  if (cliArg) {
+    return { path: resolve(cliArg), source: 'local' }
+  }
+  const found = findDeckToml(process.cwd()) || resolve('skill-deck.toml')
+  return { path: found, source: 'default' }
+}
+
+/** Async: fetch URL deck, save to cwd, return local path. */
+export async function fetchDeckUrl(url: string): Promise<string> {
+  const normalized = normalizeUrl(url)
+  const dest = resolve(process.cwd(), 'skill-deck.toml')
+  console.log(`📥 Fetching deck: ${normalized}`)
+  const res = await fetch(normalized, { signal: AbortSignal.timeout(30_000) })
+  if (!res.ok) {
+    throw new Error(`Failed to fetch deck (HTTP ${res.status}): ${normalized}`)
+  }
+  writeFileSync(dest, await res.text())
+  console.log(`   → saved to ${dest}`)
+  return dest
+}

package/src/schema.ts

@@ -8,6 +8,8 @@ export const LinkedSkillSchema = z.object({
   type: z.enum(["innate", "tool", "combo", "transient"]),
   source: z.string(),
   dest: z.string(),
+  /** Link mode: symlink (live, follows cold pool) or snapshot (pinned copy). */
+  mode: z.enum(["symlink", "snapshot"]).default("symlink"),
   content_hash: z.string().optional(),
   linked_at: z.string().datetime(),
   expires: z.string().optional(),

package/src/sync-freeze.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test, beforeEach, afterEach } from 'bun:test'
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync, symlinkSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { syncSkill, freezeSkill } from './sync-freeze'
+import { cpSync, lstatSync } from 'node:fs'
+
+// Build a minimal project with a cold pool, deck.toml, working set, and lock
+function setupProject(opts: { mode: 'snapshot' | 'symlink' }) {
+  const project = mkdtempSync(join(tmpdir(), 'sync-freeze-test-'))
+  const coldPool = join(project, 'cold-pool')
+  const workingSet = join(project, '.claude', 'skills')
+
+  // Cold pool: create a fake skill repo
+  const skillDir = join(coldPool, 'github.com', 'test-org', 'test-skill')
+  mkdirSync(skillDir, { recursive: true })
+  writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: test-skill\ndescription: test\n---\n\n# Test Skill')
+
+  // Working set
+  mkdirSync(workingSet, { recursive: true })
+
+  // Create the target in working set per mode
+  const dest = join(workingSet, 'test-skill')
+  if (opts.mode === 'snapshot') {
+    // cp from cold pool
+    cpSync(skillDir, dest, { recursive: true })
+  } else {
+    symlinkSync(skillDir, dest)
+  }
+
+  // deck.toml
+  const deckToml = `
+[deck]
+max_cards = 10
+cold_pool = "cold-pool"
+working_set = ".claude/skills"
+
+[tool.skills.test-skill]
+path = "github.com/test-org/test-skill"
+`
+  writeFileSync(join(project, 'skill-deck.toml'), deckToml)
+
+  // lock file
+  const lock = {
+    version: '1.0.0' as const,
+    generated_at: new Date().toISOString(),
+    deck_source: { path: 'skill-deck.toml', content_hash: 'abc' },
+    working_set: '.claude/skills',
+    cold_pool: 'cold-pool',
+    skills: [
+      {
+        name: 'github.com/test-org/test-skill',
+        alias: 'test-skill',
+        deck_niche: '',
+        type: 'tool' as const,
+        source: 'github.com/test-org/test-skill',
+        dest: '.claude/skills/test-skill',
+        linked_at: new Date().toISOString(),
+        deck_managed_dirs: [],
+      },
+    ],
+    constraints: { total_cards: 1, max_cards: 10, within_budget: true, transient_warnings: [], dir_overlaps: [] },
+  }
+  writeFileSync(join(project, 'skill-deck.lock'), JSON.stringify(lock, null, 2))
+
+  const deckPath = join(project, 'skill-deck.toml')
+  return { project, coldPool, workingSet, skillDir, deckPath, dest }
+}
+
+describe('syncSkill — snapshot → symlink', () => {
+  test('switches real dir to symlink', () => {
+    const { deckPath, dest, project } = setupProject({ mode: 'snapshot' })
+    const originalCwd = process.cwd
+    const exit = process.exit
+
+    try {
+      process.cwd = () => project
+      process.exit = (() => { throw new Error('exit') }) as any
+      syncSkill('test-skill', deckPath, project)
+    } catch (e: any) {
+      if (e.message !== 'exit') throw e
+    } finally {
+      process.cwd = originalCwd
+      process.exit = exit
+    }
+
+    const st = lstatSync(dest)
+    expect(st.isSymbolicLink()).toBe(true)
+    rmSync(project, { recursive: true, force: true })
+  })
+
+  test('no-op when already symlink', () => {
+    const { deckPath, dest, project } = setupProject({ mode: 'symlink' })
+    const originalCwd = process.cwd
+    const exit = process.exit
+
+    try {
+      process.cwd = () => project
+      process.exit = (() => { throw new Error('exit') }) as any
+      syncSkill('test-skill', deckPath, project)
+    } catch (e: any) {
+      if (e.message !== 'exit') throw e
+    } finally {
+      process.cwd = originalCwd
+      process.exit = exit
+    }
+
+    const st = lstatSync(dest)
+    expect(st.isSymbolicLink()).toBe(true)
+    rmSync(project, { recursive: true, force: true })
+  })
+})
+
+describe('freezeSkill — symlink → snapshot', () => {
+  test('switches symlink to real dir', () => {
+    const { deckPath, dest, project } = setupProject({ mode: 'symlink' })
+    const originalCwd = process.cwd
+    const exit = process.exit
+
+    try {
+      process.cwd = () => project
+      process.exit = (() => { throw new Error('exit') }) as any
+      freezeSkill('test-skill', deckPath, project)
+    } catch (e: any) {
+      if (e.message !== 'exit') throw e
+    } finally {
+      process.cwd = originalCwd
+      process.exit = exit
+    }
+
+    const st = lstatSync(dest)
+    expect(st.isSymbolicLink()).toBe(false)
+    expect(st.isDirectory()).toBe(true)
+    // Should have SKILL.md
+    expect(readFileSync(join(dest, 'SKILL.md'), 'utf-8')).toContain('Test Skill')
+    rmSync(project, { recursive: true, force: true })
+  })
+
+  test('no-op when already snapshot', () => {
+    const { deckPath, dest, project } = setupProject({ mode: 'snapshot' })
+    const originalCwd = process.cwd
+    const exit = process.exit
+
+    try {
+      process.cwd = () => project
+      process.exit = (() => { throw new Error('exit') }) as any
+      freezeSkill('test-skill', deckPath, project)
+    } catch (e: any) {
+      if (e.message !== 'exit') throw e
+    } finally {
+      process.cwd = originalCwd
+      process.exit = exit
+    }
+
+    const st = lstatSync(dest)
+    expect(st.isDirectory()).toBe(true)
+    expect(st.isSymbolicLink()).toBe(false)
+    rmSync(project, { recursive: true, force: true })
+  })
+})

package/src/sync-freeze.ts

@@ -0,0 +1,174 @@
+#!/usr/bin/env bun
+/**
+ * deck sync/freeze — snapshot↔symlink intent switching per skill.
+ *
+ * Per ADR-20260507190157540: snapshot = default safe (cp), sync = live (symlink).
+ * These commands switch an individual skill between modes without re-linking all.
+ */
+
+import { existsSync, readFileSync, writeFileSync, rmSync, symlinkSync, cpSync, lstatSync } from 'node:fs'
+import { resolve, dirname, join, relative } from 'node:path'
+import { homedir } from 'node:os'
+import { findDeckToml, expandHome } from './link.js'
+import { parseDeck } from './parse-deck.js'
+import { ColdPool, parseLocator } from '@lythos/cold-pool'
+import { findSource } from './link.js'
+import { parse as parseToml } from '@iarna/toml'
+import type { SkillDeckLock } from './schema.js'
+
+function readLock(projectDir: string): SkillDeckLock | null {
+  const lockPath = join(projectDir, 'skill-deck.lock')
+  if (!existsSync(lockPath)) return null
+  try {
+    return JSON.parse(readFileSync(lockPath, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+function writeLock(projectDir: string, lock: SkillDeckLock): void {
+  const lockPath = join(projectDir, 'skill-deck.lock')
+  writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n')
+}
+
+function getProjectAndDeck(cliDeckPath?: string, cliWorkdir?: string) {
+  const cliDeck = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === '--deck')
+  const DECK_PATH = cliDeck
+    ? resolve(cliDeck)
+    : findDeckToml(process.cwd()) || resolve('skill-deck.toml')
+
+  if (!existsSync(DECK_PATH)) {
+    console.error(`❌ skill-deck.toml not found in ${process.cwd()}`)
+    process.exit(1)
+  }
+
+  const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH)
+  const deckRaw = readFileSync(DECK_PATH, 'utf-8')
+  const deck = parseToml(deckRaw) as any
+  const WORKING_SET = expandHome(deck.deck?.working_set || '.claude/skills', PROJECT_DIR)
+  const COLD_POOL = expandHome(deck.deck?.cold_pool || '~/.agents/skill-repos', PROJECT_DIR)
+
+  return { DECK_PATH, PROJECT_DIR, deckRaw, deck, WORKING_SET, COLD_POOL }
+}
+
+/**
+ * Switch a skill from snapshot (real dir) to sync (symlink).
+ * The skill stays in a real directory if it's already not a symlink.
+ */
+export function syncSkill(target: string, cliDeckPath?: string, cliWorkdir?: string): void {
+  const { DECK_PATH, PROJECT_DIR, deckRaw, WORKING_SET, COLD_POOL } = getProjectAndDeck(cliDeckPath, cliWorkdir)
+
+  const { entries: parsedEntries } = parseDeck(deckRaw)
+  const match = parsedEntries.find(e => e.alias === target || e.path === target)
+  if (!match) {
+    console.error(`❌ Skill not found in deck: ${target}`)
+    process.exit(1)
+  }
+
+  const dest = join(WORKING_SET, match.alias)
+  const source = findSource(match.path, COLD_POOL, PROJECT_DIR)
+
+  if (!source.path) {
+    console.error(`❌ Source not found in cold pool: ${match.path}`)
+    process.exit(1)
+  }
+
+  // Check current mode
+  let currentMode: 'snapshot' | 'symlink' | 'missing' = 'missing'
+  try {
+    const st = lstatSync(dest)
+    currentMode = st.isSymbolicLink() ? 'symlink' : 'snapshot'
+  } catch {}
+
+  if (currentMode === 'symlink') {
+    console.log(`⏭️  ${match.alias} is already in sync mode (symlink)`)
+    return
+  }
+
+  if (currentMode === 'missing') {
+    console.error(`❌ ${match.alias} not found in working set. Run 'deck link' first.`)
+    process.exit(1)
+  }
+
+  // Remove snapshot, create symlink
+  rmSync(dest, { recursive: true, force: true })
+  symlinkSync(source.path, dest)
+  console.log(`🔄 ${match.alias}: snapshot → sync (symlink to ${relative(PROJECT_DIR, source.path)})`)
+
+  // Update lock
+  const lock = readLock(PROJECT_DIR)
+  if (lock) {
+    const skill = lock.skills.find(s => s.alias === match.alias)
+    if (skill) {
+      skill.linked_at = new Date().toISOString()
+      skill.mode = 'symlink'
+    }
+    writeLock(PROJECT_DIR, lock)
+  }
+}
+
+/**
+ * Switch a skill from sync (symlink) to snapshot (real dir, pin current HEAD).
+ */
+export function freezeSkill(target: string, cliDeckPath?: string, cliWorkdir?: string): void {
+  const { DECK_PATH, PROJECT_DIR, deckRaw, WORKING_SET, COLD_POOL } = getProjectAndDeck(cliDeckPath, cliWorkdir)
+
+  const { entries: parsedEntries } = parseDeck(deckRaw)
+  const match = parsedEntries.find(e => e.alias === target || e.path === target)
+  if (!match) {
+    console.error(`❌ Skill not found in deck: ${target}`)
+    process.exit(1)
+  }
+
+  const dest = join(WORKING_SET, match.alias)
+  const source = findSource(match.path, COLD_POOL, PROJECT_DIR)
+
+  if (!source.path) {
+    console.error(`❌ Source not found in cold pool: ${match.path}`)
+    process.exit(1)
+  }
+
+  // Check current mode
+  let currentMode: 'snapshot' | 'symlink' | 'missing' = 'missing'
+  try {
+    const st = lstatSync(dest)
+    currentMode = st.isSymbolicLink() ? 'symlink' : 'snapshot'
+  } catch {}
+
+  if (currentMode === 'snapshot') {
+    console.log(`⏭️  ${match.alias} is already in snapshot mode (real directory)`)
+    return
+  }
+
+  if (currentMode === 'missing') {
+    console.error(`❌ ${match.alias} not found in working set. Run 'deck link' first.`)
+    process.exit(1)
+  }
+
+  // Remove symlink, cp snapshot
+  rmSync(dest, { recursive: true, force: true })
+  cpSync(source.path, dest, { recursive: true })
+  console.log(`🧊 ${match.alias}: sync → snapshot (pinned copy from ${relative(PROJECT_DIR, source.path)})`)
+
+  // Record HEAD in metadata
+  try {
+    const loc = parseLocator(match.path)
+    if (loc && !loc.isLocalhost) {
+      const pool = new ColdPool(COLD_POOL)
+      // Best-effort: record a note that this is now frozen
+      // The actual HEAD recording happens via git-hash async, but we note the intent
+      console.log(`   📌 Pinned. Run 'deck link' to regenerate lock with updated content_hash.`)
+    }
+  } catch {}
+
+  // Update lock
+  const lock = readLock(PROJECT_DIR)
+  if (lock) {
+    const skill = lock.skills.find(s => s.alias === match.alias)
+    if (skill) {
+      skill.linked_at = new Date().toISOString()
+      skill.mode = 'snapshot'
+    }
+    writeLock(PROJECT_DIR, lock)
+  }
+}

package/src/validate.ts

@@ -13,6 +13,7 @@
 import { parse as parseToml } from "@iarna/toml";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { resolveDeckPathSync, fetchDeckUrl, isUrl } from "./resolve-deck.js";
 import {
   buildValidationPlan,
   executeValidationPlan,
@@ -55,9 +56,17 @@ export async function buildDeckValidation(
   options: ValidateOptions = {},
 ): Promise<DeckValidationReport> {
   const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : process.cwd();
-  const DECK_PATH = cliDeckPath
-    ? resolve(cliDeckPath)
-    : findDeckToml(PROJECT_DIR) || resolve(PROJECT_DIR, "skill-deck.toml");
+  let DECK_PATH: string
+  if (cliDeckPath && isUrl(cliDeckPath)) {
+    try {
+      DECK_PATH = await fetchDeckUrl(cliDeckPath)
+    } catch (e: any) {
+      return { status: 'invalid', deckPath: cliDeckPath, errors: [`Failed to fetch deck: ${e.message}`], warnings: [], entries: [], skills: [], max_cards: 0, constraints: { total_cards: 0, within_budget: true, transient_warnings: [], dir_overlaps: [] } }
+    }
+  } else {
+    const resolved = resolveDeckPathSync(cliDeckPath)
+    DECK_PATH = resolved.path
+  }
 
   if (!existsSync(DECK_PATH)) {
     return {