<!-- source: openspec/_root/README.md -->

# OpenSpec — You Are Here

> This file is the entry point for every collaborator — human or AI — arriving at this repository's documentation corpus.
> Read it first. Then navigate to the section that matches your role.

---

## What this repo is

**Rapoport Studio** is a Moldovan SRL that builds digital platforms and AI infrastructure for businesses, corporations, and government entities. This repository is the studio's corporate platform: the public marketing site (`rapoport.studio`), the internal workspace (`app.rapoport.studio`), and the agent/CLI infrastructure that runs the studio's operating model. OpenSpec is the documentation backbone that ties it together — a corpus of markdown files that describes what the platform is, how it works, and how to change it, written in a form that both humans and AI agents can consume accurately.

---

## The 7 places to look

| Folder | What lives here | Who reads it first |
|---|---|---|
| `mirror/` | Per-brand perception specs — how each brand presents itself to the world. Will be renamed `brands/` in a future change (`bridge-vocabulary-and-restructure` Phase 3). | Brand strategists, designers, Pavel |
| `current/` | Capability specs — one file per platform concern (auth, home, forge, db, …). The canonical source of truth for running software. | Engineers, AI agents (Forge, Muse) |
| `entities/README.md` | Entity catalog — the 7-tier model of things the platform tracks in data. Split from `current/entities.md` by `bridge-vocabulary-and-restructure`. | Engineers, product designers |
| `changes/` | Active change proposals — each a `proposal.md` / `design.md` / `tasks.md` triple. Work in progress. | Forge agents, reviewers, Pavel |
| `archive/` | Applied changes — immutable historical record. Prefix-dated (`YYYY-MM-DD-<slug>/`). | Auditors, agents doing historical research, post-mortems |
| `_methodology/` | Studio methodology — charter, lifecycle, design-system rules, research. The "how we work" layer. | Onboarding agents, PMs/designers, new collaborators |
| `connections/` | Integration contracts — GitHub, Linear, and other external-system linkage. | DevOps, automation authors |

> **Note:** This README reflects the layout as of 2026-05-12. The `bridge-vocabulary-and-restructure` change renamed `mirror/` → `brands/` and split `current/entities.md` → `entities/` folder. Phase 4 (entities split) applied 2026-05-12.

---

## Navigation quick-links

| You want to… | Go to |
|---|---|
| Understand the platform | [`current/platform.md`](../current/platform.md) |
| Find a capability spec | [`current/`](../current/) |
| Find out what a term means | [`_root/glossary.md`](./glossary.md) ← **start here for vocabulary** |
| See the entity model | [`entities/README.md`](../entities/README.md) |
| Review an active proposal | [`changes/`](../changes/) |
| Read the studio charter | [`_methodology/studio-charter.md`](../_methodology/studio-charter.md) |
| Understand the change lifecycle | [`_methodology/lifecycle.yaml`](../_methodology/lifecycle.yaml) |
| See research backing decisions | [`_methodology/research/`](../_methodology/research/) |
| Check security posture | [`_root/risk-register.md`](./risk-register.md) |

---

## Quickstart by role

- **PM / Product designer** — Start at [`current/platform.md`](../current/platform.md) § Capability map. Read the glossary's Product/Design column to map your vocabulary to the studio's. Then look at active `changes/` to find the current sprint focus.

- **Engineer** — Read [`current/platform.md`](../current/platform.md) for the stack overview. Then the capability spec relevant to your task (`current/<capability>.md`). Check `CLAUDE.md` at the repo root for agent conventions and hard rules.

- **AI agent (Forge / Muse)** — Read `CLAUDE.md` first (root), then `openspec/AGENTS.md`, then `current/platform.md`, then the specific capability spec for your assigned task. The glossary ([`_root/glossary.md`](./glossary.md)) is mandatory reading before drafting any spec prose — especially Appendix 2 (banned terms) and Appendix 3 (defined-strictly).

- **Founder / client** — Read [`_methodology/studio-charter.md`](../_methodology/studio-charter.md) for the studio's operating model. The `current/platform.md` intro gives a product overview. For brand context, look at `mirror/<your-brand-slug>/perception.md`.

- **Brand strategist / designer** — Look at `mirror/` for per-brand perception. See the glossary § Brand vocabulary for the canonical terms (`Brand`, `Identity`, `Perception`).

- **Specialist (joining a project)** — Read the engagement charter at [`_methodology/rapoport-studio-engagement.md`](../_methodology/rapoport-studio-engagement.md). Then `current/platform.md`. Ask Pavel for the Linear issue that covers your scope.

- **New collaborator (any role)** — Read this file, then the glossary, then `_methodology/studio-charter.md`. Those three files give you 80% of the vocabulary you need to work productively in this repo.

---

## Where to ask questions / file issues

- **Platform questions** → Linear (`AI-` prefix issues). Tag Pavel.
- **Spec conflicts or ambiguity** → Open a change proposal in `changes/`. See `openspec/AGENTS.md` for the three-file convention.
- **Urgent / unblocked** → Telegram (primary), WhatsApp (secondary).
- **Code bugs** → GitHub issues or PR comments in the repository.
