DOCS-README-STANDARDS

Tier: Public Status: v1.1 — Phase 4 CI gate landed 2026-05-18 (Docs slice feature-complete) Audience: contributors, documentation reviewers, future-maintainers running an audit pass against the module-README set. Document role: the canonical template + audit checklist for every module-level README.md in the repository. Anchors the "public-flip-quality module READMEs" bar described in PLATFORM-ARCHITECTURE.md §10.1.

---

Module README standards

1. Why this standard exists

The repository targets a July 2026 public alpha per PLATFORM-ARCHITECTURE.md §10.1. At that moment, every README.md outside the internal/ tree becomes a first-impression artifact for one of three audiences:

1. Future maintainers and contributors — the people who will keep this project alive across decades. The README is the durable artifact; the chat history is not.
2. Self-hosting operators and platform evaluators — technical decision-makers assessing Umbraculum as a long-term dependency.
3. Prospective module developers — partners building verticals or integrations on top of the platform.

A README that does not serve at least one of these audiences clearly should be revised (the mandate is identical to the one in README.md §"Audience for this set", applied at the module level).

The Types slice (TYPING.md, feature-complete 2026-05-18) made the codebase trustworthy at the type-system layer. The Docs slice extends that trust to the documentation layer: every module a public-flip reader could click into has a README that explains what it is, how it fits in, and how to use it locally, in a consistent voice.

This document is the single source of truth for that consistency. It is intentionally short — the standard is small enough to internalize, the template is small enough to copy/paste, and the audit checklist is small enough to run in one sitting per workspace.

---

2. Scope — which READMEs this applies to

2.1 In scope (the module-README set)

This standard governs the README.md at the root of every published workspace:

Path	Module type
apps/web/README.md	Application
apps/web/e2e/README.md	Sub-application (E2E test suite)
apps/native/README.md	Application
services/api/README.md	Service
docs-site/README.md	Documentation application
packages/sdk/ai-tool-sdk/README.md	Package (TS, MIT SDK contract)
packages/sdk/i18n-keys/README.md	Package (TS, MIT SDK contract)
packages/platform/api-client/README.md	Package (TS, npm-publishable)
packages/verticals/brewery/beerjson/README.md	Package
packages/platform/contracts/README.md	Package
packages/sdk/module-sdk/README.md	Package (TS, MIT SDK contract)
packages/platform/i18n/README.md	Package
packages/platform/i18n-react/README.md	Package
packages/platform/media/README.md	Package
packages/platform/navigation/README.md	Package
packages/platform/rendering/README.md	Package (document / file rendering scaffold)
packages/verticals/brewery/recipes-ui/README.md	Package
packages/verticals/brewery/core/README.md	Package (brewery-vertical, @umbraculum/brewery-core)
packages/platform/test-mcp/README.md	Package (developer-tooling, runtime tools server)
packages/platform/ui/README.md	Package

Sub-component READMEs (e.g. services/api/src/seed/README.md) are lighter-scope — they follow the spirit of the template (headline, one-paragraph "what / why", concrete next-step guidance) but do not need every section. The audit checklist marks which sections are required vs. optional for sub-component READMEs.

2.2 Out of scope (intentionally not standardized here)

