docs: add a role-keyed docs index, and record the shipped breaking change (#90)

* docs: add a role-keyed docs index, and record the shipped breaking change

Two gaps, both of which make a reader draw a wrong conclusion.

docs/README.md — there are 377 markdown files under docs/ and no index, so
GitHub rendered no docs landing page and the root README pointed at five
ad-hoc links, three of them maintainer-facing. There was no operator entry
point at all; the inventory that opened this effort named that the
highest-leverage gap.

The index is organised by AUDIENCE rather than by directory, because this
repo's layout does not track audience and its filenames actively mislead:
CI.md and ADOPTER-CI.md describe different repositories for opposite
readers; ASVS-L2-PHASE0-CHANGES.md is operator notes; testing/VERIFY.md is
an operator tool, not a test plan. Where a name misleads, the index says so
instead of repeating it.

Three things it does deliberately:

* Leads with a six-step start-here path for a new operator, in order, with
  one line of "why now" each. A table of 84 rows does not close a missing
  entry point no matter how good the rows are.
* Disambiguates the two SECURITY.md files up front. .github/SECURITY.md is
  the vulnerability-disclosure policy; docs/SECURITY.md is the auth/RBAC
  reference. Same filename, different jobs, and getting it wrong sends a
  vulnerability report to the wrong place.
* Quarantines the planning history rather than hiding it. ~160 of the 377
  files are dated build plans, session handoffs and measurement records.
  Each directory gets one row with a file count and an explicit "do not
  follow as instructions" banner, so the omission is VISIBLE rather than
  silent. Retired and stale documents (the PySide6 console guides, the
  de-registered self-hosted runners, a June-2026 CI summary whose counts
  have moved) are labelled where they sit.

Every one of the 72 links was checked to resolve. Two rows in the first
draft pointed at files that do not exist — docs/threat-model.md and
docs/TODO.md — and were replaced. The threat model turns out to be
deliberately unpublished, which SECURITY-DOCS-POLICY.md explains, so the
index now says that rather than dangling a link at it.

CHANGELOG.md — PR #85 shipped a breaking change with no release note. An
instance carrying an inert [[alerts.rules]] block that routes to an
unconfigured transport now refuses to start. The entry states the exact
triggering condition (including the half-filled [alerts] block missing
email_to, which is the shape that looks configured but is not) and the
mitigating fact that decides it: in that state the rule has never routed a
single alert, so the refusal removes no working behaviour. The egress-gate
widening and the DICOM refusal-message correction from the same PR are
recorded alongside it; neither had a note either.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: drop the frozen v0.1.0 .docx snapshot of the mental model

docs/MessageFoundry-Mental-Model.docx was a Word snapshot of what is now
docs/MENTAL-MODEL.md. The markdown is the living document — its masthead
reads "v0.3.2 · prepared 2026-06-18, revised 2026-07-30". The .docx masthead
still read "v0.1.0 (Early Access) · prepared 2026-06-18" and had not been
touched since 2026-07-06, two minor versions behind.

It is not a duplicate in the harmless sense. Of its 216 substantial
paragraphs only 114 survive verbatim in the markdown; the rest is not extra
information but SUPERSEDED phrasing — including a store description that
still frames SQLite as the message store with Postgres as a parenthetical,
which stopped being accurate when the three backends reached parity.

That is the case for removing it rather than regenerating it. A binary in a
public repository cannot be diffed or reviewed, so it drifts silently and
no gate can catch it: nothing referenced it, and nothing would have noticed
it going stale. The rendered PDF the website serves is generated from the
markdown, so no reader loses anything. The blob remains in git history if
the old wording is ever wanted.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: wshallwshall

CHANGELOG.md

@@ -6,7 +6,60 @@ All notable changes to MessageFoundry are documented here. The format follows
 
 ## [Unreleased]
 
+### Changed
+- **BREAKING — an `[[alerts.rules]]` block that routes to an unconfigured transport now refuses at
+  startup instead of being silently ignored.** `notifier_from_settings` returned early when **no**
+  transport was configured, *before* the loop that cross-checks each rule's `transports` against the
+  ones that exist. So the fail-loud guarantee held everywhere except the state an operator is most
+  likely to be in while first setting alerts up: with one transport configured, a rule naming a
+  different one was a hard `ValueError` at startup; with **zero** configured, the identical rule was
+  accepted and then **never applied**, and nothing said so. Validation now runs first.
+  **Who this bites:** an instance where `[[alerts.rules]]` exist AND at least one rule or escalation
+  tier sets a non-empty `transports` AND no transport is actually configured (`webhook_url` unset, and
+  **not all three** of `email_smtp_host` + `email_from` + `email_to` set — the email transport needs
+  all three, which is what makes a half-filled `[alerts]` block look configured). Such an instance
+  starts today and will refuse after upgrading.
+  **Why this is safe to take:** in that state the rule has **never routed a single alert**. The
+  refusal removes no working behaviour — it converts a permanent silent no-op into a startup error
+  that names the exact keys to add. A rule that names **no** transport is unaffected and still starts
+  (now with a warning when rules exist that cannot notify anyone), so the ordinary "write the rules
+  first, wire the transport later" flow keeps working.
+  The same cross-check now runs at **authoring** time: `messagefoundry alert add` (which the VS Code
+  "New Alert" command shells) refuses a rule routing to an unconfigured transport rather than
+  persisting a file that only fails at the next boot. It is scoped to the rule being added, so a file
+  that already contains a bad rule can still be repaired with `alert remove`.
+- **A mail-only or Direct-only PHI instance can now satisfy the open-egress startup gate by declaring
+  its destinations.** `[egress]` has eight `allowed_*` lists and all eight are enforced downstream,
+  but the startup gate hand-enumerated six: `allowed_smtp` and `allowed_direct` were absent, so an
+  instance whose only egress is `Email()` or `Direct()` exited 2 with *"outbound egress is
+  UNRESTRICTED"* while holding a fully-enumerated allow-list, and nothing in the message named the two
+  lists that did not count. The two are now counted — deliberately **only** when
+  `[security].block_unlisted_outbound` is left unset, which is exactly the state the deny-by-default
+  flip turns ON, so such an instance starts **fail-closed**. An instance that explicitly set
+  `block_unlisted_outbound = false` is unchanged and still refused, because there the other six
+  transports stay allow-any; the refusal now names that override as the reason. **No shipped refusal
+  stops firing.**
+
 ### Fixed
+- **The DICOM C-STORE SCP's fail-closed refusal named a settings key that does not exist.** It told
+  the operator to set `[inbound].source_ip_allowlist`; `InboundSettings` has no such field and section
+  models ignore unknown keys, so an operator following the engine's **own error message** wrote a key
+  into `messagefoundry.toml` that was accepted and silently discarded — leaving a non-loopback SCP
+  with no peer-IP gate while believing it had one. Aggravated by the construction gate *counting*
+  controls: a `calling_ae_allowlist` (a caller-asserted AE Title with no cryptographic binding) plus
+  the discarded key passed the check. The message now names the working surface — the `inbound(...)`
+  keyword, which for a DICOM SCP is the **only** one, since `DICOM()` is not authorable in
+  `connections.toml` — and distinguishes it from the `connections.toml` `[[inbound]]` key that *is*
+  real, so a site running MLLP alongside DICOM cannot read it as licence to delete a working
+  allowlist. The same wrong spelling is corrected in the module docstring, the gate comment,
+  `config/wiring.py`, `config/settings.py`, `docs/SECURITY.md` and `docs/ASVS-L2-PHASE0-CHANGES.md`.
+  Whether an AE-title list alone should keep satisfying that gate is tracked as **BACKLOG #252** — it
+  is an ADR 0025 §9 contract change and is deliberately **not** decided here.
+- **Two startup gates described themselves against the deployment tier rather than the enforcement
+  dial.** Comments on the managed-identity and security-notification gates read "refuse (production) /
+  warn (non-production)" over branches that read `enforcing` — and `enforce` is the shipped default on
+  `dev` and `staging` as much as on `prod`, so all three refuse. Comment-only, no behaviour change,
+  but these are the comments two published documentation defects were copied from.
 - **The load harness's no-loss reconcile did not enforce the `read >= sent // 2` intake guarantee
   0.3.2 documented.** The unconfirmed-send excusal is capped at `max(connections, half the run)`, but
   that `max()` takes the connection count as a *floor*, and every call site passes a connection count

README.md

@@ -82,6 +82,11 @@ Full documentation lives on **[messagefoundry.org](https://messagefoundry.org/)*
 [Guides](https://messagefoundry.org/guides/) ·
 [Documents](https://messagefoundry.org/documents.html)
 
+**In this repository:** [`docs/README.md`](https://github.com/MEFORORG/MessageFoundry/blob/main/docs/README.md)
+is the index for the 377 documents under `docs/`. It opens with a six-step **start-here path for a new
+operator**, then splits the rest by audience — operators, developers, security reviewers, maintainers —
+and quarantines the dated planning artifacts so you do not mistake a superseded plan for instructions.
+
 ## Installing & rolling out
 
 **The recommended way to deploy MessageFoundry is to install the published package from

docs/MessageFoundry-Mental-Model.docx

@@ -0,0 +1,151 @@
+# MessageFoundry documentation
+
+There are **377 markdown files** under `docs/`. Most of them are maintainer planning history, not
+documentation. This page exists so you do not have to guess which is which.
+
+**Filenames in this repository are unreliable signals.** `docs/CI.md` and `docs/ADOPTER-CI.md` describe
+different repositories for opposite audiences. `docs/ASVS-L2-PHASE0-CHANGES.md` is operator notes.
+`docs/testing/VERIFY.md` is an operator tool, not a test plan. Where a name misleads, this index says so
+rather than repeating it.
+
+> **Reporting a security vulnerability?** → **[`.github/SECURITY.md`](../.github/SECURITY.md)**, the
+> disclosure policy. **Not** `docs/SECURITY.md`, which despite the identical filename is the
+> authentication and RBAC reference. Two files, same name, different jobs.
+
+---
+
+## Start here — a new operator, in order
+
+Six documents, in this sequence. Each one is cheap to read and answers a question that makes the next
+one make sense.
+
+1. **[EARLY-ADOPTER-GUIDE.md](EARLY-ADOPTER-GUIDE.md)** — the only doc that sequences the whole journey.
+   It is an orchestration document: it ties the others together and adds the install-to-production
+   rollout plan that nothing else carries. Read it first even if you skim it.
+2. **[SYSTEM-REQUIREMENTS.md](SYSTEM-REQUIREMENTS.md)** — the cheap disqualifier, before you install
+   anything. Hardware, OS, the Python floor, the three store backends, ports, and sizing by volume.
+3. **[INSTALL-GUIDE.md](INSTALL-GUIDE.md)** — establishes the *deployment model*: a pinned, read-only
+   engine wheel plus your own private git config repo (ADR 0017). This is the decision that is
+   expensive to undo later, so understand it before you commit to a layout.
+4. **[USER-GUIDE.md](USER-GUIDE.md)** — the task-oriented path. Clean machine → running engine → first
+   message end to end → authoring connections, routers and handlers → operating the console and the
+   VS Code extension → reading dispositions and troubleshooting.
+5. **[DEPLOYMENT.md](DEPLOYMENT.md)** — **mandatory before any off-loopback bind.** Trust boundaries,
+   the channel × TLS posture matrix, egress allow-lists, and the fail-closed bind guards that will
+   otherwise refuse to start and leave you guessing why.
+6. **[testing/VERIFY.md](testing/VERIFY.md)** — the gate before real traffic. `messagefoundry verify`
+   is a wheel-only, on-box acceptance check that answers "is *this* box set up right, and does a
+   message actually flow?"
+
+Read alongside these, not after: **[SUPPORT-POLICY.md](SUPPORT-POLICY.md)** — only the latest version is
+supported, and re-pinning a security release is mandatory and clocked.
+
+Evaluating rather than installing? Start at **[FEATURE-MAP.md](FEATURE-MAP.md)**, the capability
+catalog, and **[../CHANGELOG.md](../CHANGELOG.md)**, which is authoritative for what is actually built.
+
+---
+
+## Operators and adopters
+
+| Document | What it answers |
+|---|---|
+| [EARLY-ADOPTER-GUIDE.md](EARLY-ADOPTER-GUIDE.md) | The whole install-to-production journey, in order. |
+| [SYSTEM-REQUIREMENTS.md](SYSTEM-REQUIREMENTS.md) | Hardware, OS, Python floor, store backends, ports, sizing. |
+| [INSTALL-GUIDE.md](INSTALL-GUIDE.md) | Pinned wheel + your own config repo; the ADR 0017 deployment model. |
+| [USER-GUIDE.md](USER-GUIDE.md) | How do I actually do X — authoring, operating, troubleshooting. |
+| [CONFIGURATION.md](CONFIGURATION.md) | Every settings key, what each gate refuses, and why. |
+| [CONNECTIONS.md](CONNECTIONS.md) | Every transport and message type, and how to author each. |
+| [DEPLOYMENT.md](DEPLOYMENT.md) | Trust boundaries, TLS posture, egress, bind guards. Read before exposing anything. |
+| [testing/VERIFY.md](testing/VERIFY.md) | On-box acceptance check: is this machine set up correctly? |
+| [SUPPORT-POLICY.md](SUPPORT-POLICY.md) | What is supported, and the clock on re-pinning security releases. |
+| [ANTIVIRUS-FIREWALL.md](ANTIVIRUS-FIREWALL.md) | Exact paths, processes and ports to exclude or open (Windows/NSSM). |
+| [SERVICE.md](SERVICE.md) | Running the engine as a long-lived service. |
+| [CLUSTERING.md](CLUSTERING.md) | Active/passive HA for the engine itself. |
+| [CLOUD-DEPLOYMENT.md](CLOUD-DEPLOYMENT.md) | Multi-node HA on Kubernetes or cloud, with managed Postgres. |
+| [CLOUD-PHI-HIPAA.md](CLOUD-PHI-HIPAA.md) | The PHI/HIPAA considerations that pair with cloud deployment. |
+| [AOAG-DEPLOYMENT.md](AOAG-DEPLOYMENT.md) | Two-datacenter HA behind a SQL Server Always On AG. For DBAs. |
+| [DEPLOY-SERVER-DB.md](DEPLOY-SERVER-DB.md) | Store setup on a real database server. |
+| [ADOPTER-CI.md](ADOPTER-CI.md) | CI for **your config repo** — and honestly, what it does not prove. Not the engine's CI. |
+| [ASVS-L2-PHASE0-CHANGES.md](ASVS-L2-PHASE0-CHANGES.md) | Operator notes for one hardening phase; §4–§5 are the living crypto and comms inventories. |
+| [AI.md](AI.md) | How the shipped AI assistant is governed: modes, data scopes, RBAC, the PHI guarantee. |
+| [DICOM.md](DICOM.md) · [HL7-VALIDATION.md](HL7-VALIDATION.md) · [CODESETS.md](CODESETS.md) | Per-domain references. |
+
+## Developers building on the engine
+
+| Document | What it answers |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | How the engine decomposes: topology, store-as-queue, concurrency, module map. |
+| [architecture-diagram.md](architecture-diagram.md) | The same structure as a picture. |
+| [MENTAL-MODEL.md](MENTAL-MODEL.md) | The conceptual model behind the pipeline. |
+| [FEATURE-MAP.md](FEATURE-MAP.md) | The capability catalog — what exists, what is deferred, what was declined. |
+| [adr/](adr/) | **150 files.** Architecture decision records: *why* a thing is the way it is. Append-only history — a decision is superseded by a new ADR, never rewritten. Start at [adr/README.md](adr/README.md). |
+
+## Security reviewers
+
+| Document | What it answers |
+|---|---|
+| [../.github/SECURITY.md](../.github/SECURITY.md) | **Vulnerability disclosure policy.** Report here. |
+| [SECURITY.md](SECURITY.md) | Authentication and RBAC — *not* the disclosure policy, despite the name. |
+| [PHI.md](PHI.md) | Where PHI can and cannot go, and what the engine guarantees. |
+| [ASVS-L2-PHASE0-CHANGES.md](ASVS-L2-PHASE0-CHANGES.md) | §4 key/crypto inventory and §5 communications inventory, both CI-drift-guarded. §1–§3 are a historical phase changelog. |
+| [Secure_Development_Standards.md](Secure_Development_Standards.md) | The standards the build process holds itself to. |
+| [SECURITY-LOOSENING.md](SECURITY-LOOSENING.md) | The inverse of a hardening guide: every `[security]` switch defaults to the protective position, and this is what moving one off it costs. |
+| [SECURITY-DOCS-POLICY.md](SECURITY-DOCS-POLICY.md) | **Read this before hunting for a threat model.** The threat model, the ASVS assessments and the risk-acceptance register are deliberately *not* published; this explains what is public, what is withheld, and how to ask. |
+
+## Maintainers and contributors
+
+| Document | What it answers |
+|---|---|
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) | How to contribute. |
+| [CI.md](CI.md) | What runs on a PR in **this** repo and which checks gate a merge. Not `ADOPTER-CI.md`. |
+| [Code_Quality_Standards.md](Code_Quality_Standards.md) | The quality rubric. Contains a dated (July 2026) graded self-assessment — treat the grade as a snapshot. |
+| [BACKLOG.md](BACKLOG.md) | **777 KB / 7,157 lines.** The maintainer work surface — ranked, deferred and declined items, including superseded sections. A required CI check keeps it current, but it is *not* a description of the product. For what the engine does, use `FEATURE-MAP.md`; for what is built, `CHANGELOG.md`. |
+| [SECURITY-REMEDIATION-LEDGER.md](SECURITY-REMEDIATION-LEDGER.md) | Single-writer coordination ledger for the 2026-06-26 audit-wave remediation. A dated work record, not a posture statement. |
+
+---
+
+## Historical and planning artifacts
+
+These directories are **dated records kept for provenance. Do not follow them as instructions** — many
+describe plans that were superseded, and several state "next steps" that shipped long ago.
+
+| Directory | Size | What it is |
+|---|---|---|
+| [releases/](releases/) | ~100 files | Multi-session build plans and session handoffs. History. |
+| [benchmarks/](benchmarks/) | ~42 files | Measurement records and inter-session review notes. The numbers are dated; the *method* is the reusable part. |
+| [research/](research/) · [design/](design/) · [archive/](archive/) | ~15 files | Exploratory and superseded material. |
+| [quality-gates/](quality-gates/) | 1 file | A single gate record. |
+
+Individually dated documents worth knowing are historical rather than current:
+
+- **[CI-SELFHOSTED-RUNNER.md](CI-SELFHOSTED-RUNNER.md)** — carries its own **RETIRED** banner. The
+  runners are de-registered. It also still contains a "the repo is private" security rationale that the
+  retirement itself invalidates.
+- **[CI-QUALITY.md](CI-QUALITY.md)** — a plain-language summary dated **June 20, 2026**, written for a
+  non-technical evaluator. Its test counts have since moved; `CI.md` is the accurate technical version.
+- **[REMOTE-CONSOLE.md](REMOTE-CONSOLE.md)** and
+  **[REMOTE-CONSOLE-CUSTOMER-GUIDE.md](REMOTE-CONSOLE-CUSTOMER-GUIDE.md)** — both describe the
+  **retired** PySide6 desktop console (BACKLOG #103, 2026-07-13).
+- **[AI-OFF-MATRIX.md](AI-OFF-MATRIX.md)** — a coverage matrix from an internal plan. Its subject
+  (working in the IDE with AI assist switched off) matters to adopters in PHI environments, but the
+  document is keyed to internal item numbers.
+
+---
+
+## Repository-root documents
+
+Not under `docs/`, and easy to miss:
+
+| File | What it is |
+|---|---|
+| [../README.md](../README.md) | Project overview. |
+| [../CHANGELOG.md](../CHANGELOG.md) | **Authoritative for build state** — what actually shipped, per release. |
+| [../.github/SECURITY.md](../.github/SECURITY.md) | Vulnerability disclosure policy. |
+| [../CONTRIBUTING.md](../CONTRIBUTING.md) · [../GOVERNANCE.md](../GOVERNANCE.md) · [../MAINTAINERS.md](../MAINTAINERS.md) | Project process. |
+| [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md) · [../CLA.md](../CLA.md) | Participation terms. |
+| [../LICENSE](../LICENSE) · [../NOTICE](../NOTICE) · [../COMMERCIAL-LICENSE.md](../COMMERCIAL-LICENSE.md) | Licensing. |
+
+---
+
+*This index is maintained by hand. If you add a document, add its row — and if it is a dated plan or a
+one-off evaluation, put it under Historical and planning artifacts, not in a reference table.*