feat: add version 0.1 of the diagrams specification

AGENTS.md

@@ -1,11 +1,12 @@
 # Instructions for agents
 
-This repository holds an FPSOT specification.
-Replace this line with what the specification covers.
+This repository holds the FPSOT diagrams specification.
+It covers diagrams as code in PlantUML, the choice of C4, UML and BPMN, data model diagrams generated from LinkML, text alternatives and color in diagrams, SVG output and file names, and diagrams in English and French.
 
-- The normative text is in `spec/en/` and `spec/fr/`. Every rule has an ID such as `XYZ-001`.
-- Follow `skill/SKILL.md` when you work on this specification. The spec text wins on any difference.
+- The normative text is in `spec/en/` and `spec/fr/`. Every rule has an ID such as `DIA-001`.
+- Follow `skill/SKILL.md` when you add or change a diagram. The spec text wins on any difference.
 - Every page exists in English and in French, with the same file name and the same IDs.
+- Accessibility rules and values belong to the FPSOT accessibility specification. Point to it and never restate a value.
 - Terms and abbreviations come from the term base of `fpsot-spec-writing`. Add a missing term there first.
-- Do not copy text from outside standards. Summarise them in your own words and cite the exact version.
+- Do not copy text from outside standards. Summarize them in your own words and cite the exact version.
 - Commits follow Conventional Commits and are signed. Pull requests are squash-merged.

CHANGELOG.md

@@ -6,15 +6,19 @@ and versions follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.h
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-11-05
+
 ### Added
 
-- `AGENTS.md`, a book per language (`spec/<lang>/book.adoc`) ending with the glossary, and a document history on each page.
-- Example requirement TPL-001 and an example comparison row in `jurisdictions/baseline.yaml`.
-- `.gitignore` for the files that the continuous integration writes.
+- Diagrams as code: PlantUML sources in `diagrams/`, their header comments, the pinned renderer, size, titles, legends and labels (DIA-001 to DIA-007).
+- Notations: C4 views for architecture, UML 2.5.1 for structure and behavior, BPMN 2.0.2 for business processes drawn as PlantUML activity diagrams, and data model diagrams generated from LinkML (DIA-010 to DIA-018).
+- Text alternatives and color: the short alternative, the long description per notation, color never alone, contrast through the accessibility specification, and an opaque background (DIA-020 to DIA-025).
+- Output and file names: committed SVG files, how pages embed them, self-contained SVG and view endings in file names (DIA-030 to DIA-033).
+- Diagrams in two languages: one source per language, shared layouts with label files, and names that stay in English (DIA-040 to DIA-044).
+- Comparison data with an international baseline, Canada and Québec rows.
+- A how-to guide with one PlantUML example per notation, a bilingual example diagram, the agent skill, `llms.txt` and a book per language.
 
-### Changed
+### Known gaps
 
-- The continuous integration runs the documentation checks, and releases can attach the PDF books.
-- Pages include the term base attributes. The guide page has a page type.
-- The French conformance section quotes RFC 8174 and points to WRT-011.
-- `NOTICE` spells out FPSOT. `NOTICES.md` names the Code of Conduct contact.
+- The accessibility specification is written at the same time; its requirement IDs are not cited yet.
+- No check yet confirms that a generated data model diagram matches its schema.

NOTICE

@@ -7,5 +7,5 @@ CONTRIBUTOR_LICENSE_AGREEMENT.md, SCOPE.md, NOTICES.md, GOVERNANCE.md, CONTRIBUT
 CODE_OF_CONDUCT.md) come from the Community Specification 1.0 repository,
 https://github.com/CommunitySpecification/Community_Specification
 at commit 8a05e46d768ac0525af882b619c42f3380a9e869.
-LICENSE.md is changed to name Apache-2.0, instead of MIT, as the source code licence.
+LICENSE.md is changed to name Apache-2.0, instead of MIT, as the source code license.
 NOTICES.md names the Code of Conduct contact and drops the instruction about it.

README.adoc

@@ -1,30 +1,23 @@
-= FPSOT specification template
+= FPSOT diagrams specification
 
