AI Agent Assembly — Documentation Hub

The centralized, evergreen documentation hub for AI Agent Assembly — the governance-native runtime for AI agents.

This repository is the documentation hub for AI Agent Assembly. It is an mdBook site, built and deployed to GitHub Pages by the deploy.yml workflow on every push to main. The hub is the central router across the product's independently versioned components — it stays evergreen by linking to each component's own docs site root rather than duplicating their content.

Read the docs

→ ai-agent-assembly.github.io/agent-assembly-docs

This is the canonical entry point. Start here for the documentation index, the core↔SDK compatibility matrix, the security model, and the open-core boundary.

What's inside

The published site (see docs/src/SUMMARY.md) covers:

• Documentation index — the central router to every component's own docs site (core + the three SDKs).
• Compatibility Matrix — the core↔SDK version matrix, generated from compatibility.toml.
• Source of Truth & Status — the canonical map of which repo owns each area and whether it is public, private/internal, alpha, or planned.
• Platform & Security
  • Security Model — how the runtime governs agents.
  • Why AI Agent Assembly? — comparison with alternatives.
  • Open Core Boundary — what is open source vs. SaaS.
• Getting Started — Quick Start (SaaS) and Cloud Deployment (both Coming soon).
• Policy Reference — the policy language reference.

Component & SDK docs

AI Agent Assembly ships as several independently versioned programs, each with its own source repository and (for the public ones) its own documentation site. The hub's router page links to each component's docs site root — which always redirects to that component's newest stable release, so these references never need maintenance. The Source of Truth & Status page is the canonical status map for every area below.

Area	Source repository	Docs
Core (agent-assembly)	agent-assembly	https://ai-agent-assembly.github.io/agent-assembly/
Python SDK	python-sdk	https://ai-agent-assembly.github.io/python-sdk/
Node SDK	node-sdk	https://ai-agent-assembly.github.io/node-sdk/
Go SDK	go-sdk	https://ai-agent-assembly.github.io/go-sdk/
Runnable examples	agent-assembly-examples	repo README
Homebrew / install	homebrew-tap	repo README
Specs (protocol & policy)	in the agent-assembly monorepo	Policy reference
Releases & compatibility	this hub + component tags	Compatibility matrix
Cloud (SaaS)	agent-assembly-cloud (private, planned)	Cloud deployment
Enterprise	agent-assembly-enterprise (private, planned)	Open core boundary

Source-of-truth labels

The hub spans public and private repositories at different maturity levels. Every area on the Source of Truth & Status page carries two labels so readers know how much weight to give a page:

• Visibility — 🟢 Public (source repo is public) or 🔒 Private / internal (source repo is private; docs describe intent, not a browsable codebase).
• Maturity — 🧪 Alpha (ships today, may change; the product is currently v0.0.1-alpha) or 🗺️ Planned (designed and documented, not yet generally available).

When adding or editing a page that describes a new area, update the status map so the public/private and alpha/planned state stays accurate.

How content reaches the site

Today the hub is manually authored: every page under docs/src/ is hand-written Markdown, registered in SUMMARY.md, built by mdbook build, and deployed to GitHub Pages by deploy.yml on every push to main. The hub does not copy content from the component repos — it links to each component's own docs site root (see the table above).

An automated cross-repo sync pipeline — where SDK repos fire a repository_dispatch event on each release to pull their docs into this hub — is designed but not yet built (tracked as AAASM-302). The end-to-end flow, the planned docs-manifest.json format, and how to onboard a new repo are documented in docs/sync-architecture.md. Until that pipeline lands, treat the manual mdBook → Pages flow as the only path content reaches the site.

Local development

Prerequisites

• mdBook (CI pins v0.4.40)
• mdbook-mermaid — the Mermaid diagram preprocessor
• python3 — for the compatibility-matrix generator and the "Last updated" preprocessor (standard library only, no third-party deps)

Serve locally

cd docs && mdbook serve

This builds and live-reloads the site at http://localhost:3000.

Check the compatibility matrix is in sync

python3 docs/scripts/generate_compatibility.py --check

generate_compatibility.py renders the core↔SDK tables into docs/src/compatibility.md from compatibility.toml. Run it with --check to fail on drift (CI runs the same check); run it with no arguments to regenerate the page in place.

The per-page "Last updated" footer is appended automatically by the last-changed.py git preprocessor, which reads each chapter's last commit date — there is nothing to update by hand.

Validation

Before opening a PR, run the same checks CI runs and review the navigation:

1. Build — cd docs && mdbook build must complete with no warnings. CI runs the identical command in deploy.yml and blocks the merge on any failure.
2. Compatibility matrix in sync — python3 docs/scripts/generate_compatibility.py --check must pass (CI runs this too); it fails on any drift between compatibility.toml and the generated tables.
3. Cross-link check — verify internal links resolve. mdBook reports broken relative links during mdbook build; for a deeper sweep you can run mdbook-linkcheck (optional, validates external links too). Every page must be registered in SUMMARY.md or mdBook will not render it.
4. Navigation review — cd docs && mdbook serve, open http://localhost:3000, and walk the sidebar top to bottom: confirm every area (core, SDKs, cloud, enterprise, Homebrew, specs, releases, operations) is reachable and the Source of Truth & Status labels are accurate.

Ownership

This hub is maintained by the AI Agent Assembly team. Review is routed by .github/CODEOWNERS; at least one Code Owner approval is required to merge. Content that crosses the open-core boundary (Cloud, Enterprise, licensing, security posture) is held for owner content review before publish. The content itself is sourced from:

• Each component's own docs site — the hub links to component site roots rather than copying their content (see the table above).
• compatibility.toml — the human-edited manifest that generates the compatibility matrix.
• Git history — the per-page "Last updated" footer is derived automatically by the last-changed.py preprocessor.

Contributing

See CONTRIBUTING.md for the full guide: how to add or edit pages, the directory layout, how to run markdownlint and the lychee link checker locally, and the PR process. The essentials:

• Content lives under docs/src/, authored in Markdown.
• Every page must be registered in docs/src/SUMMARY.md.
• The compatibility matrix is generated — edit compatibility.toml and run the generator; never hand-edit the content between the BEGIN GENERATED / END GENERATED markers in compatibility.md.
• Run cd docs && mdbook build and confirm it passes with no warnings before opening a PR.
• Follow the GitEmoji commit convention and keep commits small and atomic.

See .github/PULL_REQUEST_TEMPLATE.md for the full PR checklist.

License

Licensed under the Apache License 2.0.