AGENTS.md

# MediaRouter — AGENTS.md

## Mission

MediaRouter is an enterprise media automation platform. Development must preserve production-grade reliability, security, explicit capability gating, authoritative backend contracts, and Hugging Face Spaces compatibility.

The repository contains backend, frontend, SDK, n8n, MCP, AI, media-processing, publishing, analytics, collaboration, template, project, and Content Studio functionality.

## Operating Rules

1. Do not fabricate backend capabilities, provider support, assets, jobs, analytics, templates, or persistence.
2. Backend contracts are authoritative. Frontend capability discovery must follow actual API/OpenAPI support.
3. Never weaken authentication, authorization, PostgreSQL RLS, CORS, rate limiting, validation, or production configuration to make tests pass.
4. Do not introduce a SQLite production fallback.
5. Do not claim runtime verification when the relevant runtime was not actually exercised.
6. Do not silently replace real provider/model operations with mocks or fake success paths.
7. Preserve backward compatibility unless a migration explicitly requires a breaking change.
8. Database migrations are additive unless a destructive change is explicitly required, reviewed, and safely migrated.
9. All durable resources must have explicit ownership, workspace isolation, permission enforcement, and audit behavior.
10. Never store credentials, tokens, secrets, signed URLs, editor documents, or sensitive provider payloads in logs or audit metadata.
11. Keep Hugging Face Spaces as a supported deployment boundary. Backend containers must bind to port 7860.
12. Prefer deterministic behavior and explicit failure over optimistic/fake behavior.
13. When a feature lacks an authoritative backend contract, hide or disable the feature with a truthful reason.
14. Do not perform final production certification until all planned product phases are complete.
15. Phase 13 and later features may be added after the current feature set; do not prematurely implement them during stabilization work.

## Architecture

### Backend

Use layered architecture:

- API: FastAPI routers, validation, authentication dependencies, response schemas.
- Service: business rules and orchestration.
- Repository: persistence and query boundaries.
- Model: SQLAlchemy domain models.
- Worker: durable asynchronous jobs and provider/media execution.
- Security: authentication, authorization, scopes, workspace context, RLS, audit.
- Migration: PostgreSQL schema changes and security policies.

### Frontend

Use feature-oriented modules:

- API/query layer for authoritative backend resources.
- TanStack Query for server state.
- Zustand only for local/editor interaction state where appropriate.
- Capability discovery from runtime/backend contracts.
- Explicit loading, empty, unavailable, and error states.
- Accessible keyboard and responsive behavior.

### SDK / n8n / MCP

All integrations must map to real backend contracts.

- TypeScript SDK: typed resources and errors.
- Python SDK: typed resources and errors.
- n8n: explicit operation schemas and backend-compatible requests.
- MCP: narrow, typed, permission-aware tools; never expose unrestricted generic execution.

## Database and Security

Production uses PostgreSQL.

RLS must be enforced for workspace-owned resources where required. Tests must verify cross-workspace isolation using separate users/roles where the environment supports it.

Every new durable resource must consider:

- workspace ownership
- creator/actor
- lifecycle/status
- timestamps
- indexes
- foreign keys
- constraints
- RLS
- permissions/scopes
- audit events
- idempotency
- concurrency/revision behavior
- deletion/archive semantics

Never use reserved SQLAlchemy Declarative attributes such as `metadata` directly as Python model attributes. Map them to safe Python names when the database column must remain `metadata`.

## Production Boundary

The target deployment is Dockerized Python 3.10 on Hugging Face Spaces.

Expected production characteristics:

- Python 3.10
- pinned dependencies
- FastAPI/Uvicorn
- port 7860
- PostgreSQL
- PostgreSQL RLS
- FFmpeg/FFprobe where media processing requires them
- stateless container filesystem
- durable external media/data storage
- explicit environment variables
- production CORS
- safe error responses
- structured logging

SQLite may be used only as an explicitly bounded development/test backend when supported by the codebase.

## Change Discipline

Before modifying code:

1. Inspect existing architecture.
2. Find the authoritative backend route/schema/service.
3. Find existing patterns for the same resource type.
4. Preserve naming and migration conventions.
5. Identify affected tests and integration points.
6. Make the smallest correct change.

After modifying code:

1. Compile/import.
2. Run focused tests.
3. Run relevant domain tests.
4. Run frontend typecheck/lint/build where applicable.
5. Run SDK/n8n/MCP checks where applicable.
6. Review the final diff.
7. Report environment blockers honestly.

## Error Handling

Never fix a runtime error by deleting imports or disabling the subsystem without understanding the dependency chain.

For startup failures:

1. Read the complete traceback.
2. Fix the first application-level root cause.
3. Re-run startup.
4. Continue until application import/startup is clean.
5. Then validate health and OpenAPI.

For database failures, distinguish:

- model error
- migration error
- fixture error
- PostgreSQL configuration error
- RLS error
- environment limitation

## Status Vocabulary

Use only:

- PASS — actually verified.
- FAIL — verification ran and failed.
- BLOCKED — verification could not run because of the environment.
- NOT VERIFIED — no verification was performed.
- PARTIAL — implementation exists but one or more required verification layers remain incomplete.
- DEFERRED — intentionally postponed by project scope.

Never convert BLOCKED into PASS.

## Current Project Direction

Feature development continues before final hardening/certification.

Production certification is intentionally deferred until all planned MediaRouter product features are implemented.

The current priority for stabilization work is eliminating confirmed startup/import/model/authentication/frontend contract defects without adding new product features.