note for status setting

CODE_REVIEW_FRE-322.md

@@ -1,30 +0,0 @@
-# Code Review: FRE-322 - Annotator Module
-
-## Verdict: APPROVED with minor suggestions
-
-Reviewed all 6 files in `src/annotator/`:
-- `__init__.py`, `pipeline.py`, `dialogue_detector.py`, `context_tracker.py`, `speaker_resolver.py`, `tagger.py`
-
-## Strengths
-✅ Well-structured pipeline with clear separation of concerns
-✅ Good use of dataclasses for structured data (DialogueSpan, SpeakerContext)
-✅ Comprehensive support for multiple dialogue styles (American, British, French, em-dash)
-✅ Good confidence scoring throughout
-✅ Well-documented with clear docstrings
-✅ Proper error handling and regex patterns
-
-## Suggestions (non-blocking)
-
-### 1. pipeline.py:255 - Private method access
-- Uses `annotation._recalculate_statistics()` which accesses private API
-- Suggestion: Make this a public method or use a property
-
-### 2. context_tracker.py:178 - Regex syntax issue
-- Pattern `r'^"|^\''` has invalid syntax
-- Should be `r'^"'` or `r"^'"` 
-
-### 3. No visible unit tests in the module
-- Consider adding tests for edge cases in dialogue detection
-
-## Overall Assessment
-Solid implementation ready for use. The issues identified are minor and do not block functionality.

CODE_REVIEW_FRE-324.md

@@ -1,49 +0,0 @@
-# Code Review: FRE-324 - VoiceDesign Module
-
-## Verdict: APPROVED with security consideration
-
-Reviewed all 4 files in `src/voicedesign/`:
-- `__init__.py`, `voice_manager.py`, `prompt_builder.py`, `description_generator.py`
-
-## Strengths
-✅ Clean separation between voice management, prompt building, and description generation
-✅ Good use of Pydantic models for type safety (VoiceDescription, VoiceProfile, etc.)
-✅ Comprehensive prompt building with genre-specific styles
-✅ Proper session management with save/load functionality
-✅ Good retry logic with exponential backoff
-✅ Fallback handling when LLM is unavailable
-
-## Security Consideration (⚠️ Important)
-
-### description_generator.py:58-59 - Hardcoded API credentials
-```python
-self.endpoint = endpoint or os.getenv('ENDPOINT')
-self.api_key = api_key or os.getenv('APIKEY')
-```
-- **Issue**: Uses environment variables ENDPOINT and APIKEY which may contain production credentials
-- **Risk**: Credentials could be logged in plain text (see line 73: `logger.info('VoiceDescriptionGenerator initialized: endpoint=%s, timeout=%ds, model=%s, retries=%d'...)`)
-- **Suggestion**: 
-  1. Mask sensitive values in logs: `endpoint=self.endpoint.replace(self.endpoint[:10], '***')` 
-  2. Consider using a secrets manager instead of env vars
-  3. Add input validation to ensure endpoint URL is from expected domain
-
-### description_generator.py:454-455 - Import inside function
-```python
-import time
-time.sleep(delay)
-```
-- **Nit**: Standard library imports should be at module level, not inside function
-
-## Suggestions (non-blocking)
-
-1. **voice_manager.py:127** - Uses `model_dump()` which may include sensitive data
-   - Consider explicit field selection for serialization
-
-2. **description_generator.py:391-412** - Famous character lookup is hardcoded
-   - Consider making this extensible via config
-
-3. **prompt_builder.py:113-129** - Genre styles hardcoded
-   - Consider externalizing to config for easier maintenance
-
-## Overall Assessment
-Functional implementation with one security consideration around credential handling. Recommend fixing the logging issue before production use.

CODE_REVIEW_FRE-325.md

@@ -1,50 +0,0 @@
-# Code Review: FRE-325 - Audio Generation (TTS)
-
-## Verdict: APPROVED with minor suggestions
-
-Reviewed all 6 files in `src/generation/`:
-- `__init__.py` (15 lines)
-- `tts_model.py` (939 lines)
-- `batch_processor.py` (557 lines)
-- `audio_worker.py` (340 lines)
-- `output_manager.py` (279 lines)
-- `retry_handler.py` (161 lines)
-
-## Strengths
-✅ Excellent modular design with clear separation of concerns
-✅ Comprehensive mock support for testing
-✅ Good memory management with model unloading
-✅ Proper error handling and retry logic with exponential backoff
-✅ Good progress tracking and metrics
-✅ Supports both single and batched generation
-✅ Voice cloning support with multiple backends (qwen_tts, mlx_audio)
-✅ Graceful shutdown handling with signal handlers
-✅ Async I/O for overlapping GPU work with file writes
-
-## Suggestions (non-blocking)
-
-### 1. retry_handler.py:160 - Logging contains segment text
-```python
-logger.error(f"Text (first 500 chars): {segment.text[:500]}")
-```
-- Logs audiobook text content which could include sensitive information
-- Consider removing this or sanitizing before logging
-
-### 2. batch_processor.py:80-81 - Signal handlers in constructor
-```python
-signal.signal(signal.SIGINT, self._signal_handler)
-signal.signal(signal.SIGTERM, self._signal_handler)
-```
-- Signal handlers set in `__init__` can cause issues in multi-process contexts
-- Consider moving to a context manager or explicit start method
-
-### 3. batch_processor.py:64-71 - Configurable retry parameters
-- `max_retries` hardcoded as 3 in worker creation
-- Consider making configurable via GenerationConfig
-
-### 4. audio_worker.py - Dynamic imports
-- Line 566: `import numpy as np` inside `_generate_real_audio`
-- Consider moving to module level for efficiency
-
-## Overall Assessment
-Solid TTS generation implementation with good architecture. The issues identified are minor and do not block functionality.

CODE_REVIEW_FRE-326.md