-This repository is the starting point for an FPSOT specification.
-Create a new repository from it, then replace this text.
-
-== Start a specification
-
-. Set `SPEC_PREFIX` in `.github/workflows/ci.yml` to the three-letter prefix of the requirement IDs.
-. Replace the titles in `spec/`, `docs/antora.yml`, `publiccode.yml`, `AGENTS.md`, `NOTICE` and `skill/SKILL.md`.
-. Replace the example requirement TPL-001 and the example row in `jurisdictions/baseline.yaml`.
-. List each spec page in `spec/<lang>/book.adoc`. The glossary stays the last include.
-
-Each page ends with a document history.
-Each guide page sets `:page-type:` to tutorial, how-to, reference or explanation.
-Write abbreviations and defined terms as `{abbr-…}` and `{term-…}` from the term base of `fpsot-spec-writing`.
-The continuous integration writes `_fpsot-terms.adoc`, the glossaries and the comparison pages. Git ignores them.
+Rules for diagrams in FPSOT repositories: diagrams as PlantUML code, C4 views for architecture, UML 2.5.1 for structure and behavior, BPMN 2.0.2 for business processes, data model diagrams generated from LinkML, text alternatives, color, SVG output, file names, and diagrams in English and French.
+Accessibility rules and values come from the FPSOT accessibility specification.
+Version 0.1 is a draft.
 
 == Implement this spec
 
 Read the normative text in `spec/en/` or `spec/fr/`.
-Each requirement has an ID, such as `XYZ-001`.
-Check your implementation against every requirement.
+Start with `index.adoc`, then read the five parts.
+Each requirement has an ID from `DIA-001` to `DIA-044`.
+Check each diagram of your repository against every MUST rule.
+The shared `diagrams` workflow of `fpsot-org/GitHub-Actions` renders the sources and checks the committed SVG files.
 
 == Adopt this spec
 
-Read the guides in `docs/modules/en/pages/` or `docs/modules/fr/pages/`.
-They explain what the spec gives your organisation and how to require it.
+Read the guide in `docs/modules/en/pages/index.adoc` or `docs/modules/fr/pages/index.adoc`.
+It shows one small PlantUML example per notation, and how to embed a diagram with its text alternatives.
+The comparison pages show how the practice of Canada and Québec relates to each requirement.
+To require the spec from a supplier, ask that every delivered diagram conforms to it.
 
 == Layout
 
@@ -42,16 +35,16 @@ They explain what the spec gives your organisation and how to require it.
 | The agent skill: a short summary that cites requirement IDs.
 
 | `rules/`
-| Machine-checkable rules.
+| Machine-checkable rules. None yet.
 
 | `diagrams/`
-| PlantUML sources and their rendered SVG files.
+| PlantUML sources and their rendered SVG files: the example context diagram of the guide, in English and French.
 
 | `jurisdictions/`
-| Comparison data per jurisdiction. `baseline.yaml` lists the compared requirements.
+| Comparison data: the international baseline, Canada and Québec.
 |===
 
-== Licence
+== License
 
 The specification is under the Community Specification License 1.0.
 Source code is under the Apache License 2.0.

SCOPE.md

@@ -1,5 +1,9 @@
-# Scope
-
-[Include a detailed description of this Working Group’s Scope.  This Scope is important is it establishes the bounds of each contributor's and licensee's patent commitment. For guidance on drafting an appropriate Scope, you may find [ISO's guidance (see page 5)](https://www.iso.org/files/live/sites/isoorg/files/developing_standards/docs/en/how-to-write-standards.pdf "ISO How To Write Standards Guide") helpful.]
-
-Any changes of Scope are not retroactive.
+# Scope
+
+This Working Group develops the FPSOT diagrams specification.
+
+The specification covers how FPSOT projects draw, publish and translate diagrams: diagrams as code in PlantUML, the choice of notation (the C4 model for architecture, UML for structure and behavior, BPMN for business processes, and data model diagrams generated from LinkML schemas), the content of text alternatives for diagrams, the use of color in diagrams, the rendered SVG files and their names, and diagrams in English and French.
+
+It does not set accessibility rules or values, which the FPSOT accessibility specification sets, nor the names of files in general, which the FPSOT naming specification sets.
+
+Any changes of Scope are not retroactive.

diagrams/registry-context-en.puml

@@ -0,0 +1,6 @@
+@startuml registry-context-en
+' SPDX-License-Identifier: Community-Spec-1.0
+' Context diagram of the registry, the C4 example of the how-to guide (DIA-011, DIA-042).
+!include registry-context-labels-en.iuml
+!include registry-context.iuml
+@enduml

diagrams/registry-context-fr.puml

@@ -0,0 +1,6 @@
+@startuml registry-context-fr
+' SPDX-License-Identifier: Community-Spec-1.0
+' Context diagram of the registry, the C4 example of the how-to guide (DIA-011, DIA-042).
+!include registry-context-labels-fr.iuml
+!include registry-context.iuml
+@enduml