---
title: "Documentation index"
audience: [developer, admin, user]
summary: "Index of member-console documentation, grouped by audience, plus the front-matter convention every doc follows."
---

# Documentation

Every document in this directory carries YAML front matter declaring its
audience, so readers can find what's for them and contributors know who they're
writing for.

## Front-matter convention

Start each doc with a front-matter block:

```yaml
---
title: "Human-readable title"
audience: [admin, developer]   # one or more of: developer, admin, user (primary first)
summary: "One sentence describing what the doc covers."
---
```

The three audiences:

- **developer** — contributing to or understanding the codebase: architecture,
  design decisions, dev setup, testing, UX research and conventions, the
  provider-extension contract.
- **admin** — hosting and operating an instance: installing, configuring an
  identity provider, building the image, generating secrets, running the service.
- **user** — the general public or a member using a running service. (None yet —
  the tag is reserved for member-facing docs.)

List the primary audience first; a doc may name more than one.

## For administrators — hosting & operating

- [Production Deployment](production-deployment.md) — the sequenced path from a fresh host to a running instance; start here.
- [Environment Reference](environment-reference.md) — every configuration key with its default and `MC_*` override.
- [Hosting member-console](hosting.md) — build the image and generate secrets.
- [Deployment Architecture](deployment-architecture.md) — how the console fits alongside a public site and an identity provider.
- [Identity Provider Setup](identity-provider-setup.md) — configure an OIDC IdP for login.
- [Temporal Authorization Setup](temporal-authorization-setup.md) — emit the `permissions` claim Temporal's JWT authorizer expects.
- [Plan Management](plan-management.md) — operator guide to plan ladders and grants.
- [Stripe Integration](stripe.md) — flags, secrets, webhooks, and purchasability.

## For developers — contributing & internals

- [Database Management](database-management.md) — goose migrations and sqlc.
- [Design System](design-system.md) — UI conventions.
- [Domain Model Cards](models/README.md) — the model catalog: one card per domain model with invariants, dimensions, and traps.
- [FedWiki Integration](fedwiki-setup.md) — provisioning via the FarmManager API.
- [HTMX Setup](htmx-setup.md) — HTMX under a strict CSP.
- [Identifiers](identifiers.md) — IDs, names, and keys: which entities carry a key, its grammar and scope, and how seeds and lookups use it.
- [Operator Information Architecture](operator-ia.md) — the operator panel's IA contract.
- [Operator UX Conventions](operator-ux-conventions.md) — form and action conventions.
- [First-Contact UX Walk Process](first-contact-ux-process.md) — the repeatable method for walking the console as a stranger.
- [Operator UI Accessibility Baseline](operator-a11y-baseline.md) — what operator-UI changes are diffed against.
- [Building an Integration](building-an-integration.md) — adding a new integration.
- [Testing](testing.md) — the test taxonomy and how to run each kind, plus the UI quality gate: `make lint` (page-anatomy rules) and `make screens` (contact sheets at two widths).

## For users

_No member-facing documentation yet._

## Where things are not

Research, drafts, audits, walkthrough evidence, and other records of how a
decision was reached are not documentation; they live under
[`status/explorations/`](../status/explorations/), one directory per topic,
each with an index. This directory holds what a reader needs without the
history. The rule for every kind of file is in
[`status/MAINTAINING.md`](../status/MAINTAINING.md#where-things-live).