doc-sync

name	doc-sync
description	Audit and synchronize documentation across website, READMEs, and docs/. Use when verifying docs are aligned after feature changes, SDK updates, CLI changes, or release preparation. Detects drift between website content, markdown docs, and SDK READMEs.
argument-hint	feature area to audit or "full" for complete audit

Doc Sync: Cross-Surface Documentation Alignment

Audit and synchronize documentation across all surfaces to prevent drift.

When to Use

• After adding or changing a feature, CLI flag, or SDK capability
• After updating website content (DocsContent.astro, i18n strings)
• Before a release to verify all docs reflect current behavior
• When a code review flags outdated documentation

Documentation Surfaces

Surface	Location	Purpose
Website docs	src/website/src/components/DocsContent.astro	User-facing docs page with code examples
Website i18n	src/website/src/i18n/{en,ca,es}.ts	Translated strings for website
Root README	README.md	Project overview, install, quick start
GHA README	github-action/README.md	GitHub Action usage and inputs
CLI docs	docs/pull-command.md, docs/push-command.md	CLI command reference
GHA docs	docs/github-action.md	GitHub Action detailed docs
SDK READMEs	src/sdks/{dotnet,python,typescript}/README.md	SDK-specific install and usage
SDK examples	examples/sdk/{dotnet,python}/README.md	Example code with explanations
Changelogs	docs/changelogs/{cli,gha,sdk-*}.md	Per-component changelogs
ROADMAP	ROADMAP.md	Feature status tracking

Procedure

1. Identify Scope

Determine which feature area to audit:

• CLI: root README, docs/pull-command.md, docs/push-command.md, website DocsContent
• GHA: github-action/README.md, docs/github-action.md, website DocsContent
• SDK (per runtime): src/sdks/{runtime}/README.md, examples/sdk/{runtime}/, website DocsContent + Sdks.astro, i18n strings
• Full: all surfaces

2. Extract Source of Truth

For each feature area, identify the authoritative source:

Area	Source of Truth
CLI flags/options	src/envilder/apps/cli/entry/Cli.ts
GHA inputs	github-action/action.yml
SDK public API	SDK source code (src/sdks/{runtime}/)
Providers	src/envilder/core/infrastructure/
Map-file format	envilder.json (example) + copilot-instructions

3. Audit Each Surface

For each documentation surface, check:

• Code examples compile/run: verify syntax matches current API
• CLI flags match: documented flags exist in Cli.ts
• GHA inputs match: documented inputs exist in action.yml
• SDK methods match: documented methods exist in source
• Install commands correct: package names, versions, registries
• Provider names consistent: aws/azure naming across all docs
• Links not broken: internal cross-references resolve
• i18n complete: all 3 locales (en, ca, es) have matching keys

4. Report Drift

Present findings in a structured table:

## Documentation Drift Report

| Surface | File | Issue | Severity |
|---------|------|-------|----------|
| Website | DocsContent.astro | Missing --profile flag in CLI section | High |
| SDK README | src/sdks/python/README.md | load() example uses old API | High |
| Root README | README.md | Version badge outdated | Low |

## Alignment Actions

1. {file}: {what to update}
2. {file}: {what to update}

5. Apply Fixes

For each drift item:

1. Update the documentation surface
2. If i18n strings changed, update all 3 locales
3. Verify the fix against the source of truth

6. Validate

• Run pnpm lint to check for formatting issues
• For website changes, verify the build: check i18n key consistency

Cross-Reference Matrix

Use this matrix to ensure consistency when updating a feature:

When you change...	Also update...
CLI flag in Cli.ts	docs/pull-command.md or docs/push-command.md, root README, DocsContent, i18n
GHA input in action.yml	github-action/README.md, docs/github-action.md, website DocsContent, i18n
SDK public API	SDK README, examples README, website DocsContent + Sdks.astro, i18n
New SDK added	Run full sdk-release-checklist skill (version badge, changelog, i18n, docs)
SDK version bump	Bump canonical source file; changelog entry; website picks up version at build time
New provider	All provider listings: root README, website Providers.astro, DocsContent, SDK READMEs
Map-file format	Root README, all SDK READMEs, website DocsContent
ROADMAP status	ROADMAP.md, website Roadmap.astro

Constraints

• Never invent features not present in code
• Verify claims against source code before writing
• Preserve existing document structure and tone
• Keep code examples minimal and runnable