@lythos/skill-deck 0.9.22 → 0.9.24

package/README.md

@@ -9,7 +9,7 @@
 This package exposes a **CLI**. Invoke via:
 
 ```bash
-bunx @lythos/skill-deck@0.9.22 <command> [options]
+bunx @lythos/skill-deck@0.9.24 <command> [options]
 ```
 
 No installation required. `bunx` auto-downloads the package.
@@ -55,14 +55,14 @@ 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.22 link` |
-| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.22 validate` |
-| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.22 add owner/repo` |
-| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.22 refresh` |
-| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.22 refresh tdd` |
-| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.22 remove tdd` |
-| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.22 prune` |
-| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.22 link --deck ./my-deck.toml --workdir /path/to/project` |
+| Sync working set with `skill-deck.toml` | `bunx @lythos/skill-deck@0.9.24 link` |
+| Validate `skill-deck.toml` before committing | `bunx @lythos/skill-deck@0.9.24 validate` |
+| Download a skill to cold pool and add to deck | `bunx @lythos/skill-deck@0.9.24 add owner/repo` |
+| Pull latest versions of declared skills | `bunx @lythos/skill-deck@0.9.24 refresh` |
+| Refresh a single skill by alias | `bunx @lythos/skill-deck@0.9.24 refresh tdd` |
+| Remove a skill from deck and working set | `bunx @lythos/skill-deck@0.9.24 remove tdd` |
+| GC unreferenced repos from cold pool | `bunx @lythos/skill-deck@0.9.24 prune` |
+| Use a custom deck file or working dir | `bunx @lythos/skill-deck@0.9.24 link --deck ./my-deck.toml --workdir /path/to/project` |
 
 ### Commands
 
@@ -119,7 +119,7 @@ path = "github.com/lythos-labs/lythoskill/skills/lythoskill-deck"
 EOF
 
 # 2. Link — creates symlinks in .claude/skills/
