From 575e36f211d771ba1c6423315b69e290b585d55c Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Sat, 8 Aug 2026 05:31:55 -0500 Subject: [PATCH 1/2] Expand README, Antora, and changelog agent rules from org docs automation notes. Co-authored-by: Cursor --- RULES.md | 8 ++++---- general/antora-docs-sites.md | 5 +++++ general/creator.md | 8 +++++--- general/documentation.md | 5 ++++- general/global.md | 2 ++ general/readme-layout.md | 32 +++++++++++++++++++++++++++----- 6 files changed, 47 insertions(+), 13 deletions(-) diff --git a/RULES.md b/RULES.md index f08a39c..0066803 100644 --- 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 header, org **Docs \| Org** badge → hub URL, CI badge when CI exists, TOC if >3 sections, role-grouped Built With, back-to-top). 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 index 76ae515..831cfbf 100644 --- 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 index 7edbb1a..2591d6e 100644 --- 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 index 66b9e23..ecc749e 100644 --- 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 index e3dac59..fba6e71 100644 --- 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 index c0f716e..13a17c3 100644 --- a/general/readme-layout.md +++ b/general/readme-layout.md @@ -2,11 +2,29 @@ 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/`). | + +## Required badges (org repos) + +For **organization** repositories that have a README (not personal-user profile repos unless they publish under an org docs hub): + +1. **Org docs badge** — Label reflects the org’s docs domain / brand, not “GitHub Pages”. Example look: **`Docs | Dev-Centr`**. Link to the **org Antora (or docs) hub** page for this component (e.g. `https://docs.devcentr.org//`), never to a secondary per-repo Pages Antora site. If the component is not wired yet, still point at the hub (or the intended hub path) and wire the playbook. +2. **CI/CD status badge** — Every repo with CI/CD (GitHub Actions, Netlify, Vercel, etc.) needs a status badge that opens the workflow/dashboard for that pipeline. + +Personal-user repos: skip the org docs badge 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* (docs hub page, CI run list, contributors graph, stargazers, issues, license blob, tech homepage). Never the shield image URL. 2. **Markdown inside `
`** — 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:** `…`. 3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `` 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,17 +35,21 @@ 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, linked shields (incl. org docs + CI when applicable), 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 `
` is fine on Markdown). ## Markdown header (required shape) ```markdown
+ Docs | Dev-Centr + CI Contributors Forks Stargazers @@ -51,7 +73,7 @@ Prefer keeping `README.adoc` when the repo is AsciiDoc-native **except** major u
``` -Omit license badge / demo / docs links when absent. Collapsible TOC via `
` is fine. +Omit license / demo / docs / CI badges when absent. Swap `Docs | Dev-Centr` and the docs URL for the owning org’s brand and hub. Collapsible TOC via `
` is fine when the README has more than three sections. ### Built With (outside the HTML header) From 71d503a7d6e50c68f9d757a4305096648d0a52c9 Mon Sep 17 00:00:00 2001 From: Ryan Johnson Date: Sat, 8 Aug 2026 05:43:31 -0500 Subject: [PATCH 2/2] Drop Docs/CI shield mandates; keep Explore-the-docs hub CTA style. Co-authored-by: Cursor --- README.md | 2 ++ RULES.md | 2 +- general/readme-layout.md | 19 ++++++++----------- 3 files changed, 11 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 14cde09..3dabe5f 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@

Agent Rules

Forkable modular agent rules with 1-step assembly for local AI coding assistants.

+ Explore the docs » +

Report Bug · Request Feature diff --git a/RULES.md b/RULES.md index 0066803..da305dd 100644 --- a/RULES.md +++ b/RULES.md @@ -42,7 +42,7 @@ - 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: centered header, org **Docs \| Org** badge → hub URL, CI badge when CI exists, TOC if >3 sections, 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/readme-layout.md b/general/readme-layout.md index 13a17c3..e389a3b 100644 --- a/general/readme-layout.md +++ b/general/readme-layout.md @@ -13,18 +13,17 @@ Do **not** batch-script README rewrites across repos. Hand-edit each file so sta | **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/`). | -## Required badges (org repos) +## Docs link (org repos) -For **organization** repositories that have a README (not personal-user profile repos unless they publish under an org docs hub): +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//`), 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. -1. **Org docs badge** — Label reflects the org’s docs domain / brand, not “GitHub Pages”. Example look: **`Docs | Dev-Centr`**. Link to the **org Antora (or docs) hub** page for this component (e.g. `https://docs.devcentr.org//`), never to a secondary per-repo Pages Antora site. If the component is not wired yet, still point at the hub (or the intended hub path) and wire the playbook. -2. **CI/CD status badge** — Every repo with CI/CD (GitHub Actions, Netlify, Vercel, etc.) needs a status badge that opens the workflow/dashboard for that pipeline. +**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 docs badge unless that user publishes a docs site you should link. +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* (docs hub page, CI run list, 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 `

`** — 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:** `…`. 3. **AsciiDoc `env-github` trap** — Do **not** strip `link=` under `ifdef::env-github[]`. Prefer HTML `` 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. @@ -35,7 +34,7 @@ Personal-user repos: skip the org docs badge unless that user publishes a docs s | Audience | Layout | |----------|--------| -| **User-facing / downstream** (apps, installable CLIs, public libs, product sites) | Full: centered header, linked shields (incl. org docs + CI when applicable), structured Built With, TOC when >3 sections, 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 | @@ -48,8 +47,6 @@ Include a TOC when the README has **more than three** sections (collapsible `
- Docs | Dev-Centr - CI Contributors Forks Stargazers @@ -61,7 +58,7 @@ Include a TOC when the README has **more than three** sections (collapsible ` project_description
- Explore the docs » + Explore the docs »

View Demo @@ -73,7 +70,7 @@ Include a TOC when the README has **more than three** sections (collapsible ` ``` -Omit license / demo / docs / CI badges when absent. Swap `Docs | Dev-Centr` and the docs URL for the owning org’s brand and hub. Collapsible TOC via `
` is fine when the README has more than three sections. +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 `
` is fine when the README has more than three sections. ### Built With (outside the HTML header)