# AIOS agent context

AIOS is an open-source ecosystem with separate products and repositories. Do not treat it as one application.

## System boundary

- Individual Workspace (`aios-workspace`): one private git repository per person. It contains the numbered spine, local context, validators, agent skills/harnesses, CLI, and sync client. It works offline. No workspace file content is uploaded automatically; only an explicit eligible `aios push` uploads workspace files. Online commands are separate network operations: for example, `aios whoami`, `aios query`, and `aios analyze --push` transmit the request data needed for their operations.
- Team Brain (`aios-team-brain`): one shared Next.js + Postgres service per team. It owns team membership, authentication, shared storage, tier-filtered retrieval, dashboard administration, and cited queries.
- Website (`aios-website`): public documentation and marketing projection. It is not authoritative for implementation.
- Design (`aios-design`): shared design-system contract and published `@aios-alpha/*` packages.

People are invited to the Team Brain, never into another person's individual workspace. Each invited person creates or repairs their own workspace and connects it to the shared Brain.

## Onboarding flows

Individual:
1. Inspect with `aios onboard --inspect --json`.
2. Create or repair one individual workspace.
3. Validate it with `validation/validate-all.sh`.
4. Use it offline or choose to connect a Brain later.

Joiner:
1. Create or repair your own individual workspace.
2. Accept a Team Brain invitation.
3. Sign in and generate your own per-machine `AIOS_API_KEY`.
4. Run `aios onboard`, approve the canonical Brain origin, and validate with `aios whoami`.
5. Run `aios status` and `aios push --dry-run` before the first explicit push.

Team admin:
1. Create the admin's own individual workspace.
2. Deploy one Team Brain.
3. Establish the team and admin account.
4. Invite members with Admin → Members or `aios member invite`.
5. Send each member through the Joiner flow. Do not distribute a personal workspace repository.

## Access boundary

- Canonical tiers: `admin`, `team`, `external`.
- Friendly aliases: `private`/`personal` → `admin`; `client`/`company` → `external`.
- `admin` never syncs. The workspace blocks it and the Brain rejects it with 422.
- Missing or unresolved `access:` is default-denied.
- Path whitelist and allowed tier must both pass.
- API keys are secrets. Keep them out of output and commits.

## Workspace spine

- `0-context/`: charter/scope or role/OKRs; default `team`.
- `1-inbox/`: raw inputs and Brain pulls; default `admin`.
- `2-work/`: deliverables and working documents; default `team`.
- `3-log/`: decisions, tasks, hours, and spend; default `admin`.
- `4-shared/`: external-facing output; default `external`.
- `5-personal/`: private scratch; default `admin`.
- Business-owner workspaces also have `6-business/`, outside the sync whitelist.

## Source hierarchy

Before claiming a feature exists or is absent, inspect the owning repository's source and tests.

- Workspace behavior: `aios-workspace/scaffold/`, `scripts/`, `validation/`, and tests.
- Workspace architecture: `aios-workspace/docs/architecture.md`.
- Workspace feature summary: `aios-workspace/docs/feature-set.md`. This file exists, but executable source wins if it drifts.
- CLI commands: `aios-workspace/scripts/cli/registry.mjs` and `scripts/cli/usage.mjs`.
- Brain architecture: `aios-team-brain/docs/ARCHITECTURE.md` plus `app/api/` and `lib/`.
- Workspace ↔ Brain contract: `aios-workspace/docs/brain-api.md`.
- Brain contract version: `aios-team-brain/lib/api/version.ts`.
- Public docs: `aios-website/src/content/docs/`.
- Design contract: `aios-design/DESIGN.md`.
- Agentic Engineering Maturity: root `agentic-engineering-maturity/`.

A missing, renamed, or stale context document is evidence about documentation, not proof that implementation is missing. Search code, trace callers, inspect tests, then compare documentation in both directions.

## Verification

Run from each repository:

- Workspace: `npm run check:docs` and `node --test test/contract-conformance.test.mjs`.
- Team Brain: `npm run check:docs` and `npx vitest run test/guards/contract-conformance.test.ts`.
- Website: `npm run check:docs`, `npm test`, and `npm run build`.
- AEM: `node agentic-engineering-maturity/rubric/validate.mjs` from the context-monorepo root.

Existing green structural checks do not prove all prose or endpoint documentation is semantically current. For release work, also audit actual `/api/v1` handlers against `aios-workspace/docs/brain-api.md` in both directions.

## Public guides

- Setup map: https://aiosbrain.dev/getting-started/
- Individual workspace: https://aiosbrain.dev/getting-started/individual-workspace/
- Join a Team Brain: https://aiosbrain.dev/getting-started/onboarding-a-contributor/
- Team admin setup: https://aiosbrain.dev/getting-started/team-admin/
- Source-of-truth map: https://aiosbrain.dev/reference/source-of-truth/