agentcraft 0.0.4 → 0.0.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.1.2",
+  "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/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,7 +2,7 @@
 'use strict';
 
 const { execSync, spawnSync } = require('child_process');
-const { existsSync, readdirSync, rmSync, statSync, mkdirSync, readFileSync, copyFileSync, realpathSync } = require('fs');
+const { existsSync, readdirSync, rmSync, statSync, mkdirSync, readFileSync, writeFileSync, copyFileSync, realpathSync } = require('fs');
 const { join, dirname } = require('path');
 const { homedir } = require('os');
 
@@ -139,6 +139,105 @@ function packInit() {
   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');
@@ -157,12 +256,13 @@ function showHelp() {
 ${c.bold('AgentCraft')} — assign sounds to AI agent lifecycle events
 
 ${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 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
 
 ${c.cyan('Examples:')}
   agentcraft init
@@ -170,6 +270,7 @@ ${c.cyan('Examples:')}
   agentcraft add publisher/custom-pack
   agentcraft update
   agentcraft list
+  agentcraft create-pack my-sounds
 
 ${c.dim('Packs are stored at: ~/.agentcraft/packs/<publisher>/<name>/')}
 ${c.dim('Any git repo cloned there is automatically discovered by the dashboard.')}
@@ -208,6 +309,8 @@ if (cmd === 'init') {
   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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcraft",
-  "version": "0.0.4",
+  "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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -19,6 +19,7 @@ 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/`.
@@ -71,6 +72,14 @@ The hook script resolves this to the absolute path at runtime:
 
 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:
@@ -122,7 +131,7 @@ The registry GitHub Action runs every 6 hours and automatically picks up newly t
 ### Step 4: Share the install command
 
 ```bash
-agentcraft pack install your-username/your-repo-name
+agentcraft add your-username/your-repo-name
 ```
 
 That's the entire publish workflow — push to GitHub, tag it, done.

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'