Files

T

cgalo5758 4dad0c48c7 Write down where a rule and an act live, output order, and how to prove a test

The code-organization rules the recent refactor worked to were written
in no tracked doc. docs/go-conventions.md gains them:
- "Where a rule and an act live": one function for a rule a page shows
  and an endpoint enforces (plans.Offer); one statement for a rule SQL
  and Go both need (core.superseded_ends); a many-row act in the
  package that owns its tables (entitlements.RemoveTier, ReorderTiers,
  PlanActError); a handler that parses, calls, maps and renders; a read
  page that loads, derives, builds and renders with one name resolver
  per request; and a failed read is never an answer. The handlers that
  still open a transaction or run SQL are #221, and the reads that
  still turn a failure into a value are #207 and #197.
- "Output order": a list query ends on a unique key (#225 lists the
  ones that do not), a loop that writes rows walks a stated order
  (#218), and Go output from a map ranges over sorted keys.
- No call to Stripe while a transaction is open. The transactions
  section now says new code uses the helpers and points to #186 for
  the BeginTx calls that remain.
docs/operator-ux-conventions.md's failed-collection rule links the
general one.

docs/testing.md:
- Characterize before a refactor, and what a refactor commit may
  change.
- The deliberate-break rule covers new tests and tests whose names or
  comments state a value, names all six outcomes the break tool
  reports, and says how to read a MISSED break.
- Tests of locks and of order are deterministic; a flaky test is a
  suspected defect; a database test passes twice without a reset and
  filters to its own rows.
- Golden files: defined order, rows of the test's own fixture, an
  expected change edited in by hand before the run, `-update` one
  package at a time.
- A helper joins the test kit with its first caller and a test.

CONTRIBUTING.md: the Go and test conventions point to their pages;
docs move with the code; a written rule names its check; a script
that resets or deletes data refuses unknown arguments; "Before you
push" runs `make test`, since without the stack the database and
Stripe tests skip; a commit message reads from the repository alone;
new source files carry the SPDX header; and a small fix rides along
only when listed, while a second sighting, a new rule or lock, or two
statements of one rule get their own issue.

docs/README.md: one page per rule, and the Go conventions entry lists
what the page now covers.

2026-10-15 20:56:59 -05:00

4.9 KiB

Raw Blame History

title, audience, summary

title

audience

summary

Documentation index

developer

admin

user

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:

---
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 — the sequenced path from a fresh host to a running instance; start here.
Environment Reference — every configuration key with its default and MC_* override.
Settings and Configuration — why software uses two words for what a program is told, and how this console applies the rule.
Hosting member-console — build the image and generate secrets.
Deployment Architecture — how the console fits alongside a public site and an identity provider.
Identity Provider Setup — configure an OIDC IdP for login.
Temporal Authorization Setup — emit the permissions claim Temporal's JWT authorizer expects.
Plan Management — operator guide to plan ladders and grants.
Stripe Integration — flags, secrets, webhooks, and purchasability.

For developers — contributing & internals

Database Management — goose migrations and sqlc.
Database Locks — every advisory and serializing row lock, how each key is built, and the order each path takes them in.
Design System — UI conventions.
Domain Model Cards — the model catalog: one card per domain model with invariants, dimensions, and traps.
FedWiki Integration — provisioning via the FarmManager API.
Go Conventions — where a rule and an act live, transactions and locks, output order, error handling, and dead code.
HTMX Setup — HTMX under a strict CSP.
Identifiers — IDs, names, and keys: which entities carry a key, its grammar and scope, and how seeds and lookups use it.
Operator Information Architecture — the operator panel's IA contract.
Operator UX Conventions — form and action conventions.
First-Contact UX Walk Process — the repeatable method for walking the console as a stranger.
First-Contact UX Rubric — the instrument that method scores with: the A–G question bank, the walker protocol, and the screen coverage checklist.
Agent Runner — how an agent from another model family reviews or ideates on the code inside a disposable copy: what contains it, how a task is shaped, and what a finding must carry before it counts.
Operator UI Accessibility Baseline — what operator-UI changes are diffed against.
Building an Integration — adding a new integration.
Testing — the test taxonomy and how to run each kind, plus the gates: make lint (page-anatomy rules and the Go static checks) and make screens (contact sheets at two widths).

For users

No member-facing documentation yet.

One page per rule

A rule is written on the one page that owns it. Another page that needs the rule links to that page instead of restating it, because two copies of a rule are edited separately and drift apart.

Where things are not

Research, drafts, audits, walkthrough evidence, and other records of how a decision was reached are not documentation; they stay in a local notebook that git ignores, so a clone never carries them. When a decision lands, whatever a reader still needs is written into this directory, which holds the result without the history. The rule for every kind of file is in status/MAINTAINING.md.

4.9 KiB Raw Blame History Unescape Escape