Infra: docs enablement first attempt

.claude/commands/docs/review-doc.md

@@ -0,0 +1,36 @@
+---
+description: Self-review a docs change against the style rubric + deterministic gates before opening a PR
+argument-hint: (no args — reviews changed docs on the current branch)
+---
+
+<!--
+FIRST CUT. The QUALITY RUBRIC below is the docs-team lane. The MECHANICS
+(how it runs Vale / links / build / the model) are for the automation + AI folks to design and change freely.
+-->
+
+# /docs:review-doc — self-review before you open a PR
+
+Purpose: a contributor runs this on their changed docs so problems get caught *before* a human review — keeping the docs-team gate fast.
+
+## What it checks
+
+**Deterministic (wire to existing tooling):**
+- **Vale** — style + terminology, on changed files only
+- **Links** — relref / shortcode paths resolve (reuse the shortcode-path hook)
+- **Build** — `hugo` builds clean
+- **Frontmatter** — present + complete: `title`, `linkTitle`, `description`, `weight`, `categories`
+
+**AI rubric (the judgment layer — the part that needs a model):**
+- **Voice:** addresses "you," active voice, present tense; no marketing words ("seamless," "powerful," "simply")
+- **Structure:** matches the template shape for the doc type; sentence-case headings; verb-first task titles; one action per step
+- **Coverage / IA:** does this duplicate or belong inside an existing page? → suggest fold-in or cross-links
+- **Placeholders & security:** code uses `<angle-bracket>` placeholders; no real credentials, PII, IPs, or keys
+- **Minimalism:** flag intro fluff, redundancy, and jargon
+
+## Output
+A per-item checklist (pass / fix), each fix with a line pointer and a concrete suggestion, ending with a **"ready for review?"** verdict.
+
+## Mechanics (teammate lane — stub, design freely)
+- Scope to changed files via `git diff` (the `/edit` skill already does this — reuse it).
+- Model: per the plan's model strategy (Opus for the rubric gate; Haiku for the deterministic pass). <!-- TODO: confirm -->
+- Follows Andy's `/docs:*` command pattern.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,16 @@
+## Summary
+
+<!-- What changed and why. -->
+
+## Docs checklist
+
+- [ ] **Coverage checked** — extended or cross-linked existing docs where possible (no orphan or duplicate page)
+- [ ] Used the right **template** (task / concept / reference)
+- [ ] **Frontmatter complete** and the page **builds clean** (CI)
+- [ ] **Technically accurate**
+- [ ] Follows the [style conventions](../CLAUDE.md)
+
+<!-- Not a content change (tooling / config / CI only)? Instead of the above, check this: -->
+- [ ] **No docs needed** (no user-facing change)
+
+New to contributing docs? See [CONTRIBUTING.md](../CONTRIBUTING.md).

AGENTS.md

@@ -0,0 +1,5 @@
+# AGENTS.md
+
+This repo's writing conventions for AI tools live in [CLAUDE.md](./CLAUDE.md). Codex and any other agent working here should read and follow it — it's the same base style (Google developer documentation style), voice, structure, terminology, frontmatter, and coverage-aware authoring rules that human contributors follow.
+
+For the contributor workflow (golden path, templates, self-check, the PR bar), see [CONTRIBUTING.md](./CONTRIBUTING.md).

CLAUDE.md

