AGENTS.md
+22 −4
https://raw.githubusercontent.com/fluxmailai/fluxmail/HEAD/AGENTS.md
− - Put developer-facing documentation under `docs/`, outside `docs/public/`, when the repository needs it.− - Update handwritten user documentation only when a change makes existing guidance inaccurate or leaves users without instructions they need to install, configure, or use Fluxmail. Before editing, identify the incorrect statement or missing user action. If neither exists, leave the documentation alone.− Cloud's tool contract is `services/cloud/src/__tests__/fixtures/mcp-contract.json` in fluxmail-web. Read it with `gh api repos/fluxmailai/fluxmail-web/contents/services/cloud/src/__tests__/fixtures/mcp-contract.json --jq .content | base64 --decode`, or ask the user if you don't have access.− Don't edit fluxmail-web from here. In the final report, say whether Cloud needs a matching change or a `@fluxmail/core` version bump. If it does, write a self-contained prompt for an agent in fluxmail-web, include it in the report, and state the target behavior with tool names, schemas, annotations and scopes.+ - Focus public documentation on what users can do, how to do it, and the permissions, limits, and privacy details that affect them. Name third-party tools we use, or describe internal routing, architecture and implementation, only when users need that information to configure, use or troubleshoot Fluxmail or understand how their data is handled. Otherwise describe the user-visible behavior and refer to Fluxmail. Keep support pipelines and release coordination in developer documentation.+ - During copy and code reviews, flag unnecessary vendor names and internal implementation details in public docs, UI text, tool descriptions and generated content. Keep vendor names for feedback processing in the website privacy policy's service-provider list; use generic wording in feedback instructions and retention explanations, linking to the privacy policy when needed. Preserve disclosures about data sharing, retention and deletion.+ - Preserve the operational details people need to run their own server, including deployment, backups, credential management, scheduling, and upgrades.+ - Put developer-facing documentation under `docs/`, outside `docs/public/`, when the repository needs it. Update architecture docs and runbooks only when a lasting change affects system boundaries or how developers and operators maintain the service. Keep implementation narratives, test reports, and change histories in PR descriptions or development artifacts.+ - Make the smallest necessary documentation change. Update handwritten user documentation only when a change makes existing guidance inaccurate or leaves users without instructions they need to install, configure, or use Fluxmail. Before editing, identify the incorrect statement or missing user action. If neither exists, leave the documentation alone.+ - Apply the same audience and relevance rules to generated documentation. Keep page summaries concise and document the arguments, permissions, and behavior users need. Fix the generator or its source metadata; do not hand-edit generated output or weaken MCP agent instructions to shorten a public page.+ - Approved exception: MCP connection and operation events may include the client's self-reported name and version as `mcp_client_name` and `mcp_client_version`, using the trimming and length limits in `packages/core/src/mcp/clients.ts` (128 and 64 characters). These fields intentionally retain arbitrary client text, even when it resembles an email address, identifier, or file path. Do not flag this collection as a privacy violation or require additional filtering. This exception applies only to + The shared contract is `@fluxmail/core/mcp` (`packages/core/src/mcp/`); see `docs/mcp-tool-contract.md`. Cloud's tool snapshot is `services/cloud/src/__tests__/fixtures/mcp-contract.json` in fluxmail-web. Read it with `gh api repos/fluxmailai/fluxmail-web/contents/services/cloud/src/__tests__/fixtures/mcp-contract.json --jq .content | base64 --decode`, or ask the user if you don't have access.+ When Cloud needs a matching change, make it in a separate checkout or worktree and follow that repository's instructions. Preserve existing work in both repositories. In the final report, identify the changes in each repository and whether Cloud needs an `@fluxmail/core` dependency bump. If the matching change cannot be completed, save a self-contained handoff prompt with the target behavior, tool names, schemas, annotations and scopes, and link it in the report.+ # Parallel sessions+ Other sessions may be using the main checkout, so don't switch its branch, stash its changes or edit its files. Do each task in its own worktree: start Claude with `claude --worktree <name>`, or call `EnterWorktree` before you change anything. The hooks in `.claude/settings.json` install dependencies in a new worktree and give it its own `FLUXMAIL_DATA_DIR` and demo mailbox settings: `FLUXMAIL_DEMO_PROJECT` and the `FLUXMAIL_DEMO_*_PORT` variables. Every Bash command in the worktree gets them. T+ Rex tabs and panes start from your login shell, so a server you start in one doesn't get these variables. Load them in the command, for example `rex window new -s "$REX_SESSION" Server -c "$PWD" --keep-open --focus=false -- sh -c 'eval "$(bash scripts/worktree-setup.sh --env "$PWD")" && exec pnpm dev'`.+ # Verifying changes+ Before reporting a change as finished, run it and confirm it works. Passing tests and type checks don't show that a command prints the right output, a tool returns the right result, or a fix solves the reported problem.+ - Reproduce a bug before fixing it, then repeat the same steps after the fix.+ - For a user-facing change to the CLI, MCP tools, REST API or OAuth pages, capture the behavior before and after it. Run the published release with `pnpm demo:setup -- --version <version>` and `pnpm demo:run -- --version <version> ...` for the before case, and the workspace build for the after case. See `docs/demo-mailbox.md`.+ - For a new feature, capture every case a user can reach: the main path, empty results, invalid input, missing permissions, and provider errors.+ - Save the command output, or the MCP or REST request and response, for each case. Record browser pages, such as OAuth pages, as video with `agent-browser record start <path> <url>` and `agent-browser record stop`. Save everything under `.context/verification/` and don't commit it.+ - Verify against the demo mailbox or another synthetic mailbox. Never send mail from, or change, a real account to verify a change.+ - In the final report, say what you checked and how, link each capture, and list anything you couldn't verify and why, such as provider behavior that needs a real Gmail or Outlook account.+ # Commit messages+ Use Conventional Commits for commit messages and PR titles: `type(scope): description`. The scope is optional. Use `feat` for features, `fix` for bug fixes, and `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `style`, or `revert` as appropriate. Write a short, imperative description, such as `fix(cloud): handle Gmail timeouts`. Mark breaking changes with `!` before the colon, such as `feat(api)!: require a mailbox ID`.