# 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).
- 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.
- Gemini quota fallback is `gemini-3.6-flash` (ADR-138); 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.

## Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project.
Do not repeat what the codebase already shows; point to the authoritative file or command instead.
Prefer rewriting or pruning existing entries over appending new ones.
When updating this file, preserve this bar for all agents and keep entries concise.