From 9fd3c497234d5cb00ca0e932a2b9d477ef5aa074 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 4 Aug 2026 17:00:10 +0200 Subject: [PATCH] docs(agents): symlink editing rule, crates.io UA, jq optional chaining Signed-off-by: Sebastian Mendel --- AGENTS.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 6c621be..977c44d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,6 +13,10 @@ - Ask before: heavy deps, full rewrites, breaking changes - Never commit secrets, PII, or credentials +## Editing these instructions + +`AGENTS.md` is canonical; `CLAUDE.md` is a symlink to it (root and scoped dirs alike). Edit the resolved `AGENTS.md` target — editing `CLAUDE.md` fails the Edit-tool symlink guard. + ## Setup **This project uses [uv](https://docs.astral.sh/uv/) for package management.** Always use `uv run` to execute Python commands. @@ -109,6 +113,11 @@ This repo **is** a CLI tool manager, so the word "upgrade" is overloaded: | `uv run python audit.py --versions` | Show multi-version runtime status | | `uv run python audit.py --versions php` | Show specific runtime versions | +## External API gotchas + +- **crates.io requires a User-Agent** (`curl -fsSL -A "cli-audit" https://crates.io/api/v1/crates/`) — without it the response is non-JSON and parsing throws. The package-version MCP tools do not cover crates/cargo; manual curl is the fallback. +- **Default to jq optional chaining** over external API JSON (`.arr[]?`, `.field?`): iterating a null/absent array with `.arr[]` aborts the whole pipeline (`Cannot iterate over null`), killing loops on one empty response. Safe even when the field is usually present. + ## Data files **2-file data model** (Phase 2.1):