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

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

- 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 & 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 & Apps' in nav and home cards

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(i18n): English-only by decision — remove the cn shell

The cn language was declared in docs.site.json and mapped in middleware, but
lib/i18n.ts (what fumadocs actually consumes) only ever listed en and there is
zero cn content — a config-vs-runtime drift that made the site look bilingual.
Remove the declaration and the dead zh->cn Accept-Language mapping; keep the
i18n plumbing so a future language is content + one config line.

Verified: docs build passes; with Accept-Language: zh-CN, /docs serves the
English page with no /cn redirect.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(nav): declutter the sidebar — text-only, three sections, one screen

Feedback pass on the audience-first IA: the sidebar still read as crowded.
- Drop the hardcoded Docs/Blog links above the tree (layout.shared.tsx)
- Strip per-item icons from all 14 section meta.json files (text-only tree)
- Merge the one-item Operate section: Learn / Build / Platform
- Take References and Releases (lookup content, 22 generated/log pages) out
  of the tree — URLs still resolve (verified 200) and the docs home page
  links both; getting-started no longer defaultOpen so the first screen
  shows all twelve top-level entries at once

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(nav): surface the business-facing pages at the top of Learn

'What Can It Do?' and 'Build Without Code' were buried inside the
Get Started folder — the exact audience they serve would never expand it.
Promote both to top-level Learn entries (/docs/platform-capabilities,
/docs/build-without-code; new-in-this-PR pages, so no redirects needed),
and lead the docs-home 'Start here' list with them.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(capabilities): expand the business tour into a full section

'What Can It Do?' grows from one page into a Learn-section folder of ten
business-language pages — data, views, forms & quality, automation,
approvals, permissions, analytics, AI, integrations & everyday work, and a
requirements one-pager template. Each page keeps three anchors: business
scenarios, an 'In HotCRM' pointer at the running example, and a
'For developers' cross-link into the technical Build docs. The index
becomes a card directory; new pages drop hand-written H1s (frontmatter
title renders them). URL /docs/platform-capabilities → /docs/capabilities
(page introduced in this PR, so no redirect debt).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(capabilities): correct HotCRM flow count to 17 (verified against src/flows)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* chore(ratchet): migrate role-word baseline entry for relocated cli.mdx

The page moved getting-started → deployment in this PR; its single
pre-existing occurrence (a table header) moves with it. Net change zero.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: os-zhuang

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