feat: agent-UX — point K-PAR-001 end-tag errors at kida check (#112)

Agents doing bulk template migrations in downstream repos (e.g. IA
rewrites across dozens of `{% call %}`/`{% if %}` nests) hit parse
errors one rendered route at a time because no error message told
them `kida check <dir> --strict --validate-calls` batch-validates
the whole directory. The CLI already existed; the agent-UX gap was
that nothing surfaced it.

Adds `BULK_CHECK_TIP` in `kida.parser.errors`, appended to the five
K-PAR-001 end-tag mismatch paths: orphan `{% end %}`, mismatched
closing tags, and typed-end mismatches. AGENTS.md gains a
"downstream bulk-edit agents" bullet under "Who reads your output"
so future error-message work treats them as a first-class reader.

No test assertions rely on the exact suggestion strings; 4116 tests
pass, ruff/ty clean.

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

Author: lbliii

AGENTS.md

@@ -42,6 +42,7 @@ Kida is shipped (Bengal and Chirp depend on it) and pre-1.0. Calibrate according
 
 - **Framework builders** — Bengal, Chirp. They read `template_metadata()`, `block_metadata()`, tracebacks with line/col, and your error messages when their users misuse a tag.
 - **SSG authors** — read `kida check` / `kida format` output. If your error doesn't include the template path and a fix, it's wrong.
+- **Agents doing bulk template edits in downstream repos** — the whack-a-mole case. An agent migrating an IA across dozens of `{% call %}`/`{% if %}` nests finds parse errors one rendered route at a time unless we tell them about `kida check <dir> --strict --validate-calls`. Parser errors on unmatched `{% end %}` should surface that tip; agent-facing docs should lead with it.
 - **Migrators from Jinja2** — want to be done in five minutes. The `set` vs `let` trap is the #1 thing they hit. Error messages should *catch them*, not let them debug it themselves.
 - **Contributors** — know templating, not our internals. They read parser/compiler files; mixin patterns are surprising.
 - **Me (Lawrence)** — read diffs. Put the *what* in code, the *why* in the PR.

CHANGELOG.md

@@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`kida check --lint-fragile-paths`** — Opt-in lint rule that flags cross-template references whose target lives in the same folder as the caller (e.g. `{% include "pages/card.html" %}` from `pages/about.html`) and suggests the refactor-safe `./card.html` form. The rule covers `{% include %}`, `{% extends %}`, `{% embed %}`, `{% import %}`, and `{% from ... import %}`; references that already use `./`, `../`, or `@alias/` are ignored, and only exact same-folder matches are flagged to keep false-positives low. Default `kida check` behavior is unchanged — the rule only runs when the flag is passed.
 - **Refactor-safe templates tutorial** — New `site/content/docs/tutorials/refactor-safe-templates.md` walks through the folder-move problem, when to use `./` / `../` vs `@alias/`, and a step-by-step migration recipe using `ripgrep`. Cross-linked from the tutorials index and `docs/syntax/includes.md`.
 - **Namespace aliases for template paths** — `Environment(template_aliases={...})` maps short `@name/` prefixes to root-relative subtrees so cross-cutting component libraries stop being path-coupled. With `template_aliases={"components": "ui/components", "layouts": "ui/layouts"}`, templates can write `{% include "@components/card.html" %}` or `{% extends "@layouts/base.html" %}` regardless of where the caller lives — aliases resolve before loader lookup, so the same prefix works in every cross-template statement (`{% include %}`, `{% extends %}`, `{% embed %}`, `{% from ... import ... %}`). Aliases and `./`/`../` relative paths are orthogonal modes; aliases always resolve to an absolute root, so there is no composition of the two. Unknown aliases raise `TemplateNotFoundError` with the list of configured aliases.
+- **K-PAR-001 end-tag errors now point at `kida check`** — Orphan `{% end %}`, mismatched closing tags (e.g. `{% endfor %}` against an open `{% if %}`), and typed-end mismatches (e.g. `{% endblock %}` inside a `{% def %}`) now append a tip telling the reader to run `kida check <templates-dir> --strict` to surface every mismatch across the directory at once. Agents and humans doing bulk template migrations were discovering these one rendered route at a time; the CLI already batch-validates, but nothing in the error message said so. New `BULK_CHECK_TIP` constant in `kida.parser.errors`, wired into the five end-tag mismatch paths across `parser/statements.py`, `parser/core.py`, and `parser/blocks/core.py`. `AGENTS.md` gains an "Agents doing bulk template edits in downstream repos" bullet under "Who reads your output" to make the audience explicit for future error-message work.
 
 ## [0.8.0] - 2026-04-21
 

src/kida/parser/blocks/core.py

@@ -126,21 +126,27 @@ def _pop_block(self, expected: str | None = None) -> str:
             ParseError: If no blocks are open or if expected doesn't match.
         """
         if not self._block_stack:
+            from kida.parser.errors import BULK_CHECK_TIP
+
             raise self._error(
                 "Unexpected closing tag - no open block to close",
-                suggestion="Remove this tag or add a matching opening tag",
+                suggestion=f"Remove this tag or add a matching opening tag.\n\n{BULK_CHECK_TIP}",
             )
 
         popped: tuple[str, int, int] = self._block_stack.pop()
         block_type, lineno, _col = popped
 
         # If a specific block type is expected, validate it
         if expected and block_type != expected:
+            from kida.parser.errors import BULK_CHECK_TIP
+
             raise self._error(
                 f"Mismatched closing tag: expected {{% end{expected} %}}, "
                 f"but found closing tag for '{block_type}' block opened at line {lineno}",
-                suggestion=f"Use {{% end %}} to close the innermost block, "
-                f"or {{% end{block_type} %}} to be explicit",
+                suggestion=(
+                    f"Use {{% end %}} to close the innermost block, "
+                    f"or {{% end{block_type} %}} to be explicit.\n\n{BULK_CHECK_TIP}"
+                ),
             )
 
         return block_type
@@ -205,9 +211,11 @@ def _consume_end_tag(self, block_type: str) -> None:
             self._advance()  # consume 'endXXX'
             self._pop_block(block_type)  # Pop with type validation
         else:
+            from kida.parser.errors import BULK_CHECK_TIP
+
             raise self._error(
                 f"Expected 'end' or 'end{block_type}', got '{keyword}'",
-                suggestion="Use {% end %} to close the innermost block",
+                suggestion=f"Use {{% end %}} to close the innermost block.\n\n{BULK_CHECK_TIP}",
             )
 
         self._expect(TokenType.BLOCK_END)

src/kida/parser/core.py

@@ -161,9 +161,11 @@ def parse(self) -> Template:
         if self._current.type == TokenType.BLOCK_BEGIN:
             next_tok = self._peek(1)
             if next_tok.type == TokenType.NAME and next_tok.value in self._end_keywords:
+                from kida.parser.errors import BULK_CHECK_TIP
+
                 raise self._error(
                     f"Unexpected '{{% {next_tok.value} %}}' - no open block to close",
-                    suggestion="Remove this tag or add a matching opening tag",
+                    suggestion=f"Remove this tag or add a matching opening tag.\n\n{BULK_CHECK_TIP}",
                 )
             # Also check for orphan continuation keywords
             if next_tok.type == TokenType.NAME and next_tok.value in self._CONTINUATION_KEYWORDS:

src/kida/parser/errors.py

@@ -23,6 +23,16 @@
 }
 
 
+# Appended to suggestions for bulk end-tag mismatches (extra, mismatched, or
+# orphan end tags). Points agents doing multi-file migrations at `kida check`
+# so they stop discovering errors one rendered route at a time.
+BULK_CHECK_TIP: str = (
+    "Tip: run `kida check <templates-dir> --strict` to surface every "
+    "end-tag mismatch across the directory in one pass, instead of "
+    "discovering them one rendered page at a time."
+)
+
+
 class ParseError(TemplateSyntaxError):
     """Parser error with rich source context.
 

src/kida/parser/statements.py

@@ -323,9 +323,11 @@ def _handle_end_keyword(self, keyword: str) -> None:
         """
         # End tag without matching opening block
         if not self._block_stack:
+            from kida.parser.errors import BULK_CHECK_TIP
+
             raise self._error(
                 f"Unexpected '{keyword}' - no open block to close",
-                suggestion="Remove this tag or add a matching opening tag",
+                suggestion=f"Remove this tag or add a matching opening tag.\n\n{BULK_CHECK_TIP}",
             )
 
         # Check if end tag matches the innermost block
@@ -340,9 +342,14 @@ def _handle_end_keyword(self, keyword: str) -> None:
             return None
         else:
             # Mismatched end tag
+            from kida.parser.errors import BULK_CHECK_TIP
+
             raise self._error(
                 f"Mismatched closing tag: expected '{{% {expected_end} %}}' or '{{% end %}}', got '{{% {keyword} %}}'",
-                suggestion=f"The innermost open block is '{innermost_block}' (opened at line {self._block_stack[-1][1]})",
+                suggestion=(
+                    f"The innermost open block is '{innermost_block}' "
+                    f"(opened at line {self._block_stack[-1][1]}).\n\n{BULK_CHECK_TIP}"
+                ),
             )
 
     def _skip_comment(self) -> None: