refactor(docs): reorganize and expand documentation for clarity

Author: os-zhuang

.github/workflows/docker.yml

@@ -25,8 +25,11 @@ jobs:
           images: ghcr.io/objectstack-ai/objectos
           tags: |
             type=ref,event=branch
+            type=ref,event=tag
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=sha-,format=short
+            type=raw,value=latest,enable={{is_default_branch}}
       - uses: docker/build-push-action@v6
         with:
           context: .

content/docs/architecture.mdx

@@ -1,117 +1,127 @@
 ---
 title: Architecture
-description: How ObjectOS, the control plane, and the framework fit together.
+description: What you're actually running — for the engineer evaluating whether to bring this in.
 ---
 
 # Architecture
 
-ObjectOS is one of three layers in the ObjectStack platform. Customers
-usually deploy only ObjectOS; understanding the boundary between the
-three layers makes deployment, security review, and incident response
-easier.
+A practical view of what runs on your machines when you deploy
+ObjectOS, what data leaves your network, and what doesn't.
 
-## The three layers
+## What you deploy
+
+One Node.js process per ObjectOS instance. That's it.
 
 ```text
-+--------------------------+    +--------------------------+    +--------------------------+
-|  ObjectStack framework   |    |       Control plane      |    |          ObjectOS        |
-|  (npm packages, source)  | -> |   (authors, publishes    | -> |   (customer-hosted       |
-|                          |    |     artifacts)           |    |    runtime distribution) |
-+--------------------------+    +--------------------------+    +--------------------------+
-       runtime, plugins,             projects, environments,         executes artifacts,
-       drivers, services             metadata authoring,             owns runtime HTTP,
-                                     artifact storage                business database
+┌─────────────────────────────────────────────────────┐
+│                  ObjectOS process                   │
+│  ┌───────────────────────────────────────────────┐  │
+│  │   HTTP dispatcher  (/ · /api · /_studio …)    │  │
+│  ├───────────────────────────────────────────────┤  │
+│  │   Per-project ObjectKernel (LRU cached)       │  │
+│  │   ├─ Auth (Better Auth)                       │  │
+│  │   ├─ Security (RBAC + row-level + field)      │  │
+│  │   ├─ ObjectQL (data engine, generates SQL)    │  │
+│  │   ├─ REST API generator                       │  │
+│  │   └─ Capabilities loaded per artifact         │  │
+│  │      (audit, storage, jobs, queue, AI …)      │  │
+│  └───────────────────────────────────────────────┘  │
+└──────────┬──────────────────────────────────────────┘
+           │
+           ▼
+   Your business database
+   (Postgres / MySQL / SQLite / Turso / MongoDB)
 ```
 
-- **Framework** — the open-source `@objectstack/*` packages: kernel,
-  ObjectQL, plugins, drivers, services. Customers do not need to
-  understand or modify framework source to operate ObjectOS.
-- **Control plane** — where applications are authored and where the
-  compiled `objectstack.json` artifact is published. May be the hosted
-  ObjectStack Cloud or a customer-operated control plane.
-- **ObjectOS** — the runtime container customers deploy. It consumes
-  artifacts, builds a per-project kernel, talks to the customer-managed
-  business database, and serves application APIs and UI.
+It's a single statically-linked binary's worth of complexity. No
+sidecar, no Kafka, no separate cache layer required. Add those when you
+need them; don't pay for them on day one.
+
+## Where your data lives
+
+| Data | Lives in | Leaves your network? |
+|---|---|---|
+| Business records | Your database | **No** |
+| User accounts, sessions, OAuth tokens | Your database | **No** |
+| Audit log | Your database | **No** |
+| Settings, API keys, secrets | Your database / secret manager | **No** |
+| Uploaded files | Your disk or your S3/R2 bucket | **No** |
+| The compiled app definition (`objectstack.json`) | A file on disk or fetched from your control plane | Optional |
+
+ObjectOS does not call home. No telemetry. No license check. If you cut
+internet access entirely, it keeps running indefinitely. See
+[Air-gapped](/docs/deploy/air-gapped).
 
