# /agents.md
Agent contract for this Nabu instance.
This surface is for agents. It returns raw markdown, not HTML.
## Agent operating mode
- Read this route before touching the browser UI.
- Authenticate over HTTP, persist the session cookie, write via API, then verify by path.
- Do not use browser automation or browser-use for normal note operations.
- Use the browser UI only for human navigation or explicit UI testing.
## Authentication
- POST /api/auth/login
- Content-Type: application/x-www-form-urlencoded
- Fields: password, redirect
- Session cookie: nabu_session
- Persist the session cookie and reuse it on subsequent requests.
- Use a normal HTTP client like `curl` for writes.
## Identity
- Canonical note identity: relPath
- Deterministic read: /api/vault/notes/by-path?path=<path>
- Convenience read: /api/vault/notes/$slug
- Use relPath as the canonical note identity. Slug lookup is convenience-only and may collide.
## Common agent pitfalls
- Use `rawMarkdown`, not top-level `body` or `content`.
- Use vault-relative paths only.
- Use deterministic by-path reads after every mutation.
- When writing notes, prefer canonical frontmatter metadata (`title`, `summary`, `tags`, `authors`, `source`, `references`).
- Rename does not rewrite wiki-links or markdown links yet.
- Folder delete is empty-only and non-recursive.
Authenticate first, then read this route again for the full write contract.
Full authenticated contract includes note create/update/move/delete and empty-folder delete.
Example login:
```bash
curl -i -c /tmp/nabu-cookies.txt \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data 'password=YOUR_PASSWORD&redirect=%2Fagents.md' \
  https://www.raphyy.online/api/auth/login
```