Skip to content

Add 11 diagrams, vendor mermaid, and stop the site fetching code from a CDN - #77

Merged
rocklambros merged 5 commits into
integrationfrom
docs/diagrams
Sep 10, 2026
Merged

Add 11 diagrams, vendor mermaid, and stop the site fetching code from a CDN#77
rocklambros merged 5 commits into
integrationfrom
docs/diagrams

Conversation

@rocklambros

Copy link
Copy Markdown
Contributor

Adds 11 diagrams to the specification and concept documentation, and fixes two problems found while verifying they actually display.

The diagrams

Eleven across nine pages, placed where a reader meets each mechanism rather than collected in a gallery. The runtime path and the constraint that the LLM layer cannot read policy code, the handshake, the five dispositions, the hook taxonomy, the session lifecycle, the Trace mappings into OpenTelemetry and OCSF, the AgBOM serializations, conformance profile layering, and the in-action walkthrough.

Before this, docs/acs.md at 773 lines, specification.md at 433, and ACS_in_action_example.md at 263 carried a wire protocol, a two-layer Guardian, five dispositions, and a full scenario in prose alone.

Two problems found by rendering them in a browser

The published site fetches executable JavaScript from a third party. mkdocs-material's bundle lazily loads mermaid from https://unpkg.com/mermaid@11/dist/mermaid.min.js whenever it meets a diagram. Verified live: loading the current published identity/standards page issues that request. The version is a range, so unpkg decides which 11.x a reader executes.

The third-party guard missed it because stray_scripts allowlists the theme bundle by digest and never reads what is inside it. Confirmed three ways: third_party_hosts on the rendered page returns none, stray_scripts returns none, and the allowlisted bundle contains two unpkg URLs.

Mermaid has never rendered on this site. The one diagram already in docs/identity/standards.md resolves to an empty element with no SVG on the live site today. The theme's pass replaces the source block with an empty div before drawing, so the text is gone by the time mermaid is asked for a picture.

The fix

Mermaid 11.17.2 is vendored at docs/assets/javascripts/mermaid.min.js and declared through extra_javascript. The superfences custom fence now emits class acs-diagram rather than mermaid, so the theme does not recognise a diagram, never reaches its loader, and never empties a block. mermaid-init.js renders from the vendored copy. Authors still write ```mermaid fences and GitHub still renders them natively.

Cost: 3.5 MB uncompressed, about 956 KB gzipped, on pages that load it.

Guards

stray_scripts now accepts a built script whose digest matches a file in docs/assets/javascripts/, which proves it is byte-identical to what is committed here rather than merely allowed by path.

A new guard asserts that package-CDN references in built JavaScript match a reviewed set. The three surviving unpkg references are documented with why each cannot fire. Proven by injection: adding a jsdelivr URL fails the test, removing it passes.

NOTICE records the MIT attribution, matching the standard the file already sets for the Inter font and the AGT bundle.

Verification

Every diagram rendered in a real browser, not asserted from a bracket count. 11 of 11 produce SVGs across all nine pages, zero raw blocks remain, and zero third-party requests are issued. 206 tests pass, mkdocs build --strict clean.

rocklambros and others added 5 commits September 9, 2026 21:43
Eva Benn is no longer a co-lead of the Identity workstream. She remains
a co-lead of Outreach, so she keeps her CODEOWNERS entries and her line
in CONTRIBUTORS.md, and `project.owasp.yaml` never named her because its
schema caps leaders at five and carries the project lead plus the two
creators.

`GOVERNANCE.md` states that two leads per workstream keeps decisions
moving when one is unavailable. That sentence stops describing Identity
the moment this lands, so rather than leave it quietly false, the second
seat is recorded as open alongside the Reference Implementation,
Documentation, and Testing and Validation seats.

`GOVERNANCE.md` is a build input. `tools/render_landing.py` parses the
workstream table into the published landing page, so this changes the
site. Verified by building the full pipeline: the table renders Identity
as Richard Bird alone and Outreach unchanged with Eva and Aruneesh, and
the single-lead row parses without incident.

204 tests pass, `mkdocs build --strict` clean.

Signed-off-by: rocklambros <rock@rockcyber.com>
Promote integration to main: README rewrite with diagrams
Trace events, AgBOM formats, and conformance profiles describe shapes
(parallel mappings, one-to-many derivation, layering on a floor) in
prose alone. Draw each one next to the paragraph that defines it.

The in-action walkthrough's plain-text sequence art becomes a mermaid
sequenceDiagram in place, so the whole flow reads before the 263 lines
of step-by-step detail.

The conformance diagram states plainly that a layer is a self-declared
claim, not a verified fact, matching the page's own disclaimer that no
claim is verified in v0.1.0.

Signed-off-by: rocklambros <rock@rockcyber.com>
The runtime path, the handshake, the five dispositions, the hook
taxonomy, and the session lifecycle each carry a wire protocol or a
state machine in prose alone. Add one small diagram after the prose
that introduces each mechanism, matching the style of the existing
diagram in docs/identity/standards.md.

Signed-off-by: rocklambros <rock@rockcyber.com>
Signed-off-by: rocklambros <rock@rockcyber.com>
afogel
afogel previously approved these changes Sep 10, 2026
@rocklambros
rocklambros dismissed afogel’s stale review September 10, 2026 12:51

The merge-base changed after approval.

@rocklambros
rocklambros merged commit 5110a7a into integration Sep 10, 2026
3 checks passed
@rocklambros
rocklambros deleted the docs/diagrams branch September 10, 2026 12:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants