Consolidate v8 RC changelog into v8.1.0 release (2026-04-07)

Collapse 8.0.0-rc2 section and add entries for hq CLI, agent-friendly
conversion CLIs, template directives, comment loading, and bug fixes
shipped since rc2. Update README and getting-started docs with CLI
mentions, pipx install, hq examples link, and revised roadmap.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kkozik-amplify

CHANGELOG.md

@@ -9,15 +9,22 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Nothing yet.
 
-## \[8.0.0\] - rc2
+## \[8.1.0\] - 2026-04-07
 
 ### Added
 
 - Full architecture overhaul: bidirectional HCL2 ↔ JSON pipeline with typed rule classes. ([#203](https://github.com/amplify-education/python-hcl2/pull/203))
-  - add function tuples round-trip test suite ([#268](https://github.com/amplify-education/python-hcl2/pull/268))
+  - Add function tuples round-trip test suite ([#268](https://github.com/amplify-education/python-hcl2/pull/268))
   - Add postlexer to support multiline binary operators and ternary expressions ([#270](https://github.com/amplify-education/python-hcl2/pull/270))
-  - more robust whitespace handling in reconstruction ([#271](https://github.com/amplify-education/python-hcl2/pull/271))
-  - SerializationOptions - add an option to strip string quotes in dict/JSON output ([#272](https://github.com/amplify-education/python-hcl2/pull/272))
+  - More robust whitespace handling in reconstruction ([#271](https://github.com/amplify-education/python-hcl2/pull/271))
+  - SerializationOptions — add an option to strip string quotes in dict/JSON output ([#272](https://github.com/amplify-education/python-hcl2/pull/272))
+- `hq` read-only query CLI for HCL2 files ([#277](https://github.com/amplify-education/python-hcl2/pull/277))
+  - Add `.[]` as jq-compatible alias for `[*]` and document jq interop ([#283](https://github.com/amplify-education/python-hcl2/pull/283))
+  - Add adjacent comment support to BlockView and AttributeView queries ([#282](https://github.com/amplify-education/python-hcl2/pull/282))
+  - Refactor for readability and reduced complexity ([#284](https://github.com/amplify-education/python-hcl2/pull/284))
+- Agent-friendly conversion CLIs: `hcl2tojson` and `jsontohcl2` ([#274](https://github.com/amplify-education/python-hcl2/pull/274))
+- Add template directives support (`%{if}`, `%{for}`) in quoted strings ([#276](https://github.com/amplify-education/python-hcl2/pull/276))
+- Support loading comments ([#134](https://github.com/amplify-education/python-hcl2/issues/134))
 - CLAUDE.md ([#260](https://github.com/amplify-education/python-hcl2/pull/260))
 
 ### Fixed
@@ -34,7 +41,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Interpolation literals added to locals/variables in maps ([#252](https://github.com/amplify-education/python-hcl2/issues/252))
 - Object literal expression can't be serialized ([#253](https://github.com/amplify-education/python-hcl2/issues/253))
 - Heredocs should interpret backslash literally ([#262](https://github.com/amplify-education/python-hcl2/issues/262))
-- Parsing a multi-line multi-conditional expression causes exception - Unexpected token Token('QMARK', '?') ([#269](https://github.com/amplify-education/python-hcl2/issues/269))
+- Parsing a multi-line multi-conditional expression causes exception — Unexpected token Token('QMARK', '?') ([#269](https://github.com/amplify-education/python-hcl2/issues/269))
+- Missing space between binary operator and unary operand in reconstruction ([#275](https://github.com/amplify-education/python-hcl2/pull/275))
 
 ### Changed
 

README.md

@@ -7,8 +7,9 @@
 # Python HCL2
 
 A parser for [HCL2](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md) written in Python using
-[Lark](https://github.com/lark-parser/lark). This parser only supports HCL2 and isn't backwards compatible
-with HCL v1. It can be used to parse any HCL2 config file such as Terraform.
+[Lark](https://github.com/lark-parser/lark). It can be used as a Python library or through its CLI tools:
+`hcl2tojson`, `jsontohcl2`, and `hq` — a jq-like query tool for HCL files.
+Supports HCL2 only (not backwards compatible with HCL v1) and works with any HCL2 config file such as Terraform.
 
 ## About Amplify
 
@@ -33,6 +34,12 @@ This package can be installed using `pip`
 pip3 install python-hcl2
 ```
 
+To install the CLI tools (`hcl2tojson`, `jsontohcl2`, `hq`) globally without affecting your project environments, use [pipx](https://pipx.pypa.io/):
+
+```sh
+pipx install python-hcl2
+```
+
 ### Usage
 
 **HCL2 to Python dict:**
@@ -75,6 +82,7 @@ hcl_string = hcl2.dumps(doc.build())
 | [Querying HCL (Python)](docs/02_querying.md) | DocumentView, BlockView, tree walking, view hierarchy |
 | [Advanced API](docs/03_advanced_api.md) | Pipeline stages, Builder |
 | [hq Reference](docs/04_hq.md) | `hq` CLI — structural queries, hybrid/eval, introspection |
+| [hq Examples](docs/05_hq_examples.md) | Real-world queries for discovery, compliance, extraction |
 
 ### CLI Tools
 
@@ -123,13 +131,10 @@ Github actions will take care of publishing it to PyPi.
 
 Planned features, roughly in priority order:
 
-- **Agent-friendly CLIs** — structured errors, NDJSON streaming, and filtering for `hcl2tojson`/`jsontohcl2`
-- **Comment deserialization** — preserve comments through JSON round-trip (issue #134)
-- **jq syntax compatibility** — `.[]` as alias for `[*]`; canonical `hq --json | jq` patterns for data transforms
 - **MCP server** — expose parsing, querying, and formatting as MCP tools for AI agents
-- **Canonical formatting** — predictable whitespace output, closer to `terraform fmt`
+- **Predictable formatting** — source-derived formatting heuristics and stable whitespace defaults
 - **In-place tree edits** — `hq set`, `hq delete` for programmatic HCL modification
-- **Comment reserialization** — comments survive tree edits, not just JSON round-trips
+- **Comment deserialization** — comments survive JSON round-trips and tree edits
 - **Expression intelligence** — variable reference tracking, unused variable detection, cross-file analysis
 - **Refactoring operations** — `hq rename`, `hq extract-module`, `hq sort` for high-level code transforms
 

docs/01_getting_started.md

@@ -10,6 +10,12 @@ python-hcl2 requires Python 3.8 or higher.
 pip install python-hcl2
 ```
 
+For the CLI tools only (`hcl2tojson`, `jsontohcl2`, `hq`), [pipx](https://pipx.pypa.io/) installs them globally in an isolated environment:
+
+```sh
+pipx install python-hcl2
+```
+
 ## Quick Reference
 
 | Function | Description |