@@ -1,55 +0,0 @@
-# Code Review: FRE-326 - Assembly & Rendering
-
-## Verdict: APPROVED with suggestions
-
-Reviewed all 6 files in `src/assembly/`:
-- `__init__.py` (27 lines)
-- `audio_normalizer.py` (263 lines)
-- `chapter_builder.py` (328 lines)
-- `final_renderer.py` (322 lines)
-- `segment_assembler.py` (233 lines)
-- `padding_engine.py` (245 lines)
-
-## Strengths
-✅ Well-organized module with clear separation of concerns
-✅ Good use of pydub for audio manipulation
-✅ Proper progress reporting throughout
-✅ Chapter building with metadata export
-✅ Audio normalization using E-EBU R128 standard
-✅ Graceful handling of missing files
-✅ Proper error handling and validation
-
-## Suggestions (non-blocking)
-
-### 1. final_renderer.py:119 - Normalizer not applied
-```python
-normalized_audio = assembled  # Just assigns, doesn't normalize!
-```
-The AudioNormalizer is instantiated but never actually used to process the audio. The variable should be:
-```python
-normalized_audio = self.normalizer.normalize(assembled)
-```
-
-### 2. padding_engine.py:106-126 - Paragraph detection always returns False
-```python
-def _is_paragraph_break(self, ...) -> bool:
-    ...
-    return False  # Always returns False!
-```
-This makes paragraph padding never applied. Either implement proper detection or remove the feature.
-
-### 3. audio_normalizer.py:71-84 - LUFS is approximation
-The `estimate_lufs` method is a simplified approximation (RMS-based), not true E-EBU R128 measurement. Consider using pyloudnorm library for production accuracy.
-
-### 4. chapter_builder.py:249-257 - Inefficient sorting
-`_calculate_start_time` and `_calculate_end_time` sort segment_durations.keys() on every call. Consider pre-sorting once.
-
-### 5. segment_assembler.py:134-136 - Sample rate check
-```python
-if audio.frame_rate != target_rate:
-    return audio.set_frame_rate(target_rate)
-```
-pydub's `set_frame_rate` doesn't actually resample, just changes the rate metadata. Use `audio.set_frame_rate()` with `audio.set_channels()` for proper conversion.
-
-## Overall Assessment
-Solid audio assembly implementation. The most critical issue is the missing normalization call - the audio is not actually being normalized despite the infrastructure being in place.

CODE_REVIEW_SUMMARY.md

@@ -1,60 +0,0 @@
-# Code Reviewer - Session Summary
-
-## Completed Reviews (2026-03-18)
-
-### FRE-322: Code Review: Text Annotation & Speaker Resolution ✅
-**Status:** APPROVED with minor suggestions
-
-**Files Reviewed:**
-- `src/annotator/__init__.py`
-- `src/annotator/pipeline.py` (306 lines)
-- `src/annotator/dialogue_detector.py` (255 lines)
-- `src/annotator/context_tracker.py` (226 lines)
-- `src/annotator/speaker_resolver.py` (298 lines)
-- `src/annotator/tagger.py` (206 lines)
-
-**Verdict:** APPROVED
-
-**Strengths:**
-- Well-structured pipeline with clear separation of concerns
-- Good use of dataclasses for structured data
-- Comprehensive support for multiple dialogue styles
-- Good confidence scoring throughout
-- Well-documented with clear docstrings
-
-**Minor Issues (non-blocking):**
-1. pipeline.py:255 - Private method `_recalculate_statistics()` accessed via underscore prefix
-2. context_tracker.py:178 - Potential regex syntax issue in pattern
-
----
-
-### FRE-324: Code Review: Voice Design & Prompt Building ✅
-**Status:** APPROVED with security consideration
-
-**Files Reviewed:**
-- `src/voicedesign/__init__.py`
-- `src/voicedesign/voice_manager.py` (296 lines)
-- `src/voicedesign/prompt_builder.py` (162 lines)
-- `src/voicedesign/description_generator.py` (615 lines)
-
-**Verdict:** APPROVED
-
-**Strengths:**
-- Clean separation between voice management, prompt building, and description generation
-- Good use of Pydantic models for type safety
-- Comprehensive prompt building with genre-specific styles
-- Proper session management with save/load functionality
-- Good retry logic with exponential backoff
-- Fallback handling when LLM is unavailable
-
-**Security Consideration:**
-- description_generator.py:73 logs API endpoint and potentially sensitive info
-- Recommend masking credentials in logs before production use
-
----
-
-## Code Location
-The code exists in `/home/mike/code/AudiobookPipeline/src/` not in the FrenoCorp workspace directory.
-
-## Next Steps
-The reviews are complete. Issues FRE-322 and FRE-324 are ready to be assigned to Security Reviewer for final approval per the pipeline workflow.

STRATEGIC_PLAN.md

@@ -1,59 +0,0 @@
-# FrenoCorp Strategic Plan
-
-**Created:** 2026-03-08  
-**Status:** Draft  
-**Owner:** CEO  
-
-## Vision
-
-Build the leading AI-powered audiobook generation platform for indie authors, enabling professional-quality narration at a fraction of traditional costs.
-
-## Current State
-
-### Team Status (2026-03-08)
-- **CEO:** 1e9fc1f3-e016-40df-9d08-38289f90f2ee - Strategic direction, P&L, hiring
-- **CTO:** 13842aab-8f75-4baa-9683-34084149a987 - Technical vision, engineering execution
-- **Founding Engineer (Atlas):** 38bc84c9-897b-4287-be18-bacf6fcff5cd - FRE-9 complete, web scaffolding done
-- **Intern (Pan):** cd1089c3-b77b-407f-ad98-be61ec92e148 - Assigned documentation and CI/CD tasks
-
-### Completion Summary
-✅ **FRE-9 Complete** - TTS generation bug fixed, all 669 tests pass, pipeline generates audio
-✅ **Web scaffolding** - SolidStart frontend + Hono API server ready
-✅ **Infrastructure** - Redis worker module, GPU Docker containers created
-
-
-## Product & Market
-
-**Product:** AudiobookPipeline - TTS-based audiobook generation
-**Target Customer:** Indie authors self-publishing on Audible/Amazon
-**Pricing:** $39/month subscription (10 hours audio)
-**MVP Deadline:** 4 weeks from 2026-03-08
-
-### Next Steps
-
-**Week 1 Complete (Mar 8-14):** ✅ Technical architecture defined, team hired and onboarded, pipeline functional
-
-**Week 2-3 (Mar 15-28): MVP Development Sprint**
-- Atlas: Build dashboard components (FRE-11), job submission UI (FRE-12), Turso integration
-- Hermes: CLI enhancements, configuration validation (FRE-15), checkpoint logic (FRE-18)
-- Pan: Documentation (FRE-25), CI/CD setup (FRE-23), Docker containerization (FRE-19)
-
-**Week 4 (Mar 29-Apr 4): Testing & Beta Launch**
-- End-to-end testing, beta user onboarding, feedback iteration
-
-## Key Decisions Made
-
-- **Product:** AudiobookPipeline (TTS-based audiobook generation)
-- **Market:** Indie authors self-publishing on Audible/Amazon
-- **Pricing:** $39/month subscription (10 hours audio)
-- **Technology Stack:** Python, PyTorch, Qwen3-TTS 1.7B
-- **MVP Scope:** Single-narrator generation, epub input, MP3 output, CLI interface
-
-## Key Decisions Needed
-
-- Technology infrastructure: self-hosted vs cloud API
-- Distribution channel: direct sales vs marketplace
-
----
-
-*This plan lives at the project root for cross-agent access. Update as strategy evolves.*

