cgalo5758
71818de0bd
Implement the ux-first-run change: a state-derived setup checklist on /operator/setup with a landing region that recedes once required steps are done, and empty states that distinguish blocked from empty across operator and member surfaces. Also add production deployment and environment reference docs, plus a config-key completeness test.
66 lines
3.2 KiB
Markdown
66 lines
3.2 KiB
Markdown
---
|
|
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 and the accessibility baseline.
|
|
- [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.
|
|
- [Operator Information Architecture](operator-ia.md) — the operator panel's IA contract.
|
|
- [Operator UX Conventions](operator-ux-conventions.md) — form and action conventions.
|
|
- [Operator UX Research](operator-ux-research.md) — the M7 UX research study.
|
|
- [Operator UX Walkthrough Task](operator-ux-walkthrough-task.md) — the screen-walkthrough briefing.
|
|
- [Building an Integration](building-an-integration.md) — adding a new integration.
|
|
- [Testing](testing.md) — the test taxonomy and how to run each kind.
|
|
- `operator-ux-walkthroughs/`, `operator-ux-walkthrough-evidence/` — captured UX walkthrough evidence.
|
|
|
|
## For users
|
|
|
|
_No member-facing documentation yet._
|