> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fau.run/developer/llms.txt
> Use this file to discover all available pages before exploring further.

# Extend the codebase

> Change FAU safely — where to edit, what must stay invariant, how to test.

**Purpose:** modify this repository without breaking protocol `fau/1` or user custody
guarantees.

**Audience:** contributors who already ran [Developer getting started](https://docs.fau.run/developer/developers/getting-started.md).

## Read first

1. [Concepts](https://docs.fau.run/developer/concepts.md) — goals, non-goals, invariants
2. [Protocol overview](https://docs.fau.run/developer/protocol/overview.md) — ownership and flows
3. [Wire specification](https://docs.fau.run/developer/protocol/spec.md) — if you touch wire formats
4. [Security model](https://docs.fau.run/developer/protocol/security.md) — if you touch auth, store, or relay trust

## Where code lives

| Area | Path | Touches |
| - | - | - |
| Node / policy / MCP / `/papi` | `node/` | Grants, store, Expo push, dashboard |
| Channel plugins | `channels/<name>/` | Installable ingest/compose under node custody |
| Relay | `relay/` | Tunnel, resolve, queue, ACME |
| macOS shell | `apps/macos/` | launchd, Keychain, pair QR |
| Phone | `apps/phone/` | Pairing, device sig, UI |
| Public docs | `docs/` | This site |
| Test fixtures | `fixtures/*.json` | Device + tunnel vectors |

## Extension map

| You want to… | Do this | Do not |
| - | - | - |
| Add a structured tool | Gateway + tier first; tests | Let the LLM search then filter |
| Change approval UX | Phone / dashboard only | Put mail in push payloads |
| Add relay metrics | Relay only | Decrypt node SNI traffic |
| New LLM backend | Behind `AnswerEngine` | Move access control into prompts |
| New channel / indexer / actuator | Behind `fedagent.ports`; grant-filtered retrieve | Bypass gateway or bump wire for local ports |
| Break wire compatibility | Bump `fau/1`, update spec + vectors + both sides | Silent drift |

## Invariants (must survive a rewrite)

From [Concepts](https://docs.fau.run/developer/concepts.md) — abbreviated:

1. No inbox token to agents
2. Relay never decrypts node-SNI TLS
3. Phone decisions require device signatures (or explicit local dashboard decide)
4. Push is content-free
5. Resolve shapes match for known and unknown emails
6. Device signatures cover full targets including query strings
7. Agent nonces are single-use inside expiry

## How to test

```bash theme={null}
# Node
cd node && ../.venv/bin/pytest   # or repo .venv

# Phone
cd apps/phone && npm test

# Device vectors must stay green
# fixtures/device-vectors.json ↔ phone signer ↔ node verifier
```

If you change device canonicalization, update
[Device signing vectors](https://docs.fau.run/developer/reference/device-signing.md) **and** `fixtures/device-vectors.json`
(generator: `apps/phone/scripts/gen-device-vectors.ts`).

If you change tunnel frames or relay HTTP, update [Wire specification](https://docs.fau.run/developer/protocol/spec.md)
and `fixtures/test-vectors.json`, then run relay↔node interop tests.

## Design decision discipline

When you choose a new boundary, document in the PR:

* Decision
* Why
* Alternatives
* Tradeoff

Or the next engineer will rediscover it the hard way.

Product-shaped seams (channels, local indexes/classifiers, Computer Use) are sketched in
[Product architecture](https://docs.fau.run/developer/developers/product-architecture.md) — non-normative, not `fau/1`.

## Open questions (product / protocol)

Labeled so they are not mistaken for law — see also protocol overview:

* Per-app push filtering when multiple approval apps pair to one node
* Phone-initiated device deregister API

## Next

Return to [For protocol developers](https://docs.fau.run/developer/developers.md) or deepen in
[Protocol overview](https://docs.fau.run/developer/protocol/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.