Upload 376 files

AGENTS.md

@@ -0,0 +1,168 @@
+# 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.

app/projects/models/rendering.py

@@ -12,6 +12,7 @@ from sqlalchemy import (
     JSON,
     String,
     Text,
+    UniqueConstraint,
 )
 from sqlalchemy.orm import Mapped, mapped_column
 

docs/ai-copilot.md

@@ -1,5 +1,13 @@
 # AI Copilot
 
+## Status
+
+AI Copilot is implemented in the current working tree as a bounded,
+server-authoritative orchestration layer with durable runs, typed actions,
+scope enforcement, and MCP transport. Provider credential certification,
+PostgreSQL/RLS runtime verification, Docker, and Hugging Face startup remain
+deferred until all planned product phases are complete.
+
 AI Copilot is a validated orchestration layer over existing MediaRouter
 services. It does not execute arbitrary model output and does not duplicate
 project, asset, editor, AI Studio, generation, or render business logic.

docs/analytics.md

@@ -1,5 +1,13 @@
 # MediaRouter Analytics & Insights
 
+## Status
+
+The current working tree implements the bounded Analytics service at
+`app/analytics/`, exposes `/v1/analytics` routes, and provides frontend,
+TypeScript/Python SDK, MCP, and n8n transport surfaces. PostgreSQL schema,
+RLS certification, Docker/Hugging Face runtime verification, and provider
+certification remain deferred until all planned product phases are complete.
+
 ## Architecture
 
 Phase 10 extends the authoritative Social analytics boundary. Provider calls

docs/brand-kits.md

@@ -0,0 +1,66 @@
+# Brand Kit
+
+## Status
+
+The current working tree implements Brand Kit as a real workspace-owned domain
+under `app/brand/` with `/v1/brand` REST routes, frontend brand-kit feature
+modules, TypeScript/Python SDK resources, MCP brand tools, and an n8n
+`MediaBrandKit` node. Authoritative PostgreSQL migrations, RLS runtime
+certification, Docker/Hugging Face runtime verification, and final production
+certification remain deferred until all planned product phases are complete.
+
+## Domain model
+
+`BrandKit` and `BrandKitVersion` are the canonical records. A kit owns versions
+through `brand_kit_versions`, includes workspace/creator ownership fields, and
+tracks `status`, timestamps, and an `active_version_id`. Versions store bounded
+branding fields such as colors, fonts, voice/tone metadata, asset references,
+watermark settings, and a `metadata` JSON column mapped safely away from the
+SQLAlchemy reserved `metadata` attribute.
+
+## API
+
+| Method | Endpoint | Purpose |
+|---|---|---|
+| `GET` | `/v1/brand` | List workspace brand kits with active version metadata. |
+| `POST` | `/v1/brand` | Create a workspace brand kit. |
+| `PATCH` | `/v1/brand/{brand_kit_id}` | Update a workspace brand kit. |
+| `DELETE` | `/v1/brand/{brand_kit_id}` | Delete a workspace brand kit. |
+
+`POST /v1/brand` accepts `name`, optional `description`, and `initial_version`
+payload data. The response surface returns the kit plus its current
+`active_version_id`; it does not expose invitation tokens or secret fields.
+
+Version-specific brand-kit routes are **not exposed** in the current backend
+contract. Python and TypeScript SDKs therefore fail closed with
+`NotImplementedError` for `get_version` and `create_version` instead of
+inventing endpoints.
+
+## Frontend
+
+The frontend uses `/v1/brand` through `frontend/features/brand-kits/api/index.ts`.
+Brand kits appear in workspace settings navigation with `permission: "admin"`,
+and capability discovery treats the brand area as active when the backend
+advertises the expected routes.
+
+## SDK
+
+Both official SDKs use `/v1/brand` for list/get/create/update/delete operations.
+The Python client is defined in `sdk/python/media_platform/brand_kits.py`, and
+the TypeScript client is defined in `sdk/typescript/src/resources/brand-kits.ts`.
+Static contract tests verify route paths, request bodies, and fail-closed
+versioned-operation behavior.
+
+## MCP and n8n
+
+MCP registers narrow typed brand tools through `app/mcp/tools/brand.py` and
+`app/mcp/server.py`. The official n8n `MediaBrandKit` node consumes the shared
+MediaRouter SDK/credential boundary; no provider credentials or raw brand
+documents are exposed to n8n transports.
+
+## Security and runtime
+
+Brand kit routes reuse the existing API-key authentication, scoped workspace
+context, and structured audit boundary. Sensitive fields remain backend-only.
+PostgreSQL FORCE RLS, migration ordering, and provider-facing certification are
+intentionally deferred to the final production certification phase.

docs/publishing-operations-phase9.md

@@ -1,5 +1,13 @@
 # Publishing Operations — Phase 9
 
+## Status
+
+Publishing operations are implemented in the current working tree with durable
+unified jobs, calendar/queue/draft flows, retries, idempotency, and SDK/MCP/n8n
+transport coverage. PostgreSQL/RLS runtime verification, Docker, FFmpeg,
+Hugging Face startup, live provider certification, and final production
+certification remain deferred until all planned product phases are complete.
+
 ## Audit
 
 The Phase 8 audit found one authoritative publishing domain under

docs/template-marketplace.md

@@ -1,5 +1,13 @@
 # Template Marketplace
 
+## Status
+
+The template marketplace is implemented in the current working tree with bounded
+catalog CRUD, versioning, visibility, application, instantiation, frontend
+marketplace flows, and SDK/n8n/MCP coverage. PostgreSQL/RLS runtime
+verification, Docker, Hugging Face startup, and final production certification
+remain deferred until all planned product phases are complete.
+
 The Template Marketplace extends the existing `app/templates` domain without
 replacing the immutable YAML operation-template registry. Marketplace
 templates are authoritative database records whose versions contain only