agentcraft 0.0.2 → 0.0.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.0.9",
+  "version": "0.1.2",
   "description": "Assign sounds to AI coding agent lifecycle events. Works with Claude Code and OpenCode.",
   "author": { "name": "rohenaz" },
   "keywords": ["sounds", "hooks", "audio", "productivity", "opencode", "claude-code"]

package/README.md

@@ -49,11 +49,12 @@ bun install -g agentcraft
 ```
 
 ```bash
-agentcraft pack install rohenaz/agentcraft-sounds   # install a pack from GitHub
-agentcraft pack list                                # list installed packs
-agentcraft pack update rohenaz/agentcraft-sounds   # update a pack (git pull)
-agentcraft pack update --all                       # update all packs
-agentcraft pack remove rohenaz/agentcraft-sounds   # remove a pack
+agentcraft init                                    # first-time setup
+agentcraft add rohenaz/agentcraft-sounds           # install a pack from GitHub
+agentcraft list                                    # list installed packs
+agentcraft update rohenaz/agentcraft-sounds        # update a pack (git pull)
+agentcraft update                                  # update all packs
+agentcraft remove rohenaz/agentcraft-sounds        # remove a pack
 ```
 
 ## Sound Packs

package/bin/agentcraft.js

@@ -2,20 +2,30 @@
 'use strict';
 
 const { execSync, spawnSync } = require('child_process');
-const { existsSync, readdirSync, rmSync, statSync, mkdirSync } = require('fs');
-const { join } = require('path');
+const { existsSync, readdirSync, rmSync, statSync, mkdirSync, readFileSync, copyFileSync, realpathSync } = require('fs');
+const { join, dirname } = require('path');
 const { homedir } = require('os');
 
 const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
+const ASSIGNMENTS_PATH = join(homedir(), '.agentcraft', 'assignments.json');
 const [,, cmd, sub, ...rest] = process.argv;
 
+// ANSI colors — no dependencies
+const c = {
+  cyan:  s => `\x1b[36m${s}\x1b[0m`,
+  green: s => `\x1b[32m${s}\x1b[0m`,
+  red:   s => `\x1b[31m${s}\x1b[0m`,
+  dim:   s => `\x1b[2m${s}\x1b[0m`,
+  bold:  s => `\x1b[1m${s}\x1b[0m`,
+};
+
 function ensureDir(p) {
   mkdirSync(p, { recursive: true });
 }
 
 function parsePackId(arg) {
   if (!arg || !arg.includes('/')) {
-    console.error(`Error: pack must be "publisher/name", got: ${arg ?? '(nothing)'}`);
+    console.error(c.red(`✗ pack must be "publisher/name", got: ${arg ?? '(nothing)'}`));
     process.exit(1);
   }
   const slash = arg.indexOf('/');
@@ -24,133 +34,194 @@ function parsePackId(arg) {
   return { publisher, name, id: arg, url: `https://github.com/${publisher}/${name}` };
 }
 
+function readPackMeta(packPath) {
+  try { return JSON.parse(readFileSync(join(packPath, 'pack.json'), 'utf-8')); } catch { return {}; }
+}
+
 function getInstalledPacks() {
   if (!existsSync(PACKS_DIR)) return [];
   const packs = [];
   for (const publisher of readdirSync(PACKS_DIR)) {
     const ppath = join(PACKS_DIR, publisher);
-    try {
-      if (!statSync(ppath).isDirectory()) continue;
-    } catch { continue; }
+    try { if (!statSync(ppath).isDirectory()) continue; } catch { continue; }
     for (const name of readdirSync(ppath)) {
-      try {
-        if (statSync(join(ppath, name)).isDirectory()) packs.push(`${publisher}/${name}`);
-      } catch { continue; }
+      try { if (statSync(join(ppath, name)).isDirectory()) packs.push(`${publisher}/${name}`); } catch { continue; }
     }
   }
   return packs;
 }
 
-function packInstall(packArg) {
+function packAdd(packArg) {
   const { publisher, name, url } = parsePackId(packArg);
   const dest = join(PACKS_DIR, publisher, name);
   if (existsSync(dest)) {
-    console.log(`Already installed: ${publisher}/${name}`);
+    console.log(c.dim(`Already installed: ${publisher}/${name}`));
     process.exit(0);
   }
   ensureDir(join(PACKS_DIR, publisher));
-  console.log(`Installing ${publisher}/${name} from ${url} ...`);
+  console.log(`→ Installing ${c.cyan(`${publisher}/${name}`)} from ${c.dim(url)} ...`);
   const r = spawnSync('git', ['clone', url, dest], { stdio: 'inherit' });
   if (r.status !== 0) {
-    console.error(`Failed to install ${publisher}/${name}`);
+    console.error(c.red(`✗ Failed to install ${publisher}/${name}`));
     process.exit(1);
   }
-  console.log(`\nInstalled: ${publisher}/${name}`);
+  console.log(c.green(`✓ Installed: ${publisher}/${name}`));
 }
 
 function packRemove(packArg) {
   const { publisher, name } = parsePackId(packArg);
   const dest = join(PACKS_DIR, publisher, name);
   if (!existsSync(dest)) {
-    console.error(`Not installed: ${publisher}/${name}`);
+    console.error(c.red(`✗ Not installed: ${publisher}/${name}`));
     process.exit(1);
   }
   rmSync(dest, { recursive: true, force: true });
-  console.log(`Removed: ${publisher}/${name}`);
+  console.log(c.green(`✓ Removed: ${publisher}/${name}`));
 }
 
 function packUpdate(packArg) {
   const { publisher, name } = parsePackId(packArg);
   const dest = join(PACKS_DIR, publisher, name);
   if (!existsSync(dest)) {
-    console.error(`Not installed: ${publisher}/${name}. Run: agentcraft pack install ${publisher}/${name}`);
+    console.error(c.red(`✗ Not installed: ${publisher}/${name}`));
+    console.error(c.dim(`  Run: agentcraft add ${publisher}/${name}`));
     process.exit(1);
   }
-  console.log(`Updating ${publisher}/${name} ...`);
+  console.log(`→ Updating ${c.cyan(`${publisher}/${name}`)} ...`);
   spawnSync('git', ['-C', dest, 'pull'], { stdio: 'inherit' });
 }
 
 function packList() {
   const packs = getInstalledPacks();
   if (!packs.length) {
-    console.log('No packs installed.');
-    console.log('\nInstall the official pack:');
-    console.log('  agentcraft pack install rohenaz/agentcraft-sounds');
+    console.log(c.dim('No packs installed.'));
+    console.log('');
+    console.log('Install the official pack:');
+    console.log(`  ${c.cyan('agentcraft add rohenaz/agentcraft-sounds')}`);
+    return;
+  }
+  console.log(c.bold('Installed packs:'));
+  for (const p of packs) {
+    const meta = readPackMeta(join(PACKS_DIR, ...p.split('/')));
+    const version = meta.version ? c.dim(` v${meta.version}`) : '';
+    const desc    = meta.description ? c.dim(`   ${meta.description}`) : '';
+    console.log(`  ${c.cyan(p)}${version}${desc}`);
+  }
+}
+
+function packInit() {
+  console.log(c.bold('Initializing AgentCraft...'));
+  console.log('');
+
+  // 1. Install official pack if missing
+  const officialPack = join(PACKS_DIR, 'rohenaz', 'agentcraft-sounds');
+  if (!existsSync(officialPack)) {
+    packAdd('rohenaz/agentcraft-sounds');
   } else {
-    console.log('Installed packs:');
-    for (const p of packs) console.log(`  ${p}`);
+    console.log(c.dim(`✓ Official pack already installed`));
+  }
+
+  // 2. Create assignments.json from pack defaults if missing
+  if (!existsSync(ASSIGNMENTS_PATH)) {
+    const defaultsPath = join(officialPack, 'defaults', 'assignments.json');
+    if (existsSync(defaultsPath)) {
+      ensureDir(join(homedir(), '.agentcraft'));
+      copyFileSync(defaultsPath, ASSIGNMENTS_PATH);
+      console.log(c.green('✓ Created ~/.agentcraft/assignments.json'));
+    }
+  } else {
+    console.log(c.dim('✓ assignments.json already exists'));
+  }
+
+  console.log('');
+  console.log(c.green('✓ AgentCraft ready!'));
+  console.log(`  Dashboard: ${c.cyan('agentcraft start')}`);
+  console.log(`  Browse packs: ${c.cyan('agentcraft list')}`);
+}
+
+function getWebDir() {
+  if (process.env.CLAUDE_PLUGIN_ROOT) {
+    return join(process.env.CLAUDE_PLUGIN_ROOT, 'web');
+  }
+  // Global bun/npm install: bin/agentcraft.js → package root → web/
+  try {
+    return join(dirname(dirname(realpathSync(__filename))), 'web');
+  } catch {
+    console.error(c.red('✗ Cannot locate web directory. Set CLAUDE_PLUGIN_ROOT or reinstall.'));
+    process.exit(1);
   }
 }
 
 function showHelp() {
   console.log(`
-AgentCraft CLI — assign sounds to AI agent lifecycle events
+${c.bold('AgentCraft')} — assign sounds to AI agent lifecycle events
 
-Usage:
-  agentcraft pack install <publisher/name>     Install a sound pack from GitHub
-  agentcraft pack remove  <publisher/name>     Remove an installed pack
-  agentcraft pack update  <publisher/name>     Update a pack (git pull)
-  agentcraft pack update  --all                Update all installed packs
-  agentcraft pack list                         List installed packs
-  agentcraft start                             Launch the dashboard (port 4040)
+${c.cyan('Usage:')}
+  agentcraft init                    Set up AgentCraft (install pack + config)
+  agentcraft add <publisher/name>    Install a sound pack from GitHub
+  agentcraft remove <publisher/name> Remove an installed pack
+  agentcraft update [publisher/name] Update a pack, or all packs if no arg given
+  agentcraft list                    List installed packs
+  agentcraft start                   Launch the dashboard (port 4040)
 
-Examples:
-  agentcraft pack install rohenaz/agentcraft-sounds
-  agentcraft pack update --all
-  agentcraft pack list
+${c.cyan('Examples:')}
+  agentcraft init
+  agentcraft add rohenaz/agentcraft-sounds
+  agentcraft add publisher/custom-pack
+  agentcraft update
+  agentcraft list
 
-Packs are stored at: ~/.agentcraft/packs/<publisher>/<name>/
-Any git repo cloned there is automatically discovered by the dashboard.
+${c.dim('Packs are stored at: ~/.agentcraft/packs/<publisher>/<name>/')}
+${c.dim('Any git repo cloned there is automatically discovered by the dashboard.')}
 
-Install the Claude Code plugin:
+${c.cyan('Install the Claude Code plugin:')}
   claude plugin install agentcraft@rohenaz
 `);
 }
 
-if (cmd === 'pack') {
-  if (sub === 'install') {
-    if (!rest[0]) { console.error('Usage: agentcraft pack install <publisher/name>'); process.exit(1); }
-    packInstall(rest[0]);
-  } else if (sub === 'remove') {
-    if (!rest[0]) { console.error('Usage: agentcraft pack remove <publisher/name>'); process.exit(1); }
-    packRemove(rest[0]);
-  } else if (sub === 'update') {
-    if (rest[0] === '--all') {
-      const packs = getInstalledPacks();
-      if (!packs.length) { console.log('No packs installed.'); process.exit(0); }
-      for (const p of packs) packUpdate(p);
-    } else {
-      if (!rest[0]) { console.error('Usage: agentcraft pack update <publisher/name> | --all'); process.exit(1); }
-      packUpdate(rest[0]);
-    }
-  } else if (sub === 'list') {
-    packList();
+// Route commands
+if (cmd === 'init') {
+  packInit();
+} else if (cmd === 'add') {
+  if (!sub) { console.error(c.red('Usage: agentcraft add <publisher/name>')); process.exit(1); }
+  packAdd(sub);
+} else if (cmd === 'remove') {
+  if (!sub) { console.error(c.red('Usage: agentcraft remove <publisher/name>')); process.exit(1); }
+  packRemove(sub);
+} else if (cmd === 'update') {
+  if (!sub) {
+    const packs = getInstalledPacks();
+    if (!packs.length) { console.log(c.dim('No packs installed.')); process.exit(0); }
+    for (const p of packs) packUpdate(p);
   } else {
-    console.error(`Unknown pack subcommand: ${sub ?? '(none)'}`);
-    console.error('Usage: agentcraft pack <install|remove|update|list>');
-    process.exit(1);
+    packUpdate(sub);
   }
+} else if (cmd === 'list') {
+  packList();
 } else if (cmd === 'start') {
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
-  if (!pluginRoot) {
-    console.error('CLAUDE_PLUGIN_ROOT not set. This command is intended to run from the Claude Code plugin context.');
+  const webDir = getWebDir();
+  if (!existsSync(webDir)) {
+    console.error(c.red(`✗ Web directory not found: ${webDir}`));
     process.exit(1);
   }
-  execSync(`cd "${pluginRoot}/web" && bun dev --port 4040`, { stdio: 'inherit' });
+  console.log(`→ Starting AgentCraft at ${c.cyan('http://localhost:4040')} ...`);
+  execSync(`cd "${webDir}" && bun install --silent && bun dev --port 4040`, { stdio: 'inherit' });
 } else if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
   showHelp();
+} else if (cmd === 'pack') {
+  // Legacy shim — print migration hint and route through
+  const newCmd = sub === 'install' ? 'add' : sub;
+  console.error(c.dim(`Note: "agentcraft pack ${sub}" → "agentcraft ${newCmd}"`));
+  if (sub === 'install') { if (!rest[0]) { console.error(c.red('Usage: agentcraft add <publisher/name>')); process.exit(1); } packAdd(rest[0]); }
+  else if (sub === 'remove') { if (!rest[0]) { console.error(c.red('Usage: agentcraft remove <publisher/name>')); process.exit(1); } packRemove(rest[0]); }
+  else if (sub === 'update') {
+    if (!rest[0] || rest[0] === '--all') { const packs = getInstalledPacks(); for (const p of packs) packUpdate(p); }
+    else packUpdate(rest[0]);
+  }
+  else if (sub === 'list') packList();
+  else { console.error(c.red(`Unknown: agentcraft pack ${sub}`)); process.exit(1); }
 } else {
-  console.error(`Unknown command: ${cmd}`);
+  console.error(c.red(`✗ Unknown command: ${cmd}`));
   showHelp();
   process.exit(1);
 }

package/opencode.js

@@ -3,7 +3,10 @@
  *
  * Plays sounds on OpenCode lifecycle events using the same assignments.json
  * config as the Claude Code plugin. Shared config lives at:
- *   ~/.claude/sounds/assignments.json
+ *   ~/.agentcraft/assignments.json
+ *
+ * Packs are stored at:
+ *   ~/.agentcraft/packs/<publisher>/<name>/
  *
  * To install for OpenCode, symlink or copy this file to:
  *   ~/.config/opencode/plugins/agentcraft.js   (global)
@@ -15,24 +18,42 @@ import { execSync } from 'child_process';
 import { join } from 'path';
 import { homedir } from 'os';
 
-const CONFIG_PATH = join(homedir(), '.claude', 'sounds', 'assignments.json');
-const LIBRARY_PATH = join(homedir(), 'code', 'claude-sounds');
+const ASSIGNMENTS_PATH = join(homedir(), '.agentcraft', 'assignments.json');
+const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
 
 function getAssignments() {
   try {
-    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+    return JSON.parse(readFileSync(ASSIGNMENTS_PATH, 'utf8'));
   } catch {
     return null;
   }
 }
 
+function resolvePackPath(soundPath) {
+  if (!soundPath) return null;
+  if (soundPath.includes(':')) {
+    // "publisher/name:internal/path/to/sound.mp3"
+    const colon = soundPath.indexOf(':');
+    const packId = soundPath.slice(0, colon);
+    const internal = soundPath.slice(colon + 1);
+    const slash = packId.indexOf('/');
+    const publisher = packId.slice(0, slash);
+    const name = packId.slice(slash + 1);
+    return join(PACKS_DIR, publisher, name, internal);
+  }
+  // Legacy path — resolve against official pack
+  return join(PACKS_DIR, 'rohenaz', 'agentcraft-sounds', soundPath);
+}
+
 function play(soundPath) {
-  if (!soundPath) return;
-  const full = join(LIBRARY_PATH, soundPath);
-  if (!existsSync(full)) return;
+  const full = resolvePackPath(soundPath);
+  if (!full || !existsSync(full)) return;
   try {
     if (process.platform === 'darwin') execSync(`afplay "${full}" &`, { stdio: 'ignore' });
-    else if (process.platform === 'linux') execSync(`paplay "${full}" &`, { stdio: 'ignore' });
+    else if (process.platform === 'linux') {
+      if (existsSync('/usr/bin/paplay')) execSync(`paplay "${full}" &`, { stdio: 'ignore' });
+      else execSync(`aplay "${full}" &`, { stdio: 'ignore' });
+    }
   } catch { /* non-blocking, ignore errors */ }
 }
 
@@ -62,7 +83,6 @@ export const AgentCraft = async () => {
     'tool.execute.before': async (input) => {
       const a = getAssignments();
       if (!a || a.settings?.enabled === false) return;
-
       if (input.tool === 'skill') {
         const key = input.args?.skill;
         if (!key) return;
@@ -75,7 +95,6 @@ export const AgentCraft = async () => {
     'tool.execute.after': async (input) => {
       const a = getAssignments();
       if (!a || a.settings?.enabled === false) return;
-
       if (input.tool === 'skill') {
         const key = input.args?.skill;
         if (!key) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Assign sounds to AI coding agent lifecycle events. CLI for managing sound packs.",
   "license": "MIT",
   "author": "rohenaz",

package/skills/packs/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: agentcraft-packs
+description: This skill should be used when the user asks to "install a sound pack", "add a pack", "find sound packs", "publish a pack", "create a pack", "share my sounds", "agentcraft pack install", "browse packs", "remove a pack", "update packs", or wants to know how the AgentCraft pack system works.
+---
+
+# AgentCraft Sound Packs
+
+Sound packs are git repos containing audio files. Any GitHub repo can be a pack — no approval, no registry required. Install by `publisher/name` slug, same as GitHub.
+
+## Installing Packs
+
+### From the CLI
+
+```bash
+agentcraft init                                    # first-time setup
+agentcraft add rohenaz/agentcraft-sounds           # official pack
+agentcraft add publisher/repo-name                 # any GitHub repo
+agentcraft list                                    # show installed packs
+agentcraft update rohenaz/agentcraft-sounds        # git pull one pack
+agentcraft update                                  # update all packs
+agentcraft remove publisher/repo-name              # uninstall
+```
+
+`agentcraft pack install publisher/repo-name` resolves to `https://github.com/publisher/repo-name` and clones into `~/.agentcraft/packs/publisher/repo-name/`.
+
+Install the CLI globally:
+```bash
+bun install -g agentcraft   # or: npm install -g agentcraft
+```
+
+### From the Dashboard
+
+Open the **PACKS** tab in the AgentCraft dashboard. Installed packs show UPDATE/REMOVE buttons. The **BROWSE PACKS** section fetches the community registry and shows packs not yet installed with an INSTALL button.
+
+### Manual Install (identical result)
+
+```bash
+git clone https://github.com/publisher/repo-name ~/.agentcraft/packs/publisher/repo-name
+```
+
+Manual clone and CLI install are exactly equivalent — no manifest or registration step.
+
+## Pack Storage
+
+Packs live at `~/.agentcraft/packs/<publisher>/<name>/`. The dashboard auto-discovers everything at that path depth — any directory placed there works.
+
+```
+~/.agentcraft/packs/
+  rohenaz/
+    agentcraft-sounds/     ← official pack
+  publisher/
+    custom-pack/           ← any git repo cloned here
+```
+
+## Sound Assignment Paths
+
+Assigned sounds are stored in `~/.agentcraft/assignments.json` with a pack-prefixed path:
+
+```
+rohenaz/agentcraft-sounds:sc2/terran/session-start/scv-ready.mp3
+```
+
+Format: `publisher/name:internal/path/to/sound.mp3`
+
+The hook script resolves this to the absolute path at runtime:
+```
+~/.agentcraft/packs/rohenaz/agentcraft-sounds/sc2/terran/session-start/scv-ready.mp3
+```
+
+## Publishing a Pack
+
+Any GitHub repo with audio files (`.mp3`, `.wav`, `.ogg`, `.m4a`) is a valid pack. No manifest required — directory structure is the organization.
+
+### Step 1: Organize the repo
+
+Recommended structure — group sounds into directories by game, theme, or purpose:
+
+```
+my-sounds/
+  sc2/
+    terran/
+      session-start/
+        ready.mp3
+      task-complete/
+        salute.mp3
+  halo/
+    unsc/
+      session-start/
+        wake-up.mp3
+  ui/               ← optional: UI theme sounds
+    sc2/
+      click.mp3
+      hover.mp3
+```
+
+Any directory layout works. The dashboard groups sounds by their directory path.
+
+### Step 2: Add `pack.json` (optional but recommended)
+
+```json
+{
+  "name": "my-sounds",
+  "publisher": "your-github-username",
+  "version": "1.0.0",
+  "description": "Short description of the pack",
+  "types": ["sounds", "ui"]
+}
+```
+
+`types` is informational. Use `"ui"` if the pack includes a `ui/` directory with dashboard theme sounds.
+
+### Step 3: Tag the repo on GitHub
+
+Add the `agentcraft-pack` topic to the GitHub repo. This makes it discoverable in:
+- The community registry at `https://rohenaz.github.io/agentcraft-registry/`
+- GitHub search: `https://github.com/topics/agentcraft-pack`
+
+To tag: GitHub repo → **Settings** → **Topics** → type `agentcraft-pack` → Save.
+
+The registry GitHub Action runs every 6 hours and automatically picks up newly tagged repos.
+
+### Step 4: Share the install command
+
+```bash
+agentcraft pack install your-username/your-repo-name
+```
+
+That's the entire publish workflow — push to GitHub, tag it, done.
+
+## Pack Discovery
+
+Find community packs three ways:
+
+1. **Dashboard** — PACKS tab → BROWSE PACKS section shows the registry
+2. **Registry** — `https://github.com/topics/agentcraft-pack`
+3. **Registry JSON** — `https://rohenaz.github.io/agentcraft-registry/index.json`
+
+## UI Theme Sounds
+
+Packs can include a `ui/` directory with sounds that play as you use the AgentCraft dashboard (hover, click, page change, etc.). The dashboard's **UI SFX** dropdown lets users pick which pack's UI theme to use.
+
+Structure the `ui/` directory by theme name:
+
+```
+ui/
+  sc2/
+    click.mp3
+    hover.mp3
+    confirm.mp3
+    error.mp3
+    pageChange.mp3
+  wc3/
+    click.mp3
+    ...
+```
+
+## Additional Resources
+
+- **`references/pack-format.md`** — Full audio file requirements, directory naming conventions, and pack.json schema
+- **Registry source** — `https://github.com/rohenaz/agentcraft-registry`

package/skills/packs/references/pack-format.md

@@ -0,0 +1,122 @@
+# Pack Format Reference
+
+## Audio File Requirements
+
+Supported formats: `.mp3`, `.wav`, `.ogg`, `.m4a`
+
+Recommended: `.mp3` at 128–192kbps for compatibility and small file size.
+
+File names become the display name in the sound browser (dashes/underscores become spaces, title-cased). Keep names descriptive:
+- `scv-ready.mp3` → "Scv Ready"
+- `marine-salute-00.mp3` → "Marine Salute 00"
+
+## Directory Structure
+
+No required structure. The dashboard reads depth dynamically:
+
+- Top-level directories → **Group tabs** (e.g. `sc2`, `halo`, `classic-os`)
+- Second-level directories → **Sub-tabs** (e.g. `sc2/terran`, `halo/unsc`)
+- Third-level directories → **Subcategories** within a sub-tab (e.g. `sc2/terran/session-start`)
+- Files at any depth → Sound cards
+
+Example layouts that all work:
+
+**Game-organized:**
+```
+sc2/terran/session-start/scv-ready.mp3
+sc2/terran/task-complete/marine-salute.mp3
+sc2/protoss/session-start/probe-ready.mp3
+```
+
+**Flat:**
+```
+sounds/click.mp3
+sounds/beep.mp3
+```
+
+**Mood-organized:**
+```
+ambient/forest/birds.mp3
+action/alert/warning.mp3
+```
+
+## pack.json Schema
+
+All fields are optional. Used for display in the PACKS tab and the community registry.
+
+```json
+{
+  "name": "string",           // Display name (defaults to directory name)
+  "publisher": "string",      // GitHub username (defaults to directory publisher)
+  "version": "string",        // Semantic version, e.g. "1.0.0"
+  "description": "string",    // One-line description shown in dashboard
+  "types": ["sounds", "ui"]   // Content types: "sounds", "ui", or both
+}
+```
+
+## UI Theme Sounds
+
+Include a `ui/` directory at the pack root for dashboard UI sounds. Subdirectories are theme names. Each theme can define any subset of these event sounds:
+
+| Filename | Trigger |
+|----------|---------|
+| `click.mp3` | Button click |
+| `hover.mp3` | Element hover |
+| `confirm.mp3` | Save / success action |
+| `error.mp3` | Error / failure |
+| `pageChange.mp3` | Tab / page switch |
+| `drag.mp3` | Drag start |
+| `drop.mp3` | Drop onto slot |
+| `open.mp3` | Panel/modal open |
+| `close.mp3` | Panel/modal close |
+
+Missing files are silently skipped. Themes with no `ui/` directory are sound-only packs.
+
+Example:
+```
+ui/
+  sc2/
+    click.mp3
+    hover.mp3
+    confirm.mp3
+    error.mp3
+  wc3/
+    click.mp3
+    hover.mp3
+```
+
+## Assignment Path Format
+
+When a sound is assigned to a hook, it's stored as:
+
+```
+publisher/pack-name:path/to/sound.mp3
+```
+
+The colon (`:`) separates pack identity from the internal path. The hook script resolves this to:
+
+```
+~/.agentcraft/packs/publisher/pack-name/path/to/sound.mp3
+```
+
+Sounds from your pack will automatically use this format when assigned through the dashboard.
+
+## GitHub Topics
+
+Tag your repo with `agentcraft-pack` to appear in the community registry. Additional optional tags:
+
+| Topic | Meaning |
+|-------|---------|
+| `agentcraft-pack` | Required for discovery |
+| `agentcraft-type-sounds` | Pack contains hook sounds |
+| `agentcraft-type-ui` | Pack contains UI theme sounds |
+
+The `agentcraft-type-*` topics are parsed by the registry Action and populate the `types` field in `index.json` automatically (as a fallback when no `pack.json` is present).
+
+## File Size Guidelines
+
+- Individual sounds: ideally < 500KB, max 2MB
+- Total pack size: ideally < 50MB
+- Large packs slow down `agentcraft pack install` (git clone)
+
+Consider using `.gitattributes` with Git LFS for packs with many large audio files.

package/web/app/api/packs/route.ts

@@ -0,0 +1,109 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readdir, stat, readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawnSync } from 'child_process';
+
+const PACKS_DIR = join(homedir(), '.agentcraft', 'packs');
+
+interface PackInfo {
+  id: string;          // "publisher/name"
+  publisher: string;
+  name: string;
+  description?: string;
+  version?: string;
+}
+
+async function getInstalledPacks(): Promise<PackInfo[]> {
+  const packs: PackInfo[] = [];
+  let publishers: string[];
+  try {
+    publishers = await readdir(PACKS_DIR);
+  } catch {
+    return packs;
+  }
+  for (const publisher of publishers) {
+    const pubPath = join(PACKS_DIR, publisher);
+    const ps = await stat(pubPath).catch(() => null);
+    if (!ps?.isDirectory()) continue;
+    const names = await readdir(pubPath).catch(() => [] as string[]);
+    for (const name of names) {
+      const packPath = join(pubPath, name);
+      const ns = await stat(packPath).catch(() => null);
+      if (!ns?.isDirectory()) continue;
+      // Try to read pack.json for metadata
+      let description: string | undefined;
+      let version: string | undefined;
+      try {
+        const manifest = JSON.parse(await readFile(join(packPath, 'pack.json'), 'utf-8'));
+        description = manifest.description;
+        version = manifest.version;
+      } catch { /* no manifest, that's fine */ }
+      packs.push({ id: `${publisher}/${name}`, publisher, name, description, version });
+    }
+  }
+  return packs;
+}
+
+// GET — list installed packs
+export async function GET() {
+  const packs = await getInstalledPacks();
+  return NextResponse.json(packs);
+}
+
+// POST { repo: "publisher/name" } — install a pack
+export async function POST(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    const url = `https://github.com/${repo}`;
+    // mkdir publisher dir
+    spawnSync('mkdir', ['-p', join(PACKS_DIR, publisher)]);
+    const result = spawnSync('git', ['clone', url, dest], { timeout: 60000 });
+    if (result.status !== 0) {
+      return NextResponse.json({ error: 'Clone failed' }, { status: 500 });
+    }
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Install failed' }, { status: 500 });
+  }
+}
+
+// DELETE { repo: "publisher/name" } — remove a pack
+export async function DELETE(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    spawnSync('rm', ['-rf', dest]);
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Remove failed' }, { status: 500 });
+  }
+}
+
+// PATCH { repo: "publisher/name" } — update a pack (git pull)
+export async function PATCH(req: NextRequest) {
+  try {
+    const { repo } = await req.json();
+    if (!repo || !/^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(repo)) {
+      return NextResponse.json({ error: 'Invalid repo format' }, { status: 400 });
+    }
+    const [publisher, name] = repo.split('/');
+    const dest = join(PACKS_DIR, publisher, name);
+    const result = spawnSync('git', ['-C', dest, 'pull'], { timeout: 30000 });
+    if (result.status !== 0) {
+      return NextResponse.json({ error: 'Update failed' }, { status: 500 });
+    }
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Update failed' }, { status: 500 });
+  }
+}

package/web/components/agent-roster-panel.tsx

@@ -3,6 +3,7 @@
 import { useState, useMemo } from 'react';
 import { HookSlot } from './hook-slot';
 import { AgentForm } from './agent-form';
+import { PacksPanel } from './packs-panel';
 import { playUISound } from '@/lib/ui-audio';
 import { getEventLabel } from '@/lib/utils';
 import type { HookEvent, SkillHookEvent, SoundAssignments, AgentInfo, SkillInfo, AgentFormData, SelectMode } from '@/lib/types';
@@ -220,7 +221,7 @@ interface AgentRosterPanelProps {
 }
 
 export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChange, onPreview, onAgentsChange, selectMode, onSlotSelect }: AgentRosterPanelProps) {
-  const [activeView, setActiveView] = useState<'agents' | 'skills'>('agents');
+  const [activeView, setActiveView] = useState<'agents' | 'skills' | 'packs'>('agents');
   const [showForm, setShowForm] = useState(false);
   const [editingAgent, setEditingAgent] = useState<AgentInfo | undefined>();
   const [skillSearch, setSkillSearch] = useState('');
@@ -341,7 +342,7 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
       {/* Tab bar header */}
       <div className="shrink-0 border-b" style={{ borderColor: 'var(--sf-border)', backgroundColor: 'var(--sf-panel)' }}>
         <div className="flex items-stretch">
-          {(['agents', 'skills'] as const).map((view) => (
+          {(['agents', 'skills', 'packs'] as const).map((view) => (
             <button
               key={view}
               data-sf-hover
@@ -359,7 +360,7 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
                 backgroundColor: activeView === view ? 'rgba(0,229,255,0.04)' : 'transparent',
               }}
             >
-              {view === 'agents' ? 'AGENTS' : 'SKILLS'}
+              {view.toUpperCase()}
             </button>
           ))}
           {activeView === 'agents' && (
@@ -496,6 +497,8 @@ export function AgentRosterPanel({ assignments, agents, skills, onAssignmentChan
             })}
           </>
         )}
+
+        {activeView === 'packs' && <PacksPanel />}
       </div>
     </div>
   );

package/web/components/packs-panel.tsx

@@ -0,0 +1,180 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { playUISound } from '@/lib/ui-audio';
+
+interface PackInfo {
+  id: string;
+  publisher: string;
+  name: string;
+  description?: string;
+  version?: string;
+}
+
+interface RegistryPack {
+  id: string;
+  name: string;
+  publisher: string;
+  description: string;
+  stars: number;
+  updatedAt: string;
+}
+
+type PackAction = 'idle' | 'installing' | 'updating' | 'removing';
+
+export function PacksPanel() {
+  const [installed, setInstalled] = useState<PackInfo[]>([]);
+  const [registry, setRegistry] = useState<RegistryPack[]>([]);
+  const [actions, setActions] = useState<Record<string, PackAction>>({});
+  const [registryError, setRegistryError] = useState(false);
+
+  const fetchInstalled = useCallback(() => {
+    fetch('/api/packs').then(r => r.json()).then(setInstalled).catch(console.error);
+  }, []);
+
+  useEffect(() => {
+    fetchInstalled();
+    // Fetch registry index
+    fetch('https://rohenaz.github.io/agentcraft-registry/index.json')
+      .then(r => r.json())
+      .then(setRegistry)
+      .catch(() => setRegistryError(true));
+  }, [fetchInstalled]);
+
+  const setAction = (id: string, action: PackAction) =>
+    setActions(prev => ({ ...prev, [id]: action }));
+
+  const handleInstall = async (id: string) => {
+    setAction(id, 'installing');
+    try {
+      const r = await fetch('/api/packs', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ repo: id }) });
+      if (!r.ok) throw new Error();
+      playUISound('confirm', 0.5);
+      fetchInstalled();
+    } catch {
+      playUISound('error', 0.5);
+    }
+    setAction(id, 'idle');
+  };
+
+  const handleUpdate = async (id: string) => {
+    setAction(id, 'updating');
+    try {
+      const r = await fetch('/api/packs', { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ repo: id }) });
+      if (!r.ok) throw new Error();
+      playUISound('confirm', 0.4);
+    } catch {
+      playUISound('error', 0.5);
+    }
+    setAction(id, 'idle');
+  };
+
+  const handleRemove = async (id: string) => {
+    setAction(id, 'removing');
+    try {
+      const r = await fetch('/api/packs', { method: 'DELETE', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ repo: id }) });
+      if (!r.ok) throw new Error();
+      fetchInstalled();
+    } catch {
+      playUISound('error', 0.5);
+    }
+    setAction(id, 'idle');
+  };
+
+  const installedIds = new Set(installed.map(p => p.id));
+  const browsePacks = registry.filter(p => !installedIds.has(p.id));
+
+  const btnStyle = (active: boolean, danger = false) => ({
+    border: `1px solid ${danger ? 'rgba(255,80,80,0.4)' : active ? 'var(--sf-cyan)' : 'var(--sf-border)'}`,
+    color: danger ? 'rgba(255,80,80,0.7)' : active ? 'var(--sf-cyan)' : 'rgba(255,255,255,0.4)',
+    backgroundColor: 'transparent',
+    padding: '2px 8px',
+    fontSize: '9px',
+    fontFamily: 'inherit',
+    letterSpacing: '0.08em',
+    textTransform: 'uppercase' as const,
+    cursor: 'pointer',
+    transition: 'all 0.15s',
+  });
+
+  return (
+    <div className="flex flex-col overflow-hidden h-full">
+      {/* Installed */}
+      <div className="shrink-0 px-3 pt-3 pb-1">
+        <div className="text-[10px] sf-heading font-semibold tracking-widest uppercase mb-2" style={{ color: 'var(--sf-cyan)' }}>
+          INSTALLED PACKS
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto px-3 pb-3 space-y-1">
+        {installed.length === 0 && (
+          <div className="text-[10px] opacity-30 py-4 text-center">NO PACKS INSTALLED</div>
+        )}
+        {installed.map(pack => {
+          const action = actions[pack.id] ?? 'idle';
+          return (
+            <div key={pack.id} className="p-2.5" style={{ border: '1px solid var(--sf-border)', backgroundColor: 'rgba(0,229,255,0.02)' }}>
+              <div className="flex items-start justify-between gap-2">
+                <div className="overflow-hidden">
+                  <div className="text-xs sf-heading font-semibold truncate" style={{ color: 'rgba(255,255,255,0.85)' }}>
+                    {pack.name}
+                  </div>
+                  <div className="text-[10px] opacity-40">{pack.publisher}{pack.version ? ` · v${pack.version}` : ''}</div>
+                  {pack.description && (
+                    <div className="text-[10px] opacity-50 mt-0.5 line-clamp-2">{pack.description}</div>
+                  )}
+                </div>
+                <div className="flex gap-1 shrink-0">
+                  <button style={btnStyle(false)} disabled={action !== 'idle'} onClick={() => handleUpdate(pack.id)}>
+                    {action === 'updating' ? '···' : 'UPDATE'}
+                  </button>
+                  <button style={btnStyle(false, true)} disabled={action !== 'idle'} onClick={() => handleRemove(pack.id)}>
+                    {action === 'removing' ? '···' : 'REMOVE'}
+                  </button>
+                </div>
+              </div>
+            </div>
+          );
+        })}
+
+        {/* Browse */}
+        <div className="text-[10px] sf-heading font-semibold tracking-widest uppercase mt-4 mb-2" style={{ color: 'var(--sf-cyan)' }}>
+          BROWSE PACKS
+        </div>
+
+        {registryError && (
+          <div className="text-[10px] opacity-30 py-2 text-center">REGISTRY UNAVAILABLE</div>
+        )}
+
+        {!registryError && browsePacks.length === 0 && registry.length > 0 && (
+          <div className="text-[10px] opacity-30 py-2 text-center">ALL AVAILABLE PACKS INSTALLED</div>
+        )}
+
+        {browsePacks.map(pack => {
+          const action = actions[pack.id] ?? 'idle';
+          return (
+            <div key={pack.id} className="p-2.5" style={{ border: '1px solid var(--sf-border)' }}>
+              <div className="flex items-start justify-between gap-2">
+                <div className="overflow-hidden">
+                  <div className="flex items-center gap-2">
+                    <span className="text-xs sf-heading font-semibold truncate" style={{ color: 'rgba(255,255,255,0.85)' }}>
+                      {pack.name}
+                    </span>
+                    {pack.stars > 0 && (
+                      <span className="text-[9px] opacity-40">★ {pack.stars}</span>
+                    )}
+                  </div>
+                  <div className="text-[10px] opacity-40">{pack.publisher}</div>
+                  <div className="text-[10px] opacity-50 mt-0.5 line-clamp-2">{pack.description}</div>
+                </div>
+                <button style={btnStyle(true)} disabled={action !== 'idle'} onClick={() => handleInstall(pack.id)}>
+                  {action === 'installing' ? '···' : 'INSTALL'}
+                </button>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/web/components/sound-browser-panel.tsx

@@ -15,6 +15,12 @@ interface SoundBrowserPanelProps {
   onClearSelectMode: () => void;
 }
 
+// Strip pack prefix from category: "publisher/name:sc2/terran" → "sc2/terran"
+function internalCat(category: string): string {
+  const idx = category.indexOf(':');
+  return idx === -1 ? category : category.slice(idx + 1);
+}
+
 export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode, onSelectModeAssign, onClearSelectMode }: SoundBrowserPanelProps) {
   const [activeGroup, setActiveGroup] = useState<string>('sc2');
   const [activeCategory, setActiveCategory] = useState<string>('sc2/terran');
@@ -31,12 +37,12 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
   }, []);
 
   const allGroups = useMemo(() => {
-    return [...new Set(sounds.map((s) => s.category.split('/')[0]))].sort();
+    return [...new Set(sounds.map((s) => internalCat(s.category).split('/')[0]))].sort();
   }, [sounds]);
 
   const groupCategories = useMemo(() => {
     return [...new Set(
-      sounds.filter((s) => s.category.split('/')[0] === activeGroup).map((s) => s.category)
+      sounds.filter((s) => internalCat(s.category).split('/')[0] === activeGroup).map((s) => s.category)
     )].sort();
   }, [sounds, activeGroup]);
 
@@ -131,7 +137,7 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
                   backgroundColor: effectiveCategory === cat ? 'rgba(0,229,255,0.05)' : 'transparent',
                 }}
               >
-                {getSubTabLabel(cat)}
+                {getSubTabLabel(internalCat(cat))}
               </button>
             ))}
           </div>
@@ -176,7 +182,7 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
           <div key={cat}>
             {isSearching && (
               <div className="text-[9px] uppercase tracking-widest mb-1 mt-3 px-1 first:mt-0" style={{ color: 'var(--sf-cyan)', opacity: 0.6 }}>
-                {cat.replace(/\//g, ' › ')}
+                {internalCat(cat).replace(/\//g, ' › ')}
               </div>
             )}
             {Object.entries(subcats).map(([subcat, catSounds]) => (