Sannr docs.

Two tools, one folder

The map and the client are the tools; the .sannr folder is what they remember. It holds your API knowledge, its settings and the skills, committed with your code. Setup also puts what your agent needs where it looks, outside the folder; step 02 lists every file.

A map

Point it at a repository and it inventories the APIs it finds: the services, the routes it recognizes, who calls whom, and routes your code implements that the contract leaves out. The map is generated from your files, offline, without calling anything.

sannr map . walks the tree and writes the map as one self-contained HTML file that works offline. sannr start, an alternative to connect, produces the same static inventory during setup. Neither makes an API request; the --no-execute form in step 05 is the explicit way to say so.

The folder

The knowledge file, .sannr/stacks/sannr.json, records what agents observe about each operation: response shapes, the enum values a contract declares, the gotchas the documentation omits, and the decisions no traffic ever reveals, such as why an integration was rejected. It is committed with the code, so it travels with the repository.

sannr learn fills it from read-only requests. sannr note adds an authored lesson to one operation. sannr view writes an offline HTML snapshot of everything the file holds, with verification dates, confidence and each note's provenance, so a person can read it without a server.

A client

A request client your agent calls through MCP or the command line. It sends the request, applies your credentials from environment references, returns a bounded result with the assertions you asked for, and records what it observed. The client makes the calls; the folder is what it remembers.

In Claude Code or Codex the client is the api_request tool that sannr connect registers for the project. From a terminal, sannr request GET /health uses the same client and returns the same envelope: status, whether the call was ok, the assertions and their results, the bounded data, and a pointer to the local evidence.

Import. Verify. Deliver.

Import what you already have

Sannr reads Postman and Bruno collections, and seeds operations from an OpenAPI contract. Every import comes with a loss report. Scripts are never executed during an import; review the report and the generated suite before you run anything.

sannr import accepts Postman v2.1 and v3, and Bruno files and directories. It writes a request suite for the steps whose assertions it could translate or infer, and an adjacent to-do file naming every gap. An OpenAPI contract is not imported; sannr start seeds the knowledge file from it as unverified operations when the environment names one.

Verify against the running service

Read-only checks record what is actually true about each operation: the status codes seen, the field names and types, the drift between the contract and the server. Field values are never recorded unless the contract itself declares them; request and response bodies, headers and credentials never are.

sannr learn sends only GET and HEAD requests. sannr learn --dry-run previews exactly what would be written and writes nothing. Whatever it learns about a production environment is reported, not promoted into the committed file.

Deliver it where the agent already reads

The lessons agents record are listed, each with its operation, in a block in the instruction files your agent loads at the start of a session, so a new session has them in view without being told to go and look. The client also returns an operation's lessons with each result for it.

sannr connect writes that block into AGENTS.md and CLAUDE.md (step 02) and sannr learn refreshes it. It names the knowledge file and lists the recorded gotchas, pointing to the file for any it has no room for. Rerunning connect preserves unrelated configuration and reports conflicts instead of overwriting them.

Optional: a drift report in CI

sannr connect --ci adds a GitHub Actions workflow that runs on pushes, pull requests and a weekly schedule. It reports where the checked-in contract and the code disagree, in report-only mode and without API traffic, and it does not rewrite the contract or the knowledge file. sannr verify --read-only --ci runs the saved suites as read-only probes and exits non-zero on drift.

A recorded lesson

Automatic capture keeps bounded status and structure. It cannot know why a behavior matters. When an agent or a developer learns one reusable fact the contract does not state, the write convention asks for one present-tense sentence on the operation, recorded at once:

npx --yes @sannr/sannr@alpha note "POST /orders/{id}/confirm" "returns 200 while status remains draft unless payment_status is settled"

The note lands in the knowledge file under that operation, with who recorded it and when. Every note passes a secret guard: a note that looks like it holds a token, a key or an email address is refused, because the committed file ends up in every clone and fork.

"POST /orders/{id}/confirm": {
  "notes": [
    "returns 200 while status remains draft unless payment_status is settled"
  ],
  "notes_provenance": [{ "by": "agent", "at": "2026-09-15" }]
}

In any clone where the file is committed, the next session can see it: the client returns it with the result of each call to that operation, and the block in AGENTS.md and CLAUDE.md lists it once connect or learn next rewrites that block. A decision not to use an API is recorded the same way with sannr verdict, with its reason and scope, so the rejection leaves an artifact instead of a memory.

What stays on your machine

Sannr has no account to create and sends nothing to us. Credentials are referenced by environment variable name; the configuration stores the name, never the value. Recorded knowledge holds field names and types, and only the values a contract declares. Request evidence stays in a local folder that Sannr's own .gitignore keeps out of the repository. The API knowledge, its settings and the skills in the .sannr folder are what's meant to be shared, and they are designed to be safe to commit.

The environment configuration names a base URL, a contract path and an authentication reference such as bearer:LOCAL_API_TOKEN. The token itself lives in an environment variable or a local file outside the repository. The alpha's feedback report is written to a local file for a person to read and send; the product never sends it.

The .sannr folder

Setup writes a README.md into the folder that explains each path. This is its layout at the alpha:

Commit the knowledge, the configuration, the generated guide and the skill sources.

The words we use

API context

Everything an agent needs to use an API correctly that the specification does not say: prerequisites, quirks, rate limits, the reason a decision was made, and how recently each fact was checked.

Tribal knowledge

The working knowledge of a system that lives in the heads of the people who have been around longest and is not written anywhere a newcomer, or an agent, would find it.

The rediscovery tax

The cost of an agent re-deriving, in a fresh session, something a previous session already learned about the same API.

Authored lesson

A short note recorded on an operation by a developer or an agent, with its evidence, describing behavior the contract does not say. Sannr delivers lessons to later sessions.

Loss report

The part of an import that names what could not be carried over faithfully.

Drift

A difference between what the contract or the saved knowledge says and what the running service does now.

Repository-level context

Knowledge committed with the code, so it travels with the repository: anyone who clones it gets the same notes. Your agent's host may keep memory for you on your machine; the repository is what everyone else pulls.