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

.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.

apps/docs/lib/i18n.ts

@@ -2,10 +2,12 @@ import { defineI18n } from 'fumadocs-core/i18n';
 
 /**
  * i18n Configuration for ObjectStack Documentation
- * 
+ *
  * Supported Languages:
  * - en: English (Default)
- * - cn: Chinese (中文)
+ *
+ * The docs are English-only by decision (2026-07). To add a language later,
+ * list it here and provide content — routing already handles the rest.
  */
 export const i18n = defineI18n({
   defaultLanguage: 'en',

apps/docs/lib/layout.shared.tsx

@@ -17,10 +17,6 @@ export function baseOptions(): BaseLayoutProps {
         </div>
       ),
     },
-    links: [
-      { text: 'Docs', url: '/docs', active: 'nested-url' },
-      { text: 'Blog', url: '/blog', active: 'nested-url' },
-    ],
     githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`,
   };
 }

apps/docs/middleware.ts

@@ -19,35 +19,6 @@ function setLocaleCookie(response: NextResponse, locale: string): void {
   });
 }
 
-/**
- * Language code mapping
- * Maps browser language codes to our supported language codes
- */
-const LANGUAGE_MAPPING: Record<string, string> = {
-  'zh': 'cn',      // Chinese -> cn
-  'zh-CN': 'cn',   // Chinese (China) -> cn
-  'zh-TW': 'cn',   // Chinese (Taiwan) -> cn
-  'zh-HK': 'cn',   // Chinese (Hong Kong) -> cn
-};
-
-/**
- * Normalize language code to match our supported languages
- */
-function normalizeLanguage(lang: string): string {
-  // Check direct mapping first
-  if (LANGUAGE_MAPPING[lang]) {
-    return LANGUAGE_MAPPING[lang];
-  }
-
-  // Check if the base language (without region) is mapped
-  const baseLang = lang.split('-')[0];
-  if (LANGUAGE_MAPPING[baseLang]) {
-    return LANGUAGE_MAPPING[baseLang];
-  }
-
-  return lang;
-}
-
 /**
  * Get the preferred language from the request
  */
@@ -62,12 +33,9 @@ function getPreferredLanguage(request: NextRequest): string {
   const negotiatorHeaders = Object.fromEntries(request.headers.entries());
   const negotiator = new Negotiator({ headers: negotiatorHeaders });
   const browserLanguages = negotiator.languages();
-
-  // Normalize browser languages to match our supported languages
-  const normalizedLanguages = browserLanguages.map(normalizeLanguage);
-
+
   // Find the first match
-  for (const lang of normalizedLanguages) {
+  for (const lang of browserLanguages) {
     if (SUPPORTED_LANGUAGES.includes(lang)) {
       return lang;
     }
@@ -82,9 +50,11 @@ function getPreferredLanguage(request: NextRequest): string {
  * This middleware:
  * - Detects the user's preferred language from browser settings or cookies
  * - Redirects users to the appropriate localized version
- * - For default language (en): keeps URL as "/" (with internal rewrite)
- * - For other languages (cn): redirects to "/cn/"
+ * - For the default language (en): keeps URL as "/" (with internal rewrite)
  * - Stores language preference as a cookie
+ *
+ * The docs are English-only by decision (2026-07); the i18n plumbing stays so a
+ * future language only needs entries in lib/i18n.ts and content, not new routing.
  */
 export default function middleware(request: NextRequest) {
   const { pathname } = request.nextUrl;

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'],

content/docs.site.json

@@ -8,7 +8,8 @@
   "i18n": {
     "enabled": true,
     "defaultLanguage": "en",
-    "languages": ["en", "cn"
+    "languages": [
+      "en"
     ]
   },
   "branding": {
@@ -18,7 +19,7 @@
       "dark": "/logo.svg"
     },
     "theme": {
-      "accentColor": "blue", 
+      "accentColor": "blue",
       "radius": "0.5rem"
     }
   },
@@ -34,7 +35,10 @@
         }
       ],
       "socials": [
-        { "platform": "github", "url": "https://github.com/objectstack-ai/spec" }
+        {
+          "platform": "github",
+          "url": "https://github.com/objectstack-ai/spec"
+        }
       ]
     },
     "sidebar": {

content/docs/ai/meta.json

@@ -1,6 +1,5 @@
 {
   "title": "AI",
-  "icon": "Bot",
   "pages": [
     "index",
     "connect-mcp",

content/docs/api/meta.json

@@ -1,6 +1,5 @@
 {
   "title": "API & SDK",
-  "icon": "Plug",
   "pages": [
     "index",
     "data-api",

content/docs/automation/meta.json

@@ -1,6 +1,5 @@
 {
   "title": "Automation",
-  "icon": "Workflow",
   "pages": [
     "index",
     "hooks",

content/docs/build-without-code.mdx

@@ -0,0 +1,41 @@
+---
+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
+---
+
+
+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.

content/docs/capabilities/ai.mdx

@@ -0,0 +1,29 @@
+---
+title: AI Under Governance
+description: Ask questions and get charts, let AI act under the same permissions and audit as people, and connect your own agents over MCP
+---
+
+
+The platform's rule for AI is simple: **an agent gets exactly the access its user has — never more — and every action is audited.** AI here is not a bolt-on chat window; it operates through the same typed, permission-checked surface as the UI and the API.
+
+## Ask, and get answers with charts
+
+Ask in natural language — *"top ten opportunities by amount in the East region this quarter?"* — and get the result as data **and as a chart**, inline. No SQL, no export-to-spreadsheet detour.
+
+## Let AI do the work
+
+Conversationally create and update records, run actions, and drive processes: *"convert this lead; the account name is Acme Ltd."* Risky operations ask for confirmation first, or can be routed into a human-review inbox so AI proposes and people approve.
+
+## Knowledge answers
+
+Connect product sheets, playbooks, and policy docs, and the assistant answers from **your** knowledge — with the same permission filtering on what each person may retrieve.
+
+## Bring your own agent (MCP)
+
+Every deployment exposes its objects and permitted actions as an **MCP server** — on by default at `/api/v1/mcp`. Point Claude or any MCP client at your app and that agent can inspect and operate it, under the signed-in user's permissions, with every call audited. Your app is AI-operable the day it ships, for free.
+
+> **In HotCRM**: two copilots ship ready — a **sales copilot** (lead scoring, customer-360 summaries, email drafting, revenue forecasting) and a **service copilot** (case triage, live-data Q&A) — built from six reusable AI skills. Swap the skills to retarget them at your own domain.
+
+*The conversational UI is part of the commercial runtime; the MCP surface — bring-your-own-agent — ships in open source.*
+
+**For developers**: agents, skills, and MCP configuration in [AI](/docs/ai).

content/docs/capabilities/analytics.mdx

@@ -0,0 +1,32 @@
+---
+title: Analytics & Dashboards
+description: ~20 chart families, period-over-period comparison, runtime filters, TV display pages, four report shapes, and scheduled email digests
+---
+
+
+The executive cockpit and the ops detail report are both configured, not built. Data is live, and permissions apply inside every chart — each viewer sees only the numbers they are allowed to see.
+
+## Dashboards
+
+Compose from roughly twenty chart families:
+
+- **Single values**: KPI tiles, gauges, progress rings — total pipeline, quarter-to-date closed, target attainment.
+- **Comparisons**: bar and column by stage, rep, or product line.
+- **Trends**: line and area over time.
+- **Composition**: pie, donut, **funnel** (stage conversion), treemap.
+- **Detail**: tables and pivot tables.
+
+Dashboard extras that matter in practice:
+
+- **Period-over-period in one switch** — KPI tiles grow a "+12% vs. last period" arrow; trend charts overlay the prior period as a dashed line.
+- **Runtime filters across the top** — quarter, owner, lead source; every widget follows the selection.
+- **Full-bleed display pages** — dark, TV-styled dashboards for the office screen, with auto-fitting KPI and chart layout.
+- **One metric, one definition** — indicators like "closed revenue" are defined once in shared datasets, so two dashboards can never disagree about what the number means.
+
+## Reports
+
+Four shapes — **tabular** (detail rows), **summary** (grouped totals), **matrix** (regions × quarters), and **joined** (multi-object) — with runtime filters and export. **Scheduled email digests** deliver a report daily or weekly: the Monday-morning sales report writes itself.
+
+> **In HotCRM**: four dashboards (executive, sales, service, CRM overview) and six reports (lead, opportunity, account, case, churn), fed by six shared datasets covering accounts, contacts, leads, opportunities, products, and cases. The executive dashboard carries quarter and owner filters plus the funnel and trend widgets described above.
+
+**For developers**: dashboards, charts, and reports as metadata in [Views & Apps](/docs/ui/dashboards).

content/docs/capabilities/approvals.mdx

@@ -0,0 +1,34 @@
+---
+title: Approvals
+description: Eight ways to pick approvers, four decision modes including group sign-off, record locking, overdue escalation, and send-back-for-revision
+---
+
+
+Discounts, contracts, spend — anything that needs a human "yes" becomes an approval step in a flow, replacing the group-chat shoulder tap with a tracked, enforceable decision.
+
+## Who approves — eight resolution styles
+
+A specific person · everyone holding a position (e.g. sales managers) · the submitter's direct manager · a team · a department (optionally including sub-departments) · organization leadership · **a person named on the record itself** (e.g. the "regional director" field) · a shared queue (first responder claims it).
+
+## How it passes — four decision modes
+
+| Mode | Rule | Fits |
+|---|---|---|
+| First response | Any one approval passes it | Routine low-value requests |
+| Unanimous | Everyone must approve | Major contracts |
+| M-of-N quorum | e.g. 3 of 5 | Committee reviews |
+| **Group sign-off** | Each group must independently approve | Finance *and* legal must each clear it |
+
+Any rejection ends the chain immediately. Multi-level ladders (manager → director → VP) are just chained steps, and conditions route by amount — under 100k ends at manager, over 500k adds the VP.
+
+## Process controls
+
+- **Record locking** while pending — no editing the deal mid-approval (configurable).
+- **Status mirrored onto the record** — lists can filter by "pending approval".
+- **Overdue escalation (SLA)** — after N hours: reassign, auto-approve, auto-reject, or notify, your choice.
+- **Send back for revision** — return to the submitter for changes and a fresh round, distinct from a hard reject; retry count can be capped.
+- **An approvals inbox** for batch processing, and a permanent audit trail of who decided what, when, and why.
+
+> **In HotCRM**: the opportunity approval flow routes large or deep-discount deals to management, mirrors the outcome onto the record, and locks it while pending.
+
+**For developers**: approval nodes and approver metadata in [Automation → Approvals](/docs/automation/approvals).

content/docs/capabilities/automation.mdx

@@ -0,0 +1,29 @@
+---
+title: Automation — Processes That Run Themselves
+description: Five trigger styles, visual flow diagrams, notifications, branching, loops, waits, and external calls — the work nobody should have to remember
+---
+
+
+Anything that today relies on someone remembering — reminders, hand-offs, escalations, follow-ups — becomes a **flow**: a visual diagram the platform executes reliably, with a run history you can inspect.
+
+## Five ways a flow starts
+
+1. **When records change** — created, updated, or deleted, with conditions that can compare old vs. new values (*"amount crossed 500k"* fires once, not on every unrelated edit).
+2. **On a schedule** — every morning at 8, every Monday, the 1st of each month.
+3. **Relative to record dates** — *30 days before contract expiry*, *7 days after signing*, evaluated per record.
+4. **Launched by a person** — button-triggered wizards like "Convert lead".
+5. **Called by an external system** — your website or ERP pings an endpoint and the flow runs.
+
+## What flows can do
+
+Create, update, and delete records · send notifications (in-app, email, chat) · branch on conditions · run steps in parallel and join · loop over a set of records · wait for a duration or a signal · call external services · invoke shared sub-flows.
+
+## Reliability you can see
+
+Flows are enabled or disabled with a switch and start life as drafts. Every execution leaves a run record — which node, what outcome — and the diagram in Studio *is* the executable logic, so documentation never drifts from behavior.
+
+> **In HotCRM**: seventeen flows run the whole sales-and-service motion —
+> lead auto-assignment · lead conversion · opportunity approval · stagnation alerts · won announcements · quote generation · quote expiry reminders · contract expiration · renewal task creation · case escalation · case SLA monitoring · CSAT follow-up · campaign enrollment · campaign completion · new-contact welcome · task due reminders · urgent-task alerts.
+> Open any of them in Studio's Automation pillar to read the diagram.
+
+**For developers**: triggers, nodes, and flow metadata in [Automation](/docs/automation).

content/docs/capabilities/data.mdx

@@ -0,0 +1,46 @@
+---
+title: Manage Business Data
+description: Objects, 40+ field types, auto-computed fields, and relationships — every spreadsheet you run the business on, structured and governed
+---
+
+
+Every kind of record your team tracks — accounts, contacts, leads, opportunities, orders, tickets — becomes an **object**: a structured, permission-controlled, connected table you can create and change at any time. Columns become **fields**, and adding or changing a field is a configuration change, not a development request.
+
+## Field types for everything you record
+
+| You want to record | Field types |
+|---|---|
+| Names, notes, long text | Text / textarea / rich text |
+| Money, quantities, ratios | Currency amount / number / percent |
+| Dates and times | Date / datetime / time |
+| Choices | Single select (colored options) / multi-select / radio / checkbox group |
+| Yes-or-no | Boolean toggle |
+| People | Owner / user pickers |
+| Links to other records | Lookup (opportunity → account) / master-detail (opportunity → line items) |
+| Ratings and progress | Star rating / progress bar / slider |
+| Contact details | Phone / email / URL |
+| Places | Address / map location |
+| Images and files | Image / attachment / avatar / audio / video |
+| Signatures and codes | E-signature / QR code / barcode |
+| Labels | Tags |
+| Document numbers | Auto-number (e.g. `SO-2026-0001`) |
+
+## Fields that compute themselves
+
+- **Formula fields** derive values automatically: *expected revenue = amount × probability*, *days until close date*. When inputs change, the value updates — nobody maintains it.
+- **Roll-up summaries** total child rows onto the parent: an opportunity's product total is always the sum of its line items, recalculated the moment a line changes.
+
+## Records that connect
+
+- **One-to-many**: an account has many contacts and opportunities; the account page shows them all as related lists.
+- **Master-detail**: an opportunity owns its product line items — edited inline as a grid inside the opportunity form, saved in one step, and removed with their parent.
+- **Many-to-many**: contacts participate in many campaigns; campaigns have many members.
+- **Hierarchies**: product category trees, org structures, parent-subsidiary account chains.
+
+## Quality built into the data itself
+
+Uniqueness, required-ness, searchability, and history tracking are per-field switches. Records support soft delete (a recycle bin, not permanent loss), cloning, and full change history when tracking is on.
+
+> **In HotCRM**: 15 business objects model the full sales-and-service domain — lead, account, contact, opportunity (+ line items), quote (+ line items), product, contract, case, knowledge article, campaign (+ members), task, and forecast. Open any of them in Studio to see these field types in real use.
+
+**For developers**: the same ground with full technical depth in [Data Modeling](/docs/data-modeling).