@morya-ui/setup 0.3.7 → 0.4.0

package/README.md

@@ -38,6 +38,12 @@ npx @morya-ui/setup ai --skills=all
 # Only Cursor + VS Code MCP targets (still writes .mcp.json)
 npx @morya-ui/setup ai --editors=cursor,vscode
 
+# Narrow skill agents (default: cursor, github-copilot, zed, claude-code, windsurf)
+npx @morya-ui/setup ai --agents=github-copilot,zed
+
+# Install companion skills to every skills-CLI agent (many dirs)
+npx @morya-ui/setup ai --agents=all
+
 # Refresh AI template / MCP without touching dependencies
 npx @morya-ui/setup ai --skip-install
 ```
@@ -50,8 +56,9 @@ npx @morya-ui/setup ai --skip-install
 | `--pm pnpm\|yarn\|npm` | Package manager (default: detect from lockfile, else `pnpm`) |
 | `--skills <list>` | Comma-separated skill ids, or `all` (skips the prompt) |
 | `--editors <list>` | MCP targets: `cursor`, `vscode`, `zed`, or `all` (default: all three). Always also writes root `.mcp.json` |
+| `--agents <list>` | Skill agents: `cursor`, `github-copilot`, `zed`, `claude-code`, `windsurf` (default), or `all` (`-a '*'`) |
 | `--yes` / `-y` | Use default skills without prompting |
-| `--force` | Overwrite existing template files and the `morya-ui` MCP entry |
+| `--force` | Overwrite existing template files, MCP `morya-ui` entry, and skill-dir links |
 | `--dry-run` | Print actions without writing or installing |
 | `--skip-install` | Do not install / upgrade `morya-ui` or `@morya-ui/*` |
 | `--skip-template` | Do not copy AI skill / rules / docs (also skips companion skill install) |
@@ -75,7 +82,8 @@ Catalog: [`catalog/skills.json`](./catalog/skills.json).
 
 - Dependencies: always install / upgrade `morya-ui@latest` and any existing `@morya-ui/*` (e.g. `@morya-ui/nuxt`) to `@latest` unless `--skip-install`.
 - Template files and `.cursor/rules/*`: **skip** if the destination exists (unless `--force`).
-- Companion skills (`skills-cli`): always reinstall/update to **latest** when selected.
+- Companion skills (`skills-cli`): always reinstall/update to **latest** when selected (default agents: the five listed under `--agents`).
+- Mirrored skill dirs (`.claude/skills`, `.windsurf/skills`, `.github/skills`): **skip** if the destination exists (unless `--force`).
 - MCP configs: merge other servers / settings; skip existing `morya-ui` entry unless `--force`. New or forced entries use `npx -y @morya-ui/mcp@latest`.
 - `package.json` `check:colors`: add only if missing (unless `--force`).
 - Styles: inject only when an entry file is found and the import is not already present.
@@ -90,10 +98,20 @@ From the package `template/` (synced from repo `design-kit/`):
 - `.cursor/rules/` — Cursor-specific always-apply rules
 - `scripts/check-raw-colors.mjs`
 
-Via `npx skills add …` when optional companions are selected:
+Via `npx skills add …` when optional companions are selected (default agents: Cursor, GitHub Copilot, Zed, Claude Code, Windsurf):
 
 - `.agents/skills/frontend-design/`, `fixing-accessibility/`, and/or `impeccable/` (latest upstream)
 
+Setup then mirrors selected skills from `.agents/skills/` into agent-specific dirs that do not share that path:
+
+| Agent | Extra project dir |
+| --- | --- |
+| Claude Code | `.claude/skills/` |
+| Windsurf | `.windsurf/skills/` |
+| GitHub Copilot | `.github/skills/` (in addition to `.agents/skills`) |
+
+Cursor / Zed / Copilot already read `.agents/skills` directly.
+
 ### MCP (multi-editor)
 
 | Editor | Path | JSON key |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@morya-ui/setup",
   "type": "module",
-  "version": "0.3.7",
+  "version": "0.4.0",
   "description": "One-shot setup for morya-ui: install the library, multi-editor MCP, Agent skills, and design config.",
   "license": "MIT",
   "homepage": "https://github.com/morya-space/morya-ui/tree/main/packages/setup#readme",

package/src/__tests__/skills.test.mjs

@@ -0,0 +1,174 @@
+import assert from 'node:assert/strict'
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, it } from 'node:test'
+import {
+  DEFAULT_SKILL_AGENTS,
+  extraSkillDirsForAgents,
+  installSkillsCli,
+  parseAgentsFlag,
+  skillAgentCliFlags,
+  syncProjectSkillsToAgents,
+} from '../skills.mjs'
+
+/** @type {string[]} */
+const temps = []
+
+function makeCwd() {
+  const cwd = mkdtempSync(join(tmpdir(), 'morya-setup-skills-'))
+  temps.push(cwd)
+  return cwd
+}
+
+afterEach(() => {
+  while (temps.length) {
+    rmSync(temps.pop(), { recursive: true, force: true })
+  }
+})
+
+function seedSkill(cwd, name) {
+  const dir = join(cwd, '.agents', 'skills', name)
+  mkdirSync(dir, { recursive: true })
+  writeFileSync(join(dir, 'SKILL.md'), `---\nname: ${name}\ndescription: test\n---\n`, 'utf8')
+  return dir
+}
+
+describe('parseAgentsFlag', () => {
+  it('defaults to the five curated agents', () => {
+    assert.deepEqual(parseAgentsFlag(), [...DEFAULT_SKILL_AGENTS])
+    assert.deepEqual(parseAgentsFlag(''), [...DEFAULT_SKILL_AGENTS])
+  })
+
+  it('returns * for all', () => {
+    assert.equal(parseAgentsFlag('all'), '*')
+    assert.equal(parseAgentsFlag('*'), '*')
+  })
+
+  it('parses and dedupes a subset', () => {
+    assert.deepEqual(parseAgentsFlag('zed,cursor,zed'), ['zed', 'cursor'])
+  })
+
+  it('rejects unknown agents', () => {
+    assert.throws(() => parseAgentsFlag('cursor,not-a-real-agent'), /Unknown skill agent/)
+  })
+})
+
+describe('skillAgentCliFlags', () => {
+  it('emits one -a per default agent', () => {
+    const flags = skillAgentCliFlags(DEFAULT_SKILL_AGENTS)
+    assert.match(flags, /-a cursor/)
+    assert.match(flags, /-a github-copilot/)
+    assert.match(flags, /-a zed/)
+    assert.match(flags, /-a claude-code/)
+    assert.match(flags, /-a windsurf/)
+  })
+
+  it('emits wildcard for all', () => {
+    assert.equal(skillAgentCliFlags('*'), "-a '*'")
+  })
+})
+
+describe('extraSkillDirsForAgents', () => {
+  it('mirrors claude / windsurf / github dirs for defaults', () => {
+    assert.deepEqual(extraSkillDirsForAgents(DEFAULT_SKILL_AGENTS), [
+      '.github/skills',
+      '.claude/skills',
+      '.windsurf/skills',
+    ])
+  })
+
+  it('skips extras for agents that only use .agents/skills', () => {
+    assert.deepEqual(extraSkillDirsForAgents(['cursor', 'zed']), [])
+  })
+})
+
+describe('installSkillsCli', () => {
+  it('dry-run builds multi-agent commands', () => {
+    const cwd = makeCwd()
+    const skills = [
+      {
+        id: 'frontend-design',
+        name: 'Frontend Design',
+        description: 'x',
+        install: 'skills-cli',
+        source: 'anthropics/skills',
+        skill: 'frontend-design',
+        path: '.agents/skills/frontend-design',
+      },
+    ]
+    const result = installSkillsCli(cwd, ['frontend-design'], skills, {
+      dryRun: true,
+      agents: ['cursor', 'zed', 'github-copilot'],
+    })
+    assert.equal(result.dryRun, true)
+    assert.equal(result.commands.length, 1)
+    assert.match(result.commands[0], /skills add anthropics\/skills/)
+    assert.match(result.commands[0], /-s frontend-design/)
+    assert.match(result.commands[0], /-a cursor/)
+    assert.match(result.commands[0], /-a zed/)
+    assert.match(result.commands[0], /-a github-copilot/)
+    assert.doesNotMatch(result.commands[0], /-a cursor -y$/)
+  })
+})
+
+describe('syncProjectSkillsToAgents', () => {
+  it('links into claude / windsurf / github skill dirs', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+
+    const { results } = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: DEFAULT_SKILL_AGENTS,
+    })
+
+    const byDir = Object.fromEntries(results.map((r) => [r.dir, r]))
+    assert.ok(byDir['.claude/skills'])
+    assert.ok(byDir['.windsurf/skills'])
+    assert.ok(byDir['.github/skills'])
+    assert.ok(['linked', 'copied'].includes(byDir['.claude/skills'].action))
+
+    assert.ok(readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+    assert.ok(readFileSync(join(cwd, '.windsurf', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+    assert.ok(readFileSync(join(cwd, '.github', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'))
+  })
+
+  it('skips existing links unless force', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+    mkdirSync(join(cwd, '.claude', 'skills', 'morya-ui-pages'), { recursive: true })
+    writeFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'old\n', 'utf8')
+
+    const skipped = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+    })
+    assert.equal(skipped.results[0].action, 'skipped')
+    assert.equal(
+      readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'),
+      'old\n',
+    )
+
+    const forced = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+      force: true,
+    })
+    assert.ok(['linked', 'copied'].includes(forced.results[0].action))
+    assert.match(
+      readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md'), 'utf8'),
+      /morya-ui-pages/,
+    )
+  })
+
+  it('dry-run does not create dirs', () => {
+    const cwd = makeCwd()
+    seedSkill(cwd, 'morya-ui-pages')
+    const { results } = syncProjectSkillsToAgents(cwd, ['morya-ui-pages'], {
+      agents: ['claude-code'],
+      dryRun: true,
+    })
+    assert.equal(results[0].action, 'linked')
+    assert.throws(
+      () => readFileSync(join(cwd, '.claude', 'skills', 'morya-ui-pages', 'SKILL.md')),
+      /ENOENT/,
+    )
+  })
+})

