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

# OpenSpec Glossary

> Canonical vocabulary for Rapoport Studio's OpenSpec corpus.
> Three-column bridge table: **Studio canonical term → Product/Design/Engineering equivalent → Where it lives in the repo**.
>
> This file supersedes the original 7-term table in [`_methodology/studio-charter.md § 12`](../_methodology/studio-charter.md).
> The charter's table is kept as a historical baseline; this file is the canonical source from this point forward.
>
> Last updated: 2026-05-19 (Appendix 3 extension by `define-studio-product-model`).

---

## Main table — Studio canonical vocabulary

| Studio canonical term | Product / Design / Engineering equivalent | Repo location |
|---|---|---|
| **Brand** | Brand, Product brand, Client brand | `brands/<slug>/` |
| **Identity** | Brand identity, Brand standards, Style guide | `brands/<slug>/identity.md` |
| **Perception** | Brand image, Customer perception, Brand positioning | `brands/<slug>/identity.md § Perception` |
| **Capability** | Feature domain, Service, Module, Epic (Product), Bounded context (DDD) | `current/<capability>.md` |
| **Change** | RFC, ADR, Proposal, Ticket, User story (roughly) | `changes/<slug>/proposal.md` |
| **Proposal** | Problem statement + solution outline | `changes/<slug>/proposal.md` |
| **Design** | Technical design, Solution design, ADR, Engineering spec | `changes/<slug>/design.md` |
| **Tasks** | Acceptance criteria, Sprint tasks, Implementation checklist | `changes/<slug>/tasks.md` |
| **Narrative** | Story (product), User story arc, Page story | `current/<capability>.md` (within the spec) |
| **Surface** | UI surface, Product surface, Touchpoint | `current/<capability>.md § Surfaces` |
| **Primitive** | Component (React), UI component, Design token | `packages/ui/`, `current/design-system.md` |
| **Workspace** | Studio app, Internal dashboard, Back-office | `apps/studio/` → `app.rapoport.studio` |
| **Spec** (user-facing) | Working session, Doc, Document, the room a founder + Muse meet in | `apps/studio/src/app/(auth-walled)/(spec)/spec/[id]/`. **User-facing word per RAP-1252 D-CV-1.** In the DB the row is `idea` (the working session) under a parent `spec` (the deliverable document set: proposal/design/tasks/verification). Engineers see `idea*` in code identifiers; users see "Spec" in copy. The mismatch is intentional and recorded here so neither audience is surprised. |
| **Studio** (company) | The company; Rapoport Studio SRL | `_methodology/studio-charter.md` |
| **Curation** | Staffing model, Team composition, Talent sourcing | `_methodology/studio-charter.md § Curation` |
| **Engagement** | Project, Client project, Contract | `_methodology/rapoport-studio-engagement.md` |
| **Forge** | AI executor agent, Build bot, Code agent | `packages/forge/`, `current/forge/README.md` |
| **Muse** | Research agent, Design agent, Discovery agent | `packages/muse/`, `current/agents-overview.md` |
| **User persona** | Persona (UX/NN/g), Target user, Audience segment | `brands/<slug>/identity.md § Audience` |
| **Problem statement** | Problem definition, User need, Job to be done | `changes/<slug>/proposal.md § Problem` |
| **Success metric** | KPI, OKR, Acceptance criterion | `changes/<slug>/proposal.md § Why now` |
| **User flow** | Journey, Flow, Task flow | `current/<capability>.md § Flows` |
| **Hypothesis** | Assumption, Bet, Risk | `changes/<slug>/proposal.md § Risks` |
| **Acceptance criteria** | Done definition, Checkbox, Verification | `changes/<slug>/tasks.md § Checkpoint` |
| **NFR** | Non-functional requirement, Quality attribute, System property | `current/<capability>.md § Architecture` |

---

## Appendix 1 — Collision matrix (10 cross-school terms)

These terms carry different meanings across schools of thought that participate in studio projects. Every usage of these terms in spec prose MUST be prefixed or qualified to resolve ambiguity.