-bunx @lythos/skill-deck@0.9.22 link
+bunx @lythos/skill-deck@0.9.24 link
 ```
 
 ### Key Concepts
@@ -148,7 +148,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.22 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.24 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lythos/skill-deck",
-  "version": "0.9.22",
+  "version": "0.9.24",
   "description": "Declarative skill deck governance — cold pool, working set, deny-by-default",
   "keywords": [
     "ai-agent",
@@ -26,6 +26,7 @@
   ],
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "@lythos/cold-pool": "workspace:*",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },

package/src/add.test.ts

@@ -10,6 +10,7 @@ import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import * as childProcess from 'node:child_process'
+import { findSkillDir } from './add.ts'
 
 // Control homedir() return value for tests that need default cold_pool under tmpdir
 let mockHomeDir = '/tmp'
@@ -193,3 +194,65 @@ describe('addSkill', () => {
     }
   })
 })
+
+describe('findSkillDir', () => {
+  function makeRepo(): string {
+    const dir = mkdtempSync(join(tmpdir(), 'deck-findskill-'))
+    cleanup.push(dir)
+    return dir
+  }
+
+  function placeSkill(repo: string, relPath: string): string {
+    const skillDir = join(repo, relPath)
+    mkdirSync(skillDir, { recursive: true })
+    writeFileSync(join(skillDir, 'SKILL.md'), '---\nname: fixture\n---\n')
+    return skillDir
+  }
+
+  it('returns repoPath for standalone skill (SKILL.md at repo root)', () => {
+    const repo = makeRepo()
+    writeFileSync(join(repo, 'SKILL.md'), '---\nname: standalone\n---\n')
+    expect(findSkillDir(repo, null)).toBe(repo)
+  })
+
+  it('returns skills/ subdir when single skill exists there', () => {
+    const repo = makeRepo()
+    const expected = placeSkill(repo, 'skills/my-skill')
+    expect(findSkillDir(repo, null)).toBe(expected)
+  })
+
+  it('returns flat root dir when single skill exists at repo root', () => {
+    const repo = makeRepo()
+    const expected = placeSkill(repo, 'my-skill')
+    expect(findSkillDir(repo, null)).toBe(expected)
+  })
+
+  it('returns null when multiple flat skills exist at repo root (ambiguous)', () => {
+    const repo = makeRepo()
+    placeSkill(repo, 'skill-a')
+    placeSkill(repo, 'skill-b')
+    expect(findSkillDir(repo, null)).toBeNull()
+  })
+
+  it('finds skill in skills/ subdir when skill name is provided', () => {
+    const repo = makeRepo()
+    const expected = placeSkill(repo, 'skills/my-skill')
+    expect(findSkillDir(repo, 'my-skill')).toBe(expected)
+  })
+
+  it('finds skill at repo root when skill name is provided (flat)', () => {
+    const repo = makeRepo()
+    const expected = placeSkill(repo, 'my-skill')
+    expect(findSkillDir(repo, 'my-skill')).toBe(expected)
+  })
+
+  it('returns null when skill name provided but not found anywhere', () => {
+    const repo = makeRepo()
+    expect(findSkillDir(repo, 'nonexistent')).toBeNull()
+  })
+
+  it('returns null when no SKILL.md exists anywhere in repo', () => {
+    const repo = makeRepo()
+    expect(findSkillDir(repo, null)).toBeNull()
+  })
+})

package/src/add.ts

@@ -3,53 +3,32 @@
  * deck-add.ts — Skill acquisition command
  *
  * Downloads a skill to the cold pool, updates skill-deck.toml, and links.
- * Single backend: git clone. For feed-based discovery with decision tracking,
- * use curator add instead.
+ * Single backend: git clone (delegated to @lythos/cold-pool's executeFetchPlan).
+ * For feed-based discovery with decision tracking, use curator add instead.
  */
 
-import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync, readdirSync } from 'node:fs'
-import { mkdtempSync } from 'node:fs'
-import { tmpdir, homedir } from 'node:os'
-import { join, basename, dirname, resolve } from 'node:path'
-import { execFileSync } from 'node:child_process'
+import {
+  existsSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  readFileSync,
+  readdirSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, basename, resolve } from 'node:path'
 import { parse as parseToml, stringify as stringifyToml } from '@iarna/toml'
+import {
+  ColdPool,
+  buildFetchPlan,
+  executeFetchPlan,
+  parseLocator,
+  formatLocator,
+  type Locator,
+} from '@lythos/cold-pool'
 import { findDeckToml, expandHome } from './link.js'
-import { parseDeck } from './parse-deck.js'
 
-
-interface ParsedLocator {
-  host: string
-  owner: string
-  repo: string
-  skill: string | null
-  raw: string
-}
-
-function parseLocator(input: string): ParsedLocator | null {
-  // Format: host.tld/owner/repo/skill  or  host.tld/owner/repo
-  //         owner/repo/skill           or  owner/repo  (shorthand for github.com)
-  const parts = input.split('/').filter(Boolean)
-  if (parts.length < 2) return null
-
-  const hasHost = parts[0].includes('.')
-
-  if (hasHost) {
-    if (parts.length < 3) return null
-    const host = parts[0]
-    const owner = parts[1]
-    const repo = parts[2]
-    const skill = parts.length > 3 ? parts.slice(3).join('/') : null
-    return { host, owner, repo, skill, raw: input }
-  }
-
-  const host = 'github.com'
-  const owner = parts[0]
-  const repo = parts[1]
-  const skill = parts.length > 2 ? parts.slice(2).join('/') : null
-  return { host, owner, repo, skill, raw: input }
-}
-
-function findSkillDir(repoPath: string, skill: string | null): string | null {
+export function findSkillDir(repoPath: string, skill: string | null): string | null {
   if (skill) {
     const inSkills = join(repoPath, 'skills', skill)
     if (existsSync(join(inSkills, 'SKILL.md'))) return inSkills
@@ -67,6 +46,15 @@ function findSkillDir(repoPath: string, skill: string | null): string | null {
       if (existsSync(join(candidate, 'SKILL.md'))) return candidate
     }
   }
+  // Flat structure: scan repo root for directories containing SKILL.md
+  try {
+    const rootEntries = readdirSync(repoPath, { withFileTypes: true })
+    const rootSkillDirs = rootEntries
+      .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+      .map(e => join(repoPath, e.name))
+      .filter(p => existsSync(join(p, 'SKILL.md')))
+    if (rootSkillDirs.length === 1) return rootSkillDirs[0]
+  } catch {}
   return null
 }
 
@@ -75,7 +63,34 @@ function resolvePath(p: string): string {
   return resolve(p)
 }
 
-export async function addSkill(locator: string, options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean }) {
+function resolveColdPoolPath(deckPath: string, workdir: string): string {
+  if (existsSync(deckPath)) {
+    try {
+      const deckRaw = readFileSync(deckPath, 'utf-8')
+      const deck = parseToml(deckRaw) as { deck?: { cold_pool?: string } }
+      return expandHome(deck.deck?.cold_pool || '~/.agents/skill-repos', workdir)
+    } catch { /* fall through to default */ }
+  }
+  return join(homedir(), '.agents', 'skill-repos')
+}
+
+function fqOf(loc: Locator): string {
+  return formatLocator(loc)
+}
+
+function exitInvalidLocator(locator: string): never {
+  console.error(`❌ Invalid locator: ${locator}`)
+  console.error(`   Expected FQ form (per ADR-20260502012643244):`)
+  console.error(`     host.tld/owner/repo[/skill]   — remote skill`)
+  console.error(`     localhost/<name>              — local-only skill`)
+  console.error(`   Bare names and shorthand 'owner/repo' are rejected.`)
+  process.exit(1)
+}
+
+export async function addSkill(
+  locator: string,
+  options: { deck?: string; workdir?: string; alias?: string; type?: string; dryRun?: boolean },
+) {
   const dryRun = options.dryRun || false
   const workdir = options.workdir ? resolvePath(options.workdir) : process.cwd()
   const deckPath = options.deck
@@ -83,44 +98,46 @@ export async function addSkill(locator: string, options: { deck?: string; workdi
     : findDeckToml(workdir) || join(workdir, 'skill-deck.toml')
 
   const parsed = parseLocator(locator)
-  if (!parsed) {
-    console.error(`❌ Invalid locator: ${locator}`)
-    console.error(`   Expected: github.com/owner/repo[/skill] or owner/repo[/skill]`)
+  if (!parsed) exitInvalidLocator(locator)
+
+  if (parsed.isLocalhost) {
+    console.error(`❌ deck add does not support localhost locators (no remote to clone).`)
+    console.error(`   For local skills, place SKILL.md in your cold pool manually then run "deck link".`)
     process.exit(1)
   }
 
-  let coldPool = join(homedir(), '.agents', 'skill-repos')
-  if (existsSync(deckPath)) {
-    try {
-      const deckRaw = readFileSync(deckPath, 'utf-8')
-      const deck = parseToml(deckRaw) as any
-      coldPool = expandHome(deck.deck?.cold_pool || '~/.agents/skill-repos', workdir)
-    } catch { /* use default */ }
-  }
+  const coldPoolPath = resolveColdPoolPath(deckPath, workdir)
+  const pool = new ColdPool(coldPoolPath)
+  const fetchPlan = buildFetchPlan(pool, parsed)
+  const fqPath = fqOf(parsed)
+  const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo!
+  const alias = options.alias || skillName
+  const skillType = (options.type || 'tool').toLowerCase()
 
-  const targetDir = join(coldPool, parsed.host, parsed.owner, parsed.repo)
+  if (!['innate', 'tool', 'combo'].includes(skillType)) {
+    console.error(`❌ Invalid type: ${skillType}. Must be innate, tool, or combo.`)
+    process.exit(1)
+  }
 
   if (dryRun) {
-    const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    const alias = options.alias || skillName
-    const skillType = (options.type || 'tool').toLowerCase()
-    const fqPath = parsed.skill
-      ? `${parsed.host}/${parsed.owner}/${parsed.repo}/${parsed.skill}`
-      : `${parsed.host}/${parsed.owner}/${parsed.repo}`
-
     console.log(`🔎 Dry-run: deck add ${locator}`)
-    console.log(`   Cold pool:  ${coldPool}`)
+    console.log(`   Cold pool:  ${coldPoolPath}`)
     console.log(`   Deck:       ${deckPath}`)
     console.log()
-    console.log(`📂 Repo status: ${existsSync(join(targetDir, '.git')) ? 'already cloned' : existsSync(targetDir) ? 'dir exists (partial clone?)' : 'not in cold pool'}`)
-    if (!existsSync(join(targetDir, '.git'))) {
-      console.log(`📦 Would clone: https://${parsed.host}/${parsed.owner}/${parsed.repo}.git --depth 1`)
+    const repoStatus = existsSync(join(fetchPlan.targetDir, '.git'))
+      ? 'already cloned'
+      : existsSync(fetchPlan.targetDir)
+        ? 'dir exists (partial clone?)'
+        : 'not in cold pool'
+    console.log(`📂 Repo status: ${repoStatus}`)
+    if (!existsSync(join(fetchPlan.targetDir, '.git'))) {
+      console.log(`📦 Would clone: ${fetchPlan.cloneUrl} --depth 1`)
     }
     if (parsed.skill) {
-      const skillMd = join(targetDir, parsed.skill, 'SKILL.md')
-      if (existsSync(targetDir) && existsSync(skillMd)) {
+      const skillMd = join(fetchPlan.targetDir, parsed.skill, 'SKILL.md')
+      if (existsSync(fetchPlan.targetDir) && existsSync(skillMd)) {
         console.log(`📄 Skill path:  valid — ${skillMd}`)
-      } else if (existsSync(targetDir)) {
+      } else if (existsSync(fetchPlan.targetDir)) {
         console.log(`⚠️  Skill path:  NOT FOUND — check repo layout`)
       }
     }
@@ -131,125 +148,100 @@ export async function addSkill(locator: string, options: { deck?: string; workdi
     return
   }
 
-  if (existsSync(targetDir)) {
-    console.error(`❌ Already exists in cold pool: ${targetDir}`)
-    console.error(`   To update: rm -rf ${targetDir} and re-run`)
+  if (fetchPlan.alreadyExists) {
+    console.error(`❌ Already exists in cold pool: ${fetchPlan.targetDir}`)
+    console.error(`   To update: rm -rf ${fetchPlan.targetDir} and re-run`)
     process.exit(1)
   }
 
-  if (!existsSync(coldPool)) {
-    console.log(`📁 Creating cold pool: ${coldPool}`)
-    mkdirSync(coldPool, { recursive: true })
+  if (!existsSync(coldPoolPath)) {
+    console.log(`📁 Creating cold pool: ${coldPoolPath}`)
+    mkdirSync(coldPoolPath, { recursive: true })
   }
+  // git clone needs the parent of the target dir (e.g. host/owner/) to exist
+  mkdirSync(dirname(fetchPlan.targetDir), { recursive: true })
 
-  const tmpDir = mkdtempSync(join(tmpdir(), 'lythoskill-deck-add-'))
-  const tmpRepo = join(tmpDir, 'repo')
+  const fetchResult = executeFetchPlan(fetchPlan, {
+    log: (msg) => console.log(msg),
+  })
 
-  try {
-    const gitUrl = `https://${parsed.host}/${parsed.owner}/${parsed.repo}.git`
-    console.log(`📦 Cloning: ${gitUrl}`)
-    execFileSync('git', ['clone', '--depth', '1', gitUrl, tmpRepo], { stdio: 'inherit' })
-    let skillSourceDir = tmpRepo
-
-    if (!existsSync(skillSourceDir)) {
-      console.error(`❌ Download failed: expected output not found at ${skillSourceDir}`)
-      process.exit(1)
-    }
+  if (fetchResult.status === 'failed') {
+    rmSync(fetchPlan.targetDir, { recursive: true, force: true })
+    console.error(`❌ Failed to fetch: ${fetchResult.message ?? 'unknown error'}`)
+    process.exit(1)
+  }
 
-    mkdirSync(dirname(targetDir), { recursive: true })
-    renameSync(skillSourceDir, targetDir)
+  const skillDir = findSkillDir(fetchPlan.targetDir, parsed.skill)
+  if (!skillDir) {
+    console.error(`❌ No SKILL.md found in downloaded repo`)
+    console.error(`   Checked: ${fetchPlan.targetDir}`)
+    process.exit(1)
+  }
 
-    const skillDir = findSkillDir(targetDir, parsed.skill)
-    if (!skillDir) {
-      console.error(`❌ No SKILL.md found in downloaded repo`)
-      console.error(`   Checked: ${targetDir}`)
-      process.exit(1)
-    }
+  console.log(`✅ Skill ready: ${skillName} (alias: ${alias})`)
+  console.log(`   Location: ${skillDir}`)
 
-    const skillName = parsed.skill ? basename(parsed.skill) : parsed.repo
-    const alias = options.alias || skillName
-    const skillType = (options.type || 'tool').toLowerCase()
+  // ── 写 deck.toml ────────────────────────────────────────────
 
-    if (!['innate', 'tool', 'combo'].includes(skillType)) {
-      console.error(`❌ Invalid type: ${skillType}. Must be innate, tool, or combo.`)
+  if (existsSync(deckPath)) {
+    const deckRaw = readFileSync(deckPath, 'utf-8')
+    const deck = parseToml(deckRaw) as Record<string, any>
+
+    // 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)
     }
 
-    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
-
-      // 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)) {
+    // 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 deck[skillType].skills) {
+        for (const name of sectionData.skills) {
           const a = name.split('/').pop() || name
           dict[a] = { path: name }
         }
-        deck[skillType].skills = dict
+        deck[section].skills = dict
+        console.log(`📝 Auto-migrated [${section}] from string-array to dict format`)
       }
-
-      deck[skillType].skills[alias] = { path: fqPath }
-      writeFileSync(deckPath, stringifyToml(deck))
-      console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
-    } else {
-      const minimal: any = { deck: { max_cards: 10 } }
-      minimal[skillType] = { skills: { [alias]: { path: fqPath } } }
-      writeFileSync(deckPath, stringifyToml(minimal))
-      console.log(`📝 Created ${deckPath} with "${alias}"`)
     }
 
-    console.log('🔗 Running deck link...')
-    const { linkDeck } = await import('./link.js')
-    linkDeck(deckPath, workdir)
+    // 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
+    }
 
-  } catch (err) {
-    console.error(`❌ Failed to add skill: ${err}`)
-    process.exit(1)
-  } finally {
-    rmSync(tmpDir, { recursive: true, force: true })
+    deck[skillType].skills[alias] = { path: fqPath }
+    writeFileSync(deckPath, stringifyToml(deck))
+    console.log(`📝 Added "${alias}" to [${skillType}.skills] in ${deckPath}`)
+  } else {
+    const minimal: Record<string, any> = { deck: { max_cards: 10 } }
+    minimal[skillType] = { skills: { [alias]: { path: fqPath } } }
+    writeFileSync(deckPath, stringifyToml(minimal))
+    console.log(`📝 Created ${deckPath} with "${alias}"`)
   }
+
+  console.log('🔗 Running deck link...')
+  const { linkDeck } = await import('./link.js')
+  linkDeck(deckPath, workdir)
 }

package/src/cli.ts

@@ -12,18 +12,23 @@ 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 aliasFlagIdx = args.indexOf('--alias')
-const typeFlagIdx = args.indexOf('--type')
+// Argument helpers — accept both `--flag value` and `--flag=value` forms.
+function flagValue(name: string): string | undefined {
+  const direct = args.find((a) => a.startsWith(name + '='))
+  if (direct) return direct.slice(name.length + 1)
+  const idx = args.indexOf(name)
+  return idx >= 0 ? args[idx + 1] : undefined
+}
 
-const deckPath = deckFlagIdx >= 0 ? args[deckFlagIdx + 1] : undefined
-const workdir = workdirFlagIdx >= 0 ? args[workdirFlagIdx + 1] : undefined
-const alias = aliasFlagIdx >= 0 ? args[aliasFlagIdx + 1] : undefined
-const type = typeFlagIdx >= 0 ? args[typeFlagIdx + 1] : undefined
+const deckPath = flagValue('--deck')
+const workdir = flagValue('--workdir')
+const alias = flagValue('--alias')
+const type = flagValue('--type')
+const format = flagValue('--format')
 const noBackup = args.includes('--no-backup')
 const yes = args.includes('--yes')
 const dryRun = args.includes('--dry-run')
+const remote = args.includes('--remote')
 
 const HELP_CONFIG = {
   binName: 'lythoskill-deck',
@@ -46,6 +51,8 @@ const HELP_CONFIG = {
     { flag: '--type <type>', description: 'Target section: innate | tool | combo (default: tool)' },
     { flag: '--dry-run', description: 'Show plan without executing (add, prune)' },
     { flag: '--yes', description: 'Skip interactive confirmation (for prune)' },
+    { flag: '--remote', description: 'For validate: probe each FQ locator against api.github.com' },
+    { flag: '--format <text|json>', description: 'For validate: output format (default: text)' },
   ],
 }
 
@@ -77,7 +84,10 @@ switch (command) {
     break
   }
   case 'validate':
-    validateDeck(deckPath, workdir)
+    await validateDeck(deckPath, workdir, {
+      remote,
+      format: format === 'json' ? 'json' : 'text',
+    })
     break
   case 'remove': {
     const removeTarget = args[1] && !args[1].startsWith('-') ? args[1] : undefined

package/src/link.test.ts

@@ -67,42 +67,52 @@ describe('expandHome', () => {
 })
 
 describe('findSource', () => {
-  it('resolves fully-qualified host.tld/owner/repo/skill via cold-pool skills/ subdir', () => {
+  it('resolves FQ host.tld/owner/repo/skill via cold-pool direct path', () => {
     const coldPool = makeTmp()
     const projectDir = makeTmp()
     const expected = placeSkill(coldPool, 'github.com/lythos-labs/lythoskill/skills/lythoskill-deck')
-    const result = findSource('github.com/lythos-labs/lythoskill/lythoskill-deck', coldPool, projectDir)
+    const result = findSource('github.com/lythos-labs/lythoskill/skills/lythoskill-deck', coldPool, projectDir)
     expect(result.path).toBe(expected)
   })
 
-  it('resolves a direct cold-pool hit when name matches a top-level dir with SKILL.md', () => {
+  it('resolves FQ standalone host.tld/owner/repo (skill = null) via repo-root SKILL.md', () => {
     const coldPool = makeTmp()
     const projectDir = makeTmp()
-    const expected = placeSkill(coldPool, 'my-skill')
-    const result = findSource('my-skill', coldPool, projectDir)
+    const expected = placeSkill(coldPool, 'github.com/owner/standalone')
+    const result = findSource('github.com/owner/standalone', coldPool, projectDir)
     expect(result.path).toBe(expected)
   })
 
-  it('resolves a monorepo layout (repo/skill → coldPool/repo/skills/skill)', () => {
+  it('resolves localhost/<owner>/<repo> via uniform <host>/<owner>/<repo> layout', () => {
     const coldPool = makeTmp()
     const projectDir = makeTmp()
-    const expected = placeSkill(coldPool, 'mono-repo/skills/inner-skill')
-    const result = findSource('mono-repo/inner-skill', coldPool, projectDir)
+    const expected = placeSkill(coldPool, 'localhost/me/my-local-skill')
+    const result = findSource('localhost/me/my-local-skill', coldPool, projectDir)
     expect(result.path).toBe(expected)
   })
 
-  it('falls back to projectDir/skills/<name> for project-local skills', () => {
+  it('rejects bare names with FQ-only error (per ADR-20260502012643244)', () => {
     const coldPool = makeTmp()
     const projectDir = makeTmp()
-    const expected = placeSkill(projectDir, 'skills/local-skill')
-    const result = findSource('local-skill', coldPool, projectDir)
-    expect(result.path).toBe(expected)
+    placeSkill(coldPool, 'my-skill') // even if a dir exists
+    const result = findSource('my-skill', coldPool, projectDir)
+    expect(result.path).toBeNull()
+    expect(result.error).toBeDefined()
+    expect(result.error).toContain('not FQ')
+  })
+
+  it('rejects shorthand owner/repo (no host) with FQ-only error', () => {
+    const coldPool = makeTmp()
+    const projectDir = makeTmp()
+    const result = findSource('owner/repo', coldPool, projectDir)
+    expect(result.path).toBeNull()
+    expect(result.error).toBeDefined()
   })
 
-  it('returns {path: null} when no strategy resolves the name', () => {
+  it('returns {path: null} when FQ locator is well-formed but path absent on disk', () => {
     const coldPool = makeTmp()
     const projectDir = makeTmp()
-    const result = findSource('nonexistent-skill', coldPool, projectDir)
+    const result = findSource('github.com/owner/missing-repo/skill', coldPool, projectDir)
     expect(result.path).toBeNull()
     expect(result.error).toBeUndefined()
   })

package/src/link.ts

@@ -17,6 +17,7 @@ import {
 import { execFileSync } from "node:child_process";
 import { resolve, dirname, join, basename, relative } from "node:path";
 import { homedir } from "node:os";
+import { ColdPool, parseLocator } from "@lythos/cold-pool";
 import {
   SkillDeckLockSchema,
   type SkillDeckLock, type LinkedSkill, type ConstraintReport,
@@ -58,81 +59,43 @@ export interface FindSourceResult {
   error?: string;
 }
 
-export function findSource(name: string, coldPool: string, projectDir: string): FindSourceResult {
-  // 0. Fully-qualified path: host.tld/owner/repo/skill
-  //    → cold_pool/host.tld/owner/repo/skills/skill
-  //    Also handles host.tld/owner/repo (standalone skill without skills/ subdir)
-  const fqMatch = name.match(/^[a-z0-9-]+\.[a-z0-9-]+\//);
-  if (fqMatch) {
-    const parts = name.split("/");
-    const host = parts[0];      // github.com
-    const owner = parts[1];     // lythos-labs
-    const repo = parts[2];      // lythoskill
-    const skill = parts.slice(3).join("/"); // lythoskill-deck
-
-    if (skill) {
-      const fqPath = join(coldPool, host, owner, repo, "skills", skill);
-      if (existsSync(join(fqPath, "SKILL.md"))) return { path: fqPath };
-    }
-    // fallback: standalone skill at repo root
-    const directPath = join(coldPool, host, owner, repo);
-    if (existsSync(join(directPath, "SKILL.md"))) return { path: directPath };
-  }
-
-  // 0.5 localhost skills: localhost/skill → cold_pool/<skill>
-  if (name.startsWith('localhost/')) {
-    const skill = name.slice('localhost/'.length);
-    if (skill) {
-      const localPath = join(coldPool, skill);
-      if (existsSync(join(localPath, "SKILL.md"))) return { path: localPath };
-    }
-    return { path: null };
+/**
+ * Resolve a deck-declared locator to its physical SKILL.md directory in
+ * the cold pool. Per ADR-20260502012643244, locators are FQ-only — bare
+ * names and shorthand `owner/repo` are rejected. Internally delegates to
+ * `@lythos/cold-pool` for parsing and pool path computation.
+ *
+ * `projectDir` is currently unused (legacy parameter from the deprecated
+ * project-local fallback strategy). Kept for caller compatibility; will
+ * be removed in 0.10.x cleanup.
+ */
+export function findSource(name: string, coldPool: string, _projectDir: string): FindSourceResult {
+  const locator = parseLocator(name);
+  if (!locator) {
+    return {
+      path: null,
+      error: `Locator "${name}" is not FQ. Expected: host.tld/owner/repo[/skill] or localhost/<name>. Bare names rejected per ADR-20260502012643244.`,
+    };
   }
 
-  // 1. 直接路径
-  const direct = resolve(coldPool, name);
-  if (existsSync(join(direct, "SKILL.md"))) return { path: direct };
+  const pool = new ColdPool(coldPool);
+  const baseDir = pool.resolveDir(locator);
 
-  // 2. Monorepo: repo/skill → cold_pool/repo/skills/skill
-  if (name.includes("/")) {
-    const [repo, ...rest] = name.split("/");
-    const mono = join(coldPool, repo, "skills", rest.join("/"));
-    if (existsSync(join(mono, "SKILL.md"))) return { path: mono };
+  // localhost: baseDir is the skill dir itself
+  if (locator.isLocalhost) {
+    if (existsSync(join(baseDir, "SKILL.md"))) return { path: baseDir };
+    return { path: null };
   }
 
-  // 3. 项目本地: <project>/skills/<name>（build 输出目录，优先级高于扁平扫描）
-  const local = resolve(projectDir, "skills", name);
-  if (existsSync(join(local, "SKILL.md"))) return { path: local };
-
-  // 4. 扁平扫描: cold_pool/<any-repo>/<name> 或 <any-repo>/skills/<name>
-  //    跳过隐藏目录（agent working set、git、配置等）和 node_modules，
-  //    避免把 .claude/skills/ 里的 symlink 误判为有效 cold-pool 源
-  const matches: string[] = [];
-  try {
-    for (const entry of readdirSync(coldPool, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      if (entry.name.startsWith('.')) continue;
-      if (entry.name === 'node_modules') continue;
-      const base = join(coldPool, entry.name);
-      for (const sub of [join(base, name), join(base, "skills", name)]) {
-        if (existsSync(join(sub, "SKILL.md"))) {
-          matches.push(sub);
-        }
-      }
-    }
-  } catch {}
-
-  if (matches.length === 1) {
-    return { path: matches[0] };
-  }
-  if (matches.length > 1) {
-    const candidates = matches.map(m => relative(coldPool, m)).join(', ');
-    return {
-      path: null,
-      error: `Ambiguous skill name "${name}": found ${matches.length} matches (${candidates}). Use fully-qualified name (e.g., github.com/owner/repo/${name})`,
-    };
+  // Remote with skill subpath: SKILL.md sits inside the subpath
+  if (locator.skill) {
+    const skillDir = join(baseDir, locator.skill);
+    if (existsSync(join(skillDir, "SKILL.md"))) return { path: skillDir };
+    return { path: null };
   }
 
+  // Standalone repo: SKILL.md is at repo root
+  if (existsSync(join(baseDir, "SKILL.md"))) return { path: baseDir };
   return { path: null };
 }
 

package/src/prune-plan.ts

@@ -44,6 +44,19 @@ export function resolvePruneConfig(opts?: {
 
 // ── Cold pool scanner (pure: reads, no delete) ─────────────────────────────
 
+/**
+ * Scan cold pool for skill repos.
+ *
+ * Layout convention (per ADR-20260502012643344):
+ *   - `<coldPool>/localhost/<name>/SKILL.md`   — local skill
+ *   - `<coldPool>/<host>/<owner>/<repo>/...`   — remote skill
+ *
+ * Legacy drift detection: a top-level dir `<coldPool>/<x>/SKILL.md` (with
+ * SKILL.md directly, not under `localhost/`) is non-canonical state from
+ * older agents that bypassed FQ-only enforcement. We surface it here so
+ * prune's heredoc can list it as cleanup candidate; future writes should
+ * never produce this shape.
+ */
 export function scanColdPool(coldPool: string): string[] {
   const repos: string[] = []
   if (!existsSync(coldPool)) return repos
@@ -53,13 +66,22 @@ export function scanColdPool(coldPool: string): string[] {
       if (!host.isDirectory() || host.name.startsWith('.')) continue
       const hostPath = join(coldPool, host.name)
 
-      // Flat skill: cold-pool/skill-name/SKILL.md (localhost style)
+      // Localhost layout: <coldPool>/localhost/<name>/SKILL.md
+      if (host.name === 'localhost') {
+        for (const entry of readdirSync(hostPath, { withFileTypes: true })) {
+          if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+          repos.push(join(hostPath, entry.name))
+        }
+        continue
+      }
+
+      // Legacy drift: top-level dir with SKILL.md (not canonical)
       if (existsSync(join(hostPath, 'SKILL.md'))) {
         repos.push(hostPath)
         continue
       }
 
-      // Nested: cold-pool/github.com/owner/repo/
+      // Nested: <coldPool>/<host>/<owner>/<repo>/
       for (const owner of readdirSync(hostPath, { withFileTypes: true })) {
         if (!owner.isDirectory() || owner.name.startsWith('.')) continue
         const ownerPath = join(hostPath, owner.name)

package/src/prune.test.ts

@@ -63,7 +63,7 @@ describe('pruneDeck', () => {
     const repoB = placeRepo(coldPool, 'github.com', 'owner', 'repo-b')
     placeSkillInRepo(repoB, 'skill-b')
 
-    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a/skill-a"\n`
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a/skills/skill-a"\n`
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 
@@ -84,7 +84,7 @@ describe('pruneDeck', () => {
     const repoA = placeRepo(coldPool, 'github.com', 'owner', 'repo-a')
     placeSkillInRepo(repoA, 'skill-a')
 
-    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a/skill-a"\n`
+    const deckContent = `[deck]\nmax_cards = 10\nworking_set = ".claude/skills"\ncold_pool = "${coldPoolRel}"\n\n[tool.skills.skill-a]\npath = "github.com/owner/repo-a/skills/skill-a"\n`
     const deckPath = join(projectDir, 'skill-deck.toml')
     writeFileSync(deckPath, deckContent)
 

package/src/refresh-plan.ts

@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs'
 import { resolve, dirname, relative } from 'node:path'
 import { realpathSync } from 'node:fs'
 import { execSync } from 'node:child_process'
+import { parseLocator } from '@lythos/cold-pool'
 import { findDeckToml, expandHome, findSource } from './link'
 import { parseDeck, type ParsedSkillEntry } from './parse-deck'
 
@@ -120,6 +121,25 @@ export function buildRefreshPlan(
   const targets: RefreshTarget[] = []
 
   for (const entry of declared) {
+    // Localhost shortcut: parse the locator and short-circuit before
+    // hitting fs. localhost layout per ADR-20260507021957847 is a
+    // top-level dir under coldPool (no `localhost/` directory prefix),
+    // so path-based detectGitRoot can't distinguish it from a regular
+    // standalone skill. The locator string is the authoritative signal.
+    const locator = parseLocator(entry.path)
+    if (locator?.isLocalhost) {
+      const source = findSource(entry.path, coldPool, workdir)
+      const sourcePath = source.path ?? ''
+      targets.push({
+        alias: entry.alias,
+        path: entry.path,
+        sourcePath,
+        sourceRel: sourcePath ? relative(coldPool, sourcePath) : '',
+        type: sourcePath ? 'localhost' : 'missing',
+      })
+      continue
+    }
+
     const source = findSource(entry.path, coldPool, workdir)
 
     if (source.error || !source.path) {

package/src/refresh.ts

@@ -8,8 +8,8 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { execSync } from "node:child_process";
 import { resolve } from "node:path";
+import { gitPull } from "@lythos/cold-pool";
 import { findDeckToml, linkDeck } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
 import { buildRefreshPlan, detectGitRoot, executeRefreshPlan } from "./refresh-plan.js";
@@ -20,32 +20,6 @@ export function findGitRoot(dir: string, coldPool: string): string | null {
   return result.gitRoot ?? null
 }
 
-interface RefreshResult {
-  name: string;
-  path: string;
-  status: "updated" | "up-to-date" | "skipped" | "failed" | "not-git";
-  message?: string;
-}
-
-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 deckPath = cliDeckPath || process.argv.find((_, i, a) => a[i - 1] === "--deck");
   const workdir = cliWorkdir

package/src/validate.ts

@@ -3,24 +3,63 @@
  * deck-validate.ts — Skill Deck configuration validator
  *
  * 读取 skill-deck.toml → 校验 schema、引用有效性、约束合规性。
- * 不做：创建 symlink、修改文件系统。
+ * Optional remote check (T8 of EPIC-20260507020846020):
+ *   `--remote` → for each FQ locator, call cold-pool's buildValidationPlan
+ *   + executeValidationPlan against api.github.com to verify repo and
+ *   skill path exist BEFORE clone. Output structured ValidationReport.
+ * `--format=json` emits machine-readable output for agents.
  */
 
 import { parse as parseToml } from "@iarna/toml";
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import {
+  buildValidationPlan,
+  executeValidationPlan,
+  type ValidationReport,
+} from "@lythos/cold-pool";
 import { findDeckToml, expandHome, findSource } from "./link.js";
 import { parseDeck } from "./parse-deck.js";
 
-export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
+export interface ValidateOptions {
+  remote?: boolean;
+  format?: 'text' | 'json';
+}
+
+export interface DeckValidationReport {
+  status: 'valid' | 'invalid';
+  deckPath: string;
+  errors: string[];
+  warnings: string[];
+  entries: Array<{
+    locator: string;
+    type: string;
+    alias: string;
+    localStatus: 'found' | 'missing' | 'parse-error';
+    remote?: ValidationReport;
+  }>;
+  budget: { declared: number; max_cards: number; within_budget: boolean };
+}
+
+export async function buildDeckValidation(
+  cliDeckPath?: string,
+  cliWorkdir?: string,
+  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");
 
   if (!existsSync(DECK_PATH)) {
-    console.error(`❌ skill-deck.toml not found: ${DECK_PATH}`);
-    process.exit(1);
+    return {
+      status: 'invalid',
+      deckPath: DECK_PATH,
+      errors: [`skill-deck.toml not found: ${DECK_PATH}`],
+      warnings: [],
+      entries: [],
+      budget: { declared: 0, max_cards: 0, within_budget: true },
+    };
   }
 
   const deckRaw = readFileSync(DECK_PATH, "utf-8");
@@ -28,15 +67,19 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
   try {
     deck = parseToml(deckRaw);
   } catch (err: any) {
-    console.error(`❌ TOML parse error: ${err.message}`);
-    process.exit(1);
+    return {
+      status: 'invalid',
+      deckPath: DECK_PATH,
+      errors: [`TOML parse error: ${err.message}`],
+      warnings: [],
+      entries: [],
+      budget: { declared: 0, max_cards: 0, within_budget: true },
+    };
   }
 
   const errors: string[] = [];
   const warnings: string[] = [];
 
-  // ── Validate deck section ──────────────────────────────────
-
   if (!deck.deck || typeof deck.deck !== "object") {
     errors.push("[deck] section is required");
   } else {
@@ -51,8 +94,6 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
   const COLD_POOL = expandHome(deck.deck?.cold_pool || "~/.agents/skill-repos", PROJECT_DIR);
   const MAX_CARDS = Number(deck.deck?.max_cards || 10);
 
-  // ── Validate skill declarations ────────────────────────────
-
   const { entries: parsedEntries, deprecated: isDeprecated, errors: parseErrors } = parseDeck(deckRaw);
   if (isDeprecated) {
     warnings.push("string-array skill entries are deprecated. Run `deck migrate-schema` to upgrade.");
@@ -61,6 +102,7 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
 
   const declaredNames = new Set<string>();
   let declaredCount = 0;
+  const entryReports: DeckValidationReport['entries'] = [];
 
   for (const entry of parsedEntries) {
     declaredCount++;
@@ -70,14 +112,37 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
     declaredNames.add(entry.path);
 
     const result = findSource(entry.path, COLD_POOL, PROJECT_DIR);
+    let localStatus: 'found' | 'missing' | 'parse-error';
     if (result.error) {
       errors.push(result.error);
+      localStatus = 'parse-error';
     } else if (!result.path) {
-      errors.push(`Skill not found: ${entry.path} (${entry.type})`);
+      // Don't add to errors yet — remote check may have suggestions.
+      // Local missing is only an error if remote also fails or is skipped.
+      localStatus = 'missing';
+    } else {
+      localStatus = 'found';
+    }
+
+    let remote: ValidationReport | undefined;
+    if (options.remote) {
+      const plan = buildValidationPlan(entry.path);
+      remote = await executeValidationPlan(plan);
+      if (remote.status === 'invalid') {
+        errors.push(`Remote check invalid: ${entry.path} (${remote.phase})`);
+      }
+    } else if (localStatus === 'missing') {
+      errors.push(`Skill not found in cold pool: ${entry.path} (${entry.type})`);
     }
-  }
 
-  // ── Validate transient section ─────────────────────────────
+    entryReports.push({
+      locator: entry.path,
+      type: entry.type,
+      alias: entry.alias,
+      localStatus,
+      remote,
+    });
+  }
 
   const transientCount = Object.keys(deck.transient || {}).length;
   if (deck.transient) {
@@ -104,24 +169,59 @@ export function validateDeck(cliDeckPath?: string, cliWorkdir?: string): void {
     }
   }
 
-  // ── Budget check ───────────────────────────────────────────
-
   const total = declaredCount + transientCount;
-  if (total > MAX_CARDS) {
+  const within_budget = total <= MAX_CARDS;
+  if (!within_budget) {
     errors.push(`Budget exceeded: declared ${total} skill(s), max_cards = ${MAX_CARDS}`);
   }
 
-  // ── Report ─────────────────────────────────────────────────
+  return {
+    status: errors.length > 0 ? 'invalid' : 'valid',
+    deckPath: DECK_PATH,
+    errors,
+    warnings,
+    entries: entryReports,
+    budget: { declared: total, max_cards: MAX_CARDS, within_budget },
+  };
+}
 
-  if (warnings.length > 0) {
-    for (const w of warnings) console.warn(`⚠️  ${w}`);
+function renderText(report: DeckValidationReport): void {
+  for (const w of report.warnings) console.warn(`⚠️  ${w}`);
+
+  for (const entry of report.entries) {
+    if (entry.remote) {
+      const status = entry.remote.status
+      const icon = status === 'valid' ? '✅' : status === 'ambiguous' ? '⚠️ ' : '❌'
+      console.log(`${icon} ${entry.locator} (${entry.type}) — ${status} (${entry.remote.phase})`)
+      for (const fix of entry.remote.suggestedFixes) {
+        const tag = fix.action === 'update-locator' && fix.newLocator ? `→ ${fix.newLocator}` : fix.action
+        console.log(`     ${tag} (confidence: ${fix.confidence.toFixed(2)}) — ${fix.message}`)
+      }
+    }
   }
 
-  if (errors.length > 0) {
-    for (const e of errors) console.error(`❌ ${e}`);
-    console.error(`\n❌ Validation failed: ${errors.length} error(s)`);
-    process.exit(1);
+  if (report.errors.length > 0) {
+    for (const e of report.errors) console.error(`❌ ${e}`);
+    console.error(`\n❌ Validation failed: ${report.errors.length} error(s)`);
+  } else {
+    console.log(`✅ Validation passed: ${report.budget.declared} skill(s), max_cards = ${report.budget.max_cards}`);
   }
+}
 
-  console.log(`✅ Validation passed: ${total} skill(s), max_cards = ${MAX_CARDS}`);
+export async function validateDeck(
+  cliDeckPath?: string,
+  cliWorkdir?: string,
+  options: ValidateOptions = {},
+): Promise<void> {
+  const report = await buildDeckValidation(cliDeckPath, cliWorkdir, options);
+
+  if (options.format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    renderText(report);
+  }
+
+  if (report.status === 'invalid') {
+    process.exit(1);
+  }
 }