dev-centr · AMDphreak · Aug 8, 2026 · Aug 8, 2026 · cursor · Aug 8, 2026
diff --git a/README.md b/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>

diff --git a/RULES.md b/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.

diff --git a/general/antora-docs-sites.md b/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`.
diff --git a/general/creator.md b/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).
diff --git a/general/documentation.md b/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
 

diff --git a/general/global.md b/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

diff --git a/general/readme-layout.md b/general/readme-layout.md
@@ -2,11 +2,28 @@
 
 Read this when creating or revising a **GitHub-facing** `README.md` / `README.adoc` for owned or org repos. Structure inspiration: [othneildrew/Best-README-Template](https://github.com/othneildrew/Best-README-Template). Canonical blanks: [dev-centr/readme-template](https://github.com/dev-centr/readme-template) (fork to other orgs / personal profile as needed).
 
-Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate.
+Do **not** batch-script README rewrites across repos. Hand-edit each file so stack grouping, contact, and omitted sections stay accurate. Not every repo needs the full template — omit fields that will never apply (e.g. no logo). That template assumes the repo is a project hub; lighter repos stay simpler.
+
+## Format choice
+
+| Situation | README format |
+|-----------|----------------|
+| **Default (owned / first-party)** | Prefer **AsciiDoc** (`README.adoc`). On GitHub, use embedded HTML for the centered title/header; use `[.text-center]` (or HTML) for other centered blocks. |
+| **Fork of an upstream project** | **Retain Markdown** if upstream is Markdown. Do not convert away from the fork’s face format. |
+| **Package registry that only parses Markdown** (npm, crates.io listing copy, etc.) | Keep or add a **Markdown** README (or registry-facing copy) for the registry. Do **not** delete a Markdown copy that exists for that reason. Deep docs may still be AsciiDoc/Antora. |
+| **Major user-facing + Best-README HTML centering** | GitHub’s AsciiDoc subset centers poorly; **`README.md`** as the repo face is fine (deep docs under `docs/`). |
+
+## Docs link (org repos)
+
+For **organization** repositories with a README: include an **Explore the docs »** text link in the centered header (same pattern as `dev-centr/readme-template` / `switchyard`), pointing at the **org docs hub** component URL (e.g. `https://docs.devcentr.org/<component>/`), not a secondary per-repo Pages Antora site. Do **not** add a separate `Docs | Org` shield — that fights the established contributors/forks/stars/issues/(license) chrome.
+
+**CI status badges** are optional. Prefer leaving them out of the centered header unless the repo already uses one; do not require a CI chip for every workflow-enabled repo.
+
+Personal-user repos: skip the org-hub docs CTA unless that user publishes a docs site you should link.
 
 ## Why the prior refresh broke
 
-1. **Badge targets** — Shields must open the *thing they represent* (contributors graph, stargazers, issues, license blob, tech homepage). Never the shield image URL.
+1. **Badge targets** — Shields must open the *thing they represent* (contributors graph, stargazers, issues, license blob, tech homepage). Never the shield image URL. Docs discovery is the **Explore the docs »** text link (hub URL), not an extra Docs shield.
 2. **Markdown inside `<div align="center">`** — GitHub often does **not** resolve `[![x][shield]][url]` inside HTML blocks, so badges appear to link only to the image (or nowhere useful). **In the centered header, use HTML:** `<a href="DEST"><img src="https://img.shields.io/…" alt="…"></a>`.
 3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `<a href><img>` on GitHub, or always keep `link=` on `image:` macros.
 4. **Centering** — One centered block for **badges + title + one-liner + quick links**. Title-only centering with badges left above is incomplete.
@@ -17,11 +34,13 @@ Do **not** batch-script README rewrites across repos. Hand-edit each file so sta
 
 | Audience | Layout |
 |----------|--------|
-| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header, linked shields, structured Built With, TOC, section back-to-top, Contact, optional contrib.rocks |
+| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header (contributors/forks/stars/issues/license as applicable), **Explore the docs »** → hub when docs exist, structured Built With, TOC when >3 sections, section back-to-top, Contact, optional contrib.rocks |
 | **Internal / non-downstream** | Simplified: linked shields + short About + install/usage if needed + License/Contact. Skip LinkedIn, empty Roadmap/Acknowledgments, contrib.rocks, demo marketing links |
 | **Skip** | School repos, org `.github` profiles, archived, package-tap / registry-instruction-only, empty repos |
 
-Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major user-facing repos that need Best-README HTML centering: GitHub’s AsciiDoc subset does not center like Markdown. For those, use **`README.md`** as the repo face (deep docs stay under `docs/`).
+## Table of contents
+
+Include a TOC when the README has **more than three** sections (collapsible `<details>` is fine on Markdown).
 
 ## Markdown header (required shape)
 
@@ -39,7 +58,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u
   <p align="center">
     project_description
     <br />
-    <a href="DOCS_OR_REPO"><strong>Explore the docs »</strong></a>
+    <a href="https://docs.devcentr.org/COMPONENT/"><strong>Explore the docs »</strong></a>
     <br />
     <br />
     <a href="DEMO_OR_OMIT">View Demo</a>
@@ -51,7 +70,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u
 </div>
 ```
 
-Omit license badge / demo / docs links when absent. Collapsible TOC via `<details>` is fine.
+Omit license / demo / docs links when absent. Point **Explore the docs** at the org hub component URL when the org has a docs site. Collapsible TOC via `<details>` is fine when the README has more than three sections.
 
 ### Built With (outside the HTML header)