ADR 0034 documentation standard publication

.claude/CLAUDE.md

@@ -108,7 +108,9 @@ for full ownership details.
 ### Architecture documentation
 
 - ADRs go in `docs/architecture/adr/` with format `####-title.md`
-- Follow existing ADR structure (Status, Context, Decision, Consequences)
+- Follow the MADR structure from the template on the ADR index (`docs/architecture/adr/index.mdx`):
+  frontmatter (`adr`, `status`, `date`, `tags`), Context and problem statement, Considered options,
+  Decision outcome
 
 ## Testing before committing
 

custom-words.txt

@@ -52,6 +52,7 @@ LLDB
 Lucidchart
 Mailcatcher
 minio
+mortems
 MVVM
 NGRX
 Napi
@@ -107,6 +108,7 @@ typecheck
 typechecks
 typesafe
 udeps
+ungated
 unsynchronized
 WCAG
 weweave

docs/architecture/adr/0033-adopt-mermaid-diagram-standard.md

@@ -37,9 +37,9 @@ audience-specific views -- requires substantial rework per audience in practice.
 ## Decision outcome
 
 Chosen option: **Mermaid with defined conventions**, published as the
-[diagram standard](../../contributing/diagrams.md) on the contributing site. The standard is the
-living reference and its rules evolve by PR without superseding this decision. This ADR is
-superseded only if the chosen option itself changes. A snapshot of the rules at adoption:
+[diagram standard](../../contributing/documentation/diagrams.md) on the contributing site. The
+standard is the living reference and its rules evolve by PR without superseding this decision. This
+ADR is superseded only if the chosen option itself changes. A snapshot of the rules at adoption:
 
 1. Diagrams are Mermaid source text, nothing else: as Mermaid code blocks, or, if in Confluence, via
    Macro Pack's Mermaid diagram in text-input mode.
@@ -80,12 +80,12 @@ superseded only if the chosen option itself changes. A snapshot of the rules at
 
 ### Plan
 
-The standard is published at Contributing › Diagrams, and the bulk of the contributing site's
-existing diagrams (PlantUML/Kroki sources, static diagram assets, and source-less images) have been
-converted to comply, so the site becomes the reference implementation of the standard, with the
-exceptions noted below. Elsewhere, legacy diagrams convert when their docs are next touched: images
-and non-Mermaid sources in repos become Mermaid code blocks, and Confluence attachments and images
-become Macro Pack's Mermaid diagram in text-input mode.
+The standard is published at Contributing › Documentation › Diagrams, and the bulk of the
+contributing site's existing diagrams (PlantUML/Kroki sources, static diagram assets, and
+source-less images) have been converted to comply, so the site becomes the reference implementation
+of the standard, with the exceptions noted below. Elsewhere, legacy diagrams convert when their docs
+are next touched: images and non-Mermaid sources in repos become Mermaid code blocks, and Confluence
+attachments and images become Macro Pack's Mermaid diagram in text-input mode.
 
 The remaining adoption work is delegated to its owners:
 

docs/architecture/adr/0034-adopt-engineering-documentation-standard.md

@@ -1,6 +1,6 @@
 ---
 adr: "0034"
-status: Proposed
+status: Accepted
 date: 2026-08-05
 tags: [clients, mobile, server, sdk]
 ---
@@ -38,10 +38,10 @@ Confluence against a proposed routing model, confirming these gaps.
 
 ## Decision outcome
 
-Chosen option: **one org-wide, docs-as-code documentation standard**, published as the Documentation
-section under Contributing on this site. The standard is the living reference. Its rules evolve by
-PR without superseding this decision and this ADR is superseded only if the model itself changes. A
-snapshot of the rules at adoption:
+Chosen option: **one org-wide, docs-as-code documentation standard**, published as the
+[Documentation section](../../contributing/documentation/index.md). The standard is the living
+reference. Its rules evolve by PR without superseding this decision and this ADR is superseded only
+if the model itself changes. A snapshot of the rules at adoption:
 
 1. **Public by default**. Private content is limited to documentation about working at Bitwarden and
    sensitive information.
@@ -54,7 +54,7 @@ snapshot of the rules at adoption:
 
 Diagrams follow the separate diagram standard adopted in
 [ADR-0033](./0033-adopt-mermaid-diagram-standard.md), which keeps its own living reference at
-Contributing › Diagrams.
+Contributing › Documentation › Diagrams.
 
 AI instruction files are explicitly not documentation and are out of the standard's scope. Their
 guidance lives with the AI tooling.

docs/architecture/adr/index.mdx

@@ -75,6 +75,68 @@ the thinking process and alternatives considered rather than simply stating what
 if an ADR doesn't cover every edge case or alternative it provides valuable context and can be
 refined through discussion.
 
