diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index 1c564e0c88..0f9df888fc 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -5,7 +5,7 @@ mode: subagent
 
 **New to aidevops?** Type `/onboarding` to get started with an interactive setup wizard.
 
-**Supported tools:** [OpenCode](https://opencode.ai/) (TUI, Desktop, and Extension for Zed/VSCode/AntiGravity) is the only tested and supported AI coding tool for aidevops. The claude-code CLI is used as a companion tool called from within OpenCode. aidevops is also available in the Claude marketplace.
+**Supported tools:** [OpenCode](https://opencode.ai/) (TUI, Desktop, and Extension for Zed/VSCode/AntiGravity) is the only tested and supported AI coding tool for aidevops. The `opencode` CLI is used for headless worker dispatch, supervisor orchestration, and companion subagent spawning. aidevops is also available in the Claude marketplace.
 
 **Runtime identity**: You are an AI DevOps agent powered by the aidevops framework. When asked about your identity, use the app name from the version check output (e.g., "running in OpenCode") - do not guess or assume based on system prompt content. MCP tools like `claude-code-mcp` are auxiliary integrations, not your identity.
 
@@ -201,6 +201,32 @@ worktree-helper.sh add feature/x  # Fallback
 
 **Full docs**: `workflows/git-workflow.md`, `tools/git/worktrunk.md`
 
+## Autonomous Orchestration
+
+**CLI**: `opencode` is the ONLY supported CLI for worker dispatch. Never use `claude` CLI.
+
+**Supervisor** (`supervisor-helper.sh`): Manages parallel task execution with SQLite state machine.
+
+```bash
+# Add tasks and create batch
+supervisor-helper.sh add t001 --repo "$(pwd)" --description "Task description"
+supervisor-helper.sh batch "my-batch" --concurrency 3 --tasks "t001,t002,t003"
+
+# Install cron pulse (REQUIRED for autonomous operation)
+supervisor-helper.sh cron install
+
+# Manual pulse (cron does this automatically every 2 minutes)
+supervisor-helper.sh pulse --batch <batch-id>
+
+# Monitor
+supervisor-helper.sh dashboard --batch <batch-id>
+supervisor-helper.sh status <batch-id>
+```
+
+**Cron pulse is mandatory** for autonomous operation. Without it, the supervisor is passive and requires manual `pulse` calls. The pulse cycle: check workers -> evaluate outcomes -> dispatch next -> cleanup.
+
+**Full docs**: `tools/ai-assistants/headless-dispatch.md`, `supervisor-helper.sh help`
+
 ## Session Completion
 
 Run `/session-review` before ending. Suggest new sessions after PR merge, domain switch, or 3+ hours.
@@ -239,6 +265,7 @@ Orchestration agents can create drafts in `draft/` for reusable parallel process
 | Video | `tools/video/video-prompt-design.md`, `tools/video/remotion.md`, `tools/video/higgsfield.md` |
 | Voice | `tools/voice/speech-to-speech.md`, `voice-helper.sh talk` (voice bridge) |
 | Parallel agents | `tools/ai-assistants/headless-dispatch.md`, `tools/ai-assistants/runners/` |
+| Orchestration | `supervisor-helper.sh` (batch dispatch, cron pulse, self-healing) |
 | MCP dev | `tools/build-mcp/build-mcp.md` |
 | Agent design | `tools/build-agent/build-agent.md` |
 | Framework | `aidevops/architecture.md` |
diff --git a/.agents/scripts/agent-test-helper.sh b/.agents/scripts/agent-test-helper.sh
index dcc56c26bf..9ba6266ffc 100755
--- a/.agents/scripts/agent-test-helper.sh
+++ b/.agents/scripts/agent-test-helper.sh
@@ -60,17 +60,18 @@ readonly SUITES_DIR="${TEST_DIR}/suites"
 readonly RESULTS_DIR="${TEST_DIR}/results"
 readonly BASELINES_DIR="${TEST_DIR}/baselines"
 
-# CLI detection
+# CLI detection - opencode is the primary and only supported CLI
 detect_cli() {
     local cli="${AGENT_TEST_CLI:-}"
     if [[ -n "$cli" ]]; then
         echo "$cli"
         return 0
     fi
-    if command -v claude >/dev/null 2>&1; then
-        echo "claude"
-    elif command -v opencode >/dev/null 2>&1; then
+    if command -v opencode >/dev/null 2>&1; then
         echo "opencode"
+    elif command -v claude >/dev/null 2>&1; then
+        # DEPRECATED: claude CLI fallback - install opencode instead
+        echo "claude"
     else
         echo ""
     fi
diff --git a/.agents/scripts/pre-edit-check.sh b/.agents/scripts/pre-edit-check.sh
index c9116cd4e0..d3e89c1306 100755
--- a/.agents/scripts/pre-edit-check.sh
+++ b/.agents/scripts/pre-edit-check.sh
@@ -78,6 +78,10 @@ is_docs_only() {
     return 1
 }
 
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
 BOLD='\033[1m'
 
 # Check if we're in a git repository
diff --git a/.agents/scripts/supervisor-helper.sh b/.agents/scripts/supervisor-helper.sh
index 788f7b0022..9cb622cb6c 100755
--- a/.agents/scripts/supervisor-helper.sh
+++ b/.agents/scripts/supervisor-helper.sh
@@ -64,6 +64,17 @@
 #   - Mail: mail-helper.sh for escalation
 #   - Memory: memory-helper.sh for cross-batch learning
 #   - Git: wt/worktree-helper.sh for isolation
+#
+# IMPORTANT - Orchestration Requirements:
+#   - CLI: opencode is the ONLY supported CLI for worker dispatch.
+#     claude CLI fallback is DEPRECATED and will be removed.
+#     Install: npm i -g opencode (https://opencode.ai/)
+#   - Cron pulse: For autonomous operation, install the cron pulse:
+#       supervisor-helper.sh cron install
+#     This runs `pulse` every 2 minutes to check/dispatch/evaluate workers.
+#     Without cron, the supervisor is passive and requires manual `pulse` calls.
+#   - Batch lifecycle: add tasks -> create batch -> cron pulse handles the rest
+#     The pulse cycle: check workers -> evaluate outcomes -> dispatch next -> cleanup
 
 set -euo pipefail
 
@@ -236,7 +247,7 @@ check_system_load() {
     process_count=$(ps aux 2>/dev/null | wc -l | tr -d ' ')
     echo "process_count=$process_count"
 
-    # Supervisor worker process count (opencode/claude spawned by supervisor)
+    # Supervisor worker process count (opencode workers spawned by supervisor)
     local supervisor_process_count=0
     if [[ -d "$SUPERVISOR_DIR/pids" ]]; then
         for pid_file in "$SUPERVISOR_DIR/pids"/*.pid; do
@@ -1718,25 +1729,30 @@ detect_dispatch_mode() {
 
 #######################################
 # Resolve the AI CLI tool to use for dispatch
-# Prefers opencode, falls back to claude
+# Resolve AI CLI for worker dispatch
+# opencode is the ONLY supported CLI for aidevops supervisor workers.
+# claude CLI fallback is DEPRECATED and will be removed in a future release.
 #######################################
 resolve_ai_cli() {
-    # Prefer opencode (supports Anthropic auth + zen free models as fallback)
+    # opencode is the primary and only supported CLI
     if command -v opencode &>/dev/null; then
         echo "opencode"
         return 0
     fi
+    # DEPRECATED: claude CLI fallback - will be removed
     if command -v claude &>/dev/null; then
+        log_warning "Using deprecated claude CLI fallback. Install opencode: npm i -g opencode"
         echo "claude"
         return 0
     fi
-    log_error "Neither opencode nor claude CLI found. Install one to dispatch workers."
+    log_error "opencode CLI not found. Install it: npm i -g opencode"
+    log_error "See: https://opencode.ai/docs/installation/"
     return 1
 }
 
 #######################################
 # Resolve the best available model for a given task tier
-# Priority: Anthropic SOTA via opencode > claude CLI > opencode zen free
+# Priority: Anthropic SOTA via opencode (only supported CLI)
 #
 # Tiers:
 #   coding  - Best SOTA model for code tasks (default)
@@ -2100,7 +2116,7 @@ _list_descendants() {
 
 #######################################
 # Kill all orphaned worker processes (emergency cleanup)
-# Finds opencode/claude processes with PPID=1 that match supervisor patterns
+# Finds opencode worker processes with PPID=1 that match supervisor patterns
 #######################################
 cmd_kill_workers() {
     local dry_run=false
@@ -2151,7 +2167,7 @@ cmd_kill_workers() {
 
     log_info "Protected PIDs (active workers + self): $(echo "$protected_pattern" | tr '|' ' ' | wc -w | tr -d ' ') processes"
 
-    # Find orphaned opencode/claude processes (PPID=1, not in any terminal session)
+    # Find orphaned opencode worker processes (PPID=1, not in any terminal session)
     local orphan_count=0
     local killed_count=0
 
diff --git a/.agents/seo/mom-test-ux.md b/.agents/seo/mom-test-ux.md
new file mode 100644
index 0000000000..62ed9b51ae
--- /dev/null
+++ b/.agents/seo/mom-test-ux.md
@@ -0,0 +1,132 @@
+---
+description: "Mom Test UX evaluation - Apple-inspired 'Would this confuse my mom?' usability and CRO analysis. Use when the user wants a UX audit, usability review, conversion friction analysis, or asks why users aren't converting."
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  webfetch: true
+---
+
+# Mom Test UX / CRO Agent
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Evaluate any page/screen with "Would this confuse my mom?" heuristic
+- **Philosophy**: If a non-technical person can't complete the task in under 10 seconds of thought, the UX has failed
+- **Input**: URL, screenshot, or ARIA snapshot
+- **Output**: Actionable fix table with severity, effort, and impact ratings
+
+## The 6 UX Principles
+
+Every element is evaluated against these principles:
+
+| # | Principle | Mom Test Question |
+|---|-----------|-------------------|
+| 1 | **Clarity** | "What is this page asking me to do?" |
+| 2 | **Simplicity** | "Why are there so many things on this screen?" |
+| 3 | **Consistency** | "This button looked different on the last page?" |
+| 4 | **Feedback** | "Did anything happen when I clicked that?" |
+| 5 | **Discoverability** | "Where do I go to find X?" |
+| 6 | **Forgiveness** | "I clicked the wrong thing - how do I go back?" |
+
+## Severity Ranking
+
+| Level | Label | Definition | Example |
+|-------|-------|------------|---------|
+| S1 | **Blocker** | User cannot complete the task | CTA invisible, form broken, dead click |
+| S2 | **Major** | User completes task but with significant confusion | Ambiguous labels, hidden pricing, unclear next step |
+| S3 | **Minor** | User notices friction but works through it | Inconsistent styling, slow feedback, extra clicks |
+| S4 | **Polish** | Professional refinement | Spacing, micro-copy tone, animation timing |
+
+<!-- AI-CONTEXT-END -->
+
+## Workflow
+
+### Step 1: Capture the Page
+
+Use browser automation to get the page state:
+
+```bash
+# ARIA snapshot (preferred - fast, structured, no vision tokens)
+playwright screenshot --aria-snapshot https://example.com/pricing
+
+# Full screenshot (for layout/visual issues)
+playwright screenshot https://example.com/pricing --full-page
+```
+
+Or use Stagehand/Playwright programmatically. For manual review, the user provides the URL and you fetch with `webfetch`.
+
+### Step 2: Screen-by-Screen Analysis
+
+For each screen/page, generate the findings table:
+
+| Confusing Element | Mom's Reaction | Principle | Severity | Fix |
+|-------------------|----------------|-----------|----------|-----|
+| CTA says "Get Started" with no context | "Get started with what?" | Clarity | S2 | Change to "Start Free 14-Day Trial" |
+| Three pricing tiers with 20+ feature rows | "I don't know which one I need" | Simplicity | S2 | Highlight recommended plan, collapse features into "Most popular for..." |
+| Form shows no error until submit | "Did it work? Nothing happened" | Feedback | S1 | Add inline validation on blur |
+| Navigation has "Solutions" dropdown with 12 items | "I just want to see what you do" | Discoverability | S3 | Reduce to 4-5 grouped categories |
+| No back button in checkout flow | "I'm stuck, I'll just leave" | Forgiveness | S1 | Add breadcrumb and back navigation |
+
+### Step 3: Quick Wins Matrix
+
+Prioritise fixes by effort vs. impact:
+
+| Fix | Impact | Effort | Priority |
+|-----|--------|--------|----------|
+| Rewrite CTA copy | High | 10 min | **Do first** |
+| Add inline form validation | High | 2-4 hrs | **Do first** |
+| Add breadcrumb nav | Medium | 1-2 hrs | **Schedule** |
+| Redesign pricing table | High | 1-2 days | **Plan** |
+| Adjust spacing/polish | Low | 30 min | **Batch later** |
+
+Priority rules: High impact + Low effort = Do first. High impact + High effort = Plan. Low impact = Batch later.
+
+### Step 4: CRO Recommendations
+
+Apply proven UX patterns that directly improve conversion:
+
+| Pattern | Why It Works | Implementation |
+|---------|-------------|----------------|
+| Single primary CTA per viewport | Reduces decision paralysis | Remove competing links near the main action |
+| Social proof near decision point | Reduces anxiety at commitment | Add testimonial/count badge within 200px of CTA |
+| Progress indicator on multi-step flows | Sets expectation, reduces abandonment | "Step 2 of 3" breadcrumb bar |
+| Benefit-first headlines | Answers "what's in it for me" instantly | Replace feature-speak with outcome language |
+| Friction logging | Quantifies UX debt | Track rage clicks, dead clicks, U-turns in analytics |
+
+## Browser Automation Integration
+
+### Automated UX Scan
+
+Use Playwright to programmatically check for common Mom Test failures:
+
+1. **ARIA snapshot** - Parse `page.accessibility.snapshot()` for structure issues
+2. **Hidden CTAs** - Query `button, a[href]` and flag any with `offsetParent === null`
+3. **Vague link text** - Flag buttons/links with text like "Click here", "Learn more", "Submit"
+4. **Unlabelled inputs** - Find `input` elements missing `<label>` and `aria-label`
+5. **Missing feedback** - Check forms for absence of `aria-live` regions or inline validation
+
+Each finding maps to a severity (S1-S4) and principle (Clarity/Simplicity/etc).
+
+## Output Format
+
+The final report follows this structure:
+
+1. **One-line verdict**: Pass / Needs Work / Fail (with overall severity)
+2. **Findings table**: Every issue with Severity, Principle, Mom's Reaction, Fix
+3. **Quick wins**: Sorted by impact/effort, with time estimates
+4. **CRO opportunities**: Patterns applicable to this specific page
+5. **Accessibility flags**: Any WCAG violations found during analysis (cross-ref `seo/seo-audit-skill.md`)
+
+Every fix must be **specific and implementable** - not "improve the copy" but "Change H1 from 'Welcome to Our Platform' to 'Ship 2x Faster With Zero DevOps'".
+
+## Related
+
+- `seo/seo-audit-skill.md` - Full SEO audit (references page-cro for conversion)
+- `seo/analytics-tracking.md` - Measure UX improvements with event tracking
+- `tools/browser/browser-automation.md` - Browser tool selection for page analysis
+- `seo/programmatic-seo.md` - Applying UX patterns at scale across generated pages
diff --git a/.agents/tools/content/content-calendar.md b/.agents/tools/content/content-calendar.md
new file mode 100644
index 0000000000..c8449b4e5e
--- /dev/null
+++ b/.agents/tools/content/content-calendar.md
@@ -0,0 +1,131 @@
+---
+description: Content calendar planning with AI-powered gap analysis and lifecycle tracking
+mode: subagent
+tools:
+  read: true
+  write: true
+  bash: true
+---
+
+# Content Calendar Workflow
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Plan, schedule, and track content across platforms with AI-driven topic discovery
+- **Workflow**: Gap analysis -> topic clustering -> calendar planning -> lifecycle tracking
+- **Related**: `seo/keyword-research.md`, `seo/google-search-console.md`, `tools/content/guidelines.md`
+- **Calendar file**: `TODO.md` or `todo/content-calendar.md` (markdown-based, task-compatible)
+
+## Content Gap Analysis
+
+Use keyword research data to identify missing coverage:
+
+1. **Export GSC data**: Pull queries from `google-search-console.md` (impressions without clicks = gap)
+2. **Cluster keywords**: Group by parent topic using `keyword-research.md` SERP similarity
+3. **Audit existing content**: Map published URLs to keyword clusters, flag uncovered clusters
+4. **Competitor gap**: Compare covered topics against competitor sitemaps/rankings
+5. **Prioritize**: Score by `search_volume * (1 - current_coverage) * business_relevance`
+
+```bash
+# Extract high-impression, low-CTR queries as content gaps (see seo/google-search-console.md)
+gsc-helper.sh query-report --min-impressions 500 --max-ctr 0.02 --days 90
+```
+
+## Topic Suggestions & Clustering
+
+Organize topics into **pillars** (broad authority pages) and **clusters** (supporting articles):
+
+| Layer | Type | Example | Word Count |
+|-------|------|---------|------------|
+| Pillar | Comprehensive guide | "Complete Guide to CI/CD" | 3000-5000 |
+| Cluster | Supporting article | "GitHub Actions vs GitLab CI" | 1500-2500 |
+| Satellite | Quick reference | "Docker Compose Cheatsheet" | 500-1000 |
+
+**Search intent mapping**: Assign each topic an intent to guide format:
+
+| Intent | Format | CTA |
+|--------|--------|-----|
+| Informational | How-to, guide, explainer | Newsletter, related post |
+| Commercial | Comparison, review, "best X" | Free trial, demo |
+| Transactional | Landing page, pricing | Purchase, sign up |
+| Navigational | Documentation, FAQ | Product link, support |
+
+## Calendar Structure
+
+```markdown
+## Week of YYYY-MM-DD
+
+- [ ] MON: Draft "Topic A" (cluster: CI/CD) @author #blog ~3h
+- [ ] WED: Publish "Topic A" + social adapts @editor #publish
+- [ ] THU: LinkedIn post (Topic A excerpt) @social #linkedin
+- [ ] FRI: X thread (Topic A key points) @social #twitter
+```
+
+**Monthly overview**:
+
+| Week | Pillar Focus | Blog | Social | Video | Email |
+|------|-------------|------|--------|-------|-------|
+| 1 | DevOps | Publish 1 | 3 posts | - | Newsletter |
+| 2 | AI/ML | Publish 1 | 3 posts | 1 short | - |
+| 3 | Security | Publish 1 | 3 posts | - | Newsletter |
+| 4 | Community | Publish 1 | 3 posts | 1 long | Monthly recap |
+
+Rotate pillar focus monthly. Maintain 2:1 ratio of cluster-to-pillar content.
+
+## Content Lifecycle: `ideation -> draft -> review -> publish -> promote -> analyze`
+
+| Stage | Duration | Exit Criteria |
+|-------|----------|---------------|
+| `#ideation` | 1-2 days | Keyword assigned, outline approved |
+| `#draft` | 2-5 days | First draft complete, meets word count |
+| `#review` | 1-2 days | SEO check, brand voice, fact-check |
+| `#publish` | 1 day | Live URL, schema markup, internal links |
+| `#promote` | 5-7 days | Cross-platform adapts posted (see guidelines.md) |
+| `#analyze` | 14-30 days | GSC impressions/clicks, engagement metrics |
+
+**Task format** (TODO.md compatible):
+
+```markdown
+- [ ] t101 "CI/CD Pipeline Guide" @marcus #draft ~4h pillar:devops started:2025-01-15
+- [x] t102 "Docker vs Podman" @marcus #publish ~2h cluster:containers done:2025-01-18
+```
+
+## Platform Scheduling
+
+Optimal posting windows (adjust per audience analytics):
+
+| Platform | Best Days | Times (UTC) | Frequency |
+|----------|-----------|------------|-----------|
+| Blog | Tue-Thu | 09:00-11:00 | 1-2/week |
+| LinkedIn | Tue-Thu | 07:00-08:30 | 3-5/week |
+| X/Twitter | Mon-Fri | 12:00-15:00 | 1-3/day |
+| YouTube | Thu-Sat | 14:00-16:00 | 1-2/week |
+| Instagram | Mon, Wed, Fri | 11:00-13:00 | 3-5/week |
+| Newsletter | Tue or Thu | 10:00 | 1-2/month |
+
+**Stagger rule**: Blog publishes first. Social adaptations follow over 5-7 days per `guidelines.md` repurposing workflow.
+
+## Content Pillars Strategy
+
+Define 3-5 pillars that map to business goals. Every cluster links to its pillar; pillars link to all children. Cross-link related clusters (3-5 internal links per post). Update pillar pages quarterly.
+
+```text
+Pillar: "DevOps Automation"
+├── Cluster: CI/CD pipelines (8 articles)
+├── Cluster: Infrastructure as Code (6 articles)
+├── Cluster: Monitoring & Observability (5 articles)
+└── Cluster: Security & Compliance (4 articles)
+```
+
+## Integration Points
+
+| Tool | Purpose | Command/Reference |
+|------|---------|-------------------|
+| Keyword Research | Topic discovery, volume data | `seo/keyword-research.md` |
+| GSC | Performance tracking, gap detection | `seo/google-search-console.md` |
+| Content Guidelines | Platform voice and format specs | `tools/content/guidelines.md` |
+| TODO.md | Task tracking integration | Root `TODO.md` with `#content` tag |
+
+<!-- AI-CONTEXT-END -->
diff --git a/.agents/tools/content/docstrange.md b/.agents/tools/content/docstrange.md
new file mode 100644
index 0000000000..ad1d378abc
--- /dev/null
+++ b/.agents/tools/content/docstrange.md
@@ -0,0 +1,121 @@
+---
+description: Document structured data extraction with DocStrange (NanoNets)
+mode: subagent
+tools:
+  read: true
+  bash: true
+---
+
+# DocStrange
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Extract structured data from documents (PDF, DOCX, PPTX, XLSX, images, URLs)
+- **Install**: `pip install docstrange` (Python 3.8+, MIT license)
+- **Repo**: <https://github.com/NanoNets/docstrange> (1.3k stars)
+- **Output**: Markdown, JSON, CSV, HTML
+- **Modes**: Cloud API (free 10k docs/month) or local GPU (100% private, CUDA required)
+
+<!-- AI-CONTEXT-END -->
+
+## Supported Formats
+
+| Category | Types |
+|----------|-------|
+| **Documents** | PDF, DOCX, DOC, PPTX, PPT |
+| **Spreadsheets** | XLSX, XLS, CSV |
+| **Images** | PNG, JPG, JPEG, TIFF, BMP |
+| **Web** | HTML, HTM, URLs |
+| **Text** | TXT |
+
+## Schema-Based Extraction
+
+```python
+from docstrange import DocumentExtractor
+
+extractor = DocumentExtractor()  # cloud mode (default)
+result = extractor.extract("invoice.pdf")
+
+# Method 1: Specify fields to extract
+fields = result.extract_data(specified_fields=[
+    "invoice_number", "total_amount", "vendor_name", "due_date"
+])
+
+# Method 2: Enforce a JSON schema
+schema = {
+    "invoice_number": "string",
+    "total_amount": "number",
+    "vendor_name": "string",
+    "line_items": [{"description": "string", "amount": "number"}]
+}
+structured = result.extract_data(json_schema=schema)
+```
+
+## Processing Modes
+
+| Mode | Init | Privacy | Requires |
+|------|------|---------|----------|
+| **Cloud (default)** | `DocumentExtractor()` | Data sent to NanoNets API | Internet |
+| **Cloud (auth)** | `DocumentExtractor(api_key="...")` | Same, 10k docs/month | API key |
+| **Local GPU** | `DocumentExtractor(gpu=True)` | 100% private, on-device | CUDA GPU |
+
+```bash
+# CLI usage
+docstrange document.pdf --output json --extract-fields invoice_number total_amount
+docstrange document.pdf --gpu-mode  # local processing
+docstrange document.pdf --output json --json-schema schema.json
+```
+
+## MCP Server (Claude Desktop)
+
+The MCP server is in the repo but **not** in the PyPI package. Clone to use it.
+
+```bash
+git clone https://github.com/nanonets/docstrange.git
+pip install -e ".[dev]"
+```
+
+Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "docstrange": {
+      "command": "python3",
+      "args": ["/path/to/docstrange/mcp_server_module/server.py"]
+    }
+  }
+}
+```
+
+Features: token-aware navigation, hierarchical chunking, document search.
+
+## Common Patterns
+
+- **Invoice**: `specified_fields=["invoice_number", "vendor_name", "total_amount", "due_date", "line_items"]`
+- **Contract**: `json_schema={"parties": ["string"], "contract_value": "number", "start_date": "string", "end_date": "string", "key_terms": ["string"]}`
+- **Receipt**: `specified_fields=["merchant_name", "total_amount", "date", "payment_method"]`
+- **Batch CLI**: `docstrange *.pdf --output json --extract-fields title author date summary`
+
+## Comparison with Docling + ExtractThinker + Presidio (t073)
+
+| Aspect | DocStrange | Docling + ExtractThinker + Presidio |
+|--------|------------|-------------------------------------|
+| **Install** | `pip install docstrange` (single pkg) | 3-4 packages + spaCy model + Ollama |
+| **Schema** | JSON dict with type hints | Pydantic models (stronger typing) |
+| **PII redaction** | None built-in | Presidio (50+ entity types) |
+| **Local LLM** | Built-in 7B model (GPU mode) | BYO via Ollama (any model) |
+| **OCR quality** | Upgraded 7B model, multi-engine | Docling (EasyOCR/Tesseract) |
+| **MCP server** | Included (clone repo) | Not included |
+| **Cloud tier** | Free 10k docs/month | No cloud option |
+| **Best for** | Quick extraction, cloud+local hybrid | Custom pipelines, PII compliance |
+
+**Recommendation**: Use DocStrange for straightforward document-to-JSON extraction where PII redaction is not required. Use the Docling+ExtractThinker+Presidio stack (t073) when you need Pydantic-typed contracts, PII anonymization, or full control over the LLM backend. The two can complement each other -- DocStrange for rapid prototyping, t073 stack for production pipelines with privacy requirements.
+
+## Related
+
+- `tools/document/document-extraction.md` - Docling + ExtractThinker + Presidio stack
+- `tools/document/pandoc-helper.sh` - Format conversion
+- `tools/document/mineru.md` - Alternative PDF extraction (MinerU)
diff --git a/.agents/tools/content/guidelines.md b/.agents/tools/content/guidelines.md
new file mode 100644
index 0000000000..410932462e
--- /dev/null
+++ b/.agents/tools/content/guidelines.md
@@ -0,0 +1,129 @@
+---
+description: Platform-specific content persona adaptations and publishing guidelines
+mode: subagent
+tools:
+  read: true
+  write: true
+---
+
+# Content Persona Guidelines
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Adapt voice, tone, and format per platform while maintaining brand consistency
+- **Workflow**: Draft core message -> adapt per platform -> cross-link -> schedule
+- **Related**: `tools/social-media/bird.md`, `tools/social-media/linkedin.md`, `tools/content/content-calendar.md`
+
+## LinkedIn Persona
+
+**Tone**: Professional, authoritative, conversational where appropriate.
+
+| Element | Guideline |
+|---------|-----------|
+| Optimal length | 1300 characters (~200 words) for feed posts |
+| Structure | Hook line -> insight -> supporting data -> CTA |
+| Content types | Thought leadership, industry analysis, case studies, carousel docs |
+| Hashtags | 3-5 relevant, mix niche + broad (e.g., `#DevOps #AIAutomation`) |
+| Posting cadence | 3-5x/week, Tuesday-Thursday mornings perform best |
+
+**Do**: Share original insights, tag people/companies, use line breaks for readability.
+**Don't**: Use excessive emojis, cross-post tweets verbatim, ignore comments.
+
+## Instagram Persona
+
+**Tone**: Visual-first, approachable, behind-the-scenes authenticity.
+
+| Element | Guideline |
+|---------|-----------|
+| Caption length | 125-150 chars for feed (first line is hook), up to 2200 max |
+| Hashtags | 20-30 per post, mix of sizes (5 large, 10 medium, 15 niche) |
+| Stories | Daily, use polls/questions/countdowns for engagement |
+| Reels | 15-60s, hook in first 3s, text overlays, trending audio |
+| Carousel | 5-10 slides, educational content, save-worthy tips |
+
+**Hashtag strategy**: Research via Explorer, rotate sets, save 5 groups of 30 in templates.
+Place hashtags in first comment or end of caption (test both for reach).
+
+## YouTube Persona
+
+**Tone**: Educational, engaging, structured for retention.
+
+| Element | Guideline |
+|---------|-----------|
+| Title | 60 chars max, keyword-front-loaded, curiosity gap or number |
+| Description | 200+ words, links in first 3 lines, keyword-rich summary |
+| Timestamps | Required for 10min+ videos, improves SEO and retention |
+| Tags | 10-15, mix broad + specific, include common misspellings |
+| Thumbnails | High contrast, face + text overlay, consistent brand style |
+
+**Description structure**:
+
+```text
+Line 1-3: Key links (website, social, mentioned tools)
+Line 4-8: Video summary with target keywords
+Line 9+: Timestamps, credits, affiliate disclosures
+```
+
+**Cards/End screens**: Add cards at natural transition points. End screen in final 20s with subscribe + related video.
+
+## X/Twitter Persona
+
+**Tone**: Concise, opinionated, conversational. Direct value or hot takes.
+
+| Element | Guideline |
+|---------|-----------|
+| Character limit | 280 (standard), 25,000 (Premium) |
+| Thread strategy | 3-7 tweets, number them (1/5), hook in first tweet |
+| Engagement hooks | Questions, polls, controversial takes, "unpopular opinion:" |
+| Media | Images increase engagement 150%, native video > links |
+| Hashtags | 1-2 max per tweet, integrated into sentence when possible |
+
+**Thread template**: Hook (problem) -> Context -> Steps/Insights -> Summary -> CTA with link.
+
+See `tools/social-media/bird.md` for X/Twitter API integration and automation.
+
+## Blog/Website Persona
+
+**Tone**: Long-form, authoritative, SEO-optimized.
+
+| Element | Guideline |
+|---------|-----------|
+| Word count | 1500-2500 for standard, 3000+ for pillar content |
+| Structure | H2/H3 hierarchy, intro with hook, scannable subheadings |
+| Internal linking | 3-5 internal links per post, contextual anchor text |
+| Meta description | 150-160 chars, include primary keyword, compelling CTA |
+| Structured data | Article schema, FAQ schema where applicable, breadcrumbs |
+
+**SEO checklist**: Primary keyword in title + H1 + first 100 words + meta. Secondary keywords in H2s. Image alt text with keywords. URL slug under 60 chars.
+
+## Cross-Platform Repurposing Workflow
+
+Maximize content ROI by adapting one piece across platforms:
+
+```text
+Blog post (pillar)
+  -> LinkedIn article excerpt (key insight + link)
+  -> X/Twitter thread (3-5 key points)
+  -> Instagram carousel (visual summary)
+  -> YouTube video (deep dive or walkthrough)
+  -> Instagram Reel / YouTube Short (single tip, 60s)
+```
+
+**Timing**: Stagger publication across 5-7 days. Blog first, social follows.
+
+## Voice and Tone Consistency
+
+Maintain brand identity across platforms while adapting format:
+
+| Principle | Application |
+|-----------|-------------|
+| Core message | Same key insight, different packaging per platform |
+| Vocabulary | Technical on LinkedIn/blog, simplified on Instagram/X |
+| Personality | Consistent brand voice, adjusted formality per platform |
+| Values | Always present regardless of platform constraints |
+
+**Consistency check**: Before publishing, verify the core message is recognizable across all adapted versions. A reader following on multiple platforms should see coherence, not contradiction.
+
+<!-- AI-CONTEXT-END -->
diff --git a/.agents/tools/deployment/agent-skills.md b/.agents/tools/deployment/agent-skills.md
new file mode 100644
index 0000000000..46ffc14d51
--- /dev/null
+++ b/.agents/tools/deployment/agent-skills.md
@@ -0,0 +1,105 @@
+---
+description: Vercel Agent Skills - community skill packages for AI coding agents
+mode: subagent
+tools:
+  read: true
+  bash: true
+---
+
+# Vercel Agent Skills
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Repo**: [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)
+- **Format**: [Agent Skills](https://agentskills.io/) (SKILL.md standard)
+- **Install**: `npx skills add vercel-labs/agent-skills`
+- **Registry**: [skills.sh](https://skills.sh/vercel-labs/agent-skills)
+- **Related**: `vercel.md` (CLI deployment), `add-skill.md` (import system)
+
+<!-- AI-CONTEXT-END -->
+
+## Available Skills
+
+| Skill | Use When | Impact |
+|-------|----------|--------|
+| `vercel-deploy-claimable` | "Deploy my app", "Push this live" | Instant deploy, no auth |
+| `react-best-practices` | Writing/reviewing React or Next.js code | 40+ rules, 8 categories |
+| `web-design-guidelines` | "Review my UI", "Check accessibility" | 100+ rules across 11 areas |
+| `react-native-guidelines` | Building React Native or Expo apps | 16 rules, 7 sections |
+| `composition-patterns` | Refactoring components with boolean props | Compound component patterns |
+
+## vercel-deploy-claimable
+
+The primary deployment skill. Deploys without Vercel auth via "claimable" URLs.
+
+**How it works:**
+
+1. Packages project as tarball (excludes `node_modules`, `.git`)
+2. Auto-detects framework from `package.json` (40+ frameworks)
+3. Uploads to deployment service
+4. Returns preview URL (live site) + claim URL (transfer ownership)
+
+**Framework detection** includes: Next.js, Remix, Astro, Vite, SvelteKit, Nuxt,
+Angular, Gatsby, Hono, Express, NestJS, Fastify, Storybook, and many more.
+Static HTML projects (no `package.json`) are handled automatically.
+
+## SKILL.md Format Specification
+
+Each skill is a directory containing:
+
+```text
+skill-name/
+  SKILL.md       # Instructions for the agent (required)
+  scripts/       # Helper scripts for automation (optional)
+  references/    # Supporting documentation (optional)
+```
+
+**SKILL.md frontmatter:**
+
+```yaml
+---
+name: skill-name
+description: One sentence describing when to use this skill
+metadata:
+  author: author-name
+  version: "1.0.0"
+---
+```
+
+The body contains agent instructions: how the skill works, usage examples,
+expected output format, and troubleshooting guidance.
+
+## Installation
+
+```bash
+npx skills add vercel-labs/agent-skills          # Native CLI
+aidevops skill add vercel-labs/agent-skills       # aidevops (preferred)
+/add-skill vercel-labs/agent-skills --name vercel-deploy  # With custom name
+```
+
+Skills are auto-detected after installation. The agent uses them when relevant
+tasks are detected (e.g., "deploy my app" triggers vercel-deploy).
+
+## aidevops Integration
+
+The `add-skill-helper.sh` script handles importing Agent Skills:
+
+1. Clones the repo (`git clone --depth 1`)
+2. Detects SKILL.md format, converts frontmatter to aidevops style
+3. Places in `.agents/tools/deployment/` (or category-appropriate directory)
+4. Registers in `.agents/configs/skill-sources.json` for update tracking
+5. `setup.sh` creates symlinks to all AI assistant skill directories
+
+**Naming**: Imported skills get a `-skill` suffix (e.g., `vercel-deploy-skill.md`)
+to distinguish from native subagents. See `tools/build-agent/add-skill.md`.
+
+## When to Use What
+
+| Need | Use |
+|------|-----|
+| Full Vercel CLI (teams, env vars, domains) | `vercel.md` |
+| Quick deploy without auth (claimable) | This skill (`vercel-deploy-claimable`) |
+| Import any community skill | `/add-skill <source>` |
+| Create aidevops-compatible SKILL.md | `scripts/generate-skills.sh` |
diff --git a/.agents/tools/git/jujutsu.md b/.agents/tools/git/jujutsu.md
new file mode 100644
index 0000000000..63f700415c
--- /dev/null
+++ b/.agents/tools/git/jujutsu.md
@@ -0,0 +1,125 @@
+---
+description: Jujutsu (jj) - Git-compatible VCS with working-copy-as-commit, undo, and first-class conflicts
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: false
+  grep: false
+  webfetch: true
+  task: false
+---
+
+# Jujutsu (jj) Guide
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **CLI**: `jj` (Jujutsu) - Git-compatible VCS, written in Rust
+- **Install**: `brew install jj` (macOS) | `cargo install jj-cli` (all platforms)
+- **Repo**: <https://github.com/jj-vcs/jj> (25k+ stars, Apache-2.0)
+- **Docs**: <https://docs.jj-vcs.dev/latest/>
+- **Status**: Experimental but daily-driven by core team; Git backend is stable
+
+## Key Advantages Over Git
+
+### Working-Copy-as-Commit
+
+Every file change is automatically recorded as a commit. No staging area, no index.
+`jj` snapshots the working copy before every command - eliminates "dirty working
+directory" errors, removes the need for `git stash`, and lets you set commit messages
+anytime with `jj describe`.
+
+### Operation Log with Undo
+
+Every repository operation is recorded. `jj op log` shows history, `jj undo` reverses
+the last operation, `jj op restore <op-id>` restores any previous state.
+
+### First-Class Conflicts
+
+Conflicts are stored in commits, not as blocking errors. No command fails due to
+conflicts. Resolve them later at your convenience. Conflict resolutions propagate
+automatically to descendant commits, subsuming most `git rerere` use cases.
+
+### Automatic Rebase of Descendants
+
+Modifying any commit automatically rebases all descendants. Edit a parent and children
+update in place. Equivalent to transparent `git rebase --update-refs`. Bookmark
+(branch) pointers update automatically.
+
+### Anonymous Branches
+
+No need to name every branch. Jujutsu tracks all visible heads of the commit graph.
+Commits are never lost while reachable. Use bookmarks (named branches) only when
+pushing to remotes.
+
+## Essential Commands
+
+```bash
+# Repository setup
+jj git init                  # New jj repo with git backend
+jj git clone <url>           # Clone a git remote
+jj init --git-repo=.         # Colocate: add jj to existing git repo
+
+# Daily workflow
+jj new                       # Start a new change on top of current
+jj describe -m "message"     # Set/update commit message
+jj diff                      # Show changes in working copy
+jj log                       # Show commit graph (rich template output)
+jj status                    # Show working copy status
+
+# Rewriting history
+jj squash                    # Move working copy changes into parent
+jj split                     # Split working copy commit into two
+jj edit <rev>                # Edit an earlier commit (descendants auto-rebase)
+jj rebase -r <rev> -d <dst>  # Rebase a single commit
+jj rebase -s <rev> -d <dst>  # Rebase commit and descendants
+
+# Git interop
+jj git fetch                 # Fetch from git remotes
+jj git push                  # Push bookmarks to git remote
+jj bookmark set main         # Set a bookmark (branch) on current commit
+```
+
+## Colocated Mode (Gradual Adoption)
+
+Run `jj init --git-repo=.` in any existing git repo to use both tools side by side.
+Creates `.jj/` alongside `.git/` - both `jj` and `git` commands work in the same repo,
+reading/writing the same Git objects and refs. Team members continue using git while
+you use jj. Low-risk way to evaluate on real projects.
+
+## Benefits for AI-Assisted Development
+
+- **No staging friction**: File writes are automatically part of the working-copy
+  commit. No `git add` needed - eliminates a common source of agent errors.
+- **Safe experimentation**: `jj undo` reverses any operation instantly. Agents can
+  try approaches and roll back without risk of lost work.
+- **Parallel agent conflicts**: Multiple agents modifying overlapping files produce
+  committed conflicts rather than blocking errors. Resolve asynchronously.
+- **Simpler mental model**: One object type (commits) vs Git's working tree + index +
+  HEAD + stash. Fewer concepts means fewer agent mistakes.
+- **Audit trail**: `jj op log` provides complete operation history for debugging
+  autonomous agent actions in headless workflows.
+
+## Integration with aidevops Worktree Workflow
+
+Colocated mode works alongside `wt` (Worktrunk) worktree workflows. Worktrees created
+by `wt switch -c` are standard git worktrees; colocate each with `jj init --git-repo=.`
+if desired. `jj git push` replaces `git push` using the same remotes. Bookmarks map
+directly to git branches.
+
+**See also**: `tools/git/github-cli.md` (PR and remote workflows),
+`tools/git/conflict-resolution.md` (git conflict strategies),
+`tools/git/worktrunk.md` (worktree management)
+
+## Resources
+
+- [Tutorial](https://docs.jj-vcs.dev/latest/tutorial/)
+- [Git comparison & command table](https://docs.jj-vcs.dev/latest/git-comparison/)
+- [Steve Klabnik's Jujutsu Tutorial](https://steveklabnik.github.io/jujutsu-tutorial/)
+- [Chris Krycho's jj init essay](https://v5.chriskrycho.com/essays/jj-init/)
+
+<!-- AI-CONTEXT-END -->
diff --git a/.agents/tools/git/lumen.md b/.agents/tools/git/lumen.md
new file mode 100644
index 0000000000..2ad8d6943b
--- /dev/null
+++ b/.agents/tools/git/lumen.md
@@ -0,0 +1,106 @@
+---
+description: Lumen - AI-powered git diffs, commit generation, and change explanations
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+---
+
+# Lumen - AI Git Companion
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **CLI Tool**: `lumen` - Beautiful git diff viewer + AI commit messages
+- **Install**: `brew install jnsahaj/lumen/lumen` (macOS/Linux) | `cargo install lumen` (any)
+- **Config**: `~/.config/lumen/lumen.config.json`
+- **Setup**: `lumen configure` (interactive provider/key setup)
+- **Repo**: https://github.com/jnsahaj/lumen (Rust, MIT)
+- **Note**: `lumen diff` works without AI config; AI features need a provider
+
+**Key Commands**:
+
+```bash
+lumen diff                        # Visual side-by-side diff (uncommitted)
+lumen diff HEAD~1                 # Diff for specific commit
+lumen diff main..feature/A        # Branch comparison
+lumen diff --pr 123               # GitHub PR diff
+lumen draft                       # Generate commit message from staged changes
+lumen draft --context "reason"    # Commit message with context hint
+lumen explain                     # AI summary of working directory changes
+lumen explain HEAD~3..HEAD        # Explain last 3 commits
+lumen operate "squash last 3"     # Natural language to git command
+```
+
+<!-- AI-CONTEXT-END -->
+
+## Installation
+
+```bash
+brew install jnsahaj/lumen/lumen   # macOS/Linux
+cargo install lumen                # Any platform with Rust
+brew install fzf mdcat             # Optional: interactive picker + pretty output
+```
+
+## Configuration
+
+Run `lumen configure` for interactive setup, or create `~/.config/lumen/lumen.config.json`:
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-5-mini",
+  "api_key": "your-key-here"
+}
+```
+
+**Precedence** (highest to lowest): CLI flags > `--config` file > project `lumen.config.json` > global config > env vars > defaults.
+
+### API Key Setup
+
+Reuse keys already in `~/.config/aidevops/credentials.sh` or set per-provider env vars:
+
+```bash
+# Environment variables (alternative to config file)
+export LUMEN_AI_PROVIDER="openai"   # or claude, gemini, groq, etc.
+export LUMEN_API_KEY="your-key"
+export LUMEN_AI_MODEL="gpt-5-mini"  # optional, uses provider default
+```
+
+### Supported Providers
+
+`openai` (default), `claude`, `gemini` (free tier), `groq` (free), `deepseek`, `xai`, `ollama` (local, no key), `openrouter`. Run `lumen configure` to select provider and model interactively.
+
+## Additional Options
+
+`lumen diff` extras beyond Quick Reference:
+
+```bash
+lumen diff --watch                  # Auto-refresh on file changes
+lumen diff main..feature --stacked  # Review commits one by one
+lumen diff --file src/main.rs       # Filter to specific files
+lumen diff --theme dracula          # Custom colour theme
+lumen draft | git commit -F -       # Pipe commit message directly
+lumen explain --query "impact?"     # Ask specific questions about changes
+lumen explain --list                # Interactive commit picker (requires fzf)
+```
+
+**Diff keybindings**: `j/k` navigate, `{/}` jump hunks, `tab` sidebar, `space` mark viewed, `i` annotate, `e` open in editor, `?` all keys.
+
+## When to Use Lumen
+
+- **Pre-commit review**: `lumen diff` to review, then `lumen draft` for the commit message
+- **PR review**: `lumen diff --pr 123` for visual side-by-side review alongside `gh pr view`
+- **Understanding AI-generated changes**: `lumen explain --staged` before committing agent output
+- **Commit message generation**: `lumen draft --context "task description"` for conventional commits
+- **Complex git ops**: `lumen operate "description"` instead of memorising git syntax
+- **Stacked review**: `lumen diff main..feature --stacked` to review commits one by one
+- **Conflict resolution**: Use `lumen diff` to visualise merge conflicts (see `conflict-resolution.md`)
+
+## See Also
+
+- `conflict-resolution.md` - Git conflict resolution strategies
+- `github-cli.md` - GitHub CLI for PRs, issues, and releases
diff --git a/.agents/tools/mobile/axe-cli.md b/.agents/tools/mobile/axe-cli.md
new file mode 100644
index 0000000000..ef3d184961
--- /dev/null
+++ b/.agents/tools/mobile/axe-cli.md
@@ -0,0 +1,112 @@
+---
+description: AXe - CLI tool for iOS Simulator automation via Apple's Accessibility APIs and HID
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: false
+  grep: false
+  webfetch: false
+  task: false
+---
+
+# AXe - iOS Simulator Automation CLI
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Automate iOS Simulators using Apple's Accessibility APIs and HID
+- **Install**: `brew install cameroncooke/axe/axe`
+- **Architecture**: Single binary CLI, no server or daemon required
+- **Requirements**: macOS with Xcode and iOS Simulator
+- **GitHub**: https://github.com/cameroncooke/AXe (MIT, by XcodeBuildMCP author)
+
+**Why AXe over idb**: Single binary (no client/server), focused on UI automation,
+no external dependencies, complete HID coverage plus gesture presets and timing controls.
+
+<!-- AI-CONTEXT-END -->
+
+## Core Commands
+
+All commands require `--udid SIMULATOR_UDID`. Get UDIDs with `axe list-simulators`.
+
+### Touch, Gestures, and Input
+
+```bash
+# Tap by coordinates, accessibility ID, or label
+axe tap -x 100 -y 200 --udid $UDID
+axe tap --id "Safari" --udid $UDID
+axe tap --label "Submit" --udid $UDID
+# Swipe with configurable duration and delta
+axe swipe --start-x 100 --start-y 300 --end-x 300 --end-y 100 --udid $UDID
+# Gesture presets: scroll-up/down/left/right,
+#   swipe-from-{left,right,top,bottom}-edge
+axe gesture scroll-down --udid $UDID
+axe gesture swipe-from-left-edge --udid $UDID
+# Text input (direct, stdin, or file)
+axe type 'Hello World!' --udid $UDID
+echo "text" | axe type --stdin --udid $UDID
+```
+
+### Hardware Buttons and Timing
+
+```bash
+# Buttons: home, lock, side-button, siri, apple-pay
+axe button home --udid $UDID
+axe button lock --duration 2.0 --udid $UDID
+# Pre/post delays on any touch/gesture command (seconds)
+axe tap -x 100 -y 200 --pre-delay 1.0 --post-delay 0.5 --udid $UDID
+```
+
+### Screenshots, Video, and Accessibility
+
+```bash
+axe screenshot --output ~/Desktop/capture.png --udid $UDID    # path printed to stdout
+axe record-video --udid $UDID --fps 15 --output recording.mp4 # Ctrl+C to stop
+# Stream formats: mjpeg, ffmpeg, raw, bgra
+axe stream-video --udid $UDID --fps 30 --format ffmpeg | \
+  ffmpeg -f image2pipe -framerate 30 -i - -c:v libx264 output.mp4
+# Accessibility tree (full screen or specific point)
+axe describe-ui --udid $UDID
+axe describe-ui --point 100,200 --udid $UDID
+```
+
+## AXe CLI vs iOS Simulator MCP
+
+| Aspect | AXe CLI | iOS Simulator MCP |
+|--------|---------|-------------------|
+| Interface | CLI (scriptable) | MCP server (AI-native) |
+| Dependencies | Single binary | Node.js + MCP runtime |
+| Tap targeting | Coordinates, ID, label | Coordinates only |
+| Gesture presets | 8 built-in | Manual swipe params |
+| Video / a11y tree | Native H.264, `describe-ui` | Not available / via simctl |
+| Best for | Scripts, CI, pipelines | Direct AI tool calling |
+
+## Integration with XcodeBuildMCP
+
+AXe pairs with XcodeBuildMCP for build-then-test workflows:
+
+1. **Build** with XcodeBuildMCP (compile, install to simulator)
+2. **Automate** with AXe (tap, type, swipe, verify)
+3. **Inspect** with `describe-ui` and **capture** with `screenshot`/`record-video`
+
+## Common Patterns
+
+```bash
+# Accessibility audit: dump UI tree + screenshot
+axe describe-ui --udid "$UDID" > ui-tree.txt
+axe screenshot --output ui-state.png --udid "$UDID"
+# UI flow: tap, scroll, verify
+axe tap --label "Settings" --pre-delay 0.5 --udid "$UDID"
+axe gesture scroll-down --post-delay 0.5 --udid "$UDID"
+axe describe-ui --udid "$UDID"
+```
+
+## Related
+
+- `tools/mobile/xcodebuild-mcp.md` - Build automation (same author)
+- `tools/mobile/ios-simulator-mcp.md` - MCP-based simulator control
+- `tools/mobile/maestro.md` - Mobile UI testing framework
diff --git a/.agents/tools/mobile/ios-simulator-mcp.md b/.agents/tools/mobile/ios-simulator-mcp.md
new file mode 100644
index 0000000000..cf256cc2e2
--- /dev/null
+++ b/.agents/tools/mobile/ios-simulator-mcp.md
@@ -0,0 +1,110 @@
+---
+description: iOS Simulator MCP - AI-driven iOS simulator interaction via MCP
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: false
+  grep: false
+  webfetch: false
+  task: false
+---
+
+# iOS Simulator MCP - Simulator Interaction Server
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: MCP server for direct iOS simulator interaction (tap, swipe, type, screenshot)
+- **Install**: `npx -y ios-simulator-mcp` (runs via MCP, no global install needed)
+- **Claude Code**: `claude mcp add ios-simulator npx ios-simulator-mcp`
+- **GitHub**: https://github.com/joshuayoes/ios-simulator-mcp (1.6k stars, MIT)
+- **Featured in**: [Anthropic's Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+
+**Requirements**: macOS, Xcode with iOS simulators, Node.js, Facebook [IDB](https://fbidb.io/) (`brew tap facebook/fb && brew install idb-companion`)
+
+<!-- AI-CONTEXT-END -->
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `ui_tap` | Tap at x,y coordinates (optional duration for long-press) |
+| `ui_swipe` | Swipe from start to end coordinates |
+| `ui_type` | Input text into the focused field (ASCII) |
+| `ui_view` | Get compressed screenshot of current screen |
+| `screenshot` | Save screenshot to file (png, jpeg, tiff, bmp, gif) |
+| `record_video` | Record simulator screen (h264/hevc codec) |
+| `stop_recording` | Stop active video recording |
+| `ui_describe_all` | Describe all accessibility elements on screen |
+| `ui_describe_point` | Describe accessibility element at x,y |
+| `install_app` | Install .app or .ipa bundle on simulator |
+| `launch_app` | Launch app by bundle ID (e.g., `com.apple.mobilesafari`) |
+| `get_booted_sim_id` | Get UDID of the currently booted simulator |
+| `open_simulator` | Open the Simulator application |
+
+## Configuration
+
+```bash
+# Claude Code
+claude mcp add ios-simulator npx ios-simulator-mcp
+```
+
+```json
+// OpenCode / Cursor (~/.config/opencode/mcp.json or ~/.cursor/mcp.json)
+{
+  "mcpServers": {
+    "ios-simulator": {
+      "command": "npx",
+      "args": ["-y", "ios-simulator-mcp"]
+    }
+  }
+}
+```
+
+**Environment variables**: `IOS_SIMULATOR_MCP_DEFAULT_OUTPUT_DIR` (screenshot/video output, default `~/Downloads`), `IOS_SIMULATOR_MCP_FILTERED_TOOLS` (comma-separated tools to disable), `IOS_SIMULATOR_MCP_IDB_PATH` (custom IDB path).
+
+## AI-Assisted QA Patterns
+
+Use these prompts after implementing a feature to validate behaviour:
+
+- **Verify UI elements**: "Describe all accessibility elements on the current screen"
+- **Confirm text input**: "Enter 'Hello World' into the text field and confirm the input"
+- **Validate tap response**: "Tap at x=250, y=400 and verify the expected element responds"
+- **Validate gestures**: "Swipe from x=150, y=600 to x=150, y=100 and confirm scroll"
+- **Visual check**: "Take a screenshot and save to qa-check.png"
+- **Record flow**: "Record video while I walk through the onboarding flow"
+
+## Integration with Other Tools
+
+| Tool | Role | Integration |
+|------|------|-------------|
+| **XcodeBuildMCP** | Build the app | Build with XcodeBuildMCP, then `install_app` + `launch_app` via this MCP |
+| **Maestro** | E2E test flows | Maestro for scripted repeatable flows; this MCP for ad-hoc AI-driven QA |
+| **MiniSim** | Simulator launcher | MiniSim manages simulator lifecycle; this MCP interacts with running sims |
+
+## Comparison: ios-simulator-mcp vs AXe CLI (t100)
+
+Both enable simulator interaction but take different approaches:
+
+| Aspect | ios-simulator-mcp | AXe CLI |
+|--------|-------------------|---------|
+| **Interface** | MCP server (tool calls) | CLI commands |
+| **AI integration** | Native MCP - AI calls tools directly | Requires bash wrapping |
+| **Accessibility** | `ui_describe_all`, `ui_describe_point` | Full accessibility tree queries |
+| **Video** | `record_video` / `stop_recording` | Not available |
+| **App management** | `install_app`, `launch_app` | Not available |
+| **Best for** | AI-driven QA, interactive testing | Accessibility auditing, tree inspection |
+
+## Troubleshooting
+
+- **IDB not found**: `brew tap facebook/fb && brew install idb-companion`
+- **No booted simulator**: `xcrun simctl boot "iPhone 16 Pro"` or use MiniSim
+- **Security**: Use v1.3.3+ (command injection fix in earlier versions)
+
+## Related Tools
+
+- `tools/mobile/minisim.md` - Simulator launcher and lifecycle management
diff --git a/.agents/tools/mobile/maestro.md b/.agents/tools/mobile/maestro.md
new file mode 100644
index 0000000000..a4d8599873
--- /dev/null
+++ b/.agents/tools/mobile/maestro.md
@@ -0,0 +1,132 @@
+---
+description: Maestro - painless E2E automation for Android, iOS, and web apps
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: false
+---
+
+# Maestro - E2E Testing for Mobile and Web
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Human-readable YAML-based E2E testing for Android, iOS, and web
+- **Install**: `curl -fsSL "https://get.maestro.mobile.dev" | bash`
+- **Requirements**: Java 17+ (`java -version` to verify)
+- **Docs**: https://docs.maestro.dev
+- **GitHub**: https://github.com/mobile-dev-inc/maestro (10.6k stars, Apache-2.0)
+
+**Why Maestro**: Built on learnings from Appium, Espresso, XCTest, and Selenium.
+Interpreted YAML flows (no compilation), built-in flakiness tolerance, automatic
+waiting. Write your first test in under five minutes.
+
+<!-- AI-CONTEXT-END -->
+
+## Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| `maestro test flow.yaml` | Run a single test flow |
+| `maestro test flows/` | Run all flows in a directory |
+| `maestro studio` | Visual test builder (browser-based IDE) |
+| `maestro record flow.yaml` | Run flow and record video |
+| `maestro hierarchy` | Dump current UI hierarchy (debugging) |
+
+## YAML Flow Syntax
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `launchApp` | Launch app (optional `clearState`, `clearKeychain`) |
+| `tapOn` / `doubleTapOn` / `longPressOn` | Tap, double-tap, or long press by text, `id`, or index |
+| `inputText` / `eraseText` | Type or remove text in focused field |
+| `assertVisible` / `assertNotVisible` | Assert element presence (auto-waits) |
+| `scroll` / `scrollUntilVisible` | Scroll screen or until element appears |
+| `swipe` | Swipe direction or between coordinates |
+| `back` / `hideKeyboard` | Navigate back (Android) or dismiss keyboard |
+| `openLink` | Open URL or deep link |
+| `takeScreenshot` | Capture screenshot to file |
+| `copyTextFrom` / `runScript` | Copy element text or execute JavaScript |
+| `runFlow` | Reuse steps from another flow file |
+| `setLocation` / `clearState` | Set GPS or wipe app data |
+| `repeat` / `retry` | Loop or retry commands |
+| `assertWithAI` | AI-powered visual assertions (experimental) |
+
+### Selectors
+
+```yaml
+- tapOn: "Submit"                        # By visible text
+- tapOn: { id: "submit-btn" }           # By accessibility ID (recommended)
+- tapOn: { text: "Item", index: 0 }     # By index when multiple matches
+- extendedWaitUntil: { visible: "Done", timeout: 10000 }  # Custom timeout
+```
+
+## Cross-Platform Support
+
+| Framework | Notes |
+|-----------|-------|
+| Native Android | Full (ADB + UIAutomator) |
+| Native iOS | Full (XCTest driver, simulator only for CLI) |
+| React Native | Use `testID` prop for stable selectors |
+| Flutter | Use `semanticsLabel` for selectors |
+| Web / Hybrid | Chromium-based, WebView supported |
+
+## Maestro Studio and Cloud
+
+**Studio** (`maestro studio` or standalone desktop app) -- visual IDE for test building:
+live device mirror, element inspector, click-to-select YAML generation, AI assistance.
+Download: https://maestro.dev/#maestro-studio
+
+**Cloud** -- parallel execution on dedicated infrastructure, up to 90% faster,
+deterministic environments. Free trial: https://maestro.dev/cloud
+
+## Common Patterns
+
+```yaml
+# Login flow: maestro test -e EMAIL=user@test.com -e PASSWORD=secret flows/login.yaml
+appId: com.example.app
+---
+- launchApp:
+    clearState: true
+- tapOn: "Sign In"
+- tapOn: { id: "email" }
+- inputText: "${EMAIL}"
+- tapOn: { id: "password" }
+- inputText: "${PASSWORD}"
+- tapOn: "Log In"
+- assertVisible: "Dashboard"
+# Navigation
+- tapOn: "Settings"
+- assertVisible: "Preferences"
+- back
+- assertVisible: "Dashboard"
+- swipe: { direction: LEFT }
+# Form validation
+- tapOn: "Register"
+- tapOn: "Submit"
+- assertVisible: "Email is required"
+```
+
+## Integration with aidevops Tools
+
+| Tool | Role |
+|------|------|
+| MiniSim | Boot simulators/emulators before `maestro test` |
+| XcodeBuildMCP | Build iOS `.app`, install on simulator, then test |
+| iOS Simulator MCP | Manage simulator state alongside Maestro flows |
+
+Typical workflow: boot simulator (`xcrun simctl boot`), build app (`xcodebuild`), run `maestro test flows/`.
+
+## Related Tools
+
+- `tools/mobile/minisim.md` - Simulator/emulator launcher
+- `tools/browser/playwright.md` - Web E2E testing
diff --git a/.agents/tools/mobile/xcodebuild-mcp.md b/.agents/tools/mobile/xcodebuild-mcp.md
new file mode 100644
index 0000000000..3769d28f5b
--- /dev/null
+++ b/.agents/tools/mobile/xcodebuild-mcp.md
@@ -0,0 +1,110 @@
+---
+description: XcodeBuildMCP - MCP server for Xcode build, test, and deployment via AI agents
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: true
+  grep: true
+  webfetch: false
+  task: false
+---
+
+# XcodeBuildMCP - Xcode Integration for AI Agents
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: MCP server + CLI providing xcodebuild tools for iOS/macOS development
+- **Install**: `npx -y xcodebuildmcp@beta mcp` (MCP server mode)
+- **CLI**: `npm install -g xcodebuildmcp@beta` then `xcodebuildmcp --help`
+- **Requirements**: macOS 14.5+, Xcode 16+, Node.js 18+
+- **GitHub**: https://github.com/cameroncooke/XcodeBuildMCP (4.1k stars, MIT)
+- **Docs**: https://www.xcodebuildmcp.com
+
+**Key Capabilities**:
+- Build iOS/macOS apps for simulators and physical devices
+- Run XCTest suites and report results to the agent
+- Deploy and launch apps on simulators and connected devices
+- LLDB debugger attachment with breakpoints and variable inspection
+- UI automation (tap, swipe, type, screenshots, accessibility snapshots)
+- Swift Package Manager build/test/run
+- Scaffold new iOS/macOS projects from templates
+- Simulator management (boot, erase, location, appearance, status bar)
+
+<!-- AI-CONTEXT-END -->
+
+## MCP Configuration
+
+### Claude Code
+
+```bash
+claude mcp add XcodeBuildMCP -- npx -y xcodebuildmcp@beta mcp
+```
+
+### JSON Config (Cursor, VS Code, Claude Desktop, OpenCode)
+
+```json
+{
+  "mcpServers": {
+    "XcodeBuildMCP": {
+      "command": "npx",
+      "args": ["-y", "xcodebuildmcp@beta", "mcp"]
+    }
+  }
+}
+```
+
+## Tool Groups (76 tools, 15 workflow groups)
+
+| Group | Key Tools | Purpose |
+|-------|-----------|---------|
+| **simulator** | `build_sim`, `build_run_sim`, `test_sim`, `launch_app_sim` | iOS simulator build/test/run |
+| **device** | `build_device`, `test_device`, `install_app_device`, `launch_app_device` | Physical device deployment |
+| **macos** | `build_macos`, `build_run_macos`, `test_macos`, `launch_mac_app` | macOS app development |
+| **swift-package** | `swift_package_build`, `swift_package_test`, `swift_package_run` | SPM project workflows |
+| **debugging** | `debug_attach_sim`, `debug_breakpoint_add`, `debug_variables`, `debug_stack` | LLDB debugger integration |
+| **ui-automation** | `tap`, `swipe`, `type_text`, `screenshot`, `snapshot_ui` | UI testing and interaction |
+| **simulator-management** | `boot_sim`, `list_sims`, `set_sim_location`, `erase_sims` | Simulator lifecycle |
+| **logging** | `start_sim_log_cap`, `stop_sim_log_cap` | Log capture for debugging |
+| **project-discovery** | `discover_projs`, `list_schemes`, `show_build_settings` | Project analysis |
+| **project-scaffolding** | `scaffold_ios_project`, `scaffold_macos_project` | New project creation |
+| **session-management** | `session_set_defaults`, `sync_xcode_defaults` | Persistent session config |
+| **doctor** | `doctor` | Environment diagnostics |
+
+Only simulator tools are enabled by default. Use `manage-workflows` to enable device, macOS, debugging, or other groups.
+
+## Notes
+
+- Device tools require code signing configured in Xcode
+- Macro validation is skipped automatically to avoid Swift Macro build errors
+- `snapshot_ui` returns view hierarchy with coordinates (useful for UI automation)
+- Session defaults persist scheme/simulator/device across tool calls
+
+## Integration with aidevops Mobile Stack
+
+| Tool | Role | Combines With |
+|------|------|---------------|
+| **XcodeBuildMCP** | Build, test, deploy | Primary build tool |
+| **Maestro** | E2E UI test flows | Run after `build_run_sim` |
+| **iOS Simulator MCP** | Simulator control | Complementary sim management |
+| **AXe** | Accessibility testing | Use with `snapshot_ui` output |
+| **MiniSim** | Quick simulator launch | GUI launcher alternative |
+
+### Typical Workflow
+
+1. `discover_projs` - scan for .xcodeproj/.xcworkspace
+2. `build_sim --scheme MyApp` - build for simulator
+3. `test_sim --scheme MyApp` - run XCTest suite
+4. `build_run_sim --scheme MyApp` - deploy and launch with logs
+5. `screenshot` / `snapshot_ui` - verify UI state
+6. `maestro test flows/login.yaml` - E2E tests on running simulator
+
+## Related Tools
+
+- `tools/mobile/minisim.md` - Simulator/emulator GUI launcher
+- `tools/browser/playwright.md` - Cross-platform testing (web)
+- `services/hosting/localhost.md` - Local dev environment
diff --git a/.agents/tools/security/tirith.md b/.agents/tools/security/tirith.md
new file mode 100644
index 0000000000..716b5a8126
--- /dev/null
+++ b/.agents/tools/security/tirith.md
@@ -0,0 +1,126 @@
+---
+description: Terminal security guard - catches homograph attacks, ANSI injection, pipe-to-shell, and credential exposure before execution
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  glob: false
+  grep: false
+  webfetch: false
+---
+
+# Tirith - Terminal Security Guard
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Pre-execution security guard for terminal commands
+- **Repo**: [github.com/sheeki03/tirith](https://github.com/sheeki03/tirith) (1.5k stars, Rust, AGPL-3.0)
+- **Key trait**: Sub-millisecond overhead, fully local, no network calls, no telemetry
+- **Coverage**: 30 rules across 7 categories
+
+Browsers block homograph attacks, ANSI injection, and suspicious URLs. Terminals don't.
+Tirith hooks into your shell and intercepts dangerous commands before they execute.
+
+<!-- AI-CONTEXT-END -->
+
+## Installation
+
+```bash
+brew install sheeki03/tap/tirith   # macOS
+npm install -g tirith              # cross-platform
+cargo install tirith               # from source
+mise use -g tirith                 # mise
+```
+
+Also available via Nix, deb, rpm, AUR, Scoop, and Chocolatey.
+
+## Shell Hook Setup
+
+Add to your shell profile — this is the only activation step:
+
+```bash
+# zsh (~/.zshrc)
+eval "$(tirith init --shell zsh)"
+
+# bash (~/.bashrc)
+eval "$(tirith init --shell bash)"
+
+# fish (~/.config/fish/config.fish)
+tirith init --shell fish | source
+```
+
+Every command is now guarded. Clean commands pass through invisibly.
+
+## Rule Categories
+
+| Category | What it stops |
+|----------|---------------|
+| **Homograph attacks** | Cyrillic/Greek lookalikes in hostnames, punycode domains, mixed-script labels |
+| **Terminal injection** | ANSI escape sequences that rewrite display, bidi overrides, zero-width characters |
+| **Pipe-to-shell** | `curl \| bash`, `wget \| sh`, `python <(curl ...)`, `eval $(wget ...)` |
+| **Dotfile attacks** | Downloads targeting `~/.bashrc`, `~/.ssh/authorized_keys`, `~/.gitconfig` |
+| **Insecure transport** | Plain HTTP piped to shell, `curl -k`, disabled TLS verification |
+| **Ecosystem threats** | Git clone typosquats, untrusted Docker registries, pip/npm URL installs |
+| **Credential exposure** | `http://user:pass@host` userinfo tricks, shortened URLs hiding destinations |
+
+Critical rules (homograph, dotfile) **block** execution. Medium rules (pipe-to-shell with clean URL) **warn** but allow.
+
+## Commands
+
+```bash
+tirith check -- <cmd>          # Analyze without executing
+tirith score <url>             # URL trust signal breakdown
+tirith diff <url>              # Byte-level suspicious character comparison
+tirith run <url>               # Safe curl|bash replacement (download, review, confirm)
+tirith receipt list            # Audit trail of scripts run via tirith run
+tirith why                     # Explain last triggered rule
+tirith doctor                  # Diagnostic check (shell, hooks, policy)
+```
+
+## Configuration
+
+YAML policy file, discovered in order:
+
+1. `.tirith/policy.yaml` (walks up to repo root)
+2. `~/.config/tirith/policy.yaml`
+
+```yaml
+version: 1
+allowlist:
+  - "get.docker.com"
+  - "sh.rustup.rs"
+
+severity_overrides:
+  docker_untrusted_registry: critical
+
+fail_mode: open  # or "closed" for strict environments
+```
+
+Organizations can set `allow_bypass: false` to prevent per-command bypass.
+
+## Bypass
+
+For commands you've verified manually:
+
+```bash
+TIRITH=0 curl -L https://known-safe.example.com | bash
+```
+
+Standard shell prefix — applies to that single command only, does not persist.
+
+## Integration with aidevops
+
+**setup.sh recommendation**: Check for tirith and suggest installation if missing.
+Once `eval "$(tirith init)"` is in the shell profile, all terminal commands
+(including those spawned by aidevops scripts) are automatically guarded.
+
+**Audit log**: Local JSONL at `~/.local/share/tirith/log.jsonl` (timestamp, action, rule ID, redacted preview). Disable with `TIRITH_LOG=0`.
+
+## Related
+
+- `tools/security/privacy-filter.md` — Content privacy filtering
+- `tools/security/cdn-origin-ip.md` — CDN origin IP leak detection
diff --git a/.agents/tools/social-media/linkedin.md b/.agents/tools/social-media/linkedin.md
new file mode 100644
index 0000000000..d23f7c6664
--- /dev/null
+++ b/.agents/tools/social-media/linkedin.md
@@ -0,0 +1,127 @@
+---
+description: LinkedIn content creation, posting, and analytics via API
+mode: subagent
+tools:
+  read: true
+  write: false
+  edit: false
+  bash: true
+  webfetch: true
+---
+
+# LinkedIn Content Subagent
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Create, publish, and analyze LinkedIn content
+- **API**: Community Management API (v2) via OAuth 2.0
+- **Docs**: https://learn.microsoft.com/en-us/linkedin/marketing/
+- **Auth**: OAuth 2.0 three-legged flow, scopes: `w_member_social`, `r_organization_social`
+- **Related**: [bird.md](bird.md) (X/Twitter), [reddit.md](reddit.md) (Reddit)
+
+## Post Types
+
+| Type | Use Case | Notes |
+|------|----------|-------|
+| **Text post** | Thought leadership, updates | 3,000 char limit |
+| **Article** | Long-form content | Published on LinkedIn's platform |
+| **Carousel** | Multi-page visual content | PDF upload, up to 300 pages |
+| **Document** | Whitepapers, guides | PDF/PPT/DOC, 100MB max |
+| **Poll** | Audience engagement | 2-4 options, 1-2 week duration |
+| **Image post** | Visual content | Up to 9 images per post |
+| **Video** | Native video content | Up to 10 min recommended |
+
+<!-- AI-CONTEXT-END -->
+
+## API Access
+
+### OAuth 2.0 Setup
+
+1. Create app at https://www.linkedin.com/developers/apps
+2. Request Community Management API access (requires app review)
+3. Configure redirect URI and obtain client ID/secret
+
+```bash
+# Store credentials securely
+aidevops secret set LINKEDIN_CLIENT_ID
+aidevops secret set LINKEDIN_CLIENT_SECRET
+aidevops secret set LINKEDIN_ACCESS_TOKEN
+```
+
+### Key Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/v2/userinfo` | GET | Authenticated user profile |
+| `/v2/posts` | POST | Create text/media posts |
+| `/v2/images?action=initializeUpload` | POST | Register image upload |
+| `/v2/organizationalEntityShareStatistics` | GET | Post analytics |
+
+```bash
+# Create a text post
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  "https://api.linkedin.com/v2/posts" \
+  -d '{"author":"urn:li:person:ID","lifecycleState":"PUBLISHED","visibility":"PUBLIC","commentary":"Post text here","distribution":{"feedDistribution":"MAIN_FEED"}}'
+```
+
+## Post Structure
+
+Effective LinkedIn posts follow a consistent structure:
+
+1. **Hook line** - First 1-2 lines visible before "see more" (~210 chars)
+2. **Body** - Main content with line breaks for readability
+3. **CTA** - Call to action (comment, share, visit link)
+4. **Hashtags** - 3-5 relevant hashtags at the end
+
+### Formatting
+
+- **Bold/Italic**: Use Unicode characters (not supported natively in API)
+- **Line breaks**: `\n` in API; blank lines for paragraph separation
+- **Emoji**: Sparingly as visual anchors (1-3 per post)
+- **Limits**: 3,000 chars for posts, ~210 visible before "see more" fold
+
+## Content Best Practices
+
+- **Hashtags**: 3-5 max, mix broad (#Leadership) with niche (#DevOpsAutomation), place at end
+- **Timing**: Tue-Thu, 7-8am / 12pm / 5-6pm audience timezone, 3-5 posts/week
+- **Engagement**: Open with question or bold statement, end with CTA question
+- **Personal stories**: "I" narratives perform 2-3x better than generic content
+- **Reply fast**: Respond to comments within first hour to boost algorithmic reach
+
+## Analytics
+
+### Key Metrics
+
+| Metric | Target | API Field |
+|--------|--------|-----------|
+| Impressions | Track trend | `impressionCount` |
+| Engagement rate | >2% good, >5% excellent | `engagementRate` |
+| Click-through | >1% for link posts | `clickCount` |
+| Shares | Indicates high-value content | `shareCount` |
+
+## Automation Patterns
+
+### Content Repurposing Pipeline
+
+| Source | LinkedIn Format |
+|--------|----------------|
+| Blog post | Extract key points into text post + link |
+| Tweet thread | Expand into single LinkedIn post |
+| Conference talk | Carousel with key slides |
+| Documentation | How-to post with code snippets |
+| Reddit answer | Reframe as thought leadership |
+
+**Cross-post workflow**: Draft content once, adapt for LinkedIn (professional tone, hashtags), X/Twitter (concise, threads - see [bird.md](bird.md)), Reddit (subreddit-appropriate - see [reddit.md](reddit.md)).
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| 401 Unauthorized | Token expired; re-authenticate OAuth flow |
+| 403 Forbidden | Missing API scope or app not approved |
+| 429 Rate limited | Daily limit ~100 API calls; implement backoff |
+| Post not visible | Check visibility setting; may need `PUBLIC` scope |
+| Image upload fails | Register upload first, then PUT binary to upload URL |
diff --git a/.agents/tools/voice/transcription.md b/.agents/tools/voice/transcription.md
index 50f19284ca..64c5284d29 100644
--- a/.agents/tools/voice/transcription.md
+++ b/.agents/tools/voice/transcription.md
@@ -3,13 +3,7 @@ description: Audio/video transcription with local and cloud models
 mode: subagent
 tools:
   read: true
-  write: true
-  edit: true
   bash: true
-  glob: true
-  grep: true
-  webfetch: true
-  task: true
 ---
 
 # Audio/Video Transcription
@@ -65,32 +59,22 @@ Official usage: https://github.com/SYSTRAN/faster-whisper#usage
 
 ### via whisper.cpp (C++ native)
 
-Optimized for Apple Silicon and CPU inference.
+Optimized for Apple Silicon and CPU inference. Build from source: https://github.com/ggml-org/whisper.cpp
 
 ```bash
-# Build from source (no Homebrew formula)
-git clone https://github.com/ggml-org/whisper.cpp.git
-cd whisper.cpp && cmake -B build && cmake --build build -j --config Release
-
-# Download model
-sh ./models/download-ggml-model.sh large-v3-turbo
-
-# Transcribe
-./build/bin/whisper-cli -f audio.wav -otxt -osrt
+./build/bin/whisper-cli -m models/ggml-large-v3-turbo.bin -f audio.wav -otxt -osrt
 ```
 
 ### Model Comparison
 
 | Model | Size | Speed | Accuracy | Notes |
 |-------|------|-------|----------|-------|
-| Tiny | 75MB | 9.5 | 6.0-6.5 | Draft/preview only |
-| Base | 142MB | 8.5 | 7.2-7.5 | Quick transcription |
-| Small | 461MB | 7.0 | 8.5 | Good balance |
+| Tiny | 75MB | 9.5 | 6.0 | Draft/preview only |
+| Base | 142MB | 8.5 | 7.3 | Quick transcription |
+| Small | 461MB | 7.0 | 8.5 | Good balance, multilingual |
 | Medium | 1.5GB | 5.0 | 9.0 | Solid quality |
-| Large v2 | 2.9GB | 3.0 | 9.6 | High quality |
 | Large v3 | 2.9GB | 3.0 | 9.8 | Best quality |
 | **Large v3 Turbo** | **1.5GB** | **7.5** | **9.7** | **Recommended default** |
-| Large v3 Turbo Q | 547MB | 7.5 | 9.5 | Quantized, smaller |
 
 ### Other Local Models
 
@@ -115,7 +99,7 @@ sh ./models/download-ggml-model.sh large-v3-turbo
 | **Google** | Gemini 3 Flash | 9.5 | Fastest | Low latency |
 | **Soniox** | stt-async-v3 | 9.6 | Async | Batch processing |
 
-### Groq (Fastest Cloud)
+Store API keys via `aidevops secret set <PROVIDER>_API_KEY`. All cloud APIs accept standard multipart file upload. Example (Groq):
 
 ```bash
 curl https://api.groq.com/openai/v1/audio/transcriptions \
@@ -126,79 +110,50 @@ curl https://api.groq.com/openai/v1/audio/transcriptions \
   -F "response_format=verbose_json"
 ```
 
-Docs: https://console.groq.com/docs/speech-text
-
-### OpenAI Whisper API
-
-```bash
-curl https://api.openai.com/v1/audio/transcriptions \
-  -H "Authorization: Bearer ${OPENAI_API_KEY}" \
-  -F "file=@audio.wav" \
-  -F "model=whisper-1" \
-  -F "response_format=srt"
-```
-
-Docs: https://platform.openai.com/docs/api-reference/audio/createTranscription
+## Model Selection Guidance
 
-### ElevenLabs Scribe
+| Priority | Local | Cloud |
+|----------|-------|-------|
+| **Best accuracy** | Large v3 (9.8) | ElevenLabs Scribe v2 (9.9) |
+| **Best speed** | Parakeet V2 (English) | Groq Whisper (free tier) |
+| **Best balance** | **Large v3 Turbo** (default) | Groq or Gemini Flash |
+| **Lowest cost** | Any local model ($0) | Groq free tier, then OpenAI ($0.006/min) |
+| **Offline/private** | faster-whisper or whisper.cpp | N/A |
+| **Multilingual** | Large v3 or Small | Voxtral Mini or Gemini Pro |
 
-```bash
-curl -X POST "https://api.elevenlabs.io/v1/speech-to-text" \
-  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
-  -F "file=@audio.wav" \
-  -F "model_id=scribe_v1"
-```
-
-Docs: https://elevenlabs.io/docs/api-reference/speech-to-text
+**Decision flow**: Local first (free, private) unless file is very long (use Groq async) or accuracy is critical (use Scribe v2).
 
 ## Output Formats
 
-| Format | Extension | Use Case |
-|--------|-----------|----------|
-| Plain text | `.txt` | Reading, search indexing |
-| SRT | `.srt` | Video subtitles |
-| VTT | `.vtt` | Web video subtitles |
-| JSON | `.json` | Programmatic access, timestamps |
-| TSV | `.tsv` | Spreadsheet analysis |
+| Format | Use Case |
+|--------|----------|
+| `.txt` | Reading, search indexing |
+| `.srt` | Video subtitles (most compatible) |
+| `.vtt` | Web video subtitles |
+| `.json` | Programmatic access, timestamps |
 
-## Transcription Pipeline
+## Workflow
 
 ```text
-Input Source
-    │
-    ├── YouTube URL ──→ yt-dlp -x ──→ audio.wav
-    ├── Video URL ────→ curl + ffmpeg ──→ audio.wav
-    ├── Video file ───→ ffmpeg -vn ──→ audio.wav
-    └── Audio file ───→ (direct) ──→ audio.wav
-                                        │
-                                   Model Selection
-                                        │
-                              ┌─────────┴─────────┐
-                              │                    │
-                         Local Model          Cloud API
-                     (faster-whisper)      (Groq/OpenAI/etc)
-                              │                    │
-                              └─────────┬──────────┘
-                                        │
-                                   Output Format
-                                   (txt/srt/vtt/json)
+Source → Extract Audio (if needed) → Select Model → Transcribe → Output
 ```
 
+1. **Detect source**: YouTube URL, media URL, local audio, or local video
+2. **Extract audio**: `yt-dlp -x` (YouTube), `ffmpeg -vn` (video), direct (audio)
+3. **Select model**: Local (faster-whisper/whisper.cpp) or cloud API (Groq/OpenAI/etc)
+4. **Transcribe**: Run model, generate output in requested format
+5. **Output**: Plain text, SRT, VTT, or JSON with timestamps
+
 ## Dependencies
 
 ```bash
-# Core
-brew install yt-dlp ffmpeg    # macOS
-apt install yt-dlp ffmpeg     # Ubuntu/Debian
-
-# Local inference (pick one)
-pip install faster-whisper     # Python (recommended)
-# whisper.cpp: build from source (see above)
+brew install yt-dlp ffmpeg     # macOS (apt install on Linux)
+pip install faster-whisper      # Local inference (recommended)
 ```
 
 ## Related
 
+- `tools/voice/buzz.md` - Buzz GUI/CLI for offline Whisper transcription
+- `tools/voice/speech-to-speech.md` - Full voice pipeline (VAD + STT + LLM + TTS)
 - `tools/voice/voice-models.md` - TTS models for speech generation
-- `tools/voice/speech-to-speech.md` - Full voice pipeline
-- `tools/content/summarize.md` - Can summarize transcribed content
 - `voice-helper.sh` - CLI for voice operations
diff --git a/.agents/tools/voice/voice-ai-models.md b/.agents/tools/voice/voice-ai-models.md
new file mode 100644
index 0000000000..783f60bfa1
--- /dev/null
+++ b/.agents/tools/voice/voice-ai-models.md
@@ -0,0 +1,145 @@
+---
+description: Voice AI model landscape - TTS, STT, and S2S model selection reference
+mode: subagent
+tools:
+  read: true
+  bash: true
+---
+
+# Voice AI Models
+
+<!-- AI-CONTEXT-START -->
+
+## Quick Reference
+
+- **Purpose**: Comprehensive reference for voice AI model selection across TTS, STT, and S2S
+- **TTS details**: `tools/voice/voice-models.md` (implemented engines, integration)
+- **STT details**: `tools/voice/transcription.md` (transcription workflows, cloud APIs)
+- **S2S pipeline**: `tools/voice/speech-to-speech.md` (full voice pipeline setup)
+- **Offline tool**: `tools/voice/buzz.md` (Buzz GUI/CLI for Whisper)
+
+**When to use**: Choosing between voice AI models for a project. For implementation details, follow the cross-references above.
+
+<!-- AI-CONTEXT-END -->
+
+## TTS (Text-to-Speech)
+
+### Cloud Services
+
+| Provider | Latency | Quality | Voice Clone | Languages | Pricing |
+|----------|---------|---------|-------------|-----------|---------|
+| ElevenLabs | ~300ms | Best | Yes | 29 | $5-330/mo |
+| OpenAI TTS | ~400ms | Great | No | 57 | $15/1M chars |
+| Cartesia Sonic | ~150ms | Great | Yes (5s ref) | 17 | $8-66/mo |
+| Google Cloud TTS | ~200ms | Good | No (custom) | 50+ | $4-16/1M chars |
+
+**Pick**: ElevenLabs for quality/cloning, Cartesia for lowest latency, Google for language breadth.
+
+### Local Models
+
+| Model | Params | License | Languages | Voice Clone | GPU VRAM |
+|-------|--------|---------|-----------|-------------|----------|
+| Qwen3-TTS 0.6B | 0.6B | Apache-2.0 | 10 | Yes (5s ref) | 2GB |
+| Qwen3-TTS 1.7B | 1.7B | Apache-2.0 | 10 | Yes (5s ref) | 4GB |
+| Bark (Suno) | 1.0B | MIT | 13+ | Yes (prompt) | 6GB |
+| Coqui TTS | varies | MPL-2.0 | 20+ | Yes | 2-6GB |
+| Piper | <100M | MIT | 30+ | No | CPU only |
+
+**Pick**: Qwen3-TTS for quality + cloning, Piper for CPU-only/embedded, Bark for expressiveness (laughter, music).
+
+Also implemented in the voice bridge: **EdgeTTS** (free, 300+ voices), **macOS Say** (zero deps), **FacebookMMS** (1100+ languages). See `voice-models.md` for details.
+
+## STT (Speech-to-Text)
+
+### Cloud APIs
+
+| Provider | Model | Accuracy | Real-time | Cost |
+|----------|-------|----------|-----------|------|
+| Groq | Whisper Large v3 Turbo | 9.6 | No (batch) | Free tier |
+| ElevenLabs | Scribe v2 | 9.9 | No | Per minute |
+| Deepgram | Nova-2 / Nova-3 | 9.5-9.6 | Yes | Per minute |
+| Soniox | stt-async-v3 | 9.6 | Yes | Per minute |
+
+**Pick**: Groq for free/fast batch, ElevenLabs Scribe for accuracy, Deepgram for real-time streaming.
+
+### Local Models
+
+| Model | Size | Accuracy | Speed | GPU VRAM |
+|-------|------|----------|-------|----------|
+| Whisper Tiny | 75MB | 6.0 | Fastest | 1GB |
+| Whisper Base | 142MB | 7.3 | Fast | 1GB |
+| Whisper Small | 461MB | 8.5 | Medium | 2GB |
+| Whisper Large v3 | 2.9GB | 9.8 | Slow | 10GB |
+| Whisper Large v3 Turbo | 1.5GB | 9.7 | Fast | 5GB |
+| NVIDIA Parakeet V2 | 474MB | 9.4 | Fastest | 2GB |
+| Apple Speech | Built-in | 9.0 | Fast | On-device |
+
+**Pick**: Large v3 Turbo as default (best balance), Parakeet for English-only speed, Apple Speech for zero-setup macOS 26+.
+
+Backends: `faster-whisper` (4x speed, recommended), `whisper.cpp` (C++ native, Apple Silicon optimized). See `transcription.md`.
+
+## S2S (Speech-to-Speech)
+
+End-to-end models that process speech directly without text intermediary:
+
+| Model | Type | Latency | Availability | Notes |
+|-------|------|---------|--------------|-------|
+| GPT-4o Realtime | Cloud API | ~300ms | OpenAI API | Voice mode, emotion-aware |
+| Gemini 2.0 Live | Cloud API | ~350ms | Google API | Multimodal, streaming |
+| MiniCPM-o | Open weights | ~500ms | Local (8GB+) | 8B params, Apache-2.0 |
+| Ultravox | Open weights | ~400ms | Local (6GB+) | Audio-text multimodal |
+
+**Pick**: GPT-4o Realtime for production cloud, MiniCPM-o for local/private. For cascaded S2S (VAD+STT+LLM+TTS), see `speech-to-speech.md`.
+
+## Model Selection Guide
+
+### By Priority
+
+| Priority | TTS | STT | S2S |
+|----------|-----|-----|-----|
+| **Quality** | ElevenLabs / Qwen3-TTS 1.7B | ElevenLabs Scribe / Large v3 | GPT-4o Realtime |
+| **Speed** | Cartesia / EdgeTTS | Groq / Parakeet | Cascaded pipeline |
+| **Cost** | EdgeTTS (free) / Piper | Local Whisper ($0) / Groq free | MiniCPM-o (local) |
+| **Privacy** | Piper / Qwen3-TTS | faster-whisper / whisper.cpp | MiniCPM-o |
+| **Voice clone** | ElevenLabs / Qwen3-TTS | N/A | N/A |
+
+### Decision Flow
+
+```text
+Need voice AI?
+├── Generate speech (TTS)
+│   ├── Need voice cloning? → Qwen3-TTS (local) or ElevenLabs (cloud)
+│   ├── Need lowest latency? → Cartesia (cloud) or EdgeTTS (free)
+│   ├── Need offline? → Piper (CPU) or Qwen3-TTS (GPU)
+│   └── Default → EdgeTTS (free, good quality)
+├── Transcribe speech (STT)
+│   ├── Need real-time? → Deepgram Nova (cloud) or faster-whisper (local)
+│   ├── Need best accuracy? → ElevenLabs Scribe (cloud) or Large v3 (local)
+│   ├── Need free? → Groq free tier (cloud) or any local model
+│   └── Default → Whisper Large v3 Turbo (local)
+└── Conversational (S2S)
+    ├── Cloud OK? → GPT-4o Realtime
+    ├── Local/private? → MiniCPM-o or cascaded pipeline
+    └── Default → speech-to-speech.md cascaded pipeline
+```
+
+## GPU Requirements Summary
+
+| Use Case | Min VRAM | Recommended |
+|----------|----------|-------------|
+| STT only (Whisper Turbo) | 5GB | 8GB |
+| TTS only (Qwen3-TTS 0.6B) | 2GB | 4GB |
+| TTS only (Bark) | 6GB | 8GB |
+| S2S (MiniCPM-o) | 8GB | 16GB |
+| Full cascaded pipeline | 4GB | 12GB |
+| CPU-only (Piper + whisper.cpp) | 0 | 8GB RAM |
+
+Apple Silicon: MPS acceleration works for most PyTorch models. Use `whisper-mlx` or `mlx-audio-whisper` for optimized macOS inference.
+
+## Related
+
+- `tools/voice/voice-models.md` - TTS engines implemented in voice bridge
+- `tools/voice/transcription.md` - STT workflows, cloud API examples
+- `tools/voice/speech-to-speech.md` - Full cascaded voice pipeline
+- `tools/voice/buzz.md` - Buzz offline transcription tool
+- `voice-helper.sh` - CLI for voice operations