Documentation maintenance

How to keep docs/ aligned with the plugin. Use the Cursor slash command /update-docs (see .cursor/commands/update-docs.md) to run this checklist in a session.

Releases: /do-release runs the full /update-docs workflow first (Step 0 on develop) before version bump and tagging — not a shortened grep-only pass.

Target tree

Markdown pages live under docs/src/content/docs/ (Starlight content collection):

docs/
├── package.json
├── astro.config.mjs
├── docs.config.mjs
└── src/
    └── content/
        └── docs/
            ├── README.md
            ├── changelog.md            # generated from root CHANGELOG.md via sync:changelog
            ├── roadmap.md              # generated from knowledge/roadmap via sync:roadmap
            ├── codebase/
            │   ├── README.md
            │   ├── use-cases-and-output-profiles.md   # canonical architecture
            │   ├── php-backend.md
            │   ├── rest-api.md
            │   ├── hooks-and-extension-points.md
            │   ├── blocks-and-editor.md
            │   ├── block-bindings.md
            │   ├── examples.md
            │   ├── docs-maintenance.md
            │   └── image-placeholders.md
            └── user-guide/
                ├── README.md
                ├── installation.md
                ├── getting-started.md
                ├── settings/
                │   ├── README.md
                │   └── options-reference.md   # generated via sync:settings-docs
                ├── templates.md
                ├── editor/
                │   ├── README.md
                │   ├── template-editor.md
                │   └── blocks.md
                ├── use-cases/
                │   ├── README.md
                │   ├── how-to-configure.md
                │   ├── opengraph.md
                │   ├── featured-image.md
                │   ├── sandbox.md
                │   └── custom-use-case.md
                ├── caching/
                │   ├── README.md
                │   └── clearing-cache.md
                ├── faq.md
                └── troubleshooting.md

Policy

Situation	Action
Claim not in `includes/`, `src/`, `schemas/`, or root `README.md`	Delete the doc or section (no archive, no redirect stubs)
Codebase reference drift	Sync to code; remove wrong paragraphs entirely
User-facing workflow	Rewrite `user-guide/` from root `README.md`
Product naming / UX only	Consult `knowledge/` — not for API facts
Release notes / changelog	Edit root `CHANGELOG.md` only (source of truth); run `npm run sync:changelog` before commit (regenerates `changelog.md` here)
Planned features / roadmap	Edit `knowledge/roadmap/` only (source of truth); run `npm run sync:roadmap` before commit (rebuilds root `ROADMAP.md` and `roadmap.md` here)
Settings screen fields	Edit `schemas/options.php` and `schemas/templates.php`; run `npm run sync:settings-docs` (regenerates `user-guide/settings/options-reference.md`)

Starlight page titles: Use title in frontmatter for the visible page headline (browser tab, OG title, sidebar). Do not add a matching # heading in the body — Starlight already renders the title as <h1>. Start page content with intro copy or ## sections.

Site chrome

The header version badge (v{semver} next to the logo) reads the root package.json version at build time via docs/src/components/SiteTitle.astro. When releasing the plugin, bump that version (and coverkit.php / README stable tag); the badge updates on the next npm run docs:build or deploy.

User guide order is explicit in docs/astro.config.mjs (onboarding → settings → templates → overview → editor → Open Graph → use cases → placeholders → caching → help). Do not rely on autogenerate for those folders—it sorts pages alphabetically. When adding a user-guide page, insert it in the matching group in that file.

Settings reference (generated)

Source of truth: schemas/options.php (coverkit_options) and schemas/templates.php (preset item shape for coverkit_presets).
Generator: npm run sync:settings-docs (runs automatically before docs:build / docs:dev).
Output: user-guide/settings/options-reference.md — do not edit by hand; change the schema files instead.
Intro copy for the Settings section: user-guide/settings/README.md (hand-edited).

Do not maintain separate docs/api/, docs/hooks/, docs/classes/, docs/migration/, or docs/chat-logs/.

Code truth sources

use-cases-and-output-profiles.md — use case architecture
Plugin README on GitHub — site-owner features and quick start
coverkit.php, includes/class-coverkit-*.php, includes/functions.php
includes/class-coverkit-rest.php — REST routes
src/editor/use-cases/ — editor mapping UI

Extract routes:

rg 'register_rest_route' includes/class-coverkit-rest.php

Extract hooks:

rg "do_action\('coverkit_|apply_filters\('coverkit_" includes/

Stale-term grep (must be zero under `docs/`)

Pattern	Note
`coverkit_use_cases` without leading `_`	Meta key is `_coverkit_use_cases`
`register_coverkit_use_case`	Use `coverkit_register_use_case()`
`inject_opengraph_meta`, `sync_active_use_cases`, `boot_wordpress_outputs`	Removed; OG via `Open_Graph_Image_Use_Case`
`coverkit_active_use_cases` (template ID lists)	Loader option is `coverkit_usecases`
`Data_Collector`, `Handler_Registry`, `generate_from_template`	Removed concepts
`Renderer::___generate`	Use `Renderer::generate()`
`includes/handlers/`, `includes/runtime/`	Removed directories
`docs/api/`, `docs/hooks/`, `stale-docs-audit`, `chat-logs/`	Deleted paths

Image placeholders

When a doc needs a screenshot that does not exist yet:

Use descriptive Markdown alt text (what the image should show).
Add a *Placeholder: …* caption line.
Log the entry in image-placeholders.md with status placeholder.

Do not add decorative placeholders.

Published docs

User guide and codebase reference in docs/ are built and published to docs.coverkit.com via the Astro + Starlight app in this folder (package.json, astro.config.mjs, src/).

Task	Command
Local preview	`npm run docs:dev` (from plugin repo root) or `npm run dev` in `docs/`
Production build	`npm run docs:build` or `npm run build` in `docs/`
Sync changelog	`npm run sync:changelog` (from plugin repo root)
Sync roadmap	`npm run sync:roadmap` (from plugin repo root)

Edit markdown in src/content/docs/ (user-guide/, codebase/, and README.md). Do not hand-edit changelog.md — it is generated from root CHANGELOG.md. Do not hand-edit roadmap.md or root ROADMAP.md — both are generated from knowledge/roadmap/. Internal links may use GitHub-style .md paths (for example user-guide/getting-started.md); the docs build rewrites them to site URLs automatically. Pushes to main or develop that touch docs/ or the docs deploy workflow trigger a Cloudflare Pages deploy automatically.

Branching

For commits that change docs, create feature/docs-sync-YYYY-MM-DD from the default branch unless the user says “no branch” or “on develop”.

Verification before done

Stale-term grep returns no matches in docs/
No markdown links to deleted paths (grep repo for docs/api, docs/hooks, field-mapping-system, etc.)
rest-api.md lists every register_rest_route in class-coverkit-rest.php
docs/src/content/docs/README.md links only to files that exist
Every docs/assets/images/... placeholder has a row in image-placeholders.md