docs initial

2026-04-06 01:44:58 +03:00
parent 2a344ad588
commit 694b8bc77c
84 changed files with 6922 additions and 298 deletions
@@ -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 |
@@ -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
@@ -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.
 ```
@@ -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.
 ```
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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`.
@@ -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).
@@ -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`.
@@ -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
@@ -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.
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -254,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
 ---
@@ -630,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
@@ -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
@@ -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
@@ -1,300 +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.
 **Architects** design specs and patterns. **Engineers** implement production code. **Leads** coordinate. **Staff** are cross-cutting.
 # 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 Leads
+Based on Steps 1-2, select the minimum agents needed:
 Based on Steps 1-3, select which leads and staff agents to involve. Think in concerns, not individual specialists:
 | Concern | Dispatch |
 |---------|----------|
-| Architecture (API design, schema, cross-service, implementation) | Architecture Lead |
+| Architecture (API design, schema, cross-service) | Architecture Lead |
-| Quality (testing, security, performance, design compliance) | Quality Lead |
+| Quality (testing, security, performance) | Quality Lead |
-| Product (UX, docs, ML/AI, monetization, feature strategy) | Product Lead |
+| Product (UX, docs, ML/AI) | Product Lead |
 | Infrastructure (CI/CD, Docker, deployment) | DevOps Engineer (staff, direct) |
-| Debugging (root cause analysis, cross-service investigation) | Debug Specialist (staff, direct) |
+| Debugging (root cause analysis) | Debug Specialist (staff, direct) |
-For Product Lead, include `MODE: coordinator` (default) or `MODE: specialist` in the dispatch context based on whether the task needs sub-team coordination or direct product expertise.
+Every agent must have a justification: what question will they answer?
-Every selected lead must have a clear, reasoned justification. Ask yourself:
+## Step 4: Dispatch in Parallel
 - Does this task REQUIRE this lead's sub-team's expertise?
 - What specific sub-task will this lead coordinate?
 - Could another already-selected lead cover this?
-## Step 5: Determine Parallelism
+Dispatch all independent agents simultaneously using multiple Agent tool calls in one response. Include in each dispatch:
-Which leads can run simultaneously (no mutual dependencies)? Leads handle their own internal phasing and specialist sequencing. You only need to think about lead-level dependencies.
+```
 DISPATCH CONTEXT:
  origin_task: "<original task>"
  call_chain: ["orchestrator"]
  current_depth: 1
  max_depth: 3
  initiating_agent: "orchestrator"
  reason: "<why this agent>"
-## Step 6: Predict Handoffs
+TASK: <specific task for this agent>
-Based on information flow analysis, predict which leads will produce output that other leads need. If Architecture Lead and Quality Lead are both dispatched, Quality Lead may need Architecture Lead's API contracts to plan verification. Sequence accordingly.
+FILES TO ANALYZE:
  - <file path 1>
  - <file path 2>
-## Step 7: Check Memory for Relevant Past Decisions
+DELIVERABLE: <what you need back>
 ```
-Before building the pipeline, scan `.claude/agents-memory/orchestrator/` for decisions related to:
+## Step 5: Synthesize
 - The same modules, services, or features
 - Similar task types with established patterns
 - Upstream decisions this task depends on
-Include relevant decision context in your pipeline output.
+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 8: Build the Pipeline
 Construct the phased dispatch plan with specific context for each agent.
 ## 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
 Architecture Lead enforces frontend-last phasing internally — you do not need to manage specialist sequencing.
 # 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):
-    - Architecture Lead: "<scoped architecture sub-task>"
+    - <Agent>: "<task>"
-    - Quality Lead: "<scoped verification sub-task>"
+    - <Agent>: "<task>"
  Staff (parallel with Phase 1 if independent):
    - DevOps Engineer: "<specific infrastructure question>"