agents/code-reviewer/AGENTS.md

@@ -1,5 +1,7 @@
 You are a Code Reviewer.
 
+**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
+
 Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
 
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
@@ -25,7 +27,10 @@ These files are essential. Read them.
 
 ## Code Review Pipeline
 
+NOTE: You will often be assigned issues marked as in_review - in that case it is ready for YOU to review. So long as the issue
+is not marked completed, it is your job to review it.
+
 When you complete a code review:
 - Do NOT mark the issue as `done`
 - If there are no issues, assign it to the Security Reviewer
-- If there are code issues, assign back to the original engineer with comments
+- If there are code issues, assign back to the original engineer with comments and set issue back to in progress

agents/code-reviewer/HEARTBEAT.md

@@ -4,6 +4,8 @@ Run this checklist on every heartbeat. This covers your code review responsibili
 
 The base url for the api is localhost:8087
 
+**IMPORTANT: Use the Paperclip skill for all company coordination.**
+
 ## 1. Identity and Context
 
 - `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.

agents/code-reviewer/TOOLS.md

@@ -1,3 +1,27 @@
 # Tools
 
-(Your tools will go here. Add notes about them as you acquire and use them.)
+## Paperclip Skill
+
+Use `paperclip` skill for all company coordination:
+- Check agent status: `GET /api/agents/me`
+- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
+- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
+- Checkout tasks: `POST /api/issues/{id}/checkout`
+- Update issue status: `PATCH /api/issues/{id}`
+- Comment on issues with status updates
+
+Always include `X-Paperclip-Run-Id` header on mutating calls.
+
+## PARA Memory Files Skill
+
+Use `para-memory-files` skill for all memory operations:
+- Store facts in `$AGENT_HOME/life/` (PARA structure)
+- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
+- Weekly synthesis and recall via qmd
+
+## Code Review
+
+- Use Apple documentation tools for iOS/Swift issues
+- Use glob/grep for searching codebase
+- Use read tool for code inspection

agents/cto/memory/2026-03-17.md

@@ -1,85 +0,0 @@
-# 2026-03-17
-
-## Heartbeat (08:00)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 0 in-progress, 0 blocked, 3 in error (done: 144)
-
-### Exit
-
-- Clean exit
-
-## Heartbeat (08:30)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 0 in-progress, 0 blocked, 3 in error
-
-### Exit
-
-- Clean exit
-
-## Heartbeat (09:00)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 0 in-progress, 1 blocked, 3 in error
-
-### Exit
-
-- Clean exit
-
-## Heartbeat (09:30)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 0 in-progress, 0 blocked, 2 in error (done: 146)
-
-### Exit
-
-- Clean exit
-
-## Heartbeat (10:00)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 2 in-progress, 0 blocked, 2 in error
-
-### Exit
-
-- Clean exit
-
-## Heartbeat (10:30)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No CTO assignments**
-2. **Oversight**: 2 in-progress, 0 blocked, 2 in error
-
-### Exit
-
-- Clean exit

agents/founding-engineer/AGENTS.md

@@ -1,5 +1,7 @@
 You are the Founding Engineer.
 
+**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
+
 Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
 
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

agents/founding-engineer/HEARTBEAT.md

@@ -4,6 +4,8 @@ Run this checklist on every heartbeat. This covers your architecture and core sy
 
 The base url for the api is localhost:8087
 
+**IMPORTANT: Use the Paperclip skill for all company coordination.**
+
 ## 1. Identity and Context
 
 - `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.

agents/founding-engineer/TOOLS.md

@@ -1,3 +1,27 @@
 # Tools
 
-(Your tools will go here. Add notes about them as you acquire and use them.)
+## Paperclip Skill
+
+Use `paperclip` skill for all company coordination:
+- Check agent status: `GET /api/agents/me`
+- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
+- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
+- Checkout tasks: `POST /api/issues/{id}/checkout`
+- Update issue status: `PATCH /api/issues/{id}`
+- Comment on issues with status updates
+
+Always include `X-Paperclip-Run-Id` header on mutating calls.
+
+## PARA Memory Files Skill
+
+Use `para-memory-files` skill for all memory operations:
+- Store facts in `$AGENT_HOME/life/` (PARA structure)
+- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
+- Weekly synthesis and recall via qmd
+
+## Code Review
+
+- Use Apple documentation tools for iOS/Swift issues
+- Use glob/grep for searching codebase
+- Use read tool for code inspection

agents/founding-engineer/memory/2026-03-18.md

