Add review workflow infrastructure

.claude/skills/new-revision/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: new-revision
+description: Scaffold a new revision of an existing document by copying the latest version folder to a new version, setting the draft flag, and creating an appropriately-prefixed git branch for the review process.
+---
+
+# New Revision
+
+Scaffold a new revision of an existing document on the RMC documentation site. Copies the latest version folder to a new version directory, marks the document as draft, and creates a `docs/major/` or `docs/minor/` branch ready for the review workflow.
+
+**Arguments:** `$ARGUMENTS` — optional. If provided, use as hints for the prompts below (e.g., a document path or version number). Still confirm each value with the user before proceeding.
+
+## Step 1: Gather Information via Interactive Prompts
+
+Prompt the user for each value, one at a time. Show sensible defaults where possible. Do NOT proceed until all values are confirmed.
+
+### 1a — Document selection
+
+Ask: "Which existing document are you revising?"
+
+Read [static/versions/latestVersions.json](static/versions/latestVersions.json) and present the keys as a numbered list. The user picks one. The selected key is the `docBasePath` (e.g., `desktop-applications/lifesim/users-guide`).
+
+The corresponding value in the JSON is the `currentVersion` (e.g., `v1.0`).
+
+### 1b — Revision type
+
+Ask: "Is this a major revision or a minor revision?"
+
+- **Major revision** — substantial changes warranting a new major version. Branch prefix: `docs/major/`. Goes through Lane 2 (Peer → Lead Civil review).
+- **Minor revision** — smaller updates warranting a minor version bump. Branch prefix: `docs/minor/`. Goes through Lane 3 (Peer review only).
+
+### 1c — New version number
+
+Compute the default based on revision type:
+- Major: increment the major component, reset minor to 0 (e.g., `v1.0` → `v2.0`, `v1.5` → `v2.0`).
+- Minor: increment the minor component (e.g., `v1.0` → `v1.1`, `v1.5` → `v1.6`).
+
+Ask: "The new version will be `{newVersion}`. Is that correct, or would you like a different version number?"
+
+### 1d — Branch name
+
+Compute the default branch name as `docs/{major|minor}/{slug}-{newVersionWithoutV}` where `{slug}` is the last segment of the docBasePath (e.g., `users-guide`). Example: `docs/major/users-guide-v2.0`.
+
+Ask: "I'll use branch name `{branchName}`. Is that correct, or would you like a different name?"
+
+### 1e — Confirmation
+
+Display a summary:
+
+```
+Document:         {docBasePath}
+Current version:  {currentVersion}
+New version:      {newVersion}
+Revision type:    {major|minor}
+Branch:           {branchName}
+Source folder:    docs/{docBasePath}/{currentVersion}/
+Target folder:    docs/{docBasePath}/{newVersion}/
+Figures source:   static/figures/{docBasePath}/{currentVersion}/
+Figures target:   static/figures/{docBasePath}/{newVersion}/
+Bibliography:     static/bibliographies/{docBasePath}/{newVersion}/bib.json
+```
+
+Ask: "Does this look correct? (yes/no)"
+
+If no, ask which value to change and loop back.
+
+## Step 2: Create the git branch
+
+Create and check out the branch from the current `main` (not from the user's current branch — start clean):
+
+```bash
+git fetch origin main
+git checkout -b {branchName} origin/main
+```
+
+If the branch already exists, abort and report the conflict to the user.
+
+## Step 3: Copy the version folder
+
+Copy the entire current version directory to the new version directory:
+
+```bash
+cp -r docs/{docBasePath}/{currentVersion}/ docs/{docBasePath}/{newVersion}/
+```
+
+Then copy the figures folder:
+
+```bash
+cp -r static/figures/{docBasePath}/{currentVersion}/ static/figures/{docBasePath}/{newVersion}/
+```
+
+Then copy the bibliography folder:
+
+```bash
+cp -r static/bibliographies/{docBasePath}/{currentVersion}/ static/bibliographies/{docBasePath}/{newVersion}/
+```
+
+If any source folder doesn't exist, skip it and note in the final report.
+
+## Step 4: Update the version history file
+
+Read `docs/{docBasePath}/{newVersion}/00-version-history.mdx` and add a new placeholder row at the top of the `TableVersionHistory` props arrays:
+
+- `versions`: prepend the new version number without the `v` prefix (e.g., `'2.0'`)
+- `dates`: prepend the current month and year (e.g., `'April 2026'`)
+- `descriptions`: prepend `'Placeholder — describe the changes in this revision.'`
+- `modifiedBy`: prepend `'Enter author name'`
+- `reviewedBy`: prepend `'-'`
+- `approvedBy`: prepend `'-'`
+
+The author will fill in the actual values during the PR. The site admin will fill in `reviewedBy`/`approvedBy` at merge time.
+
+## Step 5: Set the draft flag
+
+Find the document's entry in the appropriate landing page JS file (search `src/pages/` for the `doc_location` matching `{docBasePath}`). Common locations:
+
+- Desktop apps: `src/pages/desktop-applications/{software}.js`
+- Toolboxes: `src/pages/toolboxes/{suite}.js`
+- Web apps: `src/pages/web-applications/{software}.js`
+- Dev: `src/pages/dev.js`
+
+In the matching entry, change `draft: false` to `draft: true`.
+
+> Note: this flips the draft flag on the *currently published* version too, since the flag is per-document, not per-version. The version-aware watermark logic in [src/theme/DocItem/index.js](src/theme/DocItem/index.js) ensures the watermark only appears on the *latest* version of a flagged document. Until this PR is merged, the latest version on the live site is still the previous version, which will not be watermarked. Once merged, the new version becomes latest and (briefly, until the site admin flips the flag back to `false`) the watermark will appear on it.
+
+## Step 6: Run generation scripts
+
+Run the build generation scripts to pick up the new version:
+
+```bash
+npm run sidebars && npm run counters && npm run versions
+```
+
+Verify no errors. If errors occur, diagnose and fix.
+
+## Step 7: Verify and report
+
+1. Glob to confirm the new version folder exists at `docs/{docBasePath}/{newVersion}/`
+2. Confirm the version history file has the new row
+3. Confirm the landing page JS has `draft: true`
+4. Confirm the branch is checked out (`git branch --show-current`)
+5. Report a summary to the user:
+
+```
+New revision scaffolded successfully!
+
+Document:    {docBasePath}
+Old version: {currentVersion}
+New version: {newVersion}
+Branch:      {branchName}
+
+Created:
+  - docs/{docBasePath}/{newVersion}/ (copied from {currentVersion})
+  - static/figures/{docBasePath}/{newVersion}/ (copied)
+  - static/bibliographies/{docBasePath}/{newVersion}/ (copied)
+
+Modified:
+  - docs/{docBasePath}/{newVersion}/00-version-history.mdx (new placeholder row)
+  - {landing page JS file} (draft: true)
+
+Next steps:
+  1. Edit the new version's MDX files to make your changes
+  2. Update 00-version-history.mdx with a real description and your name
+  3. Run `npm start` to preview locally
+  4. When ready, commit and open a PR (the workflow will detect the branch prefix and start {Lane 2: Peer → Lead Civil | Lane 3: Peer review} automatically)
+```

.claude/skills/pr/SKILL.md

@@ -68,28 +68,46 @@ Read `.claude/skills/git-conventions.md` for PR conventions.
 - Derived from the **overall purpose** of all commits on the branch, not just the latest commit
 - Example: "Redesign homepage with product tile grid layout"
 
-### Body
-Use this format — **Summary section only, no Test plan**:
+### Body — choose the format based on the branch prefix
 
-```markdown
-## Summary
-- {1-3 bullet points describing the changes and their purpose}
-```
+**If the current branch starts with `docs/`** → use the **Template Style** (Step 5a). The repo's PR template at `.github/pull_request_template.md` contains a checklist for document authors, including the Lane 1 "Technical edit comments addressed" checkbox that the stage-progression workflow watches for. Passing `--body` to `gh pr create` overrides the template entirely, so the skill must reproduce the template structure with the auto-generated content filled in.
 
-**Do NOT include:**
+**Otherwise (infrastructure, tooling, dependency, or any non-doc branch)** → use the **Summary Style** (Step 5b). These PRs are silently ignored by the review workflow and don't need the doc-author checklist.
+
+In both styles, the summary content should be based on **ALL** commits on the branch, not just the most recent one. Read through all the commit messages and the diff to understand the full scope. If `$ARGUMENTS` was provided, use it to focus the title and description.
+
+**Do NOT include in either style:**
 - A "Test plan" section
 - Any AI attribution, "Generated with Claude", or "Co-Authored-By" lines
 
-If `$ARGUMENTS` was provided, use it to focus the title and description.
+### Step 5a: Template Style (for `docs/` branches)
+
+1. Read [.github/pull_request_template.md](.github/pull_request_template.md). Use it as the structural skeleton.
+2. Compute the auto-generated summary: 1–3 bullets describing the changes.
+3. Compute the list of affected MDX documents: from `git diff --name-only main...HEAD`, keep entries matching `docs/**/*.mdx`. If the base is not `main`, use that instead.
+4. Build the PR body by transforming the template:
+   - Under `## Description`, replace the `<!-- Briefly describe what this PR does and why. -->` comment with the summary bullets.
+   - Under `## Affected documents`, replace the bare `- ` line with the list of affected MDX files. Format each as a markdown link relative to the repo root: `- [filename.mdx](docs/full/path/filename.mdx)`. If there are no changed MDX files, write `- _No MDX files changed in this PR._`
+   - Leave the `## Related issue(s)` section's comment placeholder unchanged so the author can fill it in.
+   - Leave **all checklist items unchecked**, including the Lane 1 Technical edit checkbox. The author checks them as they complete each item; the workflow specifically depends on the Technical edit checkbox being present and unchecked at PR open time.
+   - Leave the `## Notes for reviewers` comment placeholder unchanged.
+
+The result should be a complete copy of the template with the Description and Affected documents sections populated.
 
-The summary should be based on ALL commits on the branch, not just the most recent one. Read through all the commit messages and the diff to understand the full scope.
+### Step 5b: Summary Style (for non-`docs/` branches)
+
+Use this format — **Summary section only, no Test plan**:
+
+```markdown
+## Summary
+- {1-3 bullet points describing the changes and their purpose}
+```
 
 ## Step 6: Create the PR
 
 ```bash
 gh pr create --title "{title}" --body "$(cat <<'EOF'
-## Summary
-{bullets}
+{body from Step 5a or Step 5b}
 EOF
 )"
 ```

.claude/skills/technical-edit/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: technical-edit
+description: Run an AI-assisted technical edit on the current PR. Reads all changed MDX files, evaluates them against the RMC technical editing prompt, and posts inline review comments on the PR via the GitHub API.
+---
+
+# Technical Edit
+
+Run an AI-assisted technical edit on the current PR's documentation files.
+
+**Arguments:** `$ARGUMENTS` — optional PR number. If omitted, infer from the current branch.
+
+## Step 1: Identify the PR and changed files
+
+Determine the PR number from the current branch (use `gh pr view --json number`). List all changed `.mdx` files in the PR using `gh pr diff --name-only | grep '\.mdx$'`.
+
+## Step 2: Read the review prompt
+
+Read the standardized review prompt from `.github/ai-review/technical-editor-prompt.md`. This file contains the full set of review instructions including grammar rules, tense requirements, terminology conventions, Section 508 compliance checks, and style guidelines.
+
+## Step 3: Review each file
+
+For each changed MDX file:
+1. Read the file contents
+2. Apply the review prompt to the file
+3. For each finding, record: file path, line number or line range, severity (must-fix / should-fix / suggestion), the issue description, and a suggested fix if applicable
+
+## Step 4: Post the review on the PR
+
+Use the GitHub CLI to submit a bundled PR review with inline comments:
+
+```bash
+gh api repos/:owner/:repo/pulls/:pr/reviews \
+  --method POST \
+  -f body="AI technical edit complete. $(N) comments across $(M) files. Review prompt version: $(VERSION)." \
+  -f event="COMMENT" \
+  -f comments="[{\"path\": \"...\", \"line\": N, \"body\": \"...\"}]"
+```
+
+Each comment should be formatted as:
+```
+**[severity]** issue description
+
+> Suggested fix (if applicable)
+```
+
+Where severity is one of: 🔴 Must fix, 🟡 Should fix, 🔵 Suggestion.
+
+## Step 5: Report
+
+Tell the user:
+- How many comments were posted
+- How many files were reviewed
+- Which review prompt version was used
+- Remind the author to check the "Technical edit comments addressed" checkbox in the PR description when they're done addressing comments

.github/CODEOWNERS

@@ -0,0 +1,13 @@
+/.github/                        @usace-rmc/docs-admin
+/docusaurus.config.js            @usace-rmc/docs-admin
+/tailwind.config.js              @usace-rmc/docs-admin
+/package.json                    @usace-rmc/docs-admin
+/package-lock.json               @usace-rmc/docs-admin
+/scripts/                        @usace-rmc/docs-admin
+/src/theme/                      @usace-rmc/docs-admin
+/src/pages/                      @usace-rmc/docs-admin
+/src/components/                 @usace-rmc/docs-admin
+/src/contexts/                   @usace-rmc/docs-admin
+/src/clientModules/              @usace-rmc/docs-admin
+/src/css/                        @usace-rmc/docs-admin
+/src/draftDocs.js                @usace-rmc/docs-admin

.github/ai-review/technical-editor-prompt.md

@@ -0,0 +1,59 @@
+# RMC Technical Editor Review Prompt
+
+You are a technical editor reviewing documentation for the U.S. Army Corps of Engineers Risk Management Center (USACE RMC). The documentation is written in MDX (Markdown with JSX) and covers dam safety, levee safety, and related risk analysis topics.
+
+## Audience
+
+Practicing dam and levee safety engineers within USACE. These are technical professionals who understand the domain — do not flag correct use of technical terminology as jargon.
+
+## Review criteria
+
+### Grammar and mechanics
+- Spelling, punctuation, and sentence structure
+- Subject-verb agreement
+- Correct use of hyphens, em dashes, and en dashes
+- Consistent serial comma usage
+
+### Tense and voice
+- Prefer third-person active voice for procedures and descriptions
+- Flag passive voice when active would be clearer
+- Flag inconsistent tense within a section
+
+### Clarity and concision
+- Flag wordy passages that could be shortened without losing meaning
+- Flag ambiguous pronouns or unclear referents
+- Flag sentences over 40 words that could be split
+- Flag buried leads — key information at the end of a long sentence
+
+### Terminology consistency
+- Flag inconsistent use of terms within the document (e.g., alternating between "embankment" and "dam" when referring to the same structure)
+- Do NOT flag correct domain terminology as errors
+
+### Section 508 accessibility compliance
+- Every image must have alt text (check for `alt=` attribute)
+- Heading hierarchy must not skip levels (e.g., h2 followed by h4 without h3)
+- Link text must be descriptive (flag "click here" or "link" as link text)
+- Tables must have header rows
+- Lists must use proper markdown list syntax, not manual numbering with plain text
+- Color must not be the sole means of conveying information
+
+### Style consistency
+- Figure and table captions must follow a consistent format
+- Citations must use the site's citation key format
+- Units should be consistent within each document (metric or imperial, not mixed)
+- Acronyms must be defined on first use within each chapter
+
+## Output format
+
+For each finding, produce:
+- The file path and line number(s)
+- A severity level: 🔴 Must fix (errors, accessibility violations), 🟡 Should fix (clarity, consistency issues), 🔵 Suggestion (stylistic improvements)
+- A clear description of the issue
+- A suggested fix where possible (use GitHub suggestion block format)
+
+## What NOT to flag
+- Correct use of technical terminology, even if uncommon
+- MDX component syntax (imports, JSX elements)
+- Frontmatter fields
+- Matters of technical judgment or domain accuracy (that is the peer reviewer's job)
+- Alternative phrasings that are equally acceptable

.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## Description
+
+<!-- Briefly describe what this PR does and why. -->
+
+## Affected documents
+
+- 
+
+## Related issue(s)
+
+<!-- Link related issues. Use "Closes #N" to auto-close on merge. -->
+
+## Pre-submission checklist
+
+- [ ] I have previewed these changes locally or via the PR preview URL
+- [ ] My branch name uses one of the expected prefixes: `docs/new/`, `docs/major/`, `docs/minor/`, or `docs/fix/`
+- [ ] I have updated `00-version-history.mdx` if this change warrants a version entry
+- [ ] I have assigned a specific peer reviewer via the Reviewers sidebar (if known)
+
+## Technical edit (Lane 1 only)
+
+- [ ] Technical edit comments addressed — ready for Director review
+
+## Notes for reviewers
+
+<!-- Anything reviewers should know. -->