tokscale AGENTS.md

AI Agent Guidelines

This document provides context for AI agents working on the Tokscale project.

Maintaining AGENTS.md Files

When updating AGENTS.md files, follow these principles:

• No hardcoded counts — Don't write "10 crates" or "5 modules"; these become outdated instantly
• No exhaustive lists — Prefer dynamic commands (ls crates/) over maintaining complete lists
• Document constraints, not descriptions — Focus on non-obvious behaviors, gotchas, and cross-crate dependencies
• Use nested AGENTS.md — Place crate-specific details in crates/{name}/AGENTS.md, not here
• Verify before documenting — Grep/read the code to confirm claims are accurate
• Delete outdated info — Outdated docs are worse than no docs

Authoring PR/Issue Content via gh CLI

When writing PR bodies, issue bodies, or comments through gh pr create, gh issue comment, etc.: prefer --body-file with a written-out file over inline --body heredocs.

Why: inline --body "$(cat <<'EOF' ... EOF)" patterns lead to recurring mistakes where backticks are written as \` (incorrectly escaping them inside a single-quoted heredoc where no escaping is needed). The literal \` then renders in GitHub markdown as backslash + backtick instead of inline code formatting.

DO:

• Write the body to /tmp/pr-body.md (or similar) with the Write tool, then gh pr create --body-file /tmp/pr-body.md
• For comment edits: gh api -X PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@/tmp/comment.md

DON'T:

• Use gh pr create --body "$(cat <<'EOF' ... \ ... ` ... EOF)" — single-quoted heredoc means backticks are already literal; escaping with `` \ `` is wrong and renders incorrectly.
• Use double-quoted heredoc for bodies containing backticks unless you intend command substitution.
• Hard-wrap paragraphs at ~80 columns inside PR/issue/comment bodies. GitHub's markdown collapses single newlines into spaces so the rendered output looks fine, but the raw markdown view is what reviewers and authors edit in, and mid-sentence line breaks read as if the prose was chopped. Write each paragraph as one continuous line and let the renderer wrap it. Same rule for blockquotes, list items that span multiple lines, and table cells. Hard wraps are still fine inside fenced code blocks where preserving line layout matters.