<!-- source: openspec/current/studio-workspace/narrative.md -->

---
title: Studio Workspace — Narrative
status: stable
owner: pavel
audience: [pavel, ai, engineer]
tldr: Why the workspace exists and who it serves — the v1 Architect-mode authoring surface and the v2 out-of-scope fence.
---
# Studio Workspace — narrative

> Why this workspace exists, who it serves, and what is deliberately out of scope for v1.
> Behavioural contracts and route tables live in [`spec.md`](spec.md). Flows in [`flows.md`](flows.md).

---

## Status

**v1 implementation-ready.** The surface area, core authoring flow, and per-route purpose are fixed for the v1 layer (Architect mode). v2 expansion (intake, projects, clients, network, costs) is documented under § Out of scope (until v2). View-level design tokens and component breakdowns layer on top via `ui.md` / `design-system.md`.

---

## Goal

Ship Architect mode as Pavel's authoring surface for OpenSpec change proposals. v1 supports a single user (Pavel), four routes, and one core loop: open a canvas, converse with Muse to draft `proposal.md` / `design.md` / `tasks.md`, promote the triplet to `openspec/changes/<slug>/` on disk via a single action.

Everything else — intake from `/contact`, project workspace coordination, client roster, collaborator management, cost dashboards, multi-user — is v2 per `ROADMAP.md` layer ordering. See § Out of scope (until v2).

Authentication is magic-link via Supabase Auth; see `auth.md`. Single primary user (Pavel); selective access for collaborators arrives in v2+.

---

## Out of scope (until v2)

v1 ships only Architect mode. The following surface area is documented here so future readers know where it activates and what trade-offs were made for v1.

### v2 routes (not in v1)

| Route | v2 purpose |
|---|---|
| `/inbox` | Incoming intakes from `/contact` and Telegram intake — accept or decline |
| `/clients` | Client roster — Telegram group bindings, contact info |
| `/network` | Collaborator management — sync with the public `/network` page on `rapoport.studio` |
| `/costs` | Token usage + cost breakdown — by project, by model, by month |

### v2 workflows

- **Intake** from `/contact` form (web), Telegram `/link` command, and direct entry into `/inbox`. Lands rows in `studio.inbox` table. Client briefs and PDFs attached at intake are uploaded once through the Files API wrapper (`apps/studio/src/lib/files/`) and referenced by `file_id` on subsequent inference calls — never re-embedded as raw bytes. Uploads are tracked in the `ai_files` table with a bounded retention window plus an hourly sweep; a ZDR guard rejects uploads when the context is `zdr_required`. Contract source: `openspec/archive/2026-05-16-files-api-for-client-intake-canvas/`.
- **Acceptance** — `/inbox` row → "Accept" → creates Project + Linear project + Telegram group + bot binding.
- **Project execution coordination** — links Linear issues to Forge runs and PRs.
- **Network admin UI** — opt-in management for collaborators who appear on the public `/network` page.
- **Cost attribution and dashboards** — token usage rolled up per project, per model, per month.
- **Notification system** — in-app and email notifications for inbox events, project changes, PR review state.

### v2 bridge expansion

Both bridge endpoints exist today (see `spec.md § API surface`) as foundational scaffolds. The remaining work is the consumer-facing behavior:

- `/api/studio/intake` — Telegram bot `/note`, `/task`, `/done`, `/link`, free-text reactions. Today the route logs incoming payloads and returns `{ ok: true, received: true }`; Phase 6 (tracked as RAP-81) adds intent parsing, Linear ticket writes, and per-client `client_channels` lookup.
- `/api/studio/command` — Already routes Linear `create_task` / `read_tasks` for Pavel's personal Telegram. v2 expansion is the per-client routing surface (group-aware authentication, multi-tenant prompt context, n8n-managed dispatch).

### v2 platform expansion

- **Multi-user** — collaborator invitations, per-project access scopes, RLS rules beyond "Pavel-only."
- **Per-tab data models** — for the v2 project workspace (domain / creative / specs / pipeline tabs); per-tab component breakdowns.
- **Public Canvas mode** — the lead-capture surface that puts a Canvas-mode chat on `/` of the marketing apex (`web.md` host). See `muse.md § Vision` for Canvas mode definition.

---

## Related capabilities

- `platform.md` — overall context, capability map, operating model.
- `muse.md` — the AI substrate that powers v1's Architect mode at `/spec/[id]`. See `muse.md § Architect mode (v1)`.
- `ROADMAP.md` — single source of truth for layer ordering (v1 Architect → v1.2 Builder → v1.3 Scout → v2 Canvas).
- `design-system.md` — visual tokens, typography, animation, brand voice; addresses the workspace surface explicitly under § Surfaces › Studio (dark variant).
- `ui.md` — implementation package consumed by this app.
- `auth.md` — magic-link authentication, session shape, cookie domain handling.
- `web.md` — public marketing surface at `rapoport.studio` (sibling subdomain that shares the auth package).
