docs(adr): record schema version policy

Author: bhdicaire

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,33 @@
+# 0001. Record architecture decisions in the code repository
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+vanityURLs has product behavior, generated configuration, installer behavior, and deployment assumptions that are easier to understand when the reason for a decision is close to the code that implements it.
+
+The public website should explain how to use vanityURLs, but it should not become a long internal design log. Maintainers still need a lightweight place to record why code-level contracts exist.
+
+## Decision
+
+Record architecture decision records as Markdown files under `docs/adr/` in the code repository.
+
+Use a small structure:
+
+- title, date, and status
+- context
+- decision
+- consequences
+
+Number ADR files with a stable prefix, for example `0001-record-architecture-decisions.md`.
+
+The website may link to an ADR or source file when the implementation detail matters, but ADRs are maintained in the code repository.
+
+## Consequences
+
+- Design history travels with the code
+- Website pages can stay short and user-focused
+- Changes to product contracts can reference a local ADR in the same pull request or commit
+- ADRs are not a replacement for user documentation, tests, or inline code comments

docs/adr/0002-site-config-schema-versioning.md

@@ -0,0 +1,31 @@
+# 0002. Treat site config schema version as a stored contract
+
+Date: 2026-05-26
+
+Status: Accepted
+
+## Context
+
+`defaults/v8s-site-config.json` and `custom/v8s-site-config.json` include `schema_version`. The value has stayed at `1.0` while new optional fields were added, such as link CLI defaults and installer-managed branding fields.
+
+Additive fields do not currently require instance owners to migrate existing files because the build and installer merge defaults with custom values and tolerate missing optional fields.
+
+## Decision
+
+Keep `schema_version` at `1.0` for additive, backward-compatible changes.
+
+Increment `schema_version` only when a stored `custom/v8s-site-config.json` file needs a migration or when existing field semantics change incompatibly.
+
+When `schema_version` changes, the same change should include:
+
+- the new default schema version in `defaults/v8s-site-config.json`
+- installer or upgrade behavior that handles older custom files
+- documentation in the related release notes or ADR
+- tests or checks for the migration behavior when practical
+
+## Consequences
+
+- Instance owners are not asked to interpret schema bumps for optional fields
+- Maintainers have a clear trigger for schema version changes
+- The current `schema_version` remains useful as a future migration marker even though it is not bumped for every new field
+- Source files remain the implementation contract for exact fields