| Term | School / Context | Meaning in that school | Studio canonical | Must prefix? |
|---|---|---|---|---|
| **Capability** | Product Management | A business ability, e.g. "real-time pricing capability" | A first-class spec concern with its own `current/*.md` file | No — studio usage is aligned with Product and TOGAF |
| **Capability** | DDD | Application capability, CQRS handler | Same as above in studio context | No |
| **Capability** | TOGAF Business Architecture | A business capability with maturity levels | Same | No |
| **Eval / test** | AI/ML | Model evaluation, benchmark run | Not yet defined; use "test" for code tests, "eval" for model quality checks | Yes — specify "code test" or "model eval" |
| **Persona** | UX / NN/g | Fictional user archetype for design | "User persona" in studio spec prose | Yes — use "User persona" in spec prose |
| **Persona** | Marketing | Buyer persona / ICP | "Client profile" or "ICP" in studio prose | Yes |
| **Persona** | Lifecycle.yaml | Agent conversation role (architect/domain/tech/business/ops) | `persona_hint` in lifecycle.yaml only; NOT used in spec prose | Yes — this value lives in `lifecycle.yaml`, not in spec prose. Will be renamed `role_hint` in a future change. |
| **Voice** | Brand strategy | Brand's tone and communication style | `Identity § Voice` in brand files | No — used correctly in brand context |
| **Voice** | AI/LLM | Model voice or system-prompt persona | Not used in this sense in studio specs | Yes — specify "system prompt voice" |
| **Journey / Flow** | Product / UX | End-to-end user journey map | "User flow" in studio spec prose | No — both terms are acceptable |
| **Contract** | Engineering | Interface contract, API contract | "Interface contract" or "API contract" | Yes — specify which kind |
| **Contract** | Legal / engagement | Engagement contract, client agreement | "Engagement agreement" | Yes |
| **Postmortem / retro** | Engineering | Post-incident review | "Incident review" | No — either term acceptable |
| **Postmortem / retro** | Agile | Sprint retrospective | "Sprint retro" | No |
| **Golden dataset** | ML / AI | Benchmark dataset for model eval | Not yet a studio term | N/A — use "benchmark dataset" |
| **Risk** | Product (Cagan) | Value, usability, feasibility, viability risks | Risk as defined in `changes/<slug>/proposal.md § Risks` | No — studio usage aligned with Cagan |
| **Risk** | Security | Threat, vulnerability | See `_root/risk-register.md` | Yes — use "security risk" |
| **System card** | AI safety | Model card / transparency report | Not in current studio scope | N/A |
| **Service blueprint** | UX / service design | Cross-channel service process map | Not currently a studio artifact | N/A — if added, name it "service blueprint" explicitly |
| **Domain** | DDD | Bounded domain, problem space | Retired as a bare term in studio spec prose (see Appendix 2) | Yes — always qualify: "brand domain", "problem space", "Tier-2 entities" |
| **Domain** | Lifecycle.yaml | `persona_hint: domain` = business-domain conversation role | Lives in `lifecycle.yaml` only; acknowledged collision with DDD "Domain" | Yes — `domain` in lifecycle.yaml = conversation role, NOT a DDD concept |

---

## Appendix 2 — Banned in spec-prose

These four words MUST NOT appear as bare, unqualified terms in `openspec/current/**/*.md` or `openspec/brands/**/*.md`. They are too generic — a reader (human or AI) cannot determine meaning from context alone.

| Banned bare term | Why banned | Replacement(s) |
|---|---|---|
| **Context** | Maps to: React Context (code), LLM context window, DDD bounded context, English-word "context". All four appear in the same file. | Use: `Brand` (for brand context), `Engagement` (for project context), `Bounded scope` or `Capability scope` (for DDD), `LLM context window` (for AI), `React Context` (code — inline code only) |
| **Module** | Maps to: JS/TS module (code), feature module (product), TOGAF module, "module" as vague synonym for "thing". | Use: `Package` (for npm/code packages), `Capability` (for spec-level concerns), `TypeScript module` (inline code only) |
| **Component** | Maps to: React Component (code), UI component (design), TOGAF component, C4 component, architectural component. | Use: `Primitive` (for UI/design-system elements), `React component` (inline code only), `Capability` (for architectural), `Service` (for infrastructure) |
| **Domain** | Maps to: DDD domain (problem space), `persona_hint: domain` in lifecycle.yaml (conversation role), Tier-2 entities (previously called "Domain entities"). All three are present in this repo. | Use: `Brand` (for brand-level concerns), `Problem space` (for discovery framing), `Tier-2 entities` or `Persisted entities` (for the entity tier), `Conversation role` (for lifecycle.yaml), `domain` only inside `lifecycle.yaml` as a code value |
| **Canvas** | Retired by RAP-1170 / D-ATLAS-5 / RAP-1252. Maps to: (a) the abandoned Canvas v2 React Flow visualization product (`canvas.md`, `status: deprecated`); (b) the pre-rename `canvas_*` table family (replaced by `project → spec → idea → {messages, files}` in `archive/2026-05-23-rearchitect-spec-document-model/`); (c) the HTML `<canvas>` element. A reader cannot tell which from context. | Use: **`idea`** (the working-session entity that lives under `/spec/[id]`), **`spec`** (the deliverable document set / the user-facing word per RAP-1252 D-CV-1), or **`<canvas>`** only inside inline code when referring to the HTML element. `Canvas` as a bare term is allowed only inside `canvas.md` (the deprecated capability file itself) and inside historical-record references with an explicit date / archive pointer. |

> **Enforcement:** A lint rule (`tools/lint-spec-prose.mjs`, added in Phase 7 of `bridge-vocabulary-and-restructure`) will check these files automatically. See `Appendix 2 note` below.
>
> **Exceptions allowed by the lint rule:** `React Context`, `React Component`, `JS module`, `TypeScript module` — these are valid technical references that may appear in inline code spans.

---

## Appendix 3 — Defined strictly

Six terms with two-line definitions: what it IS and what it is NOT.

---

### Studio

**Is:** The company — Rapoport Studio SRL. A Moldovan SRL building digital platforms and AI infrastructure. The legal entity, the brand, the operating model.

