# AGENTS.md integration

`AGENTS.md` can preserve selected Gateman integration practices for later
coding-agent sessions. This guidance is optional and depends on the agent and
its tooling; not every coding agent automatically reads the file.

Project instructions do not replace current application context from
`/client/get`, the public Capability References, runtime authorization, or the
application's secure configuration.

## Version-free capability blocks

The following is a format illustration, not a complete implementation block.
For complete current instructions, use the [R2 Capability
Reference](https://docs.getgateman.com/capabilities/r2.use/).

```markdown
<!-- gateman:begin capability=r2.use -->

Illustrative capability guidance.

<!-- gateman:end capability=r2.use -->
```

The begin and end markers delimit one capability's guidance. The identifier is
the Capability Reference's canonical documentation identifier. It does not
grant authorization, report whether the capability is enabled, or identify a
runtime credential.

Markers intentionally contain no version number. Gateman uses a current-state
model: `/client/get` returns current application-specific implementation rules,
Capability References describe current public contracts, and copied project
guidance is maintained manually. There is no historical instruction selection
or version negotiation.

## Add a reusable block

When a project chooses to persist a block, a practical process is:

1. Authenticate and retrieve the current application context with
   `POST /client/get`.
2. Confirm that the application is authorized for the capability.
3. Open the linked, current Capability Reference.
4. Locate its complete reusable `AGENTS.md` block.
5. Copy the marked block into the project's appropriate agent-instruction
   file.
6. Preserve unrelated project instructions and check for an existing block
   with the same capability identifier before inserting another.

Keep the block intact, including both markers and the full Capability Reference
URL. Do not paste application configuration or credentials into it.

Several capabilities may coexist in one file. Each block keeps its own begin
and end markers. No special ordering is required by Gateman; use the project's
existing organization and keep related application instructions readable.

## Update a block manually

Gateman does not automatically synchronize copied blocks. If developers or
agents choose to refresh a copied block, a practical process is:

1. Consult the current `/client/get` context and its documentation URL.
2. Open the published Capability Reference.
3. Locate the matching capability block in the project file.
4. Replace only that complete marked block with the current published block.
5. Preserve unrelated project instructions and review the resulting diff.

Do not compare or negotiate obsolete rule versions. The published Capability
Reference and current `/client/get` response are the sources for current
guidance.

## Disabled capabilities

A copied AGENTS.md block does not grant Gateman authorization. Disabling a
capability removes the application's authorization to use its corresponding
Gateman operations. Local project instructions do not override current
Gateman authorization.

## Keep secrets out of project instructions

Never put any of the following in `AGENTS.md`:

- Provider credentials.
- HMAC application secrets or Ed25519 private keys.
- A populated `.gateman` configuration.
- Credentials returned through an authorized retrieval operation.
- Live sensitive application context that does not belong in repository
  instructions.

Safe persistent guidance can include public documentation links, supported
route names, non-secret implementation constraints, and error-handling rules.
For example:

```markdown
## Gateman email integration

- Use the enabled `email.send` capability and its current Capability Reference.
- Preserve the selected provider's native payload and idempotency behavior.
- Keep provider credentials and application signing material in server-side
  runtime configuration, never in source or logs.

When email operations return `email_sending_suspended` or
`email_sending_limit_exceeded`, check Sending Protection and authorised
recovery before investigating provider credentials, network problems, or retry
strategies. These are deliberate policy responses, not temporary provider
outages. `scope_not_allowed` means the application lacks the `email.send`
capability.
```

## Sources of truth

| Source | Purpose |
| --- | --- |
| `POST /client/get` | Current application-specific authorized context and implementation rules |
| Capability Reference | Current detailed public API contract |
| Project `AGENTS.md` | Optional persistent copy of relevant working instructions |

Project instructions are local continuity, not a second authorization system.
When they conflict with current Gateman context or the published contract,
investigate the difference and follow the current authoritative source.

## Related references

- [Using Gateman with coding agents](https://docs.getgateman.com/using-gateman-with-coding-agents/)
- [Bootstrap context](https://docs.getgateman.com/bootstrap-context/)
- [Contract v1](https://docs.getgateman.com/contract-v1/)
- [Authentication](https://docs.getgateman.com/authentication/)
- [Official PHP client](https://docs.getgateman.com/canonical-client-php/)
- [Official Node.js client](https://docs.getgateman.com/canonical-client-node/)
- [Official Python client](https://docs.getgateman.com/canonical-client-python/)
- [Official Go client](https://docs.getgateman.com/canonical-client-go/)
- [Email sending Capability Reference](https://docs.getgateman.com/capabilities/email.send/)
- [R2 Capability Reference](https://docs.getgateman.com/capabilities/r2.use/)