@lythos/skill-deck 0.7.1 → 0.9.0

package/README.md

@@ -18,8 +18,8 @@ No installation required. `bunx` auto-downloads the package.
 [deck]
 max_cards = 10
 
-[tool]
-skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[tool.skills.lythoskill-deck]
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 ```
 
 ### skill-deck.toml (full reference)
@@ -30,22 +30,21 @@ max_cards = 10              # Hard limit on total skills
 working_set = ".claude/skills"      # Where symlinks are created
 cold_pool = "~/.agents/skill-repos" # Where skills are downloaded
 
-[innate]                    # Always-loaded skills
-skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[innate.skills.lythoskill-deck]     # Always-loaded skills
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 
-[tool]                      # Auto-triggered skills
-skills = [
-  "github.com/mattpocock/skills/skills/engineering/tdd",
-  "github.com/garrytan/gstack",
-]
+[tool.skills.tdd]                   # Auto-triggered skills
+path = "github.com/mattpocock/skills/skills/engineering/tdd"
 
-[combo]                     # Multi-skill bundles
-skills = ["github.com/anthropics/skills/skills/pdf"]
+[tool.skills.gstack]
+path = "github.com/garrytan/gstack"
 
-[transient]                 # Temporary skills with expiry
-  [transient.handoff]
-  path = "./skills/handoff" # Local path (not cold pool)
-  expires = "2026-05-01"    # ISO date; warns at ≤14 days
+[combo.skills.pdf]                  # Multi-skill bundles
+path = "github.com/anthropics/skills/skills/pdf"
+
+[transient.handoff]                 # Temporary skills with expiry
+path = "./skills/handoff" # Local path (not cold pool)
+expires = "2026-05-01"    # ISO date; warns at ≤14 days
 ```
 
 ### When to invoke
@@ -55,6 +54,10 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | 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` |
 
 ### Commands
@@ -63,7 +66,10 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 |---------|------|-------------|
 | `link` | `[--deck <path>] [--workdir <dir>]` | Sync working set. Removes undeclared skills (deny-by-default). |
 | `validate` | `[deck.toml] [--workdir <dir>]` | Validate deck config without modifying files. |
-| `add` | `<locator> [--via <backend>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `add` | `<locator> [--via <backend>] [--as <alias>] [--type <type>] [--deck <path>]` | Download skill to cold pool and append to skill-deck.toml. |
+| `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`). |
 
 ### Options
 
@@ -72,6 +78,8 @@ skills = ["github.com/anthropics/skills/skills/pdf"]
 | `--deck <path>` | Path to skill-deck.toml | Find upward from cwd |
 | `--workdir <dir>` | Working directory | cwd |
 | `--via <backend>` | Download backend for `add`: `git` or `skills.sh` | `git` |
+| `--as <alias>` | Explicit alias for the skill (default: basename of path) | — |
+| `--type <type>` | Target section for `add`: `innate`, `tool`, or `combo` | `tool` |
 
 ### Safety guards
 
@@ -102,8 +110,8 @@ cat > skill-deck.toml << 'EOF'
 [deck]
 max_cards = 10
 
-[tool]
-skills = ["github.com/lythos-labs/lythoskill/skills/lythoskill-deck"]
+[tool.skills.lythoskill-deck]
+path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
@@ -138,6 +146,8 @@ Different agents look for skills in different directories. `skill-deck.toml` con
 |---------|-------|-----|
 | `❌ 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 |
 | `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 |
 | `link` refuses with "budget exceeded" | Declared skills > `max_cards` | Increase `max_cards` in `skill-deck.toml` or remove unused skills |
 | `link` refuses with "unsafe working_set" | `working_set` resolves to `~` or `/` | Check `skill-deck.toml` has correct relative path (e.g. `.claude/skills/`) |
 | Agent doesn't see skills after `link` | `working_set` path doesn't match agent's scan location | Claude Code: `.claude/skills/`; Cursor: `.cursor/skills/`; Kimi: check your platform docs. Set `working_set` correctly |

package/package.json

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

package/src/add.ts

@@ -11,9 +11,10 @@ import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync,
 import { mkdtempSync } from 'node:fs'
 import { tmpdir, homedir } from 'node:os'
 import { join, basename, dirname, resolve } from 'node:path'
-import { execSync } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
 import { findDeckToml, expandHome } from './link.js'
+import { parseDeck } from './parse-deck.js'
 
 const CLAUDE_SKILLS_DIR = join(homedir(), '.claude', 'skills')
 
@@ -75,7 +76,7 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string }) {
+export async function addSkill(locator: string, options: { via?: string; deck?: string; workdir?: string; as?: string; type?: string }) {
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
     ? resolvePath(options.deck)
@@ -129,7 +130,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
             .map(e => e.name))
         : new Set<string>()
 
-      execSync(`npx skills add ${skillsShLocator} -g`, { cwd: tmpDir, stdio: 'inherit' })
+      execFileSync('npx', ['skills', 'add', skillsShLocator, '-g'], { cwd: tmpDir, stdio: 'inherit' })
 
       // Detect the newly installed directory
       const afterDirs = existsSync(CLAUDE_SKILLS_DIR)
@@ -154,7 +155,7 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     } else {
       const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
       console.log(`📦 Cloning: ${gitUrl}`)
-      execSync(`git clone --depth 1 ${gitUrl} ${tmpRepo}`, { stdio: 'inherit' })
+      execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
       skillSourceDir = tmpRepo
     }
 
