sync-docs

Sync Documentation

Overview

Ensure documentation is synchronized across all key files when variables or features change.

Usage

/sync-docs

Documentation Files

Workflow

digraph sync_flow {
    rankdir=TB;
    node [shape=box];

    extract [label="1. Extract from variables.tf"];
    compare [label="2. Compare with docs/llms.md"];
    gaps [label="3. Identify gaps"];
    update_llms [label="4. Update docs/llms.md"];
    update_example [label="5. Update kube.tf.example"];
    update_readme [label="6. Update README if needed"];
    verify [label="7. Verify consistency"];

    extract -> compare;
    compare -> gaps;
    gaps -> update_llms;
    update_llms -> update_example;
    update_example -> update_readme;
    update_readme -> verify;
}

Step 1: Extract Variables from Source

Use Gemini for large file analysis:

# List all variables from variables.tf
gemini --model gemini-3.1-pro-preview -p "@variables.tf List ALL variable names defined in this file, one per line"

# Get variable details
gemini --model gemini-3.1-pro-preview -p "@variables.tf For variable '<name>', provide: type, default, description"

Step 2: Find Undocumented Variables

# Compare variables.tf with docs/llms.md
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @docs/llms.md List ALL variables from variables.tf that are NOT documented in docs/llms.md. Output one per line."

Step 3: Generate Documentation

docs/llms.md Format

**Variable Name**

```tf
variable_name = "default_value"

• variable_name (Type, Optional/Required):
  • Default: default_value
  • Purpose: Clear explanation of what this does
  • Usage: When and how to use it
  • Considerations: Important notes, limitations, impacts
  • Example: Practical usage example if helpful

### kube.tf.example Format

```tf
  # Description of what this controls
  # Additional context if needed
  # variable_name = "default_value"

Step 4: Update docs/llms.md

For each undocumented variable:

1. Read variable definition from variables.tf
2. Understand its usage in locals.tf and other files
3. Write comprehensive documentation following the format above
4. Place in appropriate section of docs/llms.md

Section Organization in docs/llms.md

Step 5: Update kube.tf.example

Ensure new variables appear in the example with:

• Clear comment explaining purpose
• Commented out with default value
• Grouped with related variables

# Check what's in example vs variables.tf
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @kube.tf.example List variables from variables.tf missing from kube.tf.example"

Step 6: Update README if Needed

Update README.md if:

• New major feature added
• New CNI or ingress option
• Significant capability change

Features section should match actual capabilities.

For Tailscale changes, keep these surfaces in sync:

• README.md support table and Multinetwork section
• kube.tf.example Tailscale node-transport comments
• docs/llms.md support levels and variable notes
• docs/v3-topology-recommendations.md
• examples/tailscale-node-transport/README.md
• examples/external-overlay-tailscale/README.md
• examples/external-overlay-cloudflare-access/README.md when access-boundary wording changes
• .claude/skills/kh-assistant/SKILL.md
• .claude/skills/migrate-v2-to-v3/SKILL.md

For Cloudflare Zero Trust wording, keep the boundary consistent:

• Cloudflare Access/Tunnel is a documented external operator/app access pattern.
• kube-hetzner does not add Cloudflare provider inputs or manage Cloudflare resources.
• Cloudflare Mesh/WARP is not supported kube-hetzner node transport in v3.
• Tailscale remains the supported managed node transport for secure multinetwork scale.

For Cilium Gateway API changes, keep these surfaces in sync:

• variables.tf validation for cilium_gateway_api_enabled
• locals.tf Cilium values and Gateway API CRD version mapping
• README.md
• kube.tf.example
• docs/llms.md
• docs/v3-topology-recommendations.md
• examples/cilium-gateway-api/README.md
• .claude/skills/kh-assistant/SKILL.md
• .claude/skills/test-changes/SKILL.md

For embedded registry mirror changes, keep these surfaces in sync:

• variables.tf validation for embedded_registry_mirror
• locals.tf effective generated registries YAML merge behavior
• host/control-plane/agent/autoscaler config rendering
• README.md
• kube.tf.example
• docs/llms.md
• docs/v3-topology-recommendations.md
• .claude/skills/kh-assistant/SKILL.md
• .claude/skills/test-changes/SKILL.md

For v2 -> v3 migration or production-upgrade safety changes, keep these surfaces in sync:

• MIGRATION.md, especially "Production in-place upgrades: safety model"
• docs/v2-to-v3-migration.md
• CHANGELOG.md upgrade notes
• docs/v3-release-evidence.md live proof
• .claude/skills/migrate-v2-to-v3/SKILL.md
• .claude/skills/upgrade-cluster/SKILL.md
• .claude/skills/kh-assistant/SKILL.md

The no-destroy gate must include the full protected hcloud set: hcloud_server, hcloud_network, hcloud_network_subnet, hcloud_load_balancer, hcloud_volume, hcloud_primary_ip, hcloud_placement_group, and hcloud_firewall.

For SELinux changes, keep these surfaces in sync:

• docs/selinux.md
• templates/kube-hetzner-selinux.te
• templates/k8s-custom-policies.te
• variables.tf enable_selinux and per-pool selinux
• .claude/skills/debug-node/SKILL.md
• .claude/skills/kh-assistant/SKILL.md

Do not make generic "disable SELinux" recommendations. The operator path is AVC evidence, udica-first workload policy, upstream module policy only with reproducible denials, and per-pool selinux = false as the last resort.

For release presentation changes, verify README's "What's New in v3" tag link still points at the current release tag, and keep the section current with the live GitHub release body.

Step 7: Verify Consistency

# Final verification
gemini --model gemini-3.1-pro-preview -p \
  "@variables.tf @docs/llms.md @kube.tf.example Verify these files are consistent. List any discrepancies."

Verification Checklist

• All variables.tf variables documented in docs/llms.md
• All major variables appear in kube.tf.example
• README features match actual capabilities
• No typos in variable names across files
• Default values consistent across docs
• Major-upgrade safety wording matches MIGRATION.md
• SELinux workload-denial wording points to docs/selinux.md
• README "What's New in v3" release-tag URL is current for the release train

Common Sync Issues

Variable renamed

1. Update in variables.tf
2. Search and replace in docs/llms.md
3. Search and replace in kube.tf.example
4. Add to CHANGELOG.md (breaking change!)

Variable removed

1. Remove from variables.tf
2. Remove from docs/llms.md
3. Remove from kube.tf.example
4. Add to CHANGELOG.md (breaking change!)

Default changed

1. Update in variables.tf
2. Update in docs/llms.md
3. Update in kube.tf.example
4. Consider if this is a breaking change

Quick Commands

# Regenerate terraform docs
terraform-docs markdown . > docs/terraform.md

# Validate v3 topology/Gateway/registry surfaces
uv run scripts/validate_v3_final_polish_examples.py

# Validate rendered templates and negative contract cases when those surfaces change
uv run scripts/render_harness.py
uv run scripts/contract_negative_tests.py

# Search for variable across all docs
rg -n "variable_name" docs/ kube.tf.example README.md

# Find undocumented variables (quick check)
diff <(rg -o 'variable "([^"]+)"' -r '$1' variables.tf | sort) \
     <(rg -o '`[a-z_]+`' docs/llms.md | tr -d '`' | sort -u) | rg "^<"

After Sync

1. Run terraform fmt -recursive
2. Commit only if the current task calls for a commit, with message: docs: sync documentation with variables.tf
3. If breaking changes, update CHANGELOG.md