chore(docs): document feature flags and the canonicalAssetHashes scheme

[vincenthsh]

Description

Docs follow-up promised in #321/#323. Stacked on #323 (which is stacked on #321) — only the last commit (chore(docs): document feature flags and the canonicalAssetHashes scheme) is new here; the rest collapses as the base PRs merge, and I'll rebase after each.

Adds docs/feature-flags.md:

• the FUTURE_FLAGS lifecycle (cdktn init enables for new projects, existing projects opt in via cdktf.json, graduation at the next major, no opt-out flags) and a table of all current flags;
• a full section on canonicalAssetHashes (feat(lib): canonical asset hashes behind the canonicalAssetHashes feature flag #323): the legacy hash's structural blind spots (renames, entry boundaries, permissions, empty directories), and why canonical hashing is the recommended future default;
• the canonical representation itself, explicitly incorporating the review lesson from feat(lib): define a complete canonical asset-hash representation #322: git trees and Nix NAR are canonical because they serialize a complete metadata model — modes and directory records included — not payload framing alone. The documented record table covers file/symlink permission masks (the exact bits archiveSync emits) and explicit directory records including empty ones;
• migration impact (one-time asset-path change and re-deploy on opt-in, cdktfStaticModuleAssetHash as a pinning escape hatch) and the case for adopting early (re-deploy on your schedule; trustworthy change detection; byte-reproducible archives ending filebase64sha256 drift).

Note: docs/README.md currently declares this directory deprecated in favor of upstream terraform.io docs — that pointer is stale for the fork, and this page starts rebuilding fork-native docs. Happy to move the page if maintainers prefer a different docs home.

Checklist

• I have updated the PR title to match CDKTN's style guide
• I have run the linter on my code locally
• I have performed a self-review of my code
• My changes generate no new warnings

🤖 Generated with Claude Code

[sakul-learning]

Thanks for documenting this, but this material belongs in the user-facing open-constructs/cdk-terrain-docs repository rather than the deprecated docs/ directory in this implementation repository. I suggest closing this PR and opening a focused docs PR there.

The replacement should be usage- and upgrade-oriented rather than primarily documenting the internal hash record format. In particular, it should explain:

• how to enable canonicalAssetHashes and which asset paths/types it affects;
• the user-visible problem it addresses and why asset hashes/paths can change;
• the impact and risks of enabling it, including the one-time asset path changes, uploads, and resource redeployments;
• the risks of not enabling it before the behavior becomes the default;
• the broader symlink-handling fix: what bug it fixes, when the regression was introduced, and the migration impact for projects coming from upstream CDKTF, where symlinks in archive assets worked;
• which behavior is behind the feature flag versus which symlink corrections apply independently of it.

Because these are potentially breaking asset-behavior changes behind a feature flag, most of the migration guidance should go into the 0.24.0 release/upgrade guide, with the reusable feature-flag usage material linked from the relevant asset documentation.

There is already an open docs PR for the Node.js 22.19+ prerequisite: cdk-terrain-docs#28. Its thread explicitly notes that the full upgrade-guide-v0-24.mdx work should be included after the release PR merges, so please coordinate this canonical-hash/symlink migration guidance with that 0.24 documentation work rather than creating a second documentation home here.

[vincenthsh]

closing as this goes to open-constructs/cdk-terrain-docs