package/src/cli.mjs

@@ -5,11 +5,17 @@ import { installMoryaUi } from './install.mjs'
 import { DEFAULT_EDITORS, mergeMcpConfig, parseEditorsFlag } from './mcp.mjs'
 import { ensureCheckColorsScript } from './package-json.mjs'
 import {
+  DEFAULT_SKILL_AGENTS,
   buildAiInclude,
   installSkillsCli,
+  listCanonicalSkillFolders,
   loadSkillsCatalog,
+  parseAgentsFlag,
   parseSkillsFlag,
+  resolveSkillAgents,
   resolveSkillSelection,
+  skillFolderNames,
+  syncProjectSkillsToAgents,
 } from './skills.mjs'
 import { ensureStylesImport } from './styles.mjs'
 
@@ -54,6 +60,7 @@ Commands:
 Default command:
   - install / upgrade morya-ui@latest and any existing @morya-ui/* to @latest
   - copy DESIGN.md, AGENTS.md, selected Agent skills, Cursor rules
+  - install companion skills + sync into multi-agent skill dirs
   - merge MCP configs for @morya-ui/mcp@latest (Cursor, VS Code, Zed, + .mcp.json)
   - inject import 'morya-ui/styles.css' into the app entry when found
   - add check:colors script when missing
@@ -63,8 +70,9 @@ Options:
   --pm <name>       Package manager: pnpm | yarn | npm (auto-detect by lockfile)
   --skills <list>   Comma-separated skill ids, or "all" (skips interactive prompt)
   --editors <list>  MCP targets: cursor,vscode,zed (default: all); always also writes .mcp.json
+  --agents <list>   Skill agents: cursor,github-copilot,zed,claude-code,windsurf (default), or all
   --yes             Use default skills without prompting (CI / non-interactive)
-  --force           Overwrite existing template files and MCP server entry
+  --force           Overwrite existing template files, MCP entry, and skill dir links
   --dry-run         Print actions without writing or installing
   --skip-install    Skip dependency install / upgrade
   --skip-template   Skip copying AI template files
@@ -88,6 +96,7 @@ export function parseArgs(argv) {
     pm: undefined,
     skills: undefined,
     editors: undefined,
+    agents: undefined,
     yes: false,
     force: false,
     dryRun: false,
@@ -165,6 +174,16 @@ export function parseArgs(argv) {
       options.editors = arg.slice('--editors='.length)
       continue
     }
+    if (arg === '--agents') {
+      const value = argv[++i]
+      if (!value) throw new Error('--agents requires a comma-separated list or "all"')
+      options.agents = value
+      continue
+    }
+    if (arg.startsWith('--agents=')) {
+      options.agents = arg.slice('--agents='.length)
+      continue
+    }
     throw new Error(`Unknown argument: ${arg}`)
   }
 
@@ -198,10 +217,13 @@ export async function runSetup(options) {
     pm,
     skills: skillsFlag,
     editors: editorsFlag,
+    agents: agentsFlag,
     yes,
   } = options
 
   const editors = editorsFlag != null ? parseEditorsFlag(editorsFlag) : [...DEFAULT_EDITORS]
+  const agents = agentsFlag != null ? parseAgentsFlag(agentsFlag) : [...DEFAULT_SKILL_AGENTS]
+  const agentsLabel = agents === '*' ? 'all (*)' : resolveSkillAgents(agents).join(',')
 
   console.log(`@morya-ui/setup [${mode}] → ${cwd}${dryRun ? ' (dry-run)' : ''}`)
   console.log('')
@@ -221,6 +243,7 @@ export async function runSetup(options) {
     }
     aiInclude = buildAiInclude(selectedSkills, catalog.skills)
     console.log(`Skills: ${selectedSkills.join(', ')}`)
+    console.log(`Skill agents: ${agentsLabel}`)
     console.log('')
   }
 
@@ -236,8 +259,21 @@ export async function runSetup(options) {
       })
 
   const remoteSkills = skipTemplate || !selectedSkills.length
-    ? { installed: [], commands: [], skipped: true }
-    : installSkillsCli(cwd, selectedSkills, catalog.skills, { dryRun })
+    ? { installed: [], commands: [], agents, skipped: true }
+    : installSkillsCli(cwd, selectedSkills, catalog.skills, { dryRun, agents })
+
+  const skillNamesForSync = needsTemplate
+    ? [
+        ...new Set([
+          ...skillFolderNames(selectedSkills, catalog.skills),
+          ...(dryRun ? [] : listCanonicalSkillFolders(cwd)),
+        ]),
+      ]
+    : []
+
+  const skillSync = skipTemplate || !skillNamesForSync.length
+    ? { results: [], skipped: true }
+    : syncProjectSkillsToAgents(cwd, skillNamesForSync, { force, dryRun, agents })
 
   const mcp = skipMcp
     ? { skipped: true, results: [] }
@@ -278,10 +314,27 @@ export async function runSetup(options) {
   if (remoteSkills.skipped) {
     // no companions selected or template step skipped
   } else if (remoteSkills.dryRun) {
-    console.log(`Skills CLI: dry-run — would install ${remoteSkills.installed.join(', ')}`)
+    console.log(`Skills CLI: dry-run — would install ${remoteSkills.installed.join(', ')} → ${agentsLabel}`)
     for (const command of remoteSkills.commands) console.log(`  $ ${command}`)
   } else {
-    console.log(`Skills CLI: installed ${remoteSkills.installed.join(', ')} (latest)`)
+    console.log(`Skills CLI: installed ${remoteSkills.installed.join(', ')} (latest) → ${agentsLabel}`)
+  }
+
+  if (skillSync.skipped) {
+    // nothing to mirror
+  } else {
+    const linked = skillSync.results.filter((r) => r.action === 'linked' || r.action === 'copied')
+    const skippedLinks = skillSync.results.filter((r) => r.action === 'skipped')
+    console.log(
+      `Skill dirs: ${linked.length} linked/copied, ${skippedLinks.length} skipped` +
+        (skillSync.dryRun ? ' (dry-run)' : ''),
+    )
+    for (const entry of skillSync.results.slice(0, 8)) {
+      console.log(`  ${entry.action} ${entry.dir}/${entry.skill}`)
+    }
+    if (skillSync.results.length > 8) {
+      console.log(`  … and ${skillSync.results.length - 8} more`)
+    }
   }
 
   if (mcp.skipped) {
@@ -326,5 +379,17 @@ export async function runSetup(options) {
     console.log('  4. Optional: pnpm check:colors')
   }
 
-  return { mode, install, template, remoteSkills, mcp, styles, scripts, skills: selectedSkills, editors }
+  return {
+    mode,
+    install,
+    template,
+    remoteSkills,
+    skillSync,
+    mcp,
+    styles,
+    scripts,
+    skills: selectedSkills,
+    editors,
+    agents,
+  }
 }

package/src/skills.mjs

@@ -1,12 +1,53 @@
 import { execSync } from 'node:child_process'
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  rmSync,
+  symlinkSync,
+} from 'node:fs'
+import { dirname, join, relative } from 'node:path'
 import { createInterface } from 'node:readline'
-import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { readJson } from './fs-utils.mjs'
+import { ensureDir, readJson } from './fs-utils.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const CATALOG_PATH = join(__dirname, '..', 'catalog', 'skills.json')
 
+/** Canonical project skills root shared by Cursor / Zed / GitHub Copilot. */
+export const CANONICAL_SKILLS_DIR = '.agents/skills'
+
+/**
+ * Default skills CLI agents for consumer projects.
+ * VS Code Copilot uses `github-copilot` (reads `.agents/skills`).
+ */
+export const DEFAULT_SKILL_AGENTS = [
+  'cursor',
+  'github-copilot',
+  'zed',
+  'claude-code',
+  'windsurf',
+]
+
+/**
+ * Project-relative skills directories for agents that do **not** share
+ * `.agents/skills`. Agents that already use the canonical dir are omitted.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const EXTRA_AGENT_SKILL_DIRS = {
+  'claude-code': ['.claude/skills'],
+  windsurf: ['.windsurf/skills'],
+  // Copilot also discovers `.github/skills`; keep a link for clients that prefer it.
+  'github-copilot': ['.github/skills'],
+}
+
+export const KNOWN_SKILL_AGENTS = [
+  ...new Set([...DEFAULT_SKILL_AGENTS, ...Object.keys(EXTRA_AGENT_SKILL_DIRS)]),
+]
+
 /**
  * @typedef {{
  *   id: string
@@ -49,6 +90,72 @@ export function defaultSkillIds(skills) {
   return skills.filter((s) => s.required || s.default).map((s) => s.id)
 }
 
+/**
+ * @param {string | undefined} raw
+ * @returns {string[] | '*'}
+ */
+export function parseAgentsFlag(raw) {
+  if (raw == null || raw.trim() === '') return [...DEFAULT_SKILL_AGENTS]
+  if (raw.trim() === 'all' || raw.trim() === '*') return '*'
+
+  const ids = raw
+    .split(',')
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean)
+
+  if (!ids.length) return [...DEFAULT_SKILL_AGENTS]
+  if (ids.includes('*') || ids.includes('all')) return '*'
+
+  const unknown = ids.filter((id) => !KNOWN_SKILL_AGENTS.includes(id))
+  if (unknown.length) {
+    throw new Error(
+      `Unknown skill agent id(s): ${unknown.join(', ')}. Available: ${KNOWN_SKILL_AGENTS.join(', ')}, or all`,
+    )
+  }
+
+  return [...new Set(ids)]
+}
+
+/**
+ * Resolve concrete agent names for CLI / sync (expands `*`).
+ * @param {string[] | '*'} agents
+ * @returns {string[]}
+ */
+export function resolveSkillAgents(agents) {
+  if (agents === '*') return [...DEFAULT_SKILL_AGENTS]
+  if (!Array.isArray(agents) || !agents.length) return [...DEFAULT_SKILL_AGENTS]
+  return [...new Set(agents)]
+}
+
+/**
+ * Build `-a` flags for the skills CLI.
+ * @param {string[] | '*'} agents
+ */
+export function skillAgentCliFlags(agents) {
+  if (agents === '*') return "-a '*'"
+  const list = resolveSkillAgents(agents)
+  return list.map((name) => `-a ${name}`).join(' ')
+}
+
+/**
+ * Extra project skill dirs to mirror for the selected agents.
+ * @param {string[] | '*'} agents
+ * @returns {string[]}
+ */
+export function extraSkillDirsForAgents(agents) {
+  const list = agents === '*' ? [...DEFAULT_SKILL_AGENTS] : resolveSkillAgents(agents)
+  /** @type {string[]} */
+  const dirs = []
+  for (const agent of list) {
+    const extras = EXTRA_AGENT_SKILL_DIRS[agent]
+    if (!extras) continue
+    for (const dir of extras) {
+      if (!dirs.includes(dir)) dirs.push(dir)
+    }
+  }
+  return dirs
+}
+
 /**
  * @param {string | undefined} raw
  * @param {SkillEntry[]} skills
@@ -111,18 +218,38 @@ export function buildAiInclude(skillIds, skills) {
   ]
 }
 
+/**
+ * Folder names under `.agents/skills` for the selected skill ids.
+ * @param {string[]} skillIds
+ * @param {SkillEntry[]} skills
+ * @returns {string[]}
+ */
+export function skillFolderNames(skillIds, skills) {
+  const byId = new Map(skills.map((s) => [s.id, s]))
+  return skillIds.map((id) => {
+    const entry = byId.get(id)
+    if (!entry) throw new Error(`Unknown skill id: ${id}`)
+    return entry.skill || entry.id
+  })
+}
+
 /**
  * Install selected companion skills via the skills CLI (always latest from source).
  * @param {string} cwd
  * @param {string[]} skillIds
  * @param {SkillEntry[]} skills
- * @param {{ dryRun?: boolean }} [options]
- * @returns {{ installed: string[], commands: string[], dryRun?: boolean, skipped?: boolean }}
+ * @param {{ dryRun?: boolean, agents?: string[] | '*' }} [options]
+ * @returns {{ installed: string[], commands: string[], agents: string[] | '*', dryRun?: boolean, skipped?: boolean }}
  */
