archi-cli 0.1.0__tar.gz

archi_cli-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+# Archi-backups en afgeleide artefacten — niet versioneren
+*.bak
+output/
+*.xml
+*.svg
+*.png
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+
+# macOS
+.DS_Store

archi_cli-0.1.0/LICENSE

@@ -0,0 +1,190 @@
+EUROPEAN UNION PUBLIC LICENCE v. 1.2
+EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined below) which is provided under the
+terms of this Licence. Any use of the Work, other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+The Work is provided under the terms of this Licence when the Licensor (as defined below) has placed the following
+notice immediately following the copyright notice for the Work:
+                          Licensed under the EUPL
+or has expressed by any other means his willingness to license under the EUPL.
+
+1.Definitions
+In this Licence, the following terms have the following meaning:
+— ‘The Licence’:this Licence.
+— ‘The Original Work’:the work or software distributed or communicated by the Licensor under this Licence, available
+as Source Code and also as Executable Code as the case may be.
+— ‘Derivative Works’:the works or software that could be created by the Licensee, based upon the Original Work or
+modifications thereof. This Licence does not define the extent of modification or dependence on the Original Work
+required in order to classify a work as a Derivative Work; this extent is determined by copyright law applicable in
+the country mentioned in Article 15.
+— ‘The Work’:the Original Work or its Derivative Works.
+— ‘The Source Code’:the human-readable form of the Work which is the most convenient for people to study and
+modify.
+— ‘The Executable Code’:any code which has generally been compiled and which is meant to be interpreted by
+a computer as a program.
+— ‘The Licensor’:the natural or legal person that distributes or communicates the Work under the Licence.
+— ‘Contributor(s)’:any natural or legal person who modifies the Work under the Licence, or otherwise contributes to
+the creation of a Derivative Work.
+— ‘The Licensee’ or ‘You’:any natural or legal person who makes any usage of the Work under the terms of the
+Licence.
+— ‘Distribution’ or ‘Communication’:any act of selling, giving, lending, renting, distributing, communicating,
+transmitting, or otherwise making available, online or offline, copies of the Work or providing access to its essential
+functionalities at the disposal of any other natural or legal person.
+
+2.Scope of the rights granted by the Licence
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive, sublicensable licence to do the following, for
+the duration of copyright vested in the Original Work:
+— use the Work in any circumstance and for all usage,
+— reproduce the Work,
+— modify the Work, and make Derivative Works based upon the Work,
+— communicate to the public, including the right to make available or display the Work or copies thereof to the public
+and perform publicly, as the case may be, the Work,
+— distribute the Work or copies thereof,
+— lend and rent the Work or copies thereof,
+— sublicense rights in the Work or copies thereof.
+Those rights can be exercised on any media, supports and formats, whether now known or later invented, as far as the
+applicable law permits so.
+In the countries where moral rights apply, the Licensor waives his right to exercise his moral right to the extent allowed
+by law in order to make effective the licence of the economic rights here above listed.
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to any patents held by the Licensor, to the
+extent necessary to make use of the rights granted on the Work under this Licence.
+
+3.Communication of the Source Code
+The Licensor may provide the Work either in its Source Code form, or as Executable Code. If the Work is provided as
+Executable Code, the Licensor provides in addition a machine-readable copy of the Source Code of the Work along with
+each copy of the Work that the Licensor distributes or indicates, in a notice following the copyright notice attached to
+the Work, a repository where the Source Code is easily and freely accessible for as long as the Licensor continues to
+distribute or communicate the Work.
+
+4.Limitations on copyright
+Nothing in this Licence is intended to deprive the Licensee of the benefits from any exception or limitation to the
+exclusive rights of the rights owners in the Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5.Obligations of the Licensee
+The grant of the rights mentioned above is subject to some restrictions and obligations imposed on the Licensee. Those
+obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or trademarks notices and all notices that refer to
+the Licence and to the disclaimer of warranties. The Licensee must include a copy of such notices and a copy of the
+Licence with every copy of the Work he/she distributes or communicates. The Licensee must cause any Derivative Work
+to carry prominent notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the Original Works or Derivative Works, this
+Distribution or Communication will be done under the terms of this Licence or of a later version of this Licence unless
+the Original Work is expressly distributed only under this version of the Licence — for example by communicating
+‘EUPL v. 1.2 only’. The Licensee (becoming Licensor) cannot offer or impose any additional terms or conditions on the
+Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative Works or copies thereof based upon both
+the Work and another work licensed under a Compatible Licence, this Distribution or Communication can be done
+under the terms of this Compatible Licence. For the sake of this clause, ‘Compatible Licence’ refers to the licences listed
+in the appendix attached to this Licence. Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work, the Licensee will provide
+a machine-readable copy of the Source Code or indicate a repository where this Source will be easily and freely available
+for as long as the Licensee continues to distribute or communicate the Work.
+Legal Protection: This Licence does not grant permission to use the trade names, trademarks, service marks, or names
+of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6.Chain of Authorship
+The original Licensor warrants that the copyright in the Original Work granted hereunder is owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each Contributor warrants that the copyright in the modifications he/she brings to the Work are owned by him/her or
+licensed to him/her and that he/she has the power and authority to grant the Licence.
+Each time You accept the Licence, the original Licensor and subsequent Contributors grant You a licence to their contributions
+to the Work, under the terms of this Licence.
+
+7.Disclaimer of Warranty
+The Work is a work in progress, which is continuously improved by numerous Contributors. It is not a finished work
+and may therefore contain defects or ‘bugs’ inherent to this type of development.
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis and without warranties of any kind
+concerning the Work, including without limitation merchantability, fitness for a particular purpose, absence of defects or
+errors, accuracy, non-infringement of intellectual property rights other than copyright as stated in Article 6 of this
+Licence.
+This disclaimer of warranty is an essential part of the Licence and a condition for the grant of any rights to the Work.
+
+8.Disclaimer of Liability
+Except in the cases of wilful misconduct or damages directly caused to natural persons, the Licensor will in no event be
+liable for any direct or indirect, material or moral, damages of any kind, arising out of the Licence or of the use of the
+Work, including without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, loss
+of data or any commercial damage, even if the Licensor has been advised of the possibility of such damage. However,
+the Licensor will be liable under statutory product liability laws as far such laws apply to the Work.
+
+9.Additional agreements
+While distributing the Work, You may choose to conclude an additional agreement, defining obligations or services
+consistent with this Licence. However, if accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10.Acceptance of the Licence
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’ placed under the bottom of a window
+displaying the text of this Licence or by affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable acceptance of this Licence and all of its terms
+and conditions.
+Similarly, you irrevocably accept this Licence and all of its terms and conditions by exercising any rights granted to You
+by Article 2 of this Licence, such as the use of the Work, the creation by You of a Derivative Work or the Distribution
+or Communication by You of the Work or copies thereof.
+
+11.Information to the public
+In case of any Distribution or Communication of the Work by means of electronic communication by You (for example,
+by offering to download the Work from a remote location) the distribution channel or media (for example, a website)
+must at least provide to the public the information requested by the applicable law regarding the Licensor, the Licence
+and the way it may be accessible, concluded, stored and reproduced by the Licensee.
+
+12.Termination of the Licence
+The Licence and the rights granted hereunder will terminate automatically upon any breach by the Licensee of the terms
+of the Licence.
+Such a termination will not terminate the licences of any person who has received the Work from the Licensee under
+the Licence, provided such persons remain in full compliance with the Licence.
+
+13.Miscellaneous
+Without prejudice of Article 9 above, the Licence represents the complete agreement between the Parties as to the
+Work.
+If any provision of the Licence is invalid or unenforceable under applicable law, this will not affect the validity or
+enforceability of the Licence as a whole. Such provision will be construed or reformed so as necessary to make it valid
+and enforceable.
+The European Commission may publish other linguistic versions or new versions of this Licence or updated versions of
+the Appendix, so far this is required and reasonable, without reducing the scope of the rights granted by the Licence.
+New versions of the Licence will be published with a unique version number.
+All linguistic versions of this Licence, approved by the European Commission, have identical value. Parties can take
+advantage of the linguistic version of their choice.
+
+14.Jurisdiction
+Without prejudice to specific agreement between parties,
+— any litigation resulting from the interpretation of this License, arising between the European Union institutions,
+bodies, offices or agencies, as a Licensor, and any Licensee, will be subject to the jurisdiction of the Court of Justice
+of the European Union, as laid down in article 272 of the Treaty on the Functioning of the European Union,
+— any litigation arising between other parties and resulting from the interpretation of this License, will be subject to
+the exclusive jurisdiction of the competent court where the Licensor resides or conducts its primary business.
+
+15.Applicable Law
+Without prejudice to specific agreement between parties,
+— this Licence shall be governed by the law of the European Union Member State where the Licensor has his seat,
+resides or has his registered office,
+— this licence shall be governed by Belgian law if the Licensor has no seat, residence or registered office inside
+a European Union Member State.
+
+
+                                                         Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+— GNU General Public License (GPL) v. 2, v. 3
+— GNU Affero General Public License (AGPL) v. 3
+— Open Software License (OSL) v. 2.1, v. 3.0
+— Eclipse Public License (EPL) v. 1.0
+— CeCILL v. 2.0, v. 2.1
+— Mozilla Public Licence (MPL) v. 2
+— GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+— Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for works other than software
+— European Union Public Licence (EUPL) v. 1.1, v. 1.2
+— Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the above licences without producing
+a new version of the EUPL, as long as they provide the rights granted in Article 2 of this Licence and protect the
+covered Source Code from exclusive appropriation.
+All other changes or additions to this Appendix require the production of a new EUPL version.

