cgalo5758
5829091881
The contained runner that drove the 2026-09 security audit, the README review and four rounds of design ideation lived only inside the ignored notebook. It moves to scripts/agent-runner/: the prepare, tools, audit, ideation and teardown scripts, the compose and container files, the allowlist proxy and the prompt templates, with the paths that assumed the notebook fixed and findings written to a caller-named directory. Run outputs, transcripts and the round-specific sheet scripts stay behind. docs/agent-runner.md states the method: the disposable git archive copy and the fail-closed proxy, how a task is shaped, union rather than intersection of findings across models, separate adjudication of every finding against the source, and the evidence a finding must carry.
78 lines
4.4 KiB
Markdown
78 lines
4.4 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.
|
||
- [Settings and Configuration](settings-and-configuration.md) — why software uses two words for what a program is told, and how this console applies the rule.
|
||
- [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.
|
||
- [First-Contact UX Rubric](first-contact-rubric.md) — the instrument that method scores with: the A–G question bank, the walker protocol, and the screen coverage checklist.
|
||
- [Agent Runner](agent-runner.md) — 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](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 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`](../status/MAINTAINING.md#where-things-live).
|