cgalo5758
408fa6f5a6
- Add shared ui_*.html parts (pageHeader, sectionHeader, statusBadge, emptyState) parsed into every template set - Add anatomy lint rules with a shrinking allowlist and screen-coverage check - Add make screens capture harness with contact sheets and baseline diff - Compose member and FedWiki regions server-side so pages arrive complete - Rebuild Domains and Integrations on the parts as pilots
75 lines
3.8 KiB
Markdown
75 lines
3.8 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.
|
|
- [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).
|