agentcraft 0.0.1

package/.claude-plugin/plugin.json

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

@@ -0,0 +1,95 @@
+# AgentCraft
+
+Assign sounds to your AI coding agent's lifecycle events. Configure everything through an SC2-inspired dashboard — drag sounds onto hook slots, pick a UI theme, and hear your agents come alive.
+
+Works with **Claude Code** and **OpenCode**.
+
+![AgentCraft dashboard](screenshot.jpg)
+
+## How It Works
+
+**1. Run the skill**
+
+From any Claude Code session:
+
+```
+/agentcraft
+```
+
+**2. Sounds download automatically**
+
+On first launch, AgentCraft clones the [agentcraft-sounds](https://github.com/rohenaz/agentcraft-sounds) library to `~/.agentcraft/sounds/`. No manual setup required.
+
+**3. The dashboard opens at `http://localhost:4040`**
+
+A local web UI starts in the background. It stays running between sessions so subsequent `/agentcraft` calls open instantly.
+
+**4. Assign sounds to hook points and skill calls**
+
+- **AGENTS tab** — Expand **GLOBAL OVERRIDE** or any agent row. Click a hook slot (SESSION START, STOP, TOOL FAILURE, etc.) to enter select mode, then click any sound in the browser to assign it. Or drag a sound card directly onto a slot.
+- **SKILLS tab** — Assign sounds to individual skill invocations. Each skill has an **ON INVOKE** and **ON COMPLETE** slot.
+- Hit **ESTABLISH UPLINK** to save.
+
+From then on, Claude Code plays your sounds automatically as it works — no dashboard needed.
+
+## Install
+
+```bash
+claude plugin install agentcraft@rohenaz
+```
+
+## Prerequisites
+
+- [Bun](https://bun.sh) — runs the web UI
+- [jq](https://jqlang.github.io/jq/) — JSON parsing in the hook script
+- [git](https://git-scm.com) — downloads the sound library on first run
+- macOS: `afplay` (built in) · Linux: `paplay` or `aplay`
+
+## Hooks
+
+| Event | When it fires |
+|-------|--------------|
+| `SessionStart` | New session begins |
+| `SessionEnd` | Session ends |
+| `Stop` | Claude finishes a response |
+| `SubagentStop` | A subagent completes |
+| `Notification` | Claude sends a notification |
+| `PreCompact` | Context is about to be compacted |
+| `PreToolUse (Skill)` | A skill is invoked |
+| `PostToolUse (Skill)` | A skill completes |
+
+Sounds can be set globally (fires for all agents) or per-agent (overrides global for that agent).
+
+## UI Sound Themes
+
+The **UI SFX** dropdown in the header controls ambient sounds that play as you use the dashboard. Click **⚙** to customize individual slots per theme.
+
+| Theme | Style |
+|-------|-------|
+| SC2 | StarCraft II — crisp, digital |
+| WC3 | Warcraft III — warm, fantasy |
+| FF7 | Final Fantasy VII — retro RPG |
+| FF9 | Final Fantasy IX — soft, minimal |
+| OFF | No UI sounds |
+
+## Sound Library
+
+Sounds live at `~/.agentcraft/sounds/`. Any `.mp3`, `.wav`, `.ogg`, or `.m4a` file you drop there appears in the browser automatically. To update the library:
+
+```bash
+git -C ~/.agentcraft/sounds pull
+```
+
+## Storage
+
+| Path | Contents |
+|------|----------|
+| `~/.agentcraft/assignments.json` | Your sound assignments |
+| `~/.agentcraft/sounds/` | Sound library |
+
+## Managing the Plugin
+
+```bash
+claude plugin update agentcraft@rohenaz     # Update to latest
+claude plugin uninstall agentcraft@rohenaz  # Remove
+```

package/bin/agentcraft.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+// AgentCraft CLI — https://github.com/rohenaz/agentcraft
+// Full implementation coming in a future release.
+// Install the Claude Code plugin: claude plugin install agentcraft@rohenaz
+
+const [,, cmd, ...args] = process.argv;
+
+console.log('AgentCraft CLI v0.0.1');
+console.log('Full CLI coming soon. Install the Claude Code plugin:');
+console.log('  claude plugin install agentcraft@rohenaz');

package/commands/agentcraft.md

@@ -0,0 +1,46 @@
+---
+allowed-tools: Bash(lsof:*), Bash(open:*), Bash(bun:*), Bash(curl:*), Bash(git:*), Bash(ls:*), Bash(mkdir:*)
+description: Open the AgentCraft sound assignment dashboard. Launches web UI on port 4040.
+argument-hint: "[--stop] Stop the AgentCraft server"
+---
+
+Open the AgentCraft sound assignment dashboard.
+
+If user passed --stop argument, kill the server instead:
+```bash
+kill $(lsof -ti:4040) 2>/dev/null
+echo "AgentCraft server stopped."
+```
+
+Otherwise, ensure the sound library is present. Check if ~/.agentcraft/sounds exists and has files:
+```bash
+ls ~/.agentcraft/sounds 2>/dev/null | head -1
+```
+
+If that returned nothing (empty or missing), clone the sound library:
+```bash
+git clone https://github.com/rohenaz/agentcraft-sounds ~/.agentcraft/sounds
+```
+
+Check if server is already running:
+```bash
+lsof -ti:4040
+```
+
+If NOT running, start it:
+```bash
+cd "$CLAUDE_PLUGIN_ROOT/web" && bun install --silent && bun dev --port 4040 &
+```
+
+Poll until server responds (max 15 attempts, 1s apart):
+```bash
+for i in {1..15}; do
+  curl -s http://localhost:4040/api/health | grep -q '"ok"' && break
+  sleep 1
+done
+```
+
+Then open in browser:
+```bash
+open http://localhost:4040
+```

package/hooks/hooks.json

@@ -0,0 +1,13 @@
+{
+  "description": "AgentCraft: play sounds on Claude Code lifecycle events",
+  "hooks": {
+    "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 5 }] }],
+    "SessionEnd":   [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 5 }] }],
+    "Stop":         [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }],
+    "SubagentStop": [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }],
+    "Notification": [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }],
+    "PreCompact":   [{ "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }],
+    "PreToolUse":   [{ "matcher": "Skill", "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }],
+    "PostToolUse":  [{ "matcher": "Skill", "hooks": [{ "type": "command", "command": "bash $CLAUDE_PLUGIN_ROOT/hooks/play-sound.sh", "timeout": 3 }] }]
+  }
+}

package/hooks/play-sound.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# AgentCraft hook - plays assigned sound for this event/agent/skill
+CONFIG="$HOME/.agentcraft/assignments.json"
+LIBRARY="$HOME/.agentcraft/sounds"
+
+# Read stdin with 2s timeout. 'timeout' isn't available by default on macOS,
+# so use perl's alarm() which is always present.
+INPUT=$(perl -e '$SIG{ALRM}=sub{exit 0}; alarm 2; local $/; $d=<STDIN>; print $d if $d' 2>/dev/null)
+[ -z "$INPUT" ] && INPUT='{}'
+EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
+AGENT=$(echo "$INPUT" | jq -r '.agent_type // empty')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty')
+
+[ -z "$EVENT" ] && exit 0
+[ ! -f "$CONFIG" ] && exit 0
+
+ENABLED=$(jq -r '.settings.enabled // true' "$CONFIG")
+[ "$ENABLED" = "false" ] && exit 0
+
+# 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"
+NOW=$(date +%s)
+if [ -f "$LOCKFILE" ]; then
+  LAST=$(cat "$LOCKFILE" 2>/dev/null || echo 0)
+  if [ $((NOW - LAST)) -lt 3 ]; then
+    exit 0
+  fi
+fi
+echo "$NOW" > "$LOCKFILE"
+
+SOUND=""
+
+# Skill-specific lookup: PreToolUse/PostToolUse when tool_name=Skill
+# tool_input.skill is the qualified name, e.g. "plugin-dev:hook-development" or "ask-gemini"
+if [ "$TOOL_NAME" = "Skill" ]; then
+  SKILL_KEY=$(echo "$INPUT" | jq -r '.tool_input.skill // empty')
+  if [ -n "$SKILL_KEY" ]; then
+    SKILL_ENABLED=$(jq -r --arg s "$SKILL_KEY" '.skills[$s].enabled // true' "$CONFIG")
+    if [ "$SKILL_ENABLED" = "true" ]; then
+      SOUND=$(jq -r --arg s "$SKILL_KEY" --arg e "$EVENT" '.skills[$s].hooks[$e] // empty' "$CONFIG")
+    fi
+  fi
+fi
+
+# Agent-specific lookup
+if [ -z "$SOUND" ] && [ -n "$AGENT" ]; then
+  AGENT_ENABLED=$(jq -r --arg a "$AGENT" '.agents[$a].enabled // true' "$CONFIG")
+  if [ "$AGENT_ENABLED" = "true" ]; then
+    SOUND=$(jq -r --arg a "$AGENT" --arg e "$EVENT" '.agents[$a].hooks[$e] // empty' "$CONFIG")
+  fi
+fi
+
+# Global fallback
+[ -z "$SOUND" ] && SOUND=$(jq -r --arg e "$EVENT" '.global[$e] // empty' "$CONFIG")
+[ -z "$SOUND" ] && exit 0
+
+FULL="$LIBRARY/$SOUND"
+[ ! -f "$FULL" ] && exit 0
+
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  afplay "$FULL" &
+elif command -v paplay &>/dev/null; then
+  paplay "$FULL" &
+elif command -v aplay &>/dev/null; then
+  aplay "$FULL" &
+fi
+
+exit 0

package/opencode.js

@@ -0,0 +1,87 @@
+/**
+ * AgentCraft — OpenCode plugin
+ *
+ * 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
+ *
+ * To install for OpenCode, symlink or copy this file to:
+ *   ~/.config/opencode/plugins/agentcraft.js   (global)
+ *   .opencode/plugins/agentcraft.js             (project)
+ */
+
+import { readFileSync, existsSync } from 'fs';
+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');
+
+function getAssignments() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function play(soundPath) {
+  if (!soundPath) return;
+  const full = join(LIBRARY_PATH, soundPath);
+  if (!existsSync(full)) return;
+  try {
+    if (process.platform === 'darwin') execSync(`afplay "${full}" &`, { stdio: 'ignore' });
+    else if (process.platform === 'linux') execSync(`paplay "${full}" &`, { stdio: 'ignore' });
+  } catch { /* non-blocking, ignore errors */ }
+}
+
+function playEvent(a, event) {
+  if (!a || a.settings?.enabled === false) return;
+  play(a.global?.[event]);
+}
+
+export const AgentCraft = async () => {
+  return {
+    // Session start → SessionStart
+    'session.created': async () => {
+      playEvent(getAssignments(), 'SessionStart');
+    },
+
+    // Agent idle/done → Stop
+    'session.idle': async () => {
+      playEvent(getAssignments(), 'Stop');
+    },
+
+    // Context compacted → PreCompact
+    'session.compacted': async () => {
+      playEvent(getAssignments(), 'PreCompact');
+    },
+
+    // Tool about to run → PreToolUse (skills only)
+    '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;
+        const cfg = a.skills?.[key];
+        if (cfg && cfg.enabled !== false) play(cfg.hooks?.PreToolUse);
+      }
+    },
+
+    // Tool finished → PostToolUse (skills only)
+    '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;
+        const cfg = a.skills?.[key];
+        if (cfg && cfg.enabled !== false) play(cfg.hooks?.PostToolUse);
+      }
+    },
+  };
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "agentcraft",
+  "version": "0.0.1",
+  "description": "Assign sounds to AI coding agent lifecycle events. CLI for managing sound packs.",
+  "license": "MIT",
+  "author": "rohenaz",
+  "bin": {
+    "agentcraft": "./bin/agentcraft.js"
+  },
+  "keywords": ["claude-code", "opencode", "sounds", "hooks", "audio", "agents", "ai"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rohenaz/agentcraft"
+  },
+  "homepage": "https://github.com/rohenaz/agentcraft#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/web/README.md

