dev-centr · cursor · Aug 8, 2026
diff --git a/README.md b/README.md
@@ -4,6 +4,7 @@
   <a href="https://github.com/dev-centr/agent-rules/network/members"><img src="https://img.shields.io/github/forks/dev-centr/agent-rules.svg?style=for-the-badge" alt="Forks"></a>
   <a href="https://github.com/dev-centr/agent-rules/stargazers"><img src="https://img.shields.io/github/stars/dev-centr/agent-rules.svg?style=for-the-badge" alt="Stargazers"></a>
   <a href="https://github.com/dev-centr/agent-rules/issues"><img src="https://img.shields.io/github/issues/dev-centr/agent-rules.svg?style=for-the-badge" alt="Issues"></a>
+  <a href="https://docs.devcentr.org/agent-rules/"><img src="https://img.shields.io/badge/docs-Dev--Centr-22c55e?style=for-the-badge" alt="Docs"></a>
 
   <h1>Agent Rules</h1>
   <p>Forkable modular agent rules with 1-step assembly for local AI coding assistants.</p>
@@ -26,6 +27,7 @@
     <li><a href="#installation">Installation</a></li>
     <li><a href="#usage">Usage</a></li>
     <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#changelog">Changelog</a></li>
     <li><a href="#contact">Contact</a></li>
   </ol>
 </details>
@@ -156,6 +158,12 @@ Add a license file if you want this repository to be reusable by others. Pull re
 
 <p align="right">(<a href="#readme-top">back to top</a>)</p>
 
+## Changelog
+
+Notable changes are recorded in the docs changelog: https://docs.devcentr.org/agent-rules/changelog.html
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
 ## Contact
 
 DevCentr.org - support@devcentr.org

diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
@@ -1,3 +1,8 @@
 * xref:index.adoc[Overview]
 * xref:usage.adoc[Usage]
+* xref:assembly.adoc[Assembly]
+* xref:profiles.adoc[Profiles]
 * xref:architecture.adoc[Architecture]
