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

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,15 @@ 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 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))
+- `hq` read-only query CLI for HCL2 files ([#277](https://github.com/amplify-education/python-hcl2/pull/277))
+- 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 +34,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))
+- Parsing error for multiline binary operators ([#246](https://github.com/amplify-education/python-hcl2/pull/246))
 
 ### Changed
 

CLAUDE.md

@@ -23,6 +23,7 @@ The **Direct** pipeline (`parse_to_tree` → `transform` → `to_lark` → `reco
 | `hcl2/formatter.py` | Whitespace alignment and spacing on LarkElement trees |
 | `hcl2/reconstructor.py` | LarkElement tree → HCL2 text via Lark |
 | `hcl2/builder.py` | Programmatic HCL document construction |
+| `hcl2/walk.py` | Generic tree-walking primitives for the LarkElement IR tree |
 | `hcl2/utils.py` | `SerializationOptions`, `SerializationContext`, string helpers |
 | `hcl2/const.py` | Constants: `IS_BLOCK`, `COMMENTS_KEY`, `INLINE_COMMENTS_KEY` |
 | `cli/helpers.py` | File/directory/stdin conversion helpers |
@@ -31,8 +32,15 @@ The **Direct** pipeline (`parse_to_tree` → `transform` → `to_lark` → `reco
 | `cli/hq.py` | `hq` CLI entry point — query dispatch, formatting, optional operator |
 | `hcl2/query/__init__.py` | Public query API exports |
 | `hcl2/query/_base.py` | `NodeView` base class, view registry, `view_for()` factory |
+| `hcl2/query/body.py` | `DocumentView`, `BodyView` facades for top-level and body queries |
+| `hcl2/query/blocks.py` | `BlockView` facade for block queries |
+| `hcl2/query/attributes.py` | `AttributeView` facade for attribute queries |
+| `hcl2/query/containers.py` | `TupleView`, `ObjectView` facades for container queries |
+| `hcl2/query/expressions.py` | `ConditionalView` facade for conditional expressions |
+| `hcl2/query/functions.py` | `FunctionCallView` facade for function call queries |
+| `hcl2/query/for_exprs.py` | `ForTupleView`, `ForObjectView` facades for for-expressions |
 | `hcl2/query/path.py` | Structural path parser (`PathSegment`, `parse_path`, `[select()]`, `type:name`) |
-| `hcl2/query/resolver.py` | Path resolver — segment-by-segment with label depth, type filter, FunctionCallView |
+| `hcl2/query/resolver.py` | Path resolver — segment-by-segment with label depth, type filter |
 | `hcl2/query/pipeline.py` | Pipe operator — `split_pipeline`, `classify_stage`, `execute_pipeline` |
 | `hcl2/query/builtins.py` | Built-in transforms: `keys`, `values`, `length` |
 | `hcl2/query/diff.py` | Structural diff between two HCL documents |
@@ -65,12 +73,13 @@ Follows the `json` module convention. All option parameters are keyword-only.
 
 - `load/loads` — HCL2 text → Python dict
 - `dump/dumps` — Python dict → HCL2 text
+- `query` — HCL2 text/file → `DocumentView` for structured queries
 - Intermediate stages: `parse/parses`, `parse_to_tree/parses_to_tree`, `transform`, `serialize`, `from_dict`, `from_json`, `reconstruct`
 
 ### Option Dataclasses
 
 **`SerializationOptions`** (LarkElement → dict):
-`with_comments`, `with_meta`, `wrap_objects`, `wrap_tuples`, `explicit_blocks`, `preserve_heredocs`, `force_operation_parentheses`, `preserve_scientific_notation`
+`with_comments`, `with_meta`, `wrap_objects`, `wrap_tuples`, `explicit_blocks`, `preserve_heredocs`, `force_operation_parentheses`, `preserve_scientific_notation`, `strip_string_quotes`
 
 **`DeserializerOptions`** (dict → LarkElement):
 `heredocs_to_strings`, `strings_to_heredocs`, `object_elements_colon`, `object_elements_trailing_comma`

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 |