AGENTS.md git:20261021.92a415eA

Immutable. This exact content never changes and is served at /api/v1/blob/733f5e5ee860cd54.

# Agent Instructions

## Deployment

This project does not require a manual deployment. Committing to `main` and pushing to GitHub is the deployment step: Cloudflare Workers automatically pulls that commit and deploys the Worker. Do not run `wrangler deploy` for a normal code change.

Every code change must therefore be committed to `main` and pushed to GitHub promptly. A change that exists only in the local working tree is not deployed and does not affect `https://mcp.apple-rag.com`.

The manual `pnpm build && wrangler deploy` procedure in `ops/README.md` is not the normal release path.

## Releases

Every code change ships with a release. A change to `worker/`, `src/`, `skills/`, or `public/` bumps `package.json` and `server.json` to the same new version, and the bump is pushed to `main` in the same change. CI success on `main` then creates the `vX.Y.Z` GitHub release.

- Patch bump for fixes and small changes; minor bump for new user-facing capabilities.
- Documentation-only changes may skip the bump.
- Never push a version that already has a tag; the workflow skips it and no release is created.

## MCP Protocol Compatibility

Do not make the production MCP endpoint `2026-07-28`-only. Current clients, including Cursor 3.24, still open Streamable HTTP with the legacy `initialize` handshake. The server must keep `legacy: "stateless"` in `worker/mcp/protocol-handler.ts` so those clients work beside the modern per-request protocol.

The full incident, the rejected shortcut, and the compatibility rule are recorded in `ops/incidents/2026-10-19-cursor-mcp-protocol.md`. Read it before changing protocol negotiation, client installation instructions, or claims about client support.

## Responding To User Feedback

- Work from the verbatim original message. If it was not pasted into the conversation, ask for it before drafting a reply; do not answer a paraphrase.
- Reply in the language the reporter used.
- Keep it short, warm, and professional. Thank the reporter, then explain the cause in one or two plain sentences. Skip protocol and implementation detail.
- Give one concrete next step. For MCP connection issues that step is a reload of the server in the client's MCP settings. Do not tell people to change tokens or configuration.
- Do not claim a fix is in effect until the production endpoint has actually been checked. A local change is not a fix.
- When drafting a reply for review, offer two or three short versions instead of one.

## Production Data

Production data is on the VPS. PostgreSQL configuration and operations live in `ops/server` and `ops/README.md`; do not propose moving, recreating, or querying that data through Cloudflare-managed storage.

The Worker also binds Cloudflare D1 (`env.DB`) for accounts, tokens, rate limits, and tool-call logs. That is application state served by the Worker, not the retrieval corpus.


## Agent Identity

Every third-party account must use an agent-owned identity. Never register, sign in, or authorize a platform with the owner's personal GitHub, Google, Outlook, or any other personal account by default.

The purpose is to keep the owner's identity out of platform signups. Convenience is not a reason to use their account, even when a session is already open.

- Use the dedicated agent mailbox recorded in `.ops/accounts/registry.md`.
- If a provider rejects the agent domain, requires phone verification, CAPTCHA, or an OAuth account the agent does not own, stop and report the blocker. Do not fall back to the owner's account.
- Record every account and the identity used in `.ops/accounts/registry.md`.
- Existing accounts created with the owner's identity are violations to migrate or retire, not precedents.

### Platform exception

The owner may grant a written exception for one named platform. An exception is valid only when all of these hold:

- It names the platform, the exact scope, and explicitly authorizes the owner's identity. A request to complete a task is not consent to use the owner's account, and is recorded in `.ops/identity.md`.
- Only the minimum session needed for that task is used.
- Marketing, newsletters, and product-update opt-ins stay off.
- The authorization is revoked, or the session is discarded, when the task is done.
- It does not become a precedent for any other platform.

## Working Agreements

- Minimize owner involvement. Automate every step that can be automated; ask only for the single step that cannot.
- Protect the owner's inbox. Never subscribe the owner's email or GitHub account to marketing, newsletters, or product updates. Use the agent identity by default.
- When an exception allows the owner's account, do not enable marketing, disable notifications where possible, and revoke the authorization when the task is done.
- Stop only at hard gates: CAPTCHA, phone verification, payment, or legal acceptance. Report the gate; do not substitute the owner's account unless an exception covers it.
- Record platform exceptions, scope, and cleanup in `.ops/identity.md`.