-export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {}) {
+export function installSkillsCli(
+  cwd,
+  skillIds,
+  skills,
+  { dryRun = false, agents = DEFAULT_SKILL_AGENTS } = {},
+) {
   const selected = skills.filter((s) => skillIds.includes(s.id) && isSkillsCliSkill(s))
   if (!selected.length) {
-    return { installed: [], commands: [], skipped: true }
+    return { installed: [], commands: [], agents, skipped: true }
   }
 
   for (const entry of selected) {
@@ -140,14 +267,15 @@ export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {})
     bySource.set(entry.source, list)
   }
 
+  const agentFlags = skillAgentCliFlags(agents)
   const commands = []
   for (const [source, names] of bySource) {
     const skillFlags = names.map((name) => `-s ${name}`).join(' ')
-    commands.push(`npx -y skills add ${source} ${skillFlags} -a cursor -y`)
+    commands.push(`npx -y skills add ${source} ${skillFlags} ${agentFlags} -y`)
   }
 
   if (dryRun) {
-    return { installed: selected.map((s) => s.id), commands, dryRun: true }
+    return { installed: selected.map((s) => s.id), commands, agents, dryRun: true }
   }
 
   console.log('Companion skills (latest via skills CLI):')
@@ -156,7 +284,116 @@ export function installSkillsCli(cwd, skillIds, skills, { dryRun = false } = {})
     execSync(command, { cwd, stdio: 'inherit', shell: true })
   }
 
