chore: prepare v0.22.0 release (#32)

## Summary

- Bump version to 0.22.0 in root `package.json`
- Add v0.22.0 CHANGELOG entry documenting the `cdktf` → `cdktn` package
rename and associated fixes
- Update CONTRIBUTING.md release section: point upgrade guide and PR
links to `open-constructs/cdk-terrain-docs`, remove HashiCorp-specific
post-release steps, update Sentry org to `cdktn`
- Fix `generate-documentation.js` frontmatter: `page_title` → `title`
(Mintlify standard), `CDKTF` → `CDKTN`
- Fix doc generation dependencies: `file:` → `link:`, add `jsii-rosetta`

## Test plan

- [x] `yarn docs` runs successfully with fixed frontmatter
- [x] Generated MDX files use `title:` (not `page_title:`) in
frontmatter
- [x] All 25 API reference MDX files generated (5 langs × 5 categories)
- [ ] Verify release CI triggers correctly on merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Vincent De Smet <vindes@handshakes.com.sg>

Author: 3 people

.gitignore

@@ -43,3 +43,8 @@ test/.yarn
 
 website/*
 !website/README.md
+!website/docs/
+website/docs/*
+!website/docs/cdktn/
+website/docs/cdktn/*
+!website/docs/cdktn/docs.json

CHANGELOG.md

@@ -1,3 +1,30 @@
+## 0.22.0
+
+**Breaking Changes**
+
+### Package Rename: `cdktf` to `cdktn`
+
+This is the first release under the CDK Terrain (CDKTN) project. All packages have been renamed:
+
+- `cdktf` → `cdktn`
+- `cdktf-cli` → `cdktn-cli`
+- `@cdktf/*` → `@cdktn/*`
+
+Internal symbols and logical IDs remain unchanged for backwards compatibility. Legacy config keys (`cdktf.json`, `CDKTF_*` env vars) are still supported.
+
+Prebuilt providers now require `cdktn` as a peer dependency (major version bump).
+
+### fix
+
+- fix: release-next gh token permissions [\#2db8ee4](https://github.com/open-constructs/cdk-terrain/commit/2db8ee4f0)
+- fix: pin sentry-cli to last v2 release [\#31eceb8](https://github.com/open-constructs/cdk-terrain/commit/31eceb82d)
+- fix(release): Sentry org/project [\#16](https://github.com/open-constructs/cdk-terrain/pull/16)
+
+### chore
+
+- chore: Rename to CDK Terrain / cdktn [\#7](https://github.com/open-constructs/cdk-terrain/pull/7)
+- docs: Update reference to CDKTF in PR template [\#3](https://github.com/open-constructs/cdk-terrain/pull/3)
+
 ## 0.21.0
 
 **Breaking Changes**

CONTRIBUTING.md

@@ -403,7 +403,7 @@ Most of our tests are automated but there are some workflows we need to manually
 
 - Test `cdktf` against Terraform Enterprise
 
-#### Terraform CDK
+#### CDK Terrain
 
 1. Create a new branch (e.g. `prepare-release-0.9.0`)
 2. Update the [CHANGELOG](./CHANGELOG.md): `./tools/create-changelog.sh` should get you a good start
@@ -412,15 +412,9 @@ Most of our tests are automated but there are some workflows we need to manually
 5. Merge the PR, a new release will be build and published because the version changed
 6. For major releases:
 
-- Write an [upgrade guide](https://github.com/hashicorp/web-unified-docs/tree/main/content/terraform-cdk/v0.21.x/docs/cdktf/release)
+- Write an [upgrade guide](https://github.com/open-constructs/cdk-terrain-docs/tree/main/content/release)
 - Run `yarn generate-docs` to bring our api documentation up to date
-- Make a PR with the changes over in the [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs) repository
-
-#### After the release
-
-- Updates in our other repos should largely be automated, but some of the updates require manual approval before they'll be auto-merged
-- Update the learn examples and the end to end examples
-- Check if there are PRs left behind on our [triage board](https://github.com/orgs/hashicorp/projects/125/views/4)
+- Make a PR with the changes over in the [`open-constructs/cdk-terrain-docs`](https://github.com/open-constructs/cdk-terrain-docs) repository
 
 #### Retrying a broken deployment
 
@@ -431,18 +425,11 @@ The release workflow uses sentry as the source of truth for releases. The downsi
 npm i -g @sentry/cli
 sentry-cli login
 # List all releases (optional)
-sentry-cli releases list --org hashicorp
+sentry-cli releases list --org cdktn
 # Delete the release, Note: there will be no confirmation for deleting the release!
-sentry-cli releases delete --org hashicorp <release> # e.g. cdktf-cli-0.14.0
+sentry-cli releases delete --org cdktn <release> # e.g. cdktn-cli-0.14.0
 ```
 
-### Repositories to update
-
-- [Docker E2E](https://github.com/hashicorp/docker-on-aws-ecs-with-terraform-cdk-using-typescript)
-- [Serverless E2E](https://github.com/hashicorp/cdktf-integration-serverless-example)
-- [Learn Lambda Demo](https://github.com/hashicorp/learn-cdktf-assets-stacks-lambda)
-- [AWS Adapter](https://github.com/hashicorp/cdktf-aws-cdk)
-
 ### Helper for creating the changelog
 
 Just run the following script before bumping the version, it'll create a ready to copy markdown formatted changelog.

package.json

@@ -1,6 +1,6 @@
 {
     "name": "root",
-    "version": "0.21.0",
+    "version": "0.22.0",
     "private": true,
     "scripts": {
         "build-and-package": "lerna run --scope 'cdktn*' --scope @cdktn/* build,package && tools/collect-dist.sh",
@@ -44,7 +44,7 @@
         "prepare-next-release": "standard-version --prerelease pre --release-as minor --skip.changelog=true --skip.commit=true",
         "prepare-release": "tools/prepare-release.sh",
         "release": "standard-version",
-        "generate-docs:api": "yarn && yarn build && yarn package && git clean -dfx . && mkdir -p website/docs/cdktf/api-reference && cd tools/documentation-generation && yarn && yarn docs && npx prettier --write ../../website/docs/cdktf/api-reference/**",
+        "generate-docs:api": "yarn && yarn build && mkdir -p website/docs/cdktn/api-reference && cd tools/documentation-generation && yarn && yarn docs && npx prettier --write ../../website/docs/cdktn/api-reference/**",
         "generate-docs": "yarn generate-docs:api",
         "generate-function-bindings": "cd tools/generate-function-bindings && yarn && yarn fetch-metadata && yarn generate"
     },

tools/documentation-generation/README.md

@@ -1,6 +1,110 @@
 # Documentation Generation
 
-A little node.js script that uses `jsii-docgen` to generate documentation for the `cdktn` package.
-Run `yarn && yarn docs` to generate the documentation.
+Generates API reference docs from the `cdktn` JSII assembly using [`jsii-docgen`](https://github.com/cdklabs/jsii-docgen), outputting Mintlify-compatible MDX files.
 
-This package is excluded from the hoisting because we need a locally installed copy of `cdktn` and `constructs`.
+## Usage
+
+```bash
+# From repo root (builds all packages first):
+yarn generate-docs:api
+
+# Or from this directory (assumes packages are already built):
+yarn && yarn docs
+```
+
+Output: `website/docs/cdktn/api-reference/<language>/<topic>.mdx` (25 files total).
+
+To publish, copy the output into the Mintlify docs site:
+
+```bash
+cp -r website/docs/cdktn/api-reference/* ../docs/content/api-reference/
+```
+
+## How It Works
+
+### Pipeline
+
+All transforms operate on the MDAST (abstract syntax tree) via remark/unified, so `code` and `inlineCode` nodes are naturally skipped — no placeholder hacks needed.
+
+```
+packages/cdktn/.jsii  (JSII assembly)
+        │
+        ▼
+   jsii-docgen           Generates one large markdown doc per language
+        │
+        ▼
+   remark-parse           Parse into MDAST (full AST)
+        │
+        ▼
+   splitByHeading(tree, 2)   Split by H2 into Map<topic, MDAST subtree>
+        │
+        ▼
+   sanitizeAst(subtree)      Walk text/html/link nodes, skip code/inlineCode
+        │
+        ▼
+   remark-stringify           Serialize back to clean markdown
+        │
+        ▼
+   postProcessForMdx()        MDX fixups: autolinks, `|` in <code>, lone `<`, `{`
+        │
+        ▼
+   compose()                  Wrap with MDX frontmatter, write .mdx files
+```
+
+### Languages and Topics
+
+5 languages x 5 topics = 25 `.mdx` files:
+
+| Languages  | Topics     |
+| ---------- | ---------- |
+| Typescript | Constructs |
+| Python     | Structs    |
+| Java       | Classes    |
+| CSharp     | Protocols  |
+| Go         | Enums      |
+
+### Output Format
+
+Each file gets Mintlify frontmatter:
+
+```yaml
+---
+title: "Typescript: Constructs"
+sidebarTitle: Constructs
+description: CDKTN Core API Reference for Constructs in Typescript.
+---
+```
+
+- `title` — page heading (e.g., "Typescript: Constructs")
+- `sidebarTitle` — short label for the nav sidebar (e.g., "Constructs"), since the language is already provided by the sidebar group
+- The original H2 topic heading from jsii-docgen is stripped to avoid duplication with the frontmatter title
+
+### MDX Sanitization (`sanitizeAst`)
+
+All sanitization is done at the AST level via a single `visit()` pass. The key advantage: `code` and `inlineCode` nodes are **skipped entirely**, so content like `import { Foo }` in TypeScript blocks and `-> str` in Python blocks is never corrupted.
+
+**`text` nodes** (prose):
+
+- `{@link URL text}` → spliced into proper MDAST link nodes
+- `<Foo>` generics → `< Foo >` (prevents MDX/HTML parsing; preserves `<code>`, `<a>`, `<sup>`)
+
+**`html` nodes**:
+
+- Angle bracket spacing, preserving real HTML tags (detected by tag name pattern)
+
+**`link` nodes**:
+
+- Relative terraform doc links (`/terraform/docs/...`) → absolute URLs (prefixes `https://developer.hashicorp.com`). Temporary workaround; see [#33](https://github.com/open-constructs/cdk-terrain/issues/33).
+
+**`code` / `inlineCode` nodes**: skipped — `remark-stringify` outputs their values raw
+
+**`postProcessForMdx`** (post-stringify string-level fixups, code-fence-aware):
+
+- `<url>` autolinks → `[url](url)` (MDX treats `<...>` as JSX)
+- `|` inside `<code>...</code>` → `&#124;` (prevents MDX table cell splitting)
+- Lone `<` not starting HTML tags (e.g., `<=`, `<<a`) → `&lt;`
+- `{` → `\{` (MDX brace escaping; can't be done at AST level because `remark-stringify` would double-escape)
+
+## Package Notes
+
+This package is excluded from workspace hoisting because it needs a locally installed copy of `cdktn` and `constructs` in its own `node_modules/` for jsii-docgen to resolve the JSII assembly.