-## What runs inside ObjectOS
+## How a request is served
 
 ```text
-                +-------------------------------------+
-   HTTP -->     |        HTTP dispatcher              |
-                |  /health · /api/v1/* · /api/v1/auth |
-                +-----------------+-------------------+
-                                  |
-                +-----------------v-------------------+
-                |       KernelManager (LRU cache)     |
-                |  per-project ObjectKernel instances |
-                +-----------------+-------------------+
-                                  |
-                +-----------------v-------------------+
-                |   Base plugins (always loaded)      |
-                |   ObjectQL · Security · Auth · i18n |
-                +-----------------+-------------------+
-                                  |
-                +-----------------v-------------------+
-                |   Optional capabilities (per app)   |
-                |   audit · storage · jobs · queue ·  |
-                |   realtime · feed · automation ·    |
-                |   analytics · ai · settings         |
-                +-------------------------------------+
+1. Ingress / TLS termination     (your load balancer)
+2. HTTP dispatcher               (security headers, request id)
+3. Hostname → project resolution (cached, TTL configurable)
+4. Get or build per-project kernel from LRU
+5. AuthPlugin    — session cookie, bearer token, or API key
+6. SecurityPlugin — RBAC + row-level + field-level checks
+7. Route handler — generated REST, declarative action, or custom
+8. Data driver   — ObjectQL compiles to SQL / Mongo query
+9. Response with X-Request-Id propagated
 ```
 
-Key properties:
+Steps 4-8 typically execute in < 5ms once the kernel is warm.
 
-- One ObjectOS host can serve many projects. Each project gets its own
-  `ObjectKernel` instance, isolated database connection, and auth scope.
-- Kernels are cached in an LRU (`OS_KERNEL_CACHE_SIZE`, default 32) with
-  an idle TTL (`OS_KERNEL_TTL_MS`, default 15 min) so cold-start cost is
-  amortised.
-- Capabilities listed in the artifact's `requires` array are loaded
-  lazily from optional `@objectstack/*` packages bundled in the image.
+## The three layers (only matters if you're integrating)
 
-## Boot modes
+Most customers deploy only **ObjectOS**. The other two layers exist if
+you want to know where the artifact comes from:
 
-| Mode | When to use | Hostname resolution |
+| Layer | What it is | Where it runs |
 |---|---|---|
-| Cloud-connected (`OS_CLOUD_URL`) | Multi-project deployments, hosted control plane, dynamic project lifecycle | Resolved from the control plane's `/cloud/*` API |
-| File-backed (`controlPlaneUrl: 'file'` + `OS_ARTIFACT_FILE`) | Single project, demo, air-gapped, smoke tests | Every hostname resolves to the same packaged project |
+| **Framework** (`@objectstack/*`) | Open-source kernel, ObjectQL, plugins, drivers | npm — pulled in at build time |
+| **Control plane** (optional) | Publishes compiled `objectstack.json` artifacts; you can use the hosted ObjectStack Cloud, run your own, or skip it entirely | Your CI, our cloud, or your laptop |
+| **ObjectOS** | The runtime you operate | **Your infrastructure** |
 
-The ObjectOS app wrapper (`apps/objectos/objectstack.config.ts`) picks
-the mode based on the presence of `OS_CLOUD_URL`.
+If you're shipping a single app, you don't need a control plane —
+compile `objectstack.config.ts → dist/objectstack.json` in your CI and
+ship the JSON in the image. If you're running an internal app
+marketplace with many tenants and apps, the control plane is where the
+catalog lives.
 
-## Request lifecycle
-
-```text
-1. Ingress / load balancer  (TLS termination, X-Forwarded-For)
-2. ObjectOS HTTP dispatcher (security headers, request id)
-3. Hostname → environment   (cached for OS_ENV_CACHE_TTL_MS)
-4. KernelManager.acquire    (build on miss, reuse on hit)
-5. AuthPlugin                (session/cookie or bearer/API key)
-6. SecurityPlugin            (RBAC + RLS + FLS)
-7. Route handler             (generated REST, custom action, auth route)
-8. Driver                    (ObjectQL → SQL / Mongo / memory)
-9. Response                  (X-Request-Id propagated)
-```
-
-## Data ownership
+## Boot modes
 
