From 9e8650ae341e1c8dff964e102c15384878d8f819 Mon Sep 17 00:00:00 2001 From: dprevost-perso Date: Tue, 22 Sep 2026 19:28:37 -0400 Subject: [PATCH] docs: add a Docs section to AGENTS.md - packages/cddl/docs needs manual sync packages/cddl/docs/*.md hand-documents the AST with worked examples and isn't generated from ast.ts/parser.ts, so nothing keeps it in sync automatically. Found stale twice in this session alone (IsFloat missing from references.md/ranges.md; two whole operators, the OperatorType union, and worked examples missing from operators.md) - both only caught by manual review. Write it down so it stops being a surprise. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index d199199..6ecea9e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,18 @@ Each package has its own `.release-it.ts` (sharing common config from `.release-it.base.ts`) and version — there is no monorepo-wide version to keep in sync. +## Docs + +`packages/cddl/docs/*.md` hand-documents the AST (`ast.ts`/`parser.ts`) with +worked examples — it is not generated, so nothing keeps it in sync +automatically. Any AST change (a new operator, a new field, a changed shape) +needs a matching doc update in the same PR: check `packages/cddl/docs/` for +the relevant file(s), not just the type declarations, but every worked +example and enumerated list. This isn't hypothetical — `references.md`/ +`ranges.md` (missing `IsFloat`) and `operators.md` (missing two whole +operators, `OperatorType` union, numbered list, and worked examples) were +each found stale only by manual review, not by anything automated catching it. + ## Setup Node 24, pnpm pinned in `package.json#packageManager`.