ask-llm AGENTS.md

Project agent memory

This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.

• Build/test: yarn install --immutable, then yarn build (topological — run it BEFORE yarn test; workspace tests resolve sibling packages from dist/, so unbuilt @ask-llm/shared fails every suite). Lint via yarn lint (biome format is enforced; biome check --write fixes). Harness-facing changes use the canonical local-only yarn prepr:harness gate; opt-in live authorization and evidence rules are in docs/HARNESS-SMOKE.md.
• Architecture decisions live in docs/DECISIONS.md (numbered ADRs, newest prepended at the top); provider behavior differences are deliberate and cataloged in docs/PROVIDER-PARITY.md — read both before "aligning" providers.
• Docs-model drift is CI-enforced: scripts/check-docs-drift.mjs requires apps/docs/.vitepress/theme/providers.ts defaultModel (and gemini/antigravity fallbackModel) values to match each package's constants.ts literally, matched inside each provider's own object block. Change both together.
• MCP Registry rejects duplicate versions. Keep normal and recovery publication routed through scripts/publish-mcp-registry.mjs; it verifies exact existing records and publishes only missing ones (ADR-139). A manual registry retry must not re-enter npm publication.
• Public package source tags are remote <name>@<version> refs managed only by scripts/create-or-verify-package-tags.mjs on normal and recovery release paths (ADR-151/152); changesets/action v2 must keep both create-github-releases: false and push-git-tags: false, while the helper excludes private shared, never retags/forces, and coexists with the single unified v* GitHub Release.
• Gemini quota fallback is gemini-3.7-flash (ADR-154); the antigravity fallback stays gemini-3.5-flash deliberately — agy slugs are evidence-pinned to its live catalog (ADR-137), so never bump both in sympathy.
• Provider default-model constants leak further than the provider package: packages/llm-mcp/src/constants.ts (PROVIDERS.*.defaultModel) is threaded into executors as options.model by machine.ts, so executors cannot use "was a model passed?" to detect user pins (see ADR-137).
• agy (Antigravity) CLI ground truth for this repo's executor is recorded in ADR-137 (minimum 1.1.5, base slug + separate --effort, per-slug effort tiers, the live-captured invalid model selection error grammar) and ADR-141 (answers come from --output-format json stdout — key response, usage object — on every supported version; --disable-slash-commands is 1.1.9+ only).
• Grok transport and model identity are separate (ADR-146/147; /brainstorm exact Grok + Sol routing and partial-consensus rules are in ADR-148): unified startup probes both xai-api and grok-cli readiness because request-level harness selection happens later (an explicit ASK_GROK_HARNESS narrows readiness to that default), but execution selects exactly one explicit/default harness with no failover; Cursor Agent is a model-neutral harness (ask-cursor-agent) requiring separate provider + exact Cursor catalog ID, never a provider itself.
• @ask-llm/plugin is the one publishable Claude Code + Cursor Agent + Pi host package (ADR-142/147); host contracts live in the skill adapters, apps/docs/plugin/cursor.md, and docs/PI-COMPATIBILITY.md. Cursor uses Agent Skills + a unified-only mcp.json (one ask-llm entry; split Codex/Grok servers are optional user installs whose leaves are preferred when exposed) exposing exactly codex-pair/grok-pair (explicit empty agents/commands/hooks so Claude agents and hooks/hooks.json are not auto-discovered; other skills deferred), never Claude hooks/namespaces; the Claude plugin .mcp.json bundles only Codex while @ask-llm/mcp/@ask-llm/grok-mcp stay user-scoped, and pair skills call unified ask-llm only fully pinned; Pi excludes fable-review/grok-pair, uses native provider tools, and codex-pair requires marker + project trust + a user-owned canonical-project allowlist. The published Pi host floor must equal the oldest exact pi-package-smoke matrix pin (currently 0.83.0).