agentcraft 0.0.3 → 0.0.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "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/TODO.md

@@ -0,0 +1,29 @@
+# AgentCraft TODO
+
+## Features
+
+### Push-to-Talk / Dictation Mute Key
+Assign a configurable hotkey (default: Fn key) that suppresses sound playback while held.
+Use case: PTT dictation apps (Whisper, SuperWhisper, etc.) use a held key to record. Sounds
+firing during active recording interrupt or bleed into the mic capture.
+
+**Design notes:**
+- Settings UI: "MUTE WHILE HELD" key picker in the dashboard (default `Fn`, allow any key)
+- Stored in `assignments.json` under `settings.muteKey` (e.g. `"Fn"`, `"CapsLock"`, `"F13"`)
+- Detection: the hook script can't read keyboard state directly. Options:
+  1. **Lock file approach** — dashboard JS writes `/tmp/agentcraft-muted.lock` on `keydown`
+     and removes it on `keyup`. Hook script checks for file existence before playing.
+     Requires the dashboard to be open (reasonable — it's a config tool).
+  2. **Daemon approach** — small background process (bun script) listens to keyboard events
+     via IOKit/CGEvent on macOS and manages the lock file. Survives without dashboard open.
+  3. **Passive detection** — read `/proc/bus/input` on Linux or `hidutil` output on macOS
+     to poll key state at hook execution time (complex, likely too slow).
+- Recommended: start with option 1 (lock file via dashboard), add option 2 as optional daemon.
+- The `play-sound.sh` check would be: `[ -f "/tmp/agentcraft-muted.lock" ] && exit 0`
+- Dashboard global keydown/keyup listeners write/remove the lock file via a small API route
+  (`POST /api/mute { active: boolean }`)
+
+### Sound Browser SOURCE Dropdown (multi-pack filter)
+Gemini Option A: compact SOURCE dropdown above group tabs, invisible at 1 pack, appears at 2+.
+Filters the sound browser to a specific pack or shows all with pack badges on cards.
+See: conversation history / Gemini recommendation for full spec.

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, writeFileSync, 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,297 @@ 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(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('Installed packs:');
-    for (const p of packs) console.log(`  ${p}`);
+    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 createPack(name) {
+  if (!name) {
+    console.error(c.red('Usage: agentcraft create-pack <name>'));
+    console.error(c.dim('  Example: agentcraft create-pack my-sounds'));
+    process.exit(1);
+  }
+  if (existsSync(name)) {
+    console.error(c.red(`✗ Directory already exists: ${name}`));
+    process.exit(1);
+  }
+
+  // Try to detect GitHub username from git config
+  let publisher = 'your-github-username';
+  try {
+    const gitUser = execSync('git config --global user.name 2>/dev/null', { encoding: 'utf-8' }).trim();
+    const gitEmail = execSync('git config --global github.user 2>/dev/null', { encoding: 'utf-8' }).trim();
+    if (gitEmail) publisher = gitEmail;
+    else if (gitUser) publisher = gitUser.toLowerCase().replace(/\s+/g, '-');
+  } catch { /* use default */ }
+
+  console.log(`→ Creating pack ${c.cyan(name)} ...`);
+
+  // Directory structure
+  ensureDir(join(name, 'sounds', 'session-start'));
+  ensureDir(join(name, 'sounds', 'task-complete'));
+  ensureDir(join(name, 'sounds', 'error'));
+  ensureDir(join(name, 'ui', 'my-theme'));
+
+  // pack.json
+  writeFileSync(join(name, 'pack.json'), JSON.stringify({
+    name,
+    publisher,
+    version: '1.0.0',
+    description: 'My AgentCraft sound pack',
+    types: ['sounds'],
+  }, null, 2) + '\n');
+
+  // .gitignore
+  writeFileSync(join(name, '.gitignore'), '.DS_Store\nThumbs.db\n');
+
+  // README.md
+  writeFileSync(join(name, 'README.md'), `# ${name}
+
+An [AgentCraft](https://github.com/rohenaz/agentcraft) sound pack.
+
+## Install
+
+\`\`\`bash
+agentcraft add ${publisher}/${name}
+\`\`\`
+
+Or manually:
+
+\`\`\`bash
+git clone https://github.com/${publisher}/${name} ~/.agentcraft/packs/${publisher}/${name}
+\`\`\`
+
+## Structure
+
+Drop \`.mp3\`, \`.wav\`, \`.ogg\`, or \`.m4a\` files into directories. The dashboard auto-discovers them:
+
+\`\`\`
+sounds/
+  session-start/     ← sounds here appear under "sounds > session start" group
+  task-complete/
+  error/
+ui/
+  my-theme/          ← optional: UI sounds for the dashboard itself
+    click.mp3
+    hover.mp3
+    confirm.mp3
+    error.mp3
+    pageChange.mp3
+\`\`\`
+
+Top-level directories become group tabs. Nested directories become sub-tabs and subcategories.
+Any layout works — organise however makes sense for your sounds.
+
+## Publishing
+
+1. Push this repo to GitHub as \`${publisher}/${name}\`
+2. Go to **Settings → Topics** and add the topic \`agentcraft-pack\`
+3. The community registry picks it up within 6 hours
+
+Users can then find and install it from the AgentCraft dashboard PACKS tab.
+`);
+
+  console.log(c.green(`✓ Created ${name}/`));
+  console.log('');
+  console.log('Next steps:');
+  console.log(`  1. Drop ${c.cyan('.mp3/.wav/.ogg')} files into the subdirectories`);
+  console.log(`  2. Push to GitHub as ${c.cyan(`${publisher}/${name}`)}`);
+  console.log(`  3. Add topic ${c.cyan('agentcraft-pack')} in GitHub Settings → Topics`);
+  console.log('');
+  console.log('Test locally before publishing:');
+  console.log(c.dim(`  git clone . ~/.agentcraft/packs/${publisher}/${name}`));
+  console.log(c.dim('  agentcraft start'));
+}
+
+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)
+  agentcraft create-pack <name>         Scaffold a new sound pack repo
 
-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
+  agentcraft create-pack my-sounds
 
-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 === 'create-pack') {
+  createPack(sub);
+} 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/commands/agentcraft.md

