docs

Generate / Update Documentation

Generate or update markdown documentation by analyzing the actual codebase. Never fabricate -- every statement must be backed by code you've read.

Arguments

• {target} -- What to document. One of:
  • service {name} -- Full service documentation (endpoints, events, config)
  • api {service} -- API endpoint reference for a service
  • architecture -- Update the technical architecture doc
  • domain -- Update the domain model doc
  • runbook {service} -- Operational runbook (health checks, alerts, troubleshooting)
  • quickstart -- Update the quickstart / getting started guide
  • all -- Regenerate all outdated docs

If no argument given, detect what's changed since last docs update and suggest what needs refreshing.

Configuration

Read cloudstack.json from the project root at the start of execution. Extract:

• NAMESPACE = project.namespace
• SOLUTION = backend.solutionPath
• SERVICES = backend.services[]
• FRONTEND_PATH = frontend.path (default: web)
• CHARTS_PATH = infrastructure.chartsPath (default: deploy/charts)
• TERRAFORM_PATH = infrastructure.terraformPath

If cloudstack.json does not exist, auto-detect by scanning the project structure.

Process

Step 1: Detect Scope

If no target specified:

# Find docs that may be stale -- compare last doc commit vs last code commit
git log -1 --format=%H -- docs/
git log -1 --format=%H -- src/ ${FRONTEND_PATH} ${CHARTS_PATH} ${TERRAFORM_PATH}

# Show what code changed since docs were last updated
git diff {last-docs-commit}..HEAD --stat -- src/ ${FRONTEND_PATH} ${CHARTS_PATH} ${TERRAFORM_PATH}

Present the user with a summary of what's changed and recommend which docs to update.

Step 2: Gather Evidence

Read the actual code -- do NOT guess or use stale memory. For each doc type:

Service doc (docs/services/{service-name}/README.md):

1. Read src/{Service}/{Service}.Host/Program.cs -- DI, middleware, config sections
2. Read src/{Service}/{Service}.Host/Endpoints/ -- all endpoint files
3. Read src/{Service}/{Service}.Application/Commands/ -- all command records
4. Read src/{Service}/{Service}.Application/Queries/ -- all query records
5. Read src/{Service}/{Service}.Infrastructure/DependencyInjection.cs -- external dependencies
6. Read src/{Service}/{Service}.Infrastructure/Persistence/Configurations/ -- DB schema
7. Grep for messaging subjects/topics in the service
8. Read Helm chart values if present: ${CHARTS_PATH}/{service-name}/values.yaml
9. Read appsettings.json in the Host project -- configuration keys