Path	Reason
README.md (repo root)	Has its own structure (target audience: anyone landing on the GitHub page). Already public-flip-quality. The standard applies in spirit — terminology, tone, brand framing — but the section list differs.
docs/README.md	Index for the docs folder, not a module. Has its own conventions described in-file.
docs/archive/README.md	Archive landing page; documents what's superseded. Not a module.
docs/help/README.md	End-user help index (placeholder until content lands).
internal/**/README.md	Internal tier — intentionally not public-flip-quality. Has its own conventions in internal/README.md (not linked from public docs; not published on the docs site).
apps/native/.expo/README.md	Auto-generated by Expo and gitignored on most surfaces; not authored content.
Cursor plugin skills/*/SKILL.md files	Cursor-tooling internal; not part of the public-flip surface.

---

3. Public identity and positioning

When writing or auditing a module README, use these tokens and positioning statements consistently.

Surface	Use
Platform name in prose	Umbraculum
One-line positioning	"an open-source toolset for building workspace-shaped operational applications"
Scope examples	Simple organizational tools such as PIM and quality-assurance workflows through complex manufacturing and process systems
Brewery in prose	On first mention in a non-brewery doc: brewery (reference vertical) or the brewery reference vertical — the Tier 6 example product in this monorepo, not the platform identity. Full convention: GLOSSARY.md §"Documentation convention — citing brewery".
Marketing short / CLI	UMB
Primary domain	umbraculum.dev
GitHub org	umbraculum-dev
Mascot	Umbi (canonical asset at media/umbi.png)
Brewery vertical	"the brewery vertical" (lowercase; it is a configuration of Umbraculum, not a separate product)
Title of the README	The literal package.json "name" field — @umbraculum/<package> for platform npm packages, @umbraculum/brewery-<package> for brewery-vertical npm packages (per sub-plan #9 §1.3 TRAP-avoidance discipline), @umbraculum/<app> for application workspaces, plain workspace name for services
Install / import snippets	Same — match the actual package.json "name"

3.1 Package-scope state — sub-plan #9 closed (historical note)

The npm scope @umbraculum/* (with brewery-vertical packages re-scoped under @umbraculum/brewery-*) is the live state as of 2026-05-19.

Earlier revisions of this section described a "parking" arrangement while sub-plan #9 was in flight; that arrangement is closed. README titles and imports must use the current @umbraculum/* / @umbraculum/brewery-* names verbatim — they match each workspace's package.json "name" field and resolve at the package-manager layer through the workspaces convention. Code snippets, npm command examples, install/import sections, and project callouts all use the current scope only.

---

4. Template (copy/paste)

A new module README starts from this template. Strip optional sections that don't apply; never add sections outside this set without first updating the standard.

[!NOTE] The relative paths inside the template (../../README.md, ../../docs/...) assume the README is at depth-2 from repo root — i.e. packages/<foo>/README.md, apps/<app>/README.md, or services/<svc>/README.md. For READMEs at depth-3 (e.g. apps/web/e2e/README.md, services/api/src/seed/README.md), use ../../../ instead. The Phase-4 markdown link-checker treats fenced code blocks as opaque, so the template's "broken" links (relative to this file) do not fail the gate.

# @umbraculum/<package-name>

<!-- One-line tagline. What this module is, in plain language. No marketing
     fluff. Maximum one comma. -->

> [!NOTE]
> Part of [Umbraculum](../../README.md) — an open-source toolset for building
> workspace-shaped operational applications. Renamed from
> `@brewery/<package-name>` to `@umbraculum/<package-name>` (or
> `@umbraculum/brewery-<package-name>` for brewery-vertical packages — see
> sub-plan #9 §1.3) as sub-plan #9 slot N (closed 2026-05-19); see
> [`docs/design/brewery-scope-migration-plan.md`](../../docs/design/brewery-scope-migration-plan.md).

## What this is

<!-- One short paragraph (3-6 lines). What the module does. Who consumes it
     (web, native, api, e2e, all). What it intentionally does not do. Link
     to docs/PLATFORM-ARCHITECTURE.md for the platform-level framing on
     first mention of "Umbraculum". -->

## Scope

<!-- A "contains / does not contain" pair, formatted as a bullet list. This
     is the most-asked-question by a new contributor and must be obvious. -->

- **Contains**: …
- **Does not contain**: …

## Exports / Surface

<!-- For a package: the public exports (functions, types, constants).
     For an application: the surface (routes, ports, env vars).
     For a service: the surface (HTTP routes, queues, cron jobs).
     Use a table when there are >3 entries; bullet list otherwise. -->

## Usage

<!-- One minimal end-to-end example per consumer surface. For packages
     consumed by both web and native, show one example per platform.
     Code blocks must be runnable; do not abbreviate paths. -->

```ts
import { … } from "@umbraculum/<package>";
```

## Build / test / lint (local)

<!-- Container-only commands per the node-npm-container-only rule. Run from
     the repo root unless explicitly noted. Do not show host-npm commands. -->

- Build: `npm run build:packages` (or `./scripts/build-packages-in-docker.sh` for the Docker route)
- Test: `npm run test --workspace=@umbraculum/<package>` (or container-equivalent)
- Lint: `npm run lint --workspace=@umbraculum/<package>`
- Typecheck: handled by the per-workspace typecheck CI gate; see [`docs/TYPING.md`](../../docs/TYPING.md) §"Per-workspace CI gate"

## How it fits in

<!-- Two-to-four bullets. What depends on this module. What this module
     depends on. Link to PLATFORM-ARCHITECTURE.md or other docs/* files
     for the architectural reasoning. -->

- Consumed by: …
- Depends on: …

## Status

<!-- One short paragraph or a single-row table. What's stable. What's
     experimental. What's intentionally not built yet. Be honest. -->

## Further reading

<!-- 2-5 cross-references max. Relative links into docs/ and into
     sibling modules. -->

- [`docs/PLATFORM-ARCHITECTURE.md`](../../docs/PLATFORM-ARCHITECTURE.md) — platform-level framing
- …

---

5. Audit checklist (run per README)

This is the canonical checklist used in Docs slice Phase 2 (audit + standardize the 8 existing module READMEs) and applied to every new README in Phase 3. A README that fails any must check is not public-flip-quality.

5.1 Must-haves

• Title matches the literal package.json "name" field — typically # @umbraculum/<package> for platform packages, # @umbraculum/brewery-<package> for brewery-vertical packages, # @umbraculum/<app> for application workspaces, or the plain workspace name for non-scoped services.
• One-line tagline directly under the title (no blank line between the tagline and the next section heading is acceptable).
• Project callout (the > [!NOTE] block) appears once near the top, mentions "Umbraculum", and uses the positioning from §3.
• "What this is" section: 3-6 lines, explains the module without requiring the reader to leave the file.
• "Scope" section: an explicit "Contains / Does not contain" pair.
• At least one of: "Exports / Surface", "Usage" (whichever is more meaningful for the module type).
• "Build / test / lint (local)" section: commands are container-friendly per the node-npm-container-only skill shipped by umbraculum-node-react-cursor-assistant.
• At least two cross-references via relative links — one into docs/ (typically docs/PLATFORM-ARCHITECTURE.md) and one into a sibling module or the repo root.
• All code blocks are runnable as-shown (no <placeholder> strings inside command lines).
• No obsolete placeholder tokens or pre-resolution brand-discussion history in public prose.

5.2 Should-haves

• "How it fits in" section with explicit consumed-by / depends-on bullets.
• "Status" section being honest about what's stable / experimental / not-yet-built.
• "Further reading" section with 2-5 cross-references.
• Tables used for matrix-style information (>3 entries of the same shape).

5.3 Should-not-haves

• No marketing fluff or superlatives ("blazing fast", "world-class", "best-in-class").
• No tone shift mid-document (the README opens technical, it stays technical).
• No section headings deeper than ###.
• No emojis (per the repo-wide tone-and-style convention; the brand mascot Umbi is the only canonical playful element, and it lives at docs/media/umbi.png, not in module README prose).
• No reliance on outbound http:// links for primary navigation — relative paths only, except where pointing to canonical external resources (the project's own umbraculum.dev, registry pages, upstream library docs).

5.4 Sub-component READMEs (lighter scope)

For READMEs at sub-paths (e.g. services/api/src/seed/README.md), the must-haves reduce to:

• Title (any clear noun phrase; doesn't have to match a package.json name).
• One-line tagline.
• "Why this exists" or "What this is" paragraph.
• At least one concrete actionable item (a command, a link, a TODO list).
• No obsolete placeholder tokens or pre-resolution brand-discussion history in public prose.

The brand callout, the audit-checklist's bigger sections, and the architectural cross-references are optional at this scope.

---

6. Voice and tone

The standard inherits the canonical voice described in docs/README.md §"Contributing to the documentation":

New documents should follow the existing tone: precise about decisions, honest about trade-offs, and explicit about what is not settled.

Concretely, for module READMEs:

• Precise: a contributor who reads the README and then opens src/index.ts should not be surprised. If the README claims "exports createApiClient", that export must exist.
• Honest about trade-offs: if a package has a known limitation (e.g. api-client's "webview caveat" — bearer-only native auth doesn't carry web sessions automatically), the README says so.
• Explicit about what is not settled: if a package is rough, sparse, or pre-1.0, the "Status" section says that. Avoid the temptation to over-promise to make the public flip look better; readers see through it and lose trust faster than they'd lose trust from honest scope-marking.

The mascot Umbi (the canonical asset at media/umbi.png) is the only playful element across the public-doc surface, and it does not appear in module READMEs by default — its home is onboarding, error/empty-state illustrations, and the homepage at umbraculum.dev. Module READMEs are read by people doing technical work; the playful surface is reserved for surfaces where playfulness reduces friction.

The brochure site (umbraculum-brochure, umbraculum.dev) follows the same voice with stricter visual discipline: no startup marketing aesthetics (rockets, neon heroes, hype copy). Mindset: less ego, more facts — see design/brochure-site-design-policy.md.

---

7. Cross-references

• README.md — repo entry point; demonstrates the public-flip-quality voice at the top level.
• docs/README.md — docs-folder index; demonstrates the same voice for index-style documents.
• docs/PLATFORM-ARCHITECTURE.md — platform vision and public positioning; the canonical "first mention of Umbraculum" anchor.
• docs/TYPING.md — Types slice (feature-complete 2026-05-18); the layer this Docs slice extends trust into.
• docs/TESTING.md — Testing layer map; the typed-as-tested companion.
• internal/README.md (repository only; not on the public docs site) — tier-marker conventions and cross-link discipline. This standard inherits the public docs MUST NEVER link to internal docs invariant.
• node-npm-container-only skill (shipped by umbraculum-node-react-cursor-assistant) — container-only command-execution rationale.

---

8. Decisions deferred to follow-on work

Deferred decision	Trigger condition	Owner
Apply the standard mechanically to top-level README.md and docs/README.md	Originally anchored on the close of sub-plan #9 — that closed 2026-05-19; the second-pass work is now unblocked	Docs maintainer
Public-alpha rendering preview (visual proof the READMEs render cleanly on github.com when public)	Public alpha is now targeted for July 2026 per PLATFORM-ARCHITECTURE.md §10.1	Docs maintainer + flip-coordinator
Standard for docs/help/ end-user content (different audience: workspace operators, not contributors)	First content lands in docs/help/ as the brewery vertical UI matures	Help-content owner (not yet assigned)

8.1 CI gate (LANDED 2026-05-18 — Docs slice Phase 4)

The CI gate originally listed as deferred above landed on 2026-05-18 as Docs slice Phase 4. It enforces the must-have checklist from §5.1 against the in-scope set from §2.1 (full template) plus §5.4 (sub-component lighter scope), via:

• Workflow: .github/workflows/docs-readmes.yml. Triggers on push/PR touching any **/README.md, docs/DOCS-README-STANDARDS.md, scripts/docs/**, or the workflow itself. Mirrors the typecheck gate's topology (bounded path filter, single ubuntu-latest runner, concurrency-cancel on stale runs).
• Checker: scripts/docs/check-readmes.py. Zero-dependency Python (stdlib only, runs against python3 already present on the runner). Per-README aggregation: every in-scope file is checked, failures collected with specific reasons, exit code is non-zero if any file fails so the PR run surfaces every regression at once rather than failing on the first.

The checker enforces the following subset of §5.1's must-haves (those that can be checked structurally):

1. Title matches package.json "name" field for full-scope READMEs.
2. Tagline present within 3 lines of the title.
3. Project callout present (> [!NOTE] block with Umbraculum mention and current positioning).
4. Required ## headings present: What this is, Scope, Build / test / lint (local) (full scope); What this is or Why this exists (sub-component scope).
5. ≥2 cross-references via relative links, with ≥1 into the docs/ tree (full scope only).
6. All relative links (excluding fenced code blocks) resolve to existing files.
7. No obsolete placeholder tokens or pre-resolution brand-discussion history in public prose.

Items the gate cannot mechanically check (inherent prose-quality constraints from §5.1's "must-haves" list — voice, honesty about trade-offs, "no marketing fluff", "no emojis except the canonical Umbi which lives outside module READMEs") remain the responsibility of the reviewer per the standard's §6 voice-and-tone guidance. The gate is the floor, not the ceiling.

---

9. Sign-off

Standard version: v1.1 Landed: 2026-05-18 (Docs slice — feature-complete: Phase 1 published the standard; Phase 2 audited the existing 8 READMEs; Phase 3 wrote the 6 missing READMEs; Phase 4 landed the CI gate). Next anchor: the post-sub-plan-#9 doc-tier closeout — sub-plan #9 closed 2026-05-19; §3.1 was rewritten in slot 14 from "parking guidance" to "historical closure note", and the structural checker's @umbraculum/* exclusion check was already retired in an earlier slot. The "apply this standard to top-level README.md and docs/README.md" item in §8 is now unblocked.

This document is versioned — substantive changes (adding/removing must-haves, changing the template structure, adding/removing CI-gate checks) bump the version and update the status banner. Cosmetic edits do not.