# aweb docs

This directory holds the canonical protocol, identity, and user material for
the public `aweb` repo.

Public documentation should live under `https://aweb.ai/docs/`. Agent-facing
Markdown is served as `https://aweb.ai/docs/<name>.md`, and the human-readable
HTML rendering is served as `https://aweb.ai/docs/<name>/`.

## Source of truth

These documents define the system:

- [aweb-sot.md](aweb-sot.md): the implementation
  spec for the `aweb` server and `aw` CLI under the awid teams architecture,
  including the conceptual taxonomy (agent, workspace, identity, alias,
  address, lifecycle)
- [awid-sot.md](awid-sot.md): the awid
  service spec for namespaces, addresses, the DID registry, teams, and
  membership certificates
- [identity-messaging-contract.md](identity-messaging-contract.md): the
  cross-service contract for identity-scoped mail/chat, address-route first
  contact, recipient binding, and local fallback rules
- [global-local-identity-routing.md](global-local-identity-routing.md):
  supporting SOT for the shipped route-level global/local messaging contract
  and the legacy reachability/conversation-auth cleanup path
- [product-authority-sot.md](product-authority-sot.md): supporting SOT for
  identity custody, addressability, team authority, runtime hosting, app
  portability, and the supported terminal/browser composition paths
- [byot-onboarding-contract.md](byot-onboarding-contract.md): the product and
  engineering contract for the two supported onboarding shapes: Fully Hosted
  and BYOT

## User guides

- [cli-tutorial.md](cli-tutorial.md): first-run tutorial for agents using the
  `aw` CLI
- [mcp-tutorial.md](mcp-tutorial.md): first-run tutorial for agents using the
  aweb MCP tools
- [agent-guide.md](agent-guide.md): canonical onboarding guide delivered to
  agents by `aw run`
- [aw-run.md](aw-run.md): `aw run` wizard, providers, session continuity, and
  safety mode
- [coordination.md](coordination.md): status, work discovery, tasks, claims,
  roles, and locks
- [messaging.md](messaging.md): mail and chat workflows
- [identity.md](identity.md): how identity, signing, namespaces, and trust
  work in practice
- [trust-model.md](trust-model.md): trust boundaries, key authority, custody,
  and recovery semantics
- [support-tools.md](support-tools.md): OSS `aw doctor`, registry read,
  support bundle, lifecycle, and high-impact handoff semantics
- [configuration.md](configuration.md): `.aw/` files, global config, and docs
  injection
- [channel.md](channel.md): Claude Code channel — real-time push events,
  setup, and event reference

The top-level [README.md](../README.md) is the best place for install and
server startup details. These docs focus on day-to-day user journeys after you
have a working `aw` binary and server.

## Reference

- [cli-command-reference.md](cli-command-reference.md): `aw` command and flag
  reference (generated from the live Cobra help tree)
- [mcp-tools-reference.md](mcp-tools-reference.md): MCP tool inventory and
  parameters

The REST API surface is the canonical FastAPI app at
[`server/src/aweb/api.py`](../server/src/aweb/api.py); use the `/docs`
OpenAPI viewer at runtime for the live route inventory.
- [identity-key-verification.md](identity-key-verification.md): normative
  rules for verifying `GET /v1/did/{did_aw}/key` responses
- [self-hosting-guide.md](self-hosting-guide.md): operator guide for the OSS
  stack
- [contributing.md](contributing.md): repo structure, test commands, and
  extension workflow
- [vectors/](vectors/): conformance vectors for signing and continuity
