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.

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
            ├── 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
            │   ├── examples.md
            │   ├── docs-maintenance.md
            │   └── image-placeholders.md
            └── user-guide/
                ├── README.md
                ├── installation.md
                ├── getting-started.md
                ├── templates.md
                ├── editor/
                │   ├── README.md
                │   ├── template-editor.md
                │   └── blocks.md
                ├── use-cases/
                │   ├── README.md
                │   ├── how-to-configure.md
                │   ├── opengraph.md
                │   ├── sidebar-image.md
                │   ├── minimal.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

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.

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_active_use_case_classes`
`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/`

Edit markdown in src/content/docs/ (user-guide/, codebase/, and README.md). 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