+## Format
+
+ADRs follow the [MADR](https://adr.github.io/madr/) structure: a context and problem statement, the
+considered options, and the decision outcome with its consequences. Start from the template below.
+
+Each ADR is a file named `NNNN-short-title.md` in `docs/architecture/adr/`, numbered with the next
+unused number. Refer to an ADR elsewhere by that number as ADR-NNNN, linking the file relatively so
+the reference survives a move of this section.
+
+<details>
+<summary>ADR template</summary>
+
+Delete the guidance comments before opening the pull request.
+
+```text
+---
+adr: "NNNN"
+status: Proposed
+date: YYYY-MM-DD
+tags: [clients, mobile, server, sdk]
+---
+
+# NNNN - Short imperative title
+
+<AdrTable frontMatter={frontMatter}></AdrTable>
+
+{/* Optional "## Notation" section here if the ADR relies on notation (RFC 2119
+    keywords, symbols). Delete when unused. */}
+
+## Context and problem statement
+
+{/* 2–4 paragraphs. What situation forces a decision? What breaks or
+    stays painful if we decide nothing? Link code, issues, and prior ADRs. */}
+
+## Considered options
+
+- **Option A:** one-line description.
+- **Option B:** one-line description.
+
+{/* Optional per-option subsections with pros/cons when the tradeoffs
+    need more than a line. Include "do nothing" when it is a real option. */}
+
+## Decision outcome
+
+Chosen option: **Option A**, because {decisive reason}.
+
+### Positive consequences
+
+- ...
+
+### Negative consequences
+
+- ...
+
+### Plan
+
+{/* How the decision takes effect: the follow-up work, migrations, and owners.
+    Delete when the ADR needs no follow-up. */}
+```
+
+</details>
+
 ## Status definition
 
 ADRs progress through different statuses throughout their lifecycle. Understanding these statuses

docs/contributing/documentation/component-documentation.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 1
+---
+
+# Component documentation
+
+**Audience:** Bitwarden engineers and AI agents writing or consuming in-repo documentation.
+
+Notation follows the [documentation standard's Notation](./index.md#notation). These requirements
+hold for every repo for as long as it lives, enforced by review and the doc-parity plugin. New
+repositories satisfy them at initialization by starting from
+[bitwarden/template](https://github.com/bitwarden/template). Existing repos converge per
+[Changes to this standard](./index.md#changes-to-this-standard). Additional local guidance MAY be
+layered on top, as each situation dictates.
+
+Any component that other engineers or agents consume (that is, it exposes a public interface) MUST
+have an **entry point for its scope's documentation**, at every scope from a single component to the
+repo root. The entry point lives where the component's ecosystem surfaces documentation:
+
+- At **component scope**, the entry point is the `README.md`, which registries render for packaged
+  components (a crate, an npm package, a NuGet project). Rust crates keep the README and the rustdoc
+  landing page one artifact with `#![doc = include_str!("../README.md")]`.
+- **Below component scope**, the entry point is the language's module-level documentation where it
+  exists (`//!` in Rust), since a README there duplicates what the toolchain already owns and no
+  tooling surfaces it. It SHOULD be lint-enforced where the language supports it (Rust's
+  `missing_docs`).
+- At **container and system scopes** (a container grouping several components, the repo root), the
+  entry point is a `README.md`, since no language ecosystem claims them.
+
+Whatever its carrier, the entry point MUST contain:
+
+1. **Purpose:** what problem this component solves, in 1–3 sentences.
+2. **Key concepts:** the domain model or invariants a consumer must know (e.g., `libs/state`'s
+   data-loss warning on key renames; `bitwarden-crypto`'s `derive_`/`make_` naming rules).
+3. **Usage:** the primary entry points, with a short code sample where the API is not self-evident.
+4. **Gotchas / constraints:** the things that bite people (e.g., `libs/auth`'s "do not add new code
+   here" notice). This section MUST exist when such constraints do and MUST NOT exist when they do
+   not.
+
+Documentation grows outward from the entry point of the
+[lowest common ancestor](./index.md#where-documentation-lives-rules-1-2) of the code it describes. A
+guide spanning several components therefore belongs to their parent scope:
+
+1. Everything starts at the scope's entry point.
+2. A single topic that deserves its own document becomes a named `.md` next to the code it
+   describes, linked from the entry point (`apps/browser/src/autofill/lifecycle.design.md` is the
+   exemplar).
+3. When the scope's documentation outgrows this, it splits into a `docs/` folder (exactly that name,
+   lowercase) at the scope root. `docs/` exists only beside the entry point it extends: at the repo
+   root (`clients/docs/cipher-types.md` is the exemplar) or a component with its own entry point
+   (`util/Seeder/Seeds/docs/`), never an arbitrary subdirectory.
+
+Scopes layer and multiple perspectives exist. A parent scope's documentation MAY describe the same
+code at a higher altitude, sanding off detail the deeper docs own and linking down to them, and the
+same subject MAY be documented separately per audience. Both are approved. Duplication is two
+artifacts sharing one perspective.
+
+Below component scope, reference documentation is code: doc comments on public symbols, reviewed and
+merged with functionality, lint-enforced where the platform supports it. Doc comments MUST follow
+the language's documentation norms for structure and detail. Where not enforced by the type system,
+doc comments MUST say what a caller needs (behavior, invariants, error cases). Repos with doc CI
+SHOULD fail the build on broken docs (the `sdk-internal` `cargo doc -D warnings` pattern).

docs/contributing/diagrams.md → docs/contributing/documentation/diagrams.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 5
 ---
 
 # Diagram standard
@@ -103,14 +103,14 @@ vocabulary. The example above is at context level.
 
 C4 is adopted as a **mental model only**. We are explicitly **NOT** adopting any C4 tooling/DSL.
 
-## Ownership and currency (rules 7 and 8)
+## Ownership and updates (rules 7 and 8)
 
-- The owner is CODEOWNERS for in-repo docs and the page's owning team on Confluence.
+- The owner is `CODEOWNERS` for in-repo docs and the page's owning team on Confluence.
 - Updates land in the same PR or page edit as the change the diagram depicts. A diagram known to be
   wrong is deleted or updated rather than left to mislead.
 - Every repo's root `CLAUDE.md` MUST carry the base documentation obligations, which cover diagrams:
   when you change code that a diagram describes, update the diagram in the same change. The
-  doc-currency plugin in [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) distributes
+  doc-parity plugin in [bitwarden/ai-plugins](https://github.com/bitwarden/ai-plugins) distributes
   the obligation and enforces it across every documented scope above a change. The plugin's own
   documentation owns the mechanism.
 - Agent-authored diagrams follow the same rules. Generated diagrams MUST carry a perspective caption