improved tools for ai

docs/ai-policy.md

@@ -0,0 +1,73 @@
+# AI Execution Policy
+
+Purpose: define what autonomous AI can do in this repository without explicit human approval.
+
+## Default Mode
+
+- AI may implement and debug within approved scope.
+- AI must run validation commands after code changes.
+- AI must stop and escalate when blocked by policy or ambiguity.
+
+## Allowed Autonomous Actions
+
+1. Edit frontend, backend, shared schema, docs, and scripts.
+2. Add/modify tests related to the task.
+3. Run non-destructive validation commands.
+4. Update project docs and Copilot instructions when behavior changes.
+
+## Restricted Actions (Require Approval)
+
+1. Security/privacy-sensitive logic changes.
+2. Data migrations or destructive file operations.
+3. Credential handling changes or secrets management changes.
+4. Breaking API/schema changes.
+5. Build/release signing, packaging, and deployment automation changes.
+
+## Prohibited Actions
+
+1. Destructive git commands (`git reset --hard`, force pushing protected branches).
+2. Deleting user project/media data.
+3. Bypassing required checks in CI.
+
+## Required Validation Workflow
+
+For each autonomous task:
+
+1. Implement smallest safe change set.
+2. Run lint/type/test/build checks for impacted scope.
+3. Inspect errors and fix with bounded retries.
+4. Re-run checks until green or escalated.
+5. Produce concise summary with risks and assumptions.
+
+## Escalation Triggers
+
+AI must ask a human when:
+
+1. Requirements are ambiguous and affect user-visible behavior.
+2. Multiple product choices are plausible with no clear preference.
+3. Potential legal, security, or compliance impact exists.
+4. CI remains failing after 3 repair attempts in the same area.
+5. A requested operation conflicts with this policy.
+
+## Required Artifacts In AI PR/Change Summary
+
+1. What changed.
+2. Why it changed.
+3. Validation commands and outcome.
+4. Residual risks.
+5. Follow-up tasks.
+
+## Risk Levels
+
+- Low: docs, styling, isolated refactors, non-critical bugfixes.
+- Medium: feature additions with contract-stable behavior.
+- High: API/schema/security/export pipeline/transcription pipeline changes.
+
+High-risk changes require explicit human review before merge.
+
+## TalkEdit-Specific Rules
+
+1. Preserve compatibility for desktop bridge contracts unless explicitly approved.
+2. Keep routers thin and business logic in backend services.
+3. Export/transcription pipeline changes must include regression tests.
+4. Linux WebKit startup behavior and media URL consistency are mandatory regression targets.

docs/runbooks/error-codes.md

