docs
Generate or refresh rendered project documentation, then verify it against the content-governance exit-condition family (language, completeness, tone).
SKILL.mdskills/docs/SKILL.md
GitHubUser Input
You MUST consider the user input before proceeding (if not empty).
Purpose
/akka:docs is a generator. It writes and refreshes the project's rendered
documentation under docs/, then hands that output to the content-governance
exit-condition family that verifies it. Documentation is a surface class in the
single coverage gate: every documentable thing needs a page, the same way every
code module needs a covering check. Generation lives here in the assistant; the
engine verifies the deterministic conditions and records the attestation for the
one condition it cannot decide.
When it runs
/akka:docs is primarily an À la carte command. The developer invokes it
directly when they want to (re)generate the project's rendered documentation
and see how the content-governance exit conditions decided. In Enforced mode
the assistant runs the same activity autonomously as part of its build loop,
whenever CONTENT-LANGUAGE, Completeness, or CONTENT-TONE is open and the
assistant can act on it. In both modes the behavior is identical; only
ship-gating differs.
Outline
Enumerate the documentable things. Collect what the project can document from observable sources — the a-la-carte commands, the active exit conditions, the public API endpoints detected in the tree. This enumerable set is the completeness target.
Load the fixed template. Read
plugins/akka/templates/docs-template.htmlfrom the akka plugin. This file is the fixed design contract for/akka:docs: it contains the full CSS, the full HTML skeleton, the header, the stats grid, the collapsible diagram and component sections, the SVG scaffolding for the interaction diagram, and the banded SVG scaffolding for the component graph. Every generateddocs/index.htmluses this template verbatim — the assistant MUST NOT modify the CSS, the layout, the fonts, the colors, or any other design detail. Customers do not override the design; the template is the design. The palette is enumerated inplugins/akka/templates/akka-style-guide.md, and step 9 checks the generated page against it, so this rule is enforced rather than trusted.Fill the placeholders and paste the fragments. The template contains two kinds of insertion points:
Single-value placeholders:
{{TITLE}},{{LEAD}},{{STAT_COMPONENTS}},{{STAT_EVENTS}},{{STAT_ENDPOINTS}},{{STAT_VIEWS}},{{STAT_DOMAIN_OBJECTS}},{{ENTITY_HINT}},{{INTERACTION_HINT}},{{COMPONENT_GRAPH_HINT}},{{SLUG}},{{INTERACTION_TITLE}},{{INTERACTION_DESC}},{{COMPONENT_GRAPH_TITLE}},{{COMPONENT_GRAPH_DESC}},{{FOOTER_TARGET}}. Fill each with the project-specific value.Region placeholders:
{{ENTITY_BOXES}},{{INTERACTION_SVG_BODY}},{{COMPONENT_GRAPH_BODY}},{{ADDITIONAL_DIAGRAMS}},{{COMPONENT_REFERENCE}}. The template shows each region's fragment shapes as HTML comments directly above the placeholder. Copy the fragment verbatim for every entity / domain object / component / lane / message and fill only the identifier and field values. Do not restyle. Do not restructure.
Component-kind coloring is fixed by the CSS classes (
ese,kve,view,wf,agent,ep,extfor HTML fragments;n-ese,n-kve,n-view,n-wf,n-agent,n-ep,n-extinside the component-graph SVG). Choose the class that matches the component's Akka type; the accent color follows automatically.Draw the diagrams to the rules the template states. The template's header comment carries five rules that step 9 verifies. They are not style advice, and a page that breaks one reds the language check:
- Accessibility. Every diagram
<svg>carriesrole="img"andaria-labelledby, with<title>as its first child before<defs>and<desc>immediately after, both id'd{{SLUG}}-<name>-title/-desc. Baretitle/descids are banned — two diagrams on one page collide and the second is announced with the first one's name.<desc>says what the diagram shows, never its geometry. - Connectors. Two nodes sharing neither x nor y are joined by a rounded
right-angle
<path>elbow (r=8), never a diagonal<line>. Connectors entering the same edge of a box get their own attach point ≥12px apart. Draw every connector before the nodes so the boxes paint over the stroke ends. - Labels. Every connector label needs an opaque mask rect behind it and a visible 6–10px gap above the stroke. A label sitting on its own connector hides the thing it describes. Keep the mask on open canvas — a mask overlapping a node is clipped by the node fill and the text renders as a fragment on the border.
- Color. The two color rules apply to different diagrams and mixing them erases both. Inventory graphics — the component graph and the entity boxes — are categorical: the seven kind colors identify what a thing is, and the legend decodes them. Narrative graphics — the interaction diagram — are editorial: the primary path is yellow, everything else is muted grey. Never color an interaction lane's arrows by component kind; it makes every arrow equally loud and the reader cannot find the path that matters.
- Budget and grid. Max 9 nodes, 12 connectors, 5 interaction lanes per diagram; every coordinate and size on the 4px grid. Over budget, split into an overview plus a detail diagram rather than shrinking the type.
- Accessibility. Every diagram
Choose what the diagrams show. Three artifacts are always produced — entity, interaction, component graph. Pick their content from the shapes the project actually has, rather than drawing the same thing for every project:
When the project has… The interaction diagram shows a command → event → projection path that path end to end: client, endpoint, entity, view a Workflow with steps, retries, compensation the durable execution: each step, and what happens when one fails an entity with a lifecycle in its events the state transitions and their guards an Agent with tools the model call, the tool calls, and the guardrail timers or scheduled work the ordering, with the delay on the arrow Choose the one path a reader most needs to understand; the rest belong in the component reference. If two paths are equally central, draw the primary one and note the second in
{{INTERACTION_HINT}}.Verify the path before drawing it. Read the step bodies and the call sites, not the class names — a workflow step named
persistmay not be the only step that writes, and an agent that exists may have no caller at all. A diagram asserting a call that does not happen is worse than no diagram, because it is believed.Add a diagram only when it earns its slot.
{{ADDITIONAL_DIAGRAMS}}holds zero or more extra diagrams. Add one when it shows something no other diagram on the page carries, and name that thing in itssec-hint. Two or three extra is a normal maximum.A budget waiver obliges a detail diagram. When the component graph or interaction diagram goes over budget, the rule in step 4 is to split into an overview plus a detail — the overview stays in the fixed slot and the detail goes here. Recording the waiver without drawing the detail leaves a hole and says so in writing; that is worse than either drawing it or leaving the component out silently, because it advertises the omission and does nothing about it.
Type Earns its slot when State machine a record has a lifecycle in its events and the guards are the interesting part — the entity diagram lists fields, it never shows a transition Sequence the interaction diagram hit the 5-lane limit and the participants it dropped are load-bearing Timeline one record carries several independent clocks, so a reader cannot tell which question each answers ER domain records reference each other and the entity diagram draws them as separate boxes with no edges Do not reach for a quantitative type — bar, line, scatter, treemap, radar, quadrant, Gantt. Component counts are already the stats grid, and a chart of them is decoration. If a three-column table would say the same thing, use the table.
Write
docs/index.html. After filling every placeholder, write the result todocs/index.htmlin the project directory. The file is self-contained — no external JavaScript, no external CSS, no remote images, no build step needed to view — so it can be opened directly in a browser or served from any static host.Pages for enumerated documentable things beyond the three rendered artifacts. For every à-la-carte command, active exit condition, and detected public endpoint that is not already covered by the three rendered artifacts, append a matching
<details class="sec">section to the{{COMPONENT_REFERENCE}}region using the same fragment shape shown in the template. Follow the project's terminology; the deterministic checks below verify it. A component left out of a diagram to stay inside the complexity budget is recorded here with its reason — an omission is a waiver, never a silent drop.Verify against the content-governance family. Run the three conditions and report each. Each has a default ship tier:
CONTENT-LANGUAGE (deterministic, ship tier: author). Two introspective checks over
docs/, both falsifiable, both reported under this condition:Prose. The Vale prose linter using the project's
.vale.ini(generated into/harnesses/content/by/akka:harnesses). It decides banned phrasings absent, mandated substitutions honored, terminology correct, and the structural conventions — required sections present, heading conventions followed.Diagram structure.
python harnesses/content/diagram_check.py docs/*.html, which decides the falsifiable half of step 4: the accessible-SVG contract; diagonal connectors; every<rect>and<line>coordinate on the 4px grid; a label mask clipped by a node drawn after it; a connector label with no mask; the node, connector, lane and accent budgets; every CSS class used having a rule; the Akka palette; remote assets and scripts; and the file's encoding. Four rules stay unchecked because the markup does not carry what they need — elbow radius, attach-point spacing, the 6–10px label gap, and paint order — so those are the ones to read carefully by eye.Both are introspective: shell out, map a non-zero exit to
red. On a machine without Vale or without Python the affected check isopenwith reasonblocked-outside-projectand the missing tool named, never a falsered. The author-tier default means this check runs on every ship — both tools are fast enough to be a per-commit gate.Completeness (the coverage gate, ship tier: author). Every documentable thing enumerated in step 1 has a page on disk. A documentable thing with no page reds the gate. Completeness is not a separate command — it is the documentation surface class inside the single coverage gate. A thing intentionally left undocumented is a recorded waiver with a reason, not a silent omission. The author-tier default means every ship verifies that no documentable thing has been left without a page.
CONTENT-TONE (delegated, ship tier: review). The holistic dimension a linter cannot reduce to a token list — state a fact, not a flourish; declarative, not persuasive; reads like a person. This covers the half of step 4 no script decides: whether the diagram earns its place, whether the right path was chosen, whether a node could be removed. Do not score prose or diagrams 1-to-5; that rubber-stamps. Apply the project's decomposed rubric as single-criterion pass/fail predicates, framed adversarially ("find every place this reads like marketing"; "find every node a reader would not miss"). When the pages pass, call
akka_harness_attestwith the tone condition key and a receipt reference. The attestation is keyed to a content-plus-rubric signature, so a rule change or an edit invalidates it and the condition returns toopenwith reasonneeds-user-actionuntil re-run. The engine records that the judge ran and covered the current content; it never scores the prose itself. The review-tier default means CONTENT-TONE is verified before the change is opened for team review, not on every commit — re-attesting every time a source file changes would be excessive.
Report. Call
akka_ec_conform, then presentakka_ec_summaryto the user verbatim — the plain outcome. Do NOT restate internal condition ids or the words "auditor" / "coverage gate". Offer "say 'show details' for the full checklist" for the manifest.
Key rules
- The engine never calls a model. The deterministic language check delegates to
Vale and to
diagram_check.py; completeness is a page-exists test; only the tone judgment runs here in the assistant, and it reaches the engine as an attestation, not a score. - Nothing false-passes. A missing page reds the coverage gate; a banned phrasing
or a broken diagram contract reds the language check; tone with no attestation
stays
openwith reasonneeds-user-action. - The design is checked, not trusted. A generated page using a color outside the Akka palette reds the language check, so "do not modify the CSS" is enforced.
- Same behavior wherever the exit-condition set is active. The generator and the three conditions exist in À la carte and Enforced mode alike; only ship-gating differs, advisory in À la carte and blocking in Enforced. Where the set is dormant the pages are still generated and no conditions are recorded.
Done When
- The documentable things (commands, active exit conditions, detected endpoints) were enumerated as the completeness target.
- A page was generated or refreshed under
docs/for each documentable thing, following the project's structural and terminology conventions. - Every diagram
<svg>carriesrole="img",aria-labelledby, and a prefixed<title>/<desc>pair with<title>as its first child. - Off-axis connectors are rounded right-angle elbows, connectors sharing a box edge have their own attach points, and every connector label has a mask rect with a visible gap above the stroke.
- Inventory diagrams used categorical kind color; the interaction diagram used editorial color with one primary path.
- Each diagram is inside the node / connector / lane budget, or was split into overview plus detail; anything omitted for budget is recorded as a waiver with a reason.
- Every budget waiver has its detail diagram in
{{ADDITIONAL_DIAGRAMS}}, or states why one cannot be drawn — a waiver alone advertises a hole without filling it. - Every additional diagram names, in its
sec-hint, the thing no other diagram on the page shows. - Every call, step and participant drawn was verified against the step bodies and call sites, not inferred from class names.
- CONTENT-LANGUAGE ran Vale and
harnesses/content/diagram_check.pyoverdocs/and reportedgreen/red(oropenwith reasonblocked-outside-projectwhere a tool is unavailable — never a falsered). - Completeness was checked as the documentation surface class of the coverage gate; any undocumented thing reds the gate or was recorded as a waiver with a reason.
- CONTENT-TONE applied the decomposed adversarial rubric as pass/fail predicates and, on pass, was attested via
akka_harness_attestwith the condition key and a receipt reference — never left as a numeric score. -
akka_ec_conformwas called and the plainakka_ec_summary(never internal ids or the word "auditor") was shown to the user.