docs: add Chinese i18n, legal pages, and deploy mode cards

Author: os-zhuang

AGENTS.md

@@ -0,0 +1,71 @@
+# AGENTS.md
+
+Guidance for AI agents (Claude Code, Codex, Cursor, etc.) working in this repository.
+
+## Repository
+
+ObjectOS — customer-hosted runtime for ObjectStack applications. Monorepo with the marketing + docs site under `apps/docs`.
+
+## Critical rules
+
+### 1. English is the single source of truth for all content
+
+All marketing copy, UI strings, and documentation are authored in **English first**. Chinese (`cn`) and any future locales are **translations derived from English**.
+
+- **Always edit the English source first.** Never patch a translation without updating the English original — translation passes will overwrite you.
+- If a typo or wording change only appears in Chinese, fix English too (it almost certainly has the same issue or will after the next sync).
+- New content must be added to English before translations are touched.
+- Translations are derived artifacts; treat them like generated code that happens to be checked in.
+
+### 2. Test in a real browser before claiming UI work is done
+
+Type-checks and unit tests verify code correctness, not feature correctness. For any UI change in `apps/docs`, run the dev server and exercise the change in a browser before reporting done. If a tool can't drive a browser, say so explicitly rather than guessing.
+
+## apps/docs (Fumadocs site)
+
+Stack: Next.js 16 App Router + Fumadocs UI 16 + Fumadocs MDX. Many UI affordances (theme toggle, search modal, language switcher, sidebar, link rendering) come from Fumadocs components, not custom code. Check `node_modules/fumadocs-ui` before assuming something is broken in app code.
+
+### Where things live
+
+| Concern | File |
+|---|---|
+| Locale list & default | `apps/docs/lib/i18n.ts` |
+| Language display names | `apps/docs/app/[lang]/layout.tsx` (`LANGUAGE_NAMES`) |
+| Locale detection / URL rewrite | `apps/docs/middleware.ts` |
+| Header + logo | `apps/docs/lib/layout.shared.tsx` |
+| Homepage copy (en + cn) | `apps/docs/lib/homepage-i18n.ts` |
+| Docs MDX content | `content/docs/**/*.mdx` |
+| Sidebar structure / grouping | `content/docs/**/meta.json` |
+
+### Locale conventions
+
+- Supported locales: `en` (default), `cn`.
+- Default locale has no prefix (`/docs/...`); other locales are prefixed (`/cn/docs/...`). This is set by `hideLocale: 'default-locale'` in `lib/i18n.ts`.
+- **MDX translations:** add a sibling file with `.cn.mdx` next to the English `.mdx`. Fumadocs auto-falls-back to English when a translation is missing — you can ship translations incrementally without breaking links.
+- **Homepage strings:** must exist in both `en` and `cn` objects in `lib/homepage-i18n.ts` (they implement the `HomepageTranslations` interface; missing keys are a type error).
+- **Sidebar titles:** `meta.json` `title` fields currently render in all locales. If you localize sidebar labels, add per-locale `meta.cn.json` (Fumadocs convention) — don't translate inside the English file.
+
+### Sidebar grouping
+
+Folder `meta.json` files declare a section's title, page order, and `defaultOpen: false` to make the group collapsible and collapsed by default. The root `content/docs/meta.json` references folders by name (`"deploy"`, `"build"`, …), not by the `"...deploy"` spread + `---Deploy---` separator pattern (the old pattern produced a flat ~50-item sidebar).
+
+### Translation workflow
+
+When the English source changes:
+1. Edit the English `.mdx` / `en` object first; verify it renders.
+2. Update the `.cn.mdx` / `cn` object to match.
+3. If a `.cn.mdx` doesn't exist yet, that's fine — Fumadocs falls back to English. Create one when you're ready to translate, not as a stub.
+4. Keep `frontmatter` (title, description) translated too.
+
+### Don't
+
+- Don't reintroduce the `---Section---` + `"...folder"` flat sidebar pattern.
+- Don't set `alt="ObjectOS"` on the logo image when the adjacent text already says "ObjectOS" — screen readers read it twice. Use `alt=""` + `aria-hidden`.
+- Don't add Chinese-only strings or files. If it doesn't have an English source, it shouldn't exist yet.
+
+## Commands
+
+From `apps/docs/`:
+- `npm run dev` — dev server on http://localhost:3001
+- `npm run type-check` — `fumadocs-mdx && next typegen && tsc --noEmit`
+- `npm run build` — production build

README.md

@@ -1,49 +1,54 @@
 # ObjectOS
 
