AAA is a machine-readable handshake for agent-aware sites and Settings surfaces. Agents read a small well-known set instead of inferring intent from the DOM.
| Document | Role |
|---|---|
| PROPOSAL.md | Short entry |
| docs/proposals/aaa-handshake.md | Protocol write-up |
| spec/00-overview.md | Spec tree entry |
| schemas/ | JSON Schema (draft 2020-12) |
| examples/ | Fixtures (live: false) |
- 00-overview — scope
- 01-handshake — discovery sequence
- 02-well-known —
ai-instructions.json,agents.json,llms.txt - 03-settings-surface — Settings and hand-off profiles,
action_root: "none", deep links - 04-safety — guardrails and confirmation
- 05-ownership — what this handshake covers
surface encountered
-> GET /.well-known/ai-instructions.json
-> GET discovery.actions (usually /.well-known/agents.json)
-> GET discovery.context (usually /.well-known/llms.txt)
-> if action_root is an HTTP path or URL → call only mapped actions
-> if action_root is the string "none" → use a documented Settings destination or human hand-off
Settings-desktop deep-link pattern:
app://settings?id=<anchor>
Examples in this repository set "live": false. They are fixtures, not a published origin.
- examples/well-known/ — generic site; HTTP
action_root - examples/product-examples/settings-desktop/ — Settings surface;
action_rootis the stringnone - examples/product-examples/handoff-site/ — AAA/0.2 service catalog; human-operated payment and
action_root: "none"
- Protocol target:
AAA/0.2; two current schemas with identity0.2.0, plus two byte-frozen 0.1 schemas - Reference suite: 165 tests; six JSON fixtures, all
live: false - Node 20 or later; no dependencies or package installation
node --test reference/
node reference/validate.mjs examples/well-known/agents.json
node reference/validate.mjs examples/well-known/ai-instructions.jsonCI runs the tests and validates every JSON file under examples/ on pushes and pull requests. Any nonzero result fails the check. The validator exits 0 for valid, 1 for invalid, and 2 for usage or I/O errors.
node reference/read.mjs https://example.com
node reference/read.mjs https://example.com --strict --json
node reference/read.mjs https://example.com --action get_status --json
node reference/read.mjs https://example.com --strict-pair --jsonThe reader follows ai-instructions.json → agents.json → llms.txt, using the bounded public-HTTPS fetch policy. It reports a map and warnings; it does not execute actions. Unknown fields warn and are ignored by default. --strict makes every schema error invalid. The library exports readOrigin(origin, options); the validator exports validateDocument(doc, kind) using the same strict engine as its CLI.
--strict-pair opts into cross-document validation: matching live/status and HTTP mode, unique action IDs, canonical endpoint paths under action_root, and Settings actions bound to documented anchors. In this mode, allow_autonomous_execution: false adds human confirmation for every declared action. Both shipped document pairs pass this optional check. Individual 0.2 schemas and the default reader retain their additive compatibility contract.
Outcomes are ok, missing, invalid, fetch_refused, unknown_action, or settings_profile. Exit 0 means ok or settings_profile; exit 1 means no usable requested map; exit 2 means usage error. An unknown action is never guessed. action_root: "none" never becomes an invented HTTP API. Permissive flags are advisory, and restrictive lists only tighten the consumer's existing policy.
--allow-http-local is only for an explicitly selected loopback HTTP test fixture, such as node reference/read.mjs http://127.0.0.1:8080 --allow-http-local. It does not permit loopback/private redirect targets or weaken production HTTPS checks. Keep it out of production invocations.
For new fields and experimental-name mappings, see migration to 0.2.
The original Express demo that served public/.well-known lives under reference/historical-starter/. See reference/starter-runtime.md.
MIT License. Copyright (c) 2026 Sierra Catalina. See LICENSE.