release: prepare v0.6.0 — version bump, changelog, docs update (#93)

Bump version to 0.6.0, add changelog and release notes for component
framework (#90), kida readme CLI (#89), and sharp-edge fixes (#91, #92).
Update all doc version references from 0.5.0 to 0.6.0. Add documentation
for three new CLI commands (components, readme, extract), strict_undefined
and jinja2_compat_warnings config options, DefMetadata/DefParamInfo
introspection API, component call stack in errors, compile-time warnings,
and enhanced UndefinedError with kind field.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: lbliii

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-13
+
+### Added
+
+- **Component framework** — Def introspection API (`DefMetadata`, `DefParamInfo`, `list_defs`, `def_metadata`), component call stack in error reporting, `kida components` CLI command, type-aware prop validation with `TypeMismatch` diagnostics, Components Guide and Jinja2-vs-Kida comparison docs. (#90)
+- **`kida readme` CLI** — Auto-generates README.md from project metadata (pyproject.toml, filesystem, git). Ships 4 preset templates (default, minimal, library, cli) with `--set` overrides and `--json` debug mode. (#89)
+
+### Fixed
+
+- **Sandbox `max_output_size` enforcement** — Was declared but never checked; now enforced. (#91)
+- **Block capture rejection** — `{% set x %}...{% endset %}` block capture rejected at parse time. (#91)
+- **Error codes for all SecurityError raises** — K-SEC-001 through K-SEC-005. (#91)
+- **Autoescape validation at construction** — Invalid autoescape mode now rejected at `Environment()` creation, not first compile. (#91)
+- **Structured errors** — All bare `RuntimeError` raises replaced with `TemplateRuntimeError`. (#91)
+- **Optional chaining display** — `?.` now renders `""` instead of `"None"` in display context. (#91)
+- **Broken `except` clauses** — Fixed 32 `except X, Y:` clauses (Python 2 syntax that only catches the first type). (#92)
+- **`render_with_blocks()` validation** — Unknown block names now raise with did-you-mean suggestions. (#92)
+- **Unknown compiler node types** — Now raises instead of silently ignoring. (#92)
+- **CLI check error reporting** — Errors no longer swallowed silently. (#92)
+- **`_Undefined.get()` API** — Fixed to match expected semantics. (#92)
+
+### Changed
+
+- **New warnings** — `PrecedenceWarning` (K-WARN-001) for `?? + |` without parens, `CoercionWarning` for silent filter type coercion, `MigrationWarning` (K-WARN-002) for `set` scoping with `jinja2_compat_warnings` flag. (#91)
+- **`strict_undefined` mode** — Opt-in `Environment(strict_undefined=True)` for catching attribute typos. (#92)
+- **`UndefinedError` context** — Attribute/key lookups now say "Undefined attribute/key" instead of "Undefined variable". (#92)
+- **ErrorCode coverage** — Pushed from 21 to 73+ raise sites with full docs for all 38 ErrorCode values. (#91)
+
 ## [0.5.0] - 2026-04-12
 
 ### Added

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "kida-templates"
-version = "0.5.0"
+version = "0.6.0"
 description = "Python component framework for HTML — typed props, named slots, scoped state, error boundaries, zero JavaScript"
 readme = "README.md"
 requires-python = ">=3.14"

site/content/docs/advanced/sandbox.md

@@ -71,7 +71,7 @@ env = SandboxedEnvironment(sandbox_policy=policy)
 | `allow_import` | `bool` | `False` | Whether `__import__` is available in templates. |
 | `allow_mutating_methods` | `bool` | `False` | Whether mutating collection methods (`append`, `pop`, `clear`, etc.) are accessible. |
 | `allow_calling` | `frozenset[str] \| None` | `None` | Set of type names whose instances may be called. `None` permits all callables. An empty `frozenset()` blocks all calls. |
-| `max_output_size` | `int \| None` | `None` | Maximum render output length in characters. `None` means unlimited. |
+| `max_output_size` | `int \| None` | `None` | Maximum render output length in characters. Raises `SecurityError` (K-SEC-005) when exceeded. `None` means unlimited. |
 | `max_range` | `int` | `10000` | Maximum `range()` size allowed in templates. |
 
 `SandboxPolicy` is a frozen dataclass -- construct a new instance for each configuration.

site/content/docs/get-started/installation.md

@@ -67,7 +67,7 @@ uv sync
 
 ```python
 import kida
-print(kida.__version__)  # 0.5.0
+print(kida.__version__)  # 0.6.0
 ```
 
 Or from the command line:

site/content/docs/reference/api.md

@@ -42,6 +42,9 @@ env = Environment(
 | `fragment_cache_size` | `int` | `1000` | Max cached fragments |
 | `fragment_ttl` | `float` | `300.0` | Fragment TTL (seconds) |
 | `static_context` | `dict \| None` | `None` | Values for compile-time partial evaluation |
+| `strict_undefined` | `bool` | `False` | Raise on missing attribute access |
+| `jinja2_compat_warnings` | `bool` | `False` | Warn on `{% set %}` scoping differences |
+| `validate_calls` | `bool` | `False` | Validate `{% def %}` call sites at compile time |
 
 ### Methods
 
@@ -209,7 +212,7 @@ layout = env.get_template("_layout.html")
 html = layout.render_with_blocks({"content": inner_html}, title="Page")
 ```
 
-Each key in `block_overrides` names a block; the value is a pre-rendered HTML string.
+Each key in `block_overrides` names a block; the value is a pre-rendered HTML string. Unknown block names now raise `TemplateRuntimeError` with did-you-mean suggestions.
 
 #### render_block_stream_async(block_name, **context)
 
@@ -231,7 +234,62 @@ blocks = template.list_blocks()
 # ['title', 'nav', 'content', 'footer']
 ```
 
-### Introspection (frameworks, build systems)
+### Component Introspection
+
+#### list_defs()
+
+List all `{% def %}` component names in the template.
+
+```python
+names = template.list_defs()
+# ['card', 'nav_link', 'badge']
+```
+
+#### def_metadata()
+
+Return metadata for all `{% def %}` components in the template. Returns a `dict[str, DefMetadata]`.
+
+```python
+meta = template.def_metadata()
+card = meta["card"]
+print(card.name)              # "card"
+print(card.template_name)     # "components/card.html"
+print(card.lineno)            # 3
+print(card.params)            # (DefParamInfo(name='title', annotation='str', ...), ...)
+print(card.slots)             # ('actions', 'footer')
+print(card.has_default_slot)  # True
+```
+
+**DefMetadata** fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `str` | Component name |
+| `template_name` | `str \| None` | Source template |
+| `lineno` | `int` | Line number of `{% def %}` |
+| `params` | `tuple[DefParamInfo, ...]` | Parameter metadata |
+| `slots` | `tuple[str, ...]` | Named slot names |
+| `has_default_slot` | `bool` | Whether `{% slot %}` (unnamed) exists |
+
+**DefParamInfo** fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `str` | Parameter name |
+| `annotation` | `str \| None` | Type annotation (e.g. `"str"`, `"int"`) |
+| `has_default` | `bool` | Whether a default value is defined |
+| `is_required` | `bool` | `True` if no default value |
+
+#### warnings
+
+Compile-time warnings collected during template compilation.
+
+```python
+for w in template.warnings:
+    print(w.code, w.message, w.lineno)
+```
+
+### Template Introspection (frameworks, build systems)
 
 #### template_metadata()
 
@@ -299,6 +357,7 @@ template.is_cacheable()       # True only if all blocks cacheable
 | `name` | `str \| None` | Template name |
 | `filename` | `str \| None` | Source filename |
 | `is_async` | `bool` | `True` if template uses `{% async for %}` or `{{ await }}` |
+| `warnings` | `list[TemplateWarning]` | Compile-time warnings (precedence, coercion, migration) |
 
 > **Note**: Calling `render()` or `render_stream()` on a template where `is_async` is `True` raises `TemplateRuntimeError`. Use `render_stream_async()` instead.
 
@@ -499,7 +558,7 @@ Classify block metadata into framework roles: `"fragment"`, `"page_root"`, or `N
 
 ### TemplateError
 
-Base class for all template errors.
+Base class for all template errors. All Kida exceptions carry an `ErrorCode` accessible via `exc.code`.
 
 ### TemplateSyntaxError
 
@@ -514,9 +573,24 @@ except TemplateSyntaxError as e:
     print(e)
 ```
 
+### TemplateRuntimeError
+
+Error during template rendering. Includes `component_stack` for errors inside `{% def %}` components:
+
+```python
+from kida import TemplateRuntimeError
+
+try:
+    template.render(items=None)
+except TemplateRuntimeError as e:
+    print(e.code)             # ErrorCode enum value
+    print(e.component_stack)  # [(def_name, lineno, template_name), ...]
+    print(e.format_compact()) # Formatted error with source snippet
+```
+
 ### TemplateNotFoundError
 
-Template file not found.
+Template file not found. Includes caller context (requesting template and line number).
 
 ```python
 from kida import TemplateNotFoundError
@@ -529,17 +603,41 @@ except TemplateNotFoundError as e:
 
 ### UndefinedError
 
-Accessing undefined variable.
+Accessing undefined variable or attribute. The `kind` field distinguishes between variable, attribute, and key lookups.
 
 ```python
 from kida import UndefinedError
 
 try:
     env.from_string("{{ missing }}").render()
 except UndefinedError as e:
-    print(e)
+    print(e.kind)  # "variable", "attribute", or "key"
+    print(e)       # "Undefined variable 'missing' in <string>:1"
 ```
 
+With `strict_undefined=True`, attribute access errors also include component context:
+
+```python
+env = Environment(strict_undefined=True)
+# "Undefined attribute 'typo' on User object in page.html:5"
+```
+
+### SecurityError
+
+Raised by `SandboxedEnvironment` when a template violates the security policy. Carries error codes K-SEC-001 through K-SEC-005.
+
+### Warning Classes
+
+Compile-time warnings emitted during template compilation:
+
+| Class | Code | Description |
+|-------|------|-------------|
+| `PrecedenceWarning` | K-WARN-001 | `\|` binds tighter than `??` |
+| `CoercionWarning` | — | Silent type coercion in filters (e.g. `"abc" \| float` → `0.0`) |
+| `MigrationWarning` | K-WARN-002 | `{% set %}` scoping differs from Jinja2 |
+
+These are standard Python warnings and can be filtered with `warnings.filterwarnings`.
+
 ---
 
 ## Markup