-  return { installed: selected.map((s) => s.id), commands }
+  return { installed: selected.map((s) => s.id), commands, agents }
+}
+
+/**
+ * Link (or copy) canonical `.agents/skills/<name>` into agent-specific dirs.
+ * @param {string} cwd
+ * @param {string[]} skillNames folder names under `.agents/skills`
+ * @param {{ force?: boolean, dryRun?: boolean, agents?: string[] | '*' }} [options]
+ * @returns {{ results: Array<{ skill: string, dir: string, action: string }>, dryRun?: boolean, skipped?: boolean }}
+ */
+export function syncProjectSkillsToAgents(
+  cwd,
+  skillNames,
+  { force = false, dryRun = false, agents = DEFAULT_SKILL_AGENTS } = {},
+) {
+  const names = [...new Set(skillNames.filter(Boolean))]
+  const targetDirs = extraSkillDirsForAgents(agents)
+
+  if (!names.length || !targetDirs.length) {
+    return { results: [], skipped: true, dryRun }
+  }
+
+  /** @type {Array<{ skill: string, dir: string, action: string }>} */
+  const results = []
+
+  for (const dir of targetDirs) {
+    for (const name of names) {
+      const source = join(cwd, CANONICAL_SKILLS_DIR, name)
+      const dest = join(cwd, dir, name)
+
+      if (!existsSync(source)) {
+        results.push({ skill: name, dir, action: 'missing-source' })
+        continue
+      }
+
+      if (existsSync(dest) || isSymlink(dest)) {
+        if (!force) {
+          results.push({ skill: name, dir, action: 'skipped' })
+          continue
+        }
+        if (!dryRun) {
+          rmSync(dest, { recursive: true, force: true })
+        }
+      }
+
+      if (dryRun) {
+        results.push({ skill: name, dir, action: 'linked' })
+        continue
+      }
+
+      ensureDir(join(cwd, dir))
+      const action = linkOrCopySkill(source, dest)
+      results.push({ skill: name, dir, action })
+    }
+  }
+
+  return { results, dryRun }
+}
+
+/**
+ * @param {string} path
+ */
+function isSymlink(path) {
+  try {
+    return lstatSync(path).isSymbolicLink()
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Prefer symlink; fall back to recursive copy (e.g. Windows without privilege).
+ * @param {string} source absolute
+ * @param {string} dest absolute
+ * @returns {'linked' | 'copied'}
+ */
+function linkOrCopySkill(source, dest) {
+  mkdirSync(dirname(dest), { recursive: true })
+  // Windows junctions need an absolute target; POSIX prefers a relative link.
+  const rel = relative(dirname(dest), source) || '.'
+  try {
+    if (process.platform === 'win32') {
+      symlinkSync(source, dest, 'junction')
+    } else {
+      symlinkSync(rel, dest, 'dir')
+    }
+    return 'linked'
+  } catch {
+    try {
+      symlinkSync(rel, dest, 'dir')
+      return 'linked'
+    } catch {
+      cpSync(source, dest, { recursive: true })
+      return 'copied'
+    }
+  }
+}
+
+/**
+ * Discover skill folder names already present under `.agents/skills`.
+ * @param {string} cwd
+ * @returns {string[]}
+ */
+export function listCanonicalSkillFolders(cwd) {
+  const root = join(cwd, CANONICAL_SKILLS_DIR)
+  if (!existsSync(root)) return []
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .filter((entry) => existsSync(join(root, entry.name, 'SKILL.md')))
+    .map((entry) => entry.name)
 }
 
 /**

package/template/.agents/skills/morya-ui-pages/references/component-index.md

@@ -22,7 +22,7 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 
 ## Forms · inputs
 
-`MForm`, `MFormItem`, `MInput`, `MInputPassword`, `MInputNumber`, `MTextarea`, `MInputOtp`, `MInputColor`, `MInputGroup`, `MInputTags`, `MSelect`, `MTreeSelect`, `MCascadeSelect`, `MListbox`, `MSelectButton`, `MDatePicker`, `MAutoComplete`, `MCheckbox` / `MCheckboxGroup`, `MRadio` / `MRadioGroup`, `MSwitch`, `MToggleButton`, `MSlider`, `MRating`, `MKnob`, `MFileUpload`, `MFloatLabel`, `MIconField`, `MLabel`
+`MForm` / `MFormItem` / `MFormList`, `MInput`, `MInputPassword`, `MInputNumber`, `MTextarea`, `MInputOtp`, `MInputColor`, `MInputGroup`, `MInputTags`, `MMentions`, `MSelect`, `MTreeSelect`, `MCascadeSelect`, `MListbox`, `MSelectButton`, `MDatePicker`, `MTimePicker`, `MCalendar`, `MAutoComplete`, `MCheckbox` / `MCheckboxGroup`, `MRadio` / `MRadioGroup`, `MSwitch`, `MToggleButton`, `MSlider`, `MRating`, `MKnob`, `MFileUpload`, `MFloatLabel`, `MIconField`, `MLabel`
 
 ## Layout helpers
 
@@ -30,7 +30,7 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 
 ## Data
 
-`MTable` (`columns` + **`rows`**, not `data`; optional `virtual`, `resizable`/`filterable`, `children`, `span-method`, `tree-config`), `MDataView`, `MTree`, `MPagination`, `MOrderList`, `MPickList`, `MStatus` / `MTag` / `MChip` / `MBadge`, `MAvatar` / `MAvatarGroup`, `MTimeline`, `MMeterGroup`, `MVirtualScroller`
+`MTable` (`columns` + **`rows`**, not `data`; optional `virtual`, `resizable`/`filterable`, `children`, `span-method`, `tree-config`), `MDataView`, `MList` / `MListItem` / `MListItemMeta`, `MTree`, `MPagination`, `MOrderList`, `MPickList`, `MDescriptions`, `MStatistic`, `MStatus` / `MTag` / `MChip` / `MBadge`, `MAvatar` / `MAvatarGroup`, `MTimeline`, `MMeterGroup`, `MVirtualScroller`
 
 ## Feedback
 
@@ -40,6 +40,7 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 | `toast` | `summary` + `detail`, or async / background feel | `feedback-choice` |
 | `<MMessage>` | Optional host for the `message` service. **Not** an inline alert | `feedback-choice` |
 | field `errorMessage` or token `role="alert"` | Persistent form / auth error | `feedback-choice` |
+| `MAlert` | Persistent in-page notice (not a toast) | `feedback-choice` |
 | `MEmpty` | No-data / first-use / filtered empty | `empty-result-choice` |
 | `MResult` | Terminal outcome: success, failure, 403 / 404 / 500 | `empty-result-choice` |
 | `MLoading` / `v-loading` / `loading.service` | **Default** region or fullscreen loading mask | `loading-choice` |
@@ -50,11 +51,11 @@ Full API: docs site `/components` or MCP (`get_component`, `search`, `validate_u
 
 ## Overlays & menus
 
-`MDialog`, `MDrawer`, `MConfirmDialog` / `MConfirmPopup`, `MPopover`, `MTooltip`, `MDropdown` (**actions only**), `MContextMenu`, `MCommandMenu`, `MMenu` / `MMenubar` / `MTieredMenu` / `MMegaMenu`, `MTabs`, `MStepper`
+`MDialog`, `MDrawer`, `MConfirmDialog` / `MConfirmPopup`, `MPopover`, `MTooltip`, `MDropdown` (**actions only**), `MContextMenu`, `MCommandMenu`, `MMenu` / `MMenubar` / `MTieredMenu` / `MMegaMenu`, `MTabs`, `MStepper`, `MTour`, `MAffix`, `MAnchor`
 
 ## Surfaces / media
 
-`MCard`, `MPanel`, `MAccordion`, `MCarousel`, `MGallery`, `MIcon`, `MScrollbar`, `MInplace`, `MScrollTop`, `MTerminal`
+`MCard`, `MPanel`, `MAccordion`, `MCarousel`, `MGallery`, `MImage`, `MIcon`, `MQRCode`, `MScrollbar`, `MInplace`, `MScrollTop`, `MTerminal`, `MTypography` / `MTitle` / `MText` / `MParagraph` / `MLink`, `MWatermark`
 
 ## Scenario → decision
 

package/template/.agents/skills/morya-ui-pages/references/decision-recipes.md

@@ -1308,7 +1308,7 @@ This file is the **offline** mirror for agents without MCP.
 **Recipe · props**
 
 - title + description
-- icon 或 illustration 按需（默认即可）
+- 主区域优先 illustration（no-content / no-result…）
 - 表格内放在 #empty
 
 **Recipe · slots**

package/template/.agents/skills/morya-ui-pages/references/page-layouts.md

@@ -9,7 +9,7 @@ Golden pages are **assembly demos / structure baselines**, not the default clone
 | List | List page | `list-page` (`list-page-dense` / `list-page-rail` craft only) | `layout-app-shell`, `page-header-actions`, **`list-filters-stack`** (dense → `list-filters-dense`), `list-table`, `form-in-dialog`, `confirm-delete` |
 | Form (long / dedicated) | Form page | `form-page` | `page-content-form`, `form-header`, `form-body`, `form-actions` |
 | List create/edit dialog | List create/edit dialog | `form-in-dialog` | **`form-in-dialog`** (preferred) |
-| Detail | Detail page | `detail-page` | `detail-toolbar`, `form-in-dialog` |
+| Detail | Detail page | `detail-page` | `detail-toolbar`, `detail-descriptions`, `form-in-dialog` |
 | Dashboard | Dashboard | `dashboard-page` | `dashboard-kpi-grid`, `dashboard-chart-card`, `dashboard-recent-table` |
 | Login | — (see [surfaces.md](surfaces.md)) | `login-page` | **`auth-split-shell`** |
 | Landing | — (see [surfaces.md](surfaces.md)) | `landing-page` | — |
@@ -74,8 +74,10 @@ Craft: [visual-craft.md](visual-craft.md) § Ops polish.
 
 1. `MLayout fillViewport` → `MLayoutHeader` → `MBreadcrumb`
 2. `MPageContent density="spacious"` → `MPageHeader` (title + short domain description when useful)
-3. KPI row: `MGrid` + `MPageStat` (4 columns or responsive) — `dashboard-kpi-grid`
-4. Main split: `MCard shadow="always"` + `MEmpty` (chart pending) and/or recent `MTable` — `dashboard-chart-card` / `dashboard-recent-table`
+3. Optional `MAlert` for ops tip / degraded dependency (dismissible when appropriate)
+4. KPI row: `MGrid` + **`MPageStat`** (trend + icon) — `dashboard-kpi-grid`
+5. Main split: `MCard shadow="always"` + **`MEmpty illustration`** (chart pending) and/or recent `MTable` / `MList` — `dashboard-chart-card` / `dashboard-recent-table`
+6. Plain numeric callouts inside a card (no trend UI) → `MStatistic`, not a second custom KPI CSS
 
 Craft: spacious density + Ops polish; do not turn the first viewport into a marketing hero.
 
@@ -89,7 +91,7 @@ Craft: spacious density + Ops polish; do not turn the first viewport into a mark
 | Spacing | `MSpace` / `MFlex` for peers; page gap from `MPageContent` | Nested padded divs stacking gaps |
 | Scroll | Full-viewport main lists may use table-body scroll via `fill`; otherwise layout / local `MScrollbar` | Forcing overflow on every content slot; stacked page + table scrollbars without reason |
 | Color | `--m-*` | Page-level hex / rgb |
-| Feedback | One-line → `message`; danger → confirm dialog | Toast for a single short string |
+| Feedback | One-line → `message`; danger → confirm dialog; sticky page tip → `MAlert` | Toast for a single short string |
 | A11y | Labels + icon `aria-label` | Unlabeled icon controls |
 
 Inline style is acceptable for control widths (e.g. filter `width: 14rem`).
@@ -98,9 +100,10 @@ Inline style is acceptable for control widths (e.g. filter `width: 14rem`).
 
 1. Same admin chrome as list (breadcrumb → `MPageContent`)
 2. `MPageHeader` — title, `MStatus` in `#actions`, primary/secondary/danger → `detail-toolbar`
-3. Summary `MPageSection` + property `MCard` (definition grid with `--m-*` only)
-4. Related data: `MCard` + `MTable` / tabs / timeline
-5. Short edit → `form-in-dialog`; long edit → form page / `form-in-drawer`
+3. Summary chips optional (`MTag`) — keep quiet
+4. **Attributes** → `MDescriptions` / `MDescriptionsItem` (bordered when comparing many fields) — `detail-descriptions`
+5. Related activity: prefer `MList` + `MListItemMeta` for narrative feeds; `MTable` when columns matter
+6. Short edit → `form-in-dialog`; long edit → form page / `form-in-drawer`
 
 ## List create/edit dialog — block order
 

package/template/.agents/skills/morya-ui-pages/references/surfaces.md

@@ -9,7 +9,7 @@ Pick a lane, then a surface. Prefer project golden pages for **Ops**; use the re
 | List | Scan, filter, act on many rows | Golden list + [page-layouts.md](page-layouts.md); **create/edit with ≤~8 fields → `MDialog` on the list** |
 | Form | Create / edit one entity as a **dedicated page** | Golden form — only when multi-section, many fields, or user asked for an independent form route |
 | Dashboard | Orient + jump to work | Golden dashboard |
-| Detail | Read-heavy record + secondary actions | `MPageHeader` + sections via `MCard`/`MPageSection`; edit via `MDialog` / `MDrawer` (prefer over a second form route) |
+| Detail | Read-heavy record + secondary actions | `MPageHeader` + **`MDescriptions`** for attributes; related feed via `MList` or `MTable`; edit via `MDialog` / `MDrawer` |
 | Settings | Grouped preferences | Narrow `MPageContent` + stacked `MPageSection` / `MTabs` + `MForm` |
 | Hybrid list | List + drawer/dialog | **Default Ops CRUD pattern**: list golden + `MDialog`/`MDrawer` form |
 
@@ -17,7 +17,7 @@ Pick a lane, then a surface. Prefer project golden pages for **Ops**; use the re
 
 | Surface | Job | Recipe |
 | --- | --- | --- |
-| Login / register | Authenticate with trust | Golden: MCP `get_golden_page` `login-page` — split brand + `MForm` (`MInput`, `MInputPassword`); form-level errors via token `role="alert"` (not Toast). Brand wash: [visual-craft.md](visual-craft.md) § Atmosphere |
+| Login / register | Authenticate with trust | Golden: MCP `get_golden_page` `login-page` — split brand + `MForm`; prefer `MConfigProvider input-variant="filled"`; optional `themeConfig` for brand seed; failures via `role="alert"` / `errorMessage` (not Toast). Brand wash: [visual-craft.md](visual-craft.md) § Shell recipes |
 | Invite / accept | Join org | Same shell; show org name clearly |
 | Forgot / reset | Recover access | Short form + success state with next step |
 | Profile / account | Edit self | Settings-like sections; avatar via `MAvatar` |
@@ -28,8 +28,8 @@ Keep credential forms quiet: one primary CTA, clear labels, no decorative noise
 
 | Surface | Job | Recipe |
 | --- | --- | --- |
-| Empty state | Invite first action | Golden: MCP `get_golden_page` `empty-state` — `MEmpty` + primary/secondary `MButton` in `#extra`; dashed shell + radial wash from visual-craft |
-| Onboarding | Teach the product path | `MStepper` or paced cards; one decision per step; finish → Ops home |
+| Empty state | Invite first action | Golden: MCP `get_golden_page` `empty-state` — `MEmpty` + **`illustration`** (`no-content` / `no-result` / …) + primary/secondary in `#extra` |
+| Onboarding | Teach the product path | `MStepper` or paced cards; optional `MTour` for in-app spotlight; one decision per step; finish → Ops home |
 | Wizard | Multi-step create | `MStepper` + `MForm` per step + sticky actions (`上一步` / `下一步` / `提交`) |
 | Success / result | Confirm completion | `MResult status="success"` / `error` + `#footer` next actions (`查看详情` / `返回列表`); same shell idea as `result-page` |
 
@@ -51,7 +51,7 @@ Use when the brief is landing, pricing, launch, or docs marketing — **not** fo
 
 | Surface | Job | Recipe |
 | --- | --- | --- |
-| Landing | Convert / explain product | Golden: MCP `get_golden_page` `landing-page` — one-job hero; CTAs → `MButton`; chips → `MTag`; FAQ → `MAccordion` |
+| Landing | Convert / explain product | Golden: MCP `get_golden_page` `landing-page` — one-job hero; CTAs → `MButton`; chips → `MTag`; FAQ → `MAccordion`; prefer `MTypography` / `MTitle` / `MParagraph` for hierarchy when available |
 | Pricing | Choose a plan | Clear plan cards (`MCard`) + primary CTA; highlight recommended plan without clutter |
 | Feature showcase | Prove capability | Alternating media/copy; live `M*` demo only if lightweight |
 | Docs marketing chrome | Frame documentation | Header + nav using `M*` where suitable; content area stays readable |

package/template/.agents/skills/morya-ui-pages/references/visual-craft.md

@@ -48,13 +48,32 @@ If the plan looks like any-SaaS (purple wash, cream serif, neon glow) and the us
 3. **Status** → `MStatus`; `MTag` for categories/filters only.
 4. **Row actions** — text / outlined / small.
 5. **Filter rhythm** — search ~`14rem`, selects ~`10–12rem`.
-6. **Empty** — `MEmpty` with next action.
+6. **Empty** — `MEmpty` with domain next-step copy + **one** primary in `#extra`. Prefer `illustration` (`no-content` / `no-result` / `no-message` / `network-error` / …) over a generic icon when the empty is a main region.
 7. **No extra cards** around filters/table “for polish”.
 8. **Domain copy**.
 9. **Density** — follow user cues (`compact` / spacious); don’t invent a second scale.
 10. **Quiet chrome** — no marketing heroes / glow unless the user asked.
+11. **Page alerts** — persistent in-page notices → `MAlert` (not Toast, not `<MMessage>` as markup).
+12. **Detail fields** — attribute grids → `MDescriptions` / `MDescriptionsItem` (not hand-rolled `<dl>`).
+13. **Plain metrics** — numbers without trend chrome → `MStatistic` inside a section/card; KPI strips with trend → keep `MPageStat`.
+14. **Activity / feed rows** — same-shape items without dense columns → `MList` + `MListItem` / `MListItemMeta`; tabular compare → `MTable`.
 
-Ops beauty = alignment + semantics + restraint, **not** gradients.
+Ops beauty = alignment + semantics + restraint + the right `M*` for the job, **not** gradients.
+
+## Component craft map (post-library upgrades)
+
+| Need | Prefer | Avoid |
+| --- | --- | --- |
+| Admin KPI with trend | `MPageStat` (`dashboard-kpi-grid`) | Custom stat CSS |
+| Inline / detail number | `MStatistic` | Fake big numbers with raw `<p>` |
+| Detail attribute grid | `MDescriptions` (`detail-descriptions`) | Hand-written `<dl>` / nested tables |
+| Lightweight feed | `MList` + Meta | Forcing a full `MTable` for 3–5 narrative rows |
+| Empty main region | `MEmpty` + `illustration` | “暂无数据” + bare icon only |
+| In-page notice | `MAlert` | Toast for sticky page tips |
+| Auth / form inputs | `MConfigProvider input-variant="filled"` (or filled controls) | Mixing outlined/filled without reason |
+| Brand seed | `themeConfig` / project theme CSS | Page-level hex |
+| Express headings | `MTypography` / `MTitle` / `MParagraph` where it helps hierarchy | Second font kit |
+| First-run teach | `MTour` after empty/onboarding | Modal essay walls |
 
 ## Anti-default looks
 

package/template/AGENTS.md

@@ -30,4 +30,4 @@ Editor-neutral always-on guidance for AI agents (Cursor, VS Code, Zed, Copilot,
 | Component pick | `recommend_component`, `get_component`, `get_example` |
 | Offline recipes | skill `references/` under `morya-ui-pages` |
 
-Setup writes editor MCP configs (Cursor / VS Code / Zed) and root `.mcp.json`. Reload MCP after `npx @morya-ui/setup ai`.
+Canonical skills live under `.agents/skills/` (Cursor, Zed, VS Code Copilot). Setup also mirrors them into `.claude/skills`, `.windsurf/skills`, and `.github/skills` for Claude Code / Windsurf / Copilot discovery. MCP configs: Cursor / VS Code / Zed + root `.mcp.json`. Reload MCP after `npx @morya-ui/setup ai`. Zed may require trusting the worktree before project skills load.

package/template/scripts/check-raw-colors.mjs

@@ -18,6 +18,12 @@ const HSL = /\bhsl\s*\(/g
 /** Allow transparent, currentColor, inherit in CSS values */
 const ALLOW_LINE = /var\s*\(\s*--m-|color-mix\s*\(|transparent|currentColor|inherit|none/
 
+/** Theme seed / createTheme brand inputs must be concrete colors. */
+const ALLOW_THEME_SEED = /\bcolorPrimary\s*:|\bseed\s*:\s*\{[^}]*colorPrimary/
+
+/** Canvas / encoder fallbacks that must stay concrete for off-DOM drawing. */
+const ALLOW_CANVAS_FALLBACK = /rgb\(\s*0\s*,\s*0\s*,\s*0\s*\)|rgb\(\s*255\s*,\s*255\s*,\s*255\s*\)/
+
 /** Skip demo IDs like '#1024' or 'WO-1024' in script/template strings */
 const DEMO_ID = /['"]#?[A-Z0-9-]{2,}['"]/
 
@@ -28,7 +34,7 @@ function walk(dir) {
     const full = path.join(dir, name)
     const st = statSync(full)
     if (st.isDirectory()) {
-      if (IGNORE_DIRS.has(name)) continue
+      if (IGNORE_DIRS.has(name) || name === 'demos') continue
       walk(full)
       continue
     }
@@ -36,12 +42,15 @@ function walk(dir) {
     if (!EXT.has(ext)) continue
     const normalized = full.replace(/\\/g, '/')
     if (normalized.includes('design-tokens/') || normalized.includes('/theme/')) continue
+    if (normalized.includes('/docs/demos/')) continue
     if (normalized.includes('.test.') || normalized.includes('/__tests__/')) continue
 
     const text = readFileSync(full, 'utf8')
     const lines = text.split(/\r?\n/)
     lines.forEach((line, index) => {
       if (ALLOW_LINE.test(line)) return
+      if (ALLOW_THEME_SEED.test(line)) return
+      if (ALLOW_CANVAS_FALLBACK.test(line)) return
       if (DEMO_ID.test(line)) return
       if (HEX.test(line) || RGB.test(line) || HSL.test(line)) {
         HEX.lastIndex = 0