# Repository rules: `.aiguard.yaml`

Put this file in the root of a repository to tell Grodmir which parts of it must never reach a
model, and which client it belongs to. **It can only make protection stricter.** It is plain
text in a repository that developers control, so the gateway treats it as untrusted input:

- it adds detections; the action (default **block**) still comes from your signed policy;
- it cannot allow anything, lower an action, or add an exception;
- a client assignment is honoured only if the developer's virtual key may use that client,
  otherwise the request is refused with 403 (never silently handled under another policy).

```yaml
version: 1
client: acme-gmbh            # client context id (optional)
exclude_paths:               # globs; ** crosses directories; a directory excludes everything below it
  - secrets/**
  - "**/*.pem"
markers:                     # text that marks client code: licence headers, namespaces, internal names
  - "Acme GmbH - Confidential"
  - "com.acme.billing"
```

Limits: 50 paths and 50 markers, 200 characters each (markers at least 3), file at most 64 KB.
Unknown keys are rejected.

## How it is enforced (two layers)

1. **Gateway (every tool).** The tool sends the rules in a header (`aiguard repo headers`).
   Any marker, or any path that matches `exclude_paths`, found in the text of a request (prompt,
   tool arguments, tool results, history) is a `code.client_marked` detection. Paths match by
   their tail, so `/home/dev/repo/secrets/key` matches `secrets/**`. Patterns are compiled
   with RE2 (linear time). The audit log records the category only, never the marker or path.
2. **Agent hook (Claude Code, Cursor).** `aiguard repo check` refuses tool calls that touch an
   excluded path, *before* the file is read. It fails closed: an invalid `.aiguard.yaml` blocks
   file access until fixed.

An invalid rules header is refused (HTTP 400), not ignored.

## Commands

| Command | Purpose |
|---|---|
| `aiguard repo init` | write a starter file (never overwrites) |
| `aiguard repo validate` | check the file |
| `aiguard repo headers [--format lines\|claude\|toml\|json]` | headers a tool must send: `X-AIGuard-Repo` (git remote, credentials removed, canonical `https://host/path`, matched against project `repo_patterns`), `X-AIGuard-Client`, `X-AIGuard-Repo-Rules` |
| `aiguard repo check --agent claude\|cursor` | hook; reads the tool call as JSON on stdin |

## What it does not do

- The hook is best effort for shell commands: a command can build a path at run time
  (`cat sec""rets/x`). The gateway layer catches the path when it appears in the conversation,
  but a tool without hooks reads the file locally first; only the *request carrying it* is refused.
- After a hook refuses a read, the path stays in the session history, so the gateway refuses
  the next request of that session. Start a new session (Q-035).
- Rules apply to text. Binary attachments are governed by `unknown_attachment` in the policy.
- Headers are read when the tool starts. Switching repository inside one session keeps the
  first repository's rules; start the tool per repository.