+* xref:modules-reference.adoc[Module reference]
+* xref:troubleshooting.adoc[Troubleshooting]
+* xref:changelog.adoc[Changelog]
diff --git a/docs/modules/ROOT/pages/assembly.adoc b/docs/modules/ROOT/pages/assembly.adoc
@@ -0,0 +1,55 @@
+= Assembly
+
+Agent rules assemble in one batched read when the harness has filesystem access.
+
+== Entry points
+
+[cols="1,2"]
+|===
+| File | When to use
+
+| `RULES.md`
+| Paste into an app's system prompt or custom instructions. Fill the Constants block at the top before saving.
+
+| `MAIN.md`
+| Modular assembly file when you want explicit parallel-read instructions and optional module gating (documentation, Antora, app architecture).
+
+| rules-manager
+| Compose global + machine sections into `$CODE_ROOT/agent-rules.composed.md` with file watching. https://github.com/dev-centr/rules-manager[`dev-centr/rules-manager`]
+|===
+
+== Parallel read set (MAIN.md)
+
+When `$AGENT_RULES_PATH` points at this clone, the agent reads **simultaneously**:
+
+1. `profiles/<infer-profile-name>.md`
+2. `general/global.md`
+3. `general/environment.md`
+4. `general/<windows|mac|linux>.md` (from profile `ENVIRONMENT` or host OS)
+5. `general/creator.md`
+6. `general/folder-schema.md`
+
+Conditionally (task-gated in `MAIN.md`):
+
+* `general/documentation.md` — authoring or publishing docs
+* `general/antora-docs-sites.md` — Antora sites, playbooks, hub wiring
+* `general/readme-layout.md` — GitHub-facing README layout
+* `general/app-architecture.md` — building or shipping applications
+
+Plus **`$CODE_ROOT/MEMORIES.md`** for workstation facts.
+
+== Why one step
+
+Local harnesses (Cursor, Windsurf, VS Code agents) support native file reads. Batching avoids:
+
+* Multi-turn ping-pong between modules
+* CLI `cat` truncation on large rule sets
+* Partial context when the agent stops after the first file
+
+== Paste-only fallback
+
+If the host cannot read the filesystem, `RULES.md` obligations are the only source. Fill Constants manually; you lose modular depth until filesystem access is available.
+
+== Dev-Centr product automation
+
+When the **Dev-Centr application** acts on behalf of the user, load https://github.com/dev-centr/devcentr-agent-rules[`devcentr-agent-rules`] instead of this repository. See xref:architecture.adoc[Architecture].
diff --git a/docs/modules/ROOT/pages/changelog-details/2026-03-23 - initial-forkable-rules.adoc b/docs/modules/ROOT/pages/changelog-details/2026-03-23 - initial-forkable-rules.adoc
@@ -0,0 +1,26 @@
+= 2026-03-23 – Initial forkable rules and 1-step assembly
+
+== Initial repository
+
+Canonical forkable agent rules and profiles for Dev-Centr coding assistants.
+
+Structure:
+
+* `general/` — portable rule modules (global, environment, OS layers, creator, folder-schema, documentation).
+* `profiles/` — machine constants templates (`CODE_ROOT`, `ENVIRONMENT`, optional `GITHUB_USER`, `ISSUES_REPO`).
+* `RULES.md` — agent-directed preamble; commands 1-step assembly.
+* `MAIN.md` — modular assembly with parallel file reads.
+
+== OS layers
+
+Split platform specifics into `general/windows.md`, `general/mac.md`, `general/linux.md`. Profile constant `ENVIRONMENT` selects the active layer.
+
+== 1-step assembly
+
+Optimized for local harnesses with filesystem access: agent batches semantic reads of profile + general modules in one turn instead of sequential CLI `cat` (avoids truncation and ping-pong).
+
+== README
+
+* Profile constants table.
+* Full clone vs paste-only setup paths.
+* Clarified human (README) vs agent (`RULES.md`) audience.
diff --git a/...les/ROOT/pages/changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc b/...les/ROOT/pages/changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc
@@ -0,0 +1,13 @@
+= 2026-03-31 – MAIN.md entrypoint and MEMORIES clarification
+
+== MAIN.md modular entrypoint
+
+`MAIN.md` became the modular context-assembly file listing parallel reads from `profiles/` and `general/`. `RULES.md` remains the consolidated paste preamble for apps without filesystem access.
+
+== MEMORIES location
+
+Documented **`$CODE_ROOT/MEMORIES.md`** as the single workstation memory file:
+
+* Gitignored; never committed.
+* Per-repo `MEMORIES.md` deprecated for project facts (use `AGENTS.md` + docs).
+* Format template: `MEMORIES.example.md` in this repository.
diff --git a/...ules/ROOT/pages/changelog-details/2026-08-03 - software-product-essentials.adoc b/...ules/ROOT/pages/changelog-details/2026-08-03 - software-product-essentials.adoc
@@ -0,0 +1,7 @@
+= 2026-08-03 – Software Product Essentials pointer
+
+Added `general/app-architecture.md` directing agents to the general-knowledge **Software Product Essentials** hub when scaffolding, building, shipping, or packaging applications.
+
+Covers About/build info, debug dump, Windows auto-update, installers, and CI release pipelines as core product architecture — not polish.
+
+Cross-reference: `general-knowledge` → `software-product-essentials.adoc`.
diff --git a/.../ROOT/pages/changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc b/.../ROOT/pages/changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc
@@ -0,0 +1,25 @@
+= 2026-08-06 – Antora org policy and README layout rules
+
+== Antora org policy
+
+Added `general/antora-docs-sites.md`:
+
+* One Antora site per org with a hub (Dev-Centr → https://docs.devcentr.org).
+* Product repos keep `docs/` close to code; wire into hub playbook — do not publish secondary per-repo Antora sites on GitHub Pages.
+* Actively deduplicate errant standalone Antora Pages deployments.
+
+Referenced from `general/documentation.md` and `RULES.md`.
+
+== README layout
+
+Expanded `general/readme-layout.md` with Best-README adapted patterns:
+
+* HTML `<a href><img>` badges inside centered headers (GitHub AsciiDoc/Markdown centering trap).
+* Role-grouped Built With sections.
+* Tier guidance (full vs simplified vs skip).
+
+== Other rule updates
+
+* Creator rules: SDLang in-stack; KDL greenfield; reject Extended SDL/XDL.
+* Ported sync-before-work habit into global rules and `.cursor/rules/`.
+* rules-manager path documentation in README installation section.
diff --git a/.../pages/changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc b/.../pages/changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc
@@ -0,0 +1,21 @@
+= 2026-08-08 – Antora docs and personal-reference cleanup
+
+== Summary
+
+Introduced an Antora documentation component and removed upstream personal-repository references so the canonical repo reads as org-neutral forkable content.
+
+== Documentation added
+
+* `docs/antora.yml` — component metadata (`agent-rules`, start page `ROOT:index.adoc`).
+* `docs/modules/ROOT/pages/index.adoc` — overview (what this repo is / is not).
+* `docs/modules/ROOT/pages/usage.adoc` — clone, paste, rules-manager, MEMORIES.
+* `docs/modules/ROOT/pages/architecture.adoc` — relationship to `devcentr-agent-rules` and workstation memory.
+
+== Text cleanup
+
+* `README.md`, `CONTRIBUTING.md`, `RULES.md` — replaced personal fork examples with generic guidance.
+* README adds hub docs URL; personal constants stay in the user's fork.
+
+== Hub wiring
+
+`dev-centr/docs` playbook already includes `https://github.com/dev-centr/agent-rules.git` with `start_path: docs`. Published URL: https://docs.devcentr.org/agent-rules/
diff --git a/docs/modules/ROOT/pages/changelog.adoc b/docs/modules/ROOT/pages/changelog.adoc
@@ -0,0 +1,42 @@
+= Changelog
+
+Notable changes to agent-rules rules, profiles, and documentation. Entries are in reverse chronological order. Each entry links to a detailed changelog article where helpful.
+
+== 2026-08-08 – Antora docs and personal-reference cleanup
+
+* Added Antora component under `docs/` (overview, usage, architecture).
+* Removed personal-repo references from README, CONTRIBUTING, and RULES.md; generic fork guidance instead.
+* Wired into https://docs.devcentr.org/agent-rules/[Dev-Centr docs hub] (playbook already lists this component).
+
+See xref:ROOT:changelog-details/2026-08-08 - antora-docs-and-personal-ref-cleanup.adoc[Detailed changelog].
+
+== 2026-08-06 – Antora org policy and README layout rules
+
+* `general/antora-docs-sites.md`: one Antora site per org; wire components into hub; dedupe errant GitHub Pages sites.
+* `general/readme-layout.md`: Best-README adapted layout (HTML badges, centered header, role-grouped Built With).
+* SDLang in-stack preference; KDL greenfield; ban Extended SDL/XDL in creator rules.
+* Sync-before-work habit and rules-manager path documentation.
+
+See xref:ROOT:changelog-details/2026-08-06 - antora-policy-and-readme-layout.adoc[Detailed changelog].
+
+== 2026-08-03 – Software Product Essentials pointer
+
+* `general/app-architecture.md` points agents at general-knowledge Software Product Essentials when building apps.
+
+See xref:ROOT:changelog-details/2026-08-03 - software-product-essentials.adoc[Detailed changelog].
+
+== 2026-03-31 – MAIN.md entrypoint and MEMORIES clarification
+
+* Reorganized into `MAIN.md` modular assembly entrypoint and consolidated `RULES.md` preamble.
+* Clarified `$CODE_ROOT/MEMORIES.md` as the canonical workstation memory location.
+
+See xref:ROOT:changelog-details/2026-03-31 - main-entrypoint-and-memories.adoc[Detailed changelog].
+
+== 2026-03-23 – Initial forkable rules and 1-step assembly
+
+* Initial commit: canonical forkable agent rules for Dev-Centr.
+* OS layers split (`general/windows.md`, `general/mac.md`, `general/linux.md`); `ENVIRONMENT` profile constant.
+* 1-step assembly architecture in `RULES.md` / `MAIN.md` (parallel batched reads).
+* README profile constants table; human vs agent audience clarified.
+
+See xref:ROOT:changelog-details/2026-03-23 - initial-forkable-rules.adoc[Detailed changelog].
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
@@ -14,6 +14,14 @@ https://docs.devcentr.org/agent-rules/
 * Shared end-user / project agent instructions (`RULES.md`, `general/`, `profiles/`)
 * Assembled locally (paste or via rules-manager)
 
+== Quick links
+
+* xref:usage.adoc[Usage] — clone, paste, MEMORIES
+* xref:assembly.adoc[Assembly] — 1-step parallel read architecture
+* xref:profiles.adoc[Profiles] — machine constants
+* xref:troubleshooting.adoc[Troubleshooting] — common pitfalls
+* xref:changelog.adoc[Changelog] — notable changes
+
 == What this is not
 
 * **Not** Dev-Centr product automation — that lives in https://github.com/dev-centr/devcentr-agent-rules[`devcentr-agent-rules`]

diff --git a/docs/modules/ROOT/pages/modules-reference.adoc b/docs/modules/ROOT/pages/modules-reference.adoc
@@ -0,0 +1,68 @@
+= Module reference
+
+`general/` modules are Markdown rule files the agent loads during assembly.
+
+== Always loaded
+
+[cols="1,2"]
+|===
+| Module | Covers
+
+| `global.md`
+| Core habits: plain language, gitignore allow-list, sync-before-work, Python venv/uv, build-failure policy, changelogs.
+
+| `environment.md`
+| Cross-platform tooling defaults (Node/pnpm, git hosts, path refresh patterns).
+
+| `windows.md` / `mac.md` / `linux.md`
+| OS-specific shell, paths, and tooling (selected by `ENVIRONMENT`).
+
+| `creator.md`
+| Owned-project rules: transfers, issues workflow, SDL/KDL config preference, changelog structure.
+
+| `folder-schema.md`
+| Code hive layout (`$CODE_ROOT/<host>/<owner>/<repo>`, forks, clones).
+|===
+
+== Task-gated (MAIN.md)
+
+[cols="1,2"]
+|===
+| Module | Load when
+
+| `documentation.md`
+| Authoring or publishing project documentation (Diátaxis, Antora pointers).
+
+| `antora-docs-sites.md`
+| Antora sites, org hub policy, deduplicating errant Pages deployments.
+
+| `readme-layout.md`
+| Creating or revising GitHub-facing READMEs (Best-README adapted).
+
+| `app-architecture.md`
+| Scaffolding, building, shipping, packaging applications.
+|===
+
+== Repository files
+
+[cols="1,2"]
+|===
+| File | Audience
+
+| `README.md`
+| Humans — install, usage, architecture diagram, contributing.
+
+| `RULES.md`
+| Agents — consolidated preamble; paste into app rules field.
+
+| `MAIN.md`
+| Agents with filesystem access — modular parallel assembly.
+
+| `MEMORIES.example.md`
+| Template for `$CODE_ROOT/MEMORIES.md` format.
+
+| `CONTRIBUTING.md`
+| Humans — where portable vs fork-only changes go.
+|===
+
+Source files live at the repository root and under `general/`; this page is an index for navigation.
diff --git a/docs/modules/ROOT/pages/profiles.adoc b/docs/modules/ROOT/pages/profiles.adoc
@@ -0,0 +1,37 @@
+= Profiles
+
+Machine-specific constants live in `profiles/*.md`. The agent reads **one** profile during context assembly (inferred from filename or your configuration).
+
+== Template files
+
+| File | Purpose |
+|------|---------|
+| `profiles/my-desktop.md` | Desktop workstation template |
+| `profiles/my-laptop.md` | Laptop template |
+
+Rename to match how you use the machine (for example `desktop.md`) and point your agent at that name.
+
+== Constants
+
+```text
+CODE_ROOT = <your-code-root>              # e.g. Z:\code or /home/you/src
+GITHUB_USER = <your-github-username>      # optional; path examples
+ISSUES_REPO = <path-to-.issues-repo>      # optional; omit if unused
+ENVIRONMENT = windows                     # windows | mac | linux
+```
+
+| Constant | Required? | Purpose |
+|----------|-----------|---------|
+| `CODE_ROOT` | Yes | Root directory for Git clones (see xref:../folder-schema.adoc[folder schema]). |
+| `ENVIRONMENT` | Yes | Selects `general/windows.md`, `general/mac.md`, or `general/linux.md`. |
+| `GITHUB_USER` | No | Username for path examples and org layouts. |
+| `ISSUES_REPO` | No | Path to your `.issues` workflow repository. |
+
+== Fork vs upstream
+
+* **Portable rules** → pull requests to https://github.com/dev-centr/agent-rules[`dev-centr/agent-rules`].
+* **Personal constants, org examples, private paths** → your fork only; never upstream personal workstation facts.
+
+== Workstation memory
+
+Profile constants are not the same as `$CODE_ROOT/MEMORIES.md`. Profiles hold stable machine identity; MEMORIES holds discovered facts (PATH gaps, tool locations) with usage counters. See xref:troubleshooting.adoc#memories[troubleshooting].