-> **The reference runtime distribution of the [ObjectStack framework](https://github.com/objectstack-ai/framework).**
-
-ObjectOS is what you ship to end customers. It is a thin, opinionated
-**distribution** of the ObjectStack protocol: one `objectstack.config.ts`,
-a `Dockerfile`, a Helm chart, and operational documentation. All
-protocol, kernel, drivers and official plugins come from the
-`@objectstack/*` packages on npm — this repository contains **no
-protocol implementation of its own**.
+> **Your data. Your network. Your rules.**
+>
+> ObjectOS is the customer-hosted runtime for [ObjectStack](https://github.com/objectstack-ai/framework)
+> applications — built to run inside your own infrastructure: private cloud,
+> customer data centers, or fully air-gapped networks.
+
+ObjectOS is the **distribution** of the ObjectStack protocol. The framework
+develops the kernel, drivers, and `@objectstack/*` packages on npm. This
+repository packages a protocol version into something a customer can
+`docker run`, sign an SLA on, and deploy into a network with no internet
+egress.
 
 ```
 ObjectStack framework  ≈  Linux kernel source tree
 ObjectOS               ≈  the distribution you actually deploy
 ```
 
+## Why ObjectOS
+
+For teams that cannot — or will not — hand customer data to a third party:
+
+- **Self-hosted runtime.** Runs in your environment, on your servers,
+  against your database. The control plane is optional; the runtime never
+  depends on a public service to keep the application alive.
+- **Deploy anywhere.** Single-container Docker for evaluation, Kubernetes
+  for production HA, or a long-running process on bare metal. Same
+  artifact, same behavior in every environment.
+- **Air-gapped ready.** Ship a release bundle into a network with no
+  public connectivity. ObjectOS reads its application artifact from a
+  local file and never calls home.
+- **Identity you already operate.** Local accounts, OAuth, OIDC, SAML, or
+  your corporate SSO — ObjectOS enforces the session.
+- **Permissions at the runtime.** Role-based access, record-level rules,
+  and field-level redaction are enforced by the runtime itself — not by
+  the UI.
+- **Audit, backup, observability on your terms.** Every state change is
+  auditable. Backups write to your storage. Logs and metrics export to
+  the observability stack you already use.
+
 ## Positioning
 
 | | ObjectStack framework | **ObjectOS** | Enterprise plugins |
 |---|---|---|---|
 | Repo | `objectstack-ai/framework` | `objectstack-ai/objectos` | `objectstack-ai/objectos-enterprise` (private) |
-| What it ships | Protocol, Kernel, all `@objectstack/*` packages, Studio, Cloud control plane | Runtime distribution + Docker/Helm + ops docs | SSO/SAML, SCIM, audit export, HA scheduler, … |
+| What it ships | Protocol, kernel, `@objectstack/*` packages, Studio, control plane | Runtime distribution + Docker/Helm + ops docs | SSO/SAML, SCIM, audit export, HA scheduler, … |
 | Who consumes it | Framework contributors, plugin authors | **End customers** (self-host / private cloud) | Enterprise customers |
 | License | Apache-2.0 | **Apache-2.0** | Commercial |
 | Release cadence | Frequent (per `changeset`) | Distribution semver (e.g. `2026.05 LTS`) | Tracks ObjectOS |
 
-The framework develops the protocol; ObjectOS packages a protocol
-version into something a customer can `docker run`, sign an SLA on,
-and deploy into an air-gapped environment.
-
-## Repository layout
-
-```
-objectos/
-├── apps/
-│   ├── objectos/            # Runtime entry — single objectstack.config.ts
-│   └── docs/                # Product / operations site (Fumadocs + Next.js)
-├── packages/                # Enterprise plugins (@objectos/plugin-*)
-├── content/docs/            # MDX content powering apps/docs
-├── docker/                  # Dockerfile + docker-compose
-├── helm/                    # Helm chart (planned)
-├── examples/                # Reference deployments
-├── e2e/                     # Black-box smoke tests against the published image
-└── scripts/
-```
-
 ## Boot modes
 
 ObjectOS boots in one of two modes, selected by environment variables:
@@ -63,15 +68,15 @@ pnpm install
 # Build the runtime distribution and docs
 pnpm build
 
-# Boot the runtime against a local compiled artifact produced by apps/objectos
+# Boot the runtime against a local compiled artifact
 cd apps/objectos
 OS_ARTIFACT_FILE=dist/objectstack.json PORT=3200 pnpm start
 
 # Or run the documentation site
 pnpm docs:dev
 ```
 
-Docker:
+### Docker
 
 ```bash
 mkdir -p docker/artifacts
@@ -82,6 +87,31 @@ docker compose -f docker/docker-compose.yml up --build
 Docker Compose publishes ObjectOS on `http://localhost:3000` by default.
 Use `OBJECTOS_PORT=3200` to change the host port.
 
+## Repository layout
+
+```
+objectos/
+├── apps/
+│   ├── objectos/            # Runtime entry — single objectstack.config.ts
+│   └── docs/                # Product / operations site (Fumadocs + Next.js)
+├── packages/                # Enterprise plugins (@objectos/plugin-*)
+├── content/docs/            # MDX content powering apps/docs
+├── docker/                  # Dockerfile + docker-compose
+├── helm/                    # Helm chart (planned)
+├── examples/                # Reference deployments
+├── e2e/                     # Black-box smoke tests against the published image
+└── scripts/
+```
+
+## Documentation
+
+- [Quickstart](content/docs/quickstart.mdx)
+- [Architecture](content/docs/architecture.mdx)
+- [Deployment](content/docs/deploy/index.mdx) — Docker, Kubernetes, air-gapped
+- [Authentication](content/docs/configure/authentication.mdx)
+- [Permissions](content/docs/configure/permissions.mdx)
+- [Observability](content/docs/operate/observability.mdx)
+
 ## History
 
 The current `main` is a deliberate restart aligned with the