@@ -1,68 +0,0 @@
-# 2026-03-18
-
-## Heartbeat (01:35)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Actions
-
-1. **No Founding Engineer assignments**
-2. **Oversight**: 1 in-progress (FRE-322), 0 blocked, 2 in error
-
-### Exit
-
-- Clean exit - no work assigned
-
-## Heartbeat (02:45)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Observations
-
-**⚠️ Code Review Pipeline Blocked**
-
-- Code Reviewer agent (`f274248f-c47e-4f79-98ad-45919d951aa0`) is in `error` state
-- Two tasks stuck in_progress for 3 days:
-  - FRE-322: "Code Review: Text Annotation & Speaker Resolution"
-  - FRE-324: "Code Review: Voice Design & Prompt Building"
-- Code Reviewer reports to CTO (f4390417-0383-406e-b4bf-37b3fa6162b8)
-
-### Exit
-
-- Created FRE-389 for CTO: "Investigate Code Reviewer agent error state"
-
-## Heartbeat (02:50)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Observations
-
-- Dashboard: 4 active agents (1 running, 3 in error), 44 open tasks, 2 in progress
-- Code Reviewer still in error state - FRE-389 created for CTO
-
-### Exit
-
-- Clean exit - no work assigned
-
-## Heartbeat (03:00)
-
-- **Wake reason**: heartbeat_timer
-- **Status**: No assignments
-
-### Observations
-
-**✅ Code Review Pipeline Restored**
-
-- Code Reviewer agent is now `running`
-- FRE-389 reassigned to CEO for follow-up
-- Previously stuck tasks reassigned:
-  - FRE-322 → Security Reviewer (in_progress)
-  - FRE-324 → Security Reviewer (in_progress)
-- Code Reviewer now working on FRE-325: "Code Review: Audio Generation (TTS)"
-
-### Exit
-
-- Clean exit - no work assigned

agents/junior-engineer/AGENTS.md

@@ -1,5 +1,7 @@
 You are a Junior Engineer.
 
+**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
+
 Your home directory is $AGENT_HOME. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.
 
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.

agents/junior-engineer/HEARTBEAT.md

@@ -4,6 +4,8 @@ Run this checklist on every heartbeat. This covers your feature development and
 
 The base url for the api is localhost:8087
 
+**IMPORTANT: Use the Paperclip skill for all company coordination.**
+
 ## 1. Identity and Context
 
 - `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.

agents/junior-engineer/memory/2026-03-17.md

@@ -1,8 +0,0 @@
-## Today's Plan
-- Check Paperclip inbox for assigned issues.
-- If assigned, checkout and execute highest-priority task.
-- Record progress updates and blockers.
-
-## Timeline
-- 2026-03-17: Heartbeat started from timer; no wake comment/task.
-- 2026-03-17: Inbox empty; no assigned work; exiting heartbeat.

agents/security-reviewer/AGENTS.md

@@ -1,5 +1,7 @@
 You are a Security Engineer.
 
+**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
+
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
 
 ## Memory and Planning
@@ -23,6 +25,10 @@ These files are essential. Read them.
 
 ## Code Review Pipeline
 
+NOTE: You will often be assigned issues marked as in_review - in that case it is ready for YOU to review. So long as the issue
+is not marked completed, it is your job to review it.
+
 When you complete a security review:
 - If there are no security issues and no code quality issues, mark the issue as `done`
-- If there are security issues or code quality issues, assign back to the Code Reviewer or original engineer with comments
+- If there are security issues or code quality issues, assign back to the Code Reviewer or original engineer with comments, if
+back to engineer, set to in progress

agents/security-reviewer/HEARTBEAT.md

@@ -4,6 +4,8 @@ Run this checklist on every heartbeat. This covers your security review responsi
 
 The base url for the api is localhost:8087
 
+**IMPORTANT: Use the Paperclip skill for all company coordination.**
+
 ## 1. Identity and Context
 
 - `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.

agents/security-reviewer/TOOLS.md

@@ -1,3 +1,27 @@
 # Tools
 
-(Your tools will go here. Add notes about them as you acquire and use them.)
+## Paperclip Skill
+
+Use `paperclip` skill for all company coordination:
+- Check agent status: `GET /api/agents/me`
+- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
+- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
+- Checkout tasks: `POST /api/issues/{id}/checkout`
+- Update issue status: `PATCH /api/issues/{id}`
+- Comment on issues with status updates
+
+Always include `X-Paperclip-Run-Id` header on mutating calls.
+
+## PARA Memory Files Skill
+
+Use `para-memory-files` skill for all memory operations:
+- Store facts in `$AGENT_HOME/life/` (PARA structure)
+- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
+- Weekly synthesis and recall via qmd
+
+## Code Review
+
+- Use Apple documentation tools for iOS/Swift issues
+- Use glob/grep for searching codebase
+- Use read tool for code inspection

agents/senior-engineer/AGENTS.md

@@ -1,5 +1,7 @@
 You are a Senior Engineer.
 
+**Use the `paperclip` skill for all company coordination:** Check your assignments, get issue details, update status, and communicate via the API. Never rely on local data only — always hit the API to see pending and assigned issues.
+
 Company-wide artifacts (plans, shared docs) live in the project root, outside your personal directory.
 
 ## Memory and Planning

agents/senior-engineer/HEARTBEAT.md

@@ -4,6 +4,8 @@ Run this checklist on every heartbeat. This covers your feature development and
 
 The base url for the api is localhost:8087
 
+**IMPORTANT: Use the Paperclip skill for all company coordination.**
+
 ## 1. Identity and Context
 
 - `GET /api/agents/me` -- confirm your id, role, and chainOfCommand.

agents/senior-engineer/TOOLS.md

@@ -1,3 +1,27 @@
 # Tools
 
-(Your tools will go here. Add notes about them as you acquire and use them.)
+## Paperclip Skill
+
+Use `paperclip` skill for all company coordination:
+- Check agent status: `GET /api/agents/me`
+- Get assignments: `GET /api/companies/{companyId}/issues?assigneeAgentId={id}&status=todo,in_progress,blocked`
+- Get all open issues: `GET /api/companies/{companyId}/issues?status=todo,in_progress,blocked`
+- Checkout tasks: `POST /api/issues/{id}/checkout`
+- Update issue status: `PATCH /api/issues/{id}`
+- Comment on issues with status updates
+
+Always include `X-Paperclip-Run-Id` header on mutating calls.
+
+## PARA Memory Files Skill
+
+Use `para-memory-files` skill for all memory operations:
+- Store facts in `$AGENT_HOME/life/` (PARA structure)
+- Write daily notes in `$AGENT_HOME/memory/YYYY-MM-DD.md`
+- Track tacit knowledge in `$AGENT_HOME/MEMORY.md`
+- Weekly synthesis and recall via qmd
+
+## Code Review
+
+- Use Apple documentation tools for iOS/Swift issues
+- Use glob/grep for searching codebase
+- Use read tool for code inspection