**Is not:** The workspace app (`apps/studio` → `app.rapoport.studio`). That is called **Workspace** in spec prose when the distinction matters (e.g., "the Workspace surfaces Linear issues"). In conversational English and in company branding, "Studio" still refers to the company. In code paths and spec-level descriptions of the app, prefer "Workspace".

---

### Surface

**Is:** A distinct UI surface where a capability is presented — defined by its runtime host (web page, Telegram bot, mobile screen) and its audience. Examples: the marketing site (`rapoport.studio`), the workspace (`app.rapoport.studio`), the Telegram canvas-bot.

**Is not:** A React component, a route, a page. A surface contains many routes and components. A component is a Primitive.

---

### Primitive

**Is:** An atomic UI building block in the design system (`packages/ui/`). Button, Card, Typography, Input. Maps 1:1 to a React component in the codebase. Has a Figma counterpart.

**Is not:** A capability, a feature, a page section. A Primitive is the smallest reusable unit of UI. Above Primitive is a Composite (a combination of Primitives), then a Block, then a Section, then a Page.

---

### Capability

**Is:** A first-class platform concern tracked with its own `openspec/current/<slug>.md` spec file. It has an owner, a lifecycle, and it evolves independently of other capabilities. Examples: `auth`, `home`, `forge`, `canvas`.

**Is not:** A feature, a user story, a React component, a database table. A Capability is the unit of architectural ownership in the OpenSpec corpus. Features live within capabilities; they don't get their own capability spec.

---

### Curation

**Is:** The studio's staffing and operating model. Each engagement assembles a hand-picked team of specialists from the network — not a fixed staff. Pavel is the orchestration anchor; the team is fluid per project. "Curated-team model" is the full phrase.

**Is not:** Content curation (editorial), data curation (ML), code review. In studio spec prose, "Curation" always refers to the team-assembly operating model.

> **Cross-reference:** Curation describes *how teams are staffed*. The runtime expression of curation — *which tools, research agents, and skills each specialist receives when they enter the chat* — is scoped to a separate future capability (`add-specialist-tool-composition`). The two are paired: Curation chooses the team; the ecosystem provisions their tools.

---

### Identity

**Is:** A brand's self-definition — name, voice, values, visual identity, audience, Do/Don't. The `identity.md` file (in `brands/<slug>/`) captures this. It is **what the brand says about itself**.

**Is not:** User identity (authentication, `user.id`), digital identity (SSO, OAuth). In the context of the `brands/` folder, Identity is always brand identity. For auth-layer user identity, use "User account" or "Auth identity" with the qualifier.

---

### Spec

**Is:** The architectural specification layer of one capability — its behaviour, contracts, surfaces, and decisions. Lives in `openspec/current/<capability>.md` for steady-state capabilities and in `openspec/changes/<slug>/{proposal,design,tasks,verification}.md` for in-flight changes.

**Is not:** The workspace UI surface at `/spec/[id]` (per `rename-spec-screen`) — that is a *render* of a Spec, not the Spec itself. Not a feature, user story, or database table.

---

### Brand

**Is:** The umbrella layer for one identity — voice, vocabulary, mental model, design tokens, components, motion, archetypes, surfaces — all under `openspec/brands/<slug>/`. A Brand expresses one identity across all its rendered surfaces.

**Is not:** Only voice (that is Identity, a subset). Only design (that is Design System, a subset). Only a logo (that is a Primitive in `packages/ui/`). Brand is the union of all four.

---

### Forge

**Is:** The studio's compile / build / run engine — `packages/forge/` — and its associated agents (Forge, Muse, Maestro per the cast layer). Internal-only in public-facing communication; appears as `Builder` on public surfaces per `cast-naming-role-descriptors`.

**Is not:** A publicly marketed pillar of the studio's offer. Not a deliverable to clients (clients receive *access* to Forge as shared infrastructure, not Forge itself).

---

### Product

**Is:** The integration of one Spec + one Brand + Forge access under one engagement. Per `openspec/_internal/platform/ontology.md`, one Product per engagement.

**Is not:** An isolated sphere. Product is the synthesis of the three spheres, not a fourth peer.

---

### Marketplace

**Is:** An orthogonal peer-to-peer transaction layer where platform users sell each other templates, re-usable specs, ideas, and knowledge across engagements. The studio operates the substrate; users produce the inventory.

**Is not:** Part of the studio's vertical offer (Spec / Brand / Forge). Not a studio-curated catalog. Not a content curation system.

---

### Mirror

**Is:** A sub-brand derived from a parent Brand via the Brand Mirroring operation. Typically a country-localised or audience-localised derivative, possibly under a different name, but always anchored to one parent and inheriting its identity DNA.

**Is not:** A separate perceptual spec layer (that meaning is retired — the role is absorbed into Brand). Not a synonym for the workspace UI surface (that is Spec). Not a verb for any other kind of "mirroring" anywhere in the platform. Not the retired Mirror **capability** (`current/mirror.md` tombstone) — that perceptual-spec layer is absorbed into Brand; this entry defines the re-scoped term.
