Studio 2.0

.agent/notes.md

@@ -0,0 +1,9 @@
+# Agent Notes
+
+This file is for durable repo-specific learnings that help future work but do not yet belong as hard rules.
+
+## Usage
+
+- Put normative, repo-level guidance in `.agent/rules.md` or `.agent/rules/`.
+- Put useful learnings, reminders, heuristics, and recurring gotchas here when they are worth remembering but are not yet stable enough to be promoted into rules.
+- When a note becomes clearly normative or repeatedly important, move it into the relevant rules file.

.agent/rules.md

@@ -1,35 +1,35 @@
 # Agent Rules
 
-This is the canonical entry point for repository rules.
-
-Use this file as the quick-reference summary, then consult the focused rule files in `.agent/rules/` for the details that match the task.
-
-## Read First
-
-- Verify all changes with the appropriate test and lint commands before considering a task done.
-- Use the local `./venv` for backend commands.
-- Update tests when logic changes; do not weaken tests to fit broken behavior.
-- Keep wiki docs and `wiki/Changelog.md` aligned with shipped behavior.
-- Prefer manual verification by the user for UI changes unless they explicitly ask for browser-driven verification.
-- Treat filesystem paths as a security surface; follow the backend security/path rules.
-- Push back when the requested implementation is weaker than the better pattern already available in the repo.
-
-## Rule Map
-
-- [`verification.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/verification.md)
-  Test-first expectations, verification commands, and definition of done.
-- [`workflow.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/workflow.md)
-  Ownership, pushback, documentation, and manual verification expectations.
-- [`backend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend.md)
-  Progress/state consistency, worker sync, path safety, and backend structural guidance.
-- [`frontend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend.md)
-  UI consistency, accessibility, responsiveness, and frontend quality guidance.
-
-## Priority Order
-
-When rules overlap, follow them in this order:
-
-1. Verification and correctness
-2. Security and data safety
-3. User-visible behavior and documentation accuracy
-4. Maintainability and consistency
+This is the router for repository rules.
+
+## Task Map
+
+Use the smallest rule set that matches the task.
+
+1. Always read [`verification.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/verification.md) before calling code work complete.
+1. For frontend UI or UI-state work, read [`frontend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend.md), the relevant frontend subfile(s), and [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+1. For frontend state ownership or overlays, read [`frontend-state.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend-state.md) plus [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+1. For frontend UX, recovery, waiting, or editor-flow work, read [`frontend-ux.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend-ux.md) plus [`frontend-state.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend-state.md) when state ownership is involved.
+1. For frontend interaction, styling, semantics, or responsive layout work, read [`frontend-interactions.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/frontend-interactions.md).
+1. For backend progress or ETA work, read [`backend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend.md), [`backend-progress.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-progress.md), and usually [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+1. For artifact publication or recovery work, read [`backend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend.md), [`backend-artifacts.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-artifacts.md), and usually [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+1. For backend path handling, read [`backend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend.md) and [`backend-paths.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-paths.md).
+1. For routing, service boundaries, queue policy, or migration shape, read [`backend.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend.md), [`backend-boundaries.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-boundaries.md), and [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+1. For plan, rollout, or documentation changes, read [`workflow.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/workflow.md) and usually [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md).
+
+## What Matters Most
+
+- Verify changes with the relevant tests and linting before calling work complete.
+- Use the local `./venv` for backend tooling.
+- Update tests when behavior or logic changes.
+- Fix concrete bugs or regression risks in the same pass.
+- Keep implementation docs, wiki pages, and `wiki/Changelog.md` aligned with shipped behavior.
+- Treat paths, assets, and output publication as security-sensitive.
+- Prefer the better long-term boundary when a quick fix would deepen worker-centric or UI-state coupling.
+
+## Rule Ownership
+
+- The agent owns the organization and maintainability of `.agent/rules.md`, `.agent/rules/`, and related agent guidance files.
+- The agent may restructure, split, rename, cross-link, and refine these rule files without asking for additional permission when doing so improves discoverability, routing, or long-term usability.
+- Normative, repo-level guidance should live in the rules files.
+- Durable repo learnings, heuristics, and reminders that are useful to the agent but are not yet normative rules may be stored in [`notes.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/notes.md).

.agent/rules/backend-artifacts.md

@@ -0,0 +1,12 @@
+# Backend Artifacts
+
+Use this file for completion checks, artifact publication, recovery, and cache safety.
+
+## Core Rules
+
+- Raw file existence alone is never enough to mark render work complete.
+- Validated artifact manifests plus canonical persistence state determine whether output is reusable.
+- Publish generated outputs atomically: temp file first, validate, write manifest, then promote into the final artifact location.
+- Shared cached artifacts must be immutable once published.
+- When job state is re-queued, recovered, or invalidated, clear stale runtime metadata and recalculate status from canonical state.
+- If a revision changes, mark prior artifacts stale explicitly rather than silently treating them as valid.

.agent/rules/backend-boundaries.md

@@ -0,0 +1,13 @@
+# Backend Boundaries
+
+Use this file for routing, service layers, queue policy, and legacy migration boundaries.
+
+## Core Rules
+
+- Route handlers should call domain services and orchestrator services, not engine-specific or worker-specific code directly.
+- Engine wrappers must not decide scheduling policy.
+- Queue tasks must declare resource needs; they must not acquire ad-hoc locks scattered through task code.
+- Keep domain logic, orchestration logic, engine integration, and infrastructure concerns in separate modules.
+- Prefer explicit repositories and services over ad-hoc data access from route handlers and workers.
+- During migration, compatibility adapters are acceptable, but they should live in explicit legacy or adapter layers.
+- Do not let temporary migration code redefine the long-term architecture.

.agent/rules/backend-paths.md

@@ -0,0 +1,16 @@
+# Backend Paths
+
+Use this file for request-derived filesystem paths, scanned directories, and containment checks.
+
+## Core Rules
+
+- Treat any filesystem path derived from request data, DB values, uploaded filenames, or user-editable names as untrusted.
+- For existing files or directories, prefer enumerating a trusted root and matching by `entry.name`.
+- For new paths, use the explicit containment pattern that CodeQL recognizes well:
+  1. validate with a strict regex
+  2. build with `os.path.join(...)`
+  3. normalize with `os.path.normpath(...)`
+  4. absolutize with `os.path.abspath(...)`
+  5. verify the result stays under the trusted root before reading or writing
+- Reject traversal-style input instead of silently “fixing” it.
+- Do not hide security-critical path creation in vague helpers.

.agent/rules/backend-progress.md

@@ -0,0 +1,10 @@
+# Backend Progress
+
+Use this file for ETA, progress, and WebSocket state consistency rules.
+
+## Core Rules
+
+- WebSocket progress values must be rounded to exactly 2 decimal places.
+- Only broadcast progress updates when the value advances meaningfully, the status changes, or the event carries important new context.
+- Queue and progress services own progress math. Do not duplicate ETA or completion logic inside engine wrappers or route handlers.
+- Parent-child job behavior should be modeled explicitly rather than inferred from filenames or loose naming conventions.

.agent/rules/backend.md

@@ -1,33 +1,22 @@
 # Backend Rules
 
-## Progress And State Consistency
+Use this file when the task touches backend orchestration, queueing, progress, artifact publication, or filesystem path handling.
 
-- WebSocket progress values must be rounded to exactly 2 decimal places.
-- Only broadcast progress updates when the value advances by at least 1%.
-- When a job is re-queued, reset, or recovered, clear stale metadata such as logs, timestamps, progress, and warnings.
-- Disk state is the source of truth when UI status and actual files disagree.
+## Read The Right Subfile
 
-## Technical Environment
+- [`backend-artifacts.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-artifacts.md) for manifest validation, publish flow, cache immutability, and recovery safety.
+- [`backend-progress.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-progress.md) for progress math, ETA rules, rounding, and update throttling.
+- [`backend-boundaries.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-boundaries.md) for route/service/engine boundaries and migration discipline.
+- [`backend-paths.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-paths.md) for request-derived paths and containment checks.
 
-- Always use the local `./venv` for backend tooling.
-- When worker threads update `j` objects, follow up with `update_job` so the WebSocket bridge receives the change.
+## Load Order
 
-## Path Safety And Code Scanning
+1. [`backend-progress.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-progress.md) for ETA, rounding, and progress consistency.
+1. [`backend-artifacts.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-artifacts.md) for publish/recovery/immutability.
+1. [`backend-paths.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-paths.md) for any request-derived path handling.
+1. [`backend-boundaries.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/backend-boundaries.md) for routing, orchestration, queue policy, and migration shape.
 
-- Treat any filesystem path derived from request data, DB values, uploaded filenames, or user-editable names as untrusted.
-- For existing files or directories, prefer enumerating a trusted root and matching by `entry.name`.
-- For new paths, use the explicit containment pattern that CodeQL recognizes well:
-  1. validate with a strict regex
-  2. build with `os.path.join(...)`
-  3. normalize with `os.path.normpath(...)`
-  4. absolutize with `os.path.abspath(...)`
-  5. verify the result stays under the trusted root before reading or writing
-- For filenames and profile names, require flat single-segment names unless nested paths are truly intentional.
-- Reject traversal-style input instead of silently “fixing” it.
-- Avoid hiding security-critical path creation in generic helpers unless the helper exactly mirrors the accepted containment shape and has already been proven scanner-safe.
-- When code scanning regresses, export the latest `code-scanning-alerts.json`, group by rule and file, and fix the current highest-concentration sink lines directly before broad refactors.
+## Pair With
 
-## Structural Guidance
-
-- If a file exceeds 500 lines, consider splitting it along real logical boundaries.
-- Refactor carefully to avoid circular dependencies or scattering tightly coupled logic across too many files.
+- [`modular_architecture.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/modular_architecture.md) for Studio 2.0 boundary rules.
+- [`verification.md`](/Users/stevendunn/GitHub-Steven/audiobook-factory/.agent/rules/verification.md) for the required backend test and lint verification.

.agent/rules/codex_antigravity_collaboration.md

@@ -0,0 +1,50 @@
+# Codex and Antigravity Collaboration
+
+Use this file when Antigravity/Gemini is working as an implementation worker whose output will be reviewed by Codex and the user.
+
+## Role
+
+- Act as a bounded worker, not the architect of last resort.
+- Follow the user or Codex prompt exactly before expanding scope.
+- If a requirement is ambiguous, choose the smallest safe implementation and state the assumption.
+- Prefer boring, explicit, testable code over clever abstractions.
+
+## Handoff Discipline
+
+- Start by identifying the exact files and behavior you intend to touch.
+- Do not modify unrelated files, formatting, or tests opportunistically.
+- Keep temporary reproduction files out of the final diff unless explicitly requested.
+- Remove scratch files, root `node_modules`, transient DB files, logs, and command output files before handoff.
+- Never delete tracked files as cleanup unless the prompt explicitly asks for that deletion.
+- End every response with: changed files, tests run, exact pass/fail result, remaining risks, and any artifacts left behind.
+
+## Implementation Rules
+
+- Preserve user and Codex changes. Do not revert work you did not make.
+- Use existing APIs and seams before creating new ones.
+- Keep UI components generic. Do not put queue-, chapter-, or segment-specific policy inside reusable display components.
+- Use status as the source of truth for job phase. Do not reintroduce progress sentinel hacks such as `0.01` meaning "running".
+- New durable Studio 2.0 state belongs in SQLite, not `state.json`.
+- Legacy `state.json` reads are acceptable only as migration or compatibility shims, and should remove migrated data when safe.
+- For render performance metrics, only successful terminal `done` runs may train history. Failed, cancelled, running, cached, or partial runs must not.
+- ETA fields from backend progress updates are `remaining_from_update` unless explicitly documented otherwise.
+- Avoid stale event rebroadcasts. Only include ETA/progress metadata when it is fresh or intentionally persisted.
+
+## Testing Rules
+
+- Add or update tests for every behavior change.
+- Do not weaken tests just to match a broken implementation.
+- If a test expectation changes, explain the product reason.
+- Run the narrow relevant tests first, then the broader targeted suite.
+- For this repo, backend verification usually starts with:
+  `./venv/bin/python -m pytest tests/test_startup_eta.py tests/test_progress_logic.py tests/test_websocket_broadcast.py`
+- For queue/progress frontend verification, use:
+  `cd frontend && PATH=$PATH:/opt/homebrew/bin npx vitest run src/components/PredictiveProgressBar.test.tsx src/components/GlobalQueue.test.tsx src/components/queue/GlobalQueueFiles.test.tsx`
+- If full tests or linting are requested and fail, report the exact failing test, error, and likely cause.
+
+## Review Readiness
+
+- Before handoff, run `git status --short` and inspect the diff.
+- Flag unexpected dirty files instead of silently including them.
+- If a root-level dependency directory or transient DB appears, treat it as an artifact to clean or explicitly call out.
+- Do not claim "no further changes required" if artifacts, failing tests, unverified migrations, or unclear behavior remain.

.agent/rules/frontend-interactions.md

@@ -0,0 +1,11 @@
+# Frontend Interactions
+
+Use this file for styling decisions, component boundaries, semantics, and layout responsiveness.
+
+## Core Rules
+
+- Prefer theme variables over hardcoded colors.
+- Preserve focus behavior, keyboard access, and semantics.
+- High-level interaction logic should use reliable state and clear component boundaries rather than fragile styling hacks.
+- Keep layouts usable on desktop and mobile.
+- Sticky controls and two-pane layouts must degrade gracefully on smaller screens.

.agent/rules/frontend-state.md

@@ -0,0 +1,10 @@
+# Frontend State
+
+Use this file for API-backed entities, live overlays, reconnect state, and local session state ownership.
+
+## Core Rules
+
+- Canonical entities such as projects, chapters, blocks, voices, and settings belong to API-backed data loading.
+- The frontend store owns live overlays, reconnect state, notifications, and local session state.
+- Do not let the store become a second database.
+- Do not infer canonical completion state from local UI assumptions or stale props.

.agent/rules/frontend-ux.md

@@ -0,0 +1,11 @@
+# Frontend UX
+
+Use this file for waiting/error/recovery states, user trust, and editor workflow expectations.
+
+## Core Rules
+
+- Every meaningful screen change must account for loading, empty, error, reconnecting, interrupted, and recovered states.
+- Prefer interfaces that explain why something is waiting or stale instead of hiding behind generic spinners.
+- Fast local editing is required, but canonical persistence must remain trustworthy.
+- Mark edited, stale, queued, rendering, rendered, and failed states explicitly.
+- Inline recovery actions are preferred over forcing users to leave the editor for common fixes.