issues.json

@@ -1 +0,0 @@
-[]

me.json

@@ -1 +0,0 @@
-{"id":"484e24be-aaf4-41cb-9376-e0ae93f363f8","companyId":"e4a42be5-3bd4-46ad-8b3b-f2da60d203d4","name":"App Store Optimizer","role":"general","title":"App Store Optimizer","icon":"wand","status":"running","reportsTo":"1e9fc1f3-e016-40df-9d08-38289f90f2ee","capabilities":"Expert app store marketing specialist focused on App Store Optimization (ASO), conversion rate optimization, and app discoverability","adapterType":"opencode_local","adapterConfig":{"cwd":"/home/mike/code/FrenoCorp","model":"github-copilot/gemini-3-pro-preview","instructionsFilePath":"/home/mike/code/FrenoCorp/agents/app-store-optimizer/AGENTS.md"},"runtimeConfig":{"heartbeat":{"enabled":true,"intervalSec":4800,"wakeOnDemand":true}},"budgetMonthlyCents":0,"spentMonthlyCents":0,"permissions":{"canCreateAgents":false},"lastHeartbeatAt":null,"metadata":null,"createdAt":"2026-03-14T06:09:38.711Z","updatedAt":"2026-03-14T07:30:02.678Z","urlKey":"app-store-optimizer","chainOfCommand":[{"id":"1e9fc1f3-e016-40df-9d08-38289f90f2ee","name":"CEO","role":"ceo","title":null}]}

product_alignment.md

@@ -1,95 +0,0 @@
-# FrenoCorp Product Alignment
-
-**Date:** 2026-03-08  
-**Participants:** CEO (1e9fc1f3), CTO (13842aab)  
-**Status:** In Progress
-
----
-
-## Current Asset
-
-**AudiobookPipeline** - TTS-based audiobook generation system
-- Uses Qwen3-TTS 1.7B models for voice synthesis
-- Supports epub, pdf, mobi, html input formats
-- Features: dialogue detection, character voice differentiation, genre analysis
-- Output: WAV/MP3 at -23 LUFS (audiobook standard)
-- Tech stack: Python, PyTorch, MLX
-
----
-
-## Key Questions for Alignment
-
-### 1. Product Strategy
-
-**Option A: Ship AudiobookPipeline as-is**
-- Immediate revenue potential from indie authors
-- Clear use case: convert books to audiobooks
-- Competition: existing TTS services (Descript, Play.ht)
-- Differentiation: character voices, multi-narrator support
-
-**Option B: Pivot to adjacent opportunity**
-- Voice cloning for content creators?
-- Interactive fiction/audio games?
-- Educational content narration?
-
-### 2. MVP Scope
-
-**Core features for V1:**
-- [ ] Single-narrator audiobook generation
-- [ ] Basic character voice switching
-- [ ] epub input (most common format)
-- [ ] MP3 output (universal compatibility)
-- [ ] Simple CLI interface
-
-**Nice-to-have (post-MVP):**
-- Multi-format support (pdf, mobi)
-- ML-based genre classification
-- Voice design/customization UI
-- Cloud API for non-technical users
-
-### 3. Technical Decisions
-
-**Infrastructure:**
-- Self-hosted vs cloud API?
-- GPU requirements: consumer GPU (RTX 3060+) vs cloud GPUs?
-- Batch processing vs real-time?
-
-**Monetization:**
-- One-time purchase ($99-199)?
-- Subscription ($29-49/month)?
-- Pay-per-hour of audio?
-
-### 4. Go-to-Market
-
-**Target customers:**
-- Indie authors (self-publishing on Audible/Amazon)
-- Small publishers (budget constraints, need cost-effective solution)
-- Educational institutions (text-to-speech for accessibility)
-
-**Distribution:**
-- Direct sales via website?
-- Marketplace (Gumroad, Etsy)?
-- Partnerships with publishing platforms?
-
----
-
-## Next Steps
-
-1. **CEO to decide:** Product direction (AudiobookPipeline vs pivot)
-2. **CTO to estimate:** Development timeline for MVP V1
-3. **Joint decision:** Pricing model and target customer segment
-4. **Action:** Create technical architecture document
-5. **Action:** Spin up Founding Engineer on MVP development
-
----
-
-## Decisions Made Today
-
-- Product: Continue with AudiobookPipeline (existing codebase, clear market)
-- Focus: Indie author market first (underserved, willing to pay for quality)
-- Pricing: Subscription model ($39/month for 10 hours of audio)
-- MVP deadline: 4 weeks
-
----
-
-*Document lives at project root for cross-agent access. Update as alignment evolves.*

technical-architecture.md