@@ -0,0 +1,36 @@
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

package/web/app/api/agents/[name]/route.ts

@@ -0,0 +1,44 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { writeFile, unlink } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const AGENTS_DIR = join(homedir(), '.claude', 'agents');
+
+function buildAgentContent(data: { name: string; description: string; model: string; tools: string; color: string; prompt: string }): string {
+  const lines = ['---', `name: ${data.name}`, `description: ${data.description}`, `model: ${data.model}`];
+  if (data.tools) lines.push(`tools: ${data.tools}`);
+  if (data.color) lines.push(`color: ${data.color}`);
+  lines.push('---', '', data.prompt || '');
+  return lines.join('\n');
+}
+
+export async function PUT(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> }
+) {
+  try {
+    const { name } = await params;
+    const data = await req.json();
+    const filename = `${name}.md`;
+    const content = buildAgentContent(data);
+    await writeFile(join(AGENTS_DIR, filename), content, 'utf-8');
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Failed to update agent' }, { status: 500 });
+  }
+}
+
+export async function DELETE(
+  req: NextRequest,
+  { params }: { params: Promise<{ name: string }> }
+) {
+  try {
+    const { name } = await params;
+    const filename = `${name}.md`;
+    await unlink(join(AGENTS_DIR, filename));
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Failed to delete agent' }, { status: 500 });
+  }
+}

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

