Restyle the project presentation to the Public Sector standard

Andrew Dunnrequested to merge
docs/presentation into master

Summary

This makes stig-analyzer linkable. A public-sector reader arriving cold gets a branded hero, a badge row, and a value statement they can act on in ten seconds, then progressive disclosure into the component: what it does, how it works, how to consume it, what it emits, and what it requires. The design language is the Public Sector one (paper #fbfaf8, ink #1d1d1f, accent #fc6d26, muted #6e6e74; Inter and JetBrains Mono), applied to five new hand-authored SVGs.

The presentation change carried a correctness change with it. The README's architecture description predated the Duo CLI 9.x work, so the diagrams now describe the pinned duo binary under --output-format json, the Knowledge Graph MCP path, and the per-control verdict contract that actually ships.

What changed

Brand artifacts (new, repository root)

File Size Notes
hero.svg 1200x430 README header. Title, subline, two-line lede, principles row, territory tags, GITLAB PUBLIC SECTOR band
avatar.svg 256x256 Project avatar. Same glyph, avatar scale
favicon.svg 64x64 Same glyph reduced to the quadrant that still reads at 16px

One glyph carries all three: a control matrix where the accent cell is the control under evaluation, filled cells are resolved, and outlined cells are still open.

Diagrams (new, repository root)

File Size Shows
component-in-pipeline.svg 1200x640 Consuming project, the include, the jobs the component renders, the agentic pass, and what comes out
analysis-flow.svg 1200x560 XCCDF plus indexed codebase in, per-control duo run in the middle, JSON result document and verdict out

Both follow the diagram conventions: every coordinate, width and gap divisible by four (audited mechanically; the only exception is the hero's 430 canvas height, which the presentation standard fixes), accent on two focal nodes, 1px hairlines with 2px reserved for the focal node, mono for job names, paths and commands, sans for prose, no shadows or gradients, and numbered sidenotes in a right-hand column rather than inline bubbles.

These replace the Mermaid flowcharts entirely. Mermaid rendered in a blue/purple/amber/green palette that belongs to no part of this design system, and it cannot express the grid, accent restraint, or typographic split the standard asks for. git grep mermaid now returns nothing.

Documentation

  • README.md rewritten to the presentation template: hero embed on line one, # stig-analyzer H1, three-badge row, one actionable paragraph, then What it does / How it works / Quick start / Inputs / Outputs / Requirements / Reference / Contributing / License, closing on GitLab Public Sector, 2026. The GitLab Duo entitlement is now stated plainly under Requirements instead of surfacing only as a troubleshooting note.
  • docs/RECIPES.md (new) takes the five task-shaped setup snippets off the front page: smoke test, maximum parallelism, STIG Manager, remediation planning, auto-remediation, plus the everything-at-once block. Nothing was dropped; the content is tightened.
  • docs/FEATURES.md data-flow section embeds the two SVGs and describes the STIG Manager and remediation lanes in prose, preserving what the Mermaid subgraphs carried.
  • docs/FEATURES.md and docs/INPUTS.md links repointed at RECIPES.md. Their README.md#common-setups, #4-create-a-remediation-plan and #5-auto-remediate-duo-opens-fix-mrs anchors died with that section.
  • CHANGELOG.md gains one ### Changed entry under [Unreleased].

No emoji and no em-dashes in any file this branch touches.

Screenshots

Not applicable; the artifacts are the SVGs themselves and render inline in the README. They are, in reading order:

  • hero.svg
  • component-in-pipeline.svg
  • analysis-flow.svg
  • avatar.svg (not embedded; intended for the project avatar setting)
  • favicon.svg (not embedded; intended for a docs or Pages surface)

How to review

  1. Read the rendered README.md on this branch top to bottom once, cold. It should answer what the component is and how to switch it on without a scroll back.
  2. Open the three diagrams full size and check them against the component template. Job names in component-in-pipeline.svg should match templates/stig-compliance-analysis.yml, and the contract fields in analysis-flow.svg should match parse_gitlab_duo_output() in stig_tools/stig_ai_analyzer.py.
  3. Check the brand artifacts render: xmllint --noout *.svg passes on all five, and rsvg-convert produces the expected dimensions.
  4. Check every README link resolves, including the new docs/RECIPES.md and the two SVG embeds.

Two things worth knowing while reviewing. The pipeline badge in the badge row reports master accurately, and master is red today for the reason recorded in [Unreleased]: the project-bot identity holds no Duo entitlement, so stig::verify-creds and its dependents fail by design until an entitled token exists. And the README keeps @master as the documented ref rather than a version pin, because every existing tag predates the registry repoint and this project is not yet a CI/CD Catalog resource. Both are stated in the README's Versioning section instead of being papered over.

Merge request reports