This is the source map for the public aweb repository. It separates shipped protocol authority, current guides, optional and experimental features, and compatibility material.
Company strategy, market research, positioning, and private hosted-product plans deliberately do not live in this OSS repository.
The repository README has install and server-start commands. Use this page to find the document you need, and to see which documents carry authority over shipped behavior.
The baseline contains 79 tracked Markdown documents. This front door does not self-link. The remaining 78 public Markdown paths appear below exactly once.
Do this first: the CLI tutorial. It installs aw, puts
two agents on one team and has them message each other. Finishing it means aweb
works for you. The offline-delivery and reconnect proof is in
Receiving events and waking agents.
Then, as you need them:
- Mail and chat — everyday messaging patterns beyond the round trip.
- Receiving events and waking agents — wiring wake signals into a running agent and recovering after disconnect.
- Self-hosting guide — operating the OSS services yourself. The tutorial's self-hosted path already inlines what you need to finish; this is for running them properly.
- Current protocol authority governs shipped identity, trust, routing, encryption, authentication, and coordination behavior.
- Guides and references explain those contracts; they do not override them.
- Advanced, optional, and experimental does not mean unsupported or safe to delete. These features remain available under their stated lifecycle.
- Compatibility material is not current product authority. It remains visible for existing users until its reviewed consumer migration or consolidation is complete.
Every section is expanded. The two long ones are collapsible for convenience; collapsing ranks nothing, and no section here is on its way out. Superseded and completed material is deleted rather than parked, and Git history is its archive.
These documents govern current interoperable behavior. Accuracy notices on hand-maintained inventories do not weaken their normative security and protocol authority.
Product, identity, messaging, and trust contracts
- Identity and team model — canonical vocabulary and identity/team invariants.
- aweb implementation SOT — normative aweb server/CLI contract; inventory reconciliation is pending.
- AWID implementation SOT — normative registry contract; inventory reconciliation is pending.
- Product authority SOT — current supporting custody, team-authority, addressability, and runtime axes pending consolidation.
- Fully Hosted and BYOT onboarding contract — authority shapes for managed and customer-controlled teams.
- Identity and messaging contract — identity-scoped delivery and first-contact routing.
- Federation error reference — generated stable reason, HTTP status, retryability, and safe-support contract.
- Global/local identity routing SOT — shipped global/local route behavior and compatibility cleanup.
- Identity-key verification — verifying current AWID identity keys and log heads.
- E2E messaging contract — optional advanced encrypted-message v2 envelope and cryptographic binding.
- E2E operational metadata — metadata-only operations around encrypted messages.
- E2E legacy plaintext and no-downgrade policy — mixed-version compatibility rules.
- Trust model — key authority, custody, verification, and recovery boundaries.
- Team-auth request envelope v2 — signed relying-party request contract.
- Principal attestation — custodian-signed statement of custody and channel for a team-auth request (proposal).
- Member person declaration — team controller's statement that a certificate's member is one natural person (proposal).
- secrets runner protocol — signed runner requests and assignments, and HPKE credential sealing, between secrets and its runners.
- AWID A2A publication contract — publication and bridge-delegation assertions.
- Agent health — status-host designation and the signed agent status document a host publishes.
- Agent guide — compact setup-injected communication and recovery contract for an agent.
- Portable orchestrator integration — persist identity/workspace mapping, consume events, reconnect, reply, and retire without surrendering runtime ownership.
- Teams — team membership, roster, and coordination concepts.
- Identity and teams guide — practical identity, namespace, team, and trust operations.
- Invite inspection — inspect an invite without redeeming it or changing identity or membership state.
- Hosted global bootstrap and recovery — creating a new global identity in an existing hosted team, or reusing a retained resident.
- Build a naapp — an outside author's path from an HTTP service to signed requests, optional events and agent installation.
- CLI naapp access — resident approval and finite grant snapshots for declarative HTTP apps.
- Channel — maintained Claude Code event integration.
- OSS support tools — doctor, registry reads, bundles, and safe support handoff.
- Troubleshoot a workspace — separate identity, membership, durable mailbox, event transport, and runtime wake failures.
- Mail for beads — turn on
bd mailwith aweb as the delegate: three-line setup, addressing, wake-ups, and what differs on purpose.
- Mail for Gas City — the same aweb-backed provider for Gas
City's
GC_MAIL=exec:seam; one aweb identity per city.
These are working capabilities outside the first communication journey. Current optional and advanced helpers remain supported under their documented contracts; Library/profile services and runtime materialization are opt-in. An empty-profile, one-repository team is complete, and external orchestrators keep ownership of definitions, homes, worktrees, runtimes, processes, and session UX.
Profiles, runtime, coordination, integrations, and extension contracts
- Profiles and blueprints — advanced optional Library-backed profile helper; empty-profile teams need no profile service.
- Blueprint materialization contract — current advanced optional payload, pin, and provenance contract.
- Resource-pack template contract — current advanced optional harness-neutral operating assets.
- Orchestrate a local agent team — current optional materialized-team helper workflow.
- Orchestrate more local agents — current optional membership-growth helper with operator-owned materialization and launch choices.
- Improve a profile — optional Library-backed reviewed profile-learning loop.
- Running materialized agents — advanced optional local home/worktree and launch helpers, not an aweb-owned lifecycle.
- Runtime support — current maintained wake integrations and advanced optional materialize/launch helpers.
- Agent home composition contract — current home-layout facts pending consolidation.
- Start working in your team — optional task-first workflow scheduled for repositioning.
- Tasks and work — current optional shared work coordination; external task providers remain valid.
- Roles, instructions, and locks — current optional team operating context and resource reservation.
- Work across teams — multi-team identity and messaging.
- MCP tutorial — optional MCP client journey scheduled for an OSS/hosted split.
- Add an AI tool to your team — connect Claude Code, Pi, Codex or Hermes and make it wake; the optional member/home/worktree/runtime materialization workflow is its last section.
- Connect a Hermes agent — run Hermes with the aweb platform plugin in its gateway.
Experimental means implemented or actively specified with a deliberately narrower stability promise. It does not mean planned commands should be presented as shipped.
- A2A interoperability — shipped experimental CLI/gateway and self-hosted/BYOT bridge surface.
- Mutation hook seam — shipped experimental in-process
app.state.on_mutationcallback and exact current route call sites. - aw-hooks: catalog, bindings and delivery — specified experimental contract for owner-activated named hooks, not yet shipped.
- Owner act — specified experimental controller-signed artifact for owner-only governance acts, not yet shipped.
- App manifest — current experimental manifest versions 1 and 2, variant discovery, and the byte-identical CLI interpretation contract.
- App registry and team grants — current experimental install, digest-pin, and grants read surface.
- Page format — the frozen
aweb.page/1page snapshot format, its validator and conformance vectors. - Page actions, decisions and approvals — specified experimental contract for page actions, proposal digests and approval adapters, not yet shipped.
- App task requests and conditional answers — specified experimental contract for member-authorized app task creation and conditional task answers, not yet shipped.
- App-emitted events and subscriptions — shipped experimental emit auth, subscription, SSE, and channel-core consumer contract.
- Support contract v1 — current registry-read envelope and doctor compatibility boundary; other producers remain experimental.
- Hermes gateway integration memo — prototype integration evidence.
- Session admission leases — shipped experimental session primitive with explicit non-fencing limits.
These paths remain for current users or because durable facts have not yet been consolidated. Prefer the canonical/current guide named in each document's status notice where one exists.
aw run— opt-in, provider-specific launcher, and the supported wake path for Codex today. It sits in this section because aweb does not guarantee runtime lifecycle, not because the command is superseded.aw team admin extendcommand SOT — shipped compatibility contract preserving authority discovery, ambiguity, rollback, and batch semantics; use the current growth guide and generated reference for everyday operation.
- CLI command reference — generated from Cobra help;
live
aw <command> --helpremains the direct source when generation is stale. - MCP tools reference — current tool inventory and parameters.
- Configuration — local
.aw/files, environment, and docs injection. - Current limitations — known operational boundaries.
- Messaging contract matrix — subordinate maintainer cases for routing, read state, chat waits, reconnect, and content modes.
- Protocol conformance vectors — canonical index for all 21 root JSON fixtures, with current, experimental, compatibility, and digest-only authority distinguished.
- Self-hosted A2A gateway configuration — retained public YAML example for advanced self-hosted/BYOT gateway operation.
The live REST route inventory is the FastAPI /docs OpenAPI viewer produced by
server/src/aweb/api.py; do not recreate a hand-maintained route reference.
- Contributing guide — repository structure, tests, and extension workflow.
- Open-source repository boundary — canonical framework versus
application ownership and
.aw/state policy. - Release process — the two-repository release specification: local Docker gates once, thin GitHub publication, one global go.
- A2A gateway release runbook — public OSS gateway, AWID, self-hosted/BYOT release and rollback controls.
- E2E messaging rollout runbook — generic OSS compatibility, readiness, evidence, and rollback procedure.
- Optional Library integration test stack — advanced cross-repository maintainer harness; unrelated to encrypted messaging.
- Per-team agent tmux cutover — specialized reviewed runtime migration procedure.
- This repository in an OATS workspace — the maintainers' agent souls and knowledge base kept here, and the standalone view for contributors who cannot read the workspace host.
- Beads mail delegate design record — the decided
verb surface, identity, threading, retention, and instrumentation choices
behind
aw beads-mail. - Terminal wake broker design note — one event stream per identity on a host, full messages typed into the original terminal through the OATS input operation; decided process model, state, registration, ack point, and the interface contract (aweb-abil).
- Channel-core terminal wake adapter contract — channel-core owns terminal wake delivery (immediate delivery, exact fetch, delivered ids, acks); the Go daemon supervises sessions and registrations.
- Gas City mail provider design record — the exec
contract verified against pinned Gas City source and the operation mapping
behind
aw gc-mail. - Hosted certificate anchoring draft — authorized contract for hosted roster read-back; a draft until it lands.
- Local-sender verification authority draft — record of the 2026-08-17 threat-model rulings; the normative text lives in the trust model.