Merge pull request 'Decide the wiki structure, page names and languages (ADR-0001)' (#46) from mil-005-wiki-structure-decision into main

Reviewed-on: #46

docs/adr/adr-0001-wiki-structure-and-languages.md

@@ -0,0 +1,100 @@
+# ADR-0001: Wiki structure, page names and languages
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0001 |
+| CrossReference | [MIL-005], [BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-10 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [f5fb023] |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+MIL-005 puts the documentation on the Gitea wiki in English, Danish and
+Bahasa Malaysia. Before translations are written, three things must be fixed,
+because the generator, the publishing workflow and the translators all depend
+on them: which pages exist, how a translated page is named, and which copy is
+authoritative.
+
+Forces:
+
+- The Gitea wiki is a flat list of pages; a hyphen in a page name is shown as
+  a space, and a `/` in a name needs encoding in links and in the REST API.
+- The English pages are generated from `README.md` and `guides/`
+  (`tools/build_wiki.py`) and published only by the workflow from `main`
+  (task 8). A translation must therefore live in this repository too, so it is
+  reviewed like any other change.
+- A translation silently goes stale when the English page changes. Rule 8 of
+  `AGENTS.md` requires each translated page to name the English source it
+  follows, so staleness must be detectable without the network.
+- The Business Case sets no deadline and the Product Owner language is
+  English, so English stays the single authoritative text.
+
+Options for the page name of a translation:
+
+1. **Suffix with a dot:** `Home` (English), `Home.da`, `Home.ms`. One flat
+   namespace, English has no suffix, and the files are `wiki/Home.da.md`.
+2. **Folder per language:** `da/Home`, `ms/Home`. Mirrors the repository
+   layout but needs encoded links and an encoded API path.
+3. **Suffix with a hyphen:** `Home-da`. Simple, but Gitea reads the hyphen as
+   a space, so the title shows as "Home da".
+
+Options for the source of truth of a translation:
+
+1. **Generated by machine on every change.** No stale pages, but no review by
+   a native reader and wording that changes between runs.
+2. **Written once, kept in `wiki/`, reviewed, and checked for staleness.**
+   Reviewed wording is stable; staleness is flagged by a check.
+
+## Decision
+
+The wiki has five pages (Home, Onboarding, Credentials, Troubleshooting,
+Capabilities). The English page has no suffix and is generated; a translation
+is the page name plus `.da` or `.ms` (`Home.da`, `Credentials.ms`), written by
+hand in `wiki/<Page>.<lang>.md`, reviewed by a native reader, and published by
+the same workflow. English is authoritative.
+
+Each translation starts with the comment
+`<!-- translation of <Page>.md, source sha256 <first 12 hex of the English file> -->`,
+so a check can report a translation whose English source has changed. Code
+blocks, commands, file names and the workflow's error messages stay in
+English. Terms are kept consistent through a term list (`docs/wiki-terms.md`,
+created in MIL-005 task 4).
+
+## Consequences
+
+**Positive:**
+
+- One flat set of 15 pages that the existing generator and publisher handle
+  without a new code path.
+- A stale translation is detectable offline from the recorded hash.
+- Translations are reviewed and stable, and reach the wiki only by merge.
+
+**Negative:**
+
+- Dots in page names are not yet verified on this wiki; MIL-005 task 7 (#38)
+  must publish and open them. The fallback is `Home_da`, which changes only
+  the file names and links.
+- A translation is not updated by itself; a person must re-translate when the
+  check reports it stale, so the translations can lag the English pages.
+- The check, and the language switcher line at the top of each page, are
+  still to be built in task 4.
+
+## Affected Artifacts
+
+- [MIL-005] — closes task 1 (issue #32) and defines the naming that tasks 4
+  and 5 follow.
+- [BC-001] — the wiki in three languages is in its scope list.
+
+---
+
+[MIL-005]: ../milestones/mil-005-wiki-and-translations.md
+[BC-001]: ../business-case.md
+[f5fb023]: https://git.tirsystem.com/TirSystem/github-action/commit/f5fb0238f36cbb98de482c68842fc60c7ce959e2

docs/artifact-registry.md

@@ -13,6 +13,7 @@ each document lives in *this* project and the next version to use.
 | MIL | Milestone / Gateway | docs/milestones/*.md | 006 |
 | RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 012 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0002 |
 
 ## Languages
 
@@ -25,8 +26,9 @@ each document lives in *this* project and the next version to use.
 The PO language is English, so no PO-language translations are kept.
 
 The Gitea wiki (MIL-005) is the one exception: its pages are kept in English
-(authoritative), Danish (`da`) and Bahasa Malaysia (`ms`). Each translated page
+(authoritative), Danish (`da`) and Bahasa Malaysia (`ms`). A translation is named
-names the English source version it follows.
+`<Page>.<lang>` (`Home.da`) and names the English source it follows; see
+`docs/adr/adr-0001-wiki-structure-and-languages.md`.
 
 | Artifact types | Register | Also kept as a PO-language file |
 | --- | --- | --- |