# ComplyForm Docs

## What This Is
Documentation site for ComplyForm — a Terraform compliance automation CLI. Built with Starlight (Astro-based docs framework). Deployed to Cloudflare Pages at `docs.complyform.dev`.

## Tech Stack
- **Framework:** Starlight (built on Astro 6). Requires Node 22+.
- **Content:** MDX files in `src/content/docs/`
- **Styling:** Starlight's built-in theme with custom CSS overrides for ComplyForm dark palette
- **Hosting:** Cloudflare Pages

## Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Preview: `npm run preview`

## Content Structure
```
src/content/docs/
├── index.mdx                  # Docs home
├── quickstart.mdx             # 30-second install-to-scan
├── cli-reference/             # 15 command pages
├── frameworks/                # 53 auto-generated framework pages
├── guides/                    # 6 how-to guides
├── api-reference/             # 3 API reference pages
├── drift-setup/               # 4 cloud-specific drift setup pages
└── changelog/                 # CLI + Profiles changelogs
```

## Content Rules

1. **CLI flags must match architecture §A.1 exactly.** Do not fabricate flags, invent default values, or rename options. If uncertain, leave a `<!-- TODO: verify flag -->` comment.

2. **Writing style:** Write for a DevOps engineer who reads `man` pages.
   - Lead with the command, then explain
   - One concept per paragraph
   - Code blocks > prose for anything executable
   - No marketing language in docs ("blazing fast", "revolutionary", "game-changing")
   - Use "you" not "the user"

3. **Code examples must be realistic.** Show actual `complyform` output, not placeholder text. Use plausible resource names (`google_sql_database_instance.production`, not `example_resource`).

4. **Framework data comes from `profiles/framework_registry.yaml`.** The 53 framework pages are auto-generated by `scripts/generate_docs_framework_pages.py`. Do not hand-edit generated pages.

5. **Cross-links:** Use relative Starlight links (`../../guides/brownfield`), not absolute URLs.

## Starlight Components
Use Starlight's built-in components where appropriate:
- `<Aside type="tip|caution|danger">` for callouts
- `<Card>` for link cards on overview pages
- `<Tabs>` for multi-cloud examples (GCP / AWS / Azure)
- `<Code>` for syntax-highlighted blocks with titles

## Anti-Patterns — REJECT These
- Fabricated CLI flags or options not in architecture §A.1
- Marketing copy in technical documentation
- Screenshots instead of code blocks (terminal output is text, not images)
- External links without `target="_blank" rel="noopener noreferrer"`
- Placeholder content like "Lorem ipsum" or "TODO" without a tracking comment
