doc: add design docs for open epics

- Omni/Task/DESIGN.md: Task manager improvements -
Biz/PodcastItLater/DESIGN.md: Architecture and features
- Biz/PodcastItLater/TESTING.md: Test strategy -
Network/Wai/Middleware/Braid/DESIGN.md: Keep-alive design

2 files changed, 88 insertions, 0 deletions

diff --git a/Biz/PodcastItLater/DESIGN.md b/Biz/PodcastItLater/DESIGN.md
new file mode 100644
index 0000000..29c4837
--- /dev/null
+++ b/Biz/PodcastItLater/DESIGN.md
@@ -0,0 +1,43 @@
+# PodcastItLater Design & Architecture
+
+## Overview
+Service converting web articles to podcast episodes via email/web submission.
+
+## Architecture
+- **Web**: `Biz/PodcastItLater/Web.py` (Ludic + HTMX + Starlette)
+- **Worker**: `Biz/PodcastItLater/Worker.py` (Background processing)
+- **Core**: `Biz/PodcastItLater/Core.py` (DB & Shared Logic)
+- **Billing**: `Biz/PodcastItLater/Billing.py` (Stripe Integration)
+
+## Key Features
+1.  **User Management**: Email-based magic links, RSS tokens.
+2.  **Article Processing**: Trafilatura extraction -> LLM cleanup -> TTS.
+3.  **Billing (In Progress)**: Stripe Checkout/Portal, Freemium model.
+
+## Path to Paid Product (Epic: t-143KQl2)
+
+### 1. Billing Infrastructure
+- **Stripe**: Use Stripe Checkout for subs, Portal for management.
+- **Webhooks**: Handle `checkout.session.completed`, `customer.subscription.*`.
+- **Tiers**:
+    - `Free`: 10 articles/month.
+    - `Paid`: Unlimited (initially).
+
+### 2. Usage Tracking
+- **Table**: `users` table needs `plan_tier`, `subscription_status`, `stripe_customer_id`.
+- **Logic**: Check usage count vs tier limit before allowing submission.
+- **Reset**: Usage counters reset at billing period boundary.
+
+### 3. Admin Dashboard
+- View all users and their status.
+- Manually retry/delete jobs.
+- View metrics (signups, conversions).
+
+## UX Polish (Epic: t-1vIPJYG)
+- **Mobile**: Ensure all pages work on mobile.
+- **Feedback**: Better error messages for failed URLs.
+- **Navigation**: Clean up navbar, account management access.
+
+## Audio Improvements
+- **Intro/Outro**: Add metadata-rich intro ("Title by Author").
+- **Sound Design**: Crossfade intro music.
diff --git a/Biz/PodcastItLater/TESTING.md b/Biz/PodcastItLater/TESTING.md
new file mode 100644
index 0000000..2911610
--- /dev/null
+++ b/Biz/PodcastItLater/TESTING.md
@@ -0,0 +1,45 @@
+# PodcastItLater Testing Strategy
+
+## Overview
+We use `pytest` with `Omni.Test` integration. Tests are co-located with code or in `Biz/PodcastItLater/Test.py` for E2E.
+
+## Test Categories
+
+### 1. Core (Database/Logic)
+- **Location**: `Biz/PodcastItLater/Core.py`
+- **Scope**: User creation, Job queue ops, Episode management.
+- **Key Tests**:
+    - `test_create_user`: Unique tokens.
+    - `test_queue_isolation`: Users see only their jobs.
+
+### 2. Web (HTTP/UI)
+- **Location**: `Biz/PodcastItLater/Web.py`
+- **Scope**: Routes, Auth, HTMX responses.
+- **Key Tests**:
+    - `test_submit_requires_auth`.
+    - `test_rss_feed_xml`.
+    - `test_admin_access_control`.
+
+### 3. Worker (Processing)
+- **Location**: `Biz/PodcastItLater/Worker.py`
+- **Scope**: Extraction, TTS, S3 upload.
+- **Key Tests**:
+    - `test_extract_content`: Mocked network calls.
+    - `test_tts_chunking`: Handle long text.
+    - **Error Handling**: Ensure retries work and errors are logged.
+
+### 4. Billing (Stripe)
+- **Location**: `Biz/PodcastItLater/Billing.py`
+- **Scope**: Webhook processing, Entitlement checks.
+- **Key Tests**:
+    - `test_webhook_subscription_update`: Update local DB.
+    - `test_enforce_limits`: Block submission if over limit.
+
+## Running Tests
+```bash
+# Run all
+bild --test Biz/PodcastItLater.hs
+
+# Run specific file
+./Biz/PodcastItLater/Web.py test
+```