AGENTS.md · aovestdipaperino/tokensave

Sections

1. Contributing
2. SQL query inventory
3. Build, lint, and test
4. Architecture
5. Setup and environment
6. Gotchas and workflow quirks

First lines (shown under the repo's MIT license)

# AGENTS.md

This file provides guidance to the agent when working with code in this repository.

## Fork-specific branch workflow

- Create new work branches in the user's fork rather than in the upstream
  repository. This rule applies to every fork. Use a work branch instead of
  working directly on `master`, unless the user explicitly requests a direct
  commit.
- Name branches `<type>/<short-description>`, using the same Conventional
  Commits types as commit messages (for example `feat/dart-annotations`,
  `fix/utf16-sync`, `refactor/resolver-lookup`, `ci/release-workflow`). Keep
  the description descriptive, lowercase, and hyphenated, and do not include
  the number of any issue or pull request associated with the work. Refer to
  issues and pull requests in commit messages and PR descriptions instead.
- Write commit messages and PR titles using
  [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`,
  `fix:`, `docs:`, `ci:`, `refactor:`, `test:`, `chore:`, with an optional
  scope such as `fix(db):`), as described in
  [CONTRIBUTING.md](CONTRIBUTING.md#commit-messages).

## Keeping agent guidance current

Treat `AGENTS.md` on the original repository's `master` branch
(`aovestdipaperino/tokensave`) as the baseline for shared repository guidance.
Before changing this file or preparing a branch for merge, compare it with the
latest upstream `master` version and incorporate missing shared instructions.
Preserve branch-specific instructions and intentional differences; do not
blindly replace the file. If upstream cannot be checked, disclose that limit.

Update this file in the same change whenever build/test commands, architecture,
tooling, contributor policies, or release workflows make its guidance outdated.
Keep shared rules synchronized between `master` and `beta`, and verify the
instructions against the affected branch's files before committing. Report any
remaining differences and why they are needed in the handoff.

## Graphs and diagrams

Every graph and diagram created or updated for repository documentation MUST
use Mermaid. Embed Mermaid source in fenced `mermaid` code blocks in Markdown
so GitHub can render it and contributors can edit it directly.

## README consistency and installation

Keep `README.md` synchronized between `master` and `beta`. Installation
instructions are the only permitted branch-specific difference in README
content; keep all other content the same.
Record this rule identically in both branches' `AGENTS.md` files.

- On `master`, preserve the stable installation guide: Homebrew
  (`brew install aovestdipaperino/tap/tokensave`), crates.io
  (`cargo install tokensave`), `cargo binstall tokensave`, Windows Scoop
  (add `https://github.com/aovestdipaperino/scoop-bucket` as the `tokensave`
  bucket, then `scoop install tokensave`), and prebuilt binaries from the
  latest release added to `PATH`. Retain the Cargo medium/lite variants and
  the documented release archive table.
- On `beta`, preserve installation directly from the beta branch:
  `cargo install --git https://github.com/aovestdipaperino/tokensave.git --branch beta --locked --force`.
  Retain the alternative of cloning `beta` and running
  `cargo build --release --locked` with the pinned toolchain, then adding
  the resulting binary to `PATH`, plus the source-based medium/lite variants.
  Keep the explanation that Homebrew, Scoop, crates.io, cargo-binstall, and
  published release binaries install stable releases; no prebuilt beta
  archives are published. Preserve the schema-migration/full-reindex notice,
  disposable-checkout advice, and link to the master guide for returning
  to stable.
- Preserve these installation differences when merging or synchronizing the
  branches.

## Beta announcement

`README.md` carries no beta announcement. The beta is described in the
"Trying the beta" section of `docs/guide/INSTALLATION.md` on `master`, which
also shows the explicit beta installation command. Keep that section current
with the new release features available on `beta`: when adding or changing
beta features, update its highlights and links, and describe only features
already available on the beta branch. When those features reach a stable
release, revise or remove the section so it continues to describe what is
available in beta beyond stable. Keep the installation instructions accurate
and link to the beta changelog for details.

## Documentation and GitHub Wiki

User documentation is published both as Markdown in `docs/guide/` and as the
[GitHub Wiki](https://github.com/aovestdipaperino/tokensave/wiki), and the two
MUST stay aligned. `docs/guide/` is the single source:
`.github/workflows/wiki.yml` regenerates the whole wiki from it with
`scripts/wiki/sync_wiki.py` on every relevant push to `master`. Never edit the
wiki directly, and never copy wiki content back by hand; direct wiki edits are
overwritten.

- Keep `README.md` a concise entry point: what tokensave is, the installation
  guide required above, the quick start, and the documentation table linking
  into `docs/guide/`. Put detailed explanations in the matching guide page.
- When a change adds, removes, or changes user-visible behavior (a command,
  flag, MCP tool, configuration field, environment variable, supported agent,
  language, or default), update the affected `docs/guide/` pages, and the
  README if it mentions the behavior, in the same change. A pull request that
  changes such behavior without the matching documentation update is
  incomplete.
- Describe each topic on one guide page and link to it elsewhere. The
  installation commands are the one intended duplicate: keep
  `docs/guide/INSTALLATION.md` consistent with the README installation guide
  and the branch-specific installation rules above. The README keeps only the
  common methods; less common ones, such as installing from upstream
  `master`, live only in `docs/guide/INSTALLATION.md` and are linked from the
  README.
- New guide pages use uppercase, hyphenated file names, a single `# Title`
  (the wiki page is named after it), and an entry in both the `wiki-sidebar`
  list in `docs/guide/README.md` and the README documentation table.
- Before finishing, run `python3 scripts/wiki/sync_wiki.py check` and
  `python3 -m unittest discover -s scripts/wiki`, and report the results.
- The wiki describes `master` (stable) only. On `beta`, `docs/guide/` describes
  beta behavior and is not published; keep its page structure the same as on
  `master` so the branches can be synchronized like `README.md`.
- Design notes, evaluations, and reports remain in `docs/` outside
  `docs/guide/` and are not published to the wiki.

See [CONTRIBUTING.md](CONTRIBUTING.md#documentation) for the contributor-facing
version of these rules.

## Contributing

Follow [CONTRIBUTING.md](CONTRIBUTING.md) when changing this repository, including
its mandatory [memory and resource management requirements](CONTRIBUTING.md#memory-and-resource-management).
Use the resource review checklist for resource-sensitive changes and report the
checks actually performed, their results, and any limitations in the pull request.

Follow the [GitHub issue lifecycle rules](CONTRIBUTING.md#github-issue-lifecycle):
create issues for identified bugs and enhancements, link PRs with "Refs #N" (never
"Fixes #N" / "Closes #N"), and never close an issue (including via `gh issue close`)
without explicit permission — issue closure is left to the repository maintainer.

## Issue closure verification and merged-result summaries

Before closing an issue, and only with the explicit permission required above,
the agent MUST:

- Identify the linked pull requests and check their current state on GitHub.
  Distinguish open, closed without merging, and merged PRs; a closed PR is not
  evidence that its changes were merged.
- For each merged PR, post a summary on the issue listing the new improvements.
  Link the PR and merge commit, identify the actual destination branch, and
  record validation results, limitations, and remaining work. Do not infer that
  a release was published merely because a PR merged.
- For open or closed-but-unmerged PRs, state their actual status and do not
  describe their changes as merged or delivered to the destination branch.
  If no related PR exists, record that rather than inventing a merge status.

Perform this verification and publish the applicable summary before closing the
issue. For multiple related PRs, distinguish merged work from pending or
unmerged work. If a PR merges after the issue was closed, update the issue with
the merged improvements and actual destination branch.

## Summaries for related implementations

When a topic spans multiple implementations or related pull requests, the
agent MUST write and maintain a consolidated summary. Include each change's
scope, linked issues/PRs, implementation and merge status, dependencies,