# rosetta-platform

**This repository is where Rosetta's knowledge lives.** Everything
the system knows — and every rule about how that knowledge earns
trust — originates here: the graph schema that gives knowledge its
shape, the curated Data 360 knowledge corpus itself, the engagement
digital twins, the governance gates that promote content from
proposed to validated, and the nine Claude Code and Claude.ai plugins
practitioners use to work with all of it.

Everything downstream serves what this repository produces. The Go
app server behind `api.rosetta-design.com`, the MCP connector, and
the console all *consume* the schema and knowledge published from
here — that is the system's producer/consumer split, and this repo
is the producer. Nothing becomes part of Rosetta's canon except
through this repository's review gates.

Current published release: **v1.5.12**, governed by semantic metamodel
**v1.22.0** in that immutable tag. Current reviewable source is the unpublished
**v1.23.0** candidate for v1.6.0
(docs/rosetta-semantic-metamodel-v1.23.0.md).
Published documentation lives at
[docs.rosetta-design.com](https://docs.rosetta-design.com/). The rest
of this page: the [production architecture](#the-production-architecture-on-google-cloud)
the system runs on, then the repository's contents for maintainers
and contributors.

## The production architecture on Google Cloud

Everything Rosetta serves runs on a deliberately small Google Cloud
estate — two virtual machines, one public ingress rule, and no public
SSH anywhere.

![The production estate on Google Cloud: consumers reach a Cloudflare edge, then a hardened application VM running the Caddy proxy, console, REST API, MCP connector, docs, observability, and MySQL; the Neo4j knowledge graph runs on a dedicated VM with no public ingress](docs/img/gcp-architecture-light.svg#only-light)
![The production estate on Google Cloud: consumers reach a Cloudflare edge, then a hardened application VM running the Caddy proxy, console, REST API, MCP connector, docs, observability, and MySQL; the Neo4j knowledge graph runs on a dedicated VM with no public ingress](docs/img/gcp-architecture-dark.svg#only-dark)

Every consumer — a browser on the console, a Claude session over the
MCP connector, a REST integration, a plugin installer — arrives
through Cloudflare and lands on the **application host**: a hardened
Compute Engine VM whose only public ingress is HTTPS. Behind its Caddy
reverse proxy live the enablement console
([rosetta-design.com](https://rosetta-design.com)), the Go app
server's REST API (`api.`), the MCP connector (`mcp.`), this
documentation site (`docs.`), OTLP observability, and the MySQL
database holding accounts and KMS-scoped API keys.

The knowledge graph itself — the asset all of this exists to serve —
gets its own machine: a dedicated **graph host** running Neo4j on its
own data disk with automated snapshots, reachable only over the
private network. It has **no public ingress at all**.

The whole estate is Terraform-managed (VPC, firewall rules, disks,
snapshot schedules — declared in `infra/` here and in the
consumer repo's `infra/`), built and deployed by a GitHub Actions
runner fleet, and administered exclusively through Google
Identity-Aware Proxy tunnels — SSH is closed to the internet on every
machine. Plugin and bundle distribution is gated by KMS-scoped API
keys rather than by network position.

## What this repo is

This repository owns:

- **Graph schema** (`db/schema/`) — 56 Cypher files declaring
  constraints, indexes, node-property contracts and relationship
  contracts, plus the content-edge registry; the invariant gates live
  in `scripts/neo4j/`.
- **Synthetic CI fixtures** (`db/fixtures/`) — the data every graph
  gate runs on in CI (E9-S1-WP1).
- **Not content.** Since the switch release (E9-S2-WP1, 2026-10-12;
  ADR-PL-024) the production graph is the system of record for content
  and engagements, written through the `rosetta-app-server` API.
  `db/seeds/` and `db/engagements/` left `main`; the frozen baseline tag
  `v0.27.0` holds their last state.
- **Relational schema** (`db/mysql/`) — 35 idempotent SQL migrations
  applied via `schema_migrations` tracking.
- **Plugin family** (`util/plugins/`) — nine Claude Code and
  Claude.ai plugins: `rosetta-agent` (the MCP tool surface),
  `engagement-codex`, `engagement-rehearsal`, `engagement-authoring`,
  `rosetta-archaeology`, `rosetta-research`, `d360-distiller`,
  `deploy-distiller`, and `tech-note-distiller`.
  Distributed as a KMS-gated install bundle from rosetta-design.com —
  see [INSTALL.md](INSTALL.md).
- **Operational scripts** (`scripts/`) — Bash + Node.js tooling
  invoked through `make <target>`, the canonical user-facing surface
  (ADR-PL-004).
- **Container orchestration** (`docker-compose.yml`, `docker/`) —
  Neo4j + MySQL + Phoenix services for local and CI-time stacks.
- **Infrastructure** (`infra/`) — Terraform for the GCP two-VM
  production topology.
- **Content tooling** — the plugins' content:ingest builder
  (`make content-ingest-build`, `util/seed/`), `make report-family` over
  a run bundle's Cypher (`util/python/product_family_report/`), and
  content snapshots (`make content-snapshot`). Graph-native review tools
  are E9-S3-WP1.

The authoritative definition of every Work Packet, ADR, acceptance
test, input set, and output path lives in
docs/rosetta-platform.spec-manifest.md.
The manifest is the single source of truth; this README is a
navigational companion.

## What this repo is not

- **Not a Go application server.** That is `rosetta-app-server`.
  Per Constitution C-7 (ADR-PL-016), this repo produces and
  publishes; it does not import from or depend on consumers.
- **Not the admin console or KMS.** The rosetta-design.com console
  (key management, downloads, governance review UI) is
  `rosetta-enablement-agent`.
- **Not the home of HTTP API specs, route handlers, or
  classification logic.** Those belong with the consumer.
- **Not the constellation governance layer.** Cross-repo decisions
  (`DT-RX-*` / `ADR-RX-*`) live in `rosetta-meta`; this repo's
  governance series is `ADR-PL-*`.

See manifest §2 for the full non-goals list.

## Repo map

```
rosetta-platform/
├── db/
│   ├── schema/             # 56 Cypher files (constraints, contracts, gates)
│   ├── seeds/              # canonical D360 corpus (03g–10g)
│   ├── engagements/        # engagement-scoped twin Cypher
│   ├── mysql/              # 35 idempotent SQL migrations
│   ├── migrations/         # Cypher data backfills
│   └── backups/            # gitignored
├── scripts/                # neo4j/, mysql/, content/, docker/, release/, lib/
├── util/
│   ├── seed/               # Markdown↔Cypher round-trip pipeline
│   └── plugins/            # the nine-plugin family + marketplace.json
├── docker/                 # neo4j, mysql, phoenix service configs
├── infra/                  # Terraform GCP two-VM topology
├── contracts/              # app-server intake + install-bundle contracts
├── docs/
│   ├── adrs/               # 24 ADR-PL-* governing this repo
│   ├── decision-traces/    # DecisionTrace collection point
│   ├── runbooks/           # release-cut, production-deploy, content checklists
│   ├── workplans/          # per-WP working plans
│   ├── rosetta-platform.spec-manifest.md
│   └── rosetta-semantic-metamodel-v1.23.0.md
├── docker-compose.yml      # neo4j + mysql + phoenix (no app)
├── Makefile                # operational surface (C-4)
├── INSTALL.md              # end-user plugin install guide
└── CLAUDE.md, README.md, LICENSE
```

## Quickstart

```bash
cp .env.example .env          # then edit credentials
make docker-up                # neo4j:5 + mysql:8.4 + phoenix
make db-init && make mysql-init   # apply schemas (idempotent, ADR-PL-002)
make db-seed                  # load the canonical seed corpus
make db-status                # verify counts
make db-invariants            # metamodel invariant gates
make d360-invariants          # the D360 contract gate
```

`make help` lists the full target index. Per ADR-PL-004, every
operation goes through a `make` target — no raw `docker exec`,
`mysql -u`, or `cypher-shell` in docs or runbooks.

Installing the **plugins** (end-user path) is a different flow — see
[INSTALL.md](INSTALL.md): distribution is a KMS-gated bundle on
rosetta-design.com (`plugin-install` scope API key required).

## Releases and publication

A release cut publishes two sibling artifacts under one `vX.Y.Z` tag
(runbook: docs/runbooks/release-cut.md):

- **Consumer intake tarball** (`make publish-for-app-server`) — the
  schema+seed contract `rosetta-app-server` and
  `rosetta-enablement-agent` pin (`contracts/app-server-intake.md`).
- **Install bundle** (`make publish-install-bundle`) — the KMS-gated
  end-user plugin bundle served from rosetta-design.com.

## Documentation index

- [docs.rosetta-design.com](https://docs.rosetta-design.com/) — the
  published constellation documentation site
- docs/rosetta-platform.spec-manifest.md — authoritative work definition
- docs/rosetta-semantic-metamodel-v1.23.0.md — the current source-candidate metamodel
- docs/adrs/ — the ADR-PL series (24 ADRs)
- docs/decision-traces/ — DecisionTrace record
- docs/runbooks/ — release-cut, production-deploy, content author/review checklists
- [util/plugins/](util/plugins/) — the plugin family ([overview README](util/plugins/README.md))
- CLAUDE.md — agent session invariants

## License

Proprietary work product of Keenan Vision LLC See LICENSE
for the full notice. Use, reproduction, and distribution are governed
solely by separate written agreement with Keenan Vision LLC

The license selection was ratified in
docs/decision-traces/repo-license.md
on 2026-04-26.