The architecture description

easkills docs --root <repo>
easkills docs --root <repo> --lang pl   # also docs/architecture-description.pl.md

One command produces docs/architecture-description.md plus one SVG per view in docs/views/, generated only from model/approved/ -- staging content is a proposal and never appears in documentation. The command refuses a model with validation errors; do not override that to hit a deadline.

--lang pl writes a Polish description beside the English one; commit both and regenerate both with every model change. Only the generator's own wording is translated -- element names, documentation and decision rationale stay in the language their authors wrote them in, which is a fact about the model rather than a defect of the translation.

What the generator guarantees (so you do not re-do it)

• ISO 42010 Clause 6 shape: stakeholders -> concerns -> views, with a concern-coverage table that shows nobody/no view in bold where the loop is open.
• Application portfolio with APM fields and TIME quadrants, straight from element properties -- nothing is re-judged at documentation time.
• Capability support table, including capabilities nothing realizes.
• Every declared assumption surfaced as an open question -- burying assumptions is the failure mode this section exists to prevent -- and every open clarification question from facts/questions/, with the text that raised it and who was asked.
• Decisions with their rationale (§6.10) and correspondences with the rule each one is held to (§6.9), derived from the governance log and the register -- never authored a second time in the description, and never truncated. A violated correspondence is listed as a known inconsistency rather than left in a report nobody exports.
• Deterministic output: the "as of" date is the newest lastReviewed in the model, not the wall clock, and identical models produce identical bytes. The generated files are committed; CI fails if they are stale, so regenerate and commit together with any model change.

Your job around the generator

Before: make the inputs true. The description can only be as good as the stakeholder register (ea-stakeholders), the views (ea-views) and the portfolio properties on the elements. A missing timeDisposition shows up as an em-dash in front of a CIO -- fix it in the model, with evidence, not in the markdown.

Never edit the generated files. Any hand edit is overwritten on the next run and CI flags the drift meanwhile. If a section reads wrong, the model or the generator is wrong; fix the cause.

After: audience one-pagers. When someone needs a tailored summary (a board slide, a one-pager for the auditor), write it as a separate document next to the generated one (e.g. docs/onepager-<audience>.md), sourced from the description and the model -- and say which model state ("as of" date) it reflects. Do not fork the architecture description itself per audience; one description, many extracts.

Two extracts are derived rather than written, and analysts ask for them by name: easkills rtm --out rtm.csv (every requirement, constraint, principle and goal with what it binds, what realizes it, its evidence and the decisions about it) and easkills glossary --out glossary.md (the entity table with aliases, the facts behind each term and the elements that answer to it). Hand them over as generated; a row that looks wrong is a record to fix, and the flags on a traceability row (unbound, unrealized, assumed) are the review agenda.

Reporting back

Say what was generated and from which model state, which concerns are still uncovered (the bold gaps in section 2), which portfolio fields are missing, which assumptions the reader is being asked to accept, and any violated correspondence in section 8. Those five lists are the review agenda; the prose around them is garnish.