agentcraft 0.0.3 → 0.0.4

package/.claude-plugin/plugin.json

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