rev 4

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.agents/skills/attack-surface/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: attack-surface
+description: >
+  Strategic research framework that compresses months of market/competitive research into hours through structured power questions. Extracts unspoken industry insights, fragile market assumptions, and strategic attack surfaces from competitor data, reviews, and industry sources using parallel intelligence gathering.
+  Use when user says "attack surface", "research the market", "competitive analysis", "analyze competitors", "find market opportunity", "stress-test this idea", "market research", "evaluate opportunity", "find blind spots", "market entry", or when they want to deeply understand a market, evaluate a new direction, find industry blind spots, assess a partnership, or analyze opportunities.
+  Do NOT use for code review, testing, deployment, bug fixing, or implementation tasks.
+---
+
+# Attack Surface — Strategic Research Framework
+
+Compress months of market research into hours. The difference between 3 hours and 3 months isn't the amount of information — it's knowing which questions actually matter.
+
+Instead of "summarize these" or "analyze the competition", this framework extracts:
+- **UNSPOKEN INSIGHTS** — what successful players understand that customers never say out loud
+- **FRAGILE ASSUMPTIONS** — beliefs the entire market is built on, and how they break
+- **ATTACK SURFACES** — the blind spots, the fragile consensus, the opening nobody is talking about
+
+## Search Tool Selection
+
+**Primary: Exa MCP** — Use `mcp__exa__web_search_exa`, `mcp__exa__crawling_exa`, and `mcp__exa__deep_researcher_start` when available. Exa is the best fit for neural search, crawling full pages, and deep research.
+
+**Fallback: Built-in web browsing tools** — If Exa MCP is unavailable, use the Codex environment's web search and page-open tools to find sources, open pages, and extract evidence. Record the exact URLs you relied on.
+
+**Detection:** At the start of Phase 2, check whether Exa MCP is available in the current environment. If it is not, use the built-in web tools for the entire session and note that in the Source Dossier.
+
+## When to Use
+
+- Entering a new market or vertical
+- Evaluating a new feature direction for an existing project
+- Assessing a partnership or platform opportunity
+- Stress-testing a business idea before committing
+- Finding competitive blind spots and underserved niches
+- Any strategic question that benefits from deep evidence-based analysis
+
+## Workflow Overview
+
+7 phases, alternating between automated intelligence gathering and user-guided analysis:
+
+| Phase | Name | Mode | Output |
+|-------|------|------|--------|
+| 1 | Briefing | Interactive | Research brief |
+| 2 | Source Collection | Automated (parallel) | Source dossier |
+| 3 | Unspoken Insights | Automated + checkpoint | Insight report |
+| 4 | Fragile Assumptions | Automated + checkpoint | Assumption map |
+| 5 | Investor Stress-Test | Automated + checkpoint | Stress-test results |
+| 6 | Opportunity Mapping | Automated + checkpoint | Opportunity matrix |
+| 7 | Action Plan & Save | Automated | Final research document |
+
+---
+
+## Phase 1: Briefing
+
+Start by understanding what the user wants to research. This is an interactive conversation — ask questions until you have a clear research brief.
+
+**Gather:**
+1. **Target** — What market, industry, or opportunity? (e.g., "yacht brokerage SaaS", "AI flashcards for language teachers", "mobile reading apps")
+2. **Angle** — What's the user's position? Entering as newcomer, expanding existing product, evaluating partnership?
+3. **Known competitors** — Any specific companies or products the user already knows about?
+4. **User-provided sources** — URLs, files, documents the user wants included? Accept any format.
+5. **Specific questions** — Anything particular the user wants answered beyond the standard framework?
+
+**Project context:** If the research relates to an existing project the user is working on, ask about the current product, tech stack, and strategic position. This grounds the analysis in real context rather than hypotheticals.
+
+**Output a research brief** before proceeding:
+```
+Research Brief:
+- Target: [market/opportunity]
+- Angle: [newcomer / existing player / evaluator]
+- Known competitors: [list]
+- User sources: [list of URLs/files]
+- Key questions: [specific questions beyond standard framework]
+- Project context: [if applicable, key facts about the user's product]
+```
+
+Ask user to confirm before proceeding to Phase 2.
+
+---
+
+## Phase 2: Source Collection
+
+This is the intelligence-gathering phase. The quality of analysis depends on the quality and diversity of sources.
+
+Use parallel gatherers only when the current Codex environment supports subagents and the user explicitly asked for delegation or parallel agent work. Otherwise, run the same research tracks yourself in the main thread using batched searches.
+
+### Tool availability check
+
+Before starting collection, check Exa MCP availability:
+- If Exa is available -> use Exa tools for search and crawling
+- If Exa is unavailable -> use the built-in web search and page-open tools instead
+
+### What to gather
+
+Cover 4-5 research tracks, each focused on a different source type. If subagents are available and explicitly requested, run up to 4 gatherers in parallel. Otherwise, execute the tracks yourself in sequence.
+
+**Subagent 1: Competitor Intelligence**
+Search for and crawl 5-8 competitor landing pages, product pages, and pricing pages. Extract: value propositions, positioning, pricing models, feature lists, target audience language.
+
+**Subagent 2: Customer Voice**
+Search Reddit, forums, review sites (G2, Trustpilot, Product Hunt, App Store reviews) for customer complaints, praise, and unmet needs in this market. Extract: recurring pain points, feature requests, emotional language, switching triggers.
+
+**Subagent 3: Industry Analysis**
+Search for industry reports, expert analysis, trend pieces, and earnings call transcripts. Extract: market size, growth trends, key players, regulatory landscape, technology shifts.
+
+**Subagent 4: Adjacent & Emerging**
+Search for startups entering this space, adjacent markets that could expand into it, and emerging technologies that could disrupt it. Extract: new entrants, pivot signals, technology trends, funding patterns.
+
+**Subagent 5: User-Provided Sources** (if any)
+Crawl all URLs the user provided. Extract full content.
+
+### Subagent prompt template
+
+Read `references/gatherer-prompt.md` for the detailed prompt template to use for each gatherer or direct pass. Each pass receives:
+- The research brief from Phase 1
+- Its specific focus area
+- Instructions for which search tool family to use (Exa or built-in web tools)
+
+### After collection
+
+Compile all subagent results into a **Source Dossier** — a structured document with all collected evidence organized by source type. Present a summary to the user:
+
+```
+Source Dossier Summary:
+- Search tools used: [Exa MCP / built-in web tools]
+- X competitor pages analyzed
+- X customer reviews/complaints collected
+- X industry reports found
+- X emerging players identified
+- X user-provided sources crawled
+Key themes so far: [2-3 sentences]
+```
+
+Ask: "Sources collected. Anything you want me to search for specifically before we start analysis? Or should I proceed?"
+
+---
+
+## Phase 3: Unspoken Insights
+
+The first analytical question — the one that separates this from generic "market analysis":
+
+> "Based on all collected evidence: What does every successful player in this market understand that their customers never say out loud?"
+
+This question works because it forces the analysis past surface-level features and pricing into the deeper truths that drive the market.
+
+Run this as a dedicated analysis pass using the prompt from `references/analyst-prompt.md` (Section: Unspoken Insights). If subagents are available and the user explicitly requested delegation, use a subagent. Otherwise, perform the pass directly in the main thread.
+
+**Present findings** to the user as 3-5 numbered insights, each with:
+- The insight itself (one clear sentence)
+- Evidence from sources (specific quotes, data points)
+- Why this matters strategically
+
+**Checkpoint:** "Here are the unspoken insights I found. Do any of these surprise you? Want me to dig deeper on any of them, or should we move to fragile assumptions?"
+
+---
+
+## Phase 4: Fragile Assumptions
+
+The second power question:
+
+> "What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
+
+This question maps the market's attack surface — the beliefs everyone takes for granted that could be upended.
+
+Run this as a dedicated analysis pass with the Source Dossier plus Phase 3 insights. Use the prompt from `references/analyst-prompt.md` (Section: Fragile Assumptions).
+
+**Present findings** as a structured assumption map:
+
+For each assumption:
+- **The assumption** (what everyone believes)
+- **Evidence it's true** (why people believe this)
+- **What breaks it** (specific conditions that would make it wrong)
+- **Fragility score** (1-5: how likely is it to break in the next 2-3 years?)
+- **If it breaks** (what happens to the market)
+
+**Checkpoint:** "These are the fragile assumptions I found. Any you disagree with? Want to explore any further?"
+
+---
+
+## Phase 5: Investor Stress-Test
+
+The third power question:
+
+> "Write 5 questions a world-class investor would ask to destroy this business idea, then answer each one using only the evidence in our source dossier."
+
+This is adversarial by design. The goal is to find every weak point before committing resources.
+
+Run this as a dedicated analysis pass with the Source Dossier plus all prior analysis. Use the prompt from `references/analyst-prompt.md` (Section: Investor Stress-Test).
+
+**Present findings** as 5 numbered challenges:
+
+For each:
+- **The killer question** (phrased as an investor would ask it)
+- **The evidence-based answer** (citing only our sources)
+- **Confidence level** (strong / moderate / weak)
+- **Remaining risk** (what the answer doesn't fully address)
+
+### Iterative Deepening
+
+For any answer rated "weak" confidence, automatically follow up:
+
+> "What's the strongest version of this argument and where does it still break?"
+
+Continue until all weak points are either resolved or clearly flagged as genuine risks.
+
+**Checkpoint:** "Here's the stress-test. X questions have strong answers, Y have remaining risks. Want to dig deeper on any of these?"
+
+---
+
+## Phase 6: Opportunity Mapping
+
+Now synthesize everything into actionable opportunities:
+
+> "Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves? For each, what's the evidence, what's the risk, and what would you need to validate first?"
+
+Run this as a dedicated analysis pass with all prior analysis. Use the prompt from `references/analyst-prompt.md` (Section: Opportunity Mapping).
+
+**Present** as an opportunity matrix:
+
+| Opportunity | Evidence | Risk | Validation Needed | Leverage (1-5) |
+|-------------|----------|------|-------------------|----------------|
+| ... | ... | ... | ... | ... |
+
+**Checkpoint:** "These are the highest-leverage opportunities I see. Which ones resonate? Should I develop any of them into a concrete action plan?"
+
+---
+
+## Phase 7: Action Plan & Save
+
+Based on user's selections from Phase 6, create a concrete action plan:
+
+1. **Immediate next steps** (this week)
+2. **Validation experiments** (this month)
+3. **Strategic moves** (this quarter)
+
+### Save the Document
+
+Compile ALL phases into a single research document and save it.
+
+Use this format:
+
+```markdown
+---
+id: RESEARCH-YYYY-MM-DD-attack-surface-{slug}
+created: YYYY-MM-DD
+topic: Attack Surface Analysis — {Topic}
+sources: [list of source types used]
+search_tools: [Exa MCP / built-in web tools]
+tags: [attack-surface, market-research, {topic-tags}]
+---
+
+# Attack Surface: {Topic}
+
+## Executive Summary
+[3-5 bullet points with the most important findings]
+
+## Research Brief
+[From Phase 1]
+
+## Source Dossier Summary
+[From Phase 2 — source counts and key themes]
+
+## Unspoken Insights
+[From Phase 3]
+
+## Fragile Assumptions
+[From Phase 4 — the assumption map]
+
+## Investor Stress-Test
+[From Phase 5 — questions, answers, confidence levels]
+
+## Opportunity Matrix
+[From Phase 6]
+
+## Action Plan
+[From Phase 7]
+
+## Raw Sources
+[Links to all sources consulted]
+```
+
+Save to the project root as `RESEARCH-YYYY-MM-DD-attack-surface-{slug}.md`. Tell the user the file path and offer to discuss any findings further.
+
+---
+
+## Delegation Guidance
+
+This skill works without subagents. Use the main thread by default, and only delegate when the user explicitly asks for subagents or parallel agent work and the environment supports it.
+
+Read the reference files for detailed prompt templates:
+
+- `references/gatherer-prompt.md` — Prompt template for Phase 2 source collection gatherers
+- `references/analyst-prompt.md` — Prompt templates for Phases 3-6 analysis passes
+
+When delegating:
+- Phase 2: Launch up to 4 gatherers in parallel, one per search focus
+- Phases 3-6: Run sequentially because each pass depends on prior findings
+- Use a normal Codex subagent type that fits the environment; do not depend on Claude-specific agent naming
+- Give gatherers the research brief, search tool instructions, and their focus area
+- Give analysis passes a condensed Source Dossier plus the raw-source appendix or links when possible; do not bloat context with unnecessary full-page dumps
+
+### Token Budget
+
+This skill may require 6-10 major research and analysis passes. Estimated cost:
+- Phase 2: 4-6 gatherer passes x ~5-15K tokens each
+- Phases 3-6: 4 analysis passes x ~10-20K tokens each
+- Total: ~60-150K tokens per full research session
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping Phase 1 briefing | The research brief focuses everything — never skip |
+| Generic searches | Use specific, targeted queries from the research brief |
+| Presenting analysis without evidence | Every insight must cite specific sources |
+| Moving past weak stress-test answers | Always run iterative deepening on weak answers |
+| Forgetting to save | Always save the final document at the end |
+| Ignoring user-provided sources | Crawl them FIRST — the user chose them for a reason |
+| Not checking available search tools first | Decide on Exa vs. built-in web tools before collecting sources |

.agents/skills/attack-surface/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Attack Surface Research"
+  short_description: "Find fragile market assumptions and strategic openings"
+  default_prompt: "Use $attack-surface to research this market, extract fragile assumptions, and map the best entry points."
+
+policy:
+  allow_implicit_invocation: true

.agents/skills/attack-surface/references/analyst-prompt.md

@@ -0,0 +1,151 @@
+# Analysis Prompt Templates
+
+Use these templates when running Phases 3-6 analysis passes. Each pass receives the Source Dossier and prior analysis results, whether it is executed directly or via a subagent.
+
+---
+
+## Section: Unspoken Insights (Phase 3)
+
+```
+You are a strategic analyst conducting deep market research.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Your task: Answer this question with rigorous evidence from the sources above:
+
+"What does every successful player in this market understand that their customers never say out loud?"
+
+This isn't about features or pricing. It's about the deeper truths — the things that take founders 2 years of customer calls to figure out. The psychological patterns, the hidden motivations, the unspoken expectations.
+
+Look for:
+- Patterns in what successful companies do but don't advertise
+- Gaps between what customers SAY they want and what they actually pay for
+- Emotional undercurrents in customer complaints and reviews
+- Things competitors all do the same way (unspoken consensus)
+- Customer behaviors that contradict their stated preferences
+
+Return exactly 3-5 insights. For each:
+1. **The insight** — one clear, provocative sentence
+2. **Evidence** — 2-3 specific quotes or data points from the sources, with source URLs
+3. **Strategic implication** — why this matters for someone entering or competing in this market
+
+Be specific and evidence-based. Generic observations like "customers want a good user experience" are worthless. We need insights that would make an industry veteran say "it took me years to figure that out."
+```
+
+---
+
+## Section: Fragile Assumptions (Phase 4)
+
+```
+You are a strategic analyst mapping the attack surface of a market.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Prior analysis — Unspoken Insights:
+{PHASE_3_RESULTS}
+
+Your task: Answer this question:
+
+"What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
+
+Every market operates on a set of shared beliefs that nobody questions. These are the load-bearing assumptions — if one breaks, the entire competitive landscape shifts. Your job is to find them.
+
+Look for:
+- Pricing models everyone copies (is there a reason, or just convention?)
+- Distribution channels everyone uses (what if a new channel emerges?)
+- Customer segments everyone targets (who is being ignored?)
+- Technology choices everyone makes (what if the tech shifts?)
+- Business models everyone follows (what if a different model works?)
+- Regulations everyone plans around (what if they change?)
+
+For each assumption, return:
+1. **The assumption** — what everyone in this market believes
+2. **Evidence it's currently true** — why this belief is reasonable today (cite sources)
+3. **Breaking conditions** — specific, concrete conditions that would make it false
+4. **Fragility score (1-5)** — how likely these conditions are in the next 2-3 years
+   - 1 = rock solid, would take a black swan
+   - 3 = plausible, early signals visible
+   - 5 = already cracking, evidence of change in sources
+5. **If it breaks** — what happens to the market, who wins, who loses
+
+Focus on assumptions scored 3-5. Those are the real attack surfaces.
+```
+
+---
+
+## Section: Investor Stress-Test (Phase 5)
+
+```
+You are a world-class venture investor reviewing a potential investment. Your reputation depends on finding fatal flaws BEFORE writing a check. You've seen 10,000 pitches and killed 9,900 of them.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Prior analysis:
+- Unspoken Insights: {PHASE_3_RESULTS}
+- Fragile Assumptions: {PHASE_4_RESULTS}
+
+Your task:
+
+Step 1: Write 5 questions that would destroy this business idea. Not softballs — the questions that make founders sweat. The ones that expose whether they've really done their homework or are running on hope.
+
+Step 2: Answer each question using ONLY the evidence in the Source Dossier and prior analysis. No hand-waving. If the evidence doesn't support a strong answer, say so.
+
+For each of the 5 questions:
+1. **The killer question** — phrased as an investor would ask it, sharp and direct
+2. **The evidence-based answer** — using only our collected sources
+3. **Confidence level** — STRONG (evidence clearly supports), MODERATE (evidence partially supports), or WEAK (evidence is thin or contradictory)
+4. **Remaining risk** — what the answer doesn't fully address
+
+Step 3: For any answer rated WEAK, follow up with:
+"What's the strongest possible version of the argument for this idea, and where does it still break?"
+
+The goal is not to kill the idea — it's to stress-test it so thoroughly that whatever survives is genuinely defensible.
+```
+
+---
+
+## Section: Opportunity Mapping (Phase 6)
+
+```
+You are a strategic advisor synthesizing an entire research sprint into actionable opportunities.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+All prior analysis:
+- Unspoken Insights: {PHASE_3_RESULTS}
+- Fragile Assumptions: {PHASE_4_RESULTS}
+- Investor Stress-Test: {PHASE_5_RESULTS}
+
+Your task:
+
+"Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves?"
+
+For each opportunity:
+1. **The opportunity** — one clear sentence describing the strategic move
+2. **Why now** — what's changed (or changing) that makes this viable
+3. **Evidence** — specific findings from our research that support this
+4. **The moat** — what would make this defensible once established
+5. **Risk** — the biggest thing that could go wrong
+6. **Validation needed** — the cheapest, fastest experiment to test this before committing
+7. **Leverage score (1-5)** — how much impact relative to effort
+
+Also identify:
+- **The contrarian opportunity** — the one that goes against market consensus but is supported by evidence
+- **The timing play** — the one that depends on getting the timing right (a fragile assumption about to break)
+- **The safe bet** — the one with the most evidence and lowest risk
+
+Rank all opportunities by leverage score. Be honest about which ones are speculative vs. well-supported.
+```

.agents/skills/attack-surface/references/gatherer-prompt.md

@@ -0,0 +1,188 @@
+# Source Gatherer — Prompt Templates
+
+Use these templates when running Phase 2 source collection. Each gatherer, whether run directly or delegated, gets a specific focus area and the research brief.
+
+## Search Tool Instructions
+
+Include ONE of these blocks at the top of every gatherer prompt, depending on Exa availability:
+
+### If Exa MCP is available:
+```
+SEARCH TOOLS: Use Exa MCP for all searches.
+- `mcp__exa__web_search_exa` — neural search, returns relevant results with snippets
+- `mcp__exa__crawling_exa` — crawl a URL to get full page content (use maxCharacters: 10000)
+- `mcp__exa__deep_researcher_start` + `mcp__exa__deep_researcher_check` — for comprehensive research queries
+```
+
+### If Exa MCP is NOT available (fallback):
+```
+SEARCH TOOLS: Use the built-in web browsing tools available in the current Codex environment.
+- Use web search to find relevant pages and search variations.
+- Open the most relevant pages to read full content.
+- Preserve source URLs for every quote, data point, or claim you extract.
+For each search, run 2-3 different query variations to maximize coverage.
+```
+
+---
+
+## Template: Competitor Intelligence
+
+```
+You are gathering competitive intelligence for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find and analyze 5-8 competitor or key player websites in this market.
+
+Search queries to try:
+- "{market} software/platform/tool"
+- "best {market} solutions {year}"
+- "alternatives to {known_competitor}" (if any known)
+- "{market} startup"
+
+For each competitor found, crawl their landing page, pricing page, and about page.
+
+For each competitor, extract and return:
+- Company name and URL
+- Value proposition (their main headline/pitch)
+- Target audience (who they're speaking to)
+- Key features (top 5-10)
+- Pricing model (if visible)
+- Positioning language (how they differentiate)
+- Notable claims or promises
+
+Return a structured report with all competitors analyzed. Include direct quotes from their sites.
+```
+
+---
+
+## Template: Customer Voice
+
+```
+You are gathering customer sentiment for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find genuine customer opinions — complaints, praise, and unmet needs.
+
+Search queries to try:
+- "reddit {market} complaints"
+- "reddit {market} frustrating"
+- "reddit {market} switched from {competitor}"
+- "{competitor} review" or "{competitor} problems"
+- "site:producthunt.com {market}"
+- "{market} customer reviews G2 Trustpilot"
+
+Crawl the most relevant results to get full content.
+
+Extract and categorize:
+- **Recurring pain points** (what comes up again and again)
+- **Emotional triggers** (what makes people angry, excited, or frustrated)
+- **Feature requests** (what people wish existed)
+- **Switching triggers** (why people leave one solution for another)
+- **Praise patterns** (what people genuinely love)
+
+Include direct quotes with source URLs. Raw customer language is more valuable than your summary — preserve the exact words people use.
+```
+
+---
+
+## Template: Industry Analysis
+
+```
+You are gathering industry-level intelligence for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find broad industry context — market size, trends, expert analysis.
+
+Search queries to try:
+- "{market} market size growth trends {year}"
+- "{market} industry report"
+- "{market} market analysis {year}"
+- "{major_company} earnings call {market}" (if applicable)
+- "{market} regulatory changes"
+- "{market} technology disruption"
+
+If using Exa, also use `deep_researcher_start` with model `exa-research-pro` for comprehensive coverage.
+
+Extract:
+- **Market size and growth** (TAM/SAM/SOM if available)
+- **Key trends** (what's changing in this market)
+- **Regulatory landscape** (any regulations that matter)
+- **Technology shifts** (what new tech is enabling or disrupting)
+- **Expert predictions** (what industry analysts say is coming)
+- **Funding patterns** (who's investing, how much, in what)
+
+Cite specific numbers and sources. Vague claims like "the market is growing" without data are useless.
+```
+
+---
+
+## Template: Adjacent & Emerging
+
+```
+You are scanning for emerging threats and adjacent opportunities for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find what's coming next — new entrants, adjacent markets, and potential disruptors.
+
+Search queries to try:
+- "{market} startup {year}"
+- "{market} new entrant funding"
+- "pivot to {market}"
+- "{adjacent_market} expanding into {market}"
+- "AI {market}" or "{market} automation"
+- "Y Combinator {market}" or "TechCrunch {market} {year}"
+
+Crawl the most promising results.
+
+Extract:
+- **New entrants** (startups launched in last 2 years)
+- **Adjacent threats** (companies from other markets that could enter)
+- **Technology disruptors** (new tech that could change the game)
+- **Pivot signals** (companies pivoting toward this market)
+- **Funding patterns** (recent funding rounds in this space)
+- **Unconventional approaches** (anyone doing something radically different)
+
+Focus on what nobody in the established market is paying attention to yet.
+```
+
+---
+
+## Template: User-Provided Sources
+
+```
+You are extracting content from sources provided by the user for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Sources to crawl:
+{LIST_OF_URLS_OR_FILES}
+
+Your job: Extract full content from each source. For URLs, use crawling or page-open tools. For local files, use the file-reading tools available in the current environment.
+
+For each source, return:
+- Source URL/path
+- Title
+- Full extracted content (preserve structure)
+- Key takeaways relevant to the research brief (3-5 bullet points per source)
+
+These are sources the user specifically chose — they contain information the user considers important. Extract everything.
+```

.claude/agents-memory/debug-specialist/2026-03-25-turbopack-hang-vidstack-barrel.md

@@ -0,0 +1,17 @@
+# Turbopack Dev Server Hang — @vidstack/react + Barrel Circular Import
+
+**Applies when:** Next.js dev server hangs (290%+ CPU, 1GB+ RAM, no HTTP responses), or Turbopack enters infinite recompilation
+
+Three contributing factors found:
+
+1. **Barrel self-import in features/project**: `SubtitleRevisionStep.tsx` imports `TranscriptionEditor` from the barrel `@features/project` which re-exports `SubtitleRevisionStep` itself, creating a circular module evaluation chain. Fix: use direct subpath import.
+
+2. **FSD violation features->widgets**: `SubtitleRevisionStep` imports `TimelinePanel` from `@widgets/`, violating FSD layer direction. Not a direct cause of hang but exacerbates module graph complexity.
+
+3. **@vidstack/react internal dynamic imports**: The library uses 14+ dynamic `import()` calls internally. Combined with Turbopack's inability to create shared chunks between async chunks in dev mode (GitHub issue vercel/next.js#85119), this can cause pathological module duplication during HMR.
+
+**Reproduction**: Issue is intermittent — most reliably triggered when editing files that import from `@vidstack/react` while the browser has the project wizard page open. Fresh server starts work fine.
+
+**Quick fix**: Change `SubtitleRevisionStep.tsx` line 23 from `import { TranscriptionEditor } from "@features/project"` to `import { TranscriptionEditor } from "@features/project/TranscriptionEditor"`.
+
+**Long-term**: Consider upgrading to Next.js 16.2+ which includes 200+ Turbopack fixes.

.claude/agents-memory/devops-engineer/2026-03-24-bun-image-existing-user.md

@@ -0,0 +1,9 @@
+# oven/bun Base Image Has Existing Non-Root User
+
+**Applies when:** adding non-root user to any Dockerfile that uses `oven/bun` as base image (Remotion service, or future Bun-based services).
+
+- `oven/bun:1.3.10` ships with a `bun` user (UID 1000) and `bun` group (GID 1000).
+- Home directory is `/home/bun`, shell is `/bin/sh`.
+- Do NOT create a new `app` user with `groupadd`/`useradd` -- GID 1000 collision causes `groupadd: GID '1000' already exists` build failure.
+- Instead: `RUN chown -R bun:bun /app` then `USER bun`.
+- Verified: container runs as `uid=1000(bun) gid=1000(bun)`, `/app/out` is writable.

.claude/agents-memory/devops-engineer/2026-03-24-cap-drop-redis-failure.md

@@ -0,0 +1,9 @@
+# cap_drop: ALL Breaks redis-alpine Startup
+
+**Applies when:** adding Linux capability restrictions to Docker Compose services, especially Redis or any image that switches users at startup.
+
+- `redis:7-alpine` entrypoint calls `gosu redis` to drop from root to the `redis` user.
+- `gosu` requires `SETUID` and `SETGID` capabilities to switch users.
+- `cap_drop: ALL` without `cap_add: [SETUID, SETGID]` prevents the user switch, causing immediate container exit.
+- The container logs show no error -- it just exits silently with code 1.
+- Decision (2026-03-24): removed all cap_drop/cap_add from both compose files. For a dev-only local stack, the complexity and debugging cost outweigh the security benefit. Revisit for production deployment with proper per-service capability analysis.

.claude/agents-memory/devops-engineer/2026-03-24-docker-audit-findings.md

@@ -0,0 +1,18 @@
+# Docker Infrastructure Audit Findings
+
+**Applies when:** implementing any Docker fixes, setting up CI/CD, preparing for production deployment, or reviewing PRs that touch Dockerfiles or compose files.
+
+- Backend `.dockerignore` is missing `.env` exclusion -- security risk for future `COPY . .` changes.
+- Backend `.gitignore` is missing `.env` exclusion -- latent secret leak risk.
+- MinIO image is unpinned (`minio/minio` with no tag) -- all others are pinned.
+- No resource limits on any service. Remotion needs 4GB+ for Chromium/FFmpeg renders.
+- Health checks exist only on `db` and `redis`. Missing on `minio`, `api`, `worker`, `remotion`.
+- API health check requires a `GET /api/health/` endpoint (may not exist yet -- needs backend team).
+- No restart policies on any service.
+- Both Dockerfiles run as root -- non-root user should be added to `prod` stages (dev stage has bind-mount permission complications).
+- `build-essential` is in the `base` stage, bloating the prod image by ~200MB. Move to `deps` stage only.
+- Remotion Dockerfile missing BuildKit apt cache mounts (backend has them, remotion does not).
+- Environment variables duplicated between `api` and `worker` (14 identical vars) -- use `x-backend-env` YAML anchor.
+- Worker is missing `JWT_SECRET_KEY` that API has.
+- No CI/CD pipeline exists at all -- zero automation.
+- No frontend Dockerfile -- needs `output: 'standalone'` in next.config.mjs first.

.claude/agents-memory/devops-engineer/2026-03-24-docker-dev-vs-prod-stages.md

@@ -0,0 +1,16 @@
+# Docker Dev vs Prod Stage Split
+
+**Applies when:** modifying the backend Dockerfile or docker-compose.yml, debugging import issues in containers, or setting up CI/CD image builds.
+
+- Dockerfile has 4 stages: `base` (runtime only: ffmpeg) -> `deps` (build-essential + Python deps) -> `dev` (compose target) -> `prod` (CI/CD target).
+- `base` has only runtime deps (ffmpeg). `deps` adds build-essential for C extension compilation (psycopg2, etc.).
+- `dev` inherits from `deps` (has build-essential -- fine for dev). `prod` inherits from `base` (no build-essential) and copies the pre-compiled `.venv` from `deps` via `COPY --from=deps /app/.venv /app/.venv`.
+- The `dev` stage does NOT run `uv sync` for the project itself. It relies on `PYTHONPATH=/app` + bind-mounted source at `/app/cpv3`. This avoids the stale editable-install-vs-bind-mount conflict.
+- The `prod` stage uses `UV_LINK_MODE=copy` and `uv sync --frozen --no-dev` to create a fully self-contained image with code baked in.
+- `prod` stage runs as non-root user `app` (uid/gid 1000). Dev stage stays as root due to bind-mount permission complications.
+- `docker-compose.yml` targets the `dev` stage via `build.target: dev`.
+- For CI/CD, build the `prod` stage: `docker build --target prod -t cpv3-backend:prod .`
+- The `cpv3` project is declared as `source = { editable = "." }` in `uv.lock`. With `UV_LINK_MODE=copy`, uv creates a `.pth` editable finder that maps imports to `/app/cpv3`. In dev, the bind mount overlays this directory, making the installed copy irrelevant but not harmful. The `dev` stage eliminates this ambiguity entirely.
+- `watchfiles` CLI (from `uvicorn[standard]`) is used for worker auto-restart: `watchfiles --filter python 'dramatiq ...' /app/cpv3`.
+- OrbStack propagates filesystem events natively. Docker Desktop on macOS may need `WATCHFILES_FORCE_POLLING=true`.
+- Worker REMOTION_SERVICE_URL was fixed from `http://localhost:8001` to `http://remotion:3001`.

.claude/agents-memory/devops-engineer/2026-03-24-minio-version-upgrade.md

@@ -0,0 +1,11 @@
+# MinIO Version Pinning and xl Meta Compatibility
+
+**Applies when:** changing MinIO image tag, debugging MinIO startup failures, or resetting MinIO volumes.
+
+- MinIO does NOT support downgrades. Once data is written by a newer version, older versions cannot read it.
+- The xl meta version is a storage format version embedded in MinIO's data files. Version 3 was introduced in 2025 releases.
+- Previous pin `RELEASE.2024-11-07T00-52-20Z` could not read xl meta v3 data written by a `latest` pull.
+- Current pin: `RELEASE.2025-09-07T16-13-09Z` -- the last free release on Docker Hub before MinIO stopped publishing (Oct 2025).
+- `curl` was removed from MinIO Docker images after `RELEASE.2023-10-25T06-33-25Z` (UBI micro base). Healthcheck must use `mc ready local` instead of `curl -f`.
+- If MinIO volume data is truly unrecoverable (corrupted, not just version mismatch), the nuclear option is `docker volume rm cpv3_minio` -- but this destroys all stored media files.
+- MinIO GitHub repo was archived Feb 2026. Future images may need to come from alternative sources (alpine/minio, self-build).

.claude/agents-memory/devops-engineer/2026-03-24-network-segmentation.md

@@ -0,0 +1,11 @@
+# Network Segmentation in Docker Compose
+
+**Applies when:** modifying network topology, adding new services, debugging inter-service connectivity, or reviewing compose files.
+
+- Two custom bridge networks: `db-net` (data stores) and `app-net` (application tier).
+- `db` and `redis`: only on `db-net` -- not reachable from app-net-only services.
+- `minio`: on both `db-net` and `app-net` -- accessible from all services including Remotion.
+- `api` and `worker`: on both `db-net` and `app-net` -- can reach data stores and be reached by Remotion.
+- Remotion service joins `cofee_backend_app-net` (external network) -- can reach `minio` and `api`/`worker`, but NOT `db` or `redis` directly.
+- Remotion compose references `REDIS_URL: redis://redis:6379/0` in its environment -- this will NOT resolve since `redis` is only on `db-net`. If Remotion needs Redis access, Redis must be added to `app-net` as well.
+- The old default network (`cofee_backend_default`) is no longer created. Any external references to it must be updated to `cofee_backend_app-net`.

.claude/agents-memory/orchestrator/2026-03-24-docker-audit.md

@@ -0,0 +1,22 @@
+## Decision: Docker infrastructure audit — prioritized remediation plan
+## Task: Comprehensive audit of all Dockerfiles and docker-compose files for security, performance, and best practices
+## Agents Involved: DevOps Engineer, Security Auditor (expertise applied from agent definitions)
+
+## Context
+User requested full Docker audit. All 6 Docker files examined (2 Dockerfiles, 2 docker-compose.yml, 2 .dockerignore).
+
+## Key Decisions
+- Non-root user: MUST add to both Dockerfiles before any production deployment — both confirmed running as uid=0
+- build-essential: Move to separate builder stage to cut backend image from 1.72GB to ~900MB-1GB
+- Resource limits: Required on all services, especially Remotion (4GB limit for Chromium+FFmpeg)
+- Environment anchor: Extract duplicated env vars between api and worker into x-backend-env YAML anchor
+- Network isolation: Remotion should NOT have direct DB/Redis access — segment into frontend/backend/rendering networks
+
+## Conflicts Resolved
+- None (single-perspective audit, no inter-agent conflicts)
+
+## Context for Future Tasks
+- Affects: cofee_backend/Dockerfile, cofee_backend/docker-compose.yml, remotion_service/Dockerfile, remotion_service/docker-compose.yml, both .dockerignore files, both .gitignore files
+- Depends on: Health endpoint implementation (Backend Architect + Remotion Engineer) for H3
+- Watch for: When implementing health endpoints, ensure they match the healthcheck paths defined in compose (GET /api/health/ for backend, GET /health for remotion)
+- Watch for: backend .gitignore still missing .env exclusion — fix ASAP

.claude/agents-memory/performance-engineer/2026-04-05-scroll-lag-backdrop-filter.md

@@ -0,0 +1,17 @@
+# Scroll Lag from backdrop-filter Overuse
+
+**Applies when:** investigating scroll jank, GPU compositing issues, or paint storms on any page with many Card components
+
+The /projects page had 73 elements with `backdrop-filter` causing massive GPU compositing on every scroll frame. Each `backdrop-filter: blur()` forces the GPU to sample and blur all pixels behind the element on every frame.
+
+**Key sources removed:**
+- `body { background-attachment: fixed }` in global.scss — forces full repaint every scroll frame. Replaced with `body::before` pseudo-element using `position: fixed`.
+- `Card.module.scss` had `backdrop-filter: blur(16px) saturate(180%)` on every card — replaced with `color-mix()` solid background.
+- `ProjectCard.module.scss` `.statusBadge` had `backdrop-filter: blur(8px)` — removed.
+- `ProjectCard.module.scss` `.progressCircle::before` had `backdrop-filter: blur(2px)` — removed.
+
+**Kept:** Header `backdrop-filter` (single element, important UX). Added `will-change: transform` to promote to own compositing layer.
+
+**Added:** `content-visibility: auto` on `.projectList > *` to skip rendering off-screen cards.
+
+**Method:** Element count via Chrome DevTools `$$('[style*=backdrop], *').filter(...)` and Performance panel paint profiling.

.claude/agents-memory/security-auditor/2026-03-24-docker-security-audit.md

@@ -0,0 +1,26 @@
+# Docker Infrastructure Security Audit Findings
+
+**Applies when:** reviewing Docker configurations, adding new services to docker-compose, creating production deployment configs, or auditing container security.
+
+## Critical Issues (as of 2026-03-24)
+- `cofee_backend/.env` is tracked in git (committed in `0299949`). `.gitignore` has no `.env` entry.
+- `cofee_frontend/.env` is tracked in git (committed in `71b9749`). `.gitignore` only excludes `.env*.local`, not `.env`.
+- `cofee_backend/.dockerignore` does NOT exclude `.env` — secrets enter Docker build context.
+- `remotion_service/.gitignore` and `.dockerignore` correctly exclude `.env`.
+
+## High Issues
+- Both Dockerfiles (backend + remotion) run as root — no `USER` directive, no `adduser`.
+- `docker-compose.yml` has hardcoded defaults: `JWT_SECRET_KEY=dev-secret`, `postgres/postgres`, `minioadmin/minioadmin`.
+- Redis has no authentication (`--requirepass` not set), exposed on host port 6379.
+- All ports bound to `0.0.0.0` (shorthand format), not `127.0.0.1`.
+
+## Medium Issues
+- No network segmentation — all backend services on default bridge network.
+- No container resource limits (mem_limit, cpus).
+- No capability dropping (cap_drop: ALL).
+- MinIO image unpinned (`minio/minio` = latest). Other images pinned by tag, not digest.
+- Remotion compose mounts entire project dir (`.:/app:cached`), bypassing .dockerignore at runtime.
+- Chromium sandbox disabled (`REMOTION_PUPPETEER_NO_SANDBOX=1`) + running as root.
+
+## Remediation Status
+- All findings reported, none remediated yet as of this audit date.

.claude/agents/backend-architect.md

@@ -449,3 +449,9 @@ Your output must be:
 - **Specific** — "use SQLAlchemy `selectinload()` on the `media.files` relationship" not "consider eager loading"
 - **Challenging** — if the task is wrong or over-engineered, say so
 - **Teaching** — briefly explain WHY so the team learns
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:api-design` — REST API patterns, pagination, error responses
+- `everything-claude-code:docs` — look up current FastAPI/library docs

.claude/agents/backend-qa.md

@@ -547,3 +547,8 @@ Your output must be:
 - **Specific** — "add a parametrized test for soft-deleted project exclusion in `test_projects_endpoints.py`" not "consider testing soft deletes"
 - **Challenging** — if a test is testing nothing useful (tautological assertion, mock-only logic), say so
 - **Teaching** — briefly explain WHY a test matters so the team understands the risk it mitigates
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:python-testing` — pytest strategies, fixtures, mocking, coverage

.claude/agents/db-architect.md

@@ -423,3 +423,9 @@ When proposing schema changes, always specify:
 - Alembic migration code (both upgrade and downgrade)
 - Backfill strategy if adding NOT NULL columns to existing data
 - Impact on existing queries in repository.py files
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:postgres-patterns` — query optimization, schema design, indexing
+- `everything-claude-code:database-migrations` — migration best practices

.claude/agents/debug-specialist.md

@@ -28,6 +28,16 @@ Before doing anything else:
 
 ---
 
+# Hierarchy
+
+- **Lead:** Orchestrator (direct report — staff role)
+- **Tier:** 1 (Staff)
+- **Sub-team:** None (cross-cutting)
+
+You are a staff agent — you report directly to the orchestrator and can be dispatched by any lead or specialist who needs debugging/investigation expertise. You follow the same depth rules as leads: when dispatched by the orchestrator, you enter at depth 1 and can dispatch further at depth 2.
+
+Follow the dispatch protocol defined in the team protocol.
+
 # Identity
 
 Senior Debugging Engineer, 15+ years of experience across full-stack systems, distributed services, and production incident response. You have debugged everything from single-threaded race conditions to multi-service cascading failures at scale. You find root causes, not symptoms. You do not guess — you form hypotheses from evidence and test them systematically.

.claude/agents/devops-engineer.md

@@ -20,6 +20,16 @@ At the very start of every invocation:
 
 ---
 
+# Hierarchy
+
+- **Lead:** Orchestrator (direct report — staff role)
+- **Tier:** 1 (Staff)
+- **Sub-team:** None (cross-cutting)
+
+You are a staff agent — you report directly to the orchestrator and can be dispatched by any lead or specialist who needs infrastructure/deployment expertise. You follow the same depth rules as leads: when dispatched by the orchestrator, you enter at depth 1 and can dispatch further at depth 2.
+
+Follow the dispatch protocol defined in the team protocol.
+
 # Identity
 
 You are a **Senior Platform Engineer** with 12+ years of experience across Kubernetes, CI/CD pipeline design, infrastructure as code, and production operations. You have built deployment pipelines that catch bugs before humans and infrastructure that scales without paging at 3 AM. You have migrated monoliths to microservices on Kubernetes, designed zero-downtime deployment strategies for video processing platforms, set up observability stacks that turned "it's slow" reports into root-cause dashboards, and automated away entire on-call rotations through self-healing infrastructure.
@@ -244,7 +254,29 @@ Unlike other agents that only advise, you have Edit and Write tools. When the ta
 - Write Dockerfiles, compose files, CI pipeline definitions, Kubernetes manifests, Helm charts, or Terraform modules
 - Always write complete, runnable files — never pseudocode or partial snippets
 - Include inline comments explaining non-obvious configuration choices
-- Test locally where possible (e.g., `docker-compose config` for syntax validation)
+
+## Step 7 — Validate Your Changes
+
+**CRITICAL: Never claim work is done without running validation.** After editing ANY infrastructure file, you MUST validate that your changes actually work — not just that they parse.
+
+Pick the validation commands that match what you changed:
+
+| What you changed | Syntax validation | Runtime validation |
+|-----------------|-------------------|-------------------|
+| `docker-compose.yml` | `docker compose config --quiet` | `docker compose up --build` — verify services start, check logs/health |
+| `Dockerfile` | `docker build --target <stage> .` | Run the built image, confirm entrypoint works |
+| CI pipeline (`.github/workflows/`, `.gitlab-ci.yml`) | Act/gitlab-runner local validation if available | Dry-run or explain what cannot be validated locally |
+| Kubernetes manifests | `kubectl apply --dry-run=client -f <file>` | `kubectl apply` + `kubectl get pods` if cluster is available |
+| Helm charts | `helm template . \| kubectl apply --dry-run=client -f -` | `helm install --dry-run` |
+| Terraform/Pulumi | `terraform validate` / `pulumi preview` | `terraform plan` |
+| Nginx/Traefik config | `nginx -t` or equivalent | Restart/reload and confirm upstream routing |
+| Shell scripts / entrypoints | `shellcheck <file>` if available | Execute with test inputs |
+
+**Rules:**
+- If a service was broken and you fixed it, show evidence it now works (logs, health check output, running containers)
+- If runtime validation is impossible (e.g., no cluster access), explicitly state what you could not validate and why
+- Include validation output in your response (pass/fail, relevant log lines)
+- Never say "should work" — prove it or flag what's unproven
 
 ---
 
@@ -620,3 +652,9 @@ Your output must be:
 - **Complete** — write the actual infrastructure code (Dockerfiles, compose files, CI configs, K8s manifests), not just descriptions of what should exist
 - **Challenging** — if the requested infrastructure is over-engineered for the current scale, say so and propose a simpler alternative that grows with the team
 - **Teaching** — explain WHY an infrastructure choice matters so the team makes better decisions independently
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:docker-patterns` — Docker Compose, networking, container security
+- `everything-claude-code:deployment-patterns` — CI/CD, health checks, rollback strategies

.claude/agents/frontend-architect.md

@@ -482,3 +482,9 @@ Agent(subagent_type="code-simplifier:code-simplifier", prompt="Simplify the rece
 ```
 
 Include your FSD and architectural context in prompts so subagents enforce the right patterns.
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:frontend-patterns` — React/Next.js patterns, state management
+- `everything-claude-code:docs` — look up current Next.js/React docs

.claude/agents/frontend-qa.md

@@ -572,3 +572,8 @@ Agent(subagent_type="feature-dev:code-reviewer", prompt="Review cofee_frontend/s
 ```
 
 Include your testing context in prompts so subagents highlight code paths needing coverage.
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:e2e-testing` — Playwright patterns, Page Object Model, CI/CD integration

.claude/agents/ml-ai-engineer.md

@@ -31,6 +31,15 @@ At the very start of every invocation:
 
 ---
 
+# Hierarchy
+
+- **Lead:** Product Lead
+- **Tier:** 2 (Specialist)
+- **Sub-team:** Product
+- **Peers:** UI/UX Designer, Technical Writer
+
+Follow the dispatch protocol defined in the team protocol. You can dispatch other agents for consultations when at depth 2 or lower. At depth 3, use Deferred Consultations.
+
 # Identity
 
 You are a **Senior ML Engineer** with 12+ years of experience in speech-to-text systems, NLP pipelines, and practical ML deployment. You have shipped production ASR systems that process thousands of hours of audio daily, tuned Whisper models for domain-specific vocabulary, evaluated every major cloud ASR API head-to-head, and built inference pipelines that balance quality against cost per hour of audio.

.claude/agents/orchestrator.md

@@ -1,385 +1,144 @@
 ---
 name: orchestrator
 description: Senior Tech Lead — decomposes tasks, selects specialist agents, packages context, manages handoff chains. Invoke for any non-trivial task.
-tools: Read, Grep, Glob, Bash, Agent, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs
+tools: Glob, Bash, Agent
 model: opus
 ---
 
-# First Step
-
-Before doing anything else:
-
-1. Read the shared team protocol: `.claude/agents-shared/team-protocol.md`
-2. Read your memory directory: `.claude/agents-memory/orchestrator/` — scan every file for decisions that may affect the current task
-3. Then proceed to task analysis below
-
 # Identity
 
-You are a Senior Tech Lead with 15+ years of experience across full-stack development, infrastructure, and product. You are the decision-maker, not the implementer. Your value is knowing who knows best and giving them exactly the context they need.
+You are a task router. You decompose tasks and dispatch specialist agents. You NEVER analyze code, config, or infrastructure yourself.
 
-You NEVER write code. You plan, route, package context, and manage handoff chains. You think in systems, dependencies, risk surfaces, and information flows. When you see a task, you see the blast radius, the expertise gaps, the parallel opportunities, and the handoff chains before anyone writes a single line.
+Your ONLY job:
+1. Understand what the task needs
+2. Select the right agents
+3. Dispatch them using the Agent tool
+4. Collect their outputs
+5. Synthesize into a unified report
 
-You are opinionated and decisive. When you recommend an approach, you explain why the alternatives are worse. When you spot a risk the task didn't mention, you flag it. When the task itself is wrong, you say so.
+You do NOT have Read or Grep tools. This is intentional — you cannot read file contents because doing so causes you to analyze them yourself instead of dispatching specialists. The specialists read files.
 
-# Core Expertise
+# Team Roster
 
-- **Task decomposition** — breaking complex work into parallelizable phases with clear input/output contracts between agents
+20 agents in a 4-tier hierarchy:
-- **System design at architecture level** — understanding how frontend, backend, database, infrastructure, and video processing interact in this monorepo
-- **Risk assessment** — identifying security, performance, data integrity, and UX risks before they become problems
-- **Cross-domain knowledge** — broad (not deep) understanding of all 16 specialists' domains, enough to know when each is needed and what questions to ask them
-- **Information flow analysis** — seeing what data, contracts, and artifacts flow between agents and optimizing for parallelism
-- **Conflict mediation** — resolving disagreements between specialists by weighing domain authority and contextual factors
 
-## Context7 Documentation Lookup
+| Agent | Type | Dispatch for |
+|-------|------|-------------|
+| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
+| **Quality Lead** | Lead | Testing, security, performance, design compliance |
+| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
+| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
+| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
 
-Use context7 generically — query any library relevant to the task you're decomposing.
+Leads coordinate their sub-teams internally:
+- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
+- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
+- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
 
-Example: mcp__context7__query-docs with libraryId="/vercel/next.js" and topic="app router caching"
+Staff agents (DevOps Engineer, Debug Specialist) report directly to you.
 
-## Agent Capabilities (Post-Upgrade)
+**Architects** design specs and patterns. **Engineers** implement production code. **Leads** coordinate. **Staff** are cross-cutting.
-
-When dispatching agents, leverage their new capabilities:
-
-### Visual inspection tasks
-UI/UX Designer, Design Auditor, Debug Specialist, Frontend Architect, Performance Engineer, Product Strategist — all have Chrome browser access. Include "Use Chrome browser tools to..." in dispatch context when the task involves visual UI work.
-
-### Database tasks
-DB Architect, Performance Engineer, Backend Architect — have Postgres MCP for live schema inspection, slow query analysis, and EXPLAIN ANALYZE. Dispatch DB Architect for schema/migration work; Performance Engineer for query optimization.
-
-### Dramatiq / Redis debugging
-Debug Specialist, Backend Architect — have Redis MCP for queue inspection and pub/sub monitoring. Dispatch Debug Specialist for stuck jobs or missing WebSocket notifications.
-
-### Security scanning
-Security Auditor — has semgrep, bandit, pip-audit, gitleaks via CLI. Dispatch for any security review, dependency audit, or pre-deployment check.
-
-### Performance auditing
-Performance Engineer — has Lighthouse MCP for Core Web Vitals, Chrome for JS performance API, k6 for load testing. Dispatch for frontend or backend performance investigation.
-
-### Browser testing
-Frontend QA, Backend QA — have Playwright MCP for structured a11y snapshots and cross-browser testing. Dispatch for test plan design and integration verification.
-
-### Container management
-DevOps Engineer — has Docker MCP for container health, logs, and compose management. Dispatch for infrastructure issues.
 
 # How You Work
 
-For every task, follow this step-by-step reasoning process:
-
 ## Step 1: Classify the Task
 
-Read the task carefully and answer:
+From the task description alone (no file reading), answer:
 - What is being asked? (build, fix, audit, evaluate, document, decide, research)
-- What subprojects are affected? (frontend, backend, remotion, infrastructure, multiple)
+- What subprojects are affected? (frontend, backend, remotion, infrastructure)
-- What layers are involved? (UI, API, database, task queue, video pipeline, storage)
+- What domains are involved? (security, performance, infrastructure, architecture, UX)
-- What modules are touched? (users, projects, media, files, transcription, captions, jobs, notifications, tasks, webhooks, system)
 
-## Step 2: Analyze Affected Areas
+## Step 2: Find Affected File Paths
 
-Scan the codebase at a HIGH level. You are not reading implementation — you are mapping scope:
+Use `Glob` to discover which files exist. Example:
-- Which files/directories will this task touch?
+```
-- Which API contracts might change?
+Glob(pattern="**/Dockerfile*")
-- Which database schemas are involved?
+Glob(pattern="**/docker-compose*.yml")
-- Are there cross-service boundaries (frontend-backend, backend-remotion, backend-S3)?
+```
 
-## Step 3: Identify the Risk Surface
+This gives you file paths for dispatch context. You pass PATHS to specialists — they read the files.
 
-For this specific task, what could go wrong?
+## Step 3: Select Agents
-- **Security:** Does it touch auth, user input, file uploads, tokens, credentials?
-- **Performance:** Does it involve large datasets, complex queries, heavy renders, bundle size?
-- **Data integrity:** Does it change schemas, add tables, modify relations, create migrations?
-- **UX:** Does it introduce new UI flows, modals, multi-step processes, loading states?
-- **Cross-service:** Does it change API contracts between frontend/backend/remotion?
-- **Testing:** Does it add logic that needs edge case coverage?
 
-## Step 4: Select Agents
+Based on Steps 1-2, select the minimum agents needed:
 
-Based on Steps 1-3, select the FEWEST agents that cover the task. Every selected agent must have a clear, reasoned justification. Ask yourself:
+| Concern | Dispatch |
-- Does this task REQUIRE this specialist's expertise?
+|---------|----------|
-- What specific question or analysis will this specialist answer?
+| Architecture (API design, schema, cross-service) | Architecture Lead |
-- Could another already-selected specialist cover this?
+| Quality (testing, security, performance) | Quality Lead |
+| Product (UX, docs, ML/AI) | Product Lead |
+| Infrastructure (CI/CD, Docker, deployment) | DevOps Engineer (staff, direct) |
+| Debugging (root cause analysis) | Debug Specialist (staff, direct) |
 
-## Step 5: Determine Parallelism
+Every agent must have a justification: what question will they answer?
 
-Which agents can run simultaneously (no mutual dependencies) and which must wait for others' output? Map the dependency graph:
+## Step 4: Dispatch in Parallel
-- Phase 1: agents that need only the original task context
-- Phase 2: agents that need Phase 1 outputs
-- Phase 3 (rare): agents that need Phase 2 outputs
 
-## Step 6: Predict Handoffs
+Dispatch all independent agents simultaneously using multiple Agent tool calls in one response. Include in each dispatch:
 
-Based on information flow analysis, predict which agents will likely request handoffs to other agents. Pre-dispatch where possible to avoid serial waiting.
+```
+DISPATCH CONTEXT:
+  origin_task: "<original task>"
+  call_chain: ["orchestrator"]
+  current_depth: 1
+  max_depth: 3
+  initiating_agent: "orchestrator"
+  reason: "<why this agent>"
 
-## Step 7: Check Memory for Relevant Past Decisions
+TASK: <specific task for this agent>
 
-Before building the pipeline, scan `.claude/agents-memory/orchestrator/` for decisions related to:
+FILES TO ANALYZE:
-- The same modules, services, or features
+  - <file path 1>
-- Similar task types with established patterns
+  - <file path 2>
-- Upstream decisions this task depends on
 
-Include relevant decision context in your pipeline output.
+DELIVERABLE: <what you need back>
+```
 
-## Step 8: Build the Pipeline
+## Step 5: Synthesize
 
-Construct the phased dispatch plan with specific context for each agent.
+Collect all agent outputs. Attribute every finding to the agent that produced it. Resolve conflicts between agents (see Conflict Resolution). Return the unified report.
-
-## Step 9: Package Context with Memory
-
-For each specialist being dispatched:
-1. Check their memory directory (`.claude/agents-memory/<agent-name>/`) for relevant past findings
-2. Include relevant memories in their dispatch context
-3. Include relevant Orchestrator decision memories that affect their task
-4. Give them specific, actionable context — not vague instructions
-
-# Pipeline Selection
-
-Pipeline selection is CONTEXT-AWARE. There are NO static routing tables, NO task-type templates.
-
-For every task, you reason from first principles:
-
-1. **Analyze affected areas** — which subprojects, which layers, which modules. Scan the codebase structure, don't guess.
-2. **Identify risk surface** — security, performance, data integrity, UX implications specific to THIS task.
-3. **Select agents based on THIS specific context** — the fewest agents that cover the task fully. Every dispatch must have a reasoned justification tied to what you discovered in steps 1-2.
-4. **Determine parallelism** — which agents can run simultaneously vs. which depend on others' output. Map the actual information flow, don't assume serial execution.
-5. **Predict likely handoffs** — based on information flow analysis. What will each agent produce? Who else will need that output?
-
-**Pre-dispatch where possible.** If you know Agent B will need Agent A's output, but Agent B can start their own research/analysis with available context, dispatch both in Phase 1 with a note that Agent B will receive additional context from Agent A.
-
-**Rules:**
-- Every dispatch must have reasoned justification based on THIS task's context
-- No "just in case" dispatches — if you cannot articulate what the agent will produce and who needs it, don't dispatch them
-- No task-type templates — "a frontend feature always needs Frontend Architect + UI/UX Designer + Frontend QA" is WRONG. Maybe this feature is a one-line config change. Reason about the actual task.
-- Minimum viable team — start small, inject more agents if their outputs reveal the need
-
-## Frontend-Last Phasing Rule
-
-When a plan includes **Frontend Architect** or **Frontend QA**, and ALSO includes any of the following, the frontend agents MUST run in a later phase:
-
-| Run BEFORE frontend | Why |
-|---|---|
-| **Backend Architect** | Frontend needs finalized API contracts, response shapes, endpoint paths |
-| **DB Architect** | Schema decisions affect what data is available to the frontend |
-| **UI/UX Designer** | Frontend needs interaction specs, visual direction, component behavior |
-| **Design Auditor** | Design token / component compliance rules inform frontend implementation |
-
-**How to apply:**
-- Phase 1: Backend Architect, DB Architect, UI/UX Designer, Design Auditor (whichever are needed)
-- Phase 2: Frontend Architect, Frontend QA (receive Phase 1 outputs as context)
-- If only frontend agents are needed (no backend/design dependency), they run in Phase 1 as normal
-- This rule applies to the SAME task — if frontend and backend are working on unrelated aspects, they can parallelize
-
-This prevents the common failure mode where Frontend Architect designs a component tree before knowing the API contract or design specs, then must redo work after handoff results arrive.
-
-**Context injection into frontend prompts:** When dispatching frontend agents in Phase 2, include relevant outputs from Phase 1 agents in their prompt:
-- From **Backend Architect**: API endpoint paths, response schemas, error codes, auth requirements
-- From **DB Architect**: data model shapes, available fields, relationship structures
-- From **UI/UX Designer**: interaction specs, component behavior, visual direction, layout decisions
-- From **Design Auditor**: token compliance rules, component reuse requirements, accessibility constraints
-
-Summarize each Phase 1 output to its key decisions (max ~200 words per agent) — do not dump full outputs. The frontend agent needs actionable specs, not raw analysis.
-
-# Adaptive Context Injection
-
-After each agent returns results, analyze their output for signals that warrant additional specialists. This is reactive — you inject agents based on what was ACTUALLY discovered, not what you predicted.
-
-## Security Signals
-Agent mentions auth flows, tokens, credentials, user input validation, file upload handling, SQL construction, rate limiting, CORS, or session management.
-**Action:** Inject **Security Auditor** with the specific finding and the agent's context.
-
-## Performance Signals
-Agent mentions N+1 queries, large dataset processing, heavy joins, missing pagination, synchronous blocking in async context, bundle size concerns, unnecessary re-renders, or unoptimized image/video handling.
-**Action:** Inject **Performance Engineer** on that specific area with the agent's findings.
-
-## Data Integrity Signals
-Agent proposes new tables, schema changes, complex relations, new migrations, or changes to existing model fields.
-**Action:** Inject **DB Architect** to validate the schema design, migration strategy, and query implications.
-
-## UX Signals
-Agent proposes a new UI flow, modal, multi-step process, new interaction pattern, or significant visual change.
-**Action:** Inject **UI/UX Designer** to review the interaction design, or **Design Auditor** to verify consistency with existing patterns.
-
-## Cross-Service Signals
-Agent's recommendation changes an API contract between services (frontend-backend, backend-remotion), modifies shared types, or alters the data flow between services.
-**Action:** Inject the counterpart **Architect** (Frontend or Backend) to validate the contract change from the other side.
-
-## Testing Gaps
-Agent implements or recommends logic but doesn't mention edge cases, error handling, or boundary conditions.
-**Action:** Inject the relevant **QA agent** (Frontend QA or Backend QA) to identify test scenarios.
-
-# Dynamic Handoff Prediction
-
-Handoff prediction is based on reasoning about information flow, not templates.
-
-## Information Flow Analysis
-
-For each dispatched agent, answer:
-- **What will this agent produce?** (architecture recommendation, schema design, test plan, risk assessment, etc.)
-- **Who else in the team would need that output as input?** (Backend Architect produces API contract -> Frontend Architect needs to validate client-side consumption)
-- **Can I pre-dispatch the "receiver" now?** (If the receiver can start with available context, dispatch them early to avoid serial waiting)
-
-## Dependency Reasoning
-
-- **Domain boundaries:** Does the task touch a boundary between domains (API contract, DB schema, UI spec, video pipeline)? The agent on the other side of that boundary likely needs involvement.
-- **Expertise gaps:** Does the task require decisions outside a dispatched agent's expertise? They will request a handoff — anticipate it and pre-dispatch if possible.
-- **Validation artifacts:** Does one agent produce something another agent validates (code -> QA, design -> auditor, schema -> DB Architect)? Plan for this in your pipeline phases.
-
-## Parallel Opportunity Detection
-
-- If Agent A and Agent B will both eventually be needed with **no mutual dependency** -> dispatch both NOW in the same phase
-- If Agent A will likely produce output that Agent B needs -> dispatch A in Phase 1, B in Phase 2 with a dependency note
-- If Agent B can do useful preliminary work before receiving Agent A's output -> dispatch both in Phase 1, but mark B for continuation with A's results
-
-**Rules:**
-- Every dispatch justified by THIS task's context — no generic patterns
-- No templates — reason about the actual information flow
-- Minimize total pipeline depth — prefer parallel dispatch over serial chains
 
 # Conflict Resolution
 
-When two or more agents disagree in their recommendations:
+When agents disagree:
-
+1. If one has clear domain authority → defer to the specialist
-1. **Detect the conflict** from their outputs — look for contradictory recommendations, different technology choices, or incompatible architectural approaches.
+2. If genuinely ambiguous → escalate to the user with both perspectives and trade-offs
-
-2. **Assess domain authority:**
-   - If one agent has clear domain authority over the disputed area, defer to the specialist. Example: Performance Engineer and Backend Architect disagree on caching strategy -> defer to Performance Engineer on performance implications, Backend Architect on code organization.
-   - If the conflict spans domains equally, neither has clear authority.
-
-3. **If domain authority is clear:** Accept the specialist's recommendation and explain why to the other agent in continuation context.
-
-4. **If genuinely ambiguous:** Escalate to the user with:
-   - Both perspectives, presented fairly
-   - The trade-offs of each approach
-   - Your recommendation and reasoning
-   - A clear question for the user to decide
-
-Never silently pick a side in an ambiguous conflict. The user owns the final decision on trade-offs that affect their product.
 
 # Memory
 
-## Reading Memory (START of every task)
+You cannot read memory files (no Read tool). The main session will include relevant memory in your dispatch prompt when applicable. If you produce decisions worth remembering, include them in your output and the main session will save them.
-
-Before building your pipeline:
-
-1. **Read your own memory:** Scan every file in `.claude/agents-memory/orchestrator/` for decisions that affect the current task. Look for:
-   - Decisions about the same modules, services, or features
-   - Architectural choices that constrain the current task
-   - Past conflicts and their resolutions
-   - "Watch for" notes from previous decisions
-
-2. **Read specialist memory when dispatching:** Before dispatching each specialist, check `.claude/agents-memory/<agent-name>/` for relevant past findings. Include those findings in the dispatch context so specialists build on previous knowledge instead of re-discovering it.
-
-3. **Include in your output:** List relevant past decisions in the `RELEVANT PAST DECISIONS` section and specialist memories in the `SPECIALIST MEMORY TO INCLUDE` section.
-
-## Writing Memory (END of completed tasks)
-
-After a task is fully completed (all agents finished, results synthesized), write a decision summary to `.claude/agents-memory/orchestrator/<date>-<topic-slug>.md` with this format:
-
-```markdown
-## Decision: <what was decided>
-## Task: <original task summary>
-## Agents Involved: <which specialists were dispatched>
-
-## Context
-<why this task came up, what the constraints were>
-
-## Key Decisions
-- <decision 1>: <chosen approach> — Why: <reasoning>
-- <decision 2>: <chosen approach> — Why: <reasoning>
-
-## Agent Recommendations Summary
-- <Agent Name>: <their key recommendation, 1-2 lines>
-- <Agent Name>: <their key recommendation, 1-2 lines>
-
-## Conflicts Resolved
-- <if any agents disagreed, what was decided and why>
-
-## Context for Future Tasks
-- Affects: <which modules, services, or features>
-- Depends on: <upstream decisions this relied on>
-- Watch for: <things that might invalidate this decision>
-```
-
-**What NOT to save:**
-- Implementation details (that's in the code)
-- Ephemeral debugging sessions (the fix is in git history)
-- Agent outputs verbatim (too large — summarize the key decisions and reasoning)
 
 # Output Format
 
-Your output MUST follow this exact structure:
-
 ```
 TASK ANALYSIS:
-  <what this task is about, affected areas, risk surface>
+  <what is being asked, affected file paths, which domains>
 
 PIPELINE:
   Phase 1 (parallel):
-    - <Agent>: "<specific context and question for this agent>"
+    - <Agent>: "<task>"
-  Phase 2 (depends on Phase 1):
+    - <Agent>: "<task>"
-    - <Agent>: "<context including what they need from Phase 1>"
 
-HANDOFF PREDICTION:
+AGENTS DISPATCHED:
-  <reasoned predictions about inter-agent dependencies based on information flow analysis>
+  - <Agent Name>: dispatched via Agent tool ✓
+  - <Agent Name>: dispatched via Agent tool ✓
 
-CONTEXT TRIGGERS TO WATCH:
+SYNTHESIS (from agent outputs ONLY):
-  - If <signal> detected in agent output -> inject <Agent>
+  - [Agent Name] Finding 1...
-  - If <signal> detected in agent output -> inject <Agent>
+  - [Agent Name] Finding 2...
+  - [Agent Name] Finding 3...
 
-RELEVANT PAST DECISIONS:
+CONFLICTS (if any):
-  <summaries from orchestrator memory that affect this task, or "None found" if memory is empty>
+  <disagreements between agents and resolution>
-
-SPECIALIST MEMORY TO INCLUDE:
-  - <Agent>: "<relevant past findings from their memory dir to include in dispatch>"
 ```
 
-**Context packaging for each agent dispatch must include:**
+CRITICAL: Every finding in SYNTHESIS must be attributed to a dispatched agent. If you did not dispatch agents, SYNTHESIS must say "ERROR: No agents dispatched."
-- The specific task or question for that agent
-- Relevant codebase locations (file paths, modules, directories)
-- Constraints from the overall task
-- Relevant past decisions from orchestrator memory
-- Relevant past findings from that specialist's memory
-- What other agents are working on in parallel (so they can flag cross-cutting concerns)
-- What deliverable you need back from them
-
-# Subagents for Research
-
-Use these subagents to gather context before building your dispatch pipeline. They keep research output out of your main context window.
-
-| Subagent | Model | When to use |
-|----------|-------|-------------|
-| `Explore` | Haiku (fast) | Quick scan of affected files, module structure, directory layout — enough to scope the task |
-| `feature-dev:code-explorer` | Sonnet | Deep analysis when task scope is unclear — trace features, map dependencies, understand complexity |
-
-### Usage
-
-```
-Agent(subagent_type="Explore", prompt="List all files in cofee_backend/cpv3/modules/[module]/ and cofee_frontend/src/features/[domain]/. Thoroughness: quick")
-Agent(subagent_type="feature-dev:code-explorer", prompt="Trace how [feature] works across frontend, backend, and remotion service. Map the cross-service boundaries and API contracts involved.")
-```
-
-Use `Explore` for most scoping tasks. Use `feature-dev:code-explorer` only when the task touches unfamiliar areas or has unclear blast radius.
-
-# Research Protocol
-
-Your research is high-level and scoping-focused. You are mapping the terrain, not exploring caves.
-
-1. **Read the task and Claude's initial analysis thoroughly** — understand what is being asked, not just the surface request
-2. **Check recent git log** for related ongoing work that might conflict with this task
-3. **Scan affected modules/files at HIGH level** — directory structure, file names, imports. Enough to understand scope, not implementation.
-4. **Identify cross-service boundaries** — does this task touch the Frontend-Backend API contract? Backend-Remotion pipeline? S3 storage integration? Redis pub/sub?
-5. **WebSearch only for high-level architecture patterns** when the task type is genuinely unfamiliar — e.g., "event sourcing patterns for video processing pipelines." This is rare.
-6. **NEVER research implementation details** — that is the specialists' job. You don't need to know how Remotion's `interpolate()` works or what SQLAlchemy's async session lifecycle looks like. Your specialists do.
 
 # Anti-Patterns
 
-These are things you MUST NOT do:
+- **Never analyze file contents.** You don't have Read — if you're producing technical findings about code/config, something is wrong.
-
+- **Never produce un-attributed findings.** Every recommendation must cite which agent produced it.
-- **Never write code.** Not even pseudocode in your output. You plan, route, and package context. If you catch yourself writing an implementation, stop.
+- **Never dispatch all 20 agents.** Minimum viable team — 2-4 agents for most tasks.
-- **Never skip QA agents for "simple" changes.** Simple changes break things too. If the task modifies behavior, someone should think about edge cases.
+- **Never give vague context.** Include specific file paths and focused questions.
-- **Never dispatch all 15 agents at once.** If you think a task needs all specialists, you have not decomposed it well enough. Break it into smaller tasks.
+- **Never skip dispatch.** Even if the task seems simple, dispatch the specialist.
-- **Never give vague context to specialists.** "Look at the frontend and suggest improvements" is useless. "Review the TranscriptionModal component at `@features/project/TranscriptionModal` for re-render performance — it subscribes to the full notification store and may cause unnecessary renders when unrelated notifications arrive" is useful.
+- **Never serialize what can be parallel.** Independent agents go in the same phase.
-- **Never use static routing templates.** "Frontend feature = Frontend Architect + UI/UX Designer + Frontend QA" is lazy. Maybe this frontend feature is a config change that needs zero UI work. Reason about the actual task.
-- **Never dispatch without reasoned justification.** For every agent in your pipeline, you must be able to answer: "What specific question will this agent answer, and who needs their answer?"
-- **Never assume you know implementation details.** You have broad knowledge, not deep. When in doubt, dispatch the specialist — that's what they're for.
-- **Never ignore memory.** Past decisions exist for a reason. If your memory says "we chose Stripe for payments," don't dispatch the Product Strategist to evaluate payment providers again unless the task explicitly questions that decision.
-- **Never let agents duplicate work.** If two agents will analyze the same file, give them different questions. If their scope overlaps, consolidate into one dispatch with a broader question.
-- **Never produce a pipeline without checking for parallelism.** Serial execution when parallel is possible wastes time. Always ask: "Can any of these agents start now without waiting for others?"

.claude/agents/product-lead.md

@@ -620,3 +620,9 @@ Your output must be:
 - **Evidence-backed** — every pricing recommendation cites competitor data, benchmark data, or unit economics
 - **Challenging** — if a feature request has no monetization path or retention impact, say so and recommend what to build instead
 - **Teaching** — explain WHY a pricing decision works so the team develops product intuition
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `attack-surface` — strategic market research, competitive analysis via Exa/WebSearch
+- `everything-claude-code:market-research` — market sizing, competitor comparisons

.claude/agents/remotion-engineer.md

@@ -559,3 +559,8 @@ Your output must be:
 - **Specific** — "use `interpolate(frame, [startFrame, endFrame], [0, 1], { extrapolateRight: 'clamp' })` for fade-in" not "add a fade animation"
 - **Challenging** — if a caption design will look bad at 30fps or cause render issues, say so
 - **Teaching** — briefly explain WHY a Remotion pattern works the way it does, so the team builds intuition about deterministic rendering
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:video-editing` — FFmpeg, Remotion video processing pipelines

.claude/agents/security-auditor.md

@@ -446,3 +446,8 @@ Your output must be:
 - **Specific** — "the `/api/v1/users/` endpoint is missing `get_current_user` dependency" not "some endpoints may lack auth"
 - **Challenging** — if a requested feature introduces unacceptable security risk, say so and propose a secure alternative
 - **Teaching** — briefly explain the attack vector so the team understands WHY, not just what to fix
+
+## Available Skills
+
+Use the `Skill` tool to invoke when relevant to your task:
+- `everything-claude-code:security-review` — comprehensive security checklist for auth, input, APIs, file uploads

.claude/agents/technical-writer.md

@@ -17,6 +17,15 @@ At the very start of every invocation:
 
 ---
 
+# Hierarchy
+
+- **Lead:** Product Lead
+- **Tier:** 2 (Specialist)
+- **Sub-team:** Product
+- **Peers:** UI/UX Designer, ML/AI Engineer
+
+Follow the dispatch protocol defined in the team protocol. You can dispatch other agents for consultations when at depth 2 or lower. At depth 3, use Deferred Consultations.
+
 # Identity
 
 You are a Senior Technical Writer with 12+ years of experience across developer documentation, API references, and internal knowledge bases. You have documented everything from single-page REST APIs to sprawling microservice architectures at companies where documentation was the difference between teams shipping in a week and teams drowning in Slack questions. You have written documentation for FastAPI auto-doc ecosystems, React component libraries, and video processing pipelines.

.claude/agents/ui-ux-designer.md

@@ -22,6 +22,15 @@ Before doing anything else:
 
 ---
 
+# Hierarchy
+
+- **Lead:** Product Lead
+- **Tier:** 2 (Specialist)
+- **Sub-team:** Product
+- **Peers:** Technical Writer, ML/AI Engineer
+
+Follow the dispatch protocol defined in the team protocol. You can dispatch other agents for consultations when at depth 2 or lower. At depth 3, use Deferred Consultations.
+
 # Identity
 
 You are a **Senior Product Designer** with 15+ years of experience designing interfaces that feel inevitable — premium, minimal, zero cognitive friction. You have shipped design systems at scale, led UX for SaaS products with millions of users, and understand that the difference between "side project" and "I'd pay for this" lives in the details: consistent spacing, deliberate typography, considered empty states, and interactions that respect the user's time.

.claude/rules/agent-pipeline.md

@@ -2,26 +2,60 @@
 
 ## The Rule
 
-This project has a 16-agent specialist team (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research — you MUST consult with the developer team by dispatching the orchestrator and the specialist agents it selects.
+This project has a 19-agent specialist team (`.claude/agents/`). For ANY non-trivial task — bug hunt, code review, feature, audit, optimization, research, infrastructure, debugging — you MUST dispatch the appropriate specialist agents directly.
 
-Built-in agents (e.g. `feature-dev:code-reviewer`, `feature-dev:code-explorer`) may be used alongside the team, but the project's specialist agents must always be consulted.
+**You ARE the tech lead / orchestrator.** You analyze the task, select which agents to dispatch, send them in parallel, and synthesize their outputs. There is no separate orchestrator agent.
+
+## What You Must NOT Do
+
+- **Do NOT solve non-trivial tasks yourself.** If the task requires domain expertise (Docker, database, security, frontend architecture, etc.), dispatch the specialist agents.
+- **Do NOT investigate deeply, then decide whether to dispatch.** Identify affected files/areas, select agents, dispatch. Your own exploration should be limited to understanding the task well enough to write good dispatch prompts.
+
+## Team Roster
+
+| Agent | Type | Dispatch for |
+|-------|------|-------------|
+| **Architecture Lead** | Lead | API design, schema, cross-service, component architecture |
+| **Quality Lead** | Lead | Testing strategy, quality synthesis, test gap analysis |
+| **Product Lead** | Lead | UX, docs, ML/AI, monetization, feature strategy |
+| **DevOps Engineer** | Staff | CI/CD, Docker, Kubernetes, infrastructure, deployment |
+| **Debug Specialist** | Staff | Root cause analysis, cross-service debugging |
+
+Leads coordinate sub-teams internally:
+- Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
+- Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
+- Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
+
+**You can also dispatch specialists directly** when the task is clearly scoped to one domain:
+- `devops-engineer` for Docker/infra tasks
+- `security-auditor` for security reviews
+- `backend-architect` for API design
+- `frontend-architect` for component architecture
+- etc.
+
+Use leads when the task spans multiple specialists in their sub-team. Use specialists directly when the task is focused.
 
 ## Pipeline
 
 1. **Announce** what you're doing: "Consulting with the developer team to [task description]"
-2. **Dispatch the orchestrator** agent with your analysis of the task
+2. **Identify affected files** using Glob — get file paths for dispatch context
-3. **Follow the orchestrator's pipeline** — dispatch the specialists it selects, in the phases it defines
+3. **Select agents** — minimum viable team based on the task
-4. Built-in agents can run in parallel with the specialist team when useful
+4. **Dispatch agents in parallel** using the Agent tool — pass file paths and task description, NOT file contents
-5. **Report results** — synthesize all outputs into a coherent response, crediting which specialists contributed
+5. **Collect results** from all dispatched agents
+6. **Synthesize** — present the unified report to the user, crediting which specialists contributed
 
-## Announcement Format
+## Dispatch Context
 
-Always start with a brief announcement before dispatching agents:
+Every agent dispatch should include:
+- The specific task or question
+- File paths to analyze (the agent reads them itself)
+- Constraints from the overall task
+- What deliverable you need back
 
-> Consulting with the developer team: dispatching [Agent 1], [Agent 2], [Agent 3] to [task summary].
+## Skip Agents ONLY For
 
-This tells the user which specialists are working and on what.
+- Rename a variable, fix a typo, fix a single-line syntax error
+- Answer a quick factual question about the codebase
+- Run a command the user explicitly asked for
 
-## Why
+Everything else — even tasks that seem "simple" — gets dispatched to specialists.
-
-The specialist agents have project-specific context, MCP tools (Postgres, Redis, Docker, Chrome, Lighthouse), memory directories, handoff protocols, and the team protocol for consistent quality. Consulting them ensures domain-expert analysis alongside any built-in agent work.

.claude/rules/coding-style.md

@@ -0,0 +1,78 @@
+# Coding Style (Extended)
+
+Extends the style guidelines in CLAUDE.md with patterns from ECC.
+
+## Immutability
+
+Create new objects — never mutate existing ones:
+
+```typescript
+// WRONG: mutation
+user.name = newName;
+items.push(newItem);
+
+// RIGHT: immutable update
+const updated = { ...user, name: newName };
+const updatedItems = [...items, newItem];
+```
+
+```python
+# WRONG: mutation
+user["name"] = new_name
+items.append(new_item)
+
+# RIGHT: immutable (when it matters)
+updated = {**user, "name": new_name}
+updated_items = [*items, new_item]
+```
+
+Exception: Pydantic models and SQLAlchemy ORM objects are designed for mutation — use them as intended.
+
+## File Organization
+
+- 200-400 lines typical, 800 max per file
+- High cohesion, low coupling — one concept per file
+- Backend: module structure is fixed (models, schemas, repository, service, router) — don't add extra files
+- Frontend: FSD layers are fixed — don't add files outside the layer structure
+
+## Error Handling
+
+### Frontend
+- API errors: handle in TanStack Query `onError` callbacks or error boundaries
+- Form validation: `react-hook-form` with inline `register()` validation rules and `Controller` for controlled components. Error messages in Russian.
+- Never show raw error strings to users — map to user-friendly Russian messages
+
+### Backend
+- Raise `HTTPException` with appropriate status codes in routers
+- Service layer returns data or raises domain exceptions
+- Repository layer lets SQLAlchemy exceptions propagate (service handles them)
+- Store error messages as named constants with `ERROR_` prefix
+
+## Input Validation
+
+- Frontend: TypeScript interfaces + `react-hook-form` inline rules for form data, OpenAPI-generated types for API responses
+- Backend: Pydantic schemas validate all request bodies — never trust raw input
+- File uploads: validate extension + MIME type in files module
+- Never construct SQL from user input — SQLAlchemy handles parameterization
+
+## Named Constants
+
+```python
+# WRONG
+if status == "completed":
+    ...
+
+# RIGHT
+JOB_STATUS_COMPLETED = "completed"
+if status == JOB_STATUS_COMPLETED:
+    ...
+```
+
+```typescript
+// WRONG
+if (job.status === "completed") { ... }
+
+// RIGHT
+const JOB_STATUS_COMPLETED = "completed" as const;
+if (job.status === JOB_STATUS_COMPLETED) { ... }
+```

.claude/rules/git-workflow.md

@@ -0,0 +1,41 @@
+# Git Workflow
+
+## Commit Message Format
+
+```
+<type>(<scope>): <description>
+
+<optional body>
+```
+
+**Types:** feat, fix, refactor, docs, test, chore, perf, ci
+**Scopes:** frontend, backend, remotion, infra, shared (or omit for cross-cutting)
+
+Examples:
+- `feat(frontend): add transcription progress bar to ActionPanel`
+- `fix(backend): prevent duplicate job creation in tasks service`
+- `refactor(remotion): extract caption animation into reusable spring`
+- `chore(infra): update Docker Compose PostgreSQL to 16`
+
+## Branch Naming
+
+```
+<type>/<short-description>
+```
+
+Examples: `feat/caption-styles`, `fix/upload-mime-validation`, `refactor/fsd-media-module`
+
+## Pull Request Process
+
+1. Run verification before creating PR (see `verification.md` rule)
+2. Use `git diff main...HEAD` to see all changes from branch point
+3. Summarize ALL commits (not just the latest) in PR description
+4. Include test plan with specific scenarios
+5. Push with `-u` flag for new branches
+
+## Monorepo Considerations
+
+- Commits should touch ONE subproject when possible
+- Cross-service changes (e.g., new API endpoint + frontend consumer) go in separate commits within the same PR
+- Migration commits go BEFORE the code that uses them
+- Never commit `.env`, credentials, or lock files across subprojects

.claude/rules/performance.md

@@ -0,0 +1,52 @@
+# Performance Awareness
+
+## Frontend Performance
+
+### Bundle Size
+- Avoid importing entire libraries — use tree-shakable imports
+- Dynamic `import()` for heavy components (modals, editors, charts)
+- Check: `@next/bundle-analyzer` if bundle grows unexpectedly
+- Never import server-only code in client components
+
+### Rendering
+- Memoize expensive computations with `useMemo`/`useCallback` only when profiling shows a bottleneck — not preemptively
+- Avoid prop drilling through many layers — use stores or context at the right level
+- Keep `useEffect` dependency arrays tight — stale closures are better caught by the TypeScript hook than by runtime bugs
+
+### Images & Media
+- Always use `next/image` with explicit width/height or `fill` + `sizes`
+- Lazy-load below-the-fold images (default in next/image)
+- Video thumbnails: use S3 presigned URLs with appropriate cache headers
+
+## Backend Performance
+
+### Database Queries
+- Always use `.options(selectinload(...))` or `.options(joinedload(...))` for related data — N+1 queries are the #1 backend perf killer
+- Add `.limit()` to any query that could return unbounded results
+- Use `EXPLAIN ANALYZE` (via DB Architect agent or MCP postgres) before optimizing — measure, don't guess
+- Index foreign keys and columns used in WHERE/ORDER BY
+
+### Async Patterns
+- Never use `time.sleep()` — use `asyncio.sleep()` in async code
+- Never call sync I/O (file reads, HTTP requests) in async endpoints — use `run_in_executor` or async libraries
+- Dramatiq tasks are sync — that's fine, they run in worker processes
+
+### Caching
+- Use Redis for frequently-accessed, rarely-changed data (user settings, project metadata)
+- Cache at service layer, not repository layer
+- Always set TTL — no unbounded caches
+
+## Remotion Performance
+
+- Keep composition prop data minimal — don't pass full transcription objects, pass pre-processed caption arrays
+- Use `delayRender`/`continueRender` for async data loading in compositions
+- Prefer `interpolate()` over `spring()` for simple animations — springs are heavier
+
+## Agent Model Selection
+
+When dispatching subagents, consider token cost:
+- **Sonnet** (default): Standard development work, code generation, reviews
+- **Haiku**: Lightweight lookups, simple code transformations, data extraction
+- **Opus**: Complex architectural decisions, deep analysis, ambiguous requirements
+
+Use `model: "haiku"` parameter on Agent tool for cheap, focused tasks.

.claude/rules/verification.md

@@ -0,0 +1,73 @@
+# Post-Implementation Verification
+
+After completing any feature, bug fix, or refactor — run verification before claiming the work is done.
+
+## Base Verification (after every code change)
+
+### Frontend (`cofee_frontend/`)
+```bash
+cd cofee_frontend && bunx tsc --noEmit 2>&1 | head -30
+```
+Must pass. Pre-existing errors in `app/template.tsx:15` and `CreateProjectModal.tsx:57` are known — no new errors allowed.
+
+### Backend (`cofee_backend/`)
+```bash
+cd cofee_backend && uv run ruff check cpv3/ 2>&1 | head -20
+cd cofee_backend && uv run pytest 2>&1 | tail -30
+```
+Lint and tests must pass.
+
+### Remotion (`remotion_service/`)
+```bash
+cd remotion_service && bunx tsc --noEmit 2>&1 | head -30
+```
+Must pass.
+
+## Final Verification (before PR/merge)
+
+Run base verification PLUS:
+
+### Frontend
+```bash
+cd cofee_frontend && bun run build 2>&1 | tail -20       # Production build
+cd cofee_frontend && bun run test:e2e 2>&1 | tail -30    # Playwright E2E
+```
+
+### Backend
+```bash
+cd cofee_backend && uv run ruff format --check cpv3/     # Format check
+```
+
+If you changed models: `uv run alembic check` to verify migrations are up-to-date.
+
+## Verification Report
+
+```
+VERIFICATION REPORT
+===================
+Subproject:  [frontend/backend/remotion]
+Level:       [base/final]
+Type check:  [PASS/FAIL]
+Lint:        [PASS/FAIL]
+Tests:       [PASS/FAIL] (X passed, Y failed)
+Build:       [PASS/FAIL or SKIPPED]
+E2E:         [PASS/FAIL or SKIPPED]
+
+Files changed: [count]
+Status: [READY/NOT READY]
+
+Issues to fix:
+1. ...
+```
+
+## When to Skip
+
+- Typo fixes in comments
+- Documentation-only changes
+- Changes to CLAUDE.md / agent definitions
+
+## When to Always Run Final
+
+- Cross-service changes (frontend + backend)
+- Schema/model changes
+- Auth or security-related changes

.claude/skills/attack-surface/SKILL.md

@@ -0,0 +1,316 @@
+---
+name: attack-surface
+description: >
+  Strategic research framework that compresses months of market/competitive research into hours through structured power questions. Extracts unspoken industry insights, fragile market assumptions, and strategic attack surfaces from competitor data, reviews, and industry sources using parallel intelligence gathering.
+  Use when user says "attack surface", "research the market", "competitive analysis", "analyze competitors", "find market opportunity", "stress-test this idea", "market research", "evaluate opportunity", "find blind spots", "market entry", or when they want to deeply understand a market, evaluate a new direction, find industry blind spots, assess a partnership, or analyze opportunities.
+  Do NOT use for code review, testing, deployment, bug fixing, or implementation tasks.
+---
+
+# Attack Surface — Strategic Research Framework
+
+Compress months of market research into hours. The difference between 3 hours and 3 months isn't the amount of information — it's knowing which questions actually matter.
+
+Instead of "summarize these" or "analyze the competition", this framework extracts:
+- **UNSPOKEN INSIGHTS** — what successful players understand that customers never say out loud
+- **FRAGILE ASSUMPTIONS** — beliefs the entire market is built on, and how they break
+- **ATTACK SURFACES** — the blind spots, the fragile consensus, the opening nobody is talking about
+
+## Search Tool Selection
+
+**Primary: Exa MCP** — Use `mcp__exa__web_search_exa`, `mcp__exa__crawling_exa`, `mcp__exa__deep_researcher_start` when available. Best for neural search, crawling full pages, and deep research.
+
+**Fallback: WebSearch + WebFetch** — If Exa MCP is unavailable or returns errors, fall back to the built-in `WebSearch` tool for finding sources and `WebFetch` for crawling page content. WebSearch returns snippets; WebFetch gets full page text.
+
+**Detection:** At the start of Phase 2, test Exa with a simple search. If it fails, switch to WebSearch/WebFetch for the entire session and note this in the Source Dossier.
+
+## When to Use
+
+- Entering a new market or vertical
+- Evaluating a new feature direction for an existing project
+- Assessing a partnership or platform opportunity
+- Stress-testing a business idea before committing
+- Finding competitive blind spots and underserved niches
+- Any strategic question that benefits from deep evidence-based analysis
+
+## Workflow Overview
+
+7 phases, alternating between automated intelligence gathering and user-guided analysis:
+
+| Phase | Name | Mode | Output |
+|-------|------|------|--------|
+| 1 | Briefing | Interactive | Research brief |
+| 2 | Source Collection | Automated (parallel) | Source dossier |
+| 3 | Unspoken Insights | Automated + checkpoint | Insight report |
+| 4 | Fragile Assumptions | Automated + checkpoint | Assumption map |
+| 5 | Investor Stress-Test | Automated + checkpoint | Stress-test results |
+| 6 | Opportunity Mapping | Automated + checkpoint | Opportunity matrix |
+| 7 | Action Plan & Save | Automated | Final research document |
+
+---
+
+## Phase 1: Briefing
+
+Start by understanding what the user wants to research. This is an interactive conversation — ask questions until you have a clear research brief.
+
+**Gather:**
+1. **Target** — What market, industry, or opportunity? (e.g., "yacht brokerage SaaS", "AI flashcards for language teachers", "mobile reading apps")
+2. **Angle** — What's the user's position? Entering as newcomer, expanding existing product, evaluating partnership?
+3. **Known competitors** — Any specific companies or products the user already knows about?
+4. **User-provided sources** — URLs, files, documents the user wants included? Accept any format.
+5. **Specific questions** — Anything particular the user wants answered beyond the standard framework?
+
+**Project context:** If the research relates to an existing project the user is working on, ask about the current product, tech stack, and strategic position. This grounds the analysis in real context rather than hypotheticals.
+
+**Output a research brief** before proceeding:
+```
+Research Brief:
+- Target: [market/opportunity]
+- Angle: [newcomer / existing player / evaluator]
+- Known competitors: [list]
+- User sources: [list of URLs/files]
+- Key questions: [specific questions beyond standard framework]
+- Project context: [if applicable, key facts about the user's product]
+```
+
+Ask user to confirm before proceeding to Phase 2.
+
+---
+
+## Phase 2: Source Collection
+
+This is the intelligence-gathering phase. Launch parallel subagents to collect diverse source material. The quality of analysis depends on the quality and diversity of sources.
+
+### Tool availability check
+
+Before launching subagents, test Exa MCP availability:
+- Try a simple `mcp__exa__web_search_exa` call
+- If it succeeds → use Exa tools in all subagents
+- If it fails → instruct all subagents to use `WebSearch` + `WebFetch` instead
+
+### What to gather
+
+Launch 4-6 parallel `general-purpose` subagents, each focused on a different source type.
+
+**Subagent 1: Competitor Intelligence**
+Search for and crawl 5-8 competitor landing pages, product pages, and pricing pages. Extract: value propositions, positioning, pricing models, feature lists, target audience language.
+
+**Subagent 2: Customer Voice**
+Search Reddit, forums, review sites (G2, Trustpilot, Product Hunt, App Store reviews) for customer complaints, praise, and unmet needs in this market. Extract: recurring pain points, feature requests, emotional language, switching triggers.
+
+**Subagent 3: Industry Analysis**
+Search for industry reports, expert analysis, trend pieces, and earnings call transcripts. Extract: market size, growth trends, key players, regulatory landscape, technology shifts.
+
+**Subagent 4: Adjacent & Emerging**
+Search for startups entering this space, adjacent markets that could expand into it, and emerging technologies that could disrupt it. Extract: new entrants, pivot signals, technology trends, funding patterns.
+
+**Subagent 5: User-Provided Sources** (if any)
+Crawl all URLs the user provided. Extract full content.
+
+### Subagent prompt template
+
+Read `references/gatherer-prompt.md` for the detailed prompt template to use for each subagent. Each subagent receives:
+- The research brief from Phase 1
+- Its specific focus area
+- Instructions for which search tool to use (Exa or WebSearch/WebFetch)
+
+### After collection
+
+Compile all subagent results into a **Source Dossier** — a structured document with all collected evidence organized by source type. Present a summary to the user:
+
+```
+Source Dossier Summary:
+- Search tools used: [Exa MCP / WebSearch+WebFetch]
+- X competitor pages analyzed
+- X customer reviews/complaints collected
+- X industry reports found
+- X emerging players identified
+- X user-provided sources crawled
+Key themes so far: [2-3 sentences]
+```
+
+Ask: "Sources collected. Anything you want me to search for specifically before we start analysis? Or should I proceed?"
+
+---
+
+## Phase 3: Unspoken Insights
+
+The first analytical question — the one that separates this from generic "market analysis":
+
+> "Based on all collected evidence: What does every successful player in this market understand that their customers never say out loud?"
+
+This question works because it forces the analysis past surface-level features and pricing into the deeper truths that drive the market.
+
+**Run this as a subagent** — launch a `general-purpose` subagent with the full Source Dossier and the analysis prompt from `references/analyst-prompt.md` (Section: Unspoken Insights).
+
+**Present findings** to the user as 3-5 numbered insights, each with:
+- The insight itself (one clear sentence)
+- Evidence from sources (specific quotes, data points)
+- Why this matters strategically
+
+**Checkpoint:** "Here are the unspoken insights I found. Do any of these surprise you? Want me to dig deeper on any of them, or should we move to fragile assumptions?"
+
+---
+
+## Phase 4: Fragile Assumptions
+
+The second power question:
+
+> "What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
+
+This question maps the market's attack surface — the beliefs everyone takes for granted that could be upended.
+
+**Run as subagent** with Source Dossier + Phase 3 insights. Use prompt from `references/analyst-prompt.md` (Section: Fragile Assumptions).
+
+**Present findings** as a structured assumption map:
+
+For each assumption:
+- **The assumption** (what everyone believes)
+- **Evidence it's true** (why people believe this)
+- **What breaks it** (specific conditions that would make it wrong)
+- **Fragility score** (1-5: how likely is it to break in the next 2-3 years?)
+- **If it breaks** (what happens to the market)
+
+**Checkpoint:** "These are the fragile assumptions I found. Any you disagree with? Want to explore any further?"
+
+---
+
+## Phase 5: Investor Stress-Test
+
+The third power question:
+
+> "Write 5 questions a world-class investor would ask to destroy this business idea, then answer each one using only the evidence in our source dossier."
+
+This is adversarial by design. The goal is to find every weak point before committing resources.
+
+**Run as subagent** with Source Dossier + all prior analysis. Use prompt from `references/analyst-prompt.md` (Section: Investor Stress-Test).
+
+**Present findings** as 5 numbered challenges:
+
+For each:
+- **The killer question** (phrased as an investor would ask it)
+- **The evidence-based answer** (citing only our sources)
+- **Confidence level** (strong / moderate / weak)
+- **Remaining risk** (what the answer doesn't fully address)
+
+### Iterative Deepening
+
+For any answer rated "weak" confidence, automatically follow up:
+
+> "What's the strongest version of this argument and where does it still break?"
+
+Continue until all weak points are either resolved or clearly flagged as genuine risks.
+
+**Checkpoint:** "Here's the stress-test. X questions have strong answers, Y have remaining risks. Want to dig deeper on any of these?"
+
+---
+
+## Phase 6: Opportunity Mapping
+
+Now synthesize everything into actionable opportunities:
+
+> "Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves? For each, what's the evidence, what's the risk, and what would you need to validate first?"
+
+**Run as subagent** with ALL prior analysis. Use prompt from `references/analyst-prompt.md` (Section: Opportunity Mapping).
+
+**Present** as an opportunity matrix:
+
+| Opportunity | Evidence | Risk | Validation Needed | Leverage (1-5) |
+|-------------|----------|------|-------------------|----------------|
+| ... | ... | ... | ... | ... |
+
+**Checkpoint:** "These are the highest-leverage opportunities I see. Which ones resonate? Should I develop any of them into a concrete action plan?"
+
+---
+
+## Phase 7: Action Plan & Save
+
+Based on user's selections from Phase 6, create a concrete action plan:
+
+1. **Immediate next steps** (this week)
+2. **Validation experiments** (this month)
+3. **Strategic moves** (this quarter)
+
+### Save the Document
+
+Compile ALL phases into a single research document and save it.
+
+Use this format:
+
+```markdown
+---
+id: RESEARCH-YYYY-MM-DD-attack-surface-{slug}
+created: YYYY-MM-DD
+topic: Attack Surface Analysis — {Topic}
+sources: [list of source types used]
+search_tools: [Exa MCP / WebSearch+WebFetch]
+tags: [attack-surface, market-research, {topic-tags}]
+---
+
+# Attack Surface: {Topic}
+
+## Executive Summary
+[3-5 bullet points with the most important findings]
+
+## Research Brief
+[From Phase 1]
+
+## Source Dossier Summary
+[From Phase 2 — source counts and key themes]
+
+## Unspoken Insights
+[From Phase 3]
+
+## Fragile Assumptions
+[From Phase 4 — the assumption map]
+
+## Investor Stress-Test
+[From Phase 5 — questions, answers, confidence levels]
+
+## Opportunity Matrix
+[From Phase 6]
+
+## Action Plan
+[From Phase 7]
+
+## Raw Sources
+[Links to all sources consulted]
+```
+
+Save to the project root as `RESEARCH-YYYY-MM-DD-attack-surface-{slug}.md`. Tell the user the file path and offer to discuss any findings further.
+
+---
+
+## Subagent Instructions
+
+All subagents use the `general-purpose` subagent type via the Agent tool. Read the reference files for detailed prompt templates:
+
+- `references/gatherer-prompt.md` — Prompt template for Phase 2 source collection subagents
+- `references/analyst-prompt.md` — Prompt templates for Phases 3-6 analysis subagents
+
+When launching subagents:
+- Phase 2: Launch 4-6 gatherers **in parallel** (one Agent tool call per search focus)
+- Phases 3-6: Launch **sequentially** (each builds on prior results)
+- Always pass the full Source Dossier to analysis subagents
+- Set `run_in_background: false` for analysis subagents (need results before proceeding)
+- Always include the search tool instructions (Exa vs WebSearch) in subagent prompts
+
+### Token Budget
+
+This skill launches 6-10 subagent calls total. Estimated cost:
+- Phase 2: 4-6 subagents x ~5-15K tokens each
+- Phases 3-6: 4 subagents x ~10-20K tokens each
+- Total: ~60-150K tokens per full research session
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Skipping Phase 1 briefing | The research brief focuses everything — never skip |
+| Generic searches | Use specific, targeted queries from the research brief |
+| Presenting analysis without evidence | Every insight must cite specific sources |
+| Moving past weak stress-test answers | Always run iterative deepening on weak answers |
+| Forgetting to save | Always save the final document at the end |
+| Ignoring user-provided sources | Crawl them FIRST — the user chose them for a reason |
+| Not testing Exa availability | Always test before launching parallel subagents |

.claude/skills/attack-surface/references/analyst-prompt.md

@@ -0,0 +1,151 @@
+# Analysis Subagent — Prompt Templates
+
+Use these templates when launching Phases 3-6 analysis subagents. Each receives the Source Dossier and prior analysis results. All analysis subagents should use `general-purpose` subagent type.
+
+---
+
+## Section: Unspoken Insights (Phase 3)
+
+```
+You are a strategic analyst conducting deep market research.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Your task: Answer this question with rigorous evidence from the sources above:
+
+"What does every successful player in this market understand that their customers never say out loud?"
+
+This isn't about features or pricing. It's about the deeper truths — the things that take founders 2 years of customer calls to figure out. The psychological patterns, the hidden motivations, the unspoken expectations.
+
+Look for:
+- Patterns in what successful companies do but don't advertise
+- Gaps between what customers SAY they want and what they actually pay for
+- Emotional undercurrents in customer complaints and reviews
+- Things competitors all do the same way (unspoken consensus)
+- Customer behaviors that contradict their stated preferences
+
+Return exactly 3-5 insights. For each:
+1. **The insight** — one clear, provocative sentence
+2. **Evidence** — 2-3 specific quotes or data points from the sources, with source URLs
+3. **Strategic implication** — why this matters for someone entering or competing in this market
+
+Be specific and evidence-based. Generic observations like "customers want a good user experience" are worthless. We need insights that would make an industry veteran say "it took me years to figure that out."
+```
+
+---
+
+## Section: Fragile Assumptions (Phase 4)
+
+```
+You are a strategic analyst mapping the attack surface of a market.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Prior analysis — Unspoken Insights:
+{PHASE_3_RESULTS}
+
+Your task: Answer this question:
+
+"What are the 3-5 assumptions this entire market is built on, and what would have to be true for each one to be wrong?"
+
+Every market operates on a set of shared beliefs that nobody questions. These are the load-bearing assumptions — if one breaks, the entire competitive landscape shifts. Your job is to find them.
+
+Look for:
+- Pricing models everyone copies (is there a reason, or just convention?)
+- Distribution channels everyone uses (what if a new channel emerges?)
+- Customer segments everyone targets (who is being ignored?)
+- Technology choices everyone makes (what if the tech shifts?)
+- Business models everyone follows (what if a different model works?)
+- Regulations everyone plans around (what if they change?)
+
+For each assumption, return:
+1. **The assumption** — what everyone in this market believes
+2. **Evidence it's currently true** — why this belief is reasonable today (cite sources)
+3. **Breaking conditions** — specific, concrete conditions that would make it false
+4. **Fragility score (1-5)** — how likely these conditions are in the next 2-3 years
+   - 1 = rock solid, would take a black swan
+   - 3 = plausible, early signals visible
+   - 5 = already cracking, evidence of change in sources
+5. **If it breaks** — what happens to the market, who wins, who loses
+
+Focus on assumptions scored 3-5. Those are the real attack surfaces.
+```
+
+---
+
+## Section: Investor Stress-Test (Phase 5)
+
+```
+You are a world-class venture investor reviewing a potential investment. Your reputation depends on finding fatal flaws BEFORE writing a check. You've seen 10,000 pitches and killed 9,900 of them.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Source Dossier:
+{FULL_SOURCE_DOSSIER}
+
+Prior analysis:
+- Unspoken Insights: {PHASE_3_RESULTS}
+- Fragile Assumptions: {PHASE_4_RESULTS}
+
+Your task:
+
+Step 1: Write 5 questions that would destroy this business idea. Not softballs — the questions that make founders sweat. The ones that expose whether they've really done their homework or are running on hope.
+
+Step 2: Answer each question using ONLY the evidence in the Source Dossier and prior analysis. No hand-waving. If the evidence doesn't support a strong answer, say so.
+
+For each of the 5 questions:
+1. **The killer question** — phrased as an investor would ask it, sharp and direct
+2. **The evidence-based answer** — using only our collected sources
+3. **Confidence level** — STRONG (evidence clearly supports), MODERATE (evidence partially supports), or WEAK (evidence is thin or contradictory)
+4. **Remaining risk** — what the answer doesn't fully address
+
+Step 3: For any answer rated WEAK, follow up with:
+"What's the strongest possible version of the argument for this idea, and where does it still break?"
+
+The goal is not to kill the idea — it's to stress-test it so thoroughly that whatever survives is genuinely defensible.
+```
+
+---
+
+## Section: Opportunity Mapping (Phase 6)
+
+```
+You are a strategic advisor synthesizing an entire research sprint into actionable opportunities.
+
+Research brief:
+{RESEARCH_BRIEF}
+
+All prior analysis:
+- Unspoken Insights: {PHASE_3_RESULTS}
+- Fragile Assumptions: {PHASE_4_RESULTS}
+- Investor Stress-Test: {PHASE_5_RESULTS}
+
+Your task:
+
+"Given all the unspoken insights, fragile assumptions, and blind spots we've found — what are the 3 highest-leverage entry points or strategic moves?"
+
+For each opportunity:
+1. **The opportunity** — one clear sentence describing the strategic move
+2. **Why now** — what's changed (or changing) that makes this viable
+3. **Evidence** — specific findings from our research that support this
+4. **The moat** — what would make this defensible once established
+5. **Risk** — the biggest thing that could go wrong
+6. **Validation needed** — the cheapest, fastest experiment to test this before committing
+7. **Leverage score (1-5)** — how much impact relative to effort
+
+Also identify:
+- **The contrarian opportunity** — the one that goes against market consensus but is supported by evidence
+- **The timing play** — the one that depends on getting the timing right (a fragile assumption about to break)
+- **The safe bet** — the one with the most evidence and lowest risk
+
+Rank all opportunities by leverage score. Be honest about which ones are speculative vs. well-supported.
+```

.claude/skills/attack-surface/references/gatherer-prompt.md

@@ -0,0 +1,187 @@
+# Source Gatherer — Subagent Prompt Templates
+
+Use these templates when launching Phase 2 subagents. Each subagent gets a specific focus area and the research brief.
+
+## Search Tool Instructions
+
+Include ONE of these blocks at the top of every subagent prompt, depending on Exa availability:
+
+### If Exa MCP is available:
+```
+SEARCH TOOLS: Use Exa MCP for all searches.
+- `mcp__exa__web_search_exa` — neural search, returns relevant results with snippets
+- `mcp__exa__crawling_exa` — crawl a URL to get full page content (use maxCharacters: 10000)
+- `mcp__exa__deep_researcher_start` + `mcp__exa__deep_researcher_check` — for comprehensive research queries
+```
+
+### If Exa MCP is NOT available (fallback):
+```
+SEARCH TOOLS: Use built-in WebSearch and WebFetch.
+- `WebSearch` — search the web, returns result snippets. Run multiple searches with different queries.
+- `WebFetch` — fetch full page content from a URL. Use for competitor pages, articles, reviews.
+For each search, run 2-3 different query variations to maximize coverage.
+```
+
+---
+
+## Template: Competitor Intelligence
+
+```
+You are gathering competitive intelligence for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find and analyze 5-8 competitor or key player websites in this market.
+
+Search queries to try:
+- "{market} software/platform/tool"
+- "best {market} solutions {year}"
+- "alternatives to {known_competitor}" (if any known)
+- "{market} startup"
+
+For each competitor found, crawl their landing page, pricing page, and about page.
+
+For each competitor, extract and return:
+- Company name and URL
+- Value proposition (their main headline/pitch)
+- Target audience (who they're speaking to)
+- Key features (top 5-10)
+- Pricing model (if visible)
+- Positioning language (how they differentiate)
+- Notable claims or promises
+
+Return a structured report with all competitors analyzed. Include direct quotes from their sites.
+```
+
+---
+
+## Template: Customer Voice
+
+```
+You are gathering customer sentiment for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find genuine customer opinions — complaints, praise, and unmet needs.
+
+Search queries to try:
+- "reddit {market} complaints"
+- "reddit {market} frustrating"
+- "reddit {market} switched from {competitor}"
+- "{competitor} review" or "{competitor} problems"
+- "site:producthunt.com {market}"
+- "{market} customer reviews G2 Trustpilot"
+
+Crawl the most relevant results to get full content.
+
+Extract and categorize:
+- **Recurring pain points** (what comes up again and again)
+- **Emotional triggers** (what makes people angry, excited, or frustrated)
+- **Feature requests** (what people wish existed)
+- **Switching triggers** (why people leave one solution for another)
+- **Praise patterns** (what people genuinely love)
+
+Include direct quotes with source URLs. Raw customer language is more valuable than your summary — preserve the exact words people use.
+```
+
+---
+
+## Template: Industry Analysis
+
+```
+You are gathering industry-level intelligence for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find broad industry context — market size, trends, expert analysis.
+
+Search queries to try:
+- "{market} market size growth trends {year}"
+- "{market} industry report"
+- "{market} market analysis {year}"
+- "{major_company} earnings call {market}" (if applicable)
+- "{market} regulatory changes"
+- "{market} technology disruption"
+
+If using Exa, also use `deep_researcher_start` with model `exa-research-pro` for comprehensive coverage.
+
+Extract:
+- **Market size and growth** (TAM/SAM/SOM if available)
+- **Key trends** (what's changing in this market)
+- **Regulatory landscape** (any regulations that matter)
+- **Technology shifts** (what new tech is enabling or disrupting)
+- **Expert predictions** (what industry analysts say is coming)
+- **Funding patterns** (who's investing, how much, in what)
+
+Cite specific numbers and sources. Vague claims like "the market is growing" without data are useless.
+```
+
+---
+
+## Template: Adjacent & Emerging
+
+```
+You are scanning for emerging threats and adjacent opportunities for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Your job: Find what's coming next — new entrants, adjacent markets, and potential disruptors.
+
+Search queries to try:
+- "{market} startup {year}"
+- "{market} new entrant funding"
+- "pivot to {market}"
+- "{adjacent_market} expanding into {market}"
+- "AI {market}" or "{market} automation"
+- "Y Combinator {market}" or "TechCrunch {market} {year}"
+
+Crawl the most promising results.
+
+Extract:
+- **New entrants** (startups launched in last 2 years)
+- **Adjacent threats** (companies from other markets that could enter)
+- **Technology disruptors** (new tech that could change the game)
+- **Pivot signals** (companies pivoting toward this market)
+- **Funding patterns** (recent funding rounds in this space)
+- **Unconventional approaches** (anyone doing something radically different)
+
+Focus on what nobody in the established market is paying attention to yet.
+```
+
+---
+
+## Template: User-Provided Sources
+
+```
+You are extracting content from sources provided by the user for a strategic research project.
+
+{SEARCH_TOOL_INSTRUCTIONS}
+
+Research brief:
+{RESEARCH_BRIEF}
+
+Sources to crawl:
+{LIST_OF_URLS_OR_FILES}
+
+Your job: Extract full content from each source. For URLs, use crawling tools (Exa crawling or WebFetch). For local files, use the Read tool.
+
+For each source, return:
+- Source URL/path
+- Title
+- Full extracted content (preserve structure)
+- Key takeaways relevant to the research brief (3-5 bullet points per source)
+
+These are sources the user specifically chose — they contain information the user considers important. Extract everything.
+```

.claudeignore

@@ -1,31 +1,39 @@
 # Dependencies
+
 node_modules/
 .venv/
 
 # Build output
+
 .next/
-__pycache__/
+**pycache**/
-*.pyc
+\*.pyc
 dist/
 build/
 
 # Generated files (read-only, should not be edited)
-cofee_frontend/src/shared/api/__generated__/
+
+cofee_frontend/src/shared/api/**generated**/
 
 # Lock files
+
 bun.lock
 uv.lock
 
 # Environment
+
 .env
-.env.*
+.env.\*
 
 # IDE & OS
+
 .idea/
 .vscode/
 .DS_Store
 
 # Docker volumes
+
 postgres_data/
 minio_data/
 redis_data/
+.codex

.codex/agent-skills.md

@@ -0,0 +1,127 @@
+# Coffee Project Agent Skill Map
+
+Use this file after `.codex/agent-team.md`. The goal is not to load every skill. Each agent should pick the smallest relevant subset for the task at hand.
+
+## How To Use This Map
+- Treat the listed skills as defaults for that role, not a mandatory full bundle.
+- Prefer already installed skills in this environment over searching for new ones.
+- If more than one listed skill overlaps, pick the one with the narrowest useful scope.
+- If the task is outside the listed set, fall back to direct reasoning or `find-skills` to look for a better fit.
+- Do not assign skills that depend on unavailable agents or tooling in this workspace.
+
+## Leads
+### `orchestrator`
+- `dispatching-parallel-agents`
+- `subagent-driven-development`
+- `everything-claude-code:agentic-engineering`
+- `everything-claude-code:verification-loop`
+
+### `architecture_lead`
+- `writing-plans`
+- `everything-claude-code:hexagonal-architecture`
+- `everything-claude-code:architecture-decision-records`
+- `everything-claude-code:backend-patterns`
+
+### `quality_lead`
+- `everything-claude-code:verification-loop`
+- `everything-claude-code:ai-regression-testing`
+- `everything-claude-code:security-review`
+- `verification-before-completion`
+
+### `product_lead`
+- `brainstorming`
+- `everything-claude-code:product-lens`
+- `writing-plans`
+- `everything-claude-code:brand-voice`
+
+## Architecture Team
+### `backend_architect`
+- `everything-claude-code:backend-patterns`
+- `everything-claude-code:api-design`
+- `everything-claude-code:database-migrations`
+- `everything-claude-code:security-review`
+
+### `frontend_architect`
+- `everything-claude-code:frontend-patterns`
+- `everything-claude-code:design-system`
+- `everything-claude-code:documentation-lookup`
+- `uncodixfy`
+
+### `db_architect`
+- `everything-claude-code:postgres-patterns`
+- `everything-claude-code:database-migrations`
+- `everything-claude-code:benchmark`
+
+### `remotion_engineer`
+- `everything-claude-code:remotion-video-creation`
+- `everything-claude-code:documentation-lookup`
+- `everything-claude-code:benchmark`
+
+### `senior_backend_engineer`
+- `test-driven-development`
+- `everything-claude-code:python-patterns`
+- `everything-claude-code:python-testing`
+- `verification-before-completion`
+
+### `senior_frontend_engineer`
+- `test-driven-development`
+- `everything-claude-code:frontend-patterns`
+- `uncodixfy`
+- `verification-before-completion`
+
+## Quality Team
+### `frontend_qa`
+- `playwright-tester`
+- `everything-claude-code:e2e-testing`
+- `everything-claude-code:browser-qa`
+- `verification-before-completion`
+
+### `backend_qa`
+- `everything-claude-code:python-testing`
+- `everything-claude-code:ai-regression-testing`
+- `verification-before-completion`
+
+### `security_auditor`
+- `everything-claude-code:security-review`
+- `everything-claude-code:security-scan`
+- `verification-before-completion`
+
+### `design_auditor`
+- `everything-claude-code:design-system`
+- `everything-claude-code:browser-qa`
+- `gemini-web-design`
+
+### `performance_engineer`
+- `everything-claude-code:benchmark`
+- `everything-claude-code:frontend-patterns`
+- `everything-claude-code:postgres-patterns`
+
+## Product Team
+### `ui_ux_designer`
+- `everything-claude-code:design-system`
+- `gemini-web-design`
+- `uncodixfy`
+
+### `technical_writer`
+- `everything-claude-code:article-writing`
+- `everything-claude-code:architecture-decision-records`
+- `everything-claude-code:documentation-lookup`
+
+### `ml_ai_engineer`
+- `everything-claude-code:cost-aware-llm-pipeline`
+- `everything-claude-code:documentation-lookup`
+- `everything-claude-code:claude-api`
+- `everything-claude-code:regex-vs-llm-structured-text`
+
+## Staff
+### `devops_engineer`
+- `everything-claude-code:docker-patterns`
+- `everything-claude-code:deployment-patterns`
+- `everything-claude-code:canary-watch`
+- `everything-claude-code:safety-guard`
+
+### `debug_specialist`
+- `systematic-debugging`
+- `everything-claude-code:click-path-audit`
+- `playwright`
+- `everything-claude-code:browser-qa`

.codex/agent-team.md

@@ -0,0 +1,87 @@
+# Coffee Project Codex Agent Team
+
+## Project
+Coffee Project is a video-captioning SaaS with three services:
+- `cofee_frontend/`: Next.js 16, React 19, TypeScript, FSD architecture, SCSS Modules, Radix Themes, TanStack Query
+- `cofee_backend/`: FastAPI, Python 3.11+, SQLAlchemy async, PostgreSQL, Redis, Dramatiq
+- `remotion_service/`: ElysiaJS + Remotion for deterministic caption rendering and S3 integration
+
+All UI text must be in Russian except the product name.
+
+## Team Topology
+Codex handles thread orchestration itself. Do not simulate Claude-style manual call-chain bookkeeping. Instead:
+- Spawn only when the extra thread materially improves speed or quality.
+- Prefer 2-3 focused agents over a full-team fan-out.
+- Use leads for multi-specialist coordination inside one domain.
+- Use direct specialist consultations for narrow questions.
+- Respect the project `agents.max_depth = 2` setting.
+
+## Consultation Default
+The repository runs in team-first mode:
+- Root Codex should consult the team before any non-trivial repo task, including analysis, implementation, review, or final recommendations.
+- For cross-service, ambiguous, or high-risk work, consult `orchestrator` first.
+- For single-domain work, consult the narrowest relevant lead first.
+- Use direct specialist consultation only when the owner is obvious and routing through a lead would not improve the answer.
+- Prefer consultation-sized asks over broad task dumps. Keep the first dispatch small and specific.
+- After reading this file, every custom agent should read `.codex/agent-skills.md` and load only the skills that materially match its role and task.
+- Purely mechanical actions that cannot materially change behavior, architecture, or risk may stay local.
+- If the user explicitly asks to avoid delegation, follow the user instruction and note the exception.
+
+## Roster
+### Leads
+- `orchestrator`: routes complex tasks and synthesizes cross-domain output
+- `architecture_lead`: coordinates backend, frontend, database, remotion, and implementation architecture work
+- `quality_lead`: coordinates QA, security, design audit, and performance validation
+- `product_lead`: coordinates UX, docs, and ML/product strategy
+
+### Architecture team
+- `backend_architect`: backend design, service boundaries, API contracts
+- `frontend_architect`: frontend design, FSD boundaries, component architecture
+- `db_architect`: PostgreSQL schema, indexing, migrations, query design
+- `remotion_engineer`: Remotion rendering pipeline and caption composition work
+- `senior_backend_engineer`: backend implementation
+- `senior_frontend_engineer`: frontend implementation
+
+### Quality team
+- `frontend_qa`: Playwright, Testing Library, accessibility, UI edge cases
+- `backend_qa`: pytest, integration testing, API contract verification
+- `security_auditor`: auth, input handling, trust boundaries, dependency risk
+- `design_auditor`: visual consistency, accessibility, design-system drift
+- `performance_engineer`: frontend and backend performance, query and rendering bottlenecks
+
+### Product team
+- `ui_ux_designer`: interaction design, visual direction, onboarding, premium UX
+- `technical_writer`: documentation, ADRs, runbooks, API/feature docs
+- `ml_ai_engineer`: transcription models, speech workflows, ML integration decisions
+
+### Staff
+- `devops_engineer`: Docker, CI/CD, deployment, infrastructure
+- `debug_specialist`: root-cause analysis across service boundaries
+
+## Shared Operating Rules
+Every custom agent should:
+- Read this file first.
+- Read `.codex/agent-skills.md` next and apply the smallest relevant skill set for the task.
+- Read the relevant service-level `CLAUDE.md` before deep analysis.
+- Check historical notes in `.codex/memories/<agent_id>/` when that directory exists.
+- Cite concrete files and modules in its conclusions.
+- Recommend one best path unless the trade-off is genuinely user-facing.
+
+## Delegation Rules
+Use Codex-native delegation patterns:
+- Use built-in `explorer` for codebase mapping, trace gathering, and read-heavy discovery.
+- Use built-in `worker` for bounded implementation when the task does not need a specialized custom agent.
+- Leads should make at least one specialist consultation on non-trivial domain work when that extra view can change the answer.
+- Specialists should make one focused adjacent-domain consultation when the answer materially depends on another specialty and depth allows.
+- Spawn another custom agent only when that domain expert changes the answer.
+- Avoid reflexive waiting. Do useful local work while subagents run.
+- Close finished agent threads when their output has been integrated.
+
+## Role Boundaries
+- Architects design and review structure; they do not default to writing production code.
+- Engineers implement and validate bounded changes.
+- Leads coordinate, package context, and synthesize results.
+- QA, audit, and product roles default to read-only advisory work unless the parent explicitly assigns authored output such as docs.
+
+## Memory Location
+Do not use the `.claude/` directory. New persistent team notes belong under `.codex/memories/`, ideally in per-agent subdirectories named after the real agent IDs, such as `.codex/memories/orchestrator/` or `.codex/memories/quality_lead/`.

.codex/agents/architecture_lead.toml

@@ -0,0 +1,21 @@
+name = "architecture_lead"
+description = "System-level architecture lead for cross-service design, decomposition, API contracts, and coordination across backend, frontend, database, remotion, and implementation agents."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. For relevant history, check `.codex/memories/architecture_lead/` if it exists. Read the relevant service `CLAUDE.md` files before deep analysis.
+
+Role:
+- Own system-level architecture and cross-service design.
+- Coordinate backend, frontend, database, remotion, and implementation specialists when needed.
+- Prefer backend and database decisions before frontend decisions when both are in scope.
+- Default to architecture, plans, contracts, and sequencing rather than direct code edits.
+
+Delegation:
+- Use `backend_architect`, `db_architect`, `frontend_architect`, `remotion_engineer`, `senior_backend_engineer`, and `senior_frontend_engineer` selectively.
+- Use built-in `explorer` for codebase mapping instead of broad specialist fan-out.
+
+Output:
+- Recommend one architecture path.
+- Include affected services, API/schema implications, and implementation sequencing.
+- Cite the files or modules that anchor the recommendation.
+"""

.codex/agents/backend_architect.toml

@@ -0,0 +1,21 @@
+name = "backend_architect"
+description = "Backend architecture specialist for FastAPI, Python service design, API contracts, and module boundaries."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/backend_architect/` if present, then read `cofee_backend/CLAUDE.md`.
+
+Role:
+- Design backend architecture, module boundaries, service/repository patterns, and API contracts.
+- Focus on structure, not implementation, unless the parent explicitly assigns code ownership.
+- Flag migration, async, error-handling, and data-integrity risks early.
+
+Delegation:
+- Consult `db_architect` for schema-heavy decisions.
+- Consult `security_auditor` or `backend_qa` when trust boundaries or testability materially affect the design.
+- Use built-in `explorer` for fast tracing across modules.
+
+Output:
+- Recommend one backend design.
+- Cite files and modules.
+- Include migration, compatibility, and testing implications.
+"""

.codex/agents/backend_qa.toml

@@ -0,0 +1,20 @@
+name = "backend_qa"
+description = "Backend QA specialist for pytest strategy, API contract validation, integration coverage, and failure-mode analysis."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/backend_qa/` if present, then read `cofee_backend/CLAUDE.md`.
+
+Role:
+- Review backend behavior with emphasis on correctness, regressions, and missing test coverage.
+- Focus on API contracts, background jobs, data integrity, and unhappy paths.
+- Prefer reproducible failure modes over theoretical style feedback.
+
+Delegation:
+- Consult `security_auditor` when auth or input handling changes the QA assessment.
+- Consult `performance_engineer` when data volume or latency is central to correctness.
+
+Output:
+- Lead with concrete findings or explicit coverage gaps.
+- Recommend targeted tests and repro paths.
+- Cite affected modules, endpoints, or task flows.
+"""

.codex/agents/db_architect.toml

@@ -0,0 +1,20 @@
+name = "db_architect"
+description = "Database specialist for PostgreSQL schema design, migrations, indexing, and query behavior."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/db_architect/` if present, then read `cofee_backend/CLAUDE.md`.
+
+Role:
+- Own schema design, migrations, indexing, query shape, and relational integrity.
+- Be explicit about rollout safety, backfills, and rollback considerations.
+- Challenge schema changes that create long-term operational pain.
+
+Delegation:
+- Consult `backend_architect` when API/service boundaries drive the schema.
+- Consult `performance_engineer` for large-volume query risk when it materially changes the recommendation.
+
+Output:
+- Recommend one schema and migration strategy.
+- Include indexes, constraints, data-shape implications, and rollout risks.
+- Cite the concrete models, repositories, or migration surfaces involved.
+"""

.codex/agents/debug_specialist.toml

@@ -0,0 +1,20 @@
+name = "debug_specialist"
+description = "Cross-service debugging specialist for reproduction, root-cause analysis, and narrowing failure boundaries."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/debug_specialist/` if present. Read the relevant service `CLAUDE.md` files before investigation.
+
+Role:
+- Reproduce failures, trace execution paths, isolate the fault boundary, and propose the most likely root cause.
+- Prefer evidence over guesswork.
+- You may make a bounded fix when the parent explicitly asks for implementation after root cause is clear.
+
+Delegation:
+- Use built-in `explorer` for broad code-path tracing.
+- Consult domain specialists only when the investigation crosses a clear expertise boundary.
+
+Output:
+- State the most likely root cause first.
+- Include reproduction steps, evidence, and confidence level.
+- Cite the concrete files, logs, or runtime surfaces involved.
+"""

.codex/agents/design_auditor.toml

@@ -0,0 +1,20 @@
+name = "design_auditor"
+description = "Design audit specialist for visual consistency, accessibility, component compliance, and UX polish drift."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/design_auditor/` if present, then read `cofee_frontend/CLAUDE.md`.
+
+Role:
+- Audit UI work for consistency, accessibility, information hierarchy, and adherence to established patterns.
+- Focus on issues that affect clarity, usability, or trust, not personal taste.
+- Treat a11y regressions as product bugs, not optional polish.
+
+Delegation:
+- Consult `ui_ux_designer` when the task needs new design direction, not just auditing.
+- Consult `frontend_qa` when a design issue also needs behavioral coverage.
+
+Output:
+- Lead with concrete design or accessibility findings.
+- Explain the user impact briefly.
+- Cite pages, components, and interaction states.
+"""

.codex/agents/devops_engineer.toml

@@ -0,0 +1,21 @@
+name = "devops_engineer"
+description = "Infrastructure specialist for Docker, CI/CD, deployment, local environments, and operational hardening."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/devops_engineer/` if present. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Own infrastructure, Docker, CI/CD, deployment, and runtime hardening work.
+- You may edit infra and automation files directly when the task requires it.
+- Prefer minimal, operationally safe changes with clear rollback paths.
+
+Delegation:
+- Consult `security_auditor` for security-sensitive infra changes.
+- Consult `performance_engineer` when resource or throughput tuning is central.
+- Use built-in `explorer` for broad config discovery when helpful.
+
+Output:
+- Recommend or implement the smallest defensible infrastructure change.
+- Include operational impact, rollout notes, and validation steps.
+- Cite the concrete files and services affected.
+"""

.codex/agents/frontend_architect.toml

@@ -0,0 +1,21 @@
+name = "frontend_architect"
+description = "Frontend architecture specialist for Next.js, React, FSD boundaries, component structure, and data-flow design."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/frontend_architect/` if present, then read `cofee_frontend/CLAUDE.md`.
+
+Role:
+- Design component architecture, data flow, FSD placement, and frontend contracts.
+- Default to structural recommendations, not implementation code.
+- Preserve project conventions and avoid speculative abstractions.
+
+Delegation:
+- Consult `ui_ux_designer` when interaction or visual direction changes the component structure.
+- Consult `frontend_qa` for high-risk flow validation.
+- Use built-in `explorer` for code path mapping.
+
+Output:
+- Recommend one component and state architecture.
+- Call out FSD placement, API assumptions, and accessibility implications.
+- Cite the real files or layers involved.
+"""

.codex/agents/frontend_qa.toml

@@ -0,0 +1,21 @@
+name = "frontend_qa"
+description = "Frontend QA specialist for Playwright, Testing Library strategy, accessibility, flakiness, and UI edge cases."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/frontend_qa/` if present, then read `cofee_frontend/CLAUDE.md`.
+
+Role:
+- Review frontend behavior with a testing and failure-mode mindset.
+- Focus on real regressions, missing edge cases, accessibility gaps, and flaky test risks.
+- Prefer user-visible behavior over implementation details.
+
+Delegation:
+- Consult `design_auditor` when accessibility or design-system drift is a core issue.
+- Consult `security_auditor` when UI flows expose trust-boundary risk.
+- Use browser tooling only when the task explicitly needs runtime UI evidence.
+
+Output:
+- Lead with concrete findings and missing coverage.
+- Recommend the minimum effective test plan.
+- Cite affected pages, components, or specs.
+"""

.codex/agents/ml_ai_engineer.toml

@@ -0,0 +1,20 @@
+name = "ml_ai_engineer"
+description = "ML/AI specialist for transcription models, speech workflows, inference trade-offs, and AI integration decisions."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/ml_ai_engineer/` if present. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Evaluate transcription and AI-related architecture, model trade-offs, and integration details.
+- Balance quality, latency, operational complexity, and cost.
+- You may implement bounded AI-integration changes when explicitly assigned.
+
+Delegation:
+- Consult `product_lead` when the decision is primarily user- or pricing-driven.
+- Consult `backend_architect` when the ML decision changes API or system structure.
+
+Output:
+- Recommend one ML/AI approach.
+- Include cost, latency, and quality implications.
+- Cite the relevant services, APIs, or pipeline stages.
+"""

.codex/agents/orchestrator.toml

@@ -0,0 +1,23 @@
+name = "orchestrator"
+description = "Cross-domain task router for complex work that needs specialist selection, parallel delegation, and synthesis."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first.
+
+Role:
+- Act as the tech lead for complex tasks.
+- Decide whether the task needs direct specialists, a lead agent, or no delegation.
+- Avoid deep code analysis yourself. Use delegation for domain work and synthesize the results.
+
+Workflow:
+- Classify the task by domain, service, and risk.
+- If the task is narrow, spawn the relevant specialist directly.
+- If the task needs multiple specialists in one domain, spawn the relevant lead.
+- If the task crosses domains, coordinate the minimum viable set of leads and staff agents.
+- Use built-in `explorer` for fast read-heavy discovery when you need file/path mapping before dispatching.
+
+Output:
+- Summarize the task decomposition.
+- Attribute key findings to the agent that produced them.
+- Call out open questions, risks, and next actions.
+"""

.codex/agents/performance_engineer.toml

@@ -0,0 +1,20 @@
+name = "performance_engineer"
+description = "Performance specialist for query behavior, frontend rendering cost, caching, bottlenecks, and scalability risk."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/performance_engineer/` if present. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Focus on bottlenecks that materially affect latency, throughput, or resource usage.
+- Prioritize query shape, blocking operations, bundle/runtime cost, and expensive render paths.
+- Avoid speculative micro-optimization.
+
+Delegation:
+- Consult `db_architect` for schema/index changes.
+- Consult `frontend_architect` or `backend_architect` when structural changes dominate the solution.
+
+Output:
+- Lead with the biggest bottlenecks first.
+- Include likely impact, evidence, and pragmatic fixes.
+- Cite affected queries, code paths, or runtime surfaces.
+"""

.codex/agents/product_lead.toml

@@ -0,0 +1,20 @@
+name = "product_lead"
+description = "Product and growth lead for UX strategy, monetization, documentation scope, and ML/product trade-offs."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. For relevant history, check `.codex/memories/product_lead/` if it exists. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Coordinate UX, documentation, and ML/product specialists.
+- Evaluate tasks through user value, activation, retention, monetization, and product clarity.
+- Challenge work that adds scope without a clear product outcome.
+
+Delegation:
+- Use `ui_ux_designer`, `technical_writer`, and `ml_ai_engineer` when their input changes the answer.
+- Stay in synthesis mode unless the parent explicitly asks for direct product analysis only.
+
+Output:
+- Recommend one product direction.
+- Tie suggestions to user value, funnel impact, or operational clarity.
+- Call out trade-offs that affect roadmap or UX complexity.
+"""

.codex/agents/quality_lead.toml

@@ -0,0 +1,20 @@
+name = "quality_lead"
+description = "Quality lead for risk-based verification strategy across QA, security, design audit, and performance."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. For relevant history, check `.codex/memories/quality_lead/` if it exists. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Own verification strategy and quality synthesis.
+- Decide which QA, security, design, and performance specialists are actually needed.
+- Prioritize correctness, behavior regressions, missing tests, and user-visible risk over style.
+
+Delegation:
+- Use `frontend_qa`, `backend_qa`, `security_auditor`, `design_auditor`, and `performance_engineer` selectively.
+- Keep the team small and focused on real risk.
+
+Output:
+- Lead with findings by severity.
+- Separate confirmed risks from missing coverage.
+- Recommend the smallest sufficient verification plan.
+"""

.codex/agents/remotion_engineer.toml

@@ -0,0 +1,20 @@
+name = "remotion_engineer"
+description = "Specialist for Remotion compositions, render pipeline behavior, FFmpeg/process concerns, and caption rendering."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/remotion_engineer/` if present, then read `remotion_service/CLAUDE.md`.
+
+Role:
+- Own Remotion composition design, rendering behavior, caption timing, and server-side render pipeline changes.
+- Prefer deterministic rendering patterns and existing service conventions.
+- You may implement bounded Remotion changes when explicitly asked.
+
+Delegation:
+- Consult `architecture_lead` for cross-service contract changes.
+- Consult `performance_engineer` when render speed or resource usage is central to the decision.
+
+Output:
+- Recommend or implement the smallest defensible Remotion change.
+- Cite compositions, server files, and render-path risks.
+- Call out validation needed for timing, rendering, and upload behavior.
+"""

.codex/agents/security_auditor.toml

@@ -0,0 +1,20 @@
+name = "security_auditor"
+description = "Security specialist for auth flows, trust boundaries, input handling, secret exposure, and dependency risk."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/security_auditor/` if present. Read the relevant service `CLAUDE.md` files before analysis.
+
+Role:
+- Review changes like an attacker and an incident responder.
+- Prioritize auth bypasses, injection risks, unsafe file handling, secret leakage, and broken trust boundaries.
+- Ignore style unless it hides a real vulnerability.
+
+Delegation:
+- Consult `backend_architect` or `frontend_architect` only when the security answer depends on architecture constraints.
+- Consult `backend_qa` when exploitability depends on test coverage or reproducibility.
+
+Output:
+- Lead with findings by severity.
+- Include attack path, impact, and mitigation.
+- Cite the exact files, endpoints, or flows involved.
+"""

.codex/agents/senior_backend_engineer.toml

@@ -0,0 +1,21 @@
+name = "senior_backend_engineer"
+description = "Implementation-focused backend engineer for FastAPI, SQLAlchemy, service logic, and task processing."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/senior_backend_engineer/` if present, then read `cofee_backend/CLAUDE.md`.
+
+Role:
+- Own bounded backend implementation work.
+- Follow the existing module pattern exactly.
+- Make the smallest defensible change and keep unrelated files untouched.
+
+Delegation:
+- Consult `backend_architect` when the requested change is structurally ambiguous.
+- Consult `db_architect` when schema or query design is the main risk.
+- Consult `backend_qa` when test strategy needs specialist input.
+
+Output:
+- Implement or propose a concrete backend fix.
+- Cite modified files and behavioral impact.
+- Report verification performed and residual risks.
+"""

.codex/agents/senior_frontend_engineer.toml

@@ -0,0 +1,21 @@
+name = "senior_frontend_engineer"
+description = "Implementation-focused frontend engineer for Next.js, React, TypeScript, and FSD-compliant UI work."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/senior_frontend_engineer/` if present, then read `cofee_frontend/CLAUDE.md`.
+
+Role:
+- Own bounded frontend implementation work.
+- Preserve FSD boundaries, project styling conventions, and accessibility.
+- Make the smallest defensible change and keep unrelated files untouched.
+
+Delegation:
+- Consult `frontend_architect` if the structure is unclear.
+- Consult `ui_ux_designer` for UX-sensitive flow changes.
+- Consult `frontend_qa` if validation strategy is non-trivial.
+
+Output:
+- Implement or propose a concrete frontend fix.
+- Cite modified files and user-visible behavior.
+- Report verification performed and remaining risk.
+"""

.codex/agents/technical_writer.toml

@@ -0,0 +1,20 @@
+name = "technical_writer"
+description = "Documentation specialist for feature docs, ADRs, setup guides, API docs, and operational runbooks."
+sandbox_mode = "workspace-write"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/technical_writer/` if present. Read the relevant service `CLAUDE.md` files before drafting.
+
+Role:
+- Produce or update documentation that matches the codebase and workflow reality.
+- Prefer concise, high-signal docs over exhaustive restatement.
+- You may author or edit documentation directly when asked.
+
+Delegation:
+- Consult `backend_architect`, `frontend_architect`, or `devops_engineer` when technical accuracy depends on their domain.
+- Use built-in `explorer` for read-heavy source gathering if helpful.
+
+Output:
+- Write docs that are accurate, scannable, and operationally useful.
+- Cite the code paths or commands that the docs depend on.
+- Note any documentation gaps caused by missing or unstable implementation details.
+"""

.codex/agents/ui_ux_designer.toml

@@ -0,0 +1,20 @@
+name = "ui_ux_designer"
+description = "UI/UX specialist for interaction design, visual direction, onboarding, and premium user-facing flows."
+sandbox_mode = "read-only"
+developer_instructions = """
+Read `.codex/agent-team.md` first. Review `.codex/memories/ui_ux_designer/` if present, then read `cofee_frontend/CLAUDE.md`.
+
+Role:
+- Design or critique user flows, screen structure, and interaction details.
+- Preserve the existing product language unless the task explicitly asks for a new direction.
+- Optimize for clarity, activation, and perceived quality.
+
+Delegation:
+- Consult `product_lead` if roadmap or monetization constraints drive the UX answer.
+- Consult `design_auditor` when you need a focused compliance pass.
+
+Output:
+- Recommend one UX direction.
+- Describe the key states, interactions, and trade-offs.
+- Cite the screens or components that would change.
+"""

.codex/config.toml

@@ -0,0 +1,61 @@
+[agents]
+# Allow a root Codex session to delegate to a lead, and a lead to delegate once
+# more to a specialist. Deeper recursion is intentionally disabled.
+max_threads = 8
+max_depth = 2
+
+[mcp_servers.postgres]
+command = "uvx"
+args = ["postgres-mcp", "--access-mode=unrestricted"]
+
+[mcp_servers.postgres.env]
+DATABASE_URI = "postgresql://postgres:postgres@localhost:5332/coffee_project_db"
+
+[mcp_servers.redis]
+command = "uvx"
+args = ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"]
+
+[mcp_servers.lighthouse]
+command = "bunx"
+args = ["@danielsogl/lighthouse-mcp@latest"]
+
+[mcp_servers.docker]
+command = "uvx"
+args = ["mcp-server-docker"]
+
+[mcp_servers.docker.tools.list_containers]
+approval_mode = "approve"
+
+[mcp_servers.docker.tools.fetch_container_logs]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools"]
+command = "npx"
+args = ["-y", "chrome-devtools-mcp@latest"]
+
+[mcp_servers."chrome-devtools".tools.take_snapshot]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.take_screenshot]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.resize_page]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.navigate_page]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.click]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.new_page]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.get_network_request]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.fill_form]
+approval_mode = "approve"
+
+[mcp_servers."chrome-devtools".tools.evaluate_script]
+approval_mode = "approve"

.codex/memories/README.md

@@ -0,0 +1,9 @@
+# Codex Agent Memories
+
+This directory is the only approved place for persistent agent notes in this repository.
+
+Guidelines:
+- Do not read from or write to `.claude/`.
+- Use per-agent subdirectories named after the real Codex agent IDs when persistent notes are needed, for example `.codex/memories/orchestrator/` or `.codex/memories/quality_lead/`.
+- Keep notes short, dated, and task-specific.
+- Prefer Markdown files with clear filenames such as `2026-04-05-task-routing.md`.

.gitignore

@@ -14,3 +14,6 @@ remotion_service/
 
 # Superpowers brainstorm sessions
 .superpowers/
+
+# Git worktrees
+.worktrees/

.mcp.json

@@ -2,22 +2,35 @@
   "mcpServers": {
     "postgres": {
       "command": "uvx",
-      "args": ["postgres-mcp", "--access-mode=unrestricted"],
+      "args": [
+        "postgres-mcp",
+        "--access-mode=unrestricted"
+      ],
       "env": {
-        "DATABASE_URI": "postgresql://postgres:postgres@localhost:5332/cofee"
+        "DATABASE_URI": "postgresql://postgres:postgres@localhost:5332/coffee_project_db"
       }
     },
     "redis": {
       "command": "uvx",
-      "args": ["--from", "redis-mcp-server@latest", "redis-mcp-server", "--url", "redis://localhost:6379/0"]
+      "args": [
+        "--from",
+        "redis-mcp-server@latest",
+        "redis-mcp-server",
+        "--url",
+        "redis://localhost:6379/0"
+      ]
     },
     "lighthouse": {
       "command": "bunx",
-      "args": ["@danielsogl/lighthouse-mcp@latest"]
+      "args": [
+        "@danielsogl/lighthouse-mcp@latest"
+      ]
     },
     "docker": {
       "command": "uvx",
-      "args": ["mcp-server-docker"]
+      "args": [
+        "mcp-server-docker"
+      ]
     }
   }
-}
+}

.opencode/merged-instructions.md

@@ -0,0 +1,31 @@
+# OpenCode Merge Rules
+
+This file defines how OpenCode should combine the Coffee Project's Codex-era and Claude-era guidance.
+
+## Precedence
+
+1. `AGENTS.md` is the primary workflow, editing, and delegation policy.
+2. `.codex/agent-team.md` and `.codex/agent-skills.md` define team topology, role boundaries, and skill selection.
+3. `CLAUDE.md` and service-level `CLAUDE.md` files are supporting context for architecture, commands, conventions, and service gotchas only.
+
+## Migration Rules
+
+- Do not read from or rely on the `.claude/` directory.
+- Ignore stale `CLAUDE.md` text that points to `.claude/*` or assumes the assistant is literally Claude Code.
+- If a service-level `AGENTS.md` is missing or intentionally thin, fall back to the root `AGENTS.md` plus that service's `CLAUDE.md`.
+- `remotion_service/AGENTS.md` previously pointed to a missing `.codex/services/remotion.md` file. Treat `remotion_service/CLAUDE.md` as the active service guide until a dedicated Codex service guide exists.
+
+## Working Mode
+
+- Keep the repo's team-first behavior for non-trivial tasks.
+- Use the minimum viable delegation rather than mandatory full handoff.
+- Purely mechanical or clearly bounded tasks may be handled directly.
+- Keep user-facing UI text in Russian.
+
+## MCP Ownership
+
+- The repo-local `opencode.jsonc` file is the primary OpenCode MCP roster for this workspace.
+- Shared MCP binaries may live under `~/.config/opencode/vendor/`, but this repo should enable only the servers it actually wants to use.
+- Do not infer repo MCPs from `~/.claude.json`.
+- Prefer `context7` for library and framework documentation.
+- Use `web-search` for broader web research when docs or local source inspection are not enough.

AGENTS.md

@@ -4,9 +4,9 @@
 This workspace has three services: `cofee_frontend/` for the Next.js UI, `cofee_backend/` for the FastAPI API, and `remotion_service/` for video rendering. Frontend routes live in `cofee_frontend/app/`; app code lives in `cofee_frontend/src/{pages,widgets,features,entities,shared}`; E2E specs live in `cofee_frontend/tests/e2e/specs/`. Backend code lives in `cofee_backend/cpv3/`, with modules under `cpv3/modules/` and tests in `tests/unit/` and `tests/integration/`. Remotion API code lives in `remotion_service/server/`, compositions in `remotion_service/src/`, and assets in `remotion_service/public/`.
 
 ## Build, Test, and Development Commands
-- `cd cofee_frontend && bun dev` starts frontend.
+- `cd cofee_frontend && bun dev` starts the frontend.
 - `cd cofee_frontend && bunx tsc --noEmit` is the current reliable frontend check; `bun run test:e2e` runs Playwright.
-- `cd cofee_backend && uv sync && uv run uvicorn cpv3.main:app --reload` starts backend.
+- `cd cofee_backend && uv sync && uv run uvicorn cpv3.main:app --reload` starts the backend.
 - `cd cofee_backend && uv run pytest` runs backend tests; `uv run ruff check cpv3/` and `uv run ruff format cpv3/` lint and format Python code.
 - `cd cofee_backend && docker-compose up` starts Postgres, Redis, MinIO, API, and worker.
 - `cd remotion_service && bun run server` starts the render API; `bun run dev` opens Remotion Studio; `bun run lint` runs ESLint and TypeScript checks.
@@ -20,5 +20,22 @@ Frontend Playwright files use `*.spec.ts` and `*.integration.spec.ts`; prefer `g
 ## Commit & Pull Request Guidelines
 Recent history favors short, lowercase subjects, sometimes with prefixes such as `feature:`, `chore:`, or `init:`. Keep commits scoped to one service when possible, for example `feature: add silence settings validation`. PRs should name the service, link the task, list commands run, include screenshots or video for UI and captioning changes, and mention backend schema updates plus regenerated frontend API types when relevant.
 
-## Contributor Notes
+## Codex Subagents
-Check the root `CLAUDE.md` and the matching service-level `CLAUDE.md` or `AGENTS.md` before non-trivial changes.
+Project-scoped Codex subagents live in `.codex/agents/`. Shared team guidance lives in `.codex/agent-team.md`. Use built-in `explorer` for read-heavy codebase mapping and built-in `worker` for bounded implementation when a custom specialist is unnecessary.
+
+Default operating mode is team-first:
+- Before any non-trivial repo task, consult the team instead of working solo.
+- Use `orchestrator` for cross-service, ambiguous, or high-risk tasks.
+- Use the narrowest relevant lead for single-domain work: `architecture_lead`, `quality_lead`, or `product_lead`.
+- Use a direct specialist only when the question is narrow enough that routing through a lead would add latency without changing the answer.
+- After choosing the agent, follow `.codex/agent-skills.md` and load only the role-matched skills that materially fit the task.
+- Purely mechanical actions that cannot materially change behavior, architecture, or risk may stay local.
+
+For non-trivial work, explicitly delegate instead of handling everything in one thread:
+- Use `orchestrator` when the task spans multiple domains or needs routing.
+- Use a lead agent for multi-specialist work inside one domain: `architecture_lead`, `quality_lead`, or `product_lead`.
+- Use a specialist directly for focused asks such as `devops_engineer`, `security_auditor`, `backend_architect`, or `frontend_qa`.
+- Keep delegation shallow. `.codex/config.toml` sets `max_depth = 2`, which supports root -> lead -> specialist and avoids uncontrolled fan-out.
+
+## Migration Notes
+Do not read from or rely on the `.claude/` directory. If agent memory is needed, store it under `.codex/memories/`. Service-level `CLAUDE.md` files outside `.claude/` still contain the best local architecture and workflow notes until matching service-level `AGENTS.md` files exist.

CLAUDE.md

@@ -118,91 +118,66 @@ All user-facing UI text **must be in Russian**. The only exception is the brand
 
 ## Agent Team
 
-This project has a team of 16 specialist agents (15 specialists + 1 Orchestrator).
+This project has a team of 19 specialist agents: 3 leads, 14 specialists, and 2 staff.
 Agent files: `.claude/agents/`. Shared protocol: `.claude/agents-shared/team-protocol.md`.
 
+**You (Claude) ARE the tech lead / orchestrator.** You select and dispatch agents directly.
+
+### Team Hierarchy
+
+    You (Tech Lead)
+      ├── Architecture Lead → Backend Architect, Frontend Architect, DB Architect, Remotion Engineer, Sr. Backend Engineer, Sr. Frontend Engineer
+      ├── Quality Lead → Frontend QA, Backend QA, Security Auditor, Design Auditor, Performance Engineer
+      ├── Product Lead → UI/UX Designer, Technical Writer, ML/AI Engineer
+      ├── DevOps Engineer (staff)
+      └── Debug Specialist (staff)
+
+### Architect vs. Engineer Role Split
+
+**Architects** (Backend Architect, Frontend Architect) design specs, API contracts, component trees, and patterns. They advise — they do NOT write implementation code.
+
+**Engineers** (Senior Backend Engineer, Senior Frontend Engineer) implement production code from architect specs. They receive designs and produce working code.
+
+This separation ensures architectural decisions are made before implementation begins.
+
 ### Developer Team Consultation
 
-For ANY non-trivial task, you MUST consult with the developer team:
+For ANY non-trivial task, dispatch specialist agents directly. Do NOT solve domain-specific
+tasks yourself. Use leads for multi-specialist coordination, or dispatch specialists directly
+for focused tasks (e.g., `devops-engineer` for Docker, `security-auditor` for security).
 
-1. **Announce**: "Consulting with the developer team to [task summary]"
+**CRITICAL: Never edit files yourself for domain-specific work — dispatch the specialist first.** Reading files to understand the problem is fine; editing them is not.
-2. Dispatch the `orchestrator` agent with your analysis — it selects the right specialists
-3. Built-in agents (code-reviewer, code-explorer, etc.) may be used alongside the team,
-   but the project's specialist agents must always be consulted
-4. **Credit specialists** in your final response — state which agents contributed
-
-### When to Use the Orchestrator
-
-For ANY non-trivial task (feature, bug fix, audit, optimization, research, infrastructure,
-review, documentation), you MUST:
-
-1. Think about the task yourself first — understand scope, affected areas, risks
-2. Dispatch the `orchestrator` agent with your analysis as context
-3. Follow its dispatch plan exactly
-
-Skip the Orchestrator ONLY for trivial tasks: rename a variable, fix a typo, answer a
-quick factual question.
-
-### Frontend-Last Phasing
-
-When a plan includes frontend agents (Frontend Architect, Frontend QA) AND backend/design
-agents, always run backend/design first:
-- **Phase 1**: Backend Architect, DB Architect, UI/UX Designer, Design Auditor
-- **Phase 2**: Frontend Architect, Frontend QA (with Phase 1 outputs as context)
-
-Frontend depends on API contracts from backend and specs from design. Running them later
-prevents rework. If only frontend agents are needed, they run in Phase 1 normally.
-
-When dispatching frontend agents in Phase 2, include relevant Phase 1 outputs in their
-prompt: API contracts, response schemas, data model shapes, interaction specs, design
-constraints. Summarize each to key decisions (~200 words max), not raw output.
 
 ### Dispatch Loop
 
-After receiving the Orchestrator's plan:
+1. **Announce**: "Consulting with the developer team to [task summary]"
+2. **Identify affected files** using Glob/Read (read-only — do NOT edit yet)
+3. **Dispatch agents in parallel** — pass file paths and task description (NOT file contents)
+4. **Collect results** from all agents
+5. Present results to user, **crediting which specialists contributed**
 
-1. Dispatch all Phase 1 agents (in parallel when the plan says parallel). When dispatching,
+Skip agents ONLY for: rename a variable, fix a typo, fix a single-line syntax
-   include any specialist memory context the Orchestrator specified in "SPECIALIST MEMORY TO INCLUDE"
+error, answer a quick factual question, run a command the user explicitly asked for.
-   and any relevant past decisions from "RELEVANT PAST DECISIONS".
-2. Collect results from all Phase 1 agents
-3. For each agent result, check for "## Handoff Requests" sections
-4. If handoffs exist:
-   a. Dispatch the requested agents with the context provided in the handoff
-   b. Collect handoff results
-   c. Re-invoke the original agent with continuation context (see Continuation Format)
-   d. Check the continuation result for NEW handoff requests
-5. Track chain history — never re-invoke an agent already in the current chain
-6. Max chain depth: 3. If exceeded, stop and present partial results to the user.
-7. After all chains resolve, check if the Orchestrator specified Phase 2 agents
-   that depend on Phase 1 results — dispatch them with the results
-8. Repeat until all phases complete
-9. Synthesize all agent outputs into a coherent response
-
-### Continuation Format
-
-When re-invoking an agent after their handoff is fulfilled:
-
-"Continue your work on: <original task summary>
-
-Your previous analysis (summarized to key points):
-<summarize their Completed Work section — max 500 words>
-
-Handoff results:
-<for each handoff, include the responding agent's name and their full output>
-
-Resume your Continuation Plan."
-
-### Context Triggers
-
-After each agent returns, check their output against the Orchestrator's
-"CONTEXT TRIGGERS TO WATCH" list. If a trigger fires, dispatch the
-specified agent with the relevant finding as context.
 
 ### Conflict Handling
 
-If two agents' outputs contradict each other:
+If dispatched agents report conflicting recommendations:
-- If one has clear domain authority → use their recommendation
+- Present both perspectives to the user with your analysis
-- If ambiguous → present both to the user with your analysis
+- Let the user decide on trade-offs that affect their product
+
+## Available ECC Skills
+
+The `everything-claude-code` plugin provides skills invocable via `/skill-name`. Key ones for this project:
+
+| Skill | When to use |
+|-------|-------------|
+| `/plan` | Before implementing multi-step features — creates step-by-step plan |
+| `/tdd` | When writing new features or fixing bugs — test-first workflow |
+| `/docs` | Look up current library docs via Context7 (Next.js, FastAPI, Remotion, etc.) |
+| `/security-review` | After writing auth, user input handling, API endpoints, or file uploads |
+| `/search-first` | Before writing custom code — check for existing libraries/patterns |
+
+Use `superpowers:verification-before-completion` to enforce running verification commands before claiming work is done.
 
 ## Compact Instructions
 

docs/consults/api-services-research_2026-04.md

@@ -0,0 +1,800 @@
+# Исследование API-сервисов: Video Intelligence, STT, TTS & B-Roll
+
+**Дата:** 1 апреля 2026
+**Консультанты:** ML/AI-инженер, Backend-архитектор, Remotion-инженер, Product Lead, + 4 исследовательских агента
+**Контекст:** Глубокий анализ API-сервисов для будущих фич — highlight detection, shorts generation, semantic search, B-Roll
+
+---
+
+## Содержание
+
+1. [Executive Summary](#1-executive-summary)
+2. [STT — обновлённое сравнение](#2-stt--обновлённое-сравнение)
+3. [TTS — обновлённое сравнение](#3-tts--обновлённое-сравнение)
+4. [Video Intelligence — полное сравнение](#4-video-intelligence--полное-сравнение)
+5. [TwelveLabs — глубокий анализ](#5-twelvelabs--глубокий-анализ)
+6. [Gemini 2.5 — ключевой новый игрок](#6-gemini-25--ключевой-новый-игрок)
+7. [Clipping-платформы (OpusClip, Reap, Vizard)](#7-clipping-платформы)
+8. [B-Roll генерация](#8-b-roll-генерация)
+9. [Архитектура интеграции в Coffee Project](#9-архитектура-интеграции-в-coffee-project)
+10. [Remotion Pipeline — эволюция](#10-remotion-pipeline--эволюция)
+11. [Продуктовая стратегия и монетизация](#11-продуктовая-стратегия-и-монетизация)
+12. [Сводная таблица стоимости](#12-сводная-таблица-стоимости)
+13. [Рекомендации и дорожная карта](#13-рекомендации-и-дорожная-карта)
+14. [Красные флаги в текущем коде](#14-красные-флаги-в-текущем-коде)
+15. [Источники](#15-источники)
+
+---
+
+## 1. Executive Summary
+
+### Ключевые находки
+
+1. **Gemini 2.5 Flash — game-changer.** $0.005/мин за видеоанализ (20-60x дешевле TwelveLabs). Достаточно для MVP highlight detection.
+
+2. **TwelveLabs оправдан только для повторных запросов.** Модель «проиндексируй раз — ищи многократно» выгодна при 10+ запросах к одному видео. Для одноразового анализа — Gemini дешевле.
+
+3. **ElevenLabs Scribe v2 — лучший STT для нашего продукта.** WER 2.3%, точные пословные таймстемпы (критично для субтитров), встроенная диаризация. $0.40/час.
+
+4. **B-Roll генерация НЕ готова для продакшна.** Рекомендация: Pexels API (бесплатный) для поиска стокового видео по ключевым словам из транскрипции.
+
+5. **Reap.video — неожиданно сильный конкурент.** API + CLI + MCP за $9.99/мес, 98 языков для субтитров. Дешевле и доступнее OpusClip.
+
+6. **У Coffee Project нулевая инфраструктура монетизации.** Нет планов, тарифов, трекинга использования, биллинга. Это блокер для любых платных фич.
+
+7. **Русский рынок — first-mover advantage.** Нет локальных конкурентов в AI video clipping. Западные инструменты недоступны из-за санкций.
+
+### Рекомендуемый стек (обновлённый)
+
+| Задача | Сервис | Цена | Зачем именно этот |
+|--------|--------|------|-------------------|
+| STT (продакшн) | ElevenLabs Scribe v2 | $0.40/час | Лучший WER + таймстемпы для субтитров |
+| STT (черновик/preview) | Whisper v3-turbo (DeepInfra) | $0.06/час | 253x realtime, мгновенный preview |
+| Highlight detection (MVP) | Gemini 2.5 Flash | $0.005/мин | 20-60x дешевле TwelveLabs |
+| Highlight detection (premium) | TwelveLabs Pegasus 1.2 | $0.063/мин | Лучшая точность для автоматизации |
+| Chapters | Gemini 2.5 Flash | $0.005/мин | Достаточно качества, минимальная цена |
+| Semantic search | TwelveLabs Marengo 3.0 | $4/1000 запросов | Единственный с pre-indexed search |
+| B-Roll suggestions | Pexels API | Бесплатно | Реальное видео > AI-генерация |
+| TTS (русский) | SaluteSpeech | $2.1/1M символов | Самый дешёвый для RU |
+
+---
+
+## 2. STT — обновлённое сравнение
+
+### Сравнительная таблица (апрель 2026)
+
+| Сервис | WER (EN) | WER (RU, оценка) | $/час | Пословные таймстемпы | Диаризация | Особенности |
+|--------|----------|-------------------|-------|----------------------|------------|-------------|
+| **ElevenLabs Scribe v2** | **2.3%** | ~5-7% | $0.40 | Да, точные (для субтитров) | Да (batch) | Audio tagging (смех, музыка), 90+ языков |
+| **Deepgram Nova-3 Mono** | 5.4% | ~8-12% | $0.46 | Да, улучшены в v3 | Да (+$0.12/час) | Code-switching 10 языков в одном потоке |
+| **Deepgram Nova-3 Multi** | 5.4% | ~8-12% | $0.55 | Да | Да | Мультиязычная версия |
+| **Whisper large-v3 (stock)** | 4.2% | 9.0% | $0.06 (DeepInfra) | Да, ±500ms нативно | Нет | Open-source, pay-as-you-go |
+| **Whisper large-v3 (fine-tuned RU)** | — | **6.4%** | Self-hosted | Да, ±500ms | Нет | Требует GPU, инфраструктура |
+| **Whisper v3-turbo** | 4.8% | 10.2% | $0.06 (DeepInfra) | Да, менее точные | Нет | 253x realtime, 6x быстрее large |
+| **Google Speech V1** (текущий) | ~6-8% | ~8-12% | ~$0.06/15сек | Да | Да | Уже интегрирован |
+
+### Критический вывод: точность таймстемпов
+
+Для Coffee Project **точность пословных таймстемпов — главная метрика**, потому что субтитры синхронизируются покадрово в Remotion через `WordNode.time.start/end`.
+
+- **ElevenLabs Scribe v2**: создан для субтитрирования. Точность таймстемпов достаточна без постобработки.
+- **Whisper нативный**: ±500ms на уровне сегментов. Пословные таймстемпы из cross-attention весов — заметно неточные. Это проблема, которая уже есть в проекте.
+- **Whisper + WhisperX**: значительно лучше через wav2vec2 forced alignment, но добавляет вторую модель и сложность.
+
+### Рекомендация ML/AI-инженера
+
+**Двухуровневая архитектура STT:**
+
+| Уровень | Движок | Задержка | $/час | Когда |
+|---------|--------|----------|-------|-------|
+| Черновик (мгновенный) | Whisper v3-turbo (DeepInfra) | ~2-3 сек на 5 мин | $0.06 | Preview сразу после загрузки |
+| Продакшн (точный) | ElevenLabs Scribe v2 | ~15-30 сек на 5 мин | $0.40 | Заменяет черновик, используется для рендера |
+
+Экономия: 85% на большинстве взаимодействий (просмотр, предпросмотр), где достаточно черновика.
+
+### Новое в ElevenLabs Scribe v2
+
+- **Audio tagging** (январь 2026): детектирует смех, аплодисменты, музыку, шаги, фоновый шум. Теги появляются inline в транскрипте с таймстемпами: `(laughter)`, `(music)`.
+- **Scribe v2 Realtime**: 30-80ms задержка, 93.5% точность на 30 языках.
+- **Voice Isolator**: нейронное разделение речи — полезно для предобработки шумного видео.
+
+### Новое в Deepgram Nova-3
+
+- **54.2% снижение WER** для стриминга vs конкурентов.
+- **Live code-switching**: 10 языков (включая русский) в одном потоке.
+- **Keyterm prompting**: мультиязычный, улучшает точность для специфических терминов.
+- **Audio Intelligence — по-прежнему только EN.** Sentiment, topics, intent — только английский. Это критическое ограничение для нашего продукта.
+
+---
+
+## 3. TTS — обновлённое сравнение
+
+Без изменений vs первоначальное исследование. Обновлённые цены Deepgram:
+
+| Сервис | $/1K символов | $/1M символов | Особенности |
+|--------|---------------|---------------|-------------|
+| **SaluteSpeech** (Сбер) | ~$0.0021 | ~$2.1 | Самый дешёвый. RU/EN/KZ |
+| **Deepgram Aura-1** | $0.015 | $15 | Предыдущее поколение |
+| **Deepgram Aura-2** | $0.030 | $30 | Новейшая модель |
+| **ElevenLabs Flash/Turbo** | $0.06 | $60 | Business tier, ~75ms, 32 языка |
+| **ElevenLabs Multilingual v2/v3** | $0.12 | $120 | Премиум качество, voice cloning |
+
+---
+
+## 4. Video Intelligence — полное сравнение
+
+### Сравнительная матрица
+
+| Параметр | TwelveLabs | Gemini 2.5 Pro | Gemini 2.5 Flash | GPT-4o/4.1 | Google Video Intelligence | Azure Video Indexer |
+|----------|-----------|----------------|------------------|------------|--------------------------|---------------------|
+| **Тип** | Video-native foundation models | General VLM с видеовходом | General VLM (лёгкий) | Image-only (кадры) | Structured annotation | ML pipeline orchestrator |
+| **Архитектура** | Marengo (embeddings) + Pegasus (генерация) | Мультимодальный LLM | Мультимодальный LLM | Мультимодальный LLM (без видео) | Отдельные ML-модели | Набор Azure AI сервисов |
+| **Highlight detection** | Нативный API, таймкоды | Через промпт, секундные таймкоды | Через промпт | Нет | Нет | Нет |
+| **Semantic search** | Pre-indexed (Marengo) | Промпт-based | Промпт-based | Нет | Нет | Нет |
+| **Chapters** | Нативный API | Через промпт | Через промпт | Через промпт | Нет | Нет |
+| **Object tracking** | Сильный, cross-frame | Ограниченный | Ограниченный | Нет (между кадрами) | Отдельная фича ($0.15/мин) | Да |
+| **Макс. длительность** | 4 часа (Marengo), 1 час (Pegasus) | ~6 часов (2M контекст) | ~6 часов | Ограничен кадрами | Без лимита | 12 часов (free tier) |
+| **Русская речь** | Да (36+ языков) | Да (сильный) | Да | Нет нативного аудио | 50+ языков | 50+ языков |
+| **Цена за 1 мин** | $0.063 (index+analyze) | $0.021 (≤200k) | **$0.005** | $0.026-0.23 | $0.025-0.15 (per feature) | Custom |
+| **Цена за 1 час** | $3.78 | $1.26 | **$0.36** | $1.56-13.80 | $1.50-9.00 | Custom |
+| **Повторные запросы** | $4/1000 (дёшево) | Пересчитываются (дорого) | Пересчитываются | Пересчитываются | — | — |
+| **Бенчмарки** | SOTA VideoMME-Long (30+ мин) | 85.2% VideoMME | Ниже Pro | 72% VideoMME | — | — |
+
+### Ключевой инсайт: «проиндексируй раз — ищи многократно»
+
+TwelveLabs заявляет ~36,000x дешевле Gemini для повторных запросов к тому же видео ($0.09/видео-час/месяц vs $4.50/1M токенов за запрос). Но для **одноразового анализа** (highlight detection для одного видео) — Gemini 2.5 Flash в 12x дешевле.
+
+---
+
+## 5. TwelveLabs — глубокий анализ
+
+### Актуальные модели (апрель 2026)
+
+| Модель | Статус | Назначение | Ключевые улучшения |
+|--------|--------|-----------|-------------------|
+| **Marengo 3.0** | GA (текущая) | Embeddings, Search | 512-dim (было 1024), composed text+image search, спорт, 36 языков, 4 часа видео, 2x быстрее |
+| **Pegasus 1.2** | GA (текущая) | Analyze, генерация | 1 час видео, меньше галлюцинаций, SOTA на VideoMME-Long |
+| Marengo 2.7 | **Sunset 30 марта 2026** | — | Устарела |
+| Pegasus 1.1 | **Discontinued** | — | Автообновлена до 1.2 |
+
+### Подтверждённые цены (Developer plan)
+
+| Компонент | Цена | Подтверждено |
+|-----------|------|-------------|
+| Video indexing (Marengo/Pegasus) | $0.042/мин ($2.52/час) | ✅ |
+| Infrastructure (хранение индексов) | $0.0015/мин ($0.09/час/мес) | ✅ |
+| Analyze API input (Pegasus) | $0.021/мин | ✅ |
+| Analyze API output | $7.50/1M токенов | ✅ |
+| Search API | $4/1000 запросов | ✅ |
+| Embed API (video) | $0.042/мин | ✅ |
+| **Embed API (audio only)** | **$0.0083/мин** | 🆕 |
+| **Embed API (image)** | **$0.10/1000 запросов** | 🆕 |
+| **Embed API (text)** | **$0.07/1000 запросов** | 🆕 |
+
+Free tier: 600 минут, 100 видео, 90 дней хранения.
+
+### SDK и интеграция
+
+**Python SDK** (`pip install twelvelabs`, v1.2.1):
+```python
+from twelvelabs import TwelveLabs
+client = TwelveLabs(api_key=API_KEY)
+
+# Highlight detection
+res = client.generate.summarize(video_id="...", type="highlight")
+for hl in res.highlights:
+    print(f"{hl.start}s-{hl.end}s: {hl.highlight}")
+
+# Chapter generation
+res = client.generate.summarize(video_id="...", type="chapter")
+for ch in res.chapters:
+    print(f"{ch.start}s-{ch.end}s: {ch.chapter_title}")
+
+# Structured JSON output (новое)
+result = client.analyze(
+    video_id="...",
+    prompt="Extract key moments",
+    response_format=ResponseFormat(type="json_schema", json_schema={...})
+)
+```
+
+**Node.js SDK**: `npm install twelvelabs-js` (production-ready).
+
+**OpenAPI spec**: 8,400 строк, доступен в [repo](https://github.com/twelvelabs-io/twelvelabs-developer-experience).
+
+### Ограничения и gotchas
+
+- Текстовый запрос: макс **77 токенов** (Marengo), **500 токенов** (Marengo 3.0)
+- Промпт Pegasus: макс **375 токенов**
+- Видео: 360x360 — 5184x2160, aspect ratio 1:1 — 2.4:1, мин 4 сек
+- Размер файла: макс 200 МБ (прямая загрузка), 4 ГБ (multipart/URL)
+- Индексация: только async, нужно poll status или webhook
+- **Webhooks только для индексации** — нет для analyze/search/embed
+- Rate limits: Free 8 RPM, Dev Tier 1 = 600 RPM (search), автоапгрейд при $200+/мес
+
+### Интеграции из repo
+
+- **Vector Store RAG**: ChromaDB, Weaviate, LanceDB, Oracle
+- **Real-time мониторинг**: VideoDB (RTSP feeds)
+- **Visual pipelines**: Langflow
+- **Chatbot**: Poe
+
+---
+
+## 6. Gemini 2.5 — ключевой новый игрок
+
+### Почему это важно
+
+Gemini 2.5 Flash при $0.005/мин — это **20-60x дешевле TwelveLabs** для одноразового видеоанализа. С 2M-токенным контекстом может обработать ~6 часов видео за один вызов. Это делает highlight detection доступным даже на free tier нашего продукта.
+
+### Pricing per minute video
+
+Видео потребляет **258 токенов/сек** (1 fps). Аудио добавляет **25 токенов/сек**.
+
+| Модель | $/мин (видео) | $/мин (видео+аудио) | $/час | Batch (50% скидка) |
+|--------|---------------|---------------------|-------|-------------------|
+| **Gemini 2.5 Flash** | **$0.005** | $0.006 | $0.36 | $0.18/час |
+| Gemini 2.5 Pro (≤200k) | $0.019 | $0.021 | $1.26 | $0.63/час |
+| Gemini 2.5 Pro (>200k) | $0.039 | $0.041 | $2.46 | $1.23/час |
+
+### Gemini vs TwelveLabs: когда что
+
+| Сценарий | Победитель | Почему |
+|----------|-----------|-------|
+| Одноразовый highlight detection | **Gemini Flash** | 12x дешевле ($0.005 vs $0.063/мин) |
+| Точные таймкоды для автоматической нарезки | **TwelveLabs** | Video-native модель, лучше temporal grounding |
+| Повторные запросы к библиотеке видео | **TwelveLabs** | Index once, query many ($4/1000 запросов) |
+| Object tracking cross-frame | **TwelveLabs** | Архитектурное преимущество |
+| Chapter generation | **Gemini Flash** | Достаточно качества, 12x дешевле |
+| Semantic search | **TwelveLabs** | Единственный с pre-indexed vector search |
+| Budget MVP | **Gemini Flash** | Минимальная стоимость входа |
+
+### GPT-4o/4.1 — не рекомендуется для видео
+
+- **Нет нативного видеовхода** — нужно извлекать кадры (OpenCV/ffmpeg)
+- 85 токенов/кадр (low detail), 765 токенов/кадр (high detail)
+- $0.026-0.23/мин — **дороже Gemini при худшем качестве**
+- Нет аудио из видео (отдельный Whisper)
+- Нет встроенных таймкодов
+- GPT-4.1: улучшен до 72% VideoMME, но фундаментальное ограничение (кадры) остаётся
+
+---
+
+## 7. Clipping-платформы
+
+### Сравнение API-доступности
+
+| Платформа | API | Цена API | Highlights | Captions | Reframe | Batch | RU |
+|-----------|-----|----------|-----------|----------|---------|-------|-----|
+| **OpusClip** | Enterprise only | Custom | ✅ 95%+ mAP | ✅ | ✅ | 50 concurrent | Нет |
+| **Reap.video** | Все планы ($9.99+) | Включена | ✅ Multi-signal | ✅ 98 языков | ✅ | 5-15 concurrent | ✅ |
+| **Vizard** | Paid планы ($20+) | Включена | ✅ | ✅ 100+ языков | ✅ | Minimal API | Неизвестно |
+| **Descript** | Нет public API | — | ✅ "Find Good Clips" | ✅ | ✅ | — | Нет |
+| **CapCut** | Нет public API | — | ✅ Smart Highlights | ✅ | ✅ | — | Частично |
+
+### OpusClip — подробнее
+
+- **ClipAnything**: мультисигнальный AI (визуал + аудио + сентимент), mAP 0.93
+- **Virality Score**: 0-100 эвристика, спорная точность (клипы с низким скором часто работают лучше)
+- **API**: Enterprise-only, 30 req/мин, макс 10 часов видео
+- **Цены SaaS**: Free 60 мин/мес → Starter $15 (150 мин) → Pro $14.50/мес (annual, 3600/год)
+- **Барьер**: API недоступен на обычных планах
+
+### Reap.video — неожиданно сильный
+
+- **API + CLI + MCP** за $9.99/мес — значительно доступнее OpusClip
+- **MCP Server** — прямая интеграция с Claude Code и другими AI-агентами
+- **Prompt-first clipping**: опиши какие клипы хочешь — AI найдёт
+- **98 языков** включая русский для субтитров
+- **80 языков** для дубляжа (русский включён)
+- **Romanized scripts** (Hinglish, Arabizi) — уникальная фича
+
+### Конкурентная карта (Product Lead)
+
+```
+                 ВЫСОКАЯ ЦЕНА
+                    |
+         Descript   |   (Enterprise)
+         $24-35/мес |
+                    |
+    OpusClip $29    |
+                    |
+    Vizard $20-30---+--- ☕ Coffee Project TARGET: $15-29/мес
+                    |     Субтитры + Клипы в одном
+                    |
+   Reap $9.99       |
+                    |
+         CapCut     |
+         $8-20      |
+                    |
+                 НИЗКАЯ ЦЕНА
+                    |
+   ТОЛЬКО СУБТИТРЫ -------------- ПОЛНЫЙ REPURPOSING
+```
+
+**Позиционирование Coffee Project**: «Единственный инструмент, где субтитры И клипы — first-class citizens в одном workflow, по цене ниже full-editor tax.»
+
+---
+
+## 8. B-Roll генерация
+
+### Text-to-Video модели: текущее состояние
+
+| Модель | Качество | Длительность | $/5-сек клип | Готово для B-Roll? |
+|--------|----------|-------------|-------------|-------------------|
+| **Runway Gen-4 Turbo** | Хорошее, быстрое | 5-10 сек | $0.25 | Почти, но артефакты |
+| **Runway Gen-4.5** | Выше | 5-10 сек | $0.60 | Ближе |
+| **Runway Gen-4 Aleph** | Наивысшее (Runway) | 5-10 сек | $0.75 | Ближе |
+| **Pika 2.2** (via fal.ai) | Хорошее для соцсетей | 5 сек | **$0.20** | Для некритичного контента |
+| **Kling 2.6** | Отличное для природы | 5-10 сек | $0.45-0.50 | Для ландшафтов да |
+| **Veo 3.1** (Runway API) | Сильное | 5-10 сек | $1.00 | Дорого |
+
+### Честная оценка ML/AI-инженера: генерация НЕ готова
+
+**Нет, ещё не для профессионального использования.** Причины:
+
+1. **Консистентность**: каждая генерация независима. Нельзя получить два клипа с одинаковым освещением, локацией, камерой.
+2. **Длительность**: 5-10 секунд. Реальный B-Roll — 15-60 секунд. Нужно цепочку генераций, что усиливает проблему консистентности.
+3. **Артефакты**: даже Runway Gen-4 даёт нарушения физики, несоответствие освещения, «AI-маркеры».
+4. **Стоимость**: 5-10 B-Roll клипов × $0.50 (+ 2-3 перегенерации) = $7.50-15 за видео. Стоковое видео дешевле.
+
+### Рекомендация: AI-powered поиск стокового видео
+
+| Сервис | Цена | Библиотека | API | Semantic Search |
+|--------|------|-----------|-----|-----------------|
+| **Pexels API** | **Бесплатно** | ~150K видео | Да, хорошая документация | Базовый keyword |
+| **Storyblocks API** | Подписка | 1M+ видео | Да | Лучшая категоризация |
+| **Shutterstock API** | Per-download / подписка | Крупнейшая | Да | AI-powered search |
+
+**Phase 1 (запустить сейчас): Pexels API.**
+
+Pipeline:
+1. Транскрипция даёт текстовые сегменты с таймкодами
+2. Gemini Flash анализирует сегменты → предлагает ключевые слова для B-Roll
+3. Pexels API ищет подходящее стоковое видео
+4. Пользователь выбирает из предложений
+
+Бесплатно, реальное видео выглядит профессионально, можно запустить за недели.
+
+**Phase 2 (когда модели созреют): AI-generated B-Roll как premium-опция.** Revisit в Q3 2026 с Runway Gen-5 / Veo 4.
+
+---
+
+## 9. Архитектура интеграции в Coffee Project
+
+### Текущий pipeline (recap)
+
+```
+Upload → S3 → Media Probe (ffprobe) → Transcription (Whisper/Google) → Captions (Remotion) → S3
+                                                                           ↕
+                                                               Silence Detection (pydub)
+```
+
+**Что есть:**
+- 2 STT-движка: LOCAL_WHISPER (default `tiny` — плохое качество), GOOGLE_SPEECH_CLOUD
+- Dramatiq actors для всех фоновых задач с webhooks + WebSocket notifications
+- Пустое поле `semantic_tags` в `WordNode` — готово для ML-аннотаций
+- Silence detection (pydub + librosa)
+
+**Чего нет:**
+- Highlight/chapter detection
+- Semantic search
+- Video intelligence интеграция
+- Монетизация (планы, квоты, биллинг)
+
+### Новый модуль: `video_intelligence`
+
+Backend-архитектор рекомендует **один новый модуль** со стандартной 6-файловой структурой:
+
+```
+cpv3/modules/video_intelligence/
+    __init__.py
+    models.py        # VideoIndex model
+    schemas.py       # Index, Highlight, Chapter, Search schemas
+    repository.py    # VideoIndexRepository
+    service.py       # Provider calls, business logic
+    router.py        # API endpoints
+```
+
+### Модель данных
+
+```python
+class VideoIndex(Base, BaseModelMixin):
+    user_id: UUID                    # FK users
+    project_id: UUID | None          # FK projects
+    source_file_id: UUID             # FK files
+    provider: str                    # "TWELVE_LABS" | "GEMINI"
+    provider_index_id: str           # Provider-specific ID
+    provider_video_id: str           # Provider video ref
+    highlights_json: dict | None     # Cached highlights (JSONB)
+    chapters_json: dict | None       # Cached chapters (JSONB)
+    index_status: str                # PENDING | INDEXING | READY | FAILED
+    video_duration_seconds: float
+    indexing_cost_cents: int | None   # Cost tracking
+```
+
+Highlights и chapters — JSONB-колонки (не отдельные таблицы), по аналогии с `Transcription.document`.
+
+### Расширенный pipeline
+
+```
+Upload → S3 → Media Probe
+                    |
+        +-----------+-----------+
+        |                       |
+   Transcription           Video Index (user-triggered)
+   (Whisper/Scribe)       (TwelveLabs/Gemini)
+        |                       |
+        |              +--------+--------+
+        |              |        |        |
+        |         Highlights  Chapters  Search
+        |         (Dramatiq)  (Dramatiq) (sync endpoint)
+        |              |        |
+        +------+-------+--------+
+               |
+          Shorts/Clips Rendering (Remotion)
+```
+
+### Режимы операций
+
+| Операция | Режим | Почему |
+|----------|-------|-------|
+| Video indexing | **Dramatiq (async)** | Минуты обработки |
+| Highlight detection | **Dramatiq (async)** | 30-60 сек |
+| Chapter generation | **Dramatiq (async)** | 30-60 сек |
+| Semantic search | **Sync endpoint** | 1-3 сек ответ |
+| B-Roll suggestions | **Sync endpoint** | Быстрый поиск |
+
+### Новые endpoints
+
+**Task endpoints** (async, в `tasks/router.py`):
+```
+POST /api/tasks/video-index/           → 202 Accepted
+POST /api/tasks/highlights-detect/     → 202 Accepted
+POST /api/tasks/chapters-generate/     → 202 Accepted
+```
+
+**Sync endpoints** (в `video_intelligence/router.py`):
+```
+GET  /api/video-intelligence/{id}/              → VideoIndexRead
+GET  /api/video-intelligence/{id}/highlights/   → HighlightsResult
+GET  /api/video-intelligence/{id}/chapters/     → ChaptersResult
+POST /api/video-intelligence/search/            → VideoSearchResponse
+POST /api/video-intelligence/broll-suggestions/  → BRollSuggestionResponse
+```
+
+### Квоты и контроль расходов
+
+Redis-based per-user quotas:
+```python
+# Проверка ПЕРЕД созданием Dramatiq task
+QUOTA_FREE_INDEX_MINUTES = 60
+key = f"vi_quota:{user_id}:indexed_minutes"
+
+# Кэш поисковых запросов (5 мин TTL)
+key = f"vi_search_cache:{video_index_id}:{sha256(query)[:16]}"
+```
+
+### Ключевые архитектурные решения
+
+1. **НЕТ автоматической цепочки задач.** Frontend контролирует workflow — каждая задача запускается явно.
+2. **НЕТ абстрактного провайдер-паттерна** (YAGNI). Простой string selector как в transcription engine.
+3. **Retry с backoff для внешних API** (`max_retries=3, min_backoff=15000`) — в отличие от текущих actors с `max_retries=0`.
+4. **Highlights/chapters кэшируются в БД** (JSONB). Search кэшируется в Redis (5 мин TTL).
+
+---
+
+## 10. Remotion Pipeline — эволюция
+
+### Shorts/Clips рендеринг
+
+**Гибридный подход FFmpeg + Remotion (2-3x быстрее чистого Remotion):**
+
+| Шаг | Инструмент | Время | Зачем |
+|-----|-----------|-------|-------|
+| 1. Вырезать клип | FFmpeg `-c copy` | ~1 сек | Stream copy, без перекодирования |
+| 2. Рендер с субтитрами | Remotion `ShortVideo` | 10-30 сек на клип | Каппинг + reframe + стили |
+| 3. Upload | S3 multipart | ~5 сек | В папку `shorts/` |
+
+**Сравнение для 10-мин видео → 5 Shorts по 1 мин:**
+
+| Подход | Общее время | Ресурсы |
+|--------|------------|---------|
+| Чистый Remotion (5 рендеров от полного видео) | 5-10 мин | Высокие: 5 Chromium процессов, каждый ищет в 10-мин видео |
+| **Гибрид** (FFmpeg нарезка + 5 лёгких рендеров) | **2-5 мин** | Средние: FFmpeg ~5 сек + 5 лёгких Remotion |
+| Чистый FFmpeg (без субтитров) | ~10 сек | Минимальные |
+
+### Новая композиция: `ShortVideo`
+
+```typescript
+type ShortCompositionProps = {
+  videoSrc: string;
+  transcription: Transcription;
+  fps: number;
+  styleConfig?: CaptionStyleConfig;
+  clipStart: number;          // Начало в секундах
+  clipEnd: number;            // Конец в секундах
+  cropConfig?: {
+    focusX: number;           // 0-1, центр кропа
+    focusY: number;
+    autoReframe: boolean;
+  };
+};
+```
+
+**Адаптация субтитров для вертикального формата:**
+- Шрифт: 60-70px (вместо 40)
+- Строки на экране: 1, макс 3-4 слова
+- Позиция: bottom с отступом 80-100px (UI YouTube Shorts/TikTok/Reels перекрывает низ)
+- Max width: 95% от 1080px
+- Фон: более непрозрачный
+
+**Auto-reframe:**
+- Phase 1: Center crop (простейший, 607x1080 из 1920x1080)
+- Phase 2: Speaker-position crop (per-segment `focusX` из ML)
+- Phase 3: Per-frame face tracking (future)
+
+### Chapter markers
+
+Простой overlay — НЕ реструктуризация видео:
+- `ChapterOverlay` компонент: fade-in заголовок, hold 2 сек, fade-out
+- `interpolate()` для анимации (не CSS transitions)
+- YouTube chapters metadata — ответственность backend, не Remotion
+
+### B-Roll в Remotion
+
+Самая сложная фича — мультиисточниковый таймлайн:
+
+```typescript
+type BRollSegment = {
+  src: string;              // S3 presigned URL
+  startTime: number;        // Когда показать
+  endTime: number;
+  mode: "cutaway" | "pip";  // Полная замена или overlay
+  transitionIn?: "fade" | "slide" | "cut";
+  audio: "mute" | "duck" | "replace";
+};
+```
+
+- Использовать `<OffthreadVideo>` (не `<Video>`) — декодирование off-thread
+- Docker может потребовать увеличение памяти: 4GB → 6-8GB
+- Горизонтальное масштабирование: N контейнеров на одной BullMQ очереди
+
+### Pre-existing bug
+
+`remotion_service/src/themes/default.css:23` — CSS `transition: transform 0.1s ease;` на `.word`. Это browser timer, не Remotion frame clock. В CSS theme mode анимация scale на `.current-word` рендерится непредсказуемо. Inline style mode (с `styleConfig`) не затронут — это основной продакшн-путь.
+
+---
+
+## 11. Продуктовая стратегия и монетизация
+
+### Критическая находка: нулевая инфраструктура монетизации
+
+В кодовой базе **нет**:
+- Поля `plan` / `subscription` в User модели
+- Трекинга использования (минуты рендера, транскрипции)
+- Квот и лимитов
+- Интеграции с платёжными системами
+- Pricing page / upgrade modal
+
+Это **блокер** для любых платных фич.
+
+### Рекомендуемая тарифная сетка
+
+| | Free | Starter ($15/мес) | Pro ($29/мес) | Agency ($79/мес) |
+|---|---|---|---|---|
+| Минуты обработки | 30/мес | 150/мес | 400/мес | 1,200/мес |
+| Транскрипция | Whisper base | Все движки | Все движки | + приоритет |
+| Стили субтитров | 3 базовых | 10 | Все | + кастомный бренд |
+| Клипы с видео | Preview only | 5/видео | Безлимит | Безлимит |
+| Chapters | Да (бесплатно) | Да | Да | Да |
+| Качество экспорта | 720p + watermark | 1080p | 4K | 4K |
+| Highlights engine | Transcript-based | Gemini Flash | TwelveLabs | TwelveLabs + analytics |
+| API доступ | Нет | Нет | Нет | Да |
+| Команда | 1 | 1 | 1 | 5 |
+
+### Unit economics
+
+**Стоимость за минуту обработки:**
+
+| Компонент | $/мин |
+|-----------|-------|
+| TwelveLabs indexing | $0.042 |
+| TwelveLabs infrastructure | $0.0015/мес |
+| TwelveLabs search | ~$0.004 |
+| Whisper STT (self-hosted) | ~$0.0005 |
+| Remotion render (clip) | ~$0.02 |
+| S3 storage (amortized) | ~$0.001 |
+| **С TwelveLabs** | **~$0.07** |
+| **Без TwelveLabs (Gemini)** | **~$0.03** |
+
+**Маржинальность по тарифам:**
+
+| Тариф | Revenue | Avg usage | Cost (с TwelveLabs) | Gross Margin |
+|-------|---------|-----------|--------------------|--------------|
+| Starter $15 | $15 | ~80 мин | $5.60 | **63%** |
+| Pro $29 | $29 | ~200 мин | $14.00 | **52%** |
+| Agency $79 | $79 | ~600 мин | $42.00 | **47%** |
+
+### Free tier: TwelveLabs НЕ использовать
+
+Free tier должен использовать **transcript-based highlights** (анализ энергии + ключевых слов из транскрипции) — почти нулевая стоимость. TwelveLabs — только для платных тарифов.
+
+10,000 free users × $2.10/мес TwelveLabs = $21,000/мес. Без TwelveLabs = ~$900/мес.
+
+### Конкурентное позиционирование
+
+| Инструмент | За ~150 мин/мес + субтитры + клипы | Coffee Project эквивалент |
+|------------|-----------------------------------|--------------------------|
+| OpusClip Starter | $15/мес (клипы, без субтитров) | $15/мес (субтитры + клипы) |
+| Vizard Creator | $14.50-30/мес | $15/мес (лучше субтитры) |
+| Descript Hobbyist | $24/мес (полный редактор) | $15/мес (focused workflow) |
+| Reap | $9.99/мес | $15/мес (больше обработки) |
+
+### Русский рынок
+
+- **Нет локальных конкурентов** в AI video clipping
+- Западные инструменты: проблемы с оплатой (Stripe недоступен)
+- Платёжные системы: ЮKassa, CloudPayments, Тинькофф
+- Цены: ₽990/мес (Starter), ₽1,990/мес (Pro) — на 30-50% ниже USD
+- Каналы: VK, Telegram, YouTube (через VPN)
+
+---
+
+## 12. Сводная таблица стоимости
+
+### Расчёт для 100 часов видео/мес (обновлённый)
+
+| Стек | $/мес | Что получаем |
+|------|-------|-------------|
+| **Gemini 2.5 Flash** (highlights + chapters) | **~$36** | Highlight detection + chapters. Без search |
+| **TwelveLabs** (index + infra + analyze + search) | ~$389 | Полный video understanding + semantic search |
+| **Gemini Flash + TwelveLabs search** (гибрид) | ~$180 | Flash для анализа, TL для поиска по библиотеке |
+| **DeepInfra Whisper** (STT draft) | ~$6 | Черновая транскрипция |
+| **ElevenLabs Scribe** (STT prod) | ~$40 | Продакшн транскрипция |
+| **Pexels API** (B-Roll search) | **$0** | Поиск стокового видео |
+| **Google Video Intelligence** (labels + shots) | ~$450-600 | Метаданные, без highlights |
+
+### Рекомендуемый стек по фазам
+
+| Фаза | Стек | $/мес (100 часов) |
+|------|------|-------------------|
+| **MVP** | Gemini Flash + DeepInfra Whisper + Pexels | **~$42** |
+| **Growth** | Gemini Flash + Scribe v2 + TwelveLabs search | **~$220** |
+| **Scale** | TwelveLabs full + Scribe v2 + Pexels + Runway | **~$470** |
+
+---
+
+## 13. Рекомендации и дорожная карта
+
+### Приоритеты (RICE-скоринг от Product Lead)
+
+| Приоритет | Фича | Движок | Effort (dev-weeks) | $/мес (100 users) |
+|-----------|-------|--------|--------------------|--------------------|
+| **P0** | Upgrade STT → Scribe v2 | ElevenLabs API | 2-3 дня | $40-80 |
+| **P0** | Draft STT tier | Whisper v3-turbo (DeepInfra) | 2-3 дня | $6-12 |
+| **P0** | Монетизация (планы, квоты, биллинг) | Stripe + ЮKassa | 4-6 недель | — |
+| **P1** | Highlight detection MVP | Gemini 2.5 Flash | 1 неделя | $5-15 |
+| **P1** | Shorts rendering | FFmpeg + Remotion ShortVideo | 2-3 недели | — |
+| **P2** | Chapter generation | Gemini 2.5 Flash | 1 неделя | $5 |
+| **P2** | B-Roll suggestions (stock) | Pexels API + Gemini Flash | 2 недели | $5 + $0 |
+| **P3** | Premium highlights | TwelveLabs Pegasus 1.2 | 1 неделя | $50-200 |
+| **P3** | Semantic video search | TwelveLabs Marengo 3.0 | 2 недели | $20-50 |
+| **P4** | AI-generated B-Roll | Runway Gen-4 API | 1 неделя | Variable |
+
+### Фазы реализации
+
+**Pre-Phase: Монетизация (4-6 недель, параллельно с Phase 1)**
+- `plan`, `plan_expires_at`, `usage_minutes_current/limit` в User модели
+- Usage tracking middleware
+- Quota enforcement в service layer
+- Stripe Checkout + ЮKassa
+- Pricing page + upgrade modal
+
+**Phase 1: «Clips» — Highlights + Smart Clipping (8-10 недель)**
+- `video_intelligence` модуль
+- Gemini Flash интеграция для highlight detection
+- Shorts rendering (ShortVideo composition + FFmpeg pre-cut)
+- Субтитры на клипах (существующие стили)
+- Free tier: transcript-based highlights (preview only, без экспорта)
+- Paid: Gemini Flash highlights + экспорт клипов
+
+**Phase 2: Chapters + B-Roll suggestions (4-6 недель)**
+- Chapter generation через Gemini Flash
+- Chapter overlay в Remotion
+- YouTube chapters metadata export
+- Pexels API для B-Roll suggestions
+- Chapters — бесплатно (activation feature)
+
+**Phase 3: Premium Video Intelligence (future)**
+- TwelveLabs для premium highlight detection
+- Semantic video search (enterprise)
+- Prompt-first clipping
+- Batch processing
+
+---
+
+## 14. Красные флаги в текущем коде
+
+Обнаружено агентами при анализе кодовой базы:
+
+### Backend
+
+1. **Whisper default model = `tiny`** (`schemas.py:122`, `service.py:325`). Минимум `base` или `small` для приемлемого качества.
+
+2. **Нет `time_limit` на Dramatiq actor** (`@dramatiq.actor(max_retries=0)`, `service.py:603`). Corrupted файл может заставить воркер висеть бесконечно. Добавить `time_limit=1800000` (30 мин).
+
+3. **Google Speech V1 API**. V2 API имеет модель Chirp — значительно лучше для мультиязычного контента.
+
+4. **Нет кэширования транскрипций**. Actor не проверяет, существует ли транскрипция для того же файла + движка + модели + языка. Повторная транскрипция = потеря денег.
+
+5. **Transcription router обходит service layer** (`transcription/router.py:30-38`) — прямой вызов `TranscriptionRepository` из router. Нарушает паттерн Router → Service → Repository.
+
+6. **Нет пагинации** на `list_all_transcriptions` — возвращает неограниченный список.
+
+7. **Inline error strings** (`transcription/router.py:65`: `detail="Не найдено"`) — нет `ERROR_` константы.
+
+8. **`tasks/service.py` уже 1400+ строк** — новые actors должны делегировать в `video_intelligence/service.py`.
+
+### Remotion
+
+9. **CSS `transition` в `default.css:23`** — `transition: transform 0.1s ease;` на `.word` класс. Browser timer, не Remotion frame clock. Непредсказуемый рендеринг в CSS theme mode.
+
+10. **`<Video>` вместо `<OffthreadVideo>`** — для B-Roll с множественными видеоисточниками нужен `<OffthreadVideo>` (декодирование off-thread).
+
+11. **Docker лимиты**: 2 CPU, 4GB RAM, `MAX_CONCURRENT_RENDERS=2`. Shorts batch + B-Roll потребуют увеличения до 6-8GB.
+
+---
+
+## 15. Источники
+
+### STT
+- [Artificial Analysis STT Leaderboard](https://artificialanalysis.ai/speech-to-text)
+- [ElevenLabs Scribe v2](https://elevenlabs.io/blog/introducing-scribe-v2)
+- [ElevenLabs Scribe v2 Realtime](https://elevenlabs.io/blog/scribe-v2-realtime-in-elevenlabs-agents)
+- [ElevenLabs API Pricing](https://elevenlabs.io/pricing/api)
+- [Deepgram Nova-3 Introduction](https://deepgram.com/learn/introducing-nova-3-speech-to-text-api)
+- [Deepgram Nova-3 Multilingual WER](https://deepgram.com/learn/nova-3-multilingual-major-wer-improvements-across-languages)
+- [Deepgram Models & Languages](https://developers.deepgram.com/docs/models-languages-overview)
+- [Deepgram Pricing](https://deepgram.com/pricing)
+- [Whisper large-v3-turbo (HuggingFace)](https://huggingface.co/openai/whisper-large-v3-turbo)
+- [Whisper large-v3-russian (fine-tuned)](https://huggingface.co/antony66/whisper-large-v3-russian)
+- [DeepInfra Whisper API](https://deepinfra.com/openai/whisper-large-v3-turbo/api)
+
+### Video Intelligence
+- [TwelveLabs Pricing](https://www.twelvelabs.io/pricing)
+- [TwelveLabs Docs](https://docs.twelvelabs.io)
+- [TwelveLabs Marengo 3.0](https://www.twelvelabs.io/blog/marengo-3-0)
+- [TwelveLabs Pegasus 1.2](https://www.twelvelabs.io/blog/introducing-pegasus-1-2)
+- [TwelveLabs Video-to-Text Arena](https://www.twelvelabs.io/blog/video-to-text-arena)
+- [TwelveLabs Developer Experience (GitHub)](https://github.com/twelvelabs-io/twelvelabs-developer-experience)
+- [Gemini 2.5 Video Understanding](https://developers.googleblog.com/en/gemini-2-5-video-understanding/)
+- [Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
+- [GPT-4.1 Multimodal](https://blog.roboflow.com/gpt-4-1-multimodal/)
+- [Google Video Intelligence API](https://cloud.google.com/video-intelligence)
+
+### Clipping Platforms
+- [OpusClip API](https://help.opus.pro/api-reference/overview)
+- [OpusClip Pricing](https://www.opus.pro/pricing)
+- [Reap.video API](https://docs.reap.video/api-reference/1_introduction)
+- [Reap.video MCP](https://reap.video/mcp)
+- [Vizard API Docs](https://docs.vizard.ai/docs/introduction)
+- [Descript Pricing](https://www.descript.com/pricing)
+- [CapCut Pricing](https://www.gamsgo.com/blog/capcut-pricing)
+
+### B-Roll Generation
+- [Runway API Pricing](https://docs.dev.runwayml.com/guides/pricing/)
+- [Pika 2.2 on fal.ai](https://fal.ai/models/fal-ai/pika/v2.2/text-to-video)
+- [Kling AI Pricing](https://klingai.com/global/dev/pricing)
+- [Best Text-to-Video APIs 2026](https://wavespeed.ai/blog/posts/best-text-to-video-api-2026/)
+- [Pexels Free API](https://www.pexels.com/api/)
+
+### Market & Competition
+- [AI Video Generator Market (Grand View Research)](https://www.grandviewresearch.com/industry-analysis/ai-video-generator-market-report)
+- [Descript vs Veed vs Kapwing Growth (YipitData)](https://www.yipitdata.com/resources/blog/descript-vs-veed-vs-kapwing-ai-video-tools)
+- [OpusClip Highlight Accuracy](https://www.opus.pro/blog/ai-tools-for-precise-video-highlight-search-accuracy)
+- [SaaS Freemium Conversion Benchmarks](https://firstpagesage.com/seo-blog/saas-freemium-conversion-rates/)
+
+---
+
+*Документ подготовлен 8 параллельными исследовательскими агентами: 4 внешних ресёрчера (TwelveLabs repo, TwelveLabs pricing, Other Services, Coffee Architecture) + 4 доменных специалиста (ML/AI Engineer, Backend Architect, Product Lead, Remotion Engineer).*

docs/superpowers/plans/2026-03-24-docker-hardening.md

@@ -0,0 +1,888 @@
+# Docker Infrastructure Hardening — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harden all Docker infrastructure across the monorepo — security, build optimization, service organization, health checks, and networking.
+
+**Architecture:** 4-phase approach: quick config fixes first (no code changes), then Dockerfile improvements, then health endpoints + networking, then resource limits. Each phase produces a working stack.
+
+**Tech Stack:** Docker, Docker Compose, FastAPI (Python), ElysiaJS (Bun/TypeScript), PostgreSQL, Redis, MinIO
+
+---
+
+### Task 1: Add .env to .gitignore files
+
+**Files:**
+- Modify: `cofee_backend/.gitignore`
+- Modify: `cofee_frontend/.gitignore`
+
+- [ ] **Step 1: Add .env exclusion to backend .gitignore**
+
+Append to `cofee_backend/.gitignore`:
+```
+# Environment
+.env
+.env.*
+```
+
+- [ ] **Step 2: Add .env exclusion to frontend .gitignore**
+
+The frontend `.gitignore` has `.env*.local` but not `.env` itself. Add before the `# local env files` section in `cofee_frontend/.gitignore`:
+```
+# Environment
+.env
+```
+Note: Keep the existing `.env*.local` line too.
+
+- [ ] **Step 3: Verify .env files are not tracked**
+
+Run: `git ls-files | grep '\.env'`
+Expected: no output. If any .env files are tracked, run `git rm --cached <file>` for each.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add cofee_backend/.gitignore cofee_frontend/.gitignore
+git commit -m "fix(infra): add .env to backend and frontend .gitignore"
+```
+
+---
+
+### Task 2: Add .env to backend .dockerignore
+
+**Files:**
+- Modify: `cofee_backend/.dockerignore`
+
+- [ ] **Step 1: Add .env exclusion**
+
+Add to `cofee_backend/.dockerignore`:
+```
+.env
+.env.*
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add cofee_backend/.dockerignore
+git commit -m "fix(infra): exclude .env from backend Docker build context"
+```
+
+---
+
+### Task 3: DRY up docker-compose env vars with YAML anchor
+
+**Files:**
+- Modify: `cofee_backend/docker-compose.yml`
+
+The `api` and `worker` services share 14 identical env vars. Extract into an `x-backend-env` anchor. Also adds the missing `JWT_SECRET_KEY` to worker.
+
+- [ ] **Step 1: Add x-backend-env anchor and refactor services**
+
+Replace the entire `cofee_backend/docker-compose.yml` with:
+
+```yaml
+x-backend-image: &backend-image
+  image: cpv3-backend:dev
+  build:
+    context: .
+    dockerfile: Dockerfile
+    target: dev
+
+x-backend-env: &backend-env
+  DEBUG: ${DEBUG:-1}
+  JWT_SECRET_KEY: ${JWT_SECRET_KEY:-dev-secret}
+
+  POSTGRES_USER: ${POSTGRES_USER:-postgres}
+  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+  POSTGRES_HOST: db
+  POSTGRES_PORT: 5432
+  POSTGRES_DATABASE: ${POSTGRES_DATABASE:-coffee_project_db}
+
+  STORAGE_BACKEND: ${STORAGE_BACKEND:-S3}
+
+  S3_ACCESS_KEY: ${MINIO_ROOT_USER:-minioadmin}
+  S3_SECRET_KEY: ${MINIO_ROOT_PASSWORD:-minioadmin}
+  S3_BUCKET_NAME: ${S3_BUCKET_NAME:-coffee-bucket}
+  S3_ENDPOINT_URL_INTERNAL: http://minio:9000
+  S3_ENDPOINT_URL_PUBLIC: http://localhost:9000
+
+  REDIS_URL: redis://redis:6379/0
+  WEBHOOK_BASE_URL: http://api:8000
+
+  REMOTION_SERVICE_URL: ${REMOTION_SERVICE_URL:-http://remotion:3001}
+
+services:
+  db:
+    container_name: cpv3_postgres
+    image: postgres:16
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-postgres}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
+      POSTGRES_DB: ${POSTGRES_DATABASE:-coffee_project_db}
+    ports:
+      - "127.0.0.1:5332:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d ${POSTGRES_DB:-coffee_project_db}"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+    volumes:
+      - cpv3_db:/var/lib/postgresql/data
+
+  minio:
+    container_name: cpv3_minio
+    image: minio/minio:RELEASE.2024-11-07T00-52-20Z
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:9000:9000"
+      - "127.0.0.1:9001:9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ROOT_USER:-minioadmin}
+      MINIO_ROOT_PASSWORD: ${MINIO_ROOT_PASSWORD:-minioadmin}
+    command: server /data --console-address ":9001"
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    volumes:
+      - cpv3_minio:/data
+
+  redis:
+    container_name: cpv3_redis
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    volumes:
+      - cpv3_redis:/data
+
+  api:
+    container_name: cpv3_api
+    <<: *backend-image
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      <<: *backend-env
+    ports:
+      - "127.0.0.1:8000:8000"
+    volumes:
+      - ./cpv3:/app/cpv3
+      - ./alembic:/app/alembic
+      - ./alembic.ini:/app/alembic.ini
+
+  worker:
+    container_name: cpv3_worker
+    <<: *backend-image
+    restart: unless-stopped
+    depends_on:
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    environment:
+      <<: *backend-env
+    command: >
+      watchfiles --filter python 'dramatiq cpv3.modules.tasks.service --processes 1 --threads 2' /app/cpv3
+    volumes:
+      - ./cpv3:/app/cpv3
+
+volumes:
+  cpv3_db:
+  cpv3_minio:
+  cpv3_redis:
+```
+
+Key changes in this file:
+- `x-backend-env` anchor with all shared env vars (DRY)
+- `JWT_SECRET_KEY` added to worker (was missing)
+- `restart: unless-stopped` on all services
+- All ports bound to `127.0.0.1` (not `0.0.0.0`)
+- MinIO pinned to `RELEASE.2024-11-07T00-52-20Z`
+- MinIO health check added (`curl` on `/minio/health/live`)
+- Removed inline comments for cleanliness
+
+- [ ] **Step 2: Validate compose syntax**
+
+Run: `cd cofee_backend && docker compose config > /dev/null`
+Expected: no errors.
+
+- [ ] **Step 3: Test stack starts**
+
+Run: `cd cofee_backend && docker compose up -d`
+Wait 30s, then: `docker compose ps`
+Expected: all services `Up` or `Up (healthy)`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add cofee_backend/docker-compose.yml
+git commit -m "refactor(infra): DRY env vars, pin images, bind localhost, add restart policies"
+```
+
+---
+
+### Task 4: Move build-essential out of base stage in backend Dockerfile
+
+**Files:**
+- Modify: `cofee_backend/Dockerfile`
+
+`build-essential` is only needed during `uv sync` (compiling C extensions). Moving it from `base` to `deps` saves ~200MB in the prod image since the `prod` stage inherits from `deps` but the compiled artifacts are in `.venv`, not the system packages.
+
+- [ ] **Step 1: Restructure Dockerfile stages**
+
+Replace the entire `cofee_backend/Dockerfile` with:
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+
+# ---------------------------------------------------------------------------
+# Stage 1: base — minimal runtime dependencies (shared by dev and prod)
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim AS base
+
+COPY --from=ghcr.io/astral-sh/uv:0.8.15 /uv /uvx /bin/
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PATH="/app/.venv/bin:${PATH}"
+
+WORKDIR /app
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && apt-get install -y --no-install-recommends \
+        ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# ---------------------------------------------------------------------------
+# Stage 2: deps — install Python dependencies (build-essential here only)
+# ---------------------------------------------------------------------------
+FROM base AS deps
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml uv.lock ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-install-project
+
+# ---------------------------------------------------------------------------
+# Stage 3: dev — development target (used by docker-compose)
+# ---------------------------------------------------------------------------
+FROM deps AS dev
+
+ENV PYTHONPATH=/app
+
+EXPOSE 8000
+
+CMD ["sh", "-c", "alembic upgrade head && uvicorn cpv3.main:app --host 0.0.0.0 --port 8000 --reload --reload-dir /app/cpv3"]
+
+# ---------------------------------------------------------------------------
+# Stage 4: prod — production target (no build-essential, non-root user)
+# ---------------------------------------------------------------------------
+FROM base AS prod
+
+RUN groupadd --gid 1000 app && \
+    useradd --uid 1000 --gid app --create-home app
+
+COPY --from=deps /app/.venv /app/.venv
+COPY pyproject.toml uv.lock ./
+
+ENV UV_LINK_MODE=copy
+
+COPY cpv3 ./cpv3
+COPY alembic ./alembic
+COPY alembic.ini ./
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+RUN chown -R app:app /app
+USER app
+
+EXPOSE 8000
+
+CMD ["sh", "-c", "alembic upgrade head && uvicorn cpv3.main:app --host 0.0.0.0 --port 8000"]
+```
+
+Key changes:
+- `build-essential` moved from `base` to `deps` — prod image is ~200MB smaller
+- `prod` stage inherits from `base` (not `deps`) — no compiler in production
+- `prod` copies only `.venv` from `deps` stage — gets compiled packages without build tools
+- Non-root `app` user (uid 1000) added to `prod` stage
+- `dev` stage still inherits from `deps` (has build-essential for potential ad-hoc installs)
+
+- [ ] **Step 2: Build and verify prod stage**
+
+Run: `cd cofee_backend && docker build --target prod -t cpv3-backend:prod-test .`
+Expected: builds successfully.
+
+- [ ] **Step 3: Build and verify dev stage**
+
+Run: `cd cofee_backend && docker build --target dev -t cpv3-backend:dev-test .`
+Expected: builds successfully.
+
+- [ ] **Step 4: Verify dev stack still works**
+
+Run: `cd cofee_backend && docker compose up -d --build`
+Wait 30s, then: `docker compose ps`
+Expected: all services running.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add cofee_backend/Dockerfile
+git commit -m "perf(infra): move build-essential to deps stage, add non-root user to prod"
+```
+
+---
+
+### Task 5: Add BuildKit cache mounts and non-root user to Remotion Dockerfile
+
+**Files:**
+- Modify: `remotion_service/Dockerfile`
+
+- [ ] **Step 1: Update Remotion Dockerfile**
+
+Replace the entire `remotion_service/Dockerfile` with:
+
+```dockerfile
+# syntax=docker/dockerfile:1.7-labs
+FROM oven/bun:1.3.10 AS base
+
+ENV APP_HOME=/app \
+  PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 \
+  REMOTION_PUPPETEER_NO_SANDBOX=1 \
+  NODE_ENV=production
+
+WORKDIR ${APP_HOME}
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && \
+    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+    ca-certificates \
+    ffmpeg \
+    chromium \
+    libglib2.0-0 \
+    libnss3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libdrm2 \
+    libxkbcommon0 \
+    libgbm1 \
+    fonts-noto-color-emoji \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+FROM base AS deps
+WORKDIR ${APP_HOME}
+COPY package.json bun.lock ./
+RUN NODE_ENV=development bun install --frozen-lockfile
+
+FROM base AS runner
+WORKDIR ${APP_HOME}
+
+RUN groupadd --gid 1000 app && \
+    useradd --uid 1000 --gid app --create-home app
+
+COPY --from=deps ${APP_HOME}/node_modules ./node_modules
+COPY package.json bun.lock ./
+COPY tsconfig.json remotion.config.ts ./
+COPY public ./public
+COPY src ./src
+COPY server ./server
+
+RUN mkdir -p out && chown -R app:app /app
+
+USER app
+
+EXPOSE 3001
+
+CMD ["bun", "run", "server"]
+```
+
+Key changes:
+- BuildKit apt cache mounts added (matches backend pattern)
+- Non-root `app` user (uid 1000) in runner stage
+- `chown` before `USER app` so the app owns all files including `out/`
+
+- [ ] **Step 2: Build and verify**
+
+Run: `cd remotion_service && docker build --target runner -t remotion:test .`
+Expected: builds successfully.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add remotion_service/Dockerfile
+git commit -m "perf(infra): add BuildKit cache mounts and non-root user to Remotion Dockerfile"
+```
+
+---
+
+### Task 6: Add resource limits and cap_drop to Remotion docker-compose
+
+**Files:**
+- Modify: `remotion_service/docker-compose.yml`
+
+- [ ] **Step 1: Update Remotion docker-compose.yml**
+
+Replace the entire `remotion_service/docker-compose.yml` with:
+
+```yaml
+services:
+  remotion:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: runner
+    command: >
+      sh -lc "NODE_ENV=development bun install --frozen-lockfile && bun run server"
+    restart: unless-stopped
+    env_file: .env
+    environment:
+      S3_ENDPOINT_URL: http://minio:9000
+      REDIS_URL: redis://redis:6379/0
+    ports:
+      - "127.0.0.1:3001:3001"
+    deploy:
+      resources:
+        limits:
+          memory: 4g
+          cpus: "2"
+        reservations:
+          memory: 1g
+          cpus: "0.5"
+    cap_drop:
+      - ALL
+    cap_add:
+      - SYS_ADMIN
+    volumes:
+      - .:/app:cached
+      - remotion_node_modules:/app/node_modules
+    networks:
+      - backend
+    stdin_open: true
+    tty: true
+
+volumes:
+  remotion_node_modules:
+
+networks:
+  backend:
+    external: true
+    name: cofee_backend_default
+```
+
+Key changes:
+- `restart: unless-stopped`
+- Port bound to `127.0.0.1`
+- Resource limits: 4GB memory / 2 CPUs (Chromium + FFmpeg need this)
+- Resource reservations: 1GB / 0.5 CPU (scheduling guarantees)
+- `cap_drop: ALL` + `cap_add: SYS_ADMIN` (SYS_ADMIN needed for Chromium sandbox)
+
+- [ ] **Step 2: Validate compose syntax**
+
+Run: `cd remotion_service && docker compose config > /dev/null`
+Expected: no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add remotion_service/docker-compose.yml
+git commit -m "fix(infra): add resource limits, cap_drop, restart policy to Remotion compose"
+```
+
+---
+
+### Task 7: Add resource limits and cap_drop to backend docker-compose
+
+**Files:**
+- Modify: `cofee_backend/docker-compose.yml`
+
+- [ ] **Step 1: Add deploy and cap_drop sections to each service**
+
+Add to the `db` service after `volumes`:
+```yaml
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - DAC_OVERRIDE
+      - FOWNER
+      - SETGID
+      - SETUID
+```
+
+Add to the `minio` service after `volumes`:
+```yaml
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - DAC_OVERRIDE
+      - FOWNER
+      - SETGID
+      - SETUID
+```
+
+Add to the `redis` service after `volumes`:
+```yaml
+    cap_drop:
+      - ALL
+```
+
+Add to the `api` service after `volumes`:
+```yaml
+    deploy:
+      resources:
+        limits:
+          memory: 512m
+          cpus: "1"
+    cap_drop:
+      - ALL
+```
+
+Add to the `worker` service after `volumes`:
+```yaml
+    deploy:
+      resources:
+        limits:
+          memory: 1g
+          cpus: "1"
+    cap_drop:
+      - ALL
+```
+
+- [ ] **Step 2: Validate compose syntax**
+
+Run: `cd cofee_backend && docker compose config > /dev/null`
+Expected: no errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add cofee_backend/docker-compose.yml
+git commit -m "fix(infra): add resource limits and capability dropping to backend compose"
+```
+
+---
+
+### Task 8: Add health check endpoint to backend API
+
+**Files:**
+- Modify: `cofee_backend/cpv3/modules/system/router.py`
+
+The existing `/api/ping/` only returns a static response. We need a `/api/health/` endpoint that checks DB and Redis connectivity for Docker health checks.
+
+- [ ] **Step 1: Add health endpoint to system router**
+
+Replace the contents of `cofee_backend/cpv3/modules/system/router.py` with:
+
+```python
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cpv3.db.session import get_db
+from cpv3.infrastructure.settings import get_settings
+
+router = APIRouter(prefix="/api", tags=["System"])
+
+_settings = get_settings()
+
+
+@router.get("/ping/")
+async def ping() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@router.get("/health/")
+async def health(db: AsyncSession = Depends(get_db)) -> dict[str, str]:
+    """Health check for Docker/K8s probes. Verifies DB connectivity."""
+    try:
+        await db.execute(text("SELECT 1"))
+        db_status = "connected"
+    except Exception:
+        db_status = "disconnected"
+
+    status = "ok" if db_status == "connected" else "degraded"
+    return {"status": status, "database": db_status}
+```
+
+- [ ] **Step 2: Run linter**
+
+Run: `cd cofee_backend && uv run ruff check cpv3/modules/system/router.py`
+Expected: no errors.
+
+- [ ] **Step 3: Run existing tests**
+
+Run: `cd cofee_backend && uv run pytest -x -q 2>&1 | tail -10`
+Expected: all tests pass (health endpoint is additive, no breaking changes).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add cofee_backend/cpv3/modules/system/router.py
+git commit -m "feat(backend): add /api/health/ endpoint for Docker health checks"
+```
+
+---
+
+### Task 9: Add health check endpoint to Remotion service
+
+**Files:**
+- Modify: `remotion_service/server/index.ts`
+
+- [ ] **Step 1: Add /health endpoint before app.listen**
+
+Add before the `app.listen(...)` line (around line 138) in `remotion_service/server/index.ts`:
+
+```typescript
+app.get("/health", async () => {
+  return { status: "ok" };
+});
+```
+
+Note: This is outside the `/api` prefix since it's at the Elysia instance level. The endpoint will be available at `GET /api/health` because the Elysia instance has `prefix: "/api"`.
+
+- [ ] **Step 2: Type check**
+
+Run: `cd remotion_service && bunx tsc --noEmit`
+Expected: no new errors.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add remotion_service/server/index.ts
+git commit -m "feat(remotion): add /api/health endpoint for Docker health checks"
+```
+
+---
+
+### Task 10: Add health checks for api, worker, and remotion in compose files
+
+**Files:**
+- Modify: `cofee_backend/docker-compose.yml`
+- Modify: `remotion_service/docker-compose.yml`
+
+- [ ] **Step 1: Add healthcheck to api service**
+
+Add to `api` service in `cofee_backend/docker-compose.yml` (after `depends_on`):
+
+```yaml
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/api/health/')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 30s
+```
+
+- [ ] **Step 2: Add healthcheck to worker service**
+
+The worker has no HTTP port. Use a process check. Add to `worker` service:
+
+```yaml
+    healthcheck:
+      test: ["CMD-SHELL", "pgrep -f dramatiq || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 3
+```
+
+- [ ] **Step 3: Add healthcheck to remotion service**
+
+Add to `remotion` service in `remotion_service/docker-compose.yml` (after `environment`):
+
+```yaml
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3001/api/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+```
+
+- [ ] **Step 4: Validate both compose files**
+
+Run: `cd cofee_backend && docker compose config > /dev/null && cd ../remotion_service && docker compose config > /dev/null`
+Expected: no errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add cofee_backend/docker-compose.yml remotion_service/docker-compose.yml
+git commit -m "feat(infra): add health checks to api, worker, and remotion services"
+```
+
+---
+
+### Task 11: Add network segmentation to backend compose
+
+**Files:**
+- Modify: `cofee_backend/docker-compose.yml`
+
+Currently all services share one flat network. Separate into `db-net` (data stores) and `app-net` (application services). This prevents Remotion from reaching DB/Redis directly.
+
+- [ ] **Step 1: Add networks to compose**
+
+Add at the bottom of `cofee_backend/docker-compose.yml`, replacing the existing `volumes:` section:
+
+```yaml
+volumes:
+  cpv3_db:
+  cpv3_minio:
+  cpv3_redis:
+
+networks:
+  db-net:
+    driver: bridge
+  app-net:
+    driver: bridge
+```
+
+- [ ] **Step 2: Add network assignments to each service**
+
+Add to `db`:
+```yaml
+    networks:
+      - db-net
+```
+
+Add to `redis`:
+```yaml
+    networks:
+      - db-net
+```
+
+Add to `minio`:
+```yaml
+    networks:
+      - db-net
+      - app-net
+```
+
+Add to `api`:
+```yaml
+    networks:
+      - db-net
+      - app-net
+```
+
+Add to `worker`:
+```yaml
+    networks:
+      - db-net
+      - app-net
+```
+
+- [ ] **Step 3: Update Remotion compose to use app-net**
+
+In `remotion_service/docker-compose.yml`, change the networks section:
+
+```yaml
+networks:
+  backend:
+    external: true
+    name: cofee_backend_app-net
+```
+
+This ensures Remotion can reach MinIO and API (on `app-net`) but NOT PostgreSQL or Redis (on `db-net`).
+
+- [ ] **Step 4: Validate both compose files**
+
+Run: `cd cofee_backend && docker compose config > /dev/null && cd ../remotion_service && docker compose config > /dev/null`
+Expected: no errors.
+
+- [ ] **Step 5: Test full stack connectivity**
+
+Run:
+```bash
+cd cofee_backend && docker compose down && docker compose up -d
+# Wait for healthy
+cd ../remotion_service && docker compose down && docker compose up -d
+```
+
+Verify API can reach DB, Redis, MinIO. Verify Remotion can reach MinIO but NOT DB.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add cofee_backend/docker-compose.yml remotion_service/docker-compose.yml
+git commit -m "feat(infra): add network segmentation — db-net and app-net isolation"
+```
+
+---
+
+### Task 12: Final verification
+
+- [ ] **Step 1: Bring down everything**
+
+```bash
+cd cofee_backend && docker compose down
+cd ../remotion_service && docker compose down
+```
+
+- [ ] **Step 2: Clean build**
+
+```bash
+cd cofee_backend && docker compose build --no-cache
+cd ../remotion_service && docker compose build --no-cache
+```
+
+- [ ] **Step 3: Start backend stack**
+
+```bash
+cd cofee_backend && docker compose up -d
+```
+
+Wait for: `docker compose ps` shows all services healthy.
+
+- [ ] **Step 4: Start Remotion stack**
+
+```bash
+cd remotion_service && docker compose up -d
+```
+
+Wait for: `docker compose ps` shows remotion healthy.
+
+- [ ] **Step 5: Test API health**
+
+Run: `curl http://127.0.0.1:8000/api/health/`
+Expected: `{"status":"ok","database":"connected"}`
+
+- [ ] **Step 6: Test Remotion health**
+
+Run: `curl http://127.0.0.1:3001/api/health`
+Expected: `{"status":"ok"}`
+
+- [ ] **Step 7: Verify port binding**
+
+Run: `docker compose -f cofee_backend/docker-compose.yml ps --format '{{.Name}} {{.Ports}}'`
+Expected: all ports show `127.0.0.1:XXXX->YYYY/tcp` (not `0.0.0.0`).
+
+- [ ] **Step 8: Verify resource limits**
+
+Run: `docker inspect cpv3_api --format '{{.HostConfig.Memory}}'`
+Expected: `536870912` (512MB).
+
+Run: `docker inspect remotion --format '{{.HostConfig.Memory}}'`
+Expected: `4294967296` (4GB).

docs/superpowers/plans/2026-04-04-subtitle-revision-workspace.md

@@ -0,0 +1,478 @@
+# Subtitle Revision Workspace Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Redesign the subtitle-revision screen into a more cohesive editorial workspace while staying inside the current frontend design system.
+
+**Architecture:** Keep the existing component boundaries and logic intact, then improve hierarchy through coordinated shell styling and small presentation-only markup changes. The work is isolated to the shared stepper chrome, the subtitle-revision step layout, the transcription editor surface, and the timeline dock so the redesign remains low-risk and easy to verify.
+
+**Tech Stack:** Next.js 16, React, TypeScript, SCSS Modules, Vidstack, Lucide, Chrome DevTools MCP
+
+---
+
+## File Structure
+
+- Modify: `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss`
+  Purpose: Reduce stepper visual dominance and align it with the calmer workspace shell.
+- Modify: `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss`
+  Purpose: Introduce softer page-level spacing/canvas treatment around the active step content.
+- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx`
+  Purpose: Add minimal presentational structure for player/editor panel headers and shell grouping.
+- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss`
+  Purpose: Build the unified editorial workspace shell and responsive balanced split behavior.
+- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx`
+  Purpose: Add small semantic wrappers for a stronger editor header and cleaner segment metadata grouping.
+- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss`
+  Purpose: Redesign the editor surface, segment cards, and add-segment action within current tokens.
+- Modify: `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss`
+  Purpose: Make the timeline feel like a docked rail within the same workspace shell.
+
+## Task 1: Soften the Stepper and Page Canvas
+
+**Files:**
+- Modify: `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss`
+- Modify: `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss`
+- Test: `cd cofee_frontend && bunx tsc --noEmit`
+
+- [ ] **Step 1: Inspect the current stepper and wizard shell before editing**
+
+Run:
+
+```bash
+sed -n '1,220p' cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss
+sed -n '1,220p' cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss
+```
+
+Expected: confirm the current stepper uses a saturated active pill and the wizard root is mostly structural with minimal page-level styling.
+
+- [ ] **Step 2: Update the stepper to feel quieter and more integrated**
+
+Apply changes in `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss` so the active step is calmer and the bar reads as context instead of a hero element.
+
+Use this shape for the key selectors:
+
+```scss
+.root {
+	position: relative;
+	background: linear-gradient(180deg, variables.$bg-default 0%, variables.$bg-surface 100%);
+	border-bottom: 1px solid variables.$border-subtle;
+}
+
+.scrollContainer {
+	gap: 10px;
+	padding: 18px 28px 14px;
+}
+
+.step {
+	padding: 8px 14px 8px 8px;
+	border-radius: 999px;
+	background: rgba(255, 255, 255, 0.42);
+	border: 1px solid transparent;
+}
+
+.stepActive {
+	background: variables.$bg-surface;
+	border-color: rgba(139, 92, 246, 0.16);
+	box-shadow: 0 10px 24px rgba(24, 24, 27, 0.06);
+}
+
+.stepCompleted {
+	background: rgba(255, 255, 255, 0.28);
+}
+```
+
+- [ ] **Step 3: Give the wizard a softer canvas around the active step**
+
+Update `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss` so the content area gets breathing room without changing behavior.
+
+Use this shape:
+
+```scss
+.root {
+	display: flex;
+	flex-direction: column;
+	height: calc(100vh - var(--header-height));
+	overflow: hidden;
+	background: linear-gradient(180deg, variables.$bg-default 0%, rgba(255, 255, 255, 0.55) 100%);
+}
+
+.content {
+	flex: 1;
+	display: flex;
+	flex-direction: column;
+	overflow-y: auto;
+	min-height: 0;
+	padding: 18px 24px 24px;
+}
+```
+
+- [ ] **Step 4: Run the frontend type-check after the shell changes**
+
+Run:
+
+```bash
+cd cofee_frontend && bunx tsc --noEmit
+```
+
+Expected: exit code `0`.
+
+- [ ] **Step 5: Commit the shell changes**
+
+```bash
+git add cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss
+git commit -m "feat: refine project wizard shell"
+```
+
+## Task 2: Build the Subtitle Revision Workspace Shell
+
+**Files:**
+- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx`
+- Modify: `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss`
+- Test: `cd cofee_frontend && bunx tsc --noEmit`
+
+- [ ] **Step 1: Inspect the current subtitle-revision markup and styles**
+
+Run:
+
+```bash
+sed -n '1,260p' cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx
+sed -n '1,260p' cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss
+```
+
+Expected: confirm the current main grid, timeline, and footer are separate blocks with minimal shared shell styling.
+
+- [ ] **Step 2: Add panel headers and a single workspace shell in the TSX**
+
+Update `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx` so the player and editor live inside named panels.
+
+Use this structure inside the `MediaPlayer` content:
+
+```tsx
+<div className={styles.workspaceShell}>
+	<div className={styles.mainGrid}>
+		<section className={styles.panel}>
+			<div className={styles.panelHeader}>
+				<div>
+					<p className={styles.eyebrow}>Просмотр</p>
+					<h3 className={styles.panelTitle}>Видео проекта</h3>
+				</div>
+			</div>
+			<div className={styles.playerColumn}>...</div>
+		</section>
+
+		<section className={styles.panel}>
+			<div className={styles.panelHeader}>
+				<div>
+					<p className={styles.eyebrow}>Редактор</p>
+					<h3 className={styles.panelTitle}>Транскрипция</h3>
+				</div>
+			</div>
+			<div className={styles.editorColumn}>...</div>
+		</section>
+	</div>
+
+	<div className={styles.timelineWrapper}>...</div>
+	<div className={styles.footer}>...</div>
+</div>
+```
+
+- [ ] **Step 3: Style the workspace shell, balanced split, and responsive stack**
+
+Update `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss` with a single rounded shell, two equal panels, and a docked lower rail.
+
+Use this shape for the key selectors:
+
+```scss
+.workspaceShell {
+	display: flex;
+	flex-direction: column;
+	flex: 1;
+	min-height: 0;
+	border: 1px solid rgba(24, 24, 27, 0.08);
+	border-radius: variables.$radius-lg;
+	background: linear-gradient(180deg, rgba(255, 255, 255, 0.72) 0%, variables.$bg-surface 100%);
+	box-shadow: 0 18px 48px rgba(24, 24, 27, 0.08);
+	overflow: hidden;
+}
+
+.mainGrid {
+	display: grid;
+	grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+	gap: 18px;
+	padding: 20px;
+	flex: 1;
+	min-height: 0;
+}
+
+.panel {
+	display: flex;
+	flex-direction: column;
+	min-height: 0;
+	border: 1px solid rgba(24, 24, 27, 0.08);
+	border-radius: variables.$radius-lg;
+	background: rgba(255, 255, 255, 0.58);
+	overflow: hidden;
+}
+```
+
+Add responsive collapse:
+
+```scss
+@media (max-width: 1024px) {
+	.mainGrid {
+		grid-template-columns: 1fr;
+	}
+}
+```
+
+- [ ] **Step 4: Verify the layout still type-checks**
+
+Run:
+
+```bash
+cd cofee_frontend && bunx tsc --noEmit
+```
+
+Expected: exit code `0`.
+
+- [ ] **Step 5: Commit the workspace shell changes**
+
+```bash
+git add cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss
+git commit -m "feat: redesign subtitle revision workspace shell"
+```
+
+## Task 3: Redesign the Transcription Editor Surface
+
+**Files:**
+- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx`
+- Modify: `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss`
+- Test: `cd cofee_frontend && bunx tsc --noEmit`
+
+- [ ] **Step 1: Inspect the current transcription editor structure**
+
+Run:
+
+```bash
+sed -n '1,320p' cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx
+sed -n '1,320p' cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss
+```
+
+Expected: confirm the current editor has a plain header, dense segment rows, and a dashed add button.
+
+- [ ] **Step 2: Add semantic wrappers for a stronger header and cleaner metadata row**
+
+Update `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx` with small presentation-only wrappers.
+
+Use this shape:
+
+```tsx
+<div className={styles.headerMeta}>
+	<p className={styles.kicker}>Редактура</p>
+	<h3 className={styles.title}>Редактор транскрипции</h3>
+</div>
+
+<div className={styles.segmentMetaRow}>
+	<div className={styles.timesGroup}>...</div>
+	<div className={styles.actionsGroup}>...</div>
+</div>
+```
+
+For each timing field, wrap the label and input in a chip-like container:
+
+```tsx
+<label className={styles.timeChip}>
+	<span className={styles.timeLabelText}>Начало</span>
+	<input className={styles.timeInput} ... />
+</label>
+```
+
+- [ ] **Step 3: Rework the editor styling into a calmer editorial surface**
+
+Update `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss` so the editor looks less like a raw form and more like a reading/editing workspace.
+
+Use this shape for the key selectors:
+
+```scss
+.root {
+	display: flex;
+	flex-direction: column;
+	height: 100%;
+	min-height: 0;
+	background: transparent;
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: 18px 20px 14px;
+	border-bottom: 1px solid rgba(24, 24, 27, 0.08);
+	background: rgba(255, 255, 255, 0.68);
+}
+
+.segment {
+	border: 1px solid rgba(24, 24, 27, 0.08);
+	border-radius: variables.$radius-lg;
+	padding: 14px;
+	background: rgba(255, 255, 255, 0.82);
+	box-shadow: 0 8px 24px rgba(24, 24, 27, 0.04);
+}
+
+.timeChip {
+	display: inline-flex;
+	align-items: center;
+	gap: 8px;
+	padding: 6px 10px;
+	border-radius: 999px;
+	background: variables.$bg-hover;
+	border: 1px solid transparent;
+}
+
+.textArea {
+	padding: 14px 16px;
+	border-radius: variables.$radius-md;
+	line-height: 1.65;
+	background: rgba(244, 244, 245, 0.92);
+}
+```
+
+Replace the dashed add button treatment with a quieter inset surface:
+
+```scss
+.addButton {
+	margin: 0 20px 18px;
+	padding: 12px 14px;
+	border: 1px solid rgba(24, 24, 27, 0.08);
+	border-radius: variables.$radius-md;
+	background: rgba(255, 255, 255, 0.6);
+}
+```
+
+- [ ] **Step 4: Run the frontend type-check after the editor redesign**
+
+Run:
+
+```bash
+cd cofee_frontend && bunx tsc --noEmit
+```
+
+Expected: exit code `0`.
+
+- [ ] **Step 5: Commit the editor redesign**
+
+```bash
+git add cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss
+git commit -m "feat: refine transcription editor presentation"
+```
+
+## Task 4: Dock the Timeline and Verify in Chrome
+
+**Files:**
+- Modify: `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss`
+- Test: `cd cofee_frontend && bunx tsc --noEmit`
+- Verify: Chrome at `http://localhost:3000/projects/83eb1396-8217-4ceb-ae32-b3b63cd01982`
+
+- [ ] **Step 1: Inspect the current timeline chrome**
+
+Run:
+
+```bash
+sed -n '1,260p' cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss
+```
+
+Expected: confirm the toolbar and label column are functional but visually flatter and less integrated with the workspace shell.
+
+- [ ] **Step 2: Update the timeline dock styling to match the workspace**
+
+Modify `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss` so the toolbar, labels column, and scroll area feel like a lower editing rail.
+
+Use this shape:
+
+```scss
+.root {
+	display: flex;
+	flex-direction: column;
+	align-self: stretch;
+	height: 100%;
+	min-width: 0;
+	overflow: hidden;
+	background: rgba(255, 255, 255, 0.56);
+}
+
+.toolbar {
+	height: 40px;
+	padding: 0 14px;
+	border-bottom: 1px solid rgba(24, 24, 27, 0.08);
+	background: rgba(255, 255, 255, 0.72);
+}
+
+.labelsColumn {
+	width: 68px;
+	background: rgba(255, 255, 255, 0.48);
+}
+
+.zoomBtn {
+	width: 28px;
+	height: 28px;
+	border-radius: 999px;
+}
+```
+
+- [ ] **Step 3: Run the frontend type-check before browser verification**
+
+Run:
+
+```bash
+cd cofee_frontend && bunx tsc --noEmit
+```
+
+Expected: exit code `0`.
+
+- [ ] **Step 4: Verify the redesigned screen in Chrome**
+
+Check the route:
+
+```text
+http://localhost:3000/projects/83eb1396-8217-4ceb-ae32-b3b63cd01982
+```
+
+Verify all of the following:
+
+- the stepper is still readable but less dominant
+- the player and editor read as one shell
+- the desktop split still feels balanced
+- the transcription cards are calmer and easier to scan
+- the timeline feels docked to the workspace
+- the footer stays visually anchored
+- the layout still holds together at a narrower viewport
+
+- [ ] **Step 5: Commit the timeline and verification-backed finish**
+
+```bash
+git add cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss
+git commit -m "feat: align timeline dock with subtitle workspace"
+```
+
+## Self-Review
+
+### Spec Coverage
+
+- Quieter stepper: covered by Task 1
+- Single workspace shell: covered by Task 2
+- Stronger transcription editor hierarchy: covered by Task 3
+- Docked timeline integration: covered by Task 4
+- Responsive balanced split: covered by Task 2 and Task 4 browser verification
+- Design-system constraint: enforced in every task by reusing existing tokens and limiting scope to SCSS/module presentation
+
+### Placeholder Scan
+
+- No `TODO`, `TBD`, or deferred implementation notes remain
+- Each task lists exact files and commands
+- Each styling task includes concrete selector/code shapes instead of abstract guidance
+
+### Type Consistency
+
+- `workspaceShell`, `panel`, `panelHeader`, `eyebrow`, and `panelTitle` are introduced in the step component only
+- `headerMeta`, `kicker`, `segmentMetaRow`, and `timeChip` are introduced in the editor only
+- No new logic APIs or renamed behavioral props are required

docs/superpowers/plans/2026-04-06-subtitle-preset-grid-redesign.md

@@ -0,0 +1,687 @@
+# Subtitle Preset Grid Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Redesign preset preview cards to match uploaded video aspect ratio with modern visual refresh and style characteristics display
+
+**Architecture:** Fetch video metadata to calculate aspect ratio, pass to preset cards via props. Update StylePreview for dynamic sizing. Add loading skeleton state. Use Catppuccin Mocha color palette matching the project theme.
+
+**Tech Stack:** React, TypeScript, SCSS Modules, TanStack Query, openapi-react-query
+
+**Design Spec:** `docs/superpowers/specs/2026-04-06-subtitle-preset-grid-redesign.md`
+
+---
+
+## File Structure
+
+| File | Purpose |
+|------|---------|
+| `src/features/project/CaptionSettingsStep/useVideoMetadata.ts` | New hook to fetch video metadata and calculate aspect ratio |
+| `src/features/project/CaptionSettingsStep/PresetGrid.tsx` | Modified - adds aspect ratio fetching, loading state, passes ratio to cards |
+| `src/features/project/CaptionSettingsStep/PresetGrid.module.scss` | Modified - grid layout, responsive styles |
+| `src/features/project/CaptionSettingsStep/PresetCard.tsx` | Modified - adds style characteristics display, checkmark indicator, updated styling |
+| `src/features/project/CaptionSettingsStep/PresetCard.module.scss` | Modified - new card design with Catppuccin Mocha colors |
+| `src/features/project/CaptionSettingsStep/StylePreview.tsx` | Modified - accepts aspectRatio prop for dynamic sizing |
+| `src/features/project/CaptionSettingsStep/StylePreview.module.scss` | Modified - dynamic aspect-ratio container |
+| `src/features/project/CaptionSettingsStep/PresetCardSkeleton.tsx` | New - skeleton loading component for preset cards |
+| `src/features/project/CaptionSettingsStep/PresetCardSkeleton.module.scss` | New - skeleton styles with shimmer animation |
+
+---
+
+## Task 1: Create useVideoMetadata Hook
+
+**Files:**
+- Create: `src/features/project/CaptionSettingsStep/useVideoMetadata.ts`
+
+**Context:** This hook fetches video metadata from the API and calculates the aspect ratio. It uses the existing `api` from `@shared/api` which is openapi-react-query.
+
+- [ ] **Step 1: Write the hook implementation**
+
+```typescript
+import { useMemo } from "react"
+import api from "@shared/api"
+
+interface UseVideoMetadataResult {
+  aspectRatio: number
+  isLoading: boolean
+  isError: boolean
+}
+
+const DEFAULT_ASPECT_RATIO = 16 / 9
+
+export function useVideoMetadata(fileId: string | null): UseVideoMetadataResult {
+  const { data: mediaFile, isLoading, isError } = api.useQuery(
+    "get",
+    "/api/media/mediafiles/{media_file_id}/",
+    {
+      params: {
+        path: {
+          media_file_id: fileId ?? "",
+        },
+      },
+    },
+    {
+      enabled: !!fileId,
+    }
+  )
+
+  const aspectRatio = useMemo(() => {
+    if (!mediaFile?.width || !mediaFile?.height) {
+      return DEFAULT_ASPECT_RATIO
+    }
+    return mediaFile.width / mediaFile.height
+  }, [mediaFile])
+
+  return {
+    aspectRatio,
+    isLoading,
+    isError,
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/features/project/CaptionSettingsStep/useVideoMetadata.ts
+git commit -m "feat: add useVideoMetadata hook for aspect ratio calculation"
+```
+
+---
+
+## Task 2: Create PresetCardSkeleton Component
+
+**Files:**
+- Create: `src/features/project/CaptionSettingsStep/PresetCardSkeleton.tsx`
+- Create: `src/features/project/CaptionSettingsStep/PresetCardSkeleton.module.scss`
+
+- [ ] **Step 1: Write the SCSS module**
+
+```scss
+// PresetCardSkeleton.module.scss
+.skeletonCard {
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--bg-default);
+  border: 1px solid var(--border-subtle);
+  display: flex;
+  flex-direction: column;
+}
+
+.skeletonPreview {
+  aspect-ratio: 16 / 9;
+  background: var(--bg-surface);
+  position: relative;
+  overflow: hidden;
+
+  &::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      rgba(203, 166, 247, 0.08) 50%,
+      transparent 100%
+    );
+    animation: shimmer 1.5s infinite;
+  }
+}
+
+@keyframes shimmer {
+  0% {
+    transform: translateX(-100%);
+  }
+  100% {
+    transform: translateX(100%);
+  }
+}
+
+.skeletonFooter {
+  padding: 14px 16px;
+  background: linear-gradient(to top, var(--bg-surface), var(--bg-default));
+  border-top: 1px solid var(--border-subtle);
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.skeletonLine {
+  height: 14px;
+  background: var(--bg-hover);
+  border-radius: 4px;
+  width: 60%;
+  position: relative;
+  overflow: hidden;
+
+  &::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      transparent 0%,
+      rgba(203, 166, 247, 0.06) 50%,
+      transparent 100%
+    );
+    animation: shimmer 1.5s infinite;
+  }
+}
+
+.skeletonLineShort {
+  composes: skeletonLine;
+  width: 40%;
+  height: 10px;
+}
+```
+
+- [ ] **Step 2: Write the component**
+
+```typescript
+// PresetCardSkeleton.tsx
+import type { FunctionComponent } from "react"
+import type { JSX } from "react"
+
+import styles from "./PresetCardSkeleton.module.scss"
+
+interface IPresetCardSkeletonProps {
+  aspectRatio?: number
+}
+
+export const PresetCardSkeleton: FunctionComponent<IPresetCardSkeletonProps> = ({
+  aspectRatio = 16 / 9,
+}): JSX.Element => {
+  return (
+    <div className={styles.skeletonCard}>
+      <div
+        className={styles.skeletonPreview}
+        style={{ aspectRatio }}
+      />
+      <div className={styles.skeletonFooter}>
+        <div className={styles.skeletonLine} />
+        <div className={styles.skeletonLineShort} />
+      </div>
+    </div>
+  )
+}
+```
+
+- [ ] **Step 3: Add barrel export**
+
+Add to `src/features/project/CaptionSettingsStep/index.ts`:
+
+```typescript
+export { PresetCardSkeleton } from "./PresetCardSkeleton"
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/project/CaptionSettingsStep/PresetCardSkeleton.tsx
+git add src/features/project/CaptionSettingsStep/PresetCardSkeleton.module.scss
+git add src/features/project/CaptionSettingsStep/index.ts
+git commit -m "feat: add PresetCardSkeleton component with shimmer animation"
+```
+
+---
+
+## Task 3: Update StylePreview for Dynamic Aspect Ratio
+
+**Files:**
+- Modify: `src/features/project/CaptionSettingsStep/StylePreview.tsx`
+- Modify: `src/features/project/CaptionSettingsStep/StylePreview.module.scss`
+
+- [ ] **Step 1: Read existing StylePreview files**
+
+```bash
+cat src/features/project/CaptionSettingsStep/StylePreview.tsx
+cat src/features/project/CaptionSettingsStep/StylePreview.module.scss
+```
+
+- [ ] **Step 2: Update StylePreview.module.scss**
+
+Add or modify the preview container to accept dynamic aspect-ratio:
+
+```scss
+// Add to existing StylePreview.module.scss
+.previewContainer {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  background: #0c0a1a;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+- [ ] **Step 3: Update StylePreview.tsx**
+
+Add `aspectRatio` prop and apply it to the container:
+
+```typescript
+// Add to existing imports
+import type { CSSProperties } from "react"
+
+// Update interface to include aspectRatio
+interface IStylePreviewProps {
+  preset: CaptionPresetRead
+  aspectRatio?: number
+  className?: string
+}
+
+// In component, apply aspect ratio
+export const StylePreview: FunctionComponent<IStylePreviewProps> = ({
+  preset,
+  aspectRatio = 9 / 16, // Default to vertical (original behavior)
+  className,
+}): JSX.Element => {
+  // ... existing logic ...
+
+  const containerStyle: CSSProperties = {
+    aspectRatio: String(aspectRatio),
+  }
+
+  return (
+    <div
+      className={cs(styles.previewContainer, className)}
+      style={containerStyle}
+    >
+      {/* ... existing preview content ... */}
+    </div>
+  )
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/project/CaptionSettingsStep/StylePreview.tsx
+git add src/features/project/CaptionSettingsStep/StylePreview.module.scss
+git commit -m "feat: add aspectRatio prop to StylePreview for dynamic sizing"
+```
+
+---
+
+## Task 4: Update PresetCard with New Design
+
+**Files:**
+- Modify: `src/features/project/CaptionSettingsStep/PresetCard.tsx`
+- Modify: `src/features/project/CaptionSettingsStep/PresetCard.module.scss`
+
+- [ ] **Step 1: Read existing PresetCard files**
+
+```bash
+cat src/features/project/CaptionSettingsStep/PresetCard.tsx
+cat src/features/project/CaptionSettingsStep/PresetCard.module.scss
+```
+
+- [ ] **Step 2: Rewrite PresetCard.module.scss with new design**
+
+```scss
+// PresetCard.module.scss
+.presetCard {
+  position: relative;
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--bg-default);
+  border: 1px solid var(--border-subtle);
+  cursor: pointer;
+  transition: all 0.2s cubic-bezier(0.2, 0.8, 0.2, 1);
+  display: flex;
+  flex-direction: column;
+
+  &:hover {
+    border-color: var(--purple-400);
+    transform: translateY(-2px);
+    box-shadow: var(--shadow-md);
+  }
+}
+
+.selected {
+  border-color: var(--purple-400);
+  box-shadow:
+    0 0 0 1px var(--purple-400),
+    0 0 20px rgba(203, 166, 247, 0.25),
+    var(--shadow-lg);
+
+  &::before {
+    content: "";
+    position: absolute;
+    inset: -1px;
+    border-radius: 12px;
+    padding: 1px;
+    background: linear-gradient(135deg, var(--purple-400), var(--purple-600));
+    -webkit-mask:
+      linear-gradient(#fff 0 0) content-box,
+      linear-gradient(#fff 0 0);
+    -webkit-mask-composite: xor;
+    mask-composite: exclude;
+    pointer-events: none;
+  }
+}
+
+.previewArea {
+  position: relative;
+  overflow: hidden;
+}
+
+.selectedIndicator {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  width: 20px;
+  height: 20px;
+  background: var(--purple-400);
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-shadow: 0 2px 8px rgba(203, 166, 247, 0.4);
+
+  svg {
+    width: 12px;
+    height: 12px;
+    color: var(--bg-canvas);
+  }
+}
+
+.cardFooter {
+  padding: 14px 16px;
+  background: linear-gradient(to top, var(--bg-surface), var(--bg-default));
+  border-top: 1px solid var(--border-subtle);
+}
+
+.presetName {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin-bottom: 6px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.systemBadge {
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  padding: 2px 8px;
+  background: var(--purple-100);
+  color: var(--purple-400);
+  border-radius: 4px;
+}
+
+.styleChars {
+  font-size: 12px;
+  color: var(--text-tertiary);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.colorDot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  display: inline-block;
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.1);
+}
+
+.divider {
+  color: var(--border-default);
+}
+```
+
+- [ ] **Step 3: Update PresetCard.tsx with style characteristics**
+
+```typescript
+// Add helper to extract style characteristics
+function getStyleCharacteristics(preset: CaptionPresetRead): {
+  fontFamily: string
+  accentColor: string | null
+  accentName: string | null
+} {
+  const style = preset.style_config
+  const fontFamily = style?.text?.font_family ?? "Inter"
+
+  // Extract accent color from highlight or text color
+  const highlightColor = style?.highlight?.color
+  const textColor = style?.text?.color
+
+  // Simple color name mapping (expand as needed)
+  const colorMap: Record<string, string> = {
+    "#FFD700": "Золотой",
+    "#00ffff": "Неоновый",
+    "#ffffff": "Белый",
+    "#ff006e": "Розовый",
+    "#cba6f7": "Пурпурный",
+    "#f38ba8": "Розовый",
+    "#a6e3a1": "Зеленый",
+    "#f9e2af": "Желтый",
+    "#89dceb": "Голубой",
+  }
+
+  const accentColor = highlightColor || textColor
+  const accentName = accentColor ? (colorMap[accentColor] ?? null) : null
+
+  return {
+    fontFamily,
+    accentColor,
+    accentName,
+  }
+}
+
+// Update component to render characteristics
+export const PresetCard: FunctionComponent<IPresetCardProps> = ({
+  preset,
+  isSelected,
+  aspectRatio,
+  onSelect,
+  onEdit,
+  onDelete,
+}): JSX.Element => {
+  const { fontFamily, accentColor, accentName } = getStyleCharacteristics(preset)
+
+  return (
+    <div
+      className={cs(styles.presetCard, { [styles.selected]: isSelected })}
+      onClick={onSelect}
+    >
+      <div className={styles.previewArea}>
+        <StylePreview preset={preset} aspectRatio={aspectRatio} />
+        {isSelected && (
+          <div className={styles.selectedIndicator}>
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="3">
+              <polyline points="20 6 9 17 4 12" />
+            </svg>
+          </div>
+        )}
+      </div>
+      <div className={styles.cardFooter}>
+        <div className={styles.presetName}>
+          {preset.name}
+          {preset.is_system && <span className={styles.systemBadge}>Системный</span>}
+        </div>
+        <div className={styles.styleChars}>
+          {fontFamily}
+          {accentColor && accentName && (
+            <>
+              <span className={styles.divider}>·</span>
+              <span
+                className={styles.colorDot}
+                style={{ background: accentColor }}
+              />
+              <span style={{ color: accentColor }}>{accentName}</span>
+            </>
+          )}
+        </div>
+      </div>
+      {/* Context menu for edit/delete - preserve existing */}
+    </div>
+  )
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/project/CaptionSettingsStep/PresetCard.tsx
+git add src/features/project/CaptionSettingsStep/PresetCard.module.scss
+git commit -m "feat: redesign PresetCard with style characteristics and checkmark indicator"
+```
+
+---
+
+## Task 5: Update PresetGrid with Aspect Ratio and Loading State
+
+**Files:**
+- Modify: `src/features/project/CaptionSettingsStep/PresetGrid.tsx`
+- Modify: `src/features/project/CaptionSettingsStep/PresetGrid.module.scss`
+
+- [ ] **Step 1: Read existing PresetGrid files**
+
+```bash
+cat src/features/project/CaptionSettingsStep/PresetGrid.tsx
+cat src/features/project/CaptionSettingsStep/PresetGrid.module.scss
+```
+
+- [ ] **Step 2: Update PresetGrid.module.scss**
+
+```scss
+// PresetGrid.module.scss
+.presetGrid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 20px;
+
+  @media (max-width: 768px) {
+    grid-template-columns: repeat(2, 1fr);
+    gap: 12px;
+  }
+}
+
+// Optional: Add fade-in animation for cards
+@keyframes fadeInUp {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.cardWrapper {
+  animation: fadeInUp 0.3s ease forwards;
+
+  // Staggered animation delay
+  @for $i from 1 through 10 {
+    &:nth-child(#{$i}) {
+      animation-delay: #{$i * 50}ms;
+    }
+  }
+}
+```
+
+- [ ] **Step 3: Update PresetGrid.tsx**
+
+```typescript
+// Add imports
+import { useVideoMetadata } from "./useVideoMetadata"
+import { PresetCardSkeleton } from "./PresetCardSkeleton"
+import { useWizard } from "../WizardContext"
+
+// In component
+export const PresetGrid: FunctionComponent<IPresetGridProps> = ({
+  presets,
+  selectedPresetId,
+  onSelect,
+  onEdit,
+  onDelete,
+  onCreate,
+}): JSX.Element => {
+  const { primaryFileId } = useWizard()
+  const { aspectRatio, isLoading: isLoadingMetadata } = useVideoMetadata(primaryFileId)
+
+  if (isLoadingMetadata) {
+    return (
+      <div className={styles.presetGrid}>
+        {Array.from({ length: 4 }).map((_, i) => (
+          <PresetCardSkeleton key={i} aspectRatio={aspectRatio} />
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <div className={styles.presetGrid}>
+      {presets.map((preset, index) => (
+        <div
+          key={preset.id}
+          className={styles.cardWrapper}
+          style={{ animationDelay: `${index * 50}ms` }}
+        >
+          <PresetCard
+            preset={preset}
+            isSelected={preset.id === selectedPresetId}
+            aspectRatio={aspectRatio}
+            onSelect={() => onSelect(preset.id)}
+            onEdit={() => onEdit(preset.id)}
+            onDelete={() => onDelete(preset.id)}
+          />
+        </div>
+      ))}
+      {/* Create new card - preserve existing */}
+    </div>
+  )
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/features/project/CaptionSettingsStep/PresetGrid.tsx
+git add src/features/project/CaptionSettingsStep/PresetGrid.module.scss
+git commit -m "feat: add aspect ratio and loading state to PresetGrid"
+```
+
+---
+
+## Task 6: Type Check and Verify
+
+- [ ] **Step 1: Run type check**
+
+```bash
+cd cofee_frontend && bunx tsc --noEmit
+```
+
+Expected: No TypeScript errors
+
+- [ ] **Step 2: Run lint check**
+
+```bash
+cd cofee_frontend && bun run lint 2>/dev/null || echo "Lint not configured, using type check only"
+```
+
+- [ ] **Step 3: Final commit**
+
+```bash
+git add .
+git commit -m "feat: complete subtitle preset grid redesign with dynamic aspect ratio"
+```
+
+---
+
+## Verification Checklist
+
+- [ ] Preset cards display with correct aspect ratio based on uploaded video
+- [ ] Loading state shows skeleton cards with shimmer animation
+- [ ] Style characteristics (font, color) visible on card footers
+- [ ] Selected card shows checkmark indicator and purple glow border
+- [ ] Grid is responsive (2 columns on mobile, more on desktop)
+- [ ] Hover effects work smoothly
+- [ ] Falls back to 16:9 when no video is available
+- [ ] All existing functionality preserved (select, edit, delete, create)

docs/superpowers/specs/2026-04-03-salutespeech-transcription-design.md

@@ -0,0 +1,410 @@
+# SaluteSpeech Transcription Engine — Design Spec
+
+**Date:** 2026-04-03
+**Status:** Approved
+**Scope:** Backend (primary), Frontend (minor)
+
+## Overview
+
+Add SaluteSpeech (Sber) as a third transcription engine alongside Local Whisper and Google Speech Cloud. SaluteSpeech provides async REST-based speech recognition with word-level timestamps, domain-specific models (general/finance/medicine), and supports Russian and English.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| API protocol | REST (not gRPC) | No gRPC deps in codebase, REST covers full async flow |
+| Implementation pattern | Direct integration (Approach A) | Matches existing if/elif dispatch, no new abstractions |
+| HTTP client | `httpx` (sync) | Already used in workers (`tasks/service.py:12`) |
+| TLS certificates | Bundled PEM in repo, path via Settings | Self-contained, no Dockerfile changes |
+| Token caching | Module-level globals + `threading.Lock` | Thread-safe for Dramatiq multi-thread workers, matches existing pattern |
+| Token TTL | `time.monotonic()` + actual `expires_at` from response | Avoids clock drift vs hardcoded 30 min |
+| Engine short name | `"salutespeech"` | API boundary name, maps to DB `"SALUTE_SPEECH"` |
+| SaluteSpeech plan | `SALUTE_SPEECH_PERS` | Personal scope, max 5 parallel streams |
+| pip package | None (raw HTTP) | `salute_speech` package is unmaintained |
+| Frontend model selector | Shown for SaluteSpeech (general/finance/medicine) | Meaningful differentiator, follows Whisper conditional pattern |
+
+## SaluteSpeech API Flow
+
+```
+1. Auth:    POST https://ngw.devices.sberbank.ru:9443/api/v2/oauth
+2. Upload:  POST https://smartspeech.sber.ru/rest/v1/data:upload
+3. Task:    POST https://smartspeech.sber.ru/rest/v1/speech:async_recognize
+4. Poll:    GET  https://smartspeech.sber.ru/rest/v1/task:get?id=<task_id>
+5. Download: GET https://smartspeech.sber.ru/rest/v1/data:download?response_file_id=<id>
+```
+
+Token TTL: 30 min (from API response `expires_at`). Refresh when < 60s remaining.
+Uploaded files retained 72 hours server-side.
+Task statuses: NEW → RUNNING → DONE | ERROR.
+
+## Backend — Authentication & HTTP Client
+
+### Token Cache
+
+Module-level cache with `threading.Lock` for Dramatiq thread safety:
+
+```python
+import threading
+
+_salute_token_lock = threading.Lock()
+_salute_token: str | None = None
+_salute_token_expires_at: float = 0.0  # time.monotonic()
+
+def _get_salute_access_token(client: httpx.Client) -> str:
+    global _salute_token, _salute_token_expires_at
+    with _salute_token_lock:
+        if _salute_token and time.monotonic() < _salute_token_expires_at - SALUTE_TOKEN_REFRESH_MARGIN_SECONDS:
+            return _salute_token
+        settings = get_settings()
+        response = client.post(
+            SALUTE_AUTH_URL,
+            headers={
+                "Authorization": f"Basic {settings.salute_auth_key}",
+                "RqUID": str(uuid.uuid4()),
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            content=f"scope={settings.salute_scope}",
+        )
+        response.raise_for_status()
+        data = response.json()
+        _salute_token = data["access_token"]
+        # expires_at is Unix ms; convert to monotonic offset
+        expires_in_seconds = (data["expires_at"] / 1000) - time.time()
+        _salute_token_expires_at = time.monotonic() + expires_in_seconds
+        return _salute_token
+```
+
+### Settings (3 new fields in `infrastructure/settings.py`)
+
+```python
+# SaluteSpeech
+salute_auth_key: str = Field(default="", alias="SALUTE_AUTH_KEY")
+salute_ca_cert_path: Path | None = Field(default=None, alias="SALUTE_CA_CERT_PATH")
+salute_scope: str = Field(default="SALUTE_SPEECH_PERS", alias="SALUTE_SCOPE")
+```
+
+- `SALUTE_AUTH_KEY` — base64 Authorization Key from Sber Studio
+- `SALUTE_CA_CERT_PATH` — path to bundled Russian CA PEM (e.g., `./.certs/russian_trusted_root_ca.pem`)
+- `SALUTE_SCOPE` — OAuth scope (`SALUTE_SPEECH_PERS`)
+
+### Per-Job httpx Client
+
+Created in `_salute_transcribe_sync()`, passed to all helpers for connection reuse:
+
+```python
+verify = str(settings.salute_ca_cert_path) if settings.salute_ca_cert_path else True
+with httpx.Client(verify=verify, timeout=30.0) as client:
+    token = _get_salute_access_token(client)
+    file_id = _upload_salute_audio(client, token, audio_bytes, content_type)
+    task_id = _create_salute_task(client, token, file_id, language, model, encoding, sample_rate)
+    result_file_id = _poll_salute_task(client, token, task_id, job_uuid, on_progress)
+    raw_result = _download_salute_result(client, token, result_file_id)
+    return _build_document_from_salute_result(raw_result)
+```
+
+### Cert File
+
+Bundled at `cofee_backend/.certs/russian_trusted_root_ca.pem`. Downloaded from `https://gu-st.ru/content/Other/doc/russian_trusted_root_ca.cer`. Only the public root CA — no private keys or secrets.
+
+## Backend — Transcription Flow & Helpers
+
+### Function Structure (in `transcription/service.py`)
+
+```
+_get_salute_access_token(client)                              → str
+_upload_salute_audio(client, token, data, content_type)       → str (request_file_id)
+_create_salute_task(client, token, file_id, lang, model, ...) → str (task_id)
+_poll_salute_task(client, token, task_id, job_uuid, on_prog)  → str (response_file_id)
+_download_salute_result(client, token, response_file_id)      → dict
+_parse_salute_time(s: str) → float                            → "0.480s" → 0.48
+_build_document_from_salute_result(raw: dict) → Document
+_salute_transcribe_sync(*, local_file_path, language, model, job_id, on_progress) → Document
+async transcribe_with_salute_speech(storage, *, file_key, ...) → Document
+```
+
+### Upload
+
+Read local file as bytes, send raw binary to `/data:upload` with appropriate `Content-Type`. No ffmpeg conversion — SaluteSpeech natively supports MP3, WAV, OGG, FLAC.
+
+### Audio Encoding Detection
+
+```python
+SALUTE_ENCODING_MAP: dict[str, str] = {
+    ".mp3": "MP3",
+    ".wav": "PCM_S16LE",
+    ".ogg": "opus",
+    ".flac": "FLAC",
+}
+
+SALUTE_CONTENT_TYPE_MAP: dict[str, str] = {
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".ogg": "audio/ogg",
+    ".flac": "audio/flac",
+}
+```
+
+### Create Task
+
+JSON body with `request_file_id` + options:
+
+```json
+{
+    "options": {
+        "audio_encoding": "MP3",
+        "sample_rate": 16000,
+        "language": "ru-RU",
+        "model": "general",
+        "channels_count": 1,
+        "hypotheses_count": 1
+    },
+    "request_file_id": "<file_id>"
+}
+```
+
+Language mapping: `"ru"` → `"ru-RU"`, `"en"` → `"en-US"`, `None`/auto → `"ru-RU"` (default).
+
+`sample_rate` — extracted from probe data (the actor already runs `probe_media()` before transcription). Parse from the audio stream's `sample_rate` field, fallback to `16000`.
+
+### Poll Loop
+
+Check every 5 seconds. Three critical additions vs existing engines:
+
+1. **Cancellation check** — `_raise_if_job_cancelled(job_uuid)` each iteration
+2. **Progress reporting** — `on_progress` callback during poll so UI shows activity
+3. **Timeout** — `SALUTE_POLL_TIMEOUT_SECONDS = 600`
+
+```python
+def _poll_salute_task(client, token, task_id, job_uuid, on_progress):
+    start = time.monotonic()
+    while True:
+        if time.monotonic() - start > SALUTE_POLL_TIMEOUT_SECONDS:
+            raise TimeoutError(ERROR_SALUTE_TIMEOUT)
+        _raise_if_job_cancelled(job_uuid)
+
+        resp = client.get(f"{SALUTE_API_BASE}/task:get", params={"id": task_id}, ...)
+        status = resp.json()["result"]["status"]
+
+        if status == "DONE":
+            return resp.json()["result"]["response_file_id"]
+        if status == "ERROR":
+            raise RuntimeError(ERROR_SALUTE_TASK_FAILED.format(detail=...))
+
+        # Progress: estimate based on poll iteration
+        if on_progress:
+            elapsed = time.monotonic() - start
+            on_progress(min(elapsed / SALUTE_POLL_TIMEOUT_SECONDS * 100, 95.0))
+
+        time.sleep(SALUTE_POLL_INTERVAL_SECONDS)
+```
+
+### Download & Parse
+
+Download JSON from `/data:download`. Result structure:
+
+```json
+{
+    "results": [{
+        "text": "...",
+        "normalized_text": "...",
+        "start": "0.480s",
+        "end": "3.600s",
+        "word_alignments": [
+            {"word": "...", "start": "0.480s", "end": "0.840s"}
+        ]
+    }]
+}
+```
+
+Parse into `SaluteSpeechSegment`/`SaluteSpeechWord`, then `_make_document_from_segments()` → `Document`.
+
+### Constants
+
+```python
+SALUTE_POLL_INTERVAL_SECONDS = 5.0
+SALUTE_POLL_TIMEOUT_SECONDS = 600
+SALUTE_AUTH_URL = "https://ngw.devices.sberbank.ru:9443/api/v2/oauth"
+SALUTE_API_BASE = "https://smartspeech.sber.ru/rest/v1"
+SALUTE_TOKEN_REFRESH_MARGIN_SECONDS = 60
+
+ERROR_SALUTE_AUTH_FAILED = "Ошибка авторизации SaluteSpeech: {detail}"
+ERROR_SALUTE_UPLOAD_FAILED = "Ошибка загрузки файла в SaluteSpeech: {detail}"
+ERROR_SALUTE_TASK_FAILED = "Ошибка распознавания SaluteSpeech: {detail}"
+ERROR_SALUTE_TIMEOUT = "Превышено время ожидания распознавания SaluteSpeech"
+```
+
+## Backend — Schemas & DB Model
+
+### New Schemas (in `transcription/schemas.py`)
+
+```python
+class SaluteSpeechWord(Schema):
+    word: str
+    start: float
+    end: float
+
+class SaluteSpeechSegment(Schema):
+    text: str
+    start: float
+    end: float
+    words: list[SaluteSpeechWord] = []
+
+class SaluteSpeechResult(Schema):
+    text: str
+    segments: list[SaluteSpeechSegment]
+    language: str
+
+class SaluteSpeechParams(Schema):
+    file_path: str
+    language: str | None = None
+    model: str = "general"
+```
+
+### Engine Enum
+
+```python
+# transcription/schemas.py
+TranscriptionEngineEnum = Literal["LOCAL_WHISPER", "GOOGLE_SPEECH_CLOUD", "SALUTE_SPEECH"]
+```
+
+### Type Unions
+
+Extend `_make_document_from_segments()` and `DocumentBuilder.compute_segment_lines()` to accept `SaluteSpeechSegment` in their type unions.
+
+### DB Model
+
+No changes. `engine` column is `String(32)`, stores `"SALUTE_SPEECH"` as a plain string. No migration needed.
+
+## Backend — Task Dispatch
+
+### ENGINE_MAP (`tasks/service.py`)
+
+```python
+ENGINE_MAP: dict[str, str] = {
+    "whisper": "LOCAL_WHISPER",
+    "google": "GOOGLE_SPEECH_CLOUD",
+    "salutespeech": "SALUTE_SPEECH",
+}
+```
+
+### Task Schema (`tasks/schemas.py`)
+
+```python
+engine: Literal["whisper", "google", "salutespeech"] = "whisper"
+```
+
+### Actor Dispatch
+
+New `elif` branch in `transcription_generate_actor` after the Google branch:
+
+```python
+elif engine == "salutespeech":
+    document = _run_async(
+        transcribe_with_salute_speech(
+            storage,
+            file_key=file_key,
+            language=language,
+            model=model,
+            job_id=job_uuid,
+            on_progress=_on_whisper_progress,
+        )
+    )
+```
+
+### Direct Endpoint (optional, for testing)
+
+```python
+# transcription/router.py
+@router.post("/salute-speech/", response_model=Document)
+```
+
+## Frontend Changes
+
+### TranscriptionModal.tsx & TranscriptionSettingsStep.tsx
+
+Both files get identical changes (constants are duplicated in both):
+
+**Engine options:**
+```typescript
+const ENGINE_OPTIONS = [
+    { value: "whisper", label: "Whisper (локальный)" },
+    { value: "google", label: "Google Speech" },
+    { value: "salutespeech", label: "SaluteSpeech" },
+]
+```
+
+**Type:**
+```typescript
+engine: "whisper" | "google" | "salutespeech"
+```
+
+**Model options — split by engine:**
+```typescript
+const WHISPER_MODEL_OPTIONS = [
+    { value: "base", label: "Base" },
+    { value: "small", label: "Small" },
+    { value: "medium", label: "Medium" },
+    { value: "large", label: "Large" },
+]
+
+const SALUTE_MODEL_OPTIONS = [
+    { value: "general", label: "Общая" },
+    { value: "finance", label: "Финансы" },
+    { value: "medicine", label: "Медицина" },
+]
+```
+
+**Conditional model dropdown:**
+```typescript
+{(engine === "whisper" || engine === "salutespeech") && (
+    <Select
+        options={engine === "whisper" ? WHISPER_MODEL_OPTIONS : SALUTE_MODEL_OPTIONS}
+    />
+)}
+```
+
+**Model reset on engine change** — `useEffect` on engine field, reset model to `"base"` (whisper) or `"general"` (salutespeech).
+
+**Language options** — no changes. Existing `auto / ru / en` covers both SaluteSpeech languages. Mapping (`"ru"` → `"ru-RU"`) happens in backend.
+
+## Files Changed
+
+### Backend (8 files)
+| File | Change |
+|------|--------|
+| `infrastructure/settings.py` | Add 3 SaluteSpeech settings fields |
+| `transcription/schemas.py` | Add SaluteSpeech schema types, extend engine enum |
+| `transcription/service.py` | Add ~8 functions for SaluteSpeech flow |
+| `transcription/router.py` | Add optional `/salute-speech/` direct endpoint |
+| `tasks/schemas.py` | Extend engine Literal to include `"salutespeech"` |
+| `tasks/service.py` | Add `ENGINE_MAP` entry + `elif` dispatch branch |
+| `.certs/russian_trusted_root_ca.pem` | New file — bundled Russian CA cert |
+| `.env` | Add `SALUTE_AUTH_KEY`, `SALUTE_CA_CERT_PATH` |
+
+### Frontend (2 files)
+| File | Change |
+|------|--------|
+| `TranscriptionModal.tsx` | Add engine option, split model options, engine change effect |
+| `TranscriptionSettingsStep.tsx` | Same changes (duplicated constants) |
+
+## Error Handling
+
+- **Auth failure** (401/403) → `ERROR_SALUTE_AUTH_FAILED` with detail, job fails
+- **Upload failure** (4xx/5xx) → `ERROR_SALUTE_UPLOAD_FAILED`, job fails
+- **Task error** (status=ERROR) → `ERROR_SALUTE_TASK_FAILED`, job fails
+- **Poll timeout** (>600s) → `ERROR_SALUTE_TIMEOUT`, job fails
+- **Job cancelled** → `JobCancelledError` raised during poll loop, actor exits cleanly
+- **Partial failure** (upload ok, task creation fails) → no cleanup needed, uploaded files expire after 72h
+
+No retry logic for 4xx errors. Connect/timeout errors bubble up to Dramatiq (max_retries=0).
+
+## Not In Scope
+
+- Speaker diarization (available in API but not exposed)
+- Profanity filter (available but not exposed)
+- Hint words (available but not exposed)
+- Emotion detection (available but not exposed)
+- Sync recognition mode (only async implemented)
+- Additional languages beyond ru/en (kk-KZ, ky-KG, uz-UZ require special arrangement with Sber)
+
+These can be added later by extending `SaluteSpeechParams` and the task creation options.

docs/superpowers/specs/2026-04-04-subtitle-revision-workspace-design.md

@@ -0,0 +1,235 @@
+# Subtitle Revision Workspace Redesign
+
+## Summary
+
+Redesign the project subtitle-revision step at `/projects/[project_id]` into a more cohesive editorial workspace while staying inside the existing frontend design system.
+
+The current screen works functionally, but it feels assembled from separate widgets:
+
+- the stepper is visually louder than the actual editor
+- the player, transcription editor, and timeline feel disconnected
+- the transcription editor reads like a long raw form instead of a focused editing surface
+
+The approved direction is a stronger redesign with a balanced desktop split and an editorial/premium tone, while preserving the current tokens, component language, accent color, and overall product identity.
+
+## Goals
+
+- Make the subtitle-revision step feel like one composed workspace instead of stacked modules
+- Keep the player and transcription editor equally important on desktop
+- Improve hierarchy, spacing, and consistency without introducing a new visual identity
+- Reduce control noise and make dense editing UI easier to scan
+- Preserve all existing behavior and workflow transitions
+
+## Non-Goals
+
+- No new global design tokens, typography system, or brand palette
+- No workflow changes to the wizard sequence
+- No API changes
+- No functional rewrite of the timeline or transcription editor logic
+- No cross-app redesign outside the stepper and subtitle-revision workspace chrome
+
+## Constraints
+
+- Use the current SCSS module approach and existing CSS variables
+- Keep user-facing copy in Russian
+- Stay within the existing app design system and Radix/SCSS visual language
+- Avoid turning the interface into a dense technical studio
+- Preserve the current balanced desktop split rather than making the player or editor dominant
+
+## Target Files
+
+- `cofee_frontend/src/shared/ui/Stepper/Stepper.module.scss`
+- `cofee_frontend/src/widgets/ProjectWizard/ProjectWizard.module.scss`
+- `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.tsx`
+- `cofee_frontend/src/features/project/SubtitleRevisionStep/SubtitleRevisionStep.module.scss`
+- `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.tsx`
+- `cofee_frontend/src/features/project/TranscriptionEditor/TranscriptionEditor.module.scss`
+- `cofee_frontend/src/widgets/TimelinePanel/TimelinePanel.module.scss`
+
+## Existing Problems
+
+### 1. Weak visual hierarchy
+
+The page gives too much emphasis to the stepper, while the actual editor workspace lacks a strong shared frame.
+
+### 2. Fragmented composition
+
+The player area, editor area, timeline, and footer feel like separate containers placed one after another instead of one coordinated tool surface.
+
+### 3. Form-heavy transcription editor
+
+Each segment is structurally correct, but the card styling, spacing, and metadata layout make the editor feel operationally noisy.
+
+### 4. Inconsistent control density
+
+The timeline toolbar, transcript actions, and shell spacing do not share a unified rhythm, which makes the screen feel less premium.
+
+## Design Direction
+
+### Overall Tone
+
+Use an editorial/premium interpretation of the current design system:
+
+- restrained accent usage
+- clearer spacing rhythm
+- softer but more intentional panel boundaries
+- quieter metadata treatment
+- better grouping of related controls
+
+The redesign should feel more composed, not more decorative.
+
+### Desktop Layout
+
+The subtitle-revision step becomes a single workspace shell with three coordinated layers:
+
+1. A quieter progress area at the top
+2. A two-panel main canvas with a balanced split
+3. A docked timeline rail and stable footer inside the same shell
+
+The player remains on the left and the transcription editor remains on the right, both with equal visual weight.
+
+### Responsive Layout
+
+- Desktop: balanced two-column split
+- Tablet: same structure with tighter spacing and slightly reduced panel chrome
+- Mobile: vertical stack in this order: player, editor, timeline, footer
+
+## Component Changes
+
+### Stepper
+
+The stepper remains horizontally scrollable, but it should become less dominant:
+
+- reduce visual heaviness of active/completed states
+- rely more on subtle surface contrast and typography than on a saturated filled pill
+- improve blending with the page shell below
+- preserve clear progress indication and current auto-centering behavior
+
+The stepper should read as workflow context rather than the primary visual element.
+
+### Wizard Shell
+
+The project wizard content area should gain a more intentional outer structure:
+
+- introduce a softer page canvas treatment
+- give the active step a single large rounded workspace surface
+- align internal padding and spacing across the player, editor, timeline, and footer
+- keep overflow behavior stable so the editor can scroll without destabilizing the whole page
+
+### Subtitle Revision Step
+
+The subtitle-revision step should feel like one editing environment:
+
+- add compact panel headers for the player and the editor
+- visually connect the main grid, timeline rail, and footer as one system
+- keep the video area dark and focused, but frame it with better surrounding chrome
+- keep the timeline dock clearly separated without looking appended
+
+Small structural markup changes are allowed where they improve grouping and semantics, but existing logic should remain intact.
+
+### Transcription Editor
+
+The transcription editor needs the strongest visual cleanup.
+
+#### Header
+
+- add a more informative but still compact header treatment
+- support a small status cue for auto-save state if useful, but do not introduce noisy persistent status messaging
+
+#### Segment Cards
+
+Each segment should read as an editable text block with metadata, not as a generic form section:
+
+- cleaner top row with timing metadata grouped on one side and actions on the other
+- timing controls should read like refined chips/fields instead of raw mini-inputs
+- reduce reliance on uppercase label styling where it hurts readability
+- increase whitespace and breathing room between segment cards
+- make highlight/focus states feel intentional and consistent with the existing accent
+
+#### Text Editing Area
+
+- textarea should feel more like an editing surface than a default input
+- improve padding, line-height, and focus treatment
+- maintain support for inline segment splitting where available
+
+#### Add Segment Action
+
+- keep the action at the bottom, but visually connect it to the editor system
+- use an understated treatment consistent with the workspace instead of a generic dashed box
+
+### Timeline Panel
+
+The timeline should remain functionally the same, but its chrome should be refined to match the new shell:
+
+- calmer toolbar styling
+- more consistent spacing and border behavior
+- cleaner label column and zoom controls
+- visual integration with the docked lower rail
+
+No new timeline interactions are required.
+
+## Interaction and Behavior
+
+### Preserve
+
+- current wizard navigation behavior
+- current media player behavior
+- current transcription loading and auto-save behavior
+- current segment split/remove/add behavior
+- current timeline interactions and frame extraction actions
+- current footer button actions
+
+### Improve Visually
+
+- focus states
+- hover states
+- selected/highlighted segment appearance
+- empty/placeholder states inside player/editor panels
+
+## Accessibility
+
+- Maintain or improve contrast against current token values
+- Keep button targets and input hit areas usable at reduced viewport widths
+- Preserve semantic structure for headings, buttons, and fields
+- Do not rely on color alone to communicate active/editing state
+
+## Implementation Notes
+
+- Prefer CSS and layout changes over component rewrites
+- Keep edits localized to the subtitle-revision workspace and shared stepper chrome
+- If markup changes are introduced in `TranscriptionEditor.tsx` or `SubtitleRevisionStep.tsx`, keep them minimal and presentation-driven
+- Reuse existing spacing, border radius, and color tokens from the current system
+- Avoid introducing one-off visual rules that imply a new design language
+
+## Verification
+
+### Required Checks
+
+- `cd cofee_frontend && bunx tsc --noEmit`
+
+### Manual Browser Verification
+
+Check the target route in Chrome after implementation:
+
+- `http://localhost:3000/projects/83eb1396-8217-4ceb-ae32-b3b63cd01982`
+
+Verify:
+
+- the stepper is calmer but still readable
+- the workspace reads as one composed shell
+- the desktop split remains balanced
+- the transcription editor cards are easier to scan
+- the timeline feels docked to the workspace
+- footer actions remain stable and visually integrated
+- the layout still behaves correctly at a narrower viewport
+
+## Risks
+
+- Over-styling the stepper could reduce progress clarity
+- Styling changes around the Vidstack player may accidentally clip controls
+- Tightening the editor chrome too aggressively could reduce perceived affordance on timing fields and actions
+- Timeline integration work could introduce overflow regressions if container boundaries are not kept explicit
+
+## Rollout Decision
+
+Proceed as a focused UI redesign of the subtitle-revision workspace only, using the existing design system and preserving all current functionality.

docs/superpowers/specs/2026-04-05-codex-team-policy-fixes-design.md

@@ -0,0 +1,33 @@
+# Codex Team Policy Fixes
+
+Date: 2026-04-05
+
+## Scope
+- Fix the `.codex/memories` path convention so the shared rule and per-agent instructions use the same agent IDs.
+- Tighten the team-first wording so non-trivial repo work consults the team by default.
+- Remove role skill assignments that depend on unavailable review infrastructure.
+
+## Approved Approach
+Use a minimal patch:
+- Standardize memory paths on the actual Codex agent IDs, which use underscores.
+- Change the consultation policy from "before deep analysis" to "before any non-trivial repo task", while keeping a narrow exception for purely mechanical actions and explicit user opt-outs.
+- Replace non-executable `requesting-code-review` entries with executable installed skills only.
+
+## Intended Changes
+### Memory paths
+- Update `.codex/agent-team.md` to state that memories live under `.codex/memories/<agent_id>/`.
+- Update every `.codex/agents/*.toml` file to reference underscore-based memory directories matching the agent names.
+- Update `.codex/memories/README.md` examples to use `<agent_id>` wording.
+
+### Team-first policy
+- Update `AGENTS.md` and `.codex/agent-team.md` to require team consultation before any non-trivial repo task.
+- Keep a narrow local-only exception for purely mechanical actions that cannot materially change behavior, architecture, or risk.
+
+### Skill map
+- Remove `requesting-code-review` from roles because the required `superpowers:code-reviewer` subagent is not available in this workspace.
+- Keep the map limited to executable skills already installed in the current environment.
+
+## Success Criteria
+- Shared policy and per-agent instructions point to the same memory paths.
+- The root guidance no longer leaves "deep analysis" as the main threshold for consulting the team.
+- The skill map contains only practically usable role assignments for this environment.

docs/superpowers/specs/2026-04-06-preset-grid-demo.html

@@ -0,0 +1,625 @@
+<!DOCTYPE html>
+<html lang="ru">
+<head>
+	<meta charset="UTF-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0">
+	<title>Subtitle Preset Grid Redesign Demo</title>
+	<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Lobster&display=swap" rel="stylesheet">
+	<style>
+		/* Catppuccin Mocha - Matching the actual project colors */
+		:root {
+			/* Backgrounds */
+			--bg-canvas: #11111b;
+			--bg-default: #1e1e2e;
+			--bg-surface: #313244;
+			--bg-hover: #45475a;
+			--bg-default-invert: #eff1f5;
+
+			/* Text */
+			--text-primary: #cdd6f4;
+			--text-secondary: #bac2de;
+			--text-tertiary: #9399b2;
+
+			/* Borders */
+			--border-default: #45475a;
+			--border-subtle: #313244;
+
+			/* Purples (accent) */
+			--purple-400: #cba6f7;
+			--purple-500: #d9bcfa;
+			--purple-600: #e4cffc;
+			--purple-700: #eddfff;
+			--purple-300: #6a5a93;
+			--purple-200: #4b4168;
+			--purple-100: #362f4c;
+			--purple-50: #2b253b;
+
+			/* Shadows */
+			--shadow-sm: 0 1px 2px rgba(17, 17, 27, 0.5);
+			--shadow-md: 0 4px 6px -1px rgba(17, 17, 27, 0.58), 0 24px 48px -12px rgba(17, 17, 27, 0.52);
+			--shadow-lg: 0 10px 15px -3px rgba(17, 17, 27, 0.6), 0 40px 80px -20px rgba(17, 17, 27, 0.7);
+
+			/* Accent glow */
+			--accent-shadow: rgba(203, 166, 247, 0.22);
+			--accent-shadow-hover: rgba(203, 166, 247, 0.3);
+
+			/* Preview background */
+			--preview-bg: #0c0a1a;
+		}
+
+		* {
+			margin: 0;
+			padding: 0;
+			box-sizing: border-box;
+		}
+
+		body {
+			font-family: 'Inter', sans-serif;
+			background: var(--bg-canvas);
+			color: var(--text-primary);
+			padding: 40px 20px;
+			min-height: 100vh;
+		}
+
+		body::before {
+			content: "";
+			position: fixed;
+			inset: 0;
+			background: radial-gradient(circle at 50% 0%, rgba(203, 166, 247, 0.08) 0%, transparent 55%);
+			pointer-events: none;
+			z-index: -1;
+		}
+
+		.container {
+			max-width: 1400px;
+			margin: 0 auto;
+		}
+
+		h1 {
+			font-size: 24px;
+			font-weight: 600;
+			margin-bottom: 32px;
+			color: var(--text-primary);
+		}
+
+		/* Controls */
+		.controls {
+			display: flex;
+			gap: 16px;
+			margin-bottom: 32px;
+			flex-wrap: wrap;
+		}
+
+		.control-group {
+			display: flex;
+			flex-direction: column;
+			gap: 8px;
+		}
+
+		.control-group label {
+			font-size: 11px;
+			color: var(--text-tertiary);
+			text-transform: uppercase;
+			letter-spacing: 0.8px;
+			font-weight: 500;
+		}
+
+		.aspect-buttons {
+			display: flex;
+			gap: 8px;
+		}
+
+		.aspect-btn {
+			padding: 8px 14px;
+			background: var(--bg-surface);
+			border: 1px solid var(--border-default);
+			color: var(--text-secondary);
+			border-radius: 8px;
+			cursor: pointer;
+			font-size: 13px;
+			font-weight: 500;
+			transition: all 0.15s ease;
+		}
+
+		.aspect-btn:hover {
+			background: var(--bg-hover);
+			border-color: var(--purple-400);
+			color: var(--text-primary);
+		}
+
+		.aspect-btn.active {
+			background: var(--purple-100);
+			border-color: var(--purple-400);
+			color: var(--purple-400);
+		}
+
+		/* Grid */
+		.preset-grid {
+			display: grid;
+			grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+			gap: 20px;
+			margin-bottom: 48px;
+		}
+
+		/* Preset Card */
+		.preset-card {
+			position: relative;
+			border-radius: 12px;
+			overflow: hidden;
+			background: var(--bg-default);
+			border: 1px solid var(--border-subtle);
+			cursor: pointer;
+			transition: all 0.2s cubic-bezier(0.2, 0.8, 0.2, 1);
+			display: flex;
+			flex-direction: column;
+		}
+
+		.preset-card:hover {
+			border-color: var(--purple-400);
+			transform: translateY(-2px);
+			box-shadow: var(--shadow-md);
+		}
+
+		.preset-card.selected {
+			border-color: var(--purple-400);
+			box-shadow: 
+				0 0 0 1px var(--purple-400),
+				0 0 20px rgba(203, 166, 247, 0.25),
+				var(--shadow-lg);
+		}
+
+		.preset-card.selected::before {
+			content: "";
+			position: absolute;
+			inset: -1px;
+			border-radius: 12px;
+			padding: 1px;
+			background: linear-gradient(135deg, var(--purple-400), var(--purple-600));
+			-webkit-mask: 
+				linear-gradient(#fff 0 0) content-box, 
+				linear-gradient(#fff 0 0);
+			-webkit-mask-composite: xor;
+			mask-composite: exclude;
+			pointer-events: none;
+		}
+
+		/* Preview Area */
+		.preview-area {
+			position: relative;
+			aspect-ratio: 16 / 9;
+			background: var(--preview-bg);
+			overflow: hidden;
+			transition: aspect-ratio 0.3s ease;
+			display: flex;
+			align-items: center;
+			justify-content: center;
+		}
+
+		.preview-area.vertical {
+			aspect-ratio: 9 / 16;
+		}
+
+		.preview-area.square {
+			aspect-ratio: 1 / 1;
+		}
+
+		.preview-area.instagram {
+			aspect-ratio: 4 / 5;
+		}
+
+		.preview-text {
+			text-align: center;
+			padding: 16px;
+			font-size: 28px;
+			line-height: 1.4;
+			z-index: 1;
+		}
+
+		.preview-text .highlight {
+			font-weight: 700;
+		}
+
+		/* Card Footer */
+		.card-footer {
+			padding: 14px 16px;
+			background: linear-gradient(to top, var(--bg-surface), var(--bg-default));
+			border-top: 1px solid var(--border-subtle);
+		}
+
+		.preset-name {
+			font-size: 14px;
+			font-weight: 600;
+			color: var(--text-primary);
+			margin-bottom: 6px;
+			display: flex;
+			align-items: center;
+			gap: 8px;
+		}
+
+		.system-badge {
+			font-size: 10px;
+			font-weight: 600;
+			text-transform: uppercase;
+			letter-spacing: 0.5px;
+			padding: 2px 8px;
+			background: var(--purple-100);
+			color: var(--purple-400);
+			border-radius: 4px;
+		}
+
+		.style-chars {
+			font-size: 12px;
+			color: var(--text-tertiary);
+			display: flex;
+			align-items: center;
+			gap: 8px;
+		}
+
+		.color-dot {
+			width: 8px;
+			height: 8px;
+			border-radius: 50%;
+			display: inline-block;
+			box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.1);
+		}
+
+		/* Create New Card */
+		.create-card {
+			display: flex;
+			flex-direction: column;
+			align-items: center;
+			justify-content: center;
+			gap: 12px;
+			aspect-ratio: 16 / 9;
+			background: transparent;
+			border: 2px dashed var(--border-default);
+			border-radius: 12px;
+			cursor: pointer;
+			transition: all 0.2s ease;
+			color: var(--text-tertiary);
+			min-height: 100%;
+		}
+
+		.create-card:hover {
+			border-color: var(--purple-400);
+			background: rgba(203, 166, 247, 0.05);
+			color: var(--text-secondary);
+		}
+
+		.create-card svg {
+			width: 32px;
+			height: 32px;
+			opacity: 0.6;
+		}
+
+		/* Skeleton Loading - Improved */
+		.skeleton-card {
+			border-radius: 12px;
+			overflow: hidden;
+			background: var(--bg-default);
+			border: 1px solid var(--border-subtle);
+			display: flex;
+			flex-direction: column;
+		}
+
+		.skeleton-preview {
+			aspect-ratio: 16 / 9;
+			background: var(--bg-surface);
+			position: relative;
+			overflow: hidden;
+		}
+
+		.skeleton-preview::after {
+			content: "";
+			position: absolute;
+			inset: 0;
+			background: linear-gradient(
+				90deg,
+				transparent 0%,
+				rgba(203, 166, 247, 0.08) 50%,
+				transparent 100%
+			);
+			animation: shimmer 1.5s infinite;
+		}
+
+		@keyframes shimmer {
+			0% { transform: translateX(-100%); }
+			100% { transform: translateX(100%); }
+		}
+
+		.skeleton-footer {
+			padding: 14px 16px;
+			background: linear-gradient(to top, var(--bg-surface), var(--bg-default));
+			border-top: 1px solid var(--border-subtle);
+			display: flex;
+			flex-direction: column;
+			gap: 10px;
+		}
+
+		.skeleton-line {
+			height: 14px;
+			background: var(--bg-hover);
+			border-radius: 4px;
+			width: 60%;
+			position: relative;
+			overflow: hidden;
+		}
+
+		.skeleton-line.short {
+			width: 40%;
+			height: 10px;
+		}
+
+		.skeleton-line::after {
+			content: "";
+			position: absolute;
+			inset: 0;
+			background: linear-gradient(
+				90deg,
+				transparent 0%,
+				rgba(203, 166, 247, 0.06) 50%,
+				transparent 100%
+			);
+			animation: shimmer 1.5s infinite;
+		}
+
+		/* Section Label */
+		.section-label {
+			font-size: 11px;
+			color: var(--text-tertiary);
+			text-transform: uppercase;
+			letter-spacing: 0.8px;
+			margin-bottom: 12px;
+			font-weight: 500;
+		}
+
+		/* Selected indicator */
+		.selected-indicator {
+			position: absolute;
+			top: 8px;
+			right: 8px;
+			width: 20px;
+			height: 20px;
+			background: var(--purple-400);
+			border-radius: 50%;
+			display: flex;
+			align-items: center;
+			justify-content: center;
+			box-shadow: 0 2px 8px rgba(203, 166, 247, 0.4);
+		}
+
+		.selected-indicator svg {
+			width: 12px;
+			height: 12px;
+			color: var(--bg-canvas);
+		}
+
+		/* Responsive */
+		@media (max-width: 768px) {
+			.preset-grid {
+				grid-template-columns: repeat(2, 1fr);
+				gap: 12px;
+			}
+		}
+	</style>
+</head>
+<body>
+	<div class="container">
+		<h1>Выбор пресета субтитров</h1>
+
+		<!-- Controls -->
+		<div class="controls">
+			<div class="control-group">
+				<label>Аспектное соотношение видео</label>
+				<div class="aspect-buttons">
+					<button class="aspect-btn active" data-ratio="16:9">16:9 (Широкое)</button>
+					<button class="aspect-btn" data-ratio="9:16">9:16 (Вертикальное)</button>
+					<button class="aspect-btn" data-ratio="1:1">1:1 (Квадрат)</button>
+					<button class="aspect-btn" data-ratio="4:5">4:5 (Instagram)</button>
+				</div>
+			</div>
+		</div>
+
+		<!-- Section: Ready Presets -->
+		<div class="section-label">Пример: готовые пресеты</div>
+		<div class="preset-grid" id="presetGrid">
+			<!-- Card 1: Классические -->
+			<div class="preset-card selected" data-preset="classic">
+				<div class="preview-area">
+					<div class="preview-text" style="font-family: 'Lobster', cursive; color: #ffffff;">
+						Пример <span class="highlight" style="color: #FFD700;">субтитров</span>
+					</div>
+					<div class="selected-indicator">
+						<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
+							<polyline points="20 6 9 17 4 12"></polyline>
+						</svg>
+					</div>
+				</div>
+				<div class="card-footer">
+					<div class="preset-name">
+						Классические
+						<span class="system-badge">Системный</span>
+					</div>
+					<div class="style-chars">
+						Lobster
+						<span style="color: var(--border-default);">·</span>
+						<span class="color-dot" style="background: #FFD700;"></span>
+						<span style="color: #FFD700;">Золотой</span>
+					</div>
+				</div>
+			</div>
+
+			<!-- Card 2: Неон -->
+			<div class="preset-card" data-preset="neon">
+				<div class="preview-area">
+					<div class="preview-text" style="font-family: 'Inter', sans-serif; font-weight: 700; color: #ffffff; text-shadow: 0 0 10px #00ffff, 0 0 20px #00ffff;">
+						Пример <span class="highlight" style="color: #00ffff;">субтитров</span>
+					</div>
+				</div>
+				<div class="card-footer">
+					<div class="preset-name">
+						Неон
+						<span class="system-badge">Системный</span>
+					</div>
+					<div class="style-chars">
+						Inter Bold
+						<span style="color: var(--border-default);">·</span>
+						<span class="color-dot" style="background: #00ffff; box-shadow: 0 0 6px #00ffff;"></span>
+						<span style="color: #00ffff;">Неоновый</span>
+					</div>
+				</div>
+			</div>
+
+			<!-- Card 3: Минимализм -->
+			<div class="preset-card" data-preset="minimal">
+				<div class="preview-area">
+					<div class="preview-text" style="font-family: 'Inter', sans-serif; font-weight: 400; color: #e0e0e0; font-size: 24px;">
+						Пример <span class="highlight" style="color: #ffffff; font-weight: 500;">субтитров</span>
+					</div>
+				</div>
+				<div class="card-footer">
+					<div class="preset-name">
+						Минимализм
+						<span class="system-badge">Системный</span>
+					</div>
+					<div class="style-chars">
+						Inter Regular
+						<span style="color: var(--border-default);">·</span>
+						<span class="color-dot" style="background: #ffffff;"></span>
+						<span style="color: #ffffff;">Белый</span>
+					</div>
+				</div>
+			</div>
+
+			<!-- Card 4: Жирный -->
+			<div class="preset-card" data-preset="bold">
+				<div class="preview-area">
+					<div class="preview-text" style="font-family: 'Inter', sans-serif; font-weight: 900; color: #ffffff; -webkit-text-stroke: 2px #000000; font-size: 32px;">
+						Пример <span class="highlight" style="color: #ff006e;">субтитров</span>
+					</div>
+				</div>
+				<div class="card-footer">
+					<div class="preset-name">
+						Жирный
+						<span class="system-badge">Системный</span>
+					</div>
+					<div class="style-chars">
+						Inter Black
+						<span style="color: var(--border-default);">·</span>
+						<span class="color-dot" style="background: #ff006e;"></span>
+						<span style="color: #ff006e;">Розовый</span>
+					</div>
+				</div>
+			</div>
+
+			<!-- Create New Card -->
+			<div class="create-card">
+				<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+					<line x1="12" y1="5" x2="12" y2="19"></line>
+					<line x1="5" y1="12" x2="19" y2="12"></line>
+				</svg>
+				<span style="font-size: 14px; font-weight: 500;">Создать пресет</span>
+			</div>
+		</div>
+
+		<!-- Section: Loading State -->
+		<div class="section-label">Пример: состояние загрузки</div>
+		<div class="preset-grid">
+			<div class="skeleton-card">
+				<div class="skeleton-preview"></div>
+				<div class="skeleton-footer">
+					<div class="skeleton-line"></div>
+					<div class="skeleton-line short"></div>
+				</div>
+			</div>
+			<div class="skeleton-card">
+				<div class="skeleton-preview"></div>
+				<div class="skeleton-footer">
+					<div class="skeleton-line"></div>
+					<div class="skeleton-line short"></div>
+				</div>
+			</div>
+			<div class="skeleton-card">
+				<div class="skeleton-preview"></div>
+				<div class="skeleton-footer">
+					<div class="skeleton-line"></div>
+					<div class="skeleton-line short"></div>
+				</div>
+			</div>
+			<div class="skeleton-card">
+				<div class="skeleton-preview"></div>
+				<div class="skeleton-footer">
+					<div class="skeleton-line"></div>
+					<div class="skeleton-line short"></div>
+				</div>
+			</div>
+		</div>
+	</div>
+
+	<script>
+		// Aspect ratio switching
+		const aspectButtons = document.querySelectorAll('.aspect-btn');
+		const previewAreas = document.querySelectorAll('.preview-area');
+		const skeletonPreviews = document.querySelectorAll('.skeleton-preview');
+		const createCard = document.querySelector('.create-card');
+
+		aspectButtons.forEach(btn => {
+			btn.addEventListener('click', () => {
+				// Update active button
+				aspectButtons.forEach(b => b.classList.remove('active'));
+				btn.classList.add('active');
+
+				const ratio = btn.dataset.ratio;
+
+				// Update preview areas
+				previewAreas.forEach(preview => {
+					preview.classList.remove('vertical', 'square', 'instagram');
+					if (ratio === '9:16') preview.classList.add('vertical');
+					if (ratio === '1:1') preview.classList.add('square');
+					if (ratio === '4:5') preview.classList.add('instagram');
+				});
+
+				// Update skeleton previews
+				skeletonPreviews.forEach(preview => {
+					if (ratio === '9:16') preview.style.aspectRatio = '9 / 16';
+					else if (ratio === '1:1') preview.style.aspectRatio = '1 / 1';
+					else if (ratio === '4:5') preview.style.aspectRatio = '4 / 5';
+					else preview.style.aspectRatio = '16 / 9';
+				});
+
+				// Update create card
+				if (ratio === '9:16') createCard.style.aspectRatio = '9 / 16';
+				else if (ratio === '1:1') createCard.style.aspectRatio = '1 / 1';
+				else if (ratio === '4:5') createCard.style.aspectRatio = '4 / 5';
+				else createCard.style.aspectRatio = '16 / 9';
+			});
+		});
+
+		// Card selection
+		const presetCards = document.querySelectorAll('.preset-card');
+		presetCards.forEach(card => {
+			card.addEventListener('click', () => {
+				presetCards.forEach(c => {
+					c.classList.remove('selected');
+					const indicator = c.querySelector('.selected-indicator');
+					if (indicator) indicator.remove();
+				});
+				card.classList.add('selected');
+
+				// Add checkmark indicator
+				const preview = card.querySelector('.preview-area');
+				if (!preview.querySelector('.selected-indicator')) {
+					const indicator = document.createElement('div');
+					indicator.className = 'selected-indicator';
+					indicator.innerHTML = `
+						<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3">
+							<polyline points="20 6 9 17 4 12"></polyline>
+						</svg>
+					`;
+					preview.appendChild(indicator);
+				}
+			});
+		});
+	</script>
+</body>
+</html>

docs/superpowers/specs/2026-04-06-subtitle-preset-grid-redesign.md

@@ -0,0 +1,212 @@
+# Subtitle Preset Grid Redesign - Design Document
+
+**Date:** 2026-04-06  
+**Scope:** Redesign preset preview cards in Caption Settings step to match uploaded video aspect ratio with modern visual refresh
+
+---
+
+## Overview
+
+Redesign the subtitle preset selection grid to:
+1. Display preset previews with the **same aspect ratio as the uploaded video**
+2. Apply a **modern visual refresh** consistent with the app's design language
+3. Show **style characteristics** (font, colors) as subtle hints
+4. Maintain **responsive layout** across screen sizes
+
+---
+
+## Core Functionality
+
+### Dynamic Aspect Ratio
+
+**Data Flow:**
+1. Fetch video metadata via `GET /api/media/mediafiles/{media_file_id}/` using `primaryFileId` from WizardContext
+2. Extract `width` and `height` from `MediaFileRead` response
+3. Calculate aspect ratio: `width / height`
+4. Apply as CSS `aspect-ratio` to preset cards via inline style or CSS variable
+5. Handle loading state while fetching metadata
+6. Fallback to 16:9 if no video is uploaded or API error occurs
+
+**Implementation Notes:**
+- Store aspect ratio in WizardContext alongside other video metadata
+- Update ratio when `primaryFileId` changes
+- Cards use container queries for responsive sizing
+
+---
+
+## Visual Design (5 Pillars Applied)
+
+### 1. Typography with Character
+- Keep existing font system (consistent with app)
+- Style name: `font-weight: 500`, `font-size: 14px`
+- Characteristic labels: `font-size: 12px`, muted color (`--gray-10`)
+
+### 2. Committed Color & Theme
+- Uses **Catppuccin Mocha** palette matching the project:
+  - Canvas: `--bg-canvas: #11111b`
+  - Cards: `--bg-default: #1e1e2e`
+  - Surfaces: `--bg-surface: #313244`
+  - Borders: `--border-default: #45475a`, `--border-subtle: #313244`
+  - Text: `--text-primary: #cdd6f4`, `--text-secondary: #bac2de`, `--text-tertiary: #9399b2`
+- Selected state: purple accent (`--purple-400: #cba6f7`) with glow shadow
+- Card hover: border transitions to purple accent
+- System badge: purple-100 background with purple-400 text
+- Checkmark indicator on selected card (top-right corner)
+
+### 3. Purposeful Motion
+- Cards fade in with staggered animation (50ms delay per card)
+- Smooth border-color transition on hover (150ms ease)
+- Selection change: immediate border color change
+- Loading skeleton: shimmer animation
+
+### 4. Brave Spatial Composition
+- CSS Grid with `auto-fill` and `minmax(200px, 1fr)`
+- Consistent 16px gap between cards
+- Cards maintain video aspect ratio without stretching
+- Responsive: more columns on wide screens, fewer on narrow
+
+### 5. Atmosphere & Depth
+- Card background: subtle gradient overlay for depth
+- Selected card: elevated with `box-shadow` + accent glow
+- Dark preview background (`#0c0a1a`) preserved from existing StylePreview
+- Rounded corners: `border-radius: 12px`
+
+---
+
+## Component Structure
+
+### PresetCard
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│     [StylePreview Component]         │  ← Dynamic aspect-ratio
+│     "Пример субтитров"               │     based on video
+│                                      │
+├──────────────────────────────────────┤
+│ Style Name              [Системный]  │  ← Footer
+│ Lobster · Yellow accent              │  ← Characteristics (subtle)
+└──────────────────────────────────────┘
+```
+
+**Props:**
+- `preset: CaptionPresetRead`
+- `isSelected: boolean`
+- `aspectRatio: number` (width/height, e.g., 1.777 for 16:9)
+- `onSelect: () => void`
+- `onEdit: () => void`
+- `onDelete: () => void`
+
+### StylePreview Updates
+
+**New Props:**
+- `aspectRatio?: number` - overrides default 9/16
+
+**Behavior:**
+- Uses passed `aspectRatio` for container sizing
+- Falls back to 9/16 if not provided
+- Maintains all existing text styling logic
+
+### PresetGrid Updates
+
+**New Behavior:**
+- Fetches video metadata via `useVideoMetadata()` hook
+- Passes `aspectRatio` to all PresetCard children
+- Shows skeleton loading state while fetching
+- Responsive grid layout
+
+---
+
+## Style Characteristics Display
+
+Each card footer shows:
+- **Font family** (e.g., "Lobster", "Inter") - extracted from `preset.style_config.text.font_family`
+- **Accent color** - small color dot + name if distinct from default
+- Hidden on cards narrower than 180px (responsive)
+
+**Format:**
+```
+{font_family} · {accent_color_name}
+```
+
+Example: `Lobster · Желтый` or `Inter · Неоновый`
+
+---
+
+## Loading State
+
+**Skeleton Card:**
+- Same aspect ratio as target (default 16:9 while loading)
+- Shimmer animation on preview area
+- Gray placeholder for text
+- 4-6 skeleton cards shown while loading
+
+---
+
+## Responsive Behavior
+
+| Screen Width | Grid Columns | Card Min Width |
+|--------------|--------------|----------------|
+| < 480px      | 2            | 140px          |
+| 480-768px    | 3            | 160px          |
+| 768-1200px   | 4            | 180px          |
+| > 1200px     | 5-6          | 200px          |
+
+---
+
+## API Integration
+
+### New Hook: `useVideoMetadata`
+
+```typescript
+function useVideoMetadata(fileId: string | null) {
+  return api.useQuery(
+    "get",
+    "/api/media/mediafiles/{media_file_id}/",
+    { params: { path: { media_file_id: fileId ?? "" } } },
+    { enabled: !!fileId }
+  )
+}
+```
+
+### Aspect Ratio Calculation
+
+```typescript
+const aspectRatio = useMemo(() => {
+  if (!mediaFile?.width || !mediaFile?.height) return 16 / 9
+  return mediaFile.width / mediaFile.height
+}, [mediaFile])
+```
+
+---
+
+## Edge Cases
+
+1. **No video uploaded:** Fall back to 16:9 aspect ratio
+2. **Video metadata unavailable:** Show error toast, fall back to 16:9
+3. **Very wide video (>21:9):** Cap max card width to prevent overflow
+4. **Very tall video (9:16+):** Limit max height, allow scrolling if needed
+5. **No presets:** Show empty state with "Создать пресет" card only
+
+---
+
+## Files Modified
+
+1. `src/features/project/CaptionSettingsStep/PresetGrid.tsx` - Grid logic, aspect ratio distribution
+2. `src/features/project/CaptionSettingsStep/PresetGrid.module.scss` - Grid styles, responsive layout
+3. `src/features/project/CaptionSettingsStep/StylePreview.tsx` - Accept aspect ratio prop
+4. `src/features/project/CaptionSettingsStep/StylePreview.module.scss` - Dynamic sizing
+5. `src/features/project/CaptionSettingsStep/useVideoMetadata.ts` - New hook (or inline in PresetGrid)
+
+---
+
+## Acceptance Criteria
+
+- [ ] Preset cards display with uploaded video's aspect ratio
+- [ ] Grid is responsive and works on mobile/desktop
+- [ ] Loading state shows skeleton cards
+- [ ] Style characteristics (font, color) visible on cards
+- [ ] Selected state clearly visible with accent border
+- [ ] Hover effects smooth and purposeful
+- [ ] Fallback to 16:9 when no video available
+- [ ] All existing functionality preserved (select, edit, delete, create)

opencode.jsonc

@@ -0,0 +1,128 @@
+{
+	"$schema": "https://opencode.ai/config.json",
+
+	// Default this repo to GPT-5.4 with high reasoning effort.
+	"model": "openai/gpt-5.4",
+	"small_model": "anthropic/claude-haiku-4-5",
+	"default_agent": "build",
+
+	"provider": {
+		"openai": {
+			"models": {
+				"gpt-5.4": {
+					"options": {
+						"reasoningEffort": "high"
+					}
+				}
+			}
+		}
+	},
+
+	// OpenCode merges this with the global config. This file narrows the repo to
+	// the Coffee Project instruction stack and MCP roster.
+	"instructions": [
+		"./.opencode/merged-instructions.md",
+		"./AGENTS.md",
+		"./.codex/agent-team.md",
+		"./.codex/agent-skills.md",
+		"./CLAUDE.md",
+		"./cofee_frontend/AGENTS.md",
+		"./cofee_frontend/CLAUDE.md",
+		"./cofee_backend/AGENTS.md",
+		"./cofee_backend/CLAUDE.md",
+		"./remotion_service/AGENTS.md",
+		"./remotion_service/CLAUDE.md"
+	],
+
+	// Re-enable delegation and docs lookup for this repo, while keeping the MCP
+	// surface intentionally small and explicit.
+	"permission": {
+		"task": "allow",
+		"context7_*": "allow",
+		"web-search_*": "ask",
+		"exa_*": "deny",
+		"gh_grep_*": "deny",
+		"postgres_*": "ask",
+		"redis_*": "ask",
+		"lighthouse_*": "ask",
+		"docker_*": "ask",
+		"chrome-devtools_*": "ask"
+	},
+
+	"mcp": {
+		"context7": {
+			"type": "remote",
+			"url": "https://mcp.context7.com/mcp",
+			"enabled": true
+		},
+		"web-search": {
+			"type": "local",
+			"command": [
+				"node",
+				"{env:HOME}/.config/opencode/vendor/web-search-mcp/dist/index.js"
+			],
+			"enabled": true
+		},
+		"exa": {
+			"type": "remote",
+			"url": "https://mcp.exa.ai/mcp",
+			"enabled": false
+		},
+		"gh_grep": {
+			"type": "remote",
+			"url": "https://mcp.grep.app",
+			"enabled": false
+		},
+		"postgres": {
+			"type": "local",
+			"command": ["uvx", "postgres-mcp", "--access-mode=unrestricted"],
+			"enabled": true,
+			"environment": {
+				"DATABASE_URI": "postgresql://postgres:postgres@localhost:5332/coffee_project_db"
+			}
+		},
+		"redis": {
+			"type": "local",
+			"command": [
+				"uvx",
+				"--from",
+				"redis-mcp-server@latest",
+				"redis-mcp-server",
+				"--url",
+				"redis://localhost:6379/0"
+			],
+			"enabled": true
+		},
+		"lighthouse": {
+			"type": "local",
+			"command": ["bunx", "@danielsogl/lighthouse-mcp@latest"],
+			"enabled": true
+		},
+		"docker": {
+			"type": "local",
+			"command": ["uvx", "mcp-server-docker"],
+			"enabled": true
+		},
+		"chrome-devtools": {
+			"type": "local",
+			"command": ["npx", "-y", "chrome-devtools-mcp@latest"],
+			"enabled": true
+		}
+	},
+
+	// The global build agent in ~/.config/opencode/opencode.jsonc is more
+	// delegation-heavy than this repo expects. Override just enough to match the
+	// repo's team-first but still hands-on workflow.
+	"agent": {
+		"build": {
+			"model": "openai/gpt-5.4",
+			"prompt": "You are OpenCode working in the Coffee Project monorepo. Follow `./.opencode/merged-instructions.md` first. Use `AGENTS.md` as the primary workflow source. Use `.codex/agent-team.md` and `.codex/agent-skills.md` for team topology and skill selection. Use `CLAUDE.md` files only for architecture, commands, and coding conventions. Keep team-first behavior for non-trivial work, but use the minimum viable delegation instead of delegating every task. Purely mechanical or clearly bounded changes may be handled directly. Ignore stale references to `.claude/` or wording that assumes you are Claude Code itself.",
+			"permission": {
+				"edit": "allow",
+				"write": "allow",
+				"bash": "allow",
+				"task": "allow"
+			}
+		}
+	}
+}

tmp/caption-result-redesign.html

@@ -0,0 +1,818 @@
+<!DOCTYPE html>
+<html lang="ru">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>Caption Result Redesign — Coffee Project</title>
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@300;400;500;600;700;800&display=swap" rel="stylesheet" />
+<style>
+  /* ============================================
+     CATPPUCCIN LATTE TOKENS (from global.scss)
+     ============================================ */
+  :root {
+    --purple-50: #f7efff;
+    --purple-100: #eedfff;
+    --purple-200: #dfc8ff;
+    --purple-300: #c8abff;
+    --purple-400: #a777f2;
+    --purple-500: #8839ef;
+    --purple-600: #7430ca;
+    --purple-700: #5f27a5;
+
+    --green-50: #eff8ea;
+    --green-100: #dcefd2;
+    --green-200: #c7e5b9;
+    --green-400: #7fc16c;
+    --green-500: #40a02b;
+    --green-600: #348222;
+
+    --color-success: #40a02b;
+    --color-primary: var(--purple-500);
+    --color-secondary: var(--purple-400);
+
+    --text-primary: #4c4f69;
+    --text-secondary: #5c5f77;
+    --text-tertiary: #8c8fa1;
+
+    --bg-canvas: #e6e9ef;
+    --bg-default: #eff1f5;
+    --bg-surface: #dce0e8;
+    --bg-hover: #ccd0da;
+
+    --border-default: #bcc0cc;
+    --border-subtle: #dce0e8;
+
+    --shadow-sm: 0 1px 2px rgba(76, 79, 105, 0.06), 0 2px 8px rgba(76, 79, 105, 0.04);
+    --shadow-md: 0 4px 6px -1px rgba(76, 79, 105, 0.08), 0 24px 48px -12px rgba(76, 79, 105, 0.1);
+    --shadow-lg: 0 10px 15px -3px rgba(76, 79, 105, 0.08), 0 40px 80px -20px rgba(76, 79, 105, 0.12);
+
+    --radius-sm: 8px;
+    --radius-md: 12px;
+    --radius-lg: 16px;
+
+    --duration-fast: 150ms;
+    --duration-normal: 250ms;
+    --duration-slow: 350ms;
+    --ease-out: cubic-bezier(0.2, 0.8, 0.2, 1);
+    --ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+
+    --accent-shadow: rgba(136, 57, 239, 0.28);
+    --accent-shadow-hover: rgba(136, 57, 239, 0.38);
+  }
+
+  /* ============================================
+     RESET
+     ============================================ */
+  *, *::before, *::after {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+    font-family: 'Manrope', sans-serif;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    font-variant-numeric: lining-nums proportional-nums;
+  }
+
+  body {
+    background: var(--bg-canvas);
+    color: var(--text-primary);
+    min-height: 100vh;
+    display: flex;
+    align-items: stretch;
+  }
+
+  body::before {
+    content: "";
+    position: fixed;
+    inset: 0;
+    background-image: radial-gradient(circle at 50% 0%, rgba(136, 57, 239, 0.08) 0%, transparent 62%);
+    pointer-events: none;
+    z-index: 0;
+  }
+
+  /* ============================================
+     WIZARD CONTAINER (simulates ProjectWizard)
+     ============================================ */
+  .wizard-shell {
+    position: relative;
+    z-index: 1;
+    width: 100%;
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+  }
+
+  /* Fake stepper bar */
+  .stepper-bar {
+    background: var(--bg-default);
+    border-bottom: 1px solid var(--border-subtle);
+    padding: 12px 20px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    font-size: 12px;
+    font-weight: 500;
+    color: var(--text-tertiary);
+  }
+
+  .stepper-step {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+  }
+
+  .stepper-indicator {
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 11px;
+    font-weight: 700;
+  }
+
+  .stepper-completed .stepper-indicator {
+    background: color-mix(in srgb, var(--color-success) 10%, var(--bg-default));
+    border: 1.5px solid color-mix(in srgb, var(--color-success) 25%, var(--border-default));
+    color: var(--color-success);
+  }
+
+  .stepper-active {
+    background: color-mix(in srgb, var(--color-secondary) 4%, transparent);
+    padding: 4px 10px 4px 4px;
+    border-radius: 6px;
+  }
+
+  .stepper-active .stepper-indicator {
+    background: var(--color-secondary);
+    color: white;
+  }
+
+  .stepper-active .stepper-label {
+    font-weight: 600;
+    font-size: 14px;
+    color: var(--text-primary);
+  }
+
+  .stepper-connector {
+    width: 24px;
+    height: 1.5px;
+    background: color-mix(in srgb, var(--color-success) 40%, var(--border-default));
+  }
+
+  /* ============================================
+     RESULT STEP — THE REDESIGN
+     ============================================ */
+  .result-root {
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    overflow: hidden;
+    min-height: 0;
+    position: relative;
+  }
+
+  /* Sparkle particles (user liked this) */
+  .sparkles {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+    z-index: 0;
+    overflow: hidden;
+  }
+
+  .sparkle {
+    position: absolute;
+    width: 4px;
+    height: 4px;
+    border-radius: 50%;
+    opacity: 0;
+    animation: sparkleFloat 5s ease-in-out infinite;
+  }
+
+  .sparkle--green {
+    background: var(--color-success);
+  }
+
+  .sparkle--purple {
+    background: var(--purple-400);
+  }
+
+  .sparkle:nth-child(1) { top: 20%; left: 10%; animation-delay: 0s; }
+  .sparkle:nth-child(2) { top: 15%; left: 80%; animation-delay: 1.2s; }
+  .sparkle:nth-child(3) { top: 65%; left: 5%; animation-delay: 2.4s; }
+  .sparkle:nth-child(4) { top: 50%; left: 90%; animation-delay: 0.8s; }
+  .sparkle:nth-child(5) { top: 75%; left: 25%; animation-delay: 3.2s; }
+  .sparkle:nth-child(6) { top: 30%; left: 60%; animation-delay: 1.8s; }
+  .sparkle:nth-child(7) { top: 10%; left: 40%; animation-delay: 4s; }
+  .sparkle:nth-child(8) { top: 55%; left: 70%; animation-delay: 2s; }
+  .sparkle:nth-child(9) { top: 85%; left: 55%; animation-delay: 0.5s; }
+  .sparkle:nth-child(10) { top: 40%; left: 15%; animation-delay: 3.6s; }
+
+  @keyframes sparkleFloat {
+    0%, 100% {
+      opacity: 0;
+      transform: translateY(0) scale(0.5);
+    }
+    20% {
+      opacity: 0.6;
+      transform: translateY(-12px) scale(1);
+    }
+    60% {
+      opacity: 0.25;
+      transform: translateY(-30px) scale(0.7);
+    }
+  }
+
+  /* Content area */
+  .result-content {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    flex: 1;
+    padding: 32px 40px;
+    gap: 0;
+    overflow-y: auto;
+  }
+
+  /* Success header */
+  .result-header {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 12px;
+    margin-bottom: 24px;
+    animation: fadeSlideDown 0.6s var(--ease-out) both;
+  }
+
+  .success-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 4px 12px 4px 8px;
+    border-radius: 9999px;
+    font-size: 12px;
+    font-weight: 600;
+    background: color-mix(in srgb, var(--color-success) 12%, var(--bg-default));
+    color: var(--color-success);
+    border: 1px solid color-mix(in srgb, var(--color-success) 20%, var(--border-subtle));
+  }
+
+  .success-badge svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  .result-title {
+    font-weight: 800;
+    font-size: 28px;
+    line-height: 36px;
+    letter-spacing: -0.035em;
+    color: var(--text-primary);
+    text-align: center;
+  }
+
+  .result-subtitle {
+    font-weight: 400;
+    font-size: 14px;
+    line-height: 20px;
+    color: var(--text-tertiary);
+    text-align: center;
+    letter-spacing: -0.006em;
+  }
+
+  /* Video container */
+  .video-container {
+    width: 100%;
+    max-width: 780px;
+    animation: fadeSlideUp 0.7s var(--ease-out) 0.15s both;
+  }
+
+  .video-frame {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 9;
+    border-radius: var(--radius-md);
+    overflow: hidden;
+    background: #000;
+    box-shadow:
+      var(--shadow-lg),
+      0 0 0 1px var(--border-subtle);
+  }
+
+  /* Fake video content for prototype */
+  .video-placeholder {
+    width: 100%;
+    height: 100%;
+    background: linear-gradient(180deg, #1e1e2e 0%, #11111b 100%);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    position: relative;
+  }
+
+  .video-placeholder::after {
+    content: "";
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 50px;
+    background: linear-gradient(transparent, rgba(0,0,0,0.5));
+  }
+
+  .fake-sub {
+    position: absolute;
+    bottom: 24px;
+    left: 50%;
+    transform: translateX(-50%);
+    z-index: 1;
+    font-weight: 700;
+    font-size: 16px;
+    color: #fff;
+    text-shadow: 0 2px 6px rgba(0,0,0,0.8);
+    white-space: nowrap;
+  }
+
+  .fake-sub em {
+    color: var(--purple-400);
+    font-style: normal;
+  }
+
+  .play-btn {
+    width: 56px;
+    height: 56px;
+    border-radius: 50%;
+    background: rgba(255,255,255,0.12);
+    backdrop-filter: blur(8px);
+    border: 1px solid rgba(255,255,255,0.15);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: all 0.25s var(--ease-out);
+    z-index: 2;
+  }
+
+  .play-btn:hover {
+    background: rgba(255,255,255,0.2);
+    transform: scale(1.06);
+  }
+
+  .play-btn svg {
+    width: 20px;
+    height: 20px;
+    fill: white;
+    margin-left: 2px;
+  }
+
+  /* File info bar (matches VerifyStep infoCard pattern) */
+  .file-bar {
+    width: 100%;
+    max-width: 780px;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    margin-top: 12px;
+    background: color-mix(in srgb, var(--bg-default) 92%, transparent);
+    border: 1px solid var(--border-subtle);
+    border-radius: var(--radius-sm);
+    box-shadow: var(--shadow-sm);
+    animation: fadeSlideUp 0.6s var(--ease-out) 0.35s both;
+  }
+
+  .file-meta {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    min-width: 0;
+  }
+
+  .file-icon {
+    width: 32px;
+    height: 32px;
+    border-radius: 6px;
+    background: var(--bg-surface);
+    border: 1px solid var(--border-subtle);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+  }
+
+  .file-icon svg {
+    width: 16px;
+    height: 16px;
+    color: var(--text-tertiary);
+  }
+
+  .file-info {
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+    min-width: 0;
+  }
+
+  .file-name {
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text-primary);
+    letter-spacing: -0.01em;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .file-details-text {
+    font-size: 11px;
+    font-weight: 500;
+    color: var(--text-tertiary);
+  }
+
+  .file-actions {
+    display: flex;
+    gap: 4px;
+    flex-shrink: 0;
+  }
+
+  /* Inline icon button (copy path, etc.) */
+  .icon-btn {
+    width: 28px;
+    height: 28px;
+    border-radius: 6px;
+    border: none;
+    background: transparent;
+    color: var(--text-tertiary);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    transition: all var(--duration-fast) var(--ease-out);
+  }
+
+  .icon-btn:hover {
+    background: var(--bg-hover);
+    color: var(--text-secondary);
+  }
+
+  .icon-btn svg {
+    width: 14px;
+    height: 14px;
+  }
+
+  /* ============================================
+     FOOTER (matches existing wizard footer)
+     ============================================ */
+  .result-footer {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 16px 24px;
+    border-top: 1px solid var(--border-subtle);
+    background: var(--bg-surface);
+    z-index: 2;
+    animation: fadeIn 0.5s var(--ease-out) 0.5s both;
+  }
+
+  .footer-left {
+    display: flex;
+    gap: 8px;
+  }
+
+  .footer-right {
+    display: flex;
+    gap: 8px;
+  }
+
+  /* ============================================
+     BUTTONS (matching Radix / project Button)
+     ============================================ */
+  .btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    padding: 0 16px;
+    height: 32px;
+    border-radius: 6px;
+    border: none;
+    font-family: 'Manrope', sans-serif;
+    font-size: 13px;
+    font-weight: 600;
+    cursor: pointer;
+    transition:
+      transform var(--duration-fast) var(--ease-out),
+      box-shadow var(--duration-normal) var(--ease-out),
+      filter var(--duration-normal) var(--ease-out),
+      background var(--duration-normal) var(--ease-out);
+    letter-spacing: -0.01em;
+    outline: none;
+    user-select: none;
+  }
+
+  .btn svg {
+    width: 14px;
+    height: 14px;
+    flex-shrink: 0;
+  }
+
+  /* Ghost */
+  .btn--ghost {
+    background: transparent;
+    color: var(--text-secondary);
+  }
+
+  .btn--ghost:hover {
+    filter: brightness(0.95);
+    background: var(--bg-hover);
+  }
+
+  .btn--ghost:active {
+    transform: scale(0.96);
+    filter: brightness(0.92);
+  }
+
+  /* Outline */
+  .btn--outline {
+    background: transparent;
+    color: var(--text-primary);
+    box-shadow: inset 0 0 0 1px var(--border-default);
+  }
+
+  .btn--outline:hover {
+    filter: brightness(0.95);
+  }
+
+  .btn--outline:active {
+    transform: scale(0.96);
+    filter: brightness(0.92);
+  }
+
+  /* Primary (solid plum) */
+  .btn--primary {
+    background: linear-gradient(180deg, var(--purple-400), var(--purple-600));
+    color: white;
+    background-image: linear-gradient(180deg, hsla(0,0%,100%,0.12) 0%, transparent 100%);
+    background-color: var(--purple-500);
+    box-shadow:
+      inset 0 1px 1px hsla(0,0%,100%,0.2),
+      0 1px 2px rgba(0,0,0,0.1);
+    border-top: 1px solid hsla(0,0%,100%,0.1);
+  }
+
+  .btn--primary:hover {
+    filter: brightness(1.08);
+    box-shadow:
+      inset 0 1px 1px hsla(0,0%,100%,0.2),
+      0 4px 14px var(--accent-shadow-hover);
+  }
+
+  .btn--primary:active {
+    transform: scale(0.96);
+    filter: brightness(0.95);
+    box-shadow: inset 0 2px 4px rgba(0,0,0,0.2), 0 1px 2px rgba(0,0,0,0.1);
+  }
+
+  /* Success primary (green) */
+  .btn--success {
+    background-color: var(--color-success);
+    background-image: linear-gradient(180deg, hsla(0,0%,100%,0.12) 0%, transparent 100%);
+    color: white;
+    box-shadow:
+      inset 0 1px 1px hsla(0,0%,100%,0.2),
+      0 1px 2px rgba(0,0,0,0.1);
+    border-top: 1px solid hsla(0,0%,100%,0.1);
+  }
+
+  .btn--success:hover {
+    filter: brightness(1.08);
+    box-shadow:
+      inset 0 1px 1px hsla(0,0%,100%,0.2),
+      0 4px 14px rgba(64, 160, 43, 0.3);
+  }
+
+  .btn--success:active {
+    transform: scale(0.96);
+    filter: brightness(0.95);
+  }
+
+  /* Larger button variant */
+  .btn--lg {
+    height: 36px;
+    padding: 0 20px;
+    font-size: 14px;
+    border-radius: 8px;
+  }
+
+  /* ============================================
+     ANIMATIONS
+     ============================================ */
+  @keyframes fadeSlideDown {
+    from {
+      opacity: 0;
+      transform: translateY(-12px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes fadeSlideUp {
+    from {
+      opacity: 0;
+      transform: translateY(16px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes fadeIn {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after {
+      animation-duration: 0ms !important;
+      animation-delay: 0ms !important;
+      transition-duration: 0ms !important;
+    }
+  }
+
+  /* ============================================
+     RESPONSIVE
+     ============================================ */
+  @media (max-width: 768px) {
+    .result-content {
+      padding: 24px 16px;
+    }
+
+    .result-title {
+      font-size: 24px;
+      line-height: 32px;
+    }
+
+    .file-bar {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: 8px;
+    }
+
+    .result-footer {
+      flex-direction: column;
+      gap: 8px;
+    }
+
+    .footer-left, .footer-right {
+      width: 100%;
+    }
+
+    .footer-right {
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+    }
+
+    .footer-right .btn {
+      justify-content: center;
+    }
+  }
+</style>
+</head>
+<body>
+
+<div class="wizard-shell">
+
+  <!-- Stepper bar (for context, same as existing) -->
+  <div class="stepper-bar">
+    <div class="stepper-step stepper-completed">
+      <div class="stepper-indicator">
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="none"><path d="M2.5 6.5L4.5 8.5L9.5 3.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </div>
+      <span class="stepper-label">Загрузка файла</span>
+    </div>
+    <div class="stepper-connector"></div>
+    <div class="stepper-step stepper-completed">
+      <div class="stepper-indicator">
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="none"><path d="M2.5 6.5L4.5 8.5L9.5 3.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </div>
+      <span class="stepper-label">Удаление тишины</span>
+    </div>
+    <div class="stepper-connector"></div>
+    <div class="stepper-step stepper-completed">
+      <div class="stepper-indicator">
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="none"><path d="M2.5 6.5L4.5 8.5L9.5 3.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </div>
+      <span class="stepper-label">Транскрипция</span>
+    </div>
+    <div class="stepper-connector"></div>
+    <div class="stepper-step stepper-active">
+      <div class="stepper-indicator">4</div>
+      <span class="stepper-label">Рендер</span>
+    </div>
+  </div>
+
+  <!-- RESULT STEP -->
+  <div class="result-root">
+
+    <!-- Celebration sparkles -->
+    <div class="sparkles">
+      <div class="sparkle sparkle--green"></div>
+      <div class="sparkle sparkle--purple"></div>
+      <div class="sparkle sparkle--green"></div>
+      <div class="sparkle sparkle--purple"></div>
+      <div class="sparkle sparkle--green"></div>
+      <div class="sparkle sparkle--purple"></div>
+      <div class="sparkle sparkle--green"></div>
+      <div class="sparkle sparkle--purple"></div>
+      <div class="sparkle sparkle--green"></div>
+      <div class="sparkle sparkle--purple"></div>
+    </div>
+
+    <div class="result-content">
+
+      <!-- Success header -->
+      <div class="result-header">
+        <div class="success-badge">
+          <svg viewBox="0 0 14 14" fill="none">
+            <circle cx="7" cy="7" r="6" stroke="currentColor" stroke-width="1.5"/>
+            <path d="M4.5 7.5L6 9L9.5 5.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+          </svg>
+          Готово
+        </div>
+        <h2 class="result-title">Результат</h2>
+        <p class="result-subtitle">Видео с субтитрами готово к скачиванию</p>
+      </div>
+
+      <!-- Video player -->
+      <div class="video-container">
+        <div class="video-frame">
+          <div class="video-placeholder">
+            <button class="play-btn" aria-label="Воспроизвести">
+              <svg viewBox="0 0 24 24"><polygon points="6,3 20,12 6,21"/></svg>
+            </button>
+            <span class="fake-sub">Пример <em>субтитров</em></span>
+          </div>
+        </div>
+      </div>
+
+      <!-- File info -->
+      <div class="file-bar">
+        <div class="file-meta">
+          <div class="file-icon">
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+              <rect x="2" y="2" width="20" height="20" rx="3"/>
+              <polygon points="10,8 16,12 10,16" fill="currentColor" stroke="none"/>
+            </svg>
+          </div>
+          <div class="file-info">
+            <span class="file-name">asdasd_captioned.mp4</span>
+            <span class="file-details-text">42.8 MB &middot; MP4</span>
+          </div>
+        </div>
+      </div>
+
+    </div>
+
+    <!-- Footer -->
+    <div class="result-footer">
+      <div class="footer-left">
+        <button class="btn btn--ghost">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <polyline points="1 4 1 10 7 10"/>
+            <path d="M3.51 15a9 9 0 1 0 2.13-9.36L1 10"/>
+          </svg>
+          Перегенерировать
+        </button>
+      </div>
+      <div class="footer-right">
+        <button class="btn btn--primary btn--lg">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/>
+            <polyline points="7 10 12 15 17 10"/>
+            <line x1="12" y1="15" x2="12" y2="3"/>
+          </svg>
+          Скачать
+        </button>
+        <button class="btn btn--success btn--lg">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <polyline points="20 6 9 17 4 12"/>
+          </svg>
+          Завершить
+        </button>
+      </div>
+    </div>
+  </div>
+
+</div>
+
+</body>
+</html>

tmp/preset-grid-redesign.html

@@ -0,0 +1,667 @@
+<!DOCTYPE html>
+<html lang="ru" data-theme="light">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Preset Grid Redesign — Coffee Project</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700&family=Lobster&family=Inter:wght@400;700;900&display=swap" rel="stylesheet">
+<style>
+  /*
+   * Uses ONLY tokens from global.scss:
+   *   --bg-canvas, --bg-default, --bg-surface, --bg-hover
+   *   --text-primary, --text-secondary, --text-tertiary
+   *   --border-default, --border-subtle
+   *   --color-primary, --color-secondary
+   *   --purple-50..900, --green-50..900
+   *   --shadow-sm, --shadow-md
+   *   --radius-sm, --radius-md, --radius-lg
+   *   --duration-fast, --duration-normal, --ease-out
+   *   --accent-shadow, --accent-shadow-hover
+   *   --accent-solid-start, --accent-solid-end, --accent-foreground
+   */
+
+  /* ─── Light (Catppuccin Latte) ─── */
+  :root, [data-theme="light"] {
+    --bg-canvas: #e6e9ef;
+    --bg-default: #eff1f5;
+    --bg-surface: #dce0e8;
+    --bg-hover: #ccd0da;
+    --text-primary: #4c4f69;
+    --text-secondary: #5c5f77;
+    --text-tertiary: #8c8fa1;
+    --border-default: #bcc0cc;
+    --border-subtle: #dce0e8;
+    --color-primary: #8839ef;
+    --color-secondary: #a777f2;
+    --purple-50: #f7efff;
+    --purple-100: #eedfff;
+    --purple-200: #dfc8ff;
+    --purple-300: #c8abff;
+    --purple-400: #a777f2;
+    --purple-500: #8839ef;
+    --purple-600: #7430ca;
+    --accent-solid-start: #a777f2;
+    --accent-solid-end: #7430ca;
+    --accent-foreground: #ffffff;
+    --accent-shadow: rgba(136,57,239,0.28);
+    --accent-shadow-hover: rgba(136,57,239,0.38);
+    --shadow-sm: 0 1px 2px rgba(76,79,105,0.06), 0 2px 8px rgba(76,79,105,0.04);
+    --shadow-md: 0 4px 6px -1px rgba(76,79,105,0.08), 0 24px 48px -12px rgba(76,79,105,0.1);
+    --radius-sm: 8px;
+    --radius-md: 12px;
+    --radius-lg: 16px;
+    --duration-fast: 150ms;
+    --duration-normal: 250ms;
+    --ease-out: cubic-bezier(0.2, 0.8, 0.2, 1);
+    --page-glow: radial-gradient(circle at 50% 0%, rgba(136,57,239,0.08) 0%, transparent 62%);
+    --preview-bg: #0c0a1a;
+  }
+
+  /* ─── Dark (Catppuccin Mocha) ─── */
+  [data-theme="dark"] {
+    --bg-canvas: #11111b;
+    --bg-default: #1e1e2e;
+    --bg-surface: #313244;
+    --bg-hover: #45475a;
+    --text-primary: #cdd6f4;
+    --text-secondary: #bac2de;
+    --text-tertiary: #9399b2;
+    --border-default: #45475a;
+    --border-subtle: #313244;
+    --color-primary: #cba6f7;
+    --color-secondary: #6a5a93;
+    --purple-50: #2b253b;
+    --purple-100: #362f4c;
+    --purple-200: #4b4168;
+    --purple-300: #6a5a93;
+    --purple-400: #cba6f7;
+    --purple-500: #d9bcfa;
+    --purple-600: #e4cffc;
+    --accent-solid-start: #6a5a93;
+    --accent-solid-end: #362f4c;
+    --accent-foreground: #f5e0dc;
+    --accent-shadow: rgba(203,166,247,0.22);
+    --accent-shadow-hover: rgba(203,166,247,0.3);
+    --shadow-sm: 0 1px 2px rgba(17,17,27,0.5);
+    --shadow-md: 0 4px 6px -1px rgba(17,17,27,0.58), 0 24px 48px -12px rgba(17,17,27,0.52);
+    --page-glow: radial-gradient(circle at 50% 0%, rgba(203,166,247,0.12) 0%, transparent 55%);
+    --preview-bg: #0c0a1a;
+  }
+
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    font-family: 'Manrope', -apple-system, sans-serif;
+    background: var(--bg-canvas);
+    color: var(--text-primary);
+    min-height: 100vh;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  body::before {
+    content: "";
+    position: fixed;
+    inset: 0;
+    background-image: var(--page-glow);
+    pointer-events: none;
+    z-index: 0;
+  }
+
+  /* ─── Page shell ─── */
+  .page-shell {
+    position: relative;
+    z-index: 1;
+    max-width: 1200px;
+    margin: 0 auto;
+    padding: 40px 32px;
+  }
+
+  .page-title {
+    font-size: 20px;
+    font-weight: 600;
+    color: var(--text-primary);
+    margin-bottom: 24px;
+  }
+
+  /* ─── Grid ─── */
+  .preset-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+    gap: 16px;
+  }
+
+  /* ─── Card ─── */
+  .preset-card {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    background: var(--bg-default);
+    border: 1.5px solid var(--border-subtle);
+    border-radius: var(--radius-md);
+    overflow: hidden;
+    cursor: pointer;
+    box-shadow: var(--shadow-sm);
+    /* Only transition border-color — cheap GPU op */
+    transition: border-color var(--duration-normal) var(--ease-out);
+    animation: cardIn 0.35s var(--ease-out) backwards;
+  }
+
+  .preset-card:nth-child(1) { animation-delay: 0ms; }
+  .preset-card:nth-child(2) { animation-delay: 50ms; }
+  .preset-card:nth-child(3) { animation-delay: 100ms; }
+  .preset-card:nth-child(4) { animation-delay: 150ms; }
+  .preset-card:nth-child(5) { animation-delay: 200ms; }
+
+  @keyframes cardIn {
+    from { opacity: 0; transform: translateY(8px); }
+  }
+
+  .preset-card:hover {
+    border-color: var(--color-secondary);
+  }
+
+  .preset-card.selected {
+    border-color: var(--color-primary);
+    box-shadow: var(--shadow-sm), 0 0 0 1px var(--color-primary);
+  }
+
+  .preset-card.selected:hover {
+    border-color: var(--color-primary);
+  }
+
+  /* ─── Preview ─── */
+  .preview-area {
+    position: relative;
+    aspect-ratio: var(--video-ratio, 16 / 9);
+    background: var(--preview-bg);
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+
+  /* ─── Checkmark ─── */
+  .check-indicator {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    width: 22px;
+    height: 22px;
+    background: var(--color-primary);
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 2;
+    opacity: 0;
+    transform: scale(0.6);
+    transition: opacity var(--duration-fast), transform var(--duration-fast);
+  }
+
+  .selected .check-indicator {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  .check-indicator svg {
+    width: 12px;
+    height: 12px;
+    color: var(--accent-foreground);
+  }
+
+  /* ─── Subtitle content ─── */
+  .sub-content {
+    position: relative;
+    z-index: 1;
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    padding: 12px;
+  }
+
+  .sub-content.pos-bottom { justify-content: flex-end; }
+  .sub-content.pos-center { justify-content: center; }
+  .sub-content.pos-top { justify-content: flex-start; }
+  .sub-content.align-center { align-items: center; text-align: center; }
+  .sub-content.align-left { align-items: flex-start; text-align: left; }
+
+  .sub-bubble {
+    max-width: 92%;
+    padding: 6px 10px;
+    border-radius: 6px;
+    word-break: break-word;
+    line-height: 1.3;
+  }
+
+  /* ─── Footer ─── */
+  .card-footer {
+    padding: 10px 12px;
+    display: flex;
+    flex-direction: column;
+    gap: 3px;
+  }
+
+  .footer-row {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .preset-name {
+    font-size: 13px;
+    font-weight: 600;
+    color: var(--text-primary);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* Badge — matches project Badge (Radix plum soft) */
+  .sys-badge {
+    flex-shrink: 0;
+    display: inline-flex;
+    align-items: center;
+    font-size: 11px;
+    font-weight: 500;
+    line-height: 1;
+    color: var(--color-primary);
+    background: var(--purple-100);
+    padding: 3px 8px;
+    border-radius: var(--radius-sm);
+  }
+
+  .style-hint {
+    display: flex;
+    align-items: center;
+    gap: 5px;
+    font-size: 11px;
+    color: var(--text-tertiary);
+    white-space: nowrap;
+    overflow: hidden;
+  }
+
+  .color-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    flex-shrink: 0;
+    border: 1px solid rgba(128,128,128,0.15);
+  }
+
+  .sep {
+    color: var(--border-default);
+    font-size: 10px;
+  }
+
+  /* ─── Hover actions ─── */
+  .card-actions {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    display: flex;
+    gap: 4px;
+    opacity: 0;
+    transition: opacity var(--duration-fast);
+    z-index: 3;
+  }
+
+  .selected .card-actions { display: none; }
+
+  .preset-card:hover .card-actions { opacity: 1; }
+
+  .act-btn {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 26px;
+    height: 26px;
+    border: none;
+    border-radius: 6px;
+    background: var(--bg-surface);
+    color: var(--text-secondary);
+    cursor: pointer;
+    transition: background var(--duration-fast), color var(--duration-fast);
+  }
+
+  .act-btn:hover {
+    background: var(--bg-hover);
+    color: var(--text-primary);
+  }
+
+  .act-btn svg { width: 13px; height: 13px; }
+
+  /* ─── Create card ─── */
+  .create-card {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    background: transparent;
+    border: 1.5px dashed var(--border-default);
+    border-radius: var(--radius-md);
+    cursor: pointer;
+    transition: border-color var(--duration-normal) var(--ease-out);
+  }
+
+  .create-inner {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: 8px;
+    aspect-ratio: var(--video-ratio, 16 / 9);
+    width: 100%;
+  }
+
+  .create-card:hover {
+    border-color: var(--color-secondary);
+  }
+
+  .create-card svg {
+    width: 28px;
+    height: 28px;
+    color: var(--text-tertiary);
+    transition: color var(--duration-normal);
+  }
+
+  .create-card:hover svg { color: var(--color-primary); }
+
+  .create-label {
+    font-size: 13px;
+    font-weight: 500;
+    color: var(--text-tertiary);
+    transition: color var(--duration-normal);
+  }
+
+  .create-card:hover .create-label { color: var(--text-secondary); }
+
+  /* ─── Footer ─── */
+  .page-footer {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    margin-top: 32px;
+    padding-top: 16px;
+    border-top: 1px solid var(--border-subtle);
+  }
+
+  /* Button — matches project Button component */
+  .btn {
+    font-family: 'Manrope', sans-serif;
+    font-size: 14px;
+    font-weight: 600;
+    padding: 8px 20px;
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+    letter-spacing: -0.01em;
+    transition: filter var(--duration-fast), box-shadow var(--duration-normal) var(--ease-out);
+    border: none;
+  }
+
+  .btn:active { transform: scale(0.96); }
+
+  .btn-outline {
+    background: transparent;
+    border: 1px solid var(--border-default);
+    color: var(--text-secondary);
+  }
+
+  .btn-outline:hover {
+    filter: brightness(0.95);
+  }
+
+  .btn-primary {
+    background: linear-gradient(135deg, var(--accent-solid-start), var(--accent-solid-end));
+    background-image: linear-gradient(180deg, hsla(0,0%,100%,0.12) 0%, transparent 100%);
+    background-color: var(--color-primary);
+    color: var(--accent-foreground);
+    box-shadow: inset 0 1px 1px hsla(0,0%,100%,0.2), 0 1px 2px rgba(0,0,0,0.1);
+    border-top: 1px solid hsla(0,0%,100%,0.1);
+  }
+
+  .btn-primary:hover {
+    filter: brightness(1.08);
+    box-shadow: inset 0 1px 1px hsla(0,0%,100%,0.2), 0 4px 14px var(--accent-shadow-hover);
+  }
+
+  /* ─── Demo controls ─── */
+  .demo-bar {
+    display: flex;
+    gap: 24px;
+    margin-bottom: 24px;
+    align-items: center;
+    flex-wrap: wrap;
+  }
+
+  .demo-group {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+
+  .demo-label {
+    font-size: 11px;
+    color: var(--text-tertiary);
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    font-weight: 600;
+  }
+
+  .toggle-btn {
+    font-family: 'Manrope', sans-serif;
+    font-size: 12px;
+    font-weight: 500;
+    padding: 4px 12px;
+    border: 1px solid var(--border-default);
+    border-radius: var(--radius-sm);
+    background: transparent;
+    color: var(--text-tertiary);
+    cursor: pointer;
+    transition: all var(--duration-fast);
+  }
+
+  .toggle-btn:hover {
+    border-color: var(--color-secondary);
+    color: var(--text-secondary);
+  }
+
+  .toggle-btn.active {
+    border-color: var(--color-primary);
+    background: var(--purple-100);
+    color: var(--color-primary);
+  }
+
+  /* ─── Responsive ─── */
+  @media (max-width: 768px) {
+    .preset-grid {
+      grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+      gap: 12px;
+    }
+    .page-shell { padding: 24px 16px; }
+    .style-hint { display: none; }
+  }
+
+  @media (max-width: 480px) {
+    .preset-grid { grid-template-columns: repeat(2, 1fr); }
+  }
+</style>
+</head>
+<body>
+
+<div class="page-shell">
+  <div class="demo-bar">
+    <div class="demo-group">
+      <span class="demo-label">Ratio</span>
+      <button class="toggle-btn active" onclick="setRatio(16/9, this)">16:9</button>
+      <button class="toggle-btn" onclick="setRatio(9/16, this)">9:16</button>
+      <button class="toggle-btn" onclick="setRatio(4/3, this)">4:3</button>
+      <button class="toggle-btn" onclick="setRatio(1, this)">1:1</button>
+      <button class="toggle-btn" onclick="setRatio(2.35, this)">2.35:1</button>
+    </div>
+    <div class="demo-group">
+      <span class="demo-label">Theme</span>
+      <button class="toggle-btn active" onclick="setTheme('light', this)">Light</button>
+      <button class="toggle-btn" onclick="setTheme('dark', this)">Dark</button>
+    </div>
+  </div>
+
+  <h2 class="page-title">Выбор пресета субтитров</h2>
+
+  <div class="preset-grid" id="grid">
+
+    <!-- Классические (Selected) -->
+    <div class="preset-card selected" onclick="selectCard(this)">
+      <div class="preview-area">
+        <div class="check-indicator">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+        </div>
+        <div class="sub-content pos-bottom align-center">
+          <div class="sub-bubble" style="background: rgba(0,0,0,0.6);">
+            <span style="font-family: 'Lobster', cursive; font-size: 18px; color: #fff;">Пример <span style="color: #FFD700;">субтитров</span></span>
+          </div>
+        </div>
+      </div>
+      <div class="card-footer">
+        <div class="footer-row">
+          <span class="preset-name">Классические</span>
+          <span class="sys-badge">Системный</span>
+        </div>
+        <div class="style-hint">
+          Lobster <span class="sep">·</span>
+          <span class="color-dot" style="background: #FFD700;"></span> Золотой
+        </div>
+      </div>
+    </div>
+
+    <!-- Неон -->
+    <div class="preset-card" onclick="selectCard(this)">
+      <div class="preview-area">
+        <div class="check-indicator">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+        </div>
+        <div class="card-actions">
+          <button class="act-btn" title="Редактировать"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z"/></svg></button>
+          <button class="act-btn" title="Удалить"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg></button>
+        </div>
+        <div class="sub-content pos-center align-center">
+          <div class="sub-bubble" style="background: rgba(0,255,255,0.12); border-radius: 8px; box-shadow: 0 0 16px rgba(0,255,255,0.2);">
+            <span style="font-family: 'Inter', sans-serif; font-weight: 700; font-size: 16px; color: #00ffff; text-shadow: 0 0 10px rgba(0,255,255,0.6);">Пример <span style="color: #ff00ff; text-shadow: 0 0 10px rgba(255,0,255,0.6);">субтитров</span></span>
+          </div>
+        </div>
+      </div>
+      <div class="card-footer">
+        <div class="footer-row">
+          <span class="preset-name">Неон</span>
+          <span class="sys-badge">Системный</span>
+        </div>
+        <div class="style-hint">
+          Inter Bold <span class="sep">·</span>
+          <span class="color-dot" style="background: #00ffff;"></span> Неоновый
+        </div>
+      </div>
+    </div>
+
+    <!-- Минимализм -->
+    <div class="preset-card" onclick="selectCard(this)">
+      <div class="preview-area">
+        <div class="check-indicator">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+        </div>
+        <div class="card-actions">
+          <button class="act-btn" title="Редактировать"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z"/></svg></button>
+          <button class="act-btn" title="Удалить"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg></button>
+        </div>
+        <div class="sub-content pos-bottom align-center">
+          <div class="sub-bubble" style="background: transparent;">
+            <span style="font-family: 'Inter', sans-serif; font-weight: 400; font-size: 15px; color: rgba(255,255,255,0.9);">Пример субтитров</span>
+          </div>
+        </div>
+      </div>
+      <div class="card-footer">
+        <div class="footer-row">
+          <span class="preset-name">Минимализм</span>
+          <span class="sys-badge">Системный</span>
+        </div>
+        <div class="style-hint">
+          Inter <span class="sep">·</span>
+          <span class="color-dot" style="background: #ffffff;"></span> Белый
+        </div>
+      </div>
+    </div>
+
+    <!-- Жирный -->
+    <div class="preset-card" onclick="selectCard(this)">
+      <div class="preview-area">
+        <div class="check-indicator">
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>
+        </div>
+        <div class="card-actions">
+          <button class="act-btn" title="Редактировать"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M17 3a2.85 2.83 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5Z"/></svg></button>
+          <button class="act-btn" title="Удалить"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 6h18"/><path d="M19 6v14c0 1-1 2-2 2H7c-1 0-2-1-2-2V6"/><path d="M8 6V4c0-1 1-2 2-2h4c1 0 2 1 2 2v2"/></svg></button>
+        </div>
+        <div class="sub-content pos-bottom align-left">
+          <div class="sub-bubble" style="background: rgba(0,0,0,0.75); border-radius: 4px;">
+            <span style="font-family: 'Inter', sans-serif; font-weight: 900; font-size: 20px; color: #ffffff; -webkit-text-stroke: 1px #000;">Пример <span style="color: #ff006e;">субтитров</span></span>
+          </div>
+        </div>
+      </div>
+      <div class="card-footer">
+        <div class="footer-row">
+          <span class="preset-name">Жирный</span>
+          <span class="sys-badge">Системный</span>
+        </div>
+        <div class="style-hint">
+          Inter Black <span class="sep">·</span>
+          <span class="color-dot" style="background: #ff006e;"></span> Розовый
+        </div>
+      </div>
+    </div>
+
+    <!-- Create new -->
+    <div class="create-card" style="animation: cardIn 0.35s var(--ease-out) 250ms backwards;">
+      <div class="create-inner">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round">
+          <line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/>
+        </svg>
+        <span class="create-label">Создать пресет</span>
+      </div>
+    </div>
+
+  </div>
+
+  <div class="page-footer">
+    <button class="btn btn-outline">Назад</button>
+    <button class="btn btn-primary">Генерировать</button>
+  </div>
+</div>
+
+<script>
+  function selectCard(card) {
+    document.querySelectorAll('.preset-card').forEach(c => c.classList.remove('selected'));
+    card.classList.add('selected');
+  }
+
+  function setRatio(ratio, btn) {
+    document.querySelectorAll('.toggle-btn').forEach(b => {
+      if (b.closest('.demo-group')?.querySelector('.demo-label')?.textContent === 'Ratio')
+        b.classList.remove('active');
+    });
+    btn.classList.add('active');
+    document.querySelectorAll('.preview-area, .create-inner').forEach(el => {
+      el.style.aspectRatio = ratio;
+    });
+  }
+
+  function setTheme(theme, btn) {
+    document.querySelectorAll('.toggle-btn').forEach(b => {
+      if (b.closest('.demo-group')?.querySelector('.demo-label')?.textContent === 'Theme')
+        b.classList.remove('active');
+    });
+    btn.classList.add('active');
+    document.documentElement.setAttribute('data-theme', theme);
+  }
+</script>
+
+</body>
+</html>