@@ -0,0 +1,62 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readdir, readFile, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { AgentInfo } from '@/lib/types';
+
+const AGENTS_DIR = join(homedir(), '.claude', 'agents');
+
+function buildAgentContent(data: { name: string; description: string; model: string; tools: string; color: string; prompt: string }): string {
+  const lines = ['---', `name: ${data.name}`, `description: ${data.description}`, `model: ${data.model}`];
+  if (data.tools) lines.push(`tools: ${data.tools}`);
+  if (data.color) lines.push(`color: ${data.color}`);
+  lines.push('---', '', data.prompt || '');
+  return lines.join('\n');
+}
+
+export async function GET() {
+  try {
+    const files = await readdir(AGENTS_DIR);
+    const agents: AgentInfo[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith('.md')) continue;
+      const content = await readFile(join(AGENTS_DIR, file), 'utf-8');
+      const nameMatch = content.match(/^name:\s*(.+)$/m);
+      const descMatch = content.match(/^description:\s*(.+)$/m);
+      const modelMatch = content.match(/^model:\s*(.+)$/m);
+      const toolsMatch = content.match(/^tools:\s*(.+)$/m);
+      const colorMatch = content.match(/^color:\s*(.+)$/m);
+      const promptMatch = content.match(/^---\s*\n(?:.*\n)*?---\s*\n([\s\S]*)$/);
+      const name = nameMatch ? nameMatch[1].trim() : file.replace('.md', '');
+      agents.push({
+        name,
+        filename: file,
+        description: descMatch ? descMatch[1].trim() : '',
+        model: modelMatch ? modelMatch[1].trim() : 'sonnet',
+        tools: toolsMatch ? toolsMatch[1].trim() : '',
+        color: colorMatch ? colorMatch[1].trim() : '',
+        prompt: promptMatch ? promptMatch[1].trim() : '',
+      });
+    }
+
+    return NextResponse.json(agents);
+  } catch {
+    return NextResponse.json([]);
+  }
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const data = await req.json();
+    if (!data.name || typeof data.name !== 'string') {
+      return NextResponse.json({ error: 'name required' }, { status: 400 });
+    }
+    const filename = `${data.name.toLowerCase().replace(/\s+/g, '-')}.md`;
+    const content = buildAgentContent(data);
+    await writeFile(join(AGENTS_DIR, filename), content, 'utf-8');
+    return NextResponse.json({ ok: true, filename });
+  } catch {
+    return NextResponse.json({ error: 'Failed to create agent' }, { status: 500 });
+  }
+}

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