@@ -0,0 +1,57 @@
+# Redis docs — writing conventions (humans + AI)
+
+Base style: **Google developer documentation style**; fall back to the **Microsoft Writing Style Guide** where Google is silent. Follow these on every docs change. AI tools working in this repo inherit these rules automatically.
+
+## Voice & tone
+
+- Address the reader as **"you."** Use **present tense** and **active voice**.
+- Be direct and friendly. **No marketing tone** — avoid "best-in-class," "seamless," "powerful," "simply," "just," "easily."
+- **Minimalism:** cut intro fluff, get to the action, say what's needed and stop.
+
+## Structure
+
+- **Sentence-case headings** ("Configure a database," not "Configure A Database").
+- **Task/procedure titles start with a verb** ("Create a role," "Enable auditing").
+- Follow the reader's **real workflow, in order.** Number sequential steps; **one action per step.**
+- Don't stack notes back-to-back. **No directional language** ("above/below/on the left") — link to the thing instead.
+
+## Terminology & accessible language
+
+- Use official **product / feature / UI names** exactly. The ones writers most often get wrong:
+  - **Redis Software** (standalone) and **Redis Software for Kubernetes** (the operator-based product) — not "Redis Enterprise" in prose.
+  - **Redis Feature Form** on first use per page, then **Feature Form** — never "Featureform."
+  - In prose, write **databases**, not "BDB"/"BDBs." The literal `bdb` API value and the `REC`/`REDB` abbreviations stay as-is, and CRD identifiers (`RedisEnterpriseCluster`, `RedisEnterpriseDatabase`, `RedisEnterpriseUser`) keep their exact casing.
+- Prefer plain, inclusive terms: **replica** (not slave/master), **turn off** (not disable), **end** (not kill), **allowlist/denylist**.
+- Spell out an acronym on first use.
+
+## Links
+
+- **Descriptive link text** ("see the [database configuration reference]") — never "click here" or a bare URL.
+- Internal links use the relref shortcode: `{{< relref "/operate/rs/..." >}}`.
+
+## Frontmatter (every page)
+
+```yaml
+---
+title: <full page title>
+linkTitle: <short nav title>
+description: <one sentence; used in search + nav>
+weight: <order within its section>
+categories: [docs, operate]   # match the section
+---
+```
+
+## Coverage-aware authoring — do this FIRST
+
+- Before creating a page, **check whether the topic already exists.** Prefer to **fold into / extend / cross-link** an existing page over making a new one.
+- Create a new page only when it's genuinely new — and **never leave it orphaned**: link it from its section index.
+
+## Code & security
+
+- In code and command examples, use **angle-bracket placeholders** — `<your-cluster-name>` — never real values. (This is the one exception to "match the UI exactly.")
+- **Never** include real credentials, PII, customer IPs, or SSH keys.
+
+## Before opening a PR
+
+- Run the self-check (`/docs:review-doc` once it exists); at minimum run **Vale**, the **link check**, and a **Hugo build**.
+- Confirm frontmatter is complete and the page is linked from its section.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Redis docs
+
+Thanks for helping keep our docs accurate and useful. Docs are part of a feature's definition of done — this guide is everything you need to contribute with minimal friction.
+
+> **Fastest path:** check for an existing page → copy a template → draft with AI in the repo (it already knows our style) → run the self-check → open a PR. Details below.
+
+## Do I need to write docs for this change?
+
+- **No user-facing change** (refactor, internal, tests, CI) → **no docs.** Note "no docs needed" on your PR.
+- **New product or feature area** → **yes** — start with the docs team on where it lives before writing.
+- **New feature, behavior, or setting** → **yes** — a short task or concept page.
+- **New or changed API / config field** → **update the reference** (often auto-generated — check with the docs team first).
+
+When unsure, ask in **#docs** — a 30-second question beats a missed page.
+
+## The golden path
+
+Each step names the actual action — a prompt to the AI, a command, or a click.
+
+1. **Check what already exists.** Ask Claude or Codex in the repo: *"Is there already a page about `<topic>` under `content/`? If so, where, and should I add to it instead of making a new one?"* — or in the editor, `Cmd/Ctrl+Shift+F` across `content/` for the topic, and check the search box on the docs site. If there's a related page, add to it instead of creating a new one.
+2. **Create a branch and stamp out the template.** From an up-to-date `main`, `git checkout -b DOC-xxxx` (or ask the AI to). Then generate the page from the right archetype: `hugo new content/<path>/<page>.md --kind task` (or `concept` / `reference`) — that drops in the template with frontmatter and section scaffolding. Open the new file.
+3. **Draft with AI in the repo.** In the Claude Code (or Codex) panel, paste your source material and ask it to draft — *"Draft this task page from these notes: `<spec>`."* It reads the committed `CLAUDE.md` automatically, so the draft comes out in our voice, naming, and shortcodes.
+4. **Self-check and preview.** Run `/docs:review-doc` — or manually: `vale content/<path>`, the link check, and `make serve`, then open `http://localhost:1313` to eyeball the page. Fix what's flagged, then actually run the steps or commands the page describes to confirm they work.
+5. **Open a PR.** Commit and push the branch (or tell the AI "commit and push this branch"), then open a PR on GitHub — the PR template auto-loads the docs checklist, so fill it in and request a reviewer. A docs teammate reviews for voice, structure, and placement, then merges. Merging to `main` publishes to the live site automatically — so review happens *before* merge, and changes to sensitive areas (security, release notes) always get a human reviewer first.
+
+## Templates
+
+Per-type starting points live in **`archetypes/`**: `task` (how-to), `concept` (what/why), `reference` (fields/options). To use one, run `hugo new content/<path>/<page>.md --kind task` (or `concept` / `reference`), or copy the archetype file into place. Each has inline guidance — delete the comments before publishing.
+
+## Style
+
+We follow Google developer style. The full rules live in the committed **`CLAUDE.md`**, so AI drafting in the repo inherits them automatically. The short version: write to "you," active voice, present tense; sentence-case headings; verb-first task titles; angle-bracket `<placeholders>` in code; descriptive link text; no marketing language.
+
+To check a draft against the style, run `/docs:review-doc`, or ask the AI: *"Check this page against our style rules in `CLAUDE.md` and flag anything off."*
+
+## What makes a PR ready for review (the bar)
+
+A docs teammate edits *from* your draft — they can't rewrite it from scratch. Before you request review, make sure it:
+
+- [ ] Uses the right **template** (structure is there)
+- [ ] Is **placed sensibly** — folded into or cross-linked with related docs, not an orphan or duplicate
+- [ ] **Builds clean**, with complete frontmatter (CI will tell you)
+- [ ] Is **technically accurate — and you've tested it** (followed the steps / ran the commands / checked the output), not just written it — the part only you can guarantee
+
+Run `/docs:review-doc` before you open the PR — it checks most of these at once (template, placement, build, frontmatter). The last one, testing it, is the part only you can do.
+
+If it's missing these, we'll send it back with a pointer — not to be difficult, but because that bar is what lets a small docs team keep up.
+
+## Who owns what
+
+**You** own technical accuracy and a solid first draft. **The docs team** owns voice, structure, and where it lives in the docs.
+
+## Getting help
+
+Ask in **#docs**, or tag a docs teammate on your PR.