@@ -12,15 +12,9 @@ kill $(lsof -ti:4040) 2>/dev/null
 echo "AgentCraft server stopped."
 ```
 
-Check if the official sound pack is installed:
+Run first-time setup (installs official pack + creates assignments.json if missing):
 ```bash
-ls ~/.agentcraft/packs/rohenaz/agentcraft-sounds 2>/dev/null | head -1
-```
-
-If that returned nothing (empty or missing), install it:
-```bash
-agentcraft pack install rohenaz/agentcraft-sounds 2>/dev/null || \
-  git clone https://github.com/rohenaz/agentcraft-sounds ~/.agentcraft/packs/rohenaz/agentcraft-sounds
+agentcraft init
 ```
 
 Check if server is already running:

package/hooks/play-sound.sh

@@ -17,6 +17,8 @@ TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
 ENABLED=$(jq -r '.settings.enabled // true' "$CONFIG")
 [ "$ENABLED" = "false" ] && exit 0
 
+VOLUME=$(jq -r '.settings.masterVolume // 1' "$CONFIG")
+
 # Deduplicate: prevent the same event from firing within 3 seconds.
 # Claude Code fires SessionStart twice on resume (process init + session restore).
 LOCKFILE="/tmp/agentcraft-${EVENT}.lock"
@@ -70,9 +72,10 @@ fi
 [ ! -f "$FULL" ] && exit 0
 
 if [[ "$OSTYPE" == "darwin"* ]]; then
-  afplay "$FULL" &
+  afplay -v "$VOLUME" "$FULL" &
 elif command -v paplay &>/dev/null; then
-  paplay "$FULL" &
+  VOLUME_PAPLAY=$(awk "BEGIN{printf \"%d\", $VOLUME * 65536}")
+  paplay --volume="$VOLUME_PAPLAY" "$FULL" &
 elif command -v aplay &>/dev/null; then
   aplay "$FULL" &
 fi

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.3",
+  "version": "0.0.5",
   "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,169 @@
+---
+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", "create-pack", "scaffold 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 create-pack my-sounds                   # scaffold a new pack repo
+```
+
+`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 0: Scaffold with the CLI (fastest path)
+
+```bash
+agentcraft create-pack my-sounds
+```
+
+This generates a ready-to-use pack directory with `pack.json`, `README.md`, example directories, and publishing instructions. Then drop your audio files in and push.
+
+### 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 add 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/preview/route.ts

@@ -4,13 +4,14 @@ import { resolvePackPath } from '@/lib/packs';
 
 export async function POST(req: NextRequest) {
   try {
-    const { path } = await req.json();
+    const { path, volume } = await req.json();
     if (!path || typeof path !== 'string') {
       return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
     }
     const fullPath = resolvePackPath(path);
     if (!fullPath) return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
-    spawn('afplay', [fullPath], { detached: true, stdio: 'ignore' }).unref();
+    const vol = typeof volume === 'number' && volume >= 0 && volume <= 1 ? volume : 1.0;
+    spawn('afplay', ['-v', String(vol), fullPath], { detached: true, stdio: 'ignore' }).unref();
     return NextResponse.json({ ok: true });
   } catch {
     return NextResponse.json({ error: 'Playback failed' }, { status: 500 });

package/web/app/page.tsx

@@ -79,9 +79,9 @@ export default function Page() {
     await fetch('/api/preview', {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ path }),
+      body: JSON.stringify({ path, volume: assignments.settings.masterVolume }),
     });
-  }, []);
+  }, [assignments.settings.masterVolume]);
 
   const handleSave = useCallback(async () => {
     await fetch('/api/assignments', {
@@ -100,6 +100,13 @@ export default function Page() {
     });
   }, [assignments, handleAssignmentChange]);
 
+  const handleVolumeChange = useCallback((volume: number) => {
+    handleAssignmentChange({
+      ...assignments,
+      settings: { ...assignments.settings, masterVolume: volume },
+    });
+  }, [assignments, handleAssignmentChange]);
+
   const handleUiThemeChange = useCallback((theme: UITheme) => {
     setUITheme(theme, assignments.settings?.uiSounds?.[theme]);
     handleAssignmentChange({
@@ -227,7 +234,7 @@ export default function Page() {
   return (
     <DndContext sensors={sensors} onDragStart={handleDragStart} onDragEnd={handleDragEnd}>
       <div className="h-screen w-screen overflow-hidden flex flex-col" style={{ backgroundColor: 'var(--sf-bg)' }}>
-        <HudHeader enabled={assignments.settings.enabled} onToggle={handleToggleEnabled} uiTheme={assignments.settings.uiTheme ?? 'sc2'} onUiThemeChange={handleUiThemeChange} onConfigureUISounds={() => setShowUISoundsModal(true)} />
+        <HudHeader enabled={assignments.settings.enabled} onToggle={handleToggleEnabled} uiTheme={assignments.settings.uiTheme ?? 'sc2'} onUiThemeChange={handleUiThemeChange} onConfigureUISounds={() => setShowUISoundsModal(true)} masterVolume={assignments.settings.masterVolume ?? 1.0} onVolumeChange={handleVolumeChange} />
         <div className="flex-1 grid overflow-hidden" style={{ gridTemplateColumns: '288px 1fr 320px' }}>
           <AgentRosterPanel
             assignments={assignments}

package/web/components/hud-header.tsx

@@ -9,6 +9,8 @@ interface HudHeaderProps {
   uiTheme: UITheme;
   onUiThemeChange: (theme: UITheme) => void;
   onConfigureUISounds: () => void;
+  masterVolume: number;
+  onVolumeChange: (v: number) => void;
 }
 
 const UI_THEMES: { value: UITheme; label: string }[] = [
@@ -19,7 +21,7 @@ const UI_THEMES: { value: UITheme; label: string }[] = [
   { value: 'off', label: 'OFF' },
 ];
 
-export function HudHeader({ enabled, onToggle, uiTheme, onUiThemeChange, onConfigureUISounds }: HudHeaderProps) {
+export function HudHeader({ enabled, onToggle, uiTheme, onUiThemeChange, onConfigureUISounds, masterVolume, onVolumeChange }: HudHeaderProps) {
   const [showDropdown, setShowDropdown] = useState(false);
   const activeLabel = UI_THEMES.find((t) => t.value === uiTheme)?.label ?? uiTheme.toUpperCase();
 
@@ -116,6 +118,26 @@ export function HudHeader({ enabled, onToggle, uiTheme, onUiThemeChange, onConfi
 
         <div className="h-4 w-px opacity-20" style={{ backgroundColor: 'var(--sf-cyan)' }} />
 
+        {/* Master volume */}
+        <div className="flex items-center gap-1.5">
+          <span className="text-[10px] tracking-widest uppercase opacity-40">VOL</span>
+          <input
+            type="range"
+            min={0}
+            max={100}
+            value={Math.round(masterVolume * 100)}
+            onChange={(e) => onVolumeChange(Number(e.target.value) / 100)}
+            data-no-ui-sound
+            className="w-16"
+            style={{ cursor: 'pointer', accentColor: 'var(--sf-cyan)', verticalAlign: 'middle' }}
+          />
+          <span className="text-[10px] w-7 text-right tabular-nums" style={{ color: 'var(--sf-cyan)', opacity: 0.7 }}>
+            {Math.round(masterVolume * 100)}%
+          </span>
+        </div>
+
+        <div className="h-4 w-px opacity-20" style={{ backgroundColor: 'var(--sf-cyan)' }} />
+
         {/* Master enable/disable */}
         <button
           onClick={onToggle}

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useMemo, useCallback } from 'react';
+import { useState, useMemo, useCallback, useEffect } from 'react';
 import { SoundUnit } from './sound-unit';
 import { groupSoundsByCategory, getGroupLabel, getSubTabLabel } from '@/lib/utils';
 import { playUISound } from '@/lib/ui-audio';
@@ -21,30 +21,53 @@ function internalCat(category: string): string {
   return idx === -1 ? category : category.slice(idx + 1);
 }
 
+// Extract pack ID: "publisher/name:sc2/terran" → "publisher/name"
+function packOfCat(category: string): string {
+  const idx = category.indexOf(':');
+  return idx === -1 ? '' : category.slice(0, idx);
+}
+
+// "publisher/name" → "name"
+function packShortName(packId: string): string {
+  return packId.split('/')[1] ?? packId;
+}
+
 export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode, onSelectModeAssign, onClearSelectMode }: SoundBrowserPanelProps) {
+  const [activePack, setActivePack] = useState<string | null>(null);
   const [activeGroup, setActiveGroup] = useState<string>('sc2');
   const [activeCategory, setActiveCategory] = useState<string>('sc2/terran');
   const [search, setSearch] = useState('');
 
-  const handleGroupChange = useCallback((group: string) => {
-    setActiveGroup(group);
-    playUISound('pageChange', 0.4);
-  }, []);
+  // All unique pack IDs present in the library
+  const allPacks = useMemo(() => {
+    return [...new Set(sounds.map((s) => packOfCat(s.category)))].filter(Boolean).sort();
+  }, [sounds]);
 
-  const handleCategoryChange = useCallback((cat: string) => {
-    setActiveCategory(cat);
-    playUISound('pageChange', 0.35);
-  }, []);
+  const showPackSelector = allPacks.length > 1;
+
+  // Sounds visible given the current pack filter
+  const visibleSounds = useMemo(() => {
+    if (!activePack) return sounds;
+    const prefix = activePack + ':';
+    return sounds.filter((s) => s.category.startsWith(prefix));
+  }, [sounds, activePack]);
 
   const allGroups = useMemo(() => {
-    return [...new Set(sounds.map((s) => internalCat(s.category).split('/')[0]))].sort();
-  }, [sounds]);
+    return [...new Set(visibleSounds.map((s) => internalCat(s.category).split('/')[0]))].sort();
+  }, [visibleSounds]);
+
+  // If activeGroup disappears after a pack switch, reset to the first available group
+  useEffect(() => {
+    if (allGroups.length > 0 && !allGroups.includes(activeGroup)) {
+      setActiveGroup(allGroups[0]);
+    }
+  }, [allGroups, activeGroup]);
 
   const groupCategories = useMemo(() => {
     return [...new Set(
-      sounds.filter((s) => internalCat(s.category).split('/')[0] === activeGroup).map((s) => s.category)
+      visibleSounds.filter((s) => internalCat(s.category).split('/')[0] === activeGroup).map((s) => s.category)
     )].sort();
-  }, [sounds, activeGroup]);
+  }, [visibleSounds, activeGroup]);
 
   // If activeCategory doesn't belong to current group, use first category of the group
   const effectiveCategory = groupCategories.includes(activeCategory)
@@ -64,21 +87,36 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
 
   const filteredSounds = useMemo(() => {
     if (isSearching) {
-      // Global search across all sounds
       const q = search.toLowerCase();
-      return sounds.filter((s) =>
+      return visibleSounds.filter((s) =>
         s.filename.toLowerCase().includes(q) ||
         s.category.toLowerCase().includes(q) ||
         s.subcategory.toLowerCase().includes(q)
       );
     }
-    // Normal tab-filtered view
-    return sounds.filter((s) => s.category === effectiveCategory);
-  }, [sounds, effectiveCategory, search, isSearching]);
+    return visibleSounds.filter((s) => s.category === effectiveCategory);
+  }, [visibleSounds, effectiveCategory, search, isSearching]);
 
   const grouped = useMemo(() => groupSoundsByCategory(filteredSounds), [filteredSounds]);
 
   const showSubTabs = !isSearching && groupCategories.length > 1;
+  // Show pack label on cards when browsing all packs and multiple packs are installed
+  const showPackBadge = showPackSelector && !activePack;
+
+  const handleGroupChange = useCallback((group: string) => {
+    setActiveGroup(group);
+    playUISound('pageChange', 0.4);
+  }, []);
+
+  const handleCategoryChange = useCallback((cat: string) => {
+    setActiveCategory(cat);
+    playUISound('pageChange', 0.35);
+  }, []);
+
+  const handlePackChange = useCallback((pack: string | null) => {
+    setActivePack(pack);
+    playUISound('pageChange', 0.4);
+  }, []);
 
   return (
     <div className="flex flex-col overflow-hidden" style={{ borderLeft: '1px solid var(--sf-border)', borderRight: '1px solid var(--sf-border)' }}>
@@ -103,6 +141,45 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
           }}
         />
 
+        {/* SOURCE pack selector — only shown when 2+ packs installed */}
+        {showPackSelector && (
+          <div
+            className="flex items-center gap-1 mt-2 overflow-x-auto"
+            style={{ opacity: isSearching ? 0.3 : 1, pointerEvents: isSearching ? 'none' : 'auto' }}
+          >
+            <span className="text-[9px] tracking-widest uppercase shrink-0" style={{ color: 'var(--sf-gold)', opacity: 0.6 }}>
+              SOURCE
+            </span>
+            <button
+              data-sf-hover
+              onClick={() => handlePackChange(null)}
+              className="shrink-0 px-2 py-0.5 text-[9px] sf-heading font-semibold uppercase tracking-wider transition-all"
+              style={{
+                border: `1px solid ${!activePack ? 'var(--sf-gold)' : 'rgba(255,192,0,0.2)'}`,
+                color: !activePack ? 'var(--sf-gold)' : 'rgba(255,192,0,0.45)',
+                backgroundColor: !activePack ? 'rgba(255,192,0,0.08)' : 'transparent',
+              }}
+            >
+              ALL
+            </button>
+            {allPacks.map((id) => (
+              <button
+                key={id}
+                data-sf-hover
+                onClick={() => handlePackChange(id)}
+                className="shrink-0 px-2 py-0.5 text-[9px] sf-heading font-semibold uppercase tracking-wider transition-all"
+                style={{
+                  border: `1px solid ${activePack === id ? 'var(--sf-gold)' : 'rgba(255,192,0,0.2)'}`,
+                  color: activePack === id ? 'var(--sf-gold)' : 'rgba(255,192,0,0.45)',
+                  backgroundColor: activePack === id ? 'rgba(255,192,0,0.08)' : 'transparent',
+                }}
+              >
+                {packShortName(id)}
+              </button>
+            ))}
+          </div>
+        )}
+
         {/* Group tabs */}
         <div className="flex gap-1 mt-2 overflow-x-auto" style={{ opacity: isSearching ? 0.3 : 1, pointerEvents: isSearching ? 'none' : 'auto' }}>
           {allGroups.map((group) => (
@@ -196,6 +273,7 @@ export function SoundBrowserPanel({ sounds, assignments, onPreview, selectMode,
                       isAssigned={assignedPaths.has(sound.path)}
                       onPreview={onPreview}
                       onSelectAssign={selectMode ? () => onSelectModeAssign(sound.path) : undefined}
+                      packLabel={showPackBadge ? packShortName(packOfCat(sound.category)) : undefined}
                     />
                   ))}
                 </div>

package/web/components/sound-unit.tsx

@@ -11,11 +11,12 @@ interface SoundUnitProps {
   onPreview: (path: string) => void;
   isOverlay?: boolean;
   onSelectAssign?: () => void; // if set, card click assigns instead of plays
+  packLabel?: string;          // shown when browsing multiple packs simultaneously
 }
 
 const BARS = 16;
 
-export function SoundUnit({ sound, isAssigned, onPreview, isOverlay, onSelectAssign }: SoundUnitProps) {
+export function SoundUnit({ sound, isAssigned, onPreview, isOverlay, onSelectAssign, packLabel }: SoundUnitProps) {
   const [isPlaying, setIsPlaying] = useState(false);
   const [isHovered, setIsHovered] = useState(false);
   const [bars, setBars] = useState<number[]>(sound.waveform.map(h => h / 10));
@@ -198,6 +199,11 @@ export function SoundUnit({ sound, isAssigned, onPreview, isOverlay, onSelectAss
           <span className="shrink-0 text-[9px] animate-pulse" style={{ color: 'var(--sf-cyan)' }}>♪</span>
         )}
       </div>
+      {packLabel && (
+        <span className="text-[8px] truncate leading-none" style={{ color: 'rgba(255,192,0,0.45)' }}>
+          {packLabel}
+        </span>
+      )}
     </div>
   );
 }

package/web/components/ui-sounds-modal.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useState, useEffect, useCallback, useMemo } from 'react';
 import { previewUISound } from '@/lib/ui-audio';
 import type { UITheme, UISlotMap } from '@/lib/types';
 
@@ -12,6 +12,8 @@ interface UISound {
 
 type SlotName = 'click' | 'hover' | 'error' | 'pageChange' | 'toggle' | 'confirm';
 
+const CANONICAL_SLOTS = new Set(['click', 'hover', 'error', 'pageChange', 'toggle', 'confirm']);
+
 const SLOTS: { name: SlotName; label: string; desc: string }[] = [
   { name: 'hover', label: 'HOVER', desc: 'Mouse over interactive element' },
   { name: 'click', label: 'CLICK', desc: 'Button or card clicked' },
@@ -30,8 +32,8 @@ interface Props {
 
 export function UISoundsModal({ uiTheme, uiSounds, onSave, onClose }: Props) {
   const [sounds, setSounds] = useState<UISound[]>([]);
-  const [activeTheme, setActiveTheme] = useState<UITheme>(uiTheme === 'off' ? 'sc2' : uiTheme);
-  const [slots, setSlots] = useState<UISlotMap>(uiSounds[uiTheme === 'off' ? 'sc2' : uiTheme] ?? {});
+  const [activeTheme, setActiveTheme] = useState<string>(uiTheme === 'off' ? '' : uiTheme);
+  const [slots, setSlots] = useState<UISlotMap>(uiSounds[uiTheme === 'off' ? '' : uiTheme] ?? {});
   const [activeSlot, setActiveSlot] = useState<SlotName>('hover');
   const [playing, setPlaying] = useState<string | null>(null);
 
@@ -39,8 +41,32 @@ export function UISoundsModal({ uiTheme, uiSounds, onSave, onClose }: Props) {
     fetch('/api/ui-sounds').then((r) => r.json()).then(setSounds).catch(console.error);
   }, []);
 
+  // Derive theme tabs: a ui/ subdir qualifies as a theme only if it contains
+  // at least one file whose basename matches a canonical slot name.
+  // Folders starting with '_' are always excluded (utility library escape hatch).
+  const themes = useMemo(() => {
+    const validGroups = new Set(
+      sounds
+        .filter((s) => {
+          const base = s.filename.replace(/\.(mp3|wav|ogg|m4a)$/i, '');
+          return CANONICAL_SLOTS.has(base);
+        })
+        .map((s) => s.group)
+    );
+    return [...validGroups].filter((t) => t && !t.startsWith('_')).sort();
+  }, [sounds]);
+
+  // When themes load, initialize activeTheme to first available if current isn't in list
+  useEffect(() => {
+    if (themes.length > 0 && activeTheme === '') {
+      const initial = themes[0];
+      setActiveTheme(initial);
+      setSlots(uiSounds[initial] ?? {});
+    }
+  }, [themes, activeTheme, uiSounds]);
+
   // When theme changes, load existing slot config for that theme
-  const switchTheme = useCallback((theme: UITheme) => {
+  const switchTheme = useCallback((theme: string) => {
     setActiveTheme(theme);
     setSlots(uiSounds[theme] ?? {});
   }, [uiSounds]);
@@ -110,14 +136,14 @@ export function UISoundsModal({ uiTheme, uiSounds, onSave, onClose }: Props) {
         </div>
 
         {/* Theme selector */}
-        <div className="flex items-center gap-2 px-5 py-2 shrink-0" style={{ borderBottom: '1px solid var(--sf-border)' }}>
-          <span className="text-[10px] tracking-widest uppercase opacity-40">THEME</span>
-          {(['sc2', 'wc3', 'ff7', 'ff9'] as const).map((t) => (
+        <div className="flex items-center gap-2 px-5 py-2 shrink-0 overflow-x-auto" style={{ borderBottom: '1px solid var(--sf-border)' }}>
+          <span className="text-[10px] tracking-widest uppercase opacity-40 shrink-0">THEME</span>
+          {themes.map((t) => (
             <button
               key={t}
               data-sf-hover
               onClick={() => switchTheme(t)}
-              className="px-3 py-0.5 text-[10px] sf-heading font-semibold uppercase tracking-wider transition-all"
+              className="shrink-0 px-3 py-0.5 text-[10px] sf-heading font-semibold uppercase tracking-wider transition-all"
               style={{
                 border: `1px solid ${activeTheme === t ? 'var(--sf-cyan)' : 'var(--sf-border)'}`,
                 color: activeTheme === t ? 'var(--sf-cyan)' : 'rgba(255,255,255,0.35)',

package/web/lib/types.ts

@@ -21,7 +21,7 @@ export interface SkillConfig {
   hooks: Partial<Record<SkillHookEvent, string>>;
 }
 
-export type UITheme = 'sc2' | 'wc3' | 'ff7' | 'ff9' | 'off';
+export type UITheme = string; // Dynamic: derives from installed pack ui/ directory names; 'off' disables UI sounds
 
 export interface SelectMode {
   scope: string;  // 'global' | agent-name | 'skill/qualifiedName'