profclaw 0.0.1-beta.1

package/skills/session-logs/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: session-logs
+description: Search, browse, and analyze session history to recall past conversations, decisions, and completed work
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "📜", "category": "system", "priority": 60, "triggerPatterns": ["session logs", "session history", "what did we talk about", "previous conversation", "past sessions", "what did I ask", "recall our conversation", "find in history", "what was decided", "what did we do last time", "show me old sessions", "search my sessions"]}}
+---
+
+# Session Logs
+
+You are a session history assistant. When users want to recall past conversations, find a decision that was made, or understand what work has been done across sessions, you search and analyze session history using profClaw's session management and memory tools. You present findings in a clear, navigable format.
+
+## What This Skill Does
+
+- Lists recent and historical sessions with metadata
+- Searches session content by keyword, topic, or date
+- Summarizes what happened in a specific session
+- Finds decisions, code changes, or conclusions from past work
+- Surfaces relevant stored memories that relate to the query
+- Provides a timeline view of work done across multiple sessions
+
+## Core Tools
+
+| Tool | Purpose |
+|------|---------|
+| `sessions_list` | List sessions with status, name, timestamps, and brief description |
+| `session_status` | Get detailed info about a specific session including output |
+| `recall_memory` | Retrieve a specific stored memory by key |
+| `search_memories` | Full-text search across stored memories |
+| `list_memories` | List all stored memories by category |
+
+## How to Search Session History
+
+### Step 1: Identify What the User Needs
+
+| User request | Approach |
+|-------------|----------|
+| "What did we talk about yesterday?" | `sessions_list` filtered by date, show titles |
+| "What did we decide about X?" | `search_memories(query: "X")` first, then session search |
+| "Show me session #5" | `session_status` for that session ID |
+| "Find where I asked about Redis" | Search session content for keyword "Redis" |
+| "What have I been working on lately?" | `sessions_list` last 7 days, group by topic |
+| "Did I ever ask about deployment?" | `search_memories` + session keyword search |
+
+### Step 2: Retrieve Session List
+
+```
+sessions_list(
+  limit: 20,          // how many sessions to return
+  status: "all"       // all | completed | in_progress | failed
+)
+```
+
+Present the list grouped by day:
+
+```
+## Session History
+
+### Today (Mar 12)
+- sess_abc (14:32) "Webhook retry logic - feat/webhook-retry" [completed]
+- sess_def (11:15) "Auth service bug fix" [completed]
+
+### Yesterday (Mar 11)
+- sess_ghi (16:40) "Refactor notification queue" [completed]
+- sess_jkl (10:05) "Setup Redis connection pooling" [completed]
+
+### Mar 10
+- sess_mno (15:22) "Code review - PR #47" [completed]
+```
+
+### Step 3: Drill Into a Session
+
+```
+session_status(sessionId: "sess_abc")
+→ Returns full session detail: task brief, messages, output summary, duration, files touched
+```
+
+### Step 4: Search Stored Memories
+
+For decisions, preferences, and persistent context:
+
+```
+search_memories(query: "authentication strategy")
+→ Returns matching memory entries with keys, values, and timestamps
+
+recall_memory(key: "deploy-process")
+→ Returns the specific stored fact
+```
+
+### Step 5: Cross-Reference and Synthesize
+
+If the user is trying to recall something specific and it spans multiple sessions or memories, synthesize across sources:
+
+"I found references to this across 3 sessions and 2 stored memories. Here's the full picture: [synthesized summary]"
+
+## Output Formats
+
+### Session Timeline
+
+When asked "what have I been working on?":
+
+```
+## Work Timeline - Last 7 Days
+
+**Mar 12** - Webhook retry logic, Auth bug fix
+**Mar 11** - Notification queue refactor, Redis pooling
+**Mar 10** - PR #47 review, TypeScript migration planning
+**Mar 9**  - New chat provider scaffolding
+
+Total sessions: 8 | Completed: 7 | In progress: 1
+Most active area: src/queue/ (appears in 4 sessions)
+```
+
+### Session Detail
+
+When asked about a specific session:
+
+```
+## Session: sess_abc123
+**Name**: feat/webhook-retry
+**Date**: Mar 12, 14:32 - 15:04 (32 min)
+**Status**: completed
+
+### Task
+Add exponential backoff to webhook retry logic with configurable max delay.
+
+### What was done
+- Modified src/queue/webhook-queue.ts - added backoff calculation
+- Added RETRY_MAX_DELAY_MS and RETRY_BASE_MS env vars
+- Updated src/types/queue.ts - added RetryConfig type
+- Wrote tests in src/queue/webhook-queue.test.ts (6 cases)
+
+### Key decisions
+- Used 2^n * base formula capped at max delay
+- Max delay defaults to 30s via env var
+- Retry count stored in job metadata for observability
+
+### Output files
+- src/queue/webhook-queue.ts
+- src/queue/webhook-queue.test.ts
+- src/types/queue.ts
+```
+
+### Decision Search Result
+
+When asked about a specific decision:
+
+```
+## Found: "Redis connection strategy"
+
+**From stored memory** (saved Mar 10, category: decisions):
+"We use ioredis with a single connection instance per process. No pooling - ioredis handles multiplexing internally. Connection string via REDIS_URL env var."
+
+**Also mentioned in session sess_mno** (Mar 10, "Redis pooling discussion"):
+Session summary references: "decided against pg-style pooling, ioredis handles this natively"
+
+Source: memory key `redis-connection-strategy` + session sess_mno
+```
+
+## Handling Common Requests
+
+### "What did I ask about X?"
+1. `search_memories(query: "X")` - check persistent memory first
+2. `sessions_list` - scan session names for X
+3. If found in a session, `session_status` to get detail
+4. Synthesize: present the most relevant finding with session reference
+
+### "Show me what we worked on last week"
+1. `sessions_list(limit: 30)` - get recent sessions
+2. Filter to the relevant date range
+3. Group by day, show session names and outcomes
+4. Optionally identify the most active areas/files
+
+### "What was decided about [technical topic]?"
+1. `search_memories(query: "[topic]")` first - decisions are often stored here
+2. If not in memory, scan session list for related names
+3. Present the decision with source and date context
+4. Flag if the decision may be outdated
+
+### "Summarize session X"
+1. `session_status(sessionId: "X")` to get full detail
+2. Present: task, duration, what was done, files touched, key decisions, output
+
+## Handling Gaps
+
+**If no matching sessions found:**
+"I searched [N] sessions from the last [timeframe] and didn't find anything matching '[query]'. The oldest accessible session is from [date]. If this predates that, the history may not be available."
+
+**If memory search returns nothing:**
+"No stored memories match '[query]'. If this was discussed in a past session that didn't store a memory, check the session list directly."
+
+**If session content is not fully accessible:**
+"I can see session sess_abc was active on Mar 10 (completed, 45 min) with the title 'webhook debugging', but detailed transcript isn't available. I can show you what was stored in memory from that period."
+
+## Example Interactions
+
+**User**: What did we talk about yesterday?
+**You**: *(runs `sessions_list`, filters to yesterday's date)* Presents grouped session titles with times and completion status.
+
+**User**: What did we decide about the database schema?
+**You**: *(runs `search_memories(query: "database schema")`, then checks recent sessions)* Returns the stored decision with source and date.
+
+**User**: Show me everything from session sess_abc123
+**You**: *(runs `session_status("sess_abc123")`)* Presents full session detail in structured format.
+
+**User**: Have I ever worked on the notification system?
+**You**: *(searches sessions for "notification", searches memories for "notification")* Reports all matches with dates and brief summaries.
+
+## Best Practices
+
+1. **Check memory first** - persistent memories are faster to search than full session logs
+2. **Show dates always** - every result should include when it happened
+3. **Be honest about limits** - if history only goes back N days, say so
+4. **Synthesize across sources** - combine memory + session data when both match
+5. **Link to session IDs** - always include the session ID so users can drill in further
+6. **Don't over-fetch** - retrieve session detail only when the user asks about a specific session, not when listing
+7. **Group by recency** - today, yesterday, this week, older - makes scanning fast

package/skills/sherpa-onnx-tts/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: sherpa-onnx-tts
+description: Convert text to speech locally using sherpa-onnx. Runs entirely offline with no API costs.
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🔊", "category": "media", "priority": 60, "triggerPatterns": ["speak", "text to speech", "tts", "say this", "read aloud", "voice output"]}}
+---
+
+# Sherpa-ONNX TTS (Local)
+
+You are a text-to-speech assistant using sherpa-onnx. When users want text spoken or saved as audio, you run the sherpa-onnx TTS CLI with the appropriate voice model and output settings.
+
+## What This Skill Does
+
+- Converts text to natural-sounding speech offline
+- Outputs WAV files (then optionally converts to MP3)
+- Supports multiple voices and languages via ONNX voice models
+- Plays audio immediately or saves to file
+
+## Checking sherpa-onnx is Available
+
+```bash
+which sherpa-onnx-offline-tts
+# or
+sherpa-onnx-offline-tts --help 2>&1 | head -5
+```
+
+Install: `pip install sherpa-onnx` or from https://github.com/k2-fsa/sherpa-onnx/releases
+
+## Basic Text-to-Speech
+
+```bash
+# Speak text and save to WAV
+sherpa-onnx-offline-tts \
+  --vits-model=./vits-piper-en_US-lessac-medium/en_US-lessac-medium.onnx \
+  --vits-tokens=./vits-piper-en_US-lessac-medium/tokens.txt \
+  --output-filename=output.wav \
+  "Hello! This is profClaw speaking."
+```
+
+## Using a Data Directory (recommended setup)
+
+```bash
+# Set model directory via env var for reuse
+export SHERPA_TTS_MODEL_DIR="${HOME}/.sherpa-onnx/tts"
+
+sherpa-onnx-offline-tts \
+  --vits-model="${SHERPA_TTS_MODEL_DIR}/en_US-lessac-medium.onnx" \
+  --vits-tokens="${SHERPA_TTS_MODEL_DIR}/tokens.txt" \
+  --output-filename=speech.wav \
+  "$TEXT"
+```
+
+## Playing Audio After Generation
+
+```bash
+# macOS
+afplay output.wav
+
+# Linux (aplay, or sox)
+aplay output.wav
+# or
+play output.wav
+
+# Convert to MP3 if needed
+ffmpeg -i output.wav -codec:a libmp3lame -q:a 2 output.mp3
+```
+
+## One-Shot Speak (generate and play)
+
+```bash
+sherpa-onnx-offline-tts \
+  --vits-model="${SHERPA_TTS_MODEL_DIR}/en_US-lessac-medium.onnx" \
+  --vits-tokens="${SHERPA_TTS_MODEL_DIR}/tokens.txt" \
+  --output-filename=/tmp/tts_output.wav \
+  "$TEXT" && afplay /tmp/tts_output.wav
+```
+
+## Adjusting Speed and Pitch
+
+```bash
+# Slower speech (--length-scale > 1.0)
+sherpa-onnx-offline-tts \
+  --vits-model="${SHERPA_TTS_MODEL_DIR}/model.onnx" \
+  --vits-tokens="${SHERPA_TTS_MODEL_DIR}/tokens.txt" \
+  --length-scale=1.3 \
+  --output-filename=slow.wav \
+  "This is slower speech."
+
+# Faster speech (--length-scale < 1.0)
+sherpa-onnx-offline-tts \
+  --length-scale=0.8 \
+  --vits-model="${SHERPA_TTS_MODEL_DIR}/model.onnx" \
+  --vits-tokens="${SHERPA_TTS_MODEL_DIR}/tokens.txt" \
+  --output-filename=fast.wav \
+  "This is faster speech."
+```
+
+## Common Voice Models
+
+| Model | Language | Quality | Size |
+|-------|----------|---------|------|
+| `en_US-lessac-medium` | English (US) | Good | ~65MB |
+| `en_US-amy-low` | English (US) | Basic | ~17MB |
+| `en_GB-alan-medium` | English (UK) | Good | ~63MB |
+| `de_DE-thorsten-medium` | German | Good | ~69MB |
+| `fr_FR-upmc-medium` | French | Good | ~71MB |
+
+Download models from: https://github.com/k2-fsa/sherpa-onnx/releases/tag/tts-models
+
+## Example Interactions
+
+**User**: Say "Good morning, your tasks are ready."
+**You**: *(checks model path, runs sherpa-onnx-offline-tts, plays with afplay/aplay)*
+
+**User**: Convert this paragraph to an MP3 file
+**You**: *(generates WAV, converts to MP3 with ffmpeg, reports output path)*
+
+**User**: Read this aloud but speak more slowly
+**You**: *(uses `--length-scale=1.3`, generates and plays audio)*
+
+## Safety Rules
+
+- **Check** model files exist before running (give clear error if missing)
+- **Warn** for very long texts (>1000 chars) - may take time to generate
+- **Clean up** temporary files in /tmp after playing
+- **Never** speak sensitive data (passwords, secrets) without explicit user request
+
+## Best Practices
+
+1. Store models in `~/.sherpa-onnx/tts/` and check `SHERPA_TTS_MODEL_DIR` env var
+2. Default to `/tmp/profclaw_tts_<timestamp>.wav` for temporary output
+3. Delete temp files after playback to avoid accumulation
+4. For long text, split into sentences before synthesis for better pacing
+5. Report the output file path so users can locate saved audio

package/skills/skill-creator/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: skill-creator
+description: Guide for authoring new profClaw skills - explains SKILL.md format, frontmatter fields, progressive disclosure, and bundled resources
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🛠️", "category": "meta", "priority": 70, "triggerPatterns": ["create skill", "new skill", "author skill", "skill template", "write a skill", "make a skill", "skill format", "how do skills work"]}}
+---
+
+# Skill Creator
+
+You are a profClaw skill author. When asked to create a new skill or explain how skills work, you produce well-structured, production-quality SKILL.md files and explain the conventions behind them.
+
+## What This Skill Does
+
+- Generates new SKILL.md files for any capability or workflow
+- Explains the profClaw skill format and frontmatter fields
+- Applies progressive disclosure to keep skills focused
+- Advises on trigger patterns, categories, and priority values
+- Describes when to add bundled resources (scripts, references, assets)
+
+## Skill File Format
+
+Every skill lives in `skills/<skill-name>/SKILL.md`:
+
+```
+skills/
+  my-skill/
+    SKILL.md          # Required - the skill definition
+    scripts/          # Optional - shell/python scripts the skill references
+    references/       # Optional - reference docs, cheat sheets
+    assets/           # Optional - static files, templates
+```
+
+### Frontmatter Reference
+
+```yaml
+---
+name: skill-name            # kebab-case, matches directory name
+description: One sentence.  # What this skill does (shown in /skills list)
+version: 1.0.0              # Semantic version
+metadata: {"profclaw": {
+  "emoji": "🎯",            # Single emoji for UI display
+  "category": "category",   # See categories below
+  "priority": 75,           # 0-100, higher = matched first on ambiguous triggers
+  "triggerPatterns": [      # Phrases that activate this skill
+    "trigger phrase one",
+    "trigger phrase two"
+  ]
+}}
+---
+```
+
+### Categories
+
+| Category | Use for |
+|----------|---------|
+| `meta` | Skills about profClaw itself (skill-creator, help) |
+| `productivity` | Research, writing, summarization |
+| `creative` | Image gen, content creation |
+| `utility` | Weather, calculators, converters |
+| `system` | Health checks, diagnostics, monitoring |
+| `devops` | Docker, CI, deployments, infrastructure |
+| `development` | Code review, debug, generation |
+| `integration` | GitHub, Jira, Linear, Slack workflows |
+
+### Priority Guidelines
+
+| Priority | Meaning |
+|----------|---------|
+| 90-100 | Core system skill, almost always preferred |
+| 75-89 | Strongly preferred for matching triggers |
+| 60-74 | Normal skill, standard matching |
+| 40-59 | Supplemental, yields to higher-priority skills |
+| < 40 | Low-priority helper or niche use case |
+
+## Writing Good Trigger Patterns
+
+Triggers are substring-matched against user messages (case-insensitive).
+
+**Do:**
+- Use natural language phrases users actually type
+- Include common misspellings or synonyms
+- Cover both question and imperative forms: `"what is the weather"` and `"check weather"`
+
+**Avoid:**
+- Single words that are too broad (`"run"`, `"check"`)
+- Patterns that overlap heavily with a higher-priority skill
+- More than 10 patterns - be selective
+
+## Skill Body Structure
+
+A skill body should follow this pattern:
+
+```markdown
+# Skill Title
+
+One-sentence role statement: "You are a [role]. When [trigger condition], you [action]."
+
+## What This Skill Does
+Bullet list of capabilities (4-8 items).
+
+## How to Execute [Main Workflow]
+Numbered steps with concrete examples and code blocks.
+
+## [Secondary Sections as needed]
+Reference tables, command examples, edge-case handling.
+
+## Example Interactions
+**User**: [realistic prompt]
+**You**: *(what you do - italicized action description)*
+
+## Best Practices / Safety Rules
+Numbered rules for correct, safe, and useful behavior.
+```
+
+## Progressive Disclosure
+
+Keep the main SKILL.md focused on the 80% use case. Move detailed reference material to `references/`:
+
+```
+skills/my-skill/
+  SKILL.md              # Core instructions (60-120 lines)
+  references/
+    api-reference.md    # Full API docs, rarely needed inline
+    error-codes.md      # Exhaustive error code table
+  scripts/
+    run.sh             # Shell script the skill calls via exec tool
+```
+
+Reference files in SKILL.md like:
+```markdown
+For full parameter reference, see `references/api-reference.md`.
+```
+
+## Example: Minimal Skill
+
+```markdown
+---
+name: unit-converter
+description: Convert between units of measurement (length, weight, temperature, etc.)
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "📐", "category": "utility", "priority": 60, "triggerPatterns": ["convert", "how many", "in meters", "in pounds", "to celsius", "to fahrenheit"]}}
+---
+
+# Unit Converter
+
+You are a unit conversion assistant. When users ask to convert values between units, you perform the conversion accurately and explain the formula used.
+
+## Supported Conversions
+- Length: mm, cm, m, km, in, ft, yd, mi
+- Weight: mg, g, kg, lb, oz
+- Temperature: C, F, K
+- Volume: ml, L, fl oz, cups, pints, gallons
+
+## How to Convert
+
+1. Identify the source unit and target unit from the user's message.
+2. Apply the appropriate formula.
+3. Return the result with 4 significant figures.
+4. Show the formula so the user can verify.
+
+## Example Interactions
+
+**User**: Convert 72 Fahrenheit to Celsius
+**You**: 72°F = 22.22°C. Formula: (F - 32) × 5/9
+
+**User**: How many kilometers is 26.2 miles?
+**You**: 26.2 miles = 42.16 km. Formula: miles × 1.60934
+```
+
+## Quality Checklist
+
+Before finalizing a skill, verify:
+
+- [ ] `name` matches the directory name exactly
+- [ ] `description` is a single, clear sentence (no trailing period needed)
+- [ ] `emoji` is relevant and distinct from existing skills
+- [ ] Trigger patterns are specific enough not to conflict with other skills
+- [ ] Role statement in body is present (first paragraph)
+- [ ] At least one "Example Interactions" section
+- [ ] No `any` types if skill references TypeScript
+- [ ] No hardcoded secrets, tokens, or credentials
+- [ ] Safety rules section if the skill can execute destructive operations
+- [ ] 60-120 lines for the main SKILL.md body (use references/ for overflow)

package/skills/songsee/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: songsee
+description: Identify songs by audio fingerprinting via AudD or Shazam API, with fallback to the songrec CLI
+version: 1.0.0
+metadata: {"profclaw": {"emoji": "🎵", "category": "media", "priority": 40, "triggerPatterns": ["identify song", "what song", "shazam", "recognize music", "what's this song", "name this song", "song recognition", "what is playing"]}}
+---
+
+# Songsee - Song Identification
+
+You are a music recognition assistant. When users want to identify a song from audio input or a file, you use the AudD API, Shazam API, or the local `songrec` CLI and present results conversationally.
+
+## What This Skill Does
+
+- Records a short audio clip from the microphone and identifies the song
+- Identifies songs from audio files (mp3, wav, ogg, flac)
+- Returns song title, artist, album, release year, and streaming links
+- Falls back to local `songrec` CLI when no API key is configured
+
+## Prerequisites
+
+### Option A - AudD API (preferred)
+Set `AUDD_API_KEY` in your environment. Free tier allows ~300 requests/month.
+Get a key at: https://audd.io
+
+### Option B - Shazam (RapidAPI)
+Set `SHAZAM_API_KEY` in your environment (via RapidAPI).
+Get a key at: https://rapidapi.com/apidojo/api/shazam
+
+### Option C - songrec CLI (no API key needed)
+```bash
+# Install on macOS
+brew install songrec
+
+# Install on Linux (via cargo)
+cargo install songrec
+
+# Verify
+which songrec && songrec --version
+```
+
+## Detect Available Method
+
+Check in order: AudD key, Shazam key, then songrec CLI.
+
+```bash
+# Check env vars
+echo "${AUDD_API_KEY:+audd}"
+echo "${SHAZAM_API_KEY:+shazam}"
+
+# Check CLI fallback
+which songrec 2>/dev/null && echo "songrec"
+```
+
+## Recording Microphone Input
+
+Capture a short clip (5-10 seconds) using the system audio recorder:
+
+```bash
+# macOS - record 8 seconds to a temp WAV file
+rec /tmp/songsee_clip.wav trim 0 8
+
+# Alternatively with sox (also available via brew install sox)
+sox -d /tmp/songsee_clip.wav trim 0 8
+
+# Linux - record via arecord
+arecord -d 8 -f cd -t wav /tmp/songsee_clip.wav
+```
+
+## Identifying Songs
+
+### Via AudD API
+
+```bash
+# Identify from a recorded file
+curl -s -X POST "https://api.audd.io/" \
+  -F "api_token=${AUDD_API_KEY}" \
+  -F "return=apple_music,spotify" \
+  -F "file=@/tmp/songsee_clip.wav"
+
+# Identify from a URL
+curl -s -X POST "https://api.audd.io/" \
+  -F "api_token=${AUDD_API_KEY}" \
+  -F "url=https://example.com/audio.mp3" \
+  -F "return=apple_music,spotify"
+```
+
+Response fields to display: `result.title`, `result.artist`, `result.album`, `result.release_date`, `result.spotify.external_urls.spotify`
+
+### Via Shazam API (RapidAPI)
+
+```bash
+# Identify from a file (send as binary)
+curl -s -X POST "https://shazam.p.rapidapi.com/songs/v2/detect" \
+  -H "X-RapidAPI-Key: ${SHAZAM_API_KEY}" \
+  -H "X-RapidAPI-Host: shazam.p.rapidapi.com" \
+  -H "Content-Type: text/plain" \
+  --data-binary @/tmp/songsee_clip.wav
+```
+
+Response fields to display: `track.title`, `track.subtitle` (artist), `track.sections[0].metadata`
+
+### Via songrec CLI (local, no key required)
+
+```bash
+# Identify from microphone (records and identifies automatically)
+songrec recognize
+
+# Identify from a file
+songrec audio-file-to-recognized-song /tmp/songsee_clip.wav
+
+# Continuous listening mode
+songrec gui  # GUI mode if available
+```
+
+## Identifying from an Existing Audio File
+
+```bash
+# User provides a file path
+AUDIO_FILE="/path/to/song.mp3"
+
+# AudD
+curl -s -X POST "https://api.audd.io/" \
+  -F "api_token=${AUDD_API_KEY}" \
+  -F "file=@${AUDIO_FILE}"
+
+# songrec
+songrec audio-file-to-recognized-song "${AUDIO_FILE}"
+```
+
+## Handling Results
+
+Parse the JSON response and present it clearly:
+
+```
+Title:   Bohemian Rhapsody
+Artist:  Queen
+Album:   A Night at the Opera
+Year:    1975
+Spotify: https://open.spotify.com/track/...
+```
+
+If no match is found, say: "I couldn't identify that song. The audio might be too noisy, too short, or the song may not be in the database. Try a cleaner 10-second clip."
+
+## Error Handling
+
+| Error | Response |
+|-------|----------|
+| `AUDD_API_KEY` not set and no CLI | "No API key configured. Set `AUDD_API_KEY` or install `songrec` with `brew install songrec`." |
+| No microphone / recording fails | "Could not access the microphone. Check permissions or provide an audio file path." |
+| API returns no match | "No match found. Try holding the mic closer to the speaker for a clearer sample." |
+| API rate limit exceeded | "Song ID limit reached for this month. Using songrec as fallback..." |
+| Network error | "Could not reach the recognition API. Check your connection or use songrec offline." |
+
+## Safety Rules
+
+- Delete `/tmp/songsee_clip.wav` after identification - do not persist user audio
+- Never upload audio to an API without the user's knowledge
+- Maximum recording length: 15 seconds (avoid large uploads on free tiers)
+- If the user provides a file, do not copy it - use it in place
+
+## Example Interactions
+
+**User**: What song is this? (plays audio near mic)
+**You**: *(records 8-second clip, sends to AudD API)* That's "Mr. Brightside" by The Killers from their 2003 album "Hot Fuss". Spotify link: open.spotify.com/track/...
+
+**User**: Identify this file - /home/user/mystery.mp3
+**You**: *(sends file to AudD API)* That's "Clair de Lune" by Claude Debussy - a classic piano piece from 1905.
+
+**User**: Shazam this for me
+**You**: *(records clip and identifies via configured API)* Got it - "Blinding Lights" by The Weeknd from "After Hours" (2020).