archetypes/concept.md

@@ -0,0 +1,36 @@
+---
+title: "<Noun phrase — e.g. 'Database-scoped roles'>"
+linkTitle: "<Short nav label>"
+description: "<One sentence: what this concept is.>"
+weight: 10
+categories: ["docs", "operate"]
+---
+
+<!--
+CONCEPT PAGE — explains what something is, how it works, and why it matters.
+• NOT step-by-step — link to task pages for the how-to.
+• Delete these comments before publishing.
+• Write to "you," present tense, plain language. No marketing.
+• COVERAGE CHECK FIRST: if a related concept page exists, extend it instead of creating a new one.
+-->
+
+One or two sentences: what this is and why the reader should care.
+
+## How it works
+
+<!-- Explain the model or behavior. A diagram or short example helps. Keep it conceptual, not procedural. -->
+
+## <Key components / terms>
+
+<!-- Break out the important pieces. Define each term on first use. -->
+
+## When to use it
+
+<!-- When it applies, tradeoffs, and any limits. Optional — remove if not needed. -->
+
+## Related
+
+<!-- Point to the task page(s) that show how to actually do it. -->
+
+- [<Related task>]({{< relref "/operate/..." >}})
+- [<Related reference>]({{< relref "/operate/..." >}})

archetypes/reference.md

@@ -0,0 +1,38 @@
+---
+title: "<Thing being documented — e.g. 'REDB configuration options'>"
+linkTitle: "<Short nav label>"
+description: "<One sentence: what this reference covers.>"
+weight: 10
+categories: ["docs", "operate", "reference"]
+---
+
+<!--
+REFERENCE PAGE — factual lookup: fields, options, parameters, syntax, values, defaults.
+• Comprehensive and scannable, not narrative.
+• Delete these comments before publishing.
+• NOTE: API / CRD references are often AUTO-GENERATED (k8s_apis_sync, REST-object sync) —
+  check with the docs team before hand-authoring one, or your page will be overwritten.
+• COVERAGE CHECK FIRST: extend the existing reference if there is one.
+-->
+
+One sentence on what this reference covers and where it applies.
+
+## <Category of fields / options>
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `<field>` | `<type>` | `<default>` | <What it does; note valid values or constraints.> |
+| `<field>` | `<type>` | `<default>` | <...> |
+
+## Syntax
+
+<!-- If applicable: command syntax or an example object, with angle-bracket placeholders. Remove if not needed. -->
+
+```sh
+<command> <argument> --<flag> <value>
+```
+
+## Related
+
+- [<Related concept>]({{< relref "/operate/..." >}})
+- [<Related task>]({{< relref "/operate/..." >}})

archetypes/task.md

@@ -0,0 +1,48 @@
+---
+title: "<Verb + object — e.g. 'Enable command auditing'>"
+linkTitle: "<Short nav label>"
+description: "<One sentence: what the reader accomplishes on this page.>"
+weight: 10
+categories: ["docs", "operate"]
+---
+
+<!--
+TASK PAGE — a how-to that walks the reader through accomplishing ONE goal.
+• Delete these comments before publishing.
+• Write to "you," present tense, action-oriented.
+• COVERAGE CHECK FIRST: does this belong on an existing page? If so, add it there instead of creating a new page.
+• TEST IT BEFORE PR: actually follow these steps / run these commands and confirm the output — a doc that builds is not the same as a doc that works.
+-->
+
+Brief intro — 1–2 sentences on what this task does and when you'd do it. No history or marketing.
+
+## Prerequisites
+
+<!-- What must be true before starting. Omit this section if there are none. -->
+
+- <e.g. A running Redis Enterprise cluster>
+- <e.g. Cluster admin permissions>
+
+## <Verb-first step group — e.g. "Configure the setting">
+
+<!-- Number sequential actions, one action per step. Show commands/UI with placeholders. -->
+
+1. <First action.>
+
+   ```sh
+   <command with-placeholders>
+   ```
+
+2. <Next action.>
+
+## Verify
+
+<!-- How the reader confirms it worked: expected output, a status, a UI state. -->
+
+<Describe the expected result.>
+
+## Next steps
+
+<!-- Optional. Link related tasks with relref. Remove if not needed. -->
+
+- [<Related task>]({{< relref "/operate/..." >}})