docs: add Antora changelog backfilled from git history

README.md

@@ -8,6 +8,8 @@
   <h1>Agent Rules</h1>
   <p>Forkable modular agent rules with 1-step assembly for local AI coding assistants.</p>
   <p>
+    <a href="https://docs.devcentr.org/agent-rules/"><strong>Explore the docs »</strong></a>
+    <br /><br />
     <a href="https://github.com/dev-centr/agent-rules/issues">Report Bug</a>
     &middot;
     <a href="https://github.com/dev-centr/agent-rules/issues">Request Feature</a>
@@ -25,6 +27,7 @@
     </li>
     <li><a href="#installation">Installation</a></li>
     <li><a href="#usage">Usage</a></li>
+    <li><a href="#changelog">Changelog</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#contact">Contact</a></li>
   </ol>
@@ -144,6 +147,12 @@ Public README blanks live in [dev-centr/readme-template](https://github.com/dev-
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+## Changelog
+
+Notable functional changes: [changelog on the docs site](https://docs.devcentr.org/agent-rules/changelog.html).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## Contributing
 
 Add a license file if you want this repository to be reusable by others. Pull requests with portable rule improvements are welcome.

RULES.md

@@ -35,14 +35,14 @@
 ## Creator (owned orgs)
 - Transfers: `gh api`.
 - Config: SDL (`.sdl`) for DevCentr-owned / `sdlang-d` surfaces; **KDL** (`.kdl`) for greenfield outside that stack; JSON5 when stuck in the JSON family. Do **not** adopt Extended SDL/XDL.
-- Changelog: every project; README links to it; timeline + `changelog-details/date - title`.
+- Changelog: every project; functional changes; README links to it; index + `changelog-details/date - title`; backfill from git if missing; wire into docs; alert user if cross-org secrets are required.
 
 ## Docs
 - Structure: Diátaxis (tutorials, how-to, explanation, reference).
-- Format: AsciiDoc unless host requires Markdown (e.g. npm).
-- Antora: follow `dev-centr` publishing guidance.
+- Format: AsciiDoc by default; retain Markdown on upstream forks; keep/add Markdown when a package registry only parses Markdown.
+- Antora: Valentus theme + org branding; Lunr + `antora-supplemental` AI search (`antora-search-chat`); follow `dev-centr` publishing guidance. If those extensions cannot be found, alert the user and wait.
 - **One Antora site per org** with a hub (e.g. docs.devcentr.org): wire `docs/` into the hub playbook; never publish a second Antora site on project GitHub Pages. Deduplicate errant sites. See `general/antora-docs-sites.md`. (Does not apply to mixing Antora with other docs systems.)
-- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: linked badges, centered header, role-grouped Built With, back-to-top). Hand-edit per repo; blanks in `dev-centr/readme-template`.
+- **Public README layout:** when creating/revising GitHub-facing READMEs, follow `general/readme-layout.md` (Best-README adapted: centered for-the-badge chrome, **Explore the docs »** → org hub, TOC if >3 sections, role-grouped Built With, back-to-top). Do not add Docs/CI shields that break the established look. Hand-edit per repo; blanks in `dev-centr/readme-template`.
 - Titles: follow site `STYLE.adoc` / `AGENTS.md` (not MEMORIES). Short defaults — first-party news omits org; action essays pass implied [On] and drop surplus *the*; prefer `X as Y` / *when* / disproof / questions over rigid `X is Y`; attach floating modifiers to an object; docs topics = concept names. Philosophy: `Titles as orientation`. Cursor rules = `.cursor/rules/*.mdc` dir; this file stays the paste preamble.
 - Project facts: `AGENTS.md` + README/docs. Do not commit per-repo `MEMORIES.md`.
 - **App shipping architecture:** when scaffolding/building/shipping apps, read `general/app-architecture.md` and adhere to Software Product Essentials under `$CODE_ROOT/github.com/dev-centr/general-knowledge/docs/modules/ROOT/pages/explanation/architecture/` (hub: `software-product-essentials.adoc`). About/build info, debug dump, Windows auto-update, installers, and CI release pipelines are core—not polish.

docs/modules/ROOT/nav.adoc

@@ -1,3 +1,4 @@
 * xref:index.adoc[Overview]
 * xref:usage.adoc[Usage]
 * xref:architecture.adoc[Architecture]
+* xref:changelog.adoc[Changelog]

docs/modules/ROOT/pages/changelog-details/2026-03-23 - Initial forkable agent rules.adoc

@@ -0,0 +1,14 @@
+= 2026-03-23 — Initial forkable agent rules
+
+== Summary
+
+First public release of canonical forkable agent rules for Dev-Centr coding assistants.
+
+== Changes
+
+* Repository structure: `general/`, `profiles/`, `RULES.md`, `README.md`.
+* **1-step assembly** — Paste `RULES.md`; agent batches reads of profile + general modules via native file tools.
+* Split OS layers: `general/windows.md`, `general/mac.md`, `general/linux.md` selected by profile `ENVIRONMENT`.
+* Added `general/documentation.md`, trimmed `general/creator.md`, placeholder profiles with required constants.
+* README: profile constants table; clone vs paste-only setup; human vs agent audience clarification.
+* `RULES.md` as agent-directed entrypoint.

docs/modules/ROOT/pages/changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc

@@ -0,0 +1,12 @@
+= 2026-03-31 — RULES.md preamble consolidation
+
+== Summary
+
+Reorganized the human vs agent entrypoints and clarified workstation memory location.
+
+== Changes
+
+* `MAIN.md` — Human-oriented assembly entrypoint listing modules to paste or compose.
+* `RULES.md` — Generalized consolidated preamble for direct paste into agent rules fields.
+* Clarified **`$CODE_ROOT/MEMORIES.md`** as canonical workstation memory (not per-repo `MEMORIES.md` in this clone).
+* `MEMORIES.example.md` committed as format reference; per-repo copy remains gitignored.

docs/modules/ROOT/pages/changelog-details/2026-08-03 - App shipping architecture layer.adoc

@@ -0,0 +1,11 @@
+= 2026-08-03 — App shipping architecture layer
+
+== Summary
+
+Agents scaffolding or shipping applications must follow product-architecture guidance, not just coding style rules.
+
+== Changes
+
+* Added `general/app-architecture.md` optional layer.
+* `RULES.md` — Point agents at Software Product Essentials under `general-knowledge` when building apps (About, updates, installers, CI release pipelines as core—not polish).
+* Separated app shipping architecture from Dev-Centr product automation (`devcentr-agent-rules`).

docs/modules/ROOT/pages/changelog-details/2026-08-06 - README layout and Antora org policy.adoc

@@ -0,0 +1,13 @@
+= 2026-08-06 — README layout and one Antora site policy
+
+== Summary
+
+Documented public README layout conventions and org-wide Antora publishing policy.
+
+== Changes
+
+* `general/readme-layout.md` — Best-README–adapted layout: HTML-linked shields in centered header, role-grouped Built With, back-to-top, contrib.rocks tiering.
+* `general/antora-docs-sites.md` — **One Antora site per org**; wire `docs/` into hub playbook; dedupe secondary GitHub Pages Antora sites.
+* `general/creator.md` — Prefer SDL (`.sdl`) in DevCentr stack; KDL (`.kdl`) greenfield; ban Extended SDL/XDL.
+* `RULES.md` / README — Sync-before-work habit; rules-manager path for composed rules.
+* README aligned with public template layout (centered chrome, TOC, Built With).

docs/modules/ROOT/pages/changelog-details/2026-08-07 - Antora component docs.adoc

@@ -0,0 +1,12 @@
+= 2026-08-07 — Antora component docs
+
+== Summary
+
+Introduced an Antora documentation component for this repository and scrubbed personal-repo references from public-facing text.
+
+== Changes
+
+* Added `docs/antora.yml` and ROOT pages: overview, usage, architecture.
+* Wired component into `dev-centr/docs` hub playbook (`agent-rules` source).
+* README and docs point at `https://docs.devcentr.org/agent-rules/` instead of personal clones.
+* Distinguished **agent-rules** (forkable end-user rules) from **devcentr-agent-rules** (product automation).

docs/modules/ROOT/pages/changelog-details/2026-08-08 - Documentation standards expansion.adoc

@@ -0,0 +1,15 @@
+= 2026-08-08 — Documentation standards expansion
+
+== Summary
+
+Expanded agent-facing documentation rules so README, Antora, and changelog expectations match Dev-Centr org docs automation practice.
+
+== Changes
+
+* `RULES.md` — AsciiDoc-by-default README format; Valentus + Lunr + `antora-search-chat`; changelog backfill and cross-repo wiring alerts.
+* `general/readme-layout.md` — Format-choice table; **Explore the docs »** hub CTA instead of a Docs shield; optional CI badges; TOC when >3 sections.
+* `general/documentation.md` — Valentus default UI; Lunr + AI search extensions; alert-and-wait if `antora-supplemental` is missing.
+* `general/creator.md` — Functional changelog requirement; index + `changelog-details/` structure; git backfill; cross-org secret alerts.
+* `general/antora-docs-sites.md` — Default UI and search section.
+* `general/global.md` — Load `antora-docs-sites.md` and `readme-layout.md` when relevant.
+* `README.md` — Centered **Explore the docs »** link to `https://docs.devcentr.org/agent-rules/`.

docs/modules/ROOT/pages/changelog-details/index.adoc

@@ -0,0 +1,10 @@
+= Changelog details
+
+Full changelog entries for xref:changelog.adoc[agent-rules].
+
+* xref:2026-08-08 - Documentation standards expansion.adoc[2026-08-08 — Documentation standards expansion]
+* xref:2026-08-07 - Antora component docs.adoc[2026-08-07 — Antora component docs]
+* xref:2026-08-06 - README layout and Antora org policy.adoc[2026-08-06 — README layout and one Antora site policy]
+* xref:2026-08-03 - App shipping architecture layer.adoc[2026-08-03 — App shipping architecture layer]
+* xref:2026-03-31 - RULES.md preamble consolidation.adoc[2026-03-31 — RULES.md preamble consolidation]
+* xref:2026-03-23 - Initial forkable agent rules.adoc[2026-03-23 — Initial forkable agent rules]

docs/modules/ROOT/pages/changelog.adoc

@@ -0,0 +1,47 @@
+= Changelog
+:description: Notable functional changes to forkable agent rules, profiles, and documentation standards.
+
+Timeline of notable changes to **agent-rules**.
+Detailed notes live under xref:changelog-details/index.adoc[changelog-details].
+
+== 2026-08-08 — Documentation standards expansion
+
+xref:changelog-details/2026-08-08 - Documentation standards expansion.adoc[Details]
+
+* Expanded README, Antora, and changelog guidance across `RULES.md` and `general/*.md`.
+* README header: **Explore the docs »** hub CTA; no separate Docs/CI shields in the centered chrome.
+
+== 2026-08-07 — Antora component docs
+
+xref:changelog-details/2026-08-07 - Antora component docs.adoc[Details]
+
+* Added Antora component under `docs/` (overview, usage, architecture).
+* Removed personal-repo path examples from upstream-facing text.
+
+== 2026-08-06 — README layout and one Antora site policy
+
+xref:changelog-details/2026-08-06 - README layout and Antora org policy.adoc[Details]
+
+* Documented Best-README–adapted public README layout (`general/readme-layout.md`).
+* **One Antora site per org** policy; dedupe errant per-repo GitHub Pages Antora builds.
+* SDL in-stack / KDL greenfield config rules; sync-before-work habit in rules.
+
+== 2026-08-03 — App shipping architecture layer
+
+xref:changelog-details/2026-08-03 - App shipping architecture layer.adoc[Details]
+
+* Agents building apps must read `general/app-architecture.md` and Software Product Essentials.
+
+== 2026-03-31 — RULES.md preamble consolidation
+
+xref:changelog-details/2026-03-31 - RULES.md preamble consolidation.adoc[Details]
+
+* Consolidated paste preamble into `RULES.md`; `MAIN.md` as human assembly entrypoint.
+* Clarified `$CODE_ROOT/MEMORIES.md` as the canonical workstation memory file.
+
+== 2026-03-23 — Initial forkable agent rules
+
+xref:changelog-details/2026-03-23 - Initial forkable agent rules.adoc[Details]
+
+* Canonical forkable rules for Dev-Centr coding assistants.
+* 1-step assembly architecture, OS-specific layers, placeholder profiles with `ENVIRONMENT`.

general/antora-docs-sites.md

@@ -36,3 +36,8 @@ When you find a secondary Antora site in an Antora org:
 
 - Repo-local `antora-playbook.yml` for **developer preview** of one component is fine if it does **not** get published as an org-facing site.
 - Production publish path for Dev-Centr Antora components is always the `dev-centr/docs` aggregator.
+
+## Default UI and search
+
+- Prefer **Valentus** (`antora-supplemental/valentus-theme`) with org brand colors/logo from the org’s central assets.
+- Every published site: `@antora/lunr-extension` plus the AI search/help extension from `antora-supplemental` (`antora-search-chat`; see also `antora-ai-help-extension`). Details in `general/documentation.md`.

general/creator.md

@@ -16,7 +16,9 @@ Do not apply these rules to third-party open-source contributions unless explici
 
 ## Changelogs
 
-- When you create a project, integrate a changelog into its docs. If it lacks docs, put the changelog in the repo base.
+- All **functional** changes should appear in the changelog. Prefer the project’s existing changelog style when one exists (`general/global.md`).
+- When you create a project, integrate a changelog into its docs (or docs substructure for an existing documentation system). If it lacks docs, put the changelog in the repo base.
 - Put a link to the changelog in the README in a Changelog section.
-- The changelog should contain a timeline with quick summaries and links to very detailed changelogs for each date in a `changelog-details` subfolder that names files by `date - title`.
-- If you add docs afterward, update its changelog structure.
+- Structure: an index page named **changelog** (timeline of dates + short summaries + links) and detail pages under `changelog-details/` named `date - title`. Wire the changelog into the active docs system (Antora nav, etc.) when docs exist.
+- If no changelog exists, **create it** and **backfill** from observed functional changes in git history. Unpack commits when the subject line is too thin.
+- Wiring may require commits in **related** repositories (e.g. org docs hub playbook). If any of those repos cross **org** boundaries and CI/docs fetch needs auth, **alert the user** that a cross-repo deploy key or org/repo secret must be added (say which secret and which org/repo).

general/documentation.md

@@ -9,8 +9,11 @@ Read this file when you **author, structure, or publish** project documentation
 
 ## Antora (when used)
 
+- **Default stack:** Antora + **Valentus** UI (`antora-supplemental/valentus-theme`). Customize colors and logo from the org’s existing brand assets (org `.github` profile, eponymous site repo, or other central branding repo)—do not invent a one-off palette per component.
 - If the project uses **Antora**, follow the publishing and layout guidance in the Dev-Centr documentation repository: `dev-centr/devcentr` — see `docs/modules/publishing/pages/antora-deployment.adoc` for deployment-oriented details.
-- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine).
+- **One Antora site per org** that already has a hub (e.g. https://docs.devcentr.org). Do not publish secondary per-repo Antora sites on GitHub Pages. Keep `docs/` in the product repo; **wire** into the hub playbook. See `general/antora-docs-sites.md`. Actively deduplicate when you find errant sites. Does **not** apply to mixtures of different docs systems (Antora + Fumadocs is fine). Repo-local `antora-playbook.yml` for **preview/validation CI** is fine if it does **not** publish a second public site.
+- **Search:** Enable `@antora/lunr-extension` on every published Antora site. Add the AI-assisted search/help layer from **`antora-supplemental`** — prefer [`@antora-supplemental/antora-search-chat`](https://github.com/antora-supplemental/antora-search-chat) (Lunr-first Search/Ask omnibox). Related: [`antora-ai-help-extension`](https://github.com/antora-supplemental/antora-ai-help-extension). Register Lunr before wrappers that depend on it.
+- If `antora-supplemental` (or those extensions) cannot be found after a reasonable search (rename/move), **stop and alert the user** (email, Slack, or whatever channel is available) so they can notify whoever owns this automation rule — then wait for a reply before inventing a substitute.
 
 ## Relationship to creator rules
 

general/global.md

@@ -35,6 +35,8 @@ These apply universally unless a profile says otherwise.
   - If `ENVIRONMENT` is missing, ask the user which file applies before assuming an OS.
 - You **must** read `general/creator.md` before acting.
 - Read `general/documentation.md` when you are authoring, structuring, or publishing project documentation (optional layer for doc-heavy work).
+- Read `general/antora-docs-sites.md` when the task involves Antora sites, playbooks, GitHub Pages for docs, or wiring components into an org docs hub.
+- Read `general/readme-layout.md` when creating or revising a GitHub-facing README.
 - Read `general/app-architecture.md` when you are scaffolding, building, shipping, packaging, or maintaining an application, CLI, TUI, publishable library, game client, or service (optional layer; points at local Software Product Essentials docs).
 
 ## Memory management