@@ -0,0 +1,113 @@
+# Error Codes Runbook
+
+Purpose: provide consistent, AI-readable error categories for faster autonomous debugging.
+
+## Format
+
+Use codes in this format: `<SUBSYSTEM>-<CATEGORY>-<ID>`
+
+Examples:
+
+- `BE-EXPORT-001`
+- `FE-WAVEFORM-002`
+- `HOST-BRIDGE-003`
+
+## Backend (FastAPI / Services)
+
+### Export
+
+- `BE-EXPORT-001`: Export request validation failed.
+  - Symptoms: HTTP 400, missing/invalid ranges.
+  - Likely causes: malformed payload, empty segments.
+  - First checks: request body shape, keep/mute/gain ranges.
+
+- `BE-EXPORT-002`: FFmpeg command failed.
+  - Symptoms: HTTP 500, stderr contains filter/codec error.
+  - Likely causes: invalid filter chain, unsupported codec/container.
+  - First checks: generated FFmpeg args, source media codec, target format.
+
+- `BE-EXPORT-003`: Caption burn-in/subtitle generation failed.
+  - Symptoms: burn-in export fails while plain export works.
+  - Likely causes: ASS generation issue, subtitle path/temp file cleanup race.
+  - First checks: ASS file generation, temp file lifecycle.
+
+### Transcription
+
+- `BE-TRANSCRIBE-001`: Model unavailable or download failure.
+  - Symptoms: transcription never starts or exits early.
+  - Likely causes: missing model, network/cache issue.
+  - First checks: model cache path, ensure-model logs.
+
+- `BE-TRANSCRIBE-002`: Inference pipeline runtime failure.
+  - Symptoms: mid-run crash, partial output.
+  - Likely causes: CUDA/CPU mismatch, unsupported media, resource exhaustion.
+  - First checks: environment, GPU availability, media decoding logs.
+
+### Audio / Waveform
+
+- `BE-AUDIO-001`: Waveform endpoint failed.
+  - Symptoms: waveform panel shows unavailable/error.
+  - Likely causes: decode error, invalid file path, unsupported media input.
+  - First checks: `audio/waveform` response body, file existence, FFmpeg decode path.
+
+## Frontend (React)
+
+### Timeline / Zones
+
+- `FE-TIMELINE-001`: Zone interaction state inconsistency.
+  - Symptoms: cannot drag/select/delete zones predictably.
+  - Likely causes: stale selection/editing state, hidden/selected mismatch.
+  - First checks: zone mode flags, selectedZone state transitions.
+
+- `FE-TIMELINE-002`: Visibility filter mismatch.
+  - Symptoms: hidden zones still interactive or selected.
+  - Likely causes: hit-testing ignores visibility flags.
+  - First checks: hit-test filters and selected-zone reset logic.
+
+### Media UI
+
+- `FE-WAVEFORM-001`: Waveform fetch failed.
+  - Symptoms: warning banner with URL/error.
+  - Likely causes: backend unavailable, bad path encoding, CORS/proxy issue.
+  - First checks: backend health endpoint, waveform URL, network tab logs.
+
+- `FE-PROJECT-001`: Project load mismatch.
+  - Symptoms: loaded media/transcript differs from saved data.
+  - Likely causes: schema drift, fallback URL mismatch.
+  - First checks: project schema fields, loadVideo/loadProject URL parity.
+
+## Host / Bridge (Tauri)
+
+- `HOST-BRIDGE-001`: Desktop API bridge unavailable.
+  - Symptoms: open/save/transcribe actions no-op or throw.
+  - Likely causes: bridge init error, host command mismatch.
+  - First checks: bridge initialization, command names, runtime environment.
+
+- `HOST-WEBKIT-001`: Linux WebKit startup/render regression.
+  - Symptoms: noisy startup errors, UI load issues.
+  - Likely causes: CSP/font regressions, unsupported protocol calls.
+  - First checks: CSP config, remote font usage, bridge fallback behavior.
+
+## Logging Guidance
+
+When raising errors, include:
+
+1. Error code.
+2. Human message.
+3. Correlation/request id.
+4. Relevant paths/ids (sanitized).
+5. Suggested first-check hints.
+
+Example structured payload:
+
+```json
+{
+  "code": "BE-EXPORT-002",
+  "message": "FFmpeg export failed",
+  "requestId": "exp_20260415_001",
+  "context": {
+    "format": "mp4",
+    "mode": "reencode"
+  }
+}
+```

docs/spec-template.md

@@ -0,0 +1,113 @@
+# Feature Spec Template
+
+Use this template for every net-new feature and major behavior change.
+
+## Metadata
+
+- Spec ID: SPEC-YYYYMMDD-<short-name>
+- Owner:
+- Date:
+- Status: draft | approved | in-progress | done
+- Related issue/PR:
+
+## Problem Statement
+
+Describe the user problem in 2-5 sentences.
+
+## User Story
+
+As a <user type>, I want <capability>, so that <outcome>.
+
+## Scope
+
+### In Scope
+
+1. 
+2. 
+3. 
+
+### Out of Scope
+
+1. 
+2. 
+
+## Functional Requirements
+
+1. 
+2. 
+3. 
+
+## Acceptance Criteria
+
+1. Given <state>, when <action>, then <result>.
+2. Given <state>, when <action>, then <result>.
+3. Failure handling is deterministic and user-visible.
+
+## UX Notes
+
+- Entry points (toolbar/panel/command):
+- Empty/loading/error states:
+- Keyboard shortcuts / accessibility expectations:
+
+## API And Data Contracts
+
+- Endpoints impacted:
+- Request/response changes:
+- Backward compatibility plan:
+- Project schema impact (`shared/project-schema.json`):
+
+## Architecture Impact
+
+- Frontend files/components likely affected:
+- Backend routers/services likely affected:
+- Tauri/bridge changes required:
+
+## Risks
+
+1. 
+2. 
+
+## Test Plan
+
+### Unit Tests
+
+1. 
+2. 
+
+### Integration Tests
+
+1. 
+2. 
+
+### E2E / Smoke Tests
+
+1. 
+2. 
+
+### Regression Tests
+
+List known regressions this spec must prevent.
+
+## Observability
+
+- New logs/error codes:
+- Metrics/traces needed:
+- Diagnostics artifacts expected on failure:
+
+## Rollout Plan
+
+1. Development and internal validation.
+2. Staged rollout or feature flag (if applicable).
+3. Rollback path.
+
+## Open Questions
+
+1. 
+2. 
+
+## Definition Of Done
+
+1. Acceptance criteria pass.
+2. Tests added and green.
+3. Docs/instructions updated.
+4. Risks and assumptions recorded in PR summary.