@@ -0,0 +1,53 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+const ASSIGNMENTS_PATH = join(homedir(), '.agentcraft', 'assignments.json');
+
+export async function GET() {
+  try {
+    const data = await readFile(ASSIGNMENTS_PATH, 'utf-8');
+    const parsed = JSON.parse(data);
+    // Ensure required keys exist for older assignment files
+    if (!parsed.skills) parsed.skills = {};
+    if (!parsed.settings) parsed.settings = {};
+    if (!parsed.settings.uiTheme) parsed.settings.uiTheme = 'sc2';
+    return NextResponse.json(parsed);
+  } catch {
+    return NextResponse.json({
+      global: {},
+      agents: {},
+      skills: {},
+      settings: {
+        masterVolume: 1.0,
+        enabled: true,
+        theme: 'terran',
+        uiTheme: 'sc2',
+        uiSounds: {
+          sc2: {
+            hover: 'ui/sc-bigbox/set2-move.mp3',
+            click: 'ui/sc2/click.mp3',
+            error: 'ui/sc2/error.mp3',
+          },
+          wc3: {
+            hover: 'ui/wc3/hover.mp3',
+            click: 'ui/wc3/click.mp3',
+            error: 'ui/wc3/error.mp3',
+          },
+        },
+      },
+    });
+  }
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    const body = await req.json();
+    await mkdir(dirname(ASSIGNMENTS_PATH), { recursive: true });
+    await writeFile(ASSIGNMENTS_PATH, JSON.stringify(body, null, 2), 'utf-8');
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Failed to write assignments' }, { status: 500 });
+  }
+}

