Skip to content

docs(agents): symlink editing rule, crates.io UA, jq optional chaining #139

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
CybotTM merged 1 commit into from
Aug 4, 2026
Merged

docs(agents): symlink editing rule, crates.io UA, jq optional chaining #139

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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/<name>`) — 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):
Expand Down