archi_cli-0.1.0/NOTICE

@@ -0,0 +1,15 @@
+archi-cli
+Copyright (c) 2026 Bureau Architectuur Digitale Overheid
+Licensed under the EUPL-1.2 (see LICENSE).
+
+This tool downloads and drives the Archi engine for its `normalize` command.
+Archi is a separate work and is not distributed as part of this package; it is
+fetched at runtime from the official release on first use.
+
+  Archi — ArchiMate modelling tool
+  Copyright (c) Phillip Beauvoir, Jean-Baptiste Sarrodie and contributors
+  Licensed under the MIT License
+  https://github.com/archimatetool/archi
+
+The Archi distribution bundles an OpenJDK runtime; its own licensing applies to
+that runtime.

archi_cli-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: archi-cli
+Version: 0.1.0
+Summary: ar·cli·mate — de CLI in je ArchiMate: deterministisch native .archimate-modellen inspecteren, muteren, valideren en renderen
+Project-URL: Homepage, https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting
+Project-URL: Repository, https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting
+Project-URL: Issues, https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting/issues
+Author: Bureau Architectuur Digitale Overheid
+License-Expression: EUPL-1.2
+License-File: LICENSE
+Keywords: archi,archimate,cli,enterprise-architecture,modeling
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.12
+Requires-Dist: lxml>=5.0
+Requires-Dist: typer>=0.26
+Description-Content-Type: text/markdown
+
+# AI-assisted architecting
+
+[![checks](https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting/actions/workflows/ci.yml/badge.svg)](https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting/actions/workflows/ci.yml)
+[![licentie: EUPL-1.2](https://img.shields.io/badge/licentie-EUPL--1.2-blue.svg)](LICENSE)
+
+Experiment van Bureau Architectuur Digitale Overheid: een ArchiMate-model in
+het native Archi-formaat als bron van waarheid, bijgehouden met AI-assistentie
+en deterministische tooling. Het modelbestand opent direct in Archi, zonder
+import-stap, en de views zijn op GitHub zelf te bekijken.
+
+## De `archi`-CLI los gebruiken
+
+De tooling is ook een zelfstandig pakket, `archi-cli` (*ar·cli·mate*: de CLI in
+je ArchiMate). Je installeert het commando `archi` los van deze repo:
+
+```bash
+uv tool install archi-cli
+archi --help
+```
+
+`archi` werkt op elk `.archimate`-model: geef `--model <pad>` op, of leg het
+model vast in een `archi.toml` (`[tool.archi] model = "..."`), of draai in een
+map met precies één `.archimate`-bestand. Voor `normalize` heb je de Archi-
+engine nodig; die haalt `archi` bij het eerste gebruik zelf op (of expliciet
+met `archi setup`). De rest van dit document beschrijft het werken in deze repo.
+
+## Het idee
+
+`models/ado.archimate` is de bron. Er zijn twee gelijkwaardige manieren om
+eraan te werken: via de `archi`-CLI (meestal aangestuurd door een AI-sessie
+zoals Claude Code) of gewoon in de Archi-GUI. Beide routes komen samen in
+dezelfde controles:
+
+- `just validate` controleert de integriteit: unieke ids, kloppende
+  verwijzingen van relaties en view-objecten, juiste folder-plaatsing, en
+  property-keys tegen de conventielijst.
+- `just normalize` laat headless Archi het bestand opnieuw serialiseren.
+  Archi is daarmee de canonieke serializer, dus diffs blijven klein en
+  reviewbaar, wie of wat er ook geschreven heeft.
+- `just render` genereert uit elke view in het model een Mermaid-diagram
+  (rendert op GitHub, in `views/`) en een NLDD-gestileerde HTML-pagina die de
+  layout uit het model pixelgetrouw volgt (`views/html/`), inclusief de
+  ArchiMate-notatie-iconen per elementtype, notes, groups en bendpoints.
+  Daarnaast rendert het uit elke deckdefinitie in `decks/` een presentatie
+  (`views/html/slides/`): een lineair verhaal als zelfstandige HTML-slides
+  in Rijkshuisstijl, met views uit het model als diagrammen, afgewisseld
+  met tekst- en bulletslides.
+
+Pre-commit hooks dwingen validatie en verse renders af bij elke commit die
+het model raakt. De afweging achter deze opzet, inclusief wat we inleveren
+ten opzichte van de JSON-aanpak in het zusterexperiment, staat in
+`adr/0001-archimate-als-bron.md`; het besluit om gegenereerde renders wel te
+committen staat in `adr/0002-views-als-mermaid-in-git.md`, dat voor de
+slidedecks in `adr/0003-slidedecks-als-toml-in-git.md`.
+
+## Structuur
+
+```
+models/ado.archimate         Het model, de bron van waarheid
+decks/                       Deckdefinities voor presentaties (TOML)
+views/                       Gerenderde views als Mermaid (.md, rendert op GitHub)
+views/html/                  Dezelfde views als NLDD-HTML, lokaal te bekijken
+views/html/slides/           Gerenderde slidedecks (één HTML per deck)
+docs/conventies.md           Types, property-keys en naamgeving
+docs/spelregels.md           Rollen, workflow en de een-schrijver-afspraak
+adr/                         Architectuurbeslissingen
+tools/archi_tool/            De archi-CLI (Python, lxml; beheerd met uv)
+tests/                       pytest-suite met een klein fixture-model
+.claude/skills/              Procedures voor AI-sessies (archi-model, archi-view, archi-slides)
+justfile                     Vaste taken
+```
+
+## Aan de slag
+
+Nodig: [uv](https://docs.astral.sh/uv/), [just](https://just.systems/) en
+[Archi](https://www.archimatetool.com/) voor normalisatie.
+
+macOS:
+
+```bash
+brew install uv just
+brew install --cask archi
+```
+
+Windows (PowerShell):
+
+```powershell
+winget install --id astral-sh.uv -e
+winget install --id Casey.Just -e
+winget install --id Archi.Archi -e
+```
+
+Linux: uv via `curl -LsSf https://astral.sh/uv/install.sh | sh`, just via je
+packagemanager, Archi als tgz van
+[archimatetool.com/download](https://www.archimatetool.com/download/).
+
+Archi wordt automatisch gevonden op `/Applications/Archi.app` (macOS),
+`C:\Program Files\Archi\Archi.exe` (Windows) en `/opt/Archi/Archi` (Linux);
+een ander pad geef je op via de env var `ARCHI_APP`. Python en pre-commit
+hoef je niet zelf te installeren: uv regelt de Python-versie en pre-commit
+is een dev-dependency.
+
+```bash
+just setup       # eenmalig per clone: venv, dependencies en pre-commit hooks
+just stats       # wat zit erin
+just open        # model openen in Archi
+just serve       # gerenderde HTML-views op http://localhost:8766
+```
+
+Sla `just setup` niet over: zonder de pre-commit hooks kun je committen
+zonder validatie en met verouderde renders.
+
+Alle vaste taken:
+
+| Commando | Wat het doet |
+|---|---|
+| `just setup` | venv, dependencies en pre-commit hooks installeren |
+| `just validate` | integriteitschecks (draait ook als pre-commit hook) |
+| `just render` | views en decks renderen naar `views/` en `views/html/` (ook hook) |
+| `just normalize` | canonieke serialisatie via headless Archi, duurt zo'n 15 s |
+| `just stats` | telling per elementtype, relaties en views |
+| `just tree` | folderstructuur van het model met inhoud |
+| `just list *args` | elementen tonen, bv. `just list --type Capability` |
+| `just show *args` | één element met properties en relaties, bv. `just show "Gegevensuitwisseling"` |
+| `just test` | pytest-suite |
+| `just open` | model openen in Archi |
+| `just serve` | HTML-views serveren op http://localhost:8766 |
+
+Wijzigen doe je met de CLI. Die valideert het model na elke mutatie en
+weigert op te slaan zolang er fouten zijn. Elementen zijn aanspreekbaar op id
+of op naam, zolang die uniek is:
+
+```bash
+uv run archi list --type Capability --property "Capability-niveau=gebied"
+uv run archi show "Gegevensuitwisseling"
+uv run archi tree
+uv run archi add-element --type Capability --name "..." \
+    --property "Capability-niveau=bouwblok" --property "Omschrijving=..."
+uv run archi add-relation --type Aggregation \
+    --source "Gegevensuitwisseling" --target "..." --name "bevat"
+uv run archi set-property "Gegevensuitwisseling" "Omschrijving=..."
+uv run archi rename "Oude naam" "Nieuwe naam"
+uv run archi set-documentation "Gegevensuitwisseling" "..."
+uv run archi remove "Gegevensuitwisseling" --cascade
+uv run archi add-view --name "..." --layout cluster \
+    --type Capability --relation Aggregation
+uv run archi add-view --name "... in detail" --layout cluster \
+    --root "Gegevensuitwisseling" --related
+uv run archi add-view --name "Losse selectie" --layout grid \
+    --element "Gegevensuitwisseling" --element "Kunstmatige Intelligentie"
+uv run archi slides --deck decks/ado.toml
+uv run archi set-model-name "..."
+uv run archi --help
+```
+
+Elk commando heeft nog wat minder gebruikte vlaggen: `add-element --folder`
+overschrijft de folder-plaatsing (default volgt uit het type), `add-view
+--element` voegt losse elementen aan een selectie toe (zie hierboven), en
+`slides` accepteert `--deck`, `--decks` en `--out` om gericht te renderen. De
+volledige set toont `uv run archi <commando> --help`.
+
+## Werkwijze
+
+Branch afsplitsen, wijzigen, `just validate`, `just normalize`, committen en
+een PR openen. De pre-commit hook rendert de views mee; verandert er iets in
+`views/`, dan faalt de commit een keer en stage je de verse renders erbij.
+CI draait dezelfde checks (validatie, actuele renders, tests) op Ubuntu en
+Windows, dus een omzeilde hook strandt alsnog op de PR. De
+architect-eigenaar reviewt en merget.
+
+De belangrijkste afspraak: een schrijver tegelijk op het modelbestand. Een
+enkel XML-bestand merget slecht, dus parallelle branches met modelwijzigingen
+zijn er niet. Tooling- en documentatie-PR's kunnen wel naast elkaar lopen.
+Details en rollen staan in `docs/spelregels.md`; de modelconventies (welke
+types, welke property-keys, Nederlandse naamgeving) in `docs/conventies.md`.
+
+Werk je met Claude Code, dan wordt `CLAUDE.md` automatisch geladen en
+triggeren de skills `archi-model` (modelwijzigingen doorvoeren), `archi-view`
+(views genereren) en `archi-slides` (presentaties maken) zodra je erom
+vraagt.
+
+## Herkomst
+
+Het seedmodel is de export van het ADO-niveau-1-model uit
+[`ADO-architectuurmodel-experiment`](https://github.com/BureauArchitectuurDigitaleOverheid/ADO-architectuurmodel-experiment),
+waar JSON de bron is en ArchiMate een exportformaat. Dit repo draait die
+verhouding om: het Archi-bestand is de bron, en al het andere wordt eruit
+gegenereerd.
+
+## Licentie
+
+[EUPL-1.2](LICENSE).

archi_cli-0.1.0/README.md

@@ -0,0 +1,192 @@
+# AI-assisted architecting
+
+[![checks](https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting/actions/workflows/ci.yml/badge.svg)](https://github.com/BureauArchitectuurDigitaleOverheid/ai-assisted-architecting/actions/workflows/ci.yml)
+[![licentie: EUPL-1.2](https://img.shields.io/badge/licentie-EUPL--1.2-blue.svg)](LICENSE)
+
+Experiment van Bureau Architectuur Digitale Overheid: een ArchiMate-model in
+het native Archi-formaat als bron van waarheid, bijgehouden met AI-assistentie
+en deterministische tooling. Het modelbestand opent direct in Archi, zonder
+import-stap, en de views zijn op GitHub zelf te bekijken.
+
+## De `archi`-CLI los gebruiken
+
+De tooling is ook een zelfstandig pakket, `archi-cli` (*ar·cli·mate*: de CLI in
+je ArchiMate). Je installeert het commando `archi` los van deze repo:
+
+```bash
+uv tool install archi-cli
+archi --help
+```
+
+`archi` werkt op elk `.archimate`-model: geef `--model <pad>` op, of leg het
+model vast in een `archi.toml` (`[tool.archi] model = "..."`), of draai in een
+map met precies één `.archimate`-bestand. Voor `normalize` heb je de Archi-
+engine nodig; die haalt `archi` bij het eerste gebruik zelf op (of expliciet
+met `archi setup`). De rest van dit document beschrijft het werken in deze repo.
+
+## Het idee
+
+`models/ado.archimate` is de bron. Er zijn twee gelijkwaardige manieren om
+eraan te werken: via de `archi`-CLI (meestal aangestuurd door een AI-sessie
+zoals Claude Code) of gewoon in de Archi-GUI. Beide routes komen samen in
+dezelfde controles:
+
+- `just validate` controleert de integriteit: unieke ids, kloppende
+  verwijzingen van relaties en view-objecten, juiste folder-plaatsing, en
+  property-keys tegen de conventielijst.
+- `just normalize` laat headless Archi het bestand opnieuw serialiseren.
+  Archi is daarmee de canonieke serializer, dus diffs blijven klein en
+  reviewbaar, wie of wat er ook geschreven heeft.
+- `just render` genereert uit elke view in het model een Mermaid-diagram
+  (rendert op GitHub, in `views/`) en een NLDD-gestileerde HTML-pagina die de
+  layout uit het model pixelgetrouw volgt (`views/html/`), inclusief de
+  ArchiMate-notatie-iconen per elementtype, notes, groups en bendpoints.
+  Daarnaast rendert het uit elke deckdefinitie in `decks/` een presentatie
+  (`views/html/slides/`): een lineair verhaal als zelfstandige HTML-slides
+  in Rijkshuisstijl, met views uit het model als diagrammen, afgewisseld
+  met tekst- en bulletslides.
+
+Pre-commit hooks dwingen validatie en verse renders af bij elke commit die
+het model raakt. De afweging achter deze opzet, inclusief wat we inleveren
+ten opzichte van de JSON-aanpak in het zusterexperiment, staat in
+`adr/0001-archimate-als-bron.md`; het besluit om gegenereerde renders wel te
+committen staat in `adr/0002-views-als-mermaid-in-git.md`, dat voor de
+slidedecks in `adr/0003-slidedecks-als-toml-in-git.md`.
+
+## Structuur
+
+```
+models/ado.archimate         Het model, de bron van waarheid
+decks/                       Deckdefinities voor presentaties (TOML)
+views/                       Gerenderde views als Mermaid (.md, rendert op GitHub)
+views/html/                  Dezelfde views als NLDD-HTML, lokaal te bekijken
+views/html/slides/           Gerenderde slidedecks (één HTML per deck)
+docs/conventies.md           Types, property-keys en naamgeving
+docs/spelregels.md           Rollen, workflow en de een-schrijver-afspraak
+adr/                         Architectuurbeslissingen
+tools/archi_tool/            De archi-CLI (Python, lxml; beheerd met uv)
+tests/                       pytest-suite met een klein fixture-model
+.claude/skills/              Procedures voor AI-sessies (archi-model, archi-view, archi-slides)
+justfile                     Vaste taken
+```
+
+## Aan de slag
+
+Nodig: [uv](https://docs.astral.sh/uv/), [just](https://just.systems/) en
+[Archi](https://www.archimatetool.com/) voor normalisatie.
+
+macOS:
+
+```bash
+brew install uv just
+brew install --cask archi
+```
+
+Windows (PowerShell):
+
+```powershell
+winget install --id astral-sh.uv -e
+winget install --id Casey.Just -e
+winget install --id Archi.Archi -e
+```
+
+Linux: uv via `curl -LsSf https://astral.sh/uv/install.sh | sh`, just via je
+packagemanager, Archi als tgz van
+[archimatetool.com/download](https://www.archimatetool.com/download/).
+
+Archi wordt automatisch gevonden op `/Applications/Archi.app` (macOS),
+`C:\Program Files\Archi\Archi.exe` (Windows) en `/opt/Archi/Archi` (Linux);
+een ander pad geef je op via de env var `ARCHI_APP`. Python en pre-commit
+hoef je niet zelf te installeren: uv regelt de Python-versie en pre-commit
+is een dev-dependency.
+
+```bash
+just setup       # eenmalig per clone: venv, dependencies en pre-commit hooks
+just stats       # wat zit erin
+just open        # model openen in Archi
+just serve       # gerenderde HTML-views op http://localhost:8766
+```
+
+Sla `just setup` niet over: zonder de pre-commit hooks kun je committen
+zonder validatie en met verouderde renders.
+
+Alle vaste taken:
+
+| Commando | Wat het doet |
+|---|---|
+| `just setup` | venv, dependencies en pre-commit hooks installeren |
+| `just validate` | integriteitschecks (draait ook als pre-commit hook) |
+| `just render` | views en decks renderen naar `views/` en `views/html/` (ook hook) |
+| `just normalize` | canonieke serialisatie via headless Archi, duurt zo'n 15 s |
+| `just stats` | telling per elementtype, relaties en views |
+| `just tree` | folderstructuur van het model met inhoud |
+| `just list *args` | elementen tonen, bv. `just list --type Capability` |
+| `just show *args` | één element met properties en relaties, bv. `just show "Gegevensuitwisseling"` |
+| `just test` | pytest-suite |
+| `just open` | model openen in Archi |
+| `just serve` | HTML-views serveren op http://localhost:8766 |
+
+Wijzigen doe je met de CLI. Die valideert het model na elke mutatie en
+weigert op te slaan zolang er fouten zijn. Elementen zijn aanspreekbaar op id
+of op naam, zolang die uniek is:
+
+```bash
+uv run archi list --type Capability --property "Capability-niveau=gebied"
+uv run archi show "Gegevensuitwisseling"
+uv run archi tree
+uv run archi add-element --type Capability --name "..." \
+    --property "Capability-niveau=bouwblok" --property "Omschrijving=..."
+uv run archi add-relation --type Aggregation \
+    --source "Gegevensuitwisseling" --target "..." --name "bevat"
+uv run archi set-property "Gegevensuitwisseling" "Omschrijving=..."
+uv run archi rename "Oude naam" "Nieuwe naam"
+uv run archi set-documentation "Gegevensuitwisseling" "..."
+uv run archi remove "Gegevensuitwisseling" --cascade
+uv run archi add-view --name "..." --layout cluster \
+    --type Capability --relation Aggregation
+uv run archi add-view --name "... in detail" --layout cluster \
+    --root "Gegevensuitwisseling" --related
+uv run archi add-view --name "Losse selectie" --layout grid \
+    --element "Gegevensuitwisseling" --element "Kunstmatige Intelligentie"
+uv run archi slides --deck decks/ado.toml
+uv run archi set-model-name "..."
+uv run archi --help
+```
+
+Elk commando heeft nog wat minder gebruikte vlaggen: `add-element --folder`
+overschrijft de folder-plaatsing (default volgt uit het type), `add-view
+--element` voegt losse elementen aan een selectie toe (zie hierboven), en
+`slides` accepteert `--deck`, `--decks` en `--out` om gericht te renderen. De
+volledige set toont `uv run archi <commando> --help`.
+
+## Werkwijze
+
+Branch afsplitsen, wijzigen, `just validate`, `just normalize`, committen en
+een PR openen. De pre-commit hook rendert de views mee; verandert er iets in
+`views/`, dan faalt de commit een keer en stage je de verse renders erbij.
+CI draait dezelfde checks (validatie, actuele renders, tests) op Ubuntu en
+Windows, dus een omzeilde hook strandt alsnog op de PR. De
+architect-eigenaar reviewt en merget.
+
+De belangrijkste afspraak: een schrijver tegelijk op het modelbestand. Een
+enkel XML-bestand merget slecht, dus parallelle branches met modelwijzigingen
+zijn er niet. Tooling- en documentatie-PR's kunnen wel naast elkaar lopen.
+Details en rollen staan in `docs/spelregels.md`; de modelconventies (welke
+types, welke property-keys, Nederlandse naamgeving) in `docs/conventies.md`.
+
+Werk je met Claude Code, dan wordt `CLAUDE.md` automatisch geladen en
+triggeren de skills `archi-model` (modelwijzigingen doorvoeren), `archi-view`
+(views genereren) en `archi-slides` (presentaties maken) zodra je erom
+vraagt.
+
+## Herkomst
+
+Het seedmodel is de export van het ADO-niveau-1-model uit
+[`ADO-architectuurmodel-experiment`](https://github.com/BureauArchitectuurDigitaleOverheid/ADO-architectuurmodel-experiment),
+waar JSON de bron is en ArchiMate een exportformaat. Dit repo draait die
+verhouding om: het Archi-bestand is de bron, en al het andere wordt eruit
+gegenereerd.
+
+## Licentie
+
+[EUPL-1.2](LICENSE).