@~/.claude/wiggleverse.md

# Working in rfc-app

This is the framework — the software that hosts an RFC standardization
process. It is intended to power **multiple deployments**, each of which
brands and configures itself independently. The framework is the
substrate; the deployment is the instance.

## The separation-of-concerns rule

Code in this repo must never bake in values that belong to a specific
deployment. That includes:

- The deployment's display name, tagline, or pitch copy.
- The corpus or domain the deployment is about.
- The deployment's URL, organization name, branding assets.
- Any reference to the people or community running a specific instance.

When a value of that kind is needed in source, it goes behind
configuration — typically a build-time `VITE_*` env var the frontend
reads, or a backend env var the API surfaces. The framework supplies a
loud failure path (e.g. build fails, server refuses to start) when a
required value is missing, so a misconfigured deployment can't ship the
wrong content silently.

The framework name itself (`Wiggleverse RFC`, per the founding
documents) does appear in source — in the chat system prompt, in
`PHILOSOPHY.md`, in `SPEC.md`. That is correct: those references are
about *the framework*, not about any deployment. Deployment names and
deployment content stay out.

If you find a hardcoded deployment-specific string in source, treat it
as a bug to fix in the framework: make it configurable, document the
new env var in `frontend/.env.example` or `backend/.env.example`, and
bump the version per the rules below.

## Versioning

The binding policy is in [`SPEC.md` §20](./SPEC.md). Summary so
working sessions don't have to reload the full section:

- The `VERSION` file at the repo root is the canonical version;
  `frontend/package.json#version` mirrors it. A divergence between
  the two is a spec-level bug.
- SemVer: patch = no operator action required; minor = new
  functionality plus, while pre-1.0, breaking changes spelled out
  in the changelog; major = reserved for the first stable cut and
  afterwards for breaking changes.
- Every release adds an entry to `CHANGELOG.md`. Breaking entries
  carry an "upgrade steps" block; a downstream deployment must be
  able to upgrade from any prior version by walking those blocks in
  order.

The practical recipe for downstream projects — how to pin, how to
upgrade, how the two-repo loop runs — is in
[`docs/DEPLOYMENTS.md`](./docs/DEPLOYMENTS.md). Don't restate that
recipe here; if it's wrong, fix it there.

## How changes typically flow in

The framework receives change requests from deployments. The intake
loop:

1. A deployment operator notices something they want different
   (different name, missing feature, wrong behavior).
2. Triage: is this a framework concern (bug, missing affordance, hard-
   coded value that should be configurable) or a deployment concern
   (just a config value to change)?
3. If framework: implement here, bump the version, update the changelog
   with upgrade steps.
4. The deployment then pins to the new version and applies any required
   config changes.

The framework does not name specific deployments, but it does aim to
make each deployment's upgrade path obvious and mechanical.

## Code layout

See `docs/DEV.md` for the slicing plan and build history. See
`SPEC.md` for the binding contract — section numbers (`§n.n`) in the
codebase refer to that file.