@@ -174,26 +175,79 @@ export async function addSkill(locator: string, options: { via?: string; deck?:
     }
 
     const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    console.log(`✅ Skill ready: ${skillName}`)
+    const alias = options.as || skillName
+    const skillType = (options.type || 'tool').toLowerCase()
+
+    if (!['innate', 'tool', 'combo'].includes(skillType)) {
+      console.error(`❌ Invalid type: ${skillType}. Must be innate, tool, or combo.`)
+      process.exit(1)
+    }
+
+    const fqPath = parsed.skill
+      ? `${parsed.host}/${parsed.owner}/${parsed.repo}/${parsed.skill}`
+      : `${parsed.host}/${parsed.owner}/${parsed.repo}`
+
+    console.log(`✅ Skill ready: ${skillName} (alias: ${alias})`)
     console.log(`   Location: ${skillDir}`)
 
+    // ── 写 deck.toml ────────────────────────────────────────────
+
     if (existsSync(deckPath)) {
       const deckRaw = readFileSync(deckPath, 'utf-8')
       const deck = parseToml(deckRaw) as any
-      const toolSkills = deck.tool?.skills || []
-      if (!toolSkills.includes(skillName)) {
-        if (!deck.tool) deck.tool = {}
-        if (!deck.tool.skills) deck.tool.skills = []
-        deck.tool.skills.push(skillName)
-        writeFileSync(deckPath, stringifyToml(deck))
-        console.log(`📝 Added "${skillName}" to ${deckPath}`)
-      } else {
-        console.log(`📝 "${skillName}" already declared in ${deckPath}`)
+
+      // Alias collision check across all sections
+      const allAliases = new Set<string>()
+      for (const section of ['innate', 'tool', 'combo'] as const) {
+        const skills = deck[section]?.skills
+        if (skills && typeof skills === 'object' && !Array.isArray(skills)) {
+          for (const key of Object.keys(skills)) allAliases.add(key)
+        } else if (Array.isArray(skills)) {
+          for (const name of skills) allAliases.add(name.split('/').pop() || name)
+        }
+      }
+      for (const key of Object.keys(deck.transient || {})) {
+        allAliases.add(key)
       }
+      if (allAliases.has(alias)) {
+        console.error(`❌ Alias "${alias}" already exists in deck`)
+        process.exit(1)
+      }
+
+      // Auto-migrate old string-array format to dict
+      for (const section of ['innate', 'tool', 'combo'] as const) {
+        const sectionData = deck[section]
+        if (sectionData && Array.isArray(sectionData.skills)) {
+          const dict: Record<string, { path: string }> = {}
+          for (const name of sectionData.skills) {
+            const a = name.split('/').pop() || name
+            dict[a] = { path: name }
+          }
+          deck[section].skills = dict
+          console.log(`📝 Auto-migrated [${section}] from string-array to dict format`)
+        }
+      }
+
+      // Ensure target section exists and is dict format
+      if (!deck[skillType]) deck[skillType] = {}
+      if (!deck[skillType].skills) deck[skillType].skills = {}
+      if (Array.isArray(deck[skillType].skills)) {
+        const dict: Record<string, { path: string }> = {}
+        for (const name of deck[skillType].skills) {
+          const a = name.split('/').pop() || name
+          dict[a] = { path: name }
+        }
+        deck[skillType].skills = dict
+      }
+
+      deck[skillType].skills[alias] = { path: fqPath }
+      writeFileSync(deckPath, stringifyToml(deck))
+      console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
     } else {
-      const minimal = { deck: { max_cards: 10 }, tool: { skills: [skillName] } }
+      const minimal: any = { deck: { max_cards: 10 } }
+      minimal[skillType] = { skills: { [alias]: { path: fqPath } } }
       writeFileSync(deckPath, stringifyToml(minimal))
-      console.log(`📝 Created ${deckPath} with "${skillName}"`)
+      console.log(`📝 Created ${deckPath} with "${alias}"`)
     }
 
     console.log('🔗 Running deck link...')

package/src/cli.ts

@@ -2,38 +2,53 @@
 import { linkDeck } from './link.js'
 import { validateDeck } from './validate.js'
 import { addSkill } from './add.js'
+import { refreshDeck } from './refresh.js'
 import { updateDeck } from './update.js'
+import { migrateSchema } from './migrate-schema.js'
+import { removeSkill } from './remove.js'
+import { pruneDeck } from './prune.js'
 import { formatHelp } from './help.js'
 
+const args = process.argv.slice(2)
+const command = args[0]
+
+const deckFlagIdx = args.indexOf('--deck')
+const workdirFlagIdx = args.indexOf('--workdir')
+const viaFlagIdx = args.indexOf('--via')
+const asFlagIdx = args.indexOf('--as')
+const typeFlagIdx = args.indexOf('--type')
+
+const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
+const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
+const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
+const as = asFlagIdx >= 0 ? args[asFlagIdx + 1] : undefined
+const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
+const noBackup = args.includes('--no-backup')
+const yes = args.includes('--yes')
+
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
   description: 'Declarative skill deck governance — cold pool, working set, deny-by-default',
   commands: [
     { name: 'link', description: 'Sync working set with skill-deck.toml' },
     { name: 'add', description: 'Download skill to cold pool and add to deck', args: '<locator>' },
-    { name: 'update', description: 'Pull latest versions of declared skills from upstream' },
+    { name: 'refresh', description: 'Pull latest versions of declared skills from upstream', args: '[<fq|alias>]' },
     { 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: 'migrate-schema', description: 'Convert string-array deck.toml to alias-as-key dict', args: '[--dry-run]' },
   ],
   options: [
     { flag: '--deck <path>', description: 'Specify skill-deck.toml path (default: find upward from cwd)' },
     { flag: '--workdir <dir>', description: 'Specify working directory (default: cwd)' },
     { flag: '--no-backup', description: 'Skip tar backup when removing non-symlink entries' },
     { flag: '--via <backend>', description: 'Download backend: git (default) | skills.sh' },
+    { flag: '--as <alias>', description: 'Explicit alias for the skill (default: basename of path)' },
+    { flag: '--type <type>', description: 'Target section: innate | tool | combo (default: tool)' },
+    { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
   ],
 }
 
-const args = process.argv.slice(2)
-const command = args[0]
-
-const deckFlagIdx = args.indexOf('--deck')
-const workdirFlagIdx = args.indexOf('--workdir')
-const viaFlagIdx = args.indexOf('--via')
-
-const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
-const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
-const via = viaFlagIdx >= 0 ? args[viaFlagIdx + 1] : undefined
-const noBackup = args.includes('--no-backup')
-
 switch (command) {
   case '--help':
   case '-h':
@@ -48,15 +63,49 @@ switch (command) {
       console.error('❌ Missing locator. Usage: deck add <github.com/owner/repo[/skill]>')
       process.exit(1)
     }
-    await addSkill(locator, { via, deck: deckPath, workdir })
+    await addSkill(locator, { via, deck: deckPath, workdir, as, type })
+    break
+  }
+  case 'refresh': {
+    const refreshTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    refreshDeck(deckPath, workdir, refreshTarget)
     break
   }
-  case 'update':
-    updateDeck(deckPath, workdir)
+  case 'update': {
+    const updateTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    updateDeck(deckPath, workdir, updateTarget)
     break
+  }
   case 'validate':
     validateDeck(deckPath, workdir)
     break
+  case 'remove': {
+    const removeTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined
+    if (!removeTarget) {
+      console.error('❌ Missing target. Usage: deck remove <fq|alias>')
+      process.exit(1)
+    }
+    removeSkill(removeTarget, deckPath, workdir)
+    break
+  }
+  case 'prune': {
+    await pruneDeck(deckPath, workdir, yes)
+    break
+  }
+  case 'migrate-schema': {
+    const dryRun = args.includes('--dry-run')
+    const targetPath = deckPath || 'skill-deck.toml'
+    const result = migrateSchema(targetPath, dryRun)
+    if (result.diff) {
+      console.log(result.message)
+      console.log('---')
+      console.log(result.diff)
+    } else {
+      console.log(result.message)
+    }
+    if (!result.migrated) process.exit(0)
+    break
+  }
   default:
     console.error(formatHelp(HELP_CONFIG))
     process.exit(1)

package/src/link.ts

@@ -14,13 +14,14 @@ import {
   existsSync, mkdirSync, readFileSync, readdirSync,
   symlinkSync, lstatSync, rmSync, statSync, writeFileSync,
 } from "node:fs";
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import { resolve, dirname, join, basename, relative } from "node:path";
 import { homedir } from "node:os";
 import {
   SkillDeckLockSchema,
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
 } from "./schema.js";
+import { parseDeck } from "./parse-deck.js";
 
 // ── 路径工具 ────────────────────────────────────────────────
 
@@ -173,42 +174,47 @@ if (!existsSync(DECK_PATH)) {
 const PROJECT_DIR = cliWorkdir ? resolve(cliWorkdir) : dirname(DECK_PATH);
 const deckRaw = readFileSync(DECK_PATH, "utf-8");
 const deckHash = hashContent(deckRaw);
-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);
-const MAX_CARDS = Number(deck.deck?.max_cards || 10);
+const { entries: parsedEntries, deprecated: isDeprecated, errors: parseErrors } = parseDeck(deckRaw);
+if (isDeprecated) {
+  console.warn("⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+}
+
+const parsedToml = parseToml(deckRaw) as any;
+const WORKING_SET_RAW = parsedToml.deck?.working_set || ".claude/skills";
+const COLD_POOL_RAW = parsedToml.deck?.cold_pool || "~/.agents/skill-repos";
+const WORKING_SET = expandHome(WORKING_SET_RAW, PROJECT_DIR);
+const COLD_POOL = expandHome(COLD_POOL_RAW, PROJECT_DIR);
+const MAX_CARDS = Number(parsedToml.deck?.max_cards || 10);
 
 // ── 收集声明 ────────────────────────────────────────────────
 
 interface DeclaredSkill {
-  name: string;
+  name: string;        // original path/name (for lock.source backward-compat)
+  alias: string;       // working-set flat symlink name
   type: "innate" | "tool" | "combo" | "transient";
   sourcePath: string;
   expires?: string;
 }
 
 const declared: DeclaredSkill[] = [];
-const errors: string[] = [];
-
-for (const section of ["innate", "tool", "combo"] as const) {
-  for (const name of (deck[section]?.skills || [])) {
-    if (!name || typeof name !== "string") continue;
-    const result = findSource(name, COLD_POOL, PROJECT_DIR);
-    if (result.error) {
-      errors.push(result.error);
-      continue;
-    }
-    if (!result.path) {
-      errors.push(`Skill not found: ${name}`);
-      continue;
-    }
-    declared.push({ name, type: section, sourcePath: result.path });
+const errors: string[] = [...parseErrors];
+
+for (const entry of parsedEntries) {
+  const result = findSource(entry.path, COLD_POOL, PROJECT_DIR);
+  if (result.error) {
+    errors.push(result.error);
+    continue;
+  }
+  if (!result.path) {
+    errors.push(`Skill not found: ${entry.path}`);
+    continue;
   }
+  declared.push({ name: entry.path, alias: entry.alias, type: entry.type, sourcePath: result.path });
 }
 
-// transient: sub-tables with path field
-for (const [key, value] of Object.entries(deck.transient || {})) {
+// transient: sub-tables with path field (kept backward-compat; future ADR may unify)
+for (const [key, value] of Object.entries(parsedToml.transient || {})) {
   const t = value as any;
   if (!t?.path) continue;
   const src = resolve(PROJECT_DIR, t.path);
@@ -216,7 +222,22 @@ for (const [key, value] of Object.entries(deck.transient || {})) {
     errors.push(`Transient path does not exist: ${key} → ${src}`);
     continue;
   }
-  declared.push({ name: key, type: "transient", sourcePath: src, expires: t.expires });
+  declared.push({ name: key, alias: key, type: "transient", sourcePath: src, expires: t.expires });
+}
+
+// ── 跨 type alias collision 检测 ──────────────────────────────
+const aliasToTypes = new Map<string, string[]>();
+for (const d of declared) {
+  const types = aliasToTypes.get(d.alias) || [];
+  types.push(d.type);
+  aliasToTypes.set(d.alias, types);
+}
+for (const [alias, types] of aliasToTypes) {
+  if (types.length > 1) {
+    errors.push(
+      `Alias collision: "${alias}" appears in [${types.join('], [')}]. Use --as to specify different aliases.`
+    );
+  }
 }
 
 if (errors.length > 0) {
@@ -240,6 +261,12 @@ if (errors.length > 0) {
   }
   // 继续执行已找到的 skill，不因个别缺失中断全部
 
+  // fatal errors: alias collision must block
+  const fatalErrors = errors.filter(e => e.includes('Alias collision'));
+  if (fatalErrors.length > 0) {
+    process.exit(1);
+  }
+
   // 引导：如果 cold pool 为空，给出更明确的指引
   const hasSkills = existsSync(COLD_POOL) && readdirSync(COLD_POOL).filter(e => !e.startsWith('.')).length > 0;
   if (!hasSkills) {
@@ -326,7 +353,7 @@ if (nonSymlinks.length > 0) {
       ...nonSymlinks.map(e => relative(PROJECT_DIR, join(WORKING_SET, e))),
     ];
     try {
-      execSync("tar " + tarArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" "), {
+      execFileSync("tar", tarArgs, {
         cwd: PROJECT_DIR,
         stdio: "pipe",
       });
@@ -346,7 +373,7 @@ if (nonSymlinks.length > 0) {
 }
 
 // 清理未声明的 symlink
-const declaredNames = new Set(declared.map(d => d.name.split("/")[0]));
+const declaredNames = new Set(declared.map(d => d.alias));
 try {
   for (const entry of readdirSync(WORKING_SET)) {
     if (entry.startsWith("_") || entry.startsWith(".")) continue;
@@ -366,7 +393,7 @@ try {
 const linkedSkills: LinkedSkill[] = [];
 
 for (const item of declared) {
-  const dest = join(WORKING_SET, item.name);
+  const dest = join(WORKING_SET, item.alias);
 
   // 幂等：已存在则删除重建（lstat 不跟随 symlink，能处理断链/自引用 symlink）
   try {
@@ -378,7 +405,7 @@ for (const item of declared) {
     mkdirSync(dirname(dest), { recursive: true });
     symlinkSync(item.sourcePath, dest);
   } catch (err: any) {
-    console.error(`❌ Link failed: ${item.name}: ${err.message}`);
+    console.error(`❌ Link failed: ${item.alias}: ${err.message}`);
     continue;
   }
 
@@ -396,19 +423,25 @@ for (const item of declared) {
     contentHash = hashContent(readFileSync(skillMdPath, "utf-8"));
   } catch {}
 
+  // source: relative to cold_pool (non-transient) or project dir (transient)
+  const sourceRel = item.type === "transient"
+    ? relative(PROJECT_DIR, item.sourcePath)
+    : relative(COLD_POOL, item.sourcePath);
+
   linkedSkills.push({
     name: item.name,
+    alias: item.alias,
     deck_niche: niche,
     type: item.type,
-    source: item.sourcePath,
-    dest,
+    source: sourceRel,
+    dest: relative(PROJECT_DIR, dest),
     content_hash: contentHash,
     linked_at: new Date().toISOString(),
     ...(item.expires ? { expires: item.expires } : {}),
     deck_managed_dirs: managedDirs,
   });
 
-  console.log(`  🔗 ${item.name}`);
+  console.log(`  🔗 ${item.alias}`);
 }
 
 // ── Transient 过期检查 ──────────────────────────────────────
@@ -479,9 +512,9 @@ const constraints: ConstraintReport = {
 const lock: SkillDeckLock = {
   version: "1.0.0",
   generated_at: new Date().toISOString(),
-  deck_source: { path: DECK_PATH, content_hash: deckHash },
-  working_set: WORKING_SET,
-  cold_pool: COLD_POOL,
+  deck_source: { path: relative(PROJECT_DIR, DECK_PATH), content_hash: deckHash },
+  working_set: WORKING_SET_RAW,
+  cold_pool: COLD_POOL_RAW,
   skills: linkedSkills,
   constraints,
 };

package/src/migrate-schema.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+import { parse as parseToml, stringify } from "@iarna/toml";
+import { readFileSync, writeFileSync, renameSync } from "node:fs";
+import { parseDeck } from "./parse-deck.js";
+
+export interface MigrateResult {
+  migrated: boolean;
+  message: string;
+  diff?: string;
+}
+
+export function migrateSchema(deckPath: string, dryRun: boolean): MigrateResult {
+  const raw = readFileSync(deckPath, "utf-8");
+  const { deprecated } = parseDeck(raw);
+
+  if (!deprecated) {
+    return {
+      migrated: false,
+      message: "No migration needed: deck.toml already uses alias-as-key dict schema.",
+    };
+  }
+
+  const parsed = parseToml(raw) as any;
+
+  for (const section of ["innate", "tool", "combo"] as const) {
+    const skills = parsed[section]?.skills;
+    if (!Array.isArray(skills)) continue;
+
+    delete parsed[section].skills;
+    const entries: Record<string, { path: string }> = {};
+    for (const name of skills) {
+      if (!name || typeof name !== "string") continue;
+      const alias = name.split("/").pop() || name;
+      entries[alias] = { path: name };
+    }
+    parsed[section] = { skills: entries };
+  }
+
+  const newToml = stringify(parsed);
+
+  if (dryRun) {
+    return {
+      migrated: true,
+      message: `Dry run — would migrate ${deckPath} to alias-as-key dict schema:`,
+      diff: newToml,
+    };
+  }
+
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  const backupPath = `${deckPath}.bak.${ts}`;
+  renameSync(deckPath, backupPath);
+  writeFileSync(deckPath, newToml);
+
+  return {
+    migrated: true,
+    message: `Migrated ${deckPath} → alias-as-key dict schema. Backup: ${backupPath}`,
+  };
+}

package/src/parse-deck.ts

@@ -0,0 +1,78 @@
+import { parse as parseToml } from "@iarna/toml";
+import { SkillEntrySchema } from "./schema.js";
+
+export type SkillType = "innate" | "tool" | "combo";
+
+export interface ParsedSkillEntry {
+  alias: string; // working-set flat symlink name = role identity
+  path: string;  // FQ locator or local path
+  type: SkillType;
+  role?: string;
+  why_in_deck?: string;
+  [key: string]: unknown; // forward-compat: unknown fields pass through
+}
+
+export interface ParsedDeck {
+  entries: ParsedSkillEntry[];
+  deprecated: boolean; // true if any section used legacy string-array
+  errors: string[];
+}
+
+export function parseDeck(raw: string): ParsedDeck {
+  const parsed = parseToml(raw) as any;
+  const entries: ParsedSkillEntry[] = [];
+  const errors: string[] = [];
+  let deprecated = false;
+
+  for (const section of ["innate", "tool", "combo"] as const) {
+    const sectionData = parsed[section];
+    if (!sectionData) continue;
+
+    // ── New format: [<type>.skills.<alias>] with path in body ──
+    if (
+      sectionData.skills &&
+      typeof sectionData.skills === "object" &&
+      !Array.isArray(sectionData.skills)
+    ) {
+      for (const [alias, entry] of Object.entries(sectionData.skills)) {
+        const e = entry as Record<string, unknown>;
+        if (!e?.path || typeof e.path !== "string") {
+          errors.push(
+            `Missing path for skill "${alias}" in [${section}.skills.${alias}]`
+          );
+          continue;
+        }
+        const parsedEntry = SkillEntrySchema.safeParse(e);
+        if (!parsedEntry.success) {
+          errors.push(
+            `Invalid entry "${alias}" in [${section}.skills.${alias}]: ${parsedEntry.error.message}`
+          );
+          continue;
+        }
+        entries.push({
+          alias,
+          path: e.path as string,
+          type: section,
+          ...parsedEntry.data,
+        });
+      }
+      continue;
+    }
+
+    // ── Legacy format: [<type>] with skills = ["...", ...] ──
+    const skillsArray = sectionData?.skills;
+    if (Array.isArray(skillsArray)) {
+      deprecated = true;
+      for (const name of skillsArray) {
+        if (!name || typeof name !== "string") continue;
+        entries.push({
+          alias: name.split("/").pop() || name,
+          path: name,
+          type: section,
+        });
+      }
+    }
+  }
+
+  return { entries, deprecated, errors };
+}

package/src/prune.ts

@@ -0,0 +1,196 @@
+#!/usr/bin/env bun
+/**
+ * deck-prune.ts — Cold pool garbage collection
+ *
+ * Scans the cold pool for repositories no longer referenced by any
+ * skill-deck.toml declaration and offers to delete them.
+ * Does NOT modify deck.toml or the working set.
+ */
+
+import { parse as parseToml } from "@iarna/toml";
+import { existsSync, readFileSync, readdirSync, statSync, rmSync } from "node:fs";
+import { resolve, dirname, join, relative } from "node:path";
+import { createInterface } from "node:readline";
+import { findDeckToml, expandHome, findSource } from "./link.js";
+import { parseDeck } from "./parse-deck.js";
+
+interface PruneCandidate {
+  repoPath: string;
+  repoRel: string;
+  size: number;
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
+}
+
+function calculateDirSize(dir: string): number {
+  let total = 0;
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        total += calculateDirSize(p);
+      } else if (entry.isFile()) {
+        total += statSync(p).size;
+      }
+    }
+  } catch {}
+  return total;
+}
+
+function scanColdPoolRepos(coldPool: string): string[] {
+  const repos: string[] = [];
+  try {
+    for (const host of readdirSync(coldPool, { withFileTypes: true })) {
+      if (!host.isDirectory() || host.name.startsWith(".")) continue;
+      const hostPath = join(coldPool, host.name);
+      for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
+        if (!owner.isDirectory() || owner.name.startsWith(".")) continue;
+        const ownerPath = join(hostPath, owner.name);
+        for (const repo of readdirSync(ownerPath, { withFileTypes: true })) {
+          if (!repo.isDirectory() || repo.name.startsWith(".")) continue;
+          repos.push(join(ownerPath, repo.name));
+        }
+      }
+    }
+  } catch {}
+  return repos;
+}
+
+function isRepoReferenced(repoPath: string, declaredPaths: string[], coldPool: string, projectDir: string): boolean {
+  for (const path of declaredPaths) {
+    const result = findSource(path, coldPool, projectDir);
+    if (result.path) {
+      // Check if the resolved skill path is inside this repo
+      const rel = relative(repoPath, result.path);
+      if (!rel.startsWith("..") && rel !== "") {
+        return true;
+      }
+      if (result.path === repoPath) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+async function confirm(message: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${message} (y/N) `, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
+export async function pruneDeck(cliDeckPath?: string, cliWorkdir?: string, yes?: boolean): Promise<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 in ${process.cwd()}`);
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
+    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 COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+
+  // ── 收集声明 ────────────────────────────────────────────────
+
+  const { entries: parsedEntries } = parseDeck(deckRaw);
+  const declaredPaths = parsedEntries.map(e => e.path);
+
+  // Legacy string-array fallback
+  for (const section of ["innate", "tool", "combo"] as const) {
+    const skills = deck[section]?.skills;
+    if (Array.isArray(skills)) {
+      for (const name of skills) {
+        if (name && typeof name === "string" && !declaredPaths.includes(name)) {
+          declaredPaths.push(name);
+        }
+      }
+    }
+  }
+
+  // ── 扫描 cold pool ──────────────────────────────────────────
+
+  if (!existsSync(COLD_POOL)) {
+    console.log("📭 Cold pool does not exist. Nothing to prune.");
+    process.exit(0);
+  }
+
+  const allRepos = scanColdPoolRepos(COLD_POOL);
+  if (allRepos.length === 0) {
+    console.log("📭 Cold pool is empty. Nothing to prune.");
+    process.exit(0);
+  }
+
+  // ── 求差集 ──────────────────────────────────────────────────
+
+  const candidates: PruneCandidate[] = [];
+  for (const repoPath of allRepos) {
+    if (isRepoReferenced(repoPath, declaredPaths, COLD_POOL, PROJECT_DIR)) continue;
+    const size = calculateDirSize(repoPath);
+    candidates.push({ repoPath, repoRel: relative(COLD_POOL, repoPath), size });
+  }
+
+  if (candidates.length === 0) {
+    console.log("✅ All cold pool repositories are referenced. Nothing to prune.");
+    process.exit(0);
+  }
+
+  // ── 报告 ────────────────────────────────────────────────────
+
+  const totalSize = candidates.reduce((sum, c) => sum + c.size, 0);
+  console.log(`\n🧹 Prune candidates — ${candidates.length} repo(s), ${formatSize(totalSize)} total:\n`);
+  for (const c of candidates) {
+    console.log(`   ${c.repoRel} (${formatSize(c.size)})`);
+  }
+
+  // ── 确认 ────────────────────────────────────────────────────
+
+  let shouldDelete = false;
+  if (yes) {
+    shouldDelete = true;
+    console.log("\n⚠️  --yes flag set: deleting without confirmation.");
+  } else {
+    shouldDelete = await confirm(`\nDelete ${candidates.length} unreferenced repo(s)?`);
+  }
+
+  if (!shouldDelete) {
+    console.log("❎ Prune cancelled.");
+    process.exit(0);
+  }
+
+  // ── 执行删除 ────────────────────────────────────────────────
+
+  let deleted = 0;
+  let failed = 0;
+  for (const c of candidates) {
+    try {
+      rmSync(c.repoPath, { recursive: true, force: true });
+      console.log(`  🗑️  Deleted: ${c.repoRel}`);
+      deleted++;
+    } catch (err: any) {
+      console.error(`  ❌ Failed to delete ${c.repoRel}: ${err.message}`);
+      failed++;
+    }
+  }
+
+  console.log(`\n📦 Prune complete: ${deleted} deleted, ${failed} failed`);
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}

package/src/refresh.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env bun
+/**
+ * deck-refresh.ts — Refresh declared skills from their upstream sources
+ *
+ * Reads skill-deck.toml → traverses declared skills → git pull.
+ * Supports single-skill (by FQ path or alias) or all skills.
+ * Never modifies deck.toml.
+ */
+
+import { parse as parseToml } from "@iarna/toml";
+import { existsSync, readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { resolve, dirname, join, relative } from "node:path";
+import { findDeckToml, expandHome, findSource, linkDeck } from "./link.js";
+import { parseDeck } from "./parse-deck.js";
+
+interface RefreshResult {
+  name: string;
+  path: string;
+  status: "updated" | "up-to-date" | "skipped" | "failed" | "not-git";
+  message?: string;
+}
+
+function isGitRepo(dir: string): boolean {
+  return existsSync(join(dir, ".git"));
+}
+
+function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; message: string } {
+  try {
+    const output = execSync("git pull", {
+      cwd: dir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 30000,
+    }).trim();
+
+    if (output.includes("Already up to date") || output.includes("Already up-to-date")) {
+      return { status: "up-to-date", message: output };
+    }
+    return { status: "updated", message: output };
+  } catch (err: any) {
+    const stderr = err.stderr?.toString() || err.message || "";
+    return { status: "failed", message: stderr.trim() };
+  }
+}
+
+export function refreshDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): 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 in ${process.cwd()}`);
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
+    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 COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
+
+  // ── 收集声明 ────────────────────────────────────────────────
+
+  const declared: { name: string; alias: string; path: string; type: string }[] = [];
+
+  // Use parseDeck for alias-dict compatibility
+  const { entries: parsedEntries, deprecated: isDeprecated } = parseDeck(deckRaw);
+  if (isDeprecated) {
+    console.warn("⚠️  Deprecation: string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
+  }
+
+  for (const entry of parsedEntries) {
+    declared.push({ name: entry.path, alias: entry.alias, path: entry.path, type: entry.type });
+  }
+
+  if (declared.length === 0) {
+    console.log("📭 No skills declared in deck. Nothing to refresh.");
+    process.exit(0);
+  }
+
+  // ── 确定目标 ────────────────────────────────────────────────
+
+  let targets: { name: string; alias: string; path: string; type: string }[];
+
+  if (target) {
+    // Try resolve as alias first, then as FQ path
+    const byAlias = declared.find(d => d.alias === target);
+    if (byAlias) {
+      targets = [byAlias];
+    } else {
+      const byPath = declared.find(d => d.path === target);
+      if (byPath) {
+        targets = [byPath];
+      } else {
+        console.error(`❌ Skill not found in deck: ${target}`);
+        console.error(`   Declared aliases: ${declared.map(d => d.alias).join(", ")}`);
+        process.exit(1);
+      }
+    }
+  } else {
+    targets = declared;
+  }
+
+  // ── 执行刷新 ────────────────────────────────────────────────
+
+  const results: RefreshResult[] = [];
+  let updated = 0;
+  let upToDate = 0;
+  let skipped = 0;
+  let failed = 0;
+
+  for (const item of targets) {
+    const result = findSource(item.path, COLD_POOL, PROJECT_DIR);
+
+    if (result.error || !result.path) {
+      results.push({ name: item.alias, path: "", status: "failed", message: result.error || "Skill not found in cold pool" });
+      failed++;
+      continue;
+    }
+
+    const path = result.path;
+
+    // localhost skills are user-managed; skip
+    const relativePath = relative(COLD_POOL, path);
+    if (relativePath.startsWith("localhost")) {
+      results.push({ name: item.alias, path: relativePath, status: "skipped", message: "localhost skill — user-managed" });
+      skipped++;
+      continue;
+    }
+
+    if (!isGitRepo(path)) {
+      results.push({ name: item.alias, path: relativePath, status: "not-git", message: "Not a git repository" });
+      skipped++;
+      continue;
+    }
+
+    const pullResult = gitPull(path);
+    results.push({ name: item.alias, path: relativePath, status: pullResult.status, message: pullResult.message });
+
+    if (pullResult.status === "updated") updated++;
+    else if (pullResult.status === "up-to-date") upToDate++;
+    else failed++;
+  }
+
+  // ── 报告 ────────────────────────────────────────────────────
+
+  const scope = target ? `single skill` : `${declared.length} skill(s)`;
+  console.log(`\n📦 Skill Refresh Report — ${scope} checked`);
+  console.log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`);
+  console.log();
+
+  for (const r of results) {
+    const icon =
+      r.status === "updated" ? "🔄" :
+      r.status === "up-to-date" ? "✅" :
+      r.status === "skipped" ? "⏭️" :
+      r.status === "not-git" ? "📁" :
+      "❌";
+    console.log(`${icon} ${r.name}`);
+    if (r.message && r.status !== "up-to-date") {
+      const lines = r.message.split("\n").filter(l => l.trim());
+      for (const line of lines.slice(0, 3)) {
+        console.log(`   ${line.trim()}`);
+      }
+      if (lines.length > 3) {
+        console.log(`   ... (${lines.length - 3} more lines)`);
+      }
+    }
+  }
+
+  if (updated > 0) {
+    console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync refreshed skills to working set.`);
+    console.log("🔗 Running deck link...");
+    linkDeck(cliDeckPath, cliWorkdir);
+  }
+
+  if (failed > 0) {
+    process.exit(1);
+  }
+}

package/src/remove.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+/**
+ * deck-remove.ts — Remove a skill from the declaration layer
+ *
+ * Deletes the entry from skill-deck.toml and removes the working-set symlink.
+ * Does NOT touch the cold pool (use `deck prune` for material-layer GC).
+ */
+
+import { parse as parseToml, stringify as stringifyToml } from "@iarna/toml";
+import { existsSync, readFileSync, writeFileSync, rmSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { findDeckToml, expandHome } from "./link.js";
+import { parseDeck } from "./parse-deck.js";
+
+export function removeSkill(target: string, cliDeckPath?: string, cliWorkdir?: string): 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 in ${process.cwd()}`);
+    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
+    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 { entries: parsedEntries } = parseDeck(deckRaw);
+
+  // Match by alias first, then by path
+  const match = parsedEntries.find(e => e.alias === target || e.path === target);
+
+  if (!match) {
+    console.error(`❌ Skill not found in deck: ${target}`);
+    const aliases = parsedEntries.map(e => e.alias);
+    if (aliases.length > 0) {
+      console.error(`   Declared aliases: ${aliases.join(", ")}`);
+    }
+    process.exit(1);
+  }
+
+  // ── 删 deck.toml 条目 ───────────────────────────────────────
+
+  const section = match.type;
+  const alias = match.alias;
+
+  if (deck[section]?.skills) {
+    if (Array.isArray(deck[section].skills)) {
+      // Legacy string-array format
+      deck[section].skills = deck[section].skills.filter((name: string) => {
+        const a = name.split("/").pop() || name;
+        return a !== alias;
+      });
+      if (deck[section].skills.length === 0) {
+        delete deck[section].skills;
+      }
+    } else if (typeof deck[section].skills === "object") {
+      // Dict format
+      delete deck[section].skills[alias];
+      if (Object.keys(deck[section].skills).length === 0) {
+        delete deck[section].skills;
+      }
+    }
+    // Clean up empty section
+    if (Object.keys(deck[section] || {}).length === 0) {
+      delete deck[section];
+    }
+  }
+
+  writeFileSync(DECK_PATH, stringifyToml(deck));
+  console.log(`📝 Removed "${alias}" from [${section}.skills] in ${DECK_PATH}`);
+
+  // ── 删 working set symlink ──────────────────────────────────
+
+  const symlinkPath = join(WORKING_SET, alias);
+  if (existsSync(symlinkPath)) {
+    rmSync(symlinkPath, { recursive: true, force: true });
+    console.log(`  🗑️  Removed symlink: ${symlinkPath}`);
+  } else {
+    console.log(`  ⚠️  Symlink not found: ${symlinkPath}`);
+  }
+
+  console.log(`\n💡 Cold pool untouched. Run 'bunx @lythos/skill-deck prune' to GC unreferenced repos.`);
+}

package/src/schema.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 // ── 单个已链接 Skill ────────────────────────────────────────
 export const LinkedSkillSchema = z.object({
   name: z.string(),
+  alias: z.string(),
   deck_niche: z.string(),
   type: z.enum(["innate", "tool", "combo", "transient"]),
   source: z.string(),
@@ -49,6 +50,15 @@ export const SkillDeckLockSchema = z.object({
   constraints: ConstraintReportSchema,
 });
 
+// ── Skill entry (alias-as-key dict body) ──────────────────────
+export const SkillEntrySchema = z.object({
+  path: z.string().min(1),
+  role: z.string().optional(),
+  why_in_deck: z.string().optional(),
+}).passthrough();
+
+export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+
 export type LinkedSkill = z.infer<typeof LinkedSkillSchema>;
 export type ConstraintReport = z.infer<typeof ConstraintReportSchema>;
 export type SkillDeckLock = z.infer<typeof SkillDeckLockSchema>;

package/src/update.ts

@@ -1,154 +1,13 @@
 #!/usr/bin/env bun
 /**
- * deck-update.ts — Update declared skills from their upstream sources
+ * deck-update.ts — Deprecated alias for refresh
  *
- * 读取 skill-deck.toml → 遍历声明的 skill → 对 git 来源执行 pull。
- * 职责：让冷池跟上上游版本。
- * 不做：下载新 skill（那是 add 的职责）、修改 deck.toml、同步 working set。
+ * Kept for backward compatibility. Will be removed in v1.0.0.
  */
 
-import { parse as parseToml } from "@iarna/toml";
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { execSync } from "node:child_process";
-import { resolve, dirname, join, relative } from "node:path";
-import { findDeckToml, expandHome, findSource } from "./link.js";
+import { refreshDeck } from "./refresh.js";
 
-interface UpdateResult {
-  name: string;
-  path: string;
-  status: "updated" | "up-to-date" | "skipped" | "failed" | "not-git";
-  message?: string;
+export function updateDeck(cliDeckPath?: string, cliWorkdir?: string, target?: string): void {
+  console.warn("⚠️  `deck update` is deprecated. Use `deck refresh` instead. (Removed in v1.0.0)");
+  refreshDeck(cliDeckPath, cliWorkdir, target);
 }
-
-function isGitRepo(dir: string): boolean {
-  return existsSync(join(dir, ".git"));
-}
-
-function gitPull(dir: string): { status: "updated" | "up-to-date" | "failed"; message: string } {
-  try {
-    const output = execSync("git pull", {
-      cwd: dir,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 30000,
-    }).trim();
-
-    if (output.includes("Already up to date") || output.includes("Already up-to-date")) {
-      return { status: "up-to-date", message: output };
-    }
-    return { status: "updated", message: output };
-  } catch (err: any) {
-    const stderr = err.stderr?.toString() || err.message || "";
-    return { status: "failed", message: stderr.trim() };
-  }
-}
-
-export function updateDeck(cliDeckPath?: string, cliWorkdir?: string): 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 in ${process.cwd()}`);
-    console.error(`\nCreate one or specify a path: bunx @lythos/skill-deck link --deck /path/to/deck.toml`);
-    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 COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
-
-  // ── 收集声明 ────────────────────────────────────────────────
-
-  const declared: { name: string; type: string }[] = [];
-
-  for (const section of ["innate", "tool", "combo"] as const) {
-    for (const name of (deck[section]?.skills || [])) {
-      if (!name || typeof name !== "string") continue;
-      declared.push({ name, type: section });
-    }
-  }
-
-  if (declared.length === 0) {
-    console.log("📭 No skills declared in deck. Nothing to update.");
-    process.exit(0);
-  }
-
-  // ── 执行更新 ────────────────────────────────────────────────
-
-  const results: UpdateResult[] = [];
-  let updated = 0;
-  let upToDate = 0;
-  let skipped = 0;
-  let failed = 0;
-
-  for (const { name, type } of declared) {
-    const result = findSource(name, COLD_POOL, PROJECT_DIR);
-
-    if (result.error || !result.path) {
-      results.push({ name, path: "", status: "failed", message: result.error || "Skill not found" });
-      failed++;
-      continue;
-    }
-
-    const path = result.path;
-
-    // localhost skills are user-managed; skip
-    const relativePath = relative(COLD_POOL, path);
-    if (relativePath.startsWith("localhost")) {
-      results.push({ name, path: relativePath, status: "skipped", message: "localhost skill — user-managed" });
-      skipped++;
-      continue;
-    }
-
-    if (!isGitRepo(path)) {
-      results.push({ name, path: relativePath, status: "not-git", message: "Not a git repository" });
-      skipped++;
-      continue;
-    }
-
-    const pullResult = gitPull(path);
-    results.push({ name, path: relativePath, status: pullResult.status, message: pullResult.message });
-
-    if (pullResult.status === "updated") updated++;
-    else if (pullResult.status === "up-to-date") upToDate++;
-    else failed++;
-  }
-
-  // ── 报告 ────────────────────────────────────────────────────
-
-  console.log(`\n📦 Skill Update Report — ${declared.length} skill(s) checked`);
-  console.log(`   Updated: ${updated} | Up-to-date: ${upToDate} | Skipped: ${skipped} | Failed: ${failed}`);
-  console.log();
-
-  for (const r of results) {
-    const icon =
-      r.status === "updated" ? "🔄" :
-      r.status === "up-to-date" ? "✅" :
-      r.status === "skipped" ? "⏭️" :
-      r.status === "not-git" ? "📁" :
-      "❌";
-    console.log(`${icon} ${r.name}`);
-    if (r.message && r.status !== "up-to-date") {
-      const lines = r.message.split("\n").filter(l => l.trim());
-      for (const line of lines.slice(0, 3)) {
-        console.log(`   ${line.trim()}`);
-      }
-      if (lines.length > 3) {
-        console.log(`   ... (${lines.length - 3} more lines)`);
-      }
-    }
-  }
-
-  if (updated > 0) {
-    console.log(`\n💡 Run 'bunx @lythos/skill-deck link' to sync updated skills to working set.`);
-  }
-
-  if (failed > 0) {
-    process.exit(1);
-  }
-}
-