package/web/app/api/audio/[...path]/route.ts

@@ -0,0 +1,35 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const SOUND_LIBRARY = join(homedir(), '.agentcraft', 'sounds');
+
+export async function GET(
+  req: NextRequest,
+  { params }: { params: Promise<{ path: string[] }> }
+) {
+  try {
+    const { path: pathParts } = await params;
+    const relativePath = pathParts.join('/');
+
+    if (relativePath.includes('..')) {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+
+    const fullPath = join(SOUND_LIBRARY, relativePath);
+    const data = await readFile(fullPath);
+
+    const ext = relativePath.split('.').pop()?.toLowerCase();
+    const contentType = ext === 'mp3' ? 'audio/mpeg' : ext === 'wav' ? 'audio/wav' : 'audio/mpeg';
+
+    return new NextResponse(data, {
+      headers: {
+        'Content-Type': contentType,
+        'Cache-Control': 'public, max-age=86400',
+      },
+    });
+  } catch {
+    return NextResponse.json({ error: 'Audio file not found' }, { status: 404 });
+  }
+}

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

@@ -0,0 +1,5 @@
+import { NextResponse } from 'next/server';
+
+export async function GET() {
+  return NextResponse.json({ status: 'ok', version: '1.0.0' });
+}

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

@@ -0,0 +1,22 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { spawn } from 'child_process';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const SOUND_LIBRARY = join(homedir(), '.agentcraft', 'sounds');
+
+export async function POST(req: NextRequest) {
+  try {
+    const { path } = await req.json();
+    if (!path || typeof path !== 'string' || path.includes('..')) {
+      return NextResponse.json({ error: 'Invalid path' }, { status: 400 });
+    }
+
+    const fullPath = join(SOUND_LIBRARY, path);
+    spawn('afplay', [fullPath], { detached: true, stdio: 'ignore' }).unref();
+
+    return NextResponse.json({ ok: true });
+  } catch {
+    return NextResponse.json({ error: 'Playback failed' }, { status: 500 });
+  }
+}