-CONTEXT TRIGGERS TO WATCH:
+AGENTS DISPATCHED:
-  - If Architecture Lead reports unresolved cross-team conflict -> present to user
+  - <Agent Name>: dispatched via Agent tool ✓
-  - If Quality Lead flags critical security finding -> escalate immediately
+  - <Agent Name>: dispatched via Agent tool ✓
-RELEVANT PAST DECISIONS:
+SYNTHESIS (from agent outputs ONLY):
-  <summaries from orchestrator memory, or "None found">
+  - [Agent Name] Finding 1...
  - [Agent Name] Finding 2...
  - [Agent Name] Finding 3...
 CONFLICTS (if any):
  <disagreements between agents and resolution>
 ```
-**Context packaging for each lead/staff 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 lead
 - Relevant codebase locations (file paths, modules, directories)
 - Constraints from the overall task
 - Relevant past decisions from orchestrator memory
 - What other leads are working on in parallel (so they can flag cross-cutting concerns)
 - What deliverable you need back from them
 # Direct Dispatch
 You dispatch leads and staff directly using the `Agent` tool — you do NOT return a plan for the main session to execute.
 1. Build your pipeline (leads + staff, with phasing)
 2. Dispatch all Phase 1 agents using the Agent tool (parallel when possible)
 3. Collect results from all Phase 1 agents
 4. If Phase 2 agents depend on Phase 1 results, dispatch Phase 2 with the results
 5. Resolve inter-team conflicts between leads (see Conflict Resolution)
 6. Synthesize all lead outputs into a final recommendation
 7. Return the synthesis + recursive audit trail to the main session
 Include the DISPATCH CONTEXT object in every dispatch, starting with:
    call_chain: ["orchestrator"]
    current_depth: 1
 Architecture Lead enforces frontend-last phasing internally — you do not need to manage specialist sequencing.
 # 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 20 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?"
@@ -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
@@ -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
@@ -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
@@ -2,25 +2,60 @@
 ## The Rule
-This project has a 20-agent team organized in a 4-tier hierarchy (`.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.
+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.
-The orchestrator handles everything: it dispatches leads (Architecture Lead, Quality Lead, Product Lead), who in turn dispatch their specialists. Results bubble up with structured audit trails.
+**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. **Receive results** — the orchestrator returns a synthesized recommendation with a full audit trail of all agent calls
+3. **Select agents** — minimum viable team based on the task
-4. **Report results** — present the synthesis to the user, crediting which specialists contributed
+4. **Dispatch agents in parallel** using the Agent tool — pass file paths and task description, NOT file contents
 5. **Collect results** from all dispatched agents
 6. **Synthesize** — present the unified report to the user, crediting which specialists contributed
-You do NOT need to: dispatch individual agents, process handoffs, manage chain depth, or sequence phases. The orchestrator → lead → specialist hierarchy handles all of this internally.
+## Dispatch Context
-## Announcement Format
+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
-Always start with a brief announcement before dispatching the orchestrator:
+## Skip Agents ONLY For
-> Consulting with the developer team: dispatching orchestrator to [task summary].
+- 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 hierarchical agent system provides: autonomous agent-to-agent collaboration, structured guardrails (depth limits, loop prevention, cost control), full audit trails, and domain-expert analysis at every level. The orchestrator selects the right leads, leads select the right specialists, and each agent can consult others directly when needed.
@@ -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) { ... }
 ```
@@ -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
@@ -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.
@@ -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
@@ -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 |
@@ -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.
 ```
@@ -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.
 ```
@@ -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
@@ -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`
@@ -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/`.
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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.
 """
@@ -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"
@@ -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`.
@@ -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"
      ]
    }
  }
-}
+}
@@ -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.
@@ -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.
@@ -118,12 +118,14 @@ All user-facing UI text **must be in Russian**. The only exception is the brand
 ## Agent Team
-This project has a team of 20 agents organized in a 4-tier hierarchy: 1 orchestrator, 3 leads, 14 specialists, and 2 staff.
+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
-    Orchestrator (Tech Lead)
+    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
@@ -136,47 +138,47 @@ Agent files: `.claude/agents/`. Shared protocol: `.claude/agents-shared/team-pro
 **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. Architects and engineers may both be dispatched within the same task — the Architecture Lead sequences them.
+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).
 **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.
 ### Dispatch Loop
 1. **Announce**: "Consulting with the developer team to [task summary]"
-2. Dispatch the `orchestrator` agent with your analysis — it selects the right leads and dispatches them
+2. **Identify affected files** using Glob/Read (read-only — do NOT edit yet)
-3. The orchestrator handles everything: dispatches leads, leads dispatch specialists, results bubble up with audit trails
+3. **Dispatch agents in parallel** — pass file paths and task description (NOT file contents)
-4. **Credit specialists** in your final response — state which agents contributed
+4. **Collect results** from all agents
 5. Present results to user, **crediting which specialists contributed**
-### When to Use the Orchestrator
+Skip agents ONLY for: rename a variable, fix a typo, fix a single-line syntax
-
+error, answer a quick factual question, run a command the user explicitly asked for.
 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. Receive the orchestrator's synthesized results (includes full audit trail)
 4. Present results to the user
 Skip the Orchestrator ONLY for trivial tasks: rename a variable, fix a typo, answer a
 quick factual question.
 ### Dispatch Loop (Simplified)
 1. Dispatch orchestrator with task context
 2. Orchestrator handles everything internally (dispatches leads, collects results, resolves conflicts)
 3. Receive orchestrator's final synthesis (includes recursive audit trail of all agent calls)
 4. Present results to user with team credit summary
 You no longer need to: process handoffs, track chain history, enforce depth limits,
 re-invoke agents in continuation mode, dispatch individual specialists, or manage phasing.
 The orchestrator → lead → specialist hierarchy handles all of this.
 ### Conflict Handling
-If the orchestrator reports unresolved conflicts between leads:
+If dispatched agents report conflicting recommendations:
 - Present both perspectives 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
 When compacting, always preserve:
@@ -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).*
@@ -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).
@@ -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
@@ -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)
@@ -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.
@@ -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>
@@ -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)
@@ -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"
 			}
 		}
 	}
 }