fastrevmd-lab · Oct 7, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -21,6 +21,7 @@ inspectable, and honest are very welcome.
 - Match the surrounding code's style; explain the "why" in the description.
 - Include tests where the project has them, and note how you verified the change.
 - Label maturity honestly: if something is partial or unverified, say so.
+- For README changes, follow the [README opening template](README-TEMPLATE.md).
 
 ## Ground rules
 - Deterministic decides, the model explains, a human approves — don't add an

diff --git a/README-TEMPLATE.md b/README-TEMPLATE.md
@@ -0,0 +1,62 @@
+# README opening template
+
+Use this opening for every mechub repository. Keep the first screen useful to
+an operator: state the value, show the maturity, explain the project, and give
+the shortest safe path to a first local run.
+
+```markdown
+# <project name>
+
+<One sentence describing the value this project provides.>
+
+![Status: <Planned|Alpha|Beta|Stable>](https://img.shields.io/badge/status-<planned|alpha|beta|stable>-<color>)
+
+a mechub project — sovereign AI operations for network and security teams
+
+<Two or three sentences explaining what the project does, who it is for, and
+what it connects to or produces.>
+
+## Quick start
+
+<The smallest offline-capable setup and first useful command. Link to
+prerequisites or configuration details when needed.>
+```
+
+## Status vocabulary
+
+Use exactly one of these maturity labels in the status badge:
+
+| Status | Badge | Use when |
+| --- | --- | --- |
+| Planned | `status-planned-lightgrey` | The project is proposed or not yet usable. |
+| Alpha | `status-alpha-blue` | An early usable version exists; interfaces and behaviour may change. |
+| Beta | `status-beta-yellow` | The project is usable for evaluation; interfaces are stabilising. |
+| Stable | `status-stable-brightgreen` | The supported path is established and maintained. |
+
+Use the matching Shields.io status segment in the opening badge; do not create
+additional maturity labels or colors:
+
+```markdown
+![Status: Planned](https://img.shields.io/badge/status-planned-lightgrey)
+![Status: Alpha](https://img.shields.io/badge/status-alpha-blue)
+![Status: Beta](https://img.shields.io/badge/status-beta-yellow)
+![Status: Stable](https://img.shields.io/badge/status-stable-brightgreen)
+```
+
+Do not use `In production` to describe a maintainer's own homelab or lab
+deployment. Say `running in the maintainer's lab` in prose instead. Reserve
+production claims for deployments and evidence that the project can actually
+support.
+
+## README maintenance rules
+
+- Keep the value statement to one sentence and put it before the badge.
+- Keep the canonical subtitle exactly as shown in the template.
+- Put release history and release narrative in `CHANGELOG.md`.
+- Put lab notes, experiments, and deployment observations in `docs/`.
+- Tool-count badges must match the release they describe. If a count is from
+  the unreleased branch, label it `unreleased` rather than presenting it as a
+  released capability. Reconcile the count whenever a release changes the
+  available tools.
+- Keep the quick start deterministic and offline-capable where the project
+  permits; do not imply that model output performs an unreviewed change.
diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
@@ -0,0 +1,49 @@
+# mechub style guide
+
+This guide is the shared standard for mechub repository documentation and
+metadata. Apply it consistently while keeping each repository's technical
+description specific and honest.
+
+## README opening
+
+Every README starts with an H1 containing the exact repository name. Do not
+insert or remove dashes, including in names such as `rustjunosmcp`.
+
+Use the canonical subtitle:
+
+> sovereign AI operations for network and security teams
+
+Use one status badge with exactly one of these labels: **Planned**, **Alpha**,
+**Beta**, or **Stable**. Do not use “In production” for a maintainer's
+homelab; describe that state as “running in the maintainer's lab”.
+
+Keep the opening focused on the project's value, audience, maturity, and
+shortest safe local path. Quick starts should be deterministic and
+offline-capable where the project permits, and must not imply that model
+output performs an unreviewed change.
+
+## Vendor and project naming
+
+Use the fuller product names **HPE Juniper Mist** and **Junos SRX** wherever
+those products are referenced.
+
+Append this description suffix to repository descriptions:
+
+> — a mechub project
+
+## Affiliation disclaimer
+
+Each README contains this disclaimer exactly once, replacing `{Vendor}` with
+the relevant vendor name:
+
+> This is an independent, community project. It is not affiliated with,
+> endorsed by, or supported by {Vendor}.
+
+## Review checklist
+
+- The H1 exactly matches the repository name.
+- The canonical subtitle and one approved status label are present.
+- Vendor names use the fuller forms above.
+- The affiliation disclaimer appears exactly once.
+- Claims describe evidence-backed behavior and do not overstate lab usage.
+- The repository description ends with “— a mechub project”.
diff --git a/profile/README.md b/profile/README.md
@@ -34,9 +34,20 @@ the hub is where every vendor's MCP server meets, on hardware you own.
 |---|---|
 | **Foundation** | [`mecmcp`](https://github.com/mechubsec/mecmcp) · [`rustnetconf`](https://github.com/mechubsec/rustnetconf) · [`rustez`](https://github.com/mechubsec/rustez) |
 | **MCP servers** | [`rustjunosmcp`](https://github.com/mechubsec/rustjunosmcp) · [`rustpanosmcp`](https://github.com/mechubsec/rustpanosmcp) · [`rustsdcmcp`](https://github.com/mechubsec/rustsdcmcp) · [`rustmistmcp`](https://github.com/mechubsec/rustmistmcp) · [`rustproxmoxmcp`](https://github.com/mechubsec/rustproxmoxmcp) · [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) · [`rustfortimcp`](https://github.com/mechubsec/rustfortimcp) · [`rustopnsmcp`](https://github.com/mechubsec/rustopnsmcp) |
-| **Data** | [`ssdf`](https://github.com/mechubsec/ssdf) — sovereign security data fabric |
+| **Data** | [`ssdf`](https://github.com/mechubsec/ssdf) — Sovereign Security Data Fabric; the only repository with a Python core |
 | **Evaluation** | [`mechubbench`](https://github.com/mechubsec/mechubbench) — tool-call benchmark corpus and runner for network-automation agents |
-| **Skills & tools** | [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) · [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter) · [`fwconfigsantizer`](https://github.com/mechubsec/fwconfigsantizer) · [`srxsync`](https://github.com/mechubsec/srxsync) |
+| **Skills & tools** | [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) · [`firewallintentconverter`](https://github.com/mechubsec/firewallintentconverter) · [`fwconfigsanitizer`](https://github.com/mechubsec/fwconfigsanitizer) · [`srxsync`](https://github.com/mechubsec/srxsync) |
+
+## Start here
+
+- **Foundation:** Start with [`mecmcp`](https://github.com/mechubsec/mecmcp), the shared foundation for connecting the ecosystem to management planes.
+- **MCP servers:** Use a vendor server such as [`rustunifimcp`](https://github.com/mechubsec/rustunifimcp) to explore a runnable example that fronts a management plane.
+- **Data:** [`ssdf`](https://github.com/mechubsec/ssdf) provides the Sovereign Security Data Fabric and its Python core.
+- **Evaluation:** [`mechubbench`](https://github.com/mechubsec/mechubbench) contains benchmark cases and a runner for network-automation tool calls.
+- **Skills & tools:** [`fwskillsshare`](https://github.com/mechubsec/fwskillsshare) shares reusable skills, while the companion tools convert, sanitize, and synchronize firewall data.
+
+For a newcomer, `mecmcp` is the recommended first repository because it explains
+the common foundation; `rustunifimcp` is the shortest runnable server example.
 
 ## Principles