rfc-app/docs/QUICKSTART-VISION.md

# Vision: a one-command path to a new rfc-app deployment

This document is **not** an implementation plan. It is the vision that
the current build does not yet deliver — the experience we want for
anyone who reads about the RFC framework and decides they'd like to
run their own. Today, standing up a deployment is the multi-step
journey in [`DEPLOYMENTS.md`](./DEPLOYMENTS.md). The aspiration in
this doc is to compress that journey to a single command (or a small
handful), so the friction between *I want to run an instance of this*
and *I have a working instance of this* is as close to zero as we can
get it.

We are writing this down now so the principles are settled before any
code lands.

## Who this is for

The framework is the substrate for collaborative, RFC-style
standardization of any subject where a community needs to agree on
the meaning of its terms and where the argument that produced the
agreement is itself worth preserving. The deployments we imagine the
quickstart serving include — but are not limited to:

- **Medicine.** A public, model-assisted revision of the DSM's
  diagnostic criteria. Each diagnosis becomes an RFC; the criteria
  and their boundaries are argued in transcript; graduation gives a
  diagnosis a stable identifier and a reviewable history of how it
  came to be defined the way it is. The same shape applies to
  clinical protocols, drug-interaction taxonomies, and rare-disease
  registries.
- **Law.** Model statutes, regulatory definitions, or clause
  libraries. An RFC per clause, with the drafting argument
  preserved alongside the final text. The framework's audit log
  doubles as legislative history.
- **Bioethics and biosecurity.** Vaccine protocols, gene-editing
  guidelines, dual-use research review criteria. Domains where
  consensus saves lives and the reasoning behind the consensus
  matters as much as the consensus itself.
- **Literature.** Canonical-edition standardization for works with
  contested manuscripts; lexicons for technical or constructed
  languages; controlled vocabularies for archives.
- **Software.** Library API contracts written as prose, before the
  code. RFC-style definitions of cross-language behaviors that
  multiple implementations must respect.
- **Policy and governance.** Municipal ordinance templates, NGO
  governance rubrics, standards-body procedural definitions.
- **Education.** Curriculum standards, assessment rubrics, the
  meaning of competencies and credentials.
- **Natural language itself.** The original case — the Open Human
  Model deployment — standardizing the vocabulary humans and
  machines need to share.

The quickstart's goal is to make the path from *"I run one of these
communities and we need this"* to *"my community has a working
deployment to start arguing on"* short enough that the choice is
about the work the community wants to do, not the operational lift
of getting started.

## The intended experience

A reader who has just finished `PHILOSOPHY.md` and decides they want
their own deployment should be able to:

1. Pick a name for their deployment (one user-visible string).
2. Run a single command from a clean machine — `npx
   create-rfc-deployment <name>`, or `docker compose up` from a tiny
   template, or `curl ... | bash`, or whatever shape the design
   settles on.
3. Answer a small number of questions the command can't infer:
   their Gitea endpoint (or an offer to spin one up locally), an
   admin email, the OAuth callback URL.
4. End up with: a running rfc-app instance reachable in a browser, a
   meta repository seeded with the right structure, a first sign-in
   that hands the OWNER role to the operator, and a deployment repo
   on disk holding their `.rfc-app-version` pin, their `.env`
   defaults (sans secrets), and a `CLAUDE.md` describing the
   two-repo loop.

From the operator's point of view, the framework should feel like
infrastructure they instantiated, not a codebase they cloned.

## Why this isn't there yet

The current bring-up requires the operator to do work the framework
could do for them. Specifically:

- **Gitea provisioning.** The operator stands up Gitea by hand,
  creates the bot account, generates the bot token, registers the
  OAuth2 application, copies credentials into `backend/.env`. A
  quickstart could spin up Gitea in a sibling container, create the
  bot via Gitea's first-run admin API, and emit the credentials
  straight into the deployment's environment.
- **Meta-repo seeding.** Today `scripts/seed_meta_repo.py` is a
  manual step. A quickstart could run it as part of the first boot,
  detect an already-seeded repo (idempotent), and report what it did.
