docs(ia): audience-first navigation — Learn/Build/Operate/Extend sections + business-facing entry pages

os-zhuang · claude · os-zhuang · commit 873c099c0d96 · 2026-07-24T01:01:45.000+08:00
- Root sidebar split into four audience sections via separators (zero URL churn)
- getting-started split into Start Here / Cheatsheets; CLI and Validating
  Metadata moved to Deployment &amp; Operations with redirects (incl. chain fix
  for the pre-2026-07 guides redirect) and in-content link rewrites
- New: getting-started/platform-capabilities (business-language capability
  tour, HotCRM as running example) and getting-started/build-without-code
  (Studio/Console/Setup visual-building guide)
- concepts/index gains Find Your Path reader cards; ui section renamed
  'Views &amp; Apps' in nav and home cards

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/docs-audience-first-ia.md b/.changeset/docs-audience-first-ia.md
@@ -0,0 +1,4 @@
+---
+---
+
+docs: audience-first IA — sidebar sections (Learn / Build / Operate / Extend & Reference), tooling pages moved to Deployment with redirects, new business-facing capability tour and no-code building guide, reader-path cards on Core Concepts.
diff --git a/apps/docs/redirects.mjs b/apps/docs/redirects.mjs
@@ -12,7 +12,10 @@ export const docsRedirects = [
   // getting-started
   ['/docs/guides/cheatsheets/quick-reference', '/docs/getting-started/quick-reference'],
   ['/docs/guides/common-patterns', '/docs/getting-started/common-patterns'],
-  ['/docs/guides/validating-metadata', '/docs/getting-started/validating-metadata'],
+  ['/docs/guides/validating-metadata', '/docs/deployment/validating-metadata'],
+  // 2026-07 audience-first IA: tooling pages moved out of getting-started
+  ['/docs/getting-started/cli', '/docs/deployment/cli'],
+  ['/docs/getting-started/validating-metadata', '/docs/deployment/validating-metadata'],
   // concepts
   ['/docs/getting-started/core-concepts', '/docs/concepts'],
   ['/docs/getting-started/architecture', '/docs/concepts/architecture'],
diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx
@@ -9,6 +9,17 @@ import { Scale, Code2, Database, ScrollText, Laptop } from 'lucide-react';
 
 Before diving into code, understanding these foundational ideas will make everything else click.
 
+## Find Your Path
+
+Different readers need different doors into this documentation — pick yours:
+
+<Cards>
+  <Card href="/docs/getting-started/platform-capabilities" title="I'm evaluating the platform" description="A business-language tour of what the platform can do — views, automation, approvals, permissions, analytics — no code required to read" />
+  <Card href="/docs/getting-started/build-without-code" title="I build with the visual tools" description="What admins and business analysts can do in Studio, Console, and Setup without writing metadata by hand" />
+  <Card href="/docs/getting-started/your-first-project" title="I write metadata" description="The developer path: scaffold a project, author typed metadata with an AI agent, validate, and ship" />
+  <Card href="/docs/kernel" title="I extend the platform" description="The contributor path: kernel architecture, plugins, services, and the protocol spec" />
+</Cards>
+
 ## Metadata-Driven Development
 
 Metadata-driven development is a paradigm shift where **application logic is defined by declarative data (metadata), not imperative code.**
diff --git a/content/docs/deployment/cli.mdx b/content/docs/deployment/cli.mdx
@@ -440,7 +440,7 @@ os validate path/to/config   # Validate specific file
 `os validate` will not fail the build on schema/predicate/binding grounds. In a
 scaffolded project these are wired as `npm run validate` and `npm run build`;
 your `AGENTS.md` tells coding agents to run `npm run validate` after editing
-metadata. See [Validating metadata](/docs/getting-started/validating-metadata).
+metadata. See [Validating metadata](/docs/deployment/validating-metadata).
 </Callout>
 
 #### `os info`
diff --git a/content/docs/deployment/meta.json b/content/docs/deployment/meta.json
@@ -3,6 +3,8 @@
   "icon": "Cloud",
   "pages": [
     "index",
+    "cli",
+    "validating-metadata",
     "self-hosting",
     "backup-restore",
     "vercel",
diff --git a/content/docs/deployment/self-hosting.mdx b/content/docs/deployment/self-hosting.mdx
@@ -21,7 +21,7 @@ objectstack.config.ts ──(os build, CI)──▶ dist/objectstack.json ──
   JSON file — your entire app. Build it once in CI; the host needs no
   TypeScript and no build step.
 - **`os start`** boots a production server directly from that artifact
-  ([reference](/docs/getting-started/cli#os-start)).
+  ([reference](/docs/deployment/cli#os-start)).
 - **Deployment config stays outside the artifact.** Database URL, secrets, and
   environment identity are injected via `OS_*` environment variables or flags.
 
@@ -346,7 +346,7 @@ Disable with `OS_MCP_SERVER_ENABLED=false`. See
 
 - [Backup & Restore](/docs/deployment/backup-restore) — what to back up, and the restore drill
 - [Deployment Modes](/docs/deployment) — the map of local / standalone / Cloud
-- [`os start` reference](/docs/getting-started/cli#os-start) — every flag and env var
+- [`os start` reference](/docs/deployment/cli#os-start) — every flag and env var
 - [Environment Variables](/docs/deployment/environment-variables) — the full catalog
 - [Deploy to Vercel](/docs/deployment/vercel) — the serverless alternative
 - [Troubleshooting & FAQ](/docs/deployment/troubleshooting)
diff --git a/content/docs/deployment/single-project-mode.mdx b/content/docs/deployment/single-project-mode.mdx
@@ -108,4 +108,4 @@ environments, provision databases, or mount a control plane.
 
 - [Environment-Scoped Routing](/docs/api/environment-routing)
 - [Deployment Modes](/docs/deployment)
-- [CLI reference](/docs/getting-started/cli)
+- [CLI reference](/docs/deployment/cli)
diff --git a/content/docs/deployment/validating-metadata.mdx b/content/docs/deployment/validating-metadata.mdx
@@ -173,6 +173,6 @@ Both commands support `--json` and exit non-zero on failure:
 
 ## See also
 
-- [Command Line Interface](/docs/getting-started/cli) — full `os validate` / `os build` reference
+- [Command Line Interface](/docs/deployment/cli) — full `os validate` / `os build` reference
 - [Formula & Predicates](/docs/data-modeling/formulas) — the CEL surface and `record.` scope
 - [Data Modeling](/docs/data-modeling) — objects, fields, validations, sharing
diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx
@@ -247,7 +247,7 @@ discovering a dead button three screens deep in the browser. This is the
 ["contract-first" guarantee](/docs/getting-started/how-ai-development-works#why-its-safe):
 the error is rejected at the authoring gate, not tolerated by a lenient runtime.
 For the full list of what the gate checks, see
-[Validating Metadata](/docs/getting-started/validating-metadata).
+[Validating Metadata](/docs/deployment/validating-metadata).
 
 Once it's clean:
 
diff --git a/content/docs/getting-started/build-without-code.mdx b/content/docs/getting-started/build-without-code.mdx
@@ -0,0 +1,42 @@
+---
+title: Build Without Code
+description: What admins and business analysts can do visually in Console, Studio, and Setup — and how that stays in sync with metadata written as code
+---
+
+# Build Without Code
+
+You do not have to write metadata files to build on this platform. **Console**, **Studio**, and **Setup** cover the run–design–administer loop visually — and everything you do there produces *the same metadata artifacts* a developer would write by hand, checked by the same validation gate. Clicking and coding are two editors over one definition, so a team can freely mix both.
+
+## Console — where the app runs
+
+`/_console/` is the workspace end users live in:
+
+- **Home** lists your apps, pending approvals, scheduled digests, and recently visited records.
+- Each app renders its declared navigation, views (table, kanban, calendar, gantt, …), dashboards, and record pages — switch views from the toolbar, save filters, pin favorites.
+- **Approvals inbox** collects everything waiting on you; decisions (approve / reject / send back) happen here.
+- Record pages carry the collaboration surface: discussion threads, attachments, activity timeline, and change history.
+- Global search (`⌘K`) spans objects, with partial and pinyin matching.
+
+## Studio — where the app is designed
+
+From any app, **"Design in Studio"** opens the same application in design mode. Studio is organized around four pillars:
+
+| Pillar | What you manage there |
+|---|---|
+| **Data** | Every object with its fields, plus per-object tabs for records, forms, validation rules, lifecycle hooks, actions, and API exposure |
+| **Automation** | All flows in one list with enable/disable switches; each opens as a visual diagram — triggers, branches, approval nodes, run history, and problem markers |
+| **Interface** | Apps, navigation, views, pages, and dashboards |
+| **Access** | Permission sets as a matrix of object/field grants, plus sharing configuration |
+
+Two properties make Studio safe to hand to non-developers:
+
+- **Draft → publish.** Changes save as drafts and go live only when published, with a change list to review first.
+- **Same gate as code.** A change that would break the app (a dangling reference, an invalid predicate) is rejected by the same validation that checks hand-written metadata — there is no "UI edits bypass review" back door.
+
+## Setup — where the platform is administered
+
+The **System Settings** app covers platform administration: user management and invitations, permission assignment, datasources (including federated external databases), diagnostics and audit logs, and the **Marketplace** — template apps such as HotCRM install with one click and appear alongside your own apps, ready to customize in Studio.
+
+## When to reach for code instead
+
+Visual editing shines for day-to-day evolution: adding fields, adjusting views, tweaking a flow, granting access. Teams typically switch to [metadata as code](/docs/getting-started/your-first-project) when they want version control and pull-request review across many changes, AI-assisted authoring, or promotion of the same app across environments. Both roads meet in the same artifact — start visual, graduate to code, or run both side by side.
diff --git a/content/docs/getting-started/common-patterns.mdx b/content/docs/getting-started/common-patterns.mdx
@@ -17,7 +17,7 @@ readability. In a real project, `os validate` additionally enforces your project
 **namespace prefix** on every object name (`my_app_project`) and an explicit
 **`sharingModel`** on every custom object (ADR-0090) — the patterns below include
 `sharingModel`; remember to add your prefix. See
-[Validating Metadata](/docs/getting-started/validating-metadata).
+[Validating Metadata](/docs/deployment/validating-metadata).
 </Callout>
 
 ---
diff --git a/content/docs/getting-started/examples.mdx b/content/docs/getting-started/examples.mdx
@@ -364,6 +364,6 @@ my-app/
 
 ## What's Next
 
-- [CLI Reference](/docs/getting-started/cli) — All available commands
+- [CLI Reference](/docs/deployment/cli) — All available commands
 - [Data Modeling Guide](/docs/data-modeling) — Deep dive into objects and fields
 - [Developer Guide](/docs/getting-started/quick-start) — Full learning path from objects to AI agents
diff --git a/content/docs/getting-started/how-ai-development-works.mdx b/content/docs/getting-started/how-ai-development-works.mdx
@@ -56,7 +56,7 @@ silently at runtime** — a bare-field predicate hides an action on every record
 dangling widget binding renders an empty chart. `os validate` parses every CEL
 predicate, checks each `record.<field>` resolves, and verifies widget bindings —
 failing with a **located, corrective** message. It's the same gate `os build`
-runs. See [Validating Metadata](/docs/getting-started/validating-metadata).
+runs. See [Validating Metadata](/docs/deployment/validating-metadata).
 
 ### 3. Contract-first — reject at the gate, never patch the runtime
 
@@ -106,7 +106,7 @@ protect what agents do to real data at runtime. See
   />
   <Card
     title="Validating Metadata"
-    href="/docs/getting-started/validating-metadata"
+    href="/docs/deployment/validating-metadata"
     description="Exactly what the authoring gate checks, and why typecheck isn't enough."
   />
 </Cards>
diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json
@@ -3,14 +3,16 @@
   "icon": "Rocket",
   "defaultOpen": true,
   "pages": [
+    "---Start Here---",
     "index",
+    "platform-capabilities",
     "how-ai-development-works",
     "build-with-claude-code",
     "your-first-project",
     "quick-start",
+    "build-without-code",
     "examples",
-    "cli",
-    "validating-metadata",
+    "---Cheatsheets---",
     "common-patterns",
     "quick-reference",
     "glossary"
diff --git a/content/docs/getting-started/platform-capabilities.mdx b/content/docs/getting-started/platform-capabilities.mdx
@@ -0,0 +1,71 @@
+---
+title: What Can It Do?
+description: A business-language tour of the platform's capabilities — data, views, automation, approvals, permissions, analytics, AI — with a real CRM as the running example
+---
+
+# What Can It Do?
+
+This page answers one question: **"can the platform do the business feature I need?"** — in business language, with no code. Every capability below ships in the platform today, and the official **HotCRM** template (one-click install from the Marketplace) implements all of them end to end, so you can open a running app and click through everything you read here.
+
+If you are a developer, the [Build sections](/docs/data-modeling) cover the same ground with full technical depth.
+
+## Manage business data
+
+Every kind of record — accounts, contacts, leads, opportunities, orders, tickets — is an **object** you can create and change at any time. Fields cover 40+ types: text, amounts with currency, dates, single/multi select with colored options, people pickers, star ratings, progress bars, addresses and map locations, images and file attachments, e-signatures, QR codes, tags, and auto-numbered document codes.
+
+Two field families do work for you:
+
+- **Formula fields** compute values automatically (*expected revenue = amount × probability*; *days until close*).
+- **Roll-up fields** total child rows onto the parent (*an opportunity's product total updates the moment a line item changes*).
+
+Records relate to each other: one account has many contacts and opportunities; an opportunity owns its product line items (edited inline as a grid, saved atomically); many-to-many and tree hierarchies are built in.
+
+## See data the way each team works
+
+The same records can be opened in **nine list views** — table, kanban board, calendar, gantt, gallery, timeline, map, tree, and chart — plus three form styles (simple, tabbed, multi-step wizard). Views are saved, named, and shared: sales reps drag deals across a *Pipeline* board grouped by stage, delivery managers plan the same data on a gantt, leadership reads it as charts. Filters support relative dates ("this quarter", "last 7 days" — 36 built-in tokens) so saved views stay current forever, and global search understands partial matches across objects.
+
+## Keep data clean at the point of entry
+
+Validation runs when records are saved, not at month-end: required fields, format checks, cross-field logic (*close date cannot be in the past*), and **state machines** that define which stage transitions are legal (*negotiation → won or lost; no skipping ahead*) — enforced by the runtime on every write. Public forms can be published to a URL for anonymous submission (web-to-lead), exposing only the fields you whitelist.
+
+## Let processes run themselves
+
+Automation flows are configured as visual diagrams and trigger five ways: when records change (with conditions that can compare old vs. new values), on schedules, relative to record dates (*30 days before contract expiry*), from user-launched wizards, or from external system calls. Inside a flow you can create and update records, send notifications (in-app, email, chat), branch on conditions, loop over record sets, wait for time or signals, and call external services.
+
+HotCRM ships sixteen of these ready-made: lead auto-assignment and conversion, opportunity stagnation alerts and won announcements, quote generation and expiry reminders, contract renewal tasks, case escalation with SLA monitoring and CSAT follow-up, campaign enrollment, and task reminders.
+
+## Approvals
+
+Any step that needs a human decision becomes an approval node: eight ways to pick approvers (specific person, position, submitter's manager, team, department including children, a person named on the record, or a shared queue) and four decision modes — first response, unanimous, M-of-N quorum, and **group sign-off** where each group must independently approve. Records lock while pending, approval status mirrors onto the record for filtering, overdue approvals escalate automatically, and *send back for revision* returns the record to the submitter for another round instead of a hard reject. Every decision is permanently logged.
+
+## Control who sees what
+
+Access is layered, and the runtime enforces it on every request — including reports, APIs, and AI:
+
+1. **Capability level** — which personas can create, read, edit, or delete each object, granted through permission sets (effective access is the union of everything granted).
+2. **Data depth** — five scopes from *own records only*, through *own and reports* (management chain), *business unit*, *unit and below*, up to *organization-wide*.
+3. **Record sharing** — declarative rules widen the baseline (*opportunities over $1M auto-share to the sales VP with edit access*), plus manual shares.
+4. **Field-level security** — the same record shows different fields to different people (*cost price visible to managers only*); hidden fields are stripped server-side everywhere.
+
+Organizations model business-unit trees and positions, with reporting lines driving the "my team's data" scopes. Every change is audited (who changed what, when, old and new values), and an explain facility answers "why can this person see this record?" layer by layer.
+
+## Analytics that answer questions
+
+Dashboards compose ~20 chart families — KPIs with period-over-period comparison arrows, bar/line/area trends, funnels, donuts, treemaps, tables and pivots — over centrally defined datasets, so a metric like "closed revenue" means the same thing on every chart. Dashboards take runtime filters (quarter, owner, source), and full-bleed TV-style display pages are supported for office screens. Reports come in tabular, summary, matrix, and joined forms, with scheduled email digests.
+
+## AI that respects the rules
+
+AI operates under the same permissions and audit trail as people. Ask questions in natural language and get answers **with charts**; let the AI create and update records or run actions (dangerous ones require confirmation, or route into a human-approval inbox); connect your own AI tooling — every deployment exposes its objects and actions as a governed MCP endpoint, so agents like Claude can operate the app you built. HotCRM includes a sales copilot (lead scoring, customer 360, email drafting, revenue forecasting) and a service copilot (case triage, live data Q&A).
+
+## Connect everything else
+
+Bulk import/export, generated REST APIs for every object, outbound webhooks on data changes, inbound triggers from external systems, ready-made connectors (Slack, generic REST), federation of existing external databases (query them in place — no migration), and a Marketplace of installable template apps. Interface text is translatable per language; HotCRM ships in four.
+
+## See it live
+
+```bash
+npm create objectstack@latest my-app && cd my-app
+npx os dev --ui        # → http://localhost:3000/_console/
+```
+
+Install **HotCRM** from the Marketplace and open the *Capability Map* — every section above links to a working screen.
diff --git a/content/docs/getting-started/quick-start.mdx b/content/docs/getting-started/quick-start.mdx
@@ -14,7 +14,7 @@ But you do need to **read** them. In AI development the human's job shifts from
 writing code to *verifying* what the agent produced: is the object modelled right,
 is that predicate scoped correctly, does the app match what you asked for? This
 page is a tour of the pieces so you can review an agent's work with confidence —
-and catch the things the [validation gate](/docs/getting-started/validating-metadata)
+and catch the things the [validation gate](/docs/deployment/validating-metadata)
 can't.
 
 <Callout type="tip">
@@ -153,7 +153,7 @@ npx os dev --ui     # boot the app, then open http://localhost:3000/_console/
 `os validate` proves the metadata is *well-formed*; the **Console** at `/_console/`
 proves it does what you *meant* — create a record, watch an action show/hide,
 confirm the nav and filters. That visual check is the human's half of every build
-loop. See [Validating Metadata](/docs/getting-started/validating-metadata) for what
+loop. See [Validating Metadata](/docs/deployment/validating-metadata) for what
 the gate catches, and [Build with Claude Code](/docs/getting-started/build-with-claude-code)
 for the full describe → author → validate → verify cycle.
 
@@ -186,5 +186,5 @@ for the full describe → author → validate → verify cycle.
 
 - [Build with Claude Code](/docs/getting-started/build-with-claude-code) &mdash; Build a real app end-to-end with an agent
 - [Example Apps](/docs/getting-started/examples) &mdash; Run the Todo, CRM, and showcase examples
-- [CLI Reference](/docs/getting-started/cli) &mdash; All available commands
+- [CLI Reference](/docs/deployment/cli) &mdash; All available commands
 - [Protocol Reference](/docs/references) &mdash; Complete schema documentation
diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx
diff --git a/content/docs/index.mdx b/content/docs/index.mdx
diff --git a/content/docs/meta.json b/content/docs/meta.json
diff --git a/content/docs/plugins/packages.mdx b/content/docs/plugins/packages.mdx
diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx
diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +---
++
 +docs: audience-first IA — sidebar sections (Learn / Build / Operate / Extend & Reference), tooling pages moved to Deployment with redirects, new business-facing capability tour and no-code building guide, reader-path cards on Core Concepts.