Gateman
Documentation/AGENTS.md integration

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.

<!-- 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:

## 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

SourcePurpose
POST /client/getCurrent application-specific authorized context and implementation rules
Capability ReferenceCurrent detailed public API contract
Project AGENTS.mdOptional 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.