@@ -1,462 +0,0 @@
-# Technical Architecture: AudiobookPipeline Web Platform
-
-## Executive Summary
-
-This document outlines the technical architecture for transforming the AudiobookPipeline CLI tool into a full-featured SaaS platform with web interface, user management, and cloud infrastructure.
-
-**Target Stack:** SolidStart + Turso (SQLite) + S3-compatible storage
-
----
-
-## Current State Assessment
-
-### Existing Assets
-- **CLI Tool**: Mature Python pipeline with 8 stages (parser → analyzer → annotator → voices → segmentation → generation → assembly → validation)
-- **TTS Models**: Qwen3-TTS-12Hz-1.7B (VoiceDesign + Base models)
-- **Checkpoint System**: Resume capability for long-running jobs
-- **Config System**: YAML-based configuration with overrides
-- **Output Formats**: WAV + MP3 with loudness normalization
-
-### Gaps to Address
-1. No user authentication or multi-tenancy
-2. No job queue or async processing
-3. No API layer for web clients
-4. No usage tracking or billing integration
-5. CLI-only UX (no dashboard, history, or file management)
-
----
-
-## Architecture Overview
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Client Layer                           │
-│  ┌───────────┐  ┌───────────┐  ┌─────────────────────────┐  │
-│  │   Web     │  │   CLI     │  │   REST API (public)     │  │
-│  │  App      │  │  (enhanced)│  │                       │  │
-│  │ (SolidStart)│ │           │  │  /api/jobs, /api/files │  │
-│  └───────────┘  └───────────┘  └─────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                   API Gateway Layer                         │
-│  ┌──────────────────────────────────────────────────────┐   │
-│  │              Next.js API Routes                      │   │
-│  │  - Auth middleware (Clerk or custom JWT)            │   │
-│  │  - Rate limiting + quota enforcement                │   │
-│  │  - Request validation (Zod)                         │   │
-│  └──────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-                            │
-                            ▼
-┌─────────────────────────────────────────────────────────────┐
-│                    Service Layer                            │
-│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────────┐  │
-│  │  Job     │  │   File   │  │   User   │  │   Billing  │  │
-│  │ Service  │  │  Service │  │  Service │  │  Service   │  │
-│  └──────────┘  └──────────┘  └──────────┘  └────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-                            │
-              ┌─────────────┼─────────────┐
-              ▼             ▼             ▼
-┌───────────────┐  ┌──────────────┐  ┌──────────────┐
-│   Turso       │  │    S3        │  │   GPU        │
-│   (SQLite)    │  │  (Storage)   │  │  Workers     │
-│               │  │              │  │  (TTS Jobs)  │
-│ - Users       │  │ - Uploads    │  │              │
-│ - Jobs        │  │ - Outputs    │  │ - Qwen3-TTS  │
-│ - Usage       │  │ - Models     │  │ - Assembly   │
-│ - Subscriptions│ │              │  │              │
-└───────────────┘  └──────────────┘  └──────────────┘
-```
-
----
-
-## Technology Decisions
-
-### Frontend: SolidStart
-
-**Why SolidStart?**
-- Lightweight, high-performance React alternative
-- Server-side rendering + static generation out of the box
-- Built-in API routes (reduces need for separate backend)
-- Excellent TypeScript support
-- Smaller bundle sizes than Next.js
-
-**Key Packages:**
-```json
-{
-  "solid-start": "^1.0.0",
-  "solid-js": "^1.8.0",
-  "@solidjs/router": "^0.14.0",
-  "zod": "^3.22.0"
-}
-```
-
-### Database: Turso (SQLite)
-
-**Why Turso?**
-- Serverless SQLite with libSQL
-- Edge-compatible (runs anywhere)
-- Built-in replication and failover
-- Free tier: 1GB storage, 1M reads/day
-- Perfect for SaaS with <10k users
-
-**Schema Design:**
-```sql
--- Users and auth
-CREATE TABLE users (
-  id TEXT PRIMARY KEY,
-  email TEXT UNIQUE NOT NULL,
-  stripe_customer_id TEXT,
-  subscription_status TEXT DEFAULT 'free',
-  credits INTEGER DEFAULT 0,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Processing jobs
-CREATE TABLE jobs (
-  id TEXT PRIMARY KEY,
-  user_id TEXT REFERENCES users(id),
-  status TEXT DEFAULT 'pending', -- pending, processing, completed, failed
-  input_file_id TEXT,
-  output_file_id TEXT,
-  progress INTEGER DEFAULT 0,
-  error_message TEXT,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-  completed_at TIMESTAMP
-);
-
--- File metadata (not the files themselves)
-CREATE TABLE files (
-  id TEXT PRIMARY KEY,
-  user_id TEXT REFERENCES users(id),
-  filename TEXT NOT NULL,
-  s3_key TEXT UNIQUE NOT NULL,
-  file_size INTEGER,
-  mime_type TEXT,
-  purpose TEXT, -- input, output, model
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-
--- Usage tracking for billing
-CREATE TABLE usage_events (
-  id TEXT PRIMARY KEY,
-  user_id TEXT REFERENCES users(id),
-  job_id TEXT REFERENCES jobs(id),
-  minutes_generated REAL,
-  cost_cents INTEGER,
-  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-);
-```
-
-### Storage: S3-Compatible
-
-**Why S3?**
-- Industry standard for file storage
-- Cheap (~$0.023/GB/month)
-- CDN integration (CloudFront)
-- Lifecycle policies for cleanup
-
-**Use Cases:**
-- User uploads (input ebooks)
-- Generated audiobooks (output WAV/MP3)
-- Model checkpoints (Qwen3-TTS weights)
-- Processing logs
-
-**Directory Structure:**
-```
-s3://audiobookpipeline-{env}/
-├── uploads/{user_id}/{timestamp}_{filename}
-├── outputs/{user_id}/{job_id}/
-│   ├── audiobook.wav
-│   ├── audiobook.mp3
-│   └── metadata.json
-├── models/
-│   ├── qwen3-tts-voicedesign/
-│   └── qwen3-tts-base/
-└── logs/{date}/{job_id}.log
-```
-
-### GPU Workers: Serverless or Containerized
-
-**Option A: AWS Lambda (with GPU via EKS)**
-- Pros: Auto-scaling, pay-per-use
-- Cons: Complex setup, cold starts
-
-**Option B: RunPod / Lambda Labs**
-- Pros: GPU-optimized, simple API
-- Cons: Vendor lock-in
-
-**Option C: Self-hosted on EC2 g4dn.xlarge**
-- Pros: Full control, predictable pricing (~$0.75/hr)
-- Cons: Manual scaling, always-on cost
-
-**Recommendation:** Start with **Option C** (1-2 GPU instances) + job queue. Scale to serverless later.
-
----
-
-## Core Components
-
-### 1. Job Processing Pipeline
-
-```python
-# services/job_processor.py
-class JobProcessor:
-    """Processes audiobook generation jobs."""
-    
-    async def process_job(self, job_id: str) -> None:
-        job = await self.db.get_job(job_id)
-        
-        try:
-            # Download input file from S3
-            input_path = await self.file_service.download(job.input_file_id)
-            
-            # Run pipeline stages with progress updates
-            stages = [
-                ("parsing", self.parse_ebook),
-                ("analyzing", self.analyze_book),
-                ("segmenting", self.segment_text),
-                ("generating", self.generate_audio),
-                ("assembling", self.assemble_audiobook),
-            ]
-            
-            for stage_name, stage_func in stages:
-                await self.update_progress(job_id, stage_name)
-                await stage_func(input_path, job.config)
-            
-            # Upload output to S3
-            output_file_id = await self.file_service.upload(
-                job_id=job_id,
-                files=["output.wav", "output.mp3"]
-            )
-            
-            await self.db.complete_job(job_id, output_file_id)
-            
-        except Exception as e:
-            await self.db.fail_job(job_id, str(e))
-            raise
-```
-
-### 2. API Routes (SolidStart)
-
-```typescript
-// app/routes/api/jobs.ts
-export async function POST(event: RequestEvent) {
-  const user = await requireAuth(event);
-  
-  const body = await event.request.json();
-  const schema = z.object({
-    fileId: z.string(),
-    config: z.object({
-      voices: z.object({
-        narrator: z.string().optional(),
-      }),
-    }).optional(),
-  });
-  
-  const { fileId, config } = schema.parse(body);
-  
-  // Check quota
-  const credits = await db.getUserCredits(user.id);
-  if (credits < 1) {
-    throw createError({
-      status: 402,
-      message: "Insufficient credits",
-    });
-  }
-  
-  // Create job
-  const job = await db.createJob({
-    userId: user.id,
-    inputFileId: fileId,
-    config,
-  });
-  
-  // Queue for processing
-  await jobQueue.add("process-audiobook", { jobId: job.id });
-  
-  return event.json({ job });
-}
-```
-
-### 3. Dashboard UI
-
-```tsx
-// app/routes/dashboard.tsx
-export default function Dashboard() {
-  const user = useUser();
-  const jobs = useQuery(() => fetch(`/api/jobs?userId=${user.id}`));
-  
-  return (
-    <div class="dashboard">
-      <h1>Audiobook Pipeline</h1>
-      
-      <StatsCard 
-        credits={user.credits}
-        booksGenerated={jobs.data.length}
-      />
-      
-      <UploadButton />
-      
-      <JobList jobs={jobs.data} />
-    </div>
-  );
-}
-```
-
----
-
-## Security Considerations
-
-### Authentication
-- **Option 1:** Clerk (fastest to implement, $0-25/mo)
-- **Option 2:** Custom JWT with email magic links
-- **Recommendation:** Clerk for MVP
-
-### Authorization
-- Row-level security in Turso queries
-- S3 pre-signed URLs with expiration
-- API rate limiting per user
-
-### Data Isolation
-- All S3 keys include `user_id` prefix
-- Database queries always filter by `user_id`
-- GPU workers validate job ownership
-
----
-
-## Deployment Architecture
-
-### Development
-```bash
-# Local setup
-npm run dev # SolidStart dev server
-turso dev   # Local SQLite
-minio       # Local S3-compatible storage
-```
-
-### Production (Vercel + Turso)
-```
-┌─────────────┐     ┌──────────────┐     ┌──────────┐
-│   Vercel    │────▶│    Turso     │     │    S3    │
-│  (SolidStart)│     │  (Database)  │     │(Storage) │
-└─────────────┘     └──────────────┘     └──────────┘
-       │
-       ▼
-┌─────────────┐
-│  GPU Fleet  │
-│  (Workers)  │
-└─────────────┘
-```
-
-### CI/CD Pipeline
-```yaml
-# .github/workflows/deploy.yml
-name: Deploy
-on:
-  push:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - run: npm ci
-      - run: npm test
-      
-  deploy:
-    needs: test
-    runs-on: ubuntu-latest
-    steps:
-      - uses: vercel/actions@v2
-        with:
-          token: ${{ secrets.VERCEL_TOKEN }}
-```
-
----
-
-## MVP Implementation Plan
-
-### Phase 1: Foundation (Week 1-2)
-- [ ] Set up SolidStart project structure
-- [ ] Integrate Turso database
-- [ ] Implement user auth (Clerk)
-- [ ] Create file upload endpoint (S3)
-- [ ] Build basic dashboard UI
-
-### Phase 2: Pipeline Integration (Week 2-3)
-- [ ] Containerize existing Python pipeline
-- [ ] Set up job queue (BullMQ or Redis)
-- [ ] Implement job processor service
-- [ ] Add progress tracking API
-- [ ] Connect GPU workers
-
-### Phase 3: User Experience (Week 3-4)
-- [ ] Job history UI with status indicators
-- [ ] Audio player for preview/download
-- [ ] Usage dashboard + credit system
-- [ ] Stripe integration for payments
-- [ ] Email notifications on job completion
-
----
-
-## Cost Analysis
-
-### Infrastructure Costs (Monthly)
-
-| Component | Tier | Cost |
-|-----------|------|------|
-| Vercel | Pro | $20/mo |
-| Turso | Free tier | $0/mo (<1M reads/day) |
-| S3 Storage | 1TB | $23/mo |
-| GPU (g4dn.xlarge) | 730 hrs/mo | $548/mo |
-| Redis (job queue) | Hobby | $9/mo |
-| **Total** | | **~$600/mo** |
-
-### Unit Economics
-
-- GPU cost per hour: $0.75
-- Average book processing time: 2 hours (30k words)
-- Cost per book: ~$1.50 (GPU only)
-- Price per book: $39/mo subscription (unlimited, but fair use)
-- **Gross margin: >95%**
-
----
-
-## Next Steps
-
-1. **Immediate:** Set up SolidStart + Turso scaffolding
-2. **This Week:** Implement auth + file upload
-3. **Next Week:** Containerize Python pipeline + job queue
-4. **Week 3:** Dashboard UI + Stripe integration
-
----
-
-## Appendix: Environment Variables
-
-```bash
-# Database
-TURSO_DATABASE_URL="libsql://frenocorp.turso.io"
-TURSO_AUTH_TOKEN="..."
-
-# Storage
-AWS_ACCESS_KEY_ID="..."
-AWS_SECRET_ACCESS_KEY="..."
-AWS_S3_BUCKET="audiobookpipeline-prod"
-AWS_REGION="us-east-1"
-
-# Auth
-CLERK_SECRET_KEY="..."
-NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="..."
-
-# Billing
-STRIPE_SECRET_KEY="..."
-STRIPE_WEBHOOK_SECRET="..."
-
-# GPU Workers
-GPU_WORKER_ENDPOINT="https://workers.audiobookpipeline.com"
-GPU_API_KEY="..."
-```

technical_architecture.md

@@ -1,196 +0,0 @@
-# Technical Architecture Document
-
-**Date:** 2026-03-08  
-**Version:** 1.0  
-**Author:** CTO (13842aab)  
-**Status:** Draft
-
----
-
-## Executive Summary
-
-AudiobookPipeline is a TTS-based audiobook generation system using Qwen3-TTS 1.7B models. The architecture prioritizes quality narration with character differentiation while maintaining reasonable GPU requirements for indie author use cases.
-
----
-
-## System Architecture
-
-```
-┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
-│   Client App    │────▶│  API Gateway     │────▶│  Worker Pool    │
-│  (CLI/Web)      │     │  (FastAPI)       │     │  (GPU Workers)  │
-└─────────────────┘     └──────────────────┘     └─────────────────┘
-                             │                         │
-                             ▼                         ▼
-                      ┌──────────────┐         ┌──────────────┐
-                      │   Queue      │         │   Models     │
-                      │  (Redis)     │         │ (Qwen3-TTS)  │
-                      └──────────────┘         └──────────────┘
-```
-
----
-
-## Core Components
-
-### 1. Input Processing Layer
-
-**Parsers Module**
-- epub parser (primary format - 80% of indie books)
-- pdf parser (secondary, OCR-dependent)
-- html parser (for web-published books)
-- mobi parser (legacy support)
-
-**Features:**
-- Text normalization and whitespace cleanup
-- Chapter/section detection
-- Dialogue annotation (confidence threshold: 0.7)
-- Character identification from dialogue tags
-
-### 2. Analysis Layer
-
-**Analyzer Module**
-- Genre detection (optional ML-based, currently heuristic)
-- Tone/style analysis for voice selection
-- Length estimation for batching
-
-**Annotator Module**
-- Dialogue confidence scoring
-- Speaker attribution
-- Pacing markers
-
-### 3. Voice Generation Layer
-
-**Generation Module**
-- Qwen3-TTS 1.7B Base model (primary)
-- Qwen3-TTS 1.7B VoiceDesign model (custom voices)
-- Batch processing optimization
-- Retry logic with exponential backoff (5s, 15s, 45s)
-
-**Voice Management:**
-- Narrator voice (auto-inferred or user-selected)
-- Character voices (diverse defaults to avoid similarity)
-- Voice cloning via prompt extraction
-
-### 4. Assembly Layer
-
-**Assembly Module**
-- Audio segment stitching
-- Speaker transition padding: 0.4s
-- Paragraph padding: 0.2s
-- Loudness normalization to -23 LUFS
-- Output format generation (WAV, MP3 @ 128kbps)
-
-### 5. Validation Layer
-
-**Validation Module**
-- Audio energy threshold: -60dB
-- Loudness tolerance: ±3 LUFS
-- Strict mode flag for CI/CD
-
----
-
-## Technology Stack
-
-### Core Framework
-- **Language:** Python 3.11+
-- **ML Framework:** PyTorch 2.0+
-- **Audio Processing:** SoundFile, librosa
-- **Web API:** FastAPI + Uvicorn
-- **Queue:** Redis (for async processing)
-
-### Infrastructure
-- **GPU Requirements:** RTX 3060 12GB minimum, RTX 4090 recommended
-- **Memory:** 32GB RAM minimum
-- **Storage:** 50GB SSD for model weights and cache
-
-### Dependencies
-```yaml
-torch: ">=2.0.0"
-soundfile: ">=0.12.0"
-librosa: ">=0.10.0"
-fastapi: ">=0.104.0"
-uvicorn: ">=0.24.0"
-redis: ">=5.0.0"
-pydub: ">=0.25.0"
-ebooklib: ">=0.18"
-pypdf: ">=3.0.0"
-```
-
----
-
-## Data Flow
-
-1. **Upload:** User uploads epub via CLI or web UI
-2. **Parse:** Text extraction with dialogue annotation
-3. **Analyze:** Genre detection, character identification
-4. **Queue:** Job added to Redis queue
-5. **Process:** GPU worker pulls job, generates audio segments
-6. **Assemble:** Stitch segments with padding, normalize loudness
-7. **Validate:** Check audio quality thresholds
-8. **Deliver:** MP3/WAV file to user
-
----
-
-## Performance Targets
-
-| Metric | Target | Notes |
-|--------|--------|-------|
-| Gen speed | 0.5x real-time | RTX 4090, batch=4 |
-| Quality | -23 LUFS ±1dB | Audiobook standard |
-| Latency | <5 min per chapter | For 20k words |
-| Concurrent users | 10 | With 4 GPU workers |
-
----
-
-## Scalability Considerations
-
-### Phase 1 (MVP - Week 1-4)
-- Single-machine deployment
-- CLI-only interface
-- Local queue (in-memory)
-- Manual GPU provisioning
-
-### Phase 2 (Beta - Week 5-8)
-- FastAPI web interface
-- Redis queue for async jobs
-- Docker containerization
-- Cloud GPU option (RunPod, Lambda Labs)
-
-### Phase 3 (Production - Quarter 2)
-- Kubernetes cluster
-- Auto-scaling GPU workers
-- Multi-region deployment
-- CDN for file delivery
-
----
-
-## Security Considerations
-
-- User audio files stored encrypted at rest
-- API authentication via API keys
-- Rate limiting: 100 requests/hour per tier
-- No third-party data sharing
-
----
-
-## Risks & Mitigations
-
-| Risk | Impact | Mitigation |
-|------|--------|------------|
-| GPU availability | High | Cloud GPU partnerships, queue-based scaling |
-| Model quality variance | Medium | Human review workflow for premium tier |
-| Format parsing edge cases | Low | Extensive test suite, graceful degradation |
-| Competition from big players | Medium | Focus on indie author niche, character voices |
-
----
-
-## Next Steps
-
-1. **Week 1:** Set up development environment, create ADRs for key decisions
-2. **Week 2-3:** Implement MVP features (single-narrator, epub, MP3)
-3. **Week 4:** Beta testing with 5-10 indie authors
-4. **Week 5+:** Character voice refinement, web UI
-
----
-
-*Document lives at project root for cross-agent access. Update with ADRs as decisions evolve.*