user-onboarding / v0.2 — operating a4sx (install → automations → fleets → environments)

Audience: the operator/developer who runs a4sx and builds automations on it. (This is the *human* guide. A *landing agent* gets a machine brief at GET /orient; the full spec catalog is GET /specs.) On a hosted a4sx workspace the platform is already running: §1 (install), §2 (first-run bootstrap) and the host-fleet commands in §8 describe running the platform itself, which a workspace user does not do.

The paradigm, in one line: you build automations by first onboarding live data from your systems into a4sx, then growing skills on top of that live data — and the platform *enforces* that order (§11). This guide walks the whole operator journey:

install → first admin token → bring your own model → onboard a data source → secrets → how skills work → make skills persistent (shims) → manage fleets → environments.

---

substrate. Everything is an event on a queryable stream (GET /events). It's the source of truth; it's k8s-hosted and survives everything around it.

OAuth holders — are *ephemeral* processes that emit into / read from the stream. They're declared as fleet-specs and a reconciler keeps them alive.

environments isolate workspaces *within* a tenant.

---

The collector (/app/polaris-bot-mdx — the collector's image, deployment and log banner keep its internal name polaris-bot-mdx):

Key env vars (collector/config.py):

The host fleet (/app/agent-mdx-orchestration) — the satellites run on a docker host driven by a reconciler. Bring it up idempotently: ✅ checkpoint: curl https://<collector>/healthz → {"ok":true,…}.

---

0. The shape of the system

1. Install & run

2. Your first admin token

3. Bring your own model / subscription

4. Onboard your first external data source *(do this before building skills)*

5. Secret management (the vault)

6. How skills work

7. Make skills persistent — shims

8. Managing fleets

9. Environments

10. The whole journey on one page

11. The guardrail that enforces the paradigm: at_target

12. Go deeper (GET /specs/<name>/latest)