-| Data | Where it lives | Owned by |
+| Mode | When | How |
 |---|---|---|
-| Compiled artifact (`objectstack.json`) | Control plane or local file | Application/release team |
-| Business records (your domain data) | Customer-managed database | Customer |
-| Identity (`sys_user`, `sys_session`, …) | Same database as business records | Customer |
-| Settings (`sys_setting`) | Same database as business records | Customer |
-| Secrets baseline (`OS_AUTH_SECRET`, OIDC client secret, DB creds) | Customer secret manager | Customer |
-| Audit log (`sys_audit_log`) | Same database (when `audit` capability is enabled) | Customer |
-
-ObjectOS never copies business data back to the control plane.
-
-## Security boundary
-
-- ObjectOS only needs to make one outbound connection during operation
-  (to the control plane Artifact API) in cloud-connected mode, plus any
-  customer-configured integrations (SMTP, object storage, webhook
-  targets, identity providers).
-- Air-gapped mode removes the control-plane call entirely.
-- See [Production readiness](/docs/operate/production) for the
-  go-live checklist.
+| **Standalone** | Single app, dev, evaluation, air-gapped, most production deployments | `pnpm dev` or run `dist/objectstack.json` from disk |
+| **File-backed** | Production with externally-managed artifacts | Set `OS_ARTIFACT_FILE=/path/to/objectstack.json` |
+| **Cloud-connected** | Multi-tenant / multi-app deployments fed by a control plane | Set `OS_CLOUD_URL` + `OS_CLOUD_API_KEY` |
+
+Mode is auto-detected from environment variables.
+
+## Performance characteristics
+
+| Metric | Number |
+|---|---|
+| Cold start (process up, ready for traffic) | ~1 second |
+| Per-kernel warmup (first request to a project) | 50-300ms depending on capabilities |
+| Warm request latency (CRUD via REST) | typically < 10ms + database latency |
+| Memory footprint | ~150MB base; ~10-30MB per active project kernel |
+| Concurrent projects per instance | Limited by `OS_KERNEL_CACHE_SIZE` (default 32) |
+
+## Why this shape
+
+- **One Node process, no sidecars** → fits in a `docker run`, fits in a
+  systemd unit, fits in a Lambda-like environment.
+- **Per-project kernel, LRU cached** → one instance can serve many
+  small apps without paying the warmup cost on every request.
+- **Generated APIs on top of declared metadata** → there's no codegen
+  step in your CI, no client SDK to publish; the API matches your data
+  model by construction.
+- **All capabilities are optional plugins** → image size scales with
+  what you actually use.
+
+## Where to go next
+
+- [Production Readiness](/docs/operate/production) — checklist before
+  exposing it to real traffic.
+- [Runtime Configuration](/docs/configure/runtime) — wiring databases,
+  caches, and secrets.
+- [Runtime Capabilities](/docs/reference/runtime-capabilities) —
+  which optional packages exist and what they enable.

content/docs/configure/email.mdx

@@ -22,6 +22,25 @@ The default is `log`. ObjectOS falls back to the log transport when a
 real provider is configured but no API key is supplied — useful to keep
 non-production environments from accidentally sending mail.
 
+### What about SMTP?
+
+Native SMTP transport is **not** built into the runtime today. If your
+environment requires SMTP (corporate relay, on-prem mail, air-gapped
+deployment) you have two production-grade options:
+
+1. **Run an SMTP-to-API relay** in front of ObjectOS. Resend, Postmark,
+   and self-hosted alternatives (Postal, Cuttlefish) all accept SMTP
+   ingress and re-emit via their HTTP API — ObjectOS talks to them
+   over HTTPS as normal.
+2. **Run the runtime with a custom email plugin.** The email plugin
+   API is small (one `send(message)` function); a project plugin that
+   wraps `nodemailer` plugs in via the `requires` list. See the
+   [plugin authoring guide](https://github.com/objectstack-ai/spec)
+   in the spec repo.
+
+Native SMTP transport is on the roadmap; track progress at
+[github.com/objectstack-ai/objectos/issues](https://github.com/objectstack-ai/objectos/issues).
+
 ## Environment variables
 
 | Variable | Purpose |