Skip to content

CLAUDE.md

Latest commit

 

History

History
157 lines (115 loc) · 7.52 KB

CLAUDE.md

File metadata and controls

157 lines (115 loc) · 7.52 KB
Raw

CLAUDE.md

This is the official documentation site for the RMC (Risk Management Center) suite of tools developed by the U.S. Army Corps of Engineers. Built with Docusaurus 3.x, Tailwind CSS, and custom React components.

Quick Commands

npm start            # Start dev server (runs all generation scripts first)
npm run build        # Build static site for production
npm run sidebars     # Generate sidebars.js from MDX folder structure
npm run counters     # Generate figure/table/equation counters
npm run versions     # Extract version metadata
npm run report-map   # Generate reportIdMap.js for document routing
npm run image-dims   # Generate image dimension metadata
npm run generate-toc # Generate Event Tree Database TOC data

Build scripts respect DOCS_MODE: dev (default) builds all docs including those flagged active: false; prod excludes inactive docs. npm start sets dev; npm run build sets prod.

Project Structure

docs/                          # Documentation content (MDX files)
├── desktop-applications/      # LifeSim, RMC-TotalRisk, RMC-RFA, RMC-BestFit
├── toolbox-technical-manuals/ # Internal Erosion, Overtopping, Risk Calcs, Seismic
├── web-applications/          # RRFT, LST, DST
└── dev/                       # Developer-facing docs
    ├── documentation-guide/   # Contributor guide and style reference
    ├── github-workflows/      # GitHub workflow SOP
    ├── architecture/          # Web app architecture references
    ├── ai-development/        # AI-assisted development guidance
    ├── python-quickstart-guide/
    └── dst/                   # DST developer + UI style guides

src/
├── components/                # 40+ custom React components (Figure, Table*, Citation, etc.)
├── contexts/                  # ReportIdContext, TourContext
├── css/                       # Tailwind & component styles
├── theme/                     # Docusaurus theme customizations (DocItem watermark, Layout, etc.)
├── docConfig.js               # Central source of truth for active/draft flags
└── draftDocs.js               # Thin shim around docConfig.js (consumed by DocItem)

scripts/                       # Build automation (sidebars, counters, versions, etc.)
static/                        # Static assets and auto-generated metadata
.github/                       # CODEOWNERS, PR template, workflows, AI review prompt
planning/                      # Implementation specs for cross-cutting changes

Auto-Generated Files (DO NOT EDIT)

These files are regenerated by build scripts:

  • sidebars.js - Generated from docs/ structure
  • src/reportIdMap.js - Generated from MDX frontmatter
  • src/imageDimensions.js - Generated from images in static/figures/
  • static/counters/ - Figure/table/equation numbering
  • static/versions/ - Version metadata
  • src/data/ - Event tree TOC data

Document Active/Draft Flags

src/docConfig.js is the central registry for every published document tile. Each entry has two orthogonal flags:

  • active: true means the doc is built, served, sidebar-registered, and indexed by Algolia. false means the doc is excluded from the prod build and renders as a "Coming Soon" tile on the landing page; in dev (DOCS_MODE=dev) it still builds so contributors can work on it.
  • draft: true renders a diagonal "DRAFT" watermark on the latest version only of the doc (older versions stay unwatermarked). false means no watermark.

The two flags are orthogonal — a doc can be active: true, draft: true (published with watermark) or active: false, draft: true (unpublished but flagged for future watermarking).

Key Patterns

MDX Document Structure

---
title: "Document Title"
---

import NavContainer from "@site/src/components/NavContainer";
import Figure from "@site/src/components/Figure";

<NavContainer
  link="/path"
  linkTitle="Title"
  document="relative/path"
/>

# Heading

Content with <Figure figKey="fig1" src="path" alt="text" caption="..." />

Custom Components

  • Figures: <Figure figKey="unique-key" src="path" alt="text" caption="..." />
  • Tables: <TableHorizontal tableKey="key" /> or <TableVertical tableKey="key" />
  • Equations: <Equation equationKey="key">\LaTeX</Equation>
  • Citations: (Author, Year) <Citation citationKey="key" /> - the text citation is preserved alongside the component (renders as "(Author, Year) [1]"). The Citation component must be placed OUTSIDE the author-year parentheses, not inside. Include <Bibliography /> on the References page.
  • References: <FigureReference figKey="key" />, <TableReference tableKey="key" />

File Naming

  • Numbered prefixes for ordering: 01-filename.mdx, 02-filename.mdx
  • Version paths: docs/{category}/{app}/{type}/v{major}.{minor}/
  • Special files: 00-document-info.mdx, 00-version-history.mdx

Branching and Review Workflow

The main branch is protected. All changes go through a pull request. Branch prefixes auto-assign the PR to one of five review lanes via the stage-progression.yml GitHub workflow:

Prefix Lane Reviews required
docs/new/ New document Peer → Lead Civil → Technical edit → Director
docs/major/ Major revision (new major version) Peer → Lead Civil
docs/minor/ Minor revision (new minor version) Peer
docs/fix/ Editorial fix None (admin self-merge)
docs/dev/ Dev docs (anything under docs/dev/) None (admin self-merge)

Dev-docs detection is also content-based: any PR whose changed files under docs/ are all under docs/dev/ is auto-routed to lane:dev regardless of branch name.

Branch protection on main requires two status checks:

  • CI Build — runs npm run build on every PR
  • review-workflow — set by stage-progression.yml; flips to success when the PR reaches stage:ready-to-merge (or immediately for lane:editorial-fix and lane:dev)

Full details: docs/dev/documentation-guide/ chapters 09–15.

Code Style

  • Prettier: 150 char line width, single quotes, trailing commas
  • Tailwind CSS with USACE branding colors (primary: #4a7c9b)
  • React components use ReportIdContext for version-aware data

Git Commit Messages

  • Do NOT include "Co-Authored-By: Claude", "Claude Code", or any AI/assistant attribution in commit messages
  • Keep commit messages concise and focused on the changes made

QC Reviews

The QC prompt template at qc/qc-prompt.md is a manually-usable template for AI-assisted document reviews. It supports three levels:

Level Name When to Use
1 Syntax & Grammar No source PDF available; check MDX syntax, components, grammar only
2 Source Comparison Source PDF available; Level 1 + verify MDX matches source exactly
3 Technical Edit Source PDF available; Levels 1 & 2 + suggest content improvements

Key rules:

  • Level 1: Do NOT suggest rewording or technical changes—syntax and grammar only
  • Level 2: Do NOT suggest improvements beyond matching the source document
  • Level 3: Full editorial suggestions allowed; mark these as "Editorial" category with "Suggestion" severity
  • All levels: Do NOT edit MDX files directly—output findings to qc/ only

The standardized prompt for the formal in-PR technical edit is at .github/ai-review/technical-editor-prompt.md — see Documentation Guide chapter 13 for how it's invoked.

Requirements

  • Node.js >= 18.0
  • npm