- **Frontend `.env`.** The operator copies `.env.example` and hand-
  fills `VITE_APP_NAME`. A quickstart could ask once and write the
  file.
- **Deployment repo bootstrap.** Today the deployment repo is a
  thing the operator creates manually. A quickstart could generate
  it: a fresh git repo containing `.rfc-app-version`, a README
  template, a `CONTRIBUTING.md` template, a `CLAUDE.md` template
  cloned from this repo's pattern, and a placeholder
  `rfcs/RFC-0001-...md` the operator fills in.
- **OAuth callback wiring.** The current bring-up requires the
  operator to register an OAuth app in Gitea by hand. A quickstart
  could do this through Gitea's API once the bot token exists.
- **Process supervision.** Today `deploy/RUNBOOK.md` walks an
  operator through systemd / nginx by hand. A quickstart could ship
  a Docker Compose file (or systemd unit templates) that bring up
  backend + frontend + Gitea in one shot.

Each of these is a small lift on its own. Together they're a
quickstart product — and that's what this doc is staking out.

## Design principles for when the work gets picked up

The quickstart is downstream of every other contract in this repo.
The principles below keep it that way:

**The quickstart does not embed deployment values.** It collects
them from the operator and writes them where they belong (the new
deployment's repo, the server's `.env`, etc.). The framework remains
deployment-agnostic; the quickstart is a configurator, not a
template renderer that bakes in OHM-like choices.

**The quickstart respects `SPEC.md` §20.** It pins the new
deployment to the current framework version (the `VERSION` file).
Future upgrades go through the §20.5 sequence — the quickstart does
not invent a parallel upgrade path. If the quickstart needs to bump
the pin, it does so by editing `.rfc-app-version` in the deployment
repo, the same way an operator would by hand.

**The quickstart produces a deployment repo that an operator can
own.** The output is plain files in a git repo, not a runtime that
hides the configuration. An operator who never wants to think about
the quickstart again can read the generated `CLAUDE.md` and
`.rfc-app-version` and continue from there with `DEPLOYMENTS.md` as
their guide.

**Loud failures, not silent defaults.** If the operator declines to
supply a required value, the quickstart refuses to continue. We do
not ship a "demo" deployment that produces something running but
useless; the framework's separation-of-concerns rule is upstream of
the quickstart's UX.

**One thing at a time.** A quickstart that tries to handle every
deployment topology (single-machine, Kubernetes, managed Gitea,
self-hosted Gitea, Cloud Run, Fly, etc.) on day one is a project
that ships nothing. The first cut targets a single happy path —
likely a single-machine Docker Compose with a local Gitea — and the
others are §19.2-style follow-ups.

## Open questions to settle before building

When this work gets picked up, the design session will need to
settle:

- **Where does the quickstart live?** A separate repo? A `tools/`
  directory in this repo? A published npm package? Each has trade-
  offs (versioning, discoverability, upgrade story).
- **What's the shape of "one command"?** `npx create-rfc-deployment`,
  `docker compose up`, `curl | bash`, a TUI installer, a web wizard
  hosted by the framework's docs site? The shape determines the
  audience.
- **Does the quickstart bring up Gitea or assume it exists?** Both
  are valid; "bring up Gitea" is friendlier for new operators but
  enlarges the quickstart's surface; "assume Gitea" is cleaner but
  leaves a real bring-up step in the operator's lap.
- **How does the quickstart handle secrets?** Generate them and
  write them to disk? Print them to stdout? Both? What's the
  rotation story?
- **What does the upgrade story look like for an operator who used
  the quickstart?** The pin lives in the deployment repo per §20.5;
  the quickstart should never become a parallel upgrade path. But
  it might offer an `rfc-app upgrade` command that just runs the
  §20.5 sequence in one shot.

These are the conversations to have when the time comes. None of them
need answering today; this doc exists so that whoever picks this up
has the shape of the goal in front of them.

## Status

Not started. This doc is the seed. When work begins, it gets its own
§19.2 candidate in `SPEC.md` and the design session follows the
existing decision-and-fold pattern. Until then, [`DEPLOYMENTS.md`](./DEPLOYMENTS.md)
is the path an operator follows.