From 873c099c0d960d5c7ac943eb94f3ccfd985a98a9 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 01:01:45 +0800 Subject: [PATCH 1/7] =?UTF-8?q?docs(ia):=20audience-first=20navigation=20?= =?UTF-8?q?=E2=80=94=20Learn/Build/Operate/Extend=20sections=20+=20busines?= =?UTF-8?q?s-facing=20entry=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .changeset/docs-audience-first-ia.md | 4 ++ apps/docs/redirects.mjs | 5 +- content/docs/concepts/index.mdx | 11 +++ .../{getting-started => deployment}/cli.mdx | 2 +- content/docs/deployment/meta.json | 2 + content/docs/deployment/self-hosting.mdx | 4 +- .../docs/deployment/single-project-mode.mdx | 2 +- .../validating-metadata.mdx | 2 +- .../build-with-claude-code.mdx | 2 +- .../getting-started/build-without-code.mdx | 42 +++++++++++ .../docs/getting-started/common-patterns.mdx | 2 +- content/docs/getting-started/examples.mdx | 2 +- .../how-ai-development-works.mdx | 4 +- content/docs/getting-started/meta.json | 6 +- .../getting-started/platform-capabilities.mdx | 71 +++++++++++++++++++ content/docs/getting-started/quick-start.mdx | 6 +- .../getting-started/your-first-project.mdx | 6 +- content/docs/index.mdx | 2 +- content/docs/meta.json | 10 ++- content/docs/plugins/packages.mdx | 2 +- content/docs/references/index.mdx | 2 +- content/docs/ui/meta.json | 2 +- 22 files changed, 165 insertions(+), 26 deletions(-) create mode 100644 .changeset/docs-audience-first-ia.md rename content/docs/{getting-started => deployment}/cli.mdx (99%) rename content/docs/{getting-started => deployment}/validating-metadata.mdx (98%) create mode 100644 content/docs/getting-started/build-without-code.mdx create mode 100644 content/docs/getting-started/platform-capabilities.mdx diff --git a/.changeset/docs-audience-first-ia.md b/.changeset/docs-audience-first-ia.md new file mode 100644 index 0000000000..e9552b08ff --- /dev/null +++ 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 index db689d59d2..2f5ccb8e40 100644 --- 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 index 091ef17952..ea42d3a3ad 100644 --- 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: + + + + + + + + ## 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/getting-started/cli.mdx b/content/docs/deployment/cli.mdx similarity index 99% rename from content/docs/getting-started/cli.mdx rename to content/docs/deployment/cli.mdx index a6ca466bfb..d924dfde3b 100644 --- a/content/docs/getting-started/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). #### `os info` diff --git a/content/docs/deployment/meta.json b/content/docs/deployment/meta.json index bc2345ac15..1a4434dbc6 100644 --- 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 index 692751c9b0..4d11e9eb81 100644 --- 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 index 3239ea550b..7549ea717c 100644 --- 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/getting-started/validating-metadata.mdx b/content/docs/deployment/validating-metadata.mdx similarity index 98% rename from content/docs/getting-started/validating-metadata.mdx rename to content/docs/deployment/validating-metadata.mdx index 49b4586c02..2d1fbcff84 100644 --- a/content/docs/getting-started/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 index e31244390c..d479139ebe 100644 --- 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 new file mode 100644 index 0000000000..64e3d16b9a --- /dev/null +++ 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 index 91f082b466..cb0f0791d0 100644 --- 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). --- diff --git a/content/docs/getting-started/examples.mdx b/content/docs/getting-started/examples.mdx index ddcd838101..9f9a9d345e 100644 --- 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 index 2d407c9527..57b0c21198 100644 --- 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.` 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 /> diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index 4306d0f4f6..e9d66d1795 100644 --- 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 new file mode 100644 index 0000000000..2cc3ffec56 --- /dev/null +++ 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 index c08041442f..820acf5b5d 100644 --- 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. @@ -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) — Build a real app end-to-end with an agent - [Example Apps](/docs/getting-started/examples) — Run the Todo, CRM, and showcase examples -- [CLI Reference](/docs/getting-started/cli) — All available commands +- [CLI Reference](/docs/deployment/cli) — All available commands - [Protocol Reference](/docs/references) — Complete schema documentation diff --git a/content/docs/getting-started/your-first-project.mdx b/content/docs/getting-started/your-first-project.mdx index 2d3d546768..af3d89a1d0 100644 --- a/content/docs/getting-started/your-first-project.mdx +++ b/content/docs/getting-started/your-first-project.mdx @@ -75,7 +75,7 @@ the npm package and always works offline. `os init` (from `@objectstack/cli`) is an alternative scaffolder with `app` / -`plugin` / `empty` templates — see the [CLI reference](/docs/getting-started/cli#os-init). +`plugin` / `empty` templates — see the [CLI reference](/docs/deployment/cli#os-init). `npm create objectstack` is the recommended entry point for new standalone projects. @@ -238,7 +238,7 @@ npm run validate `os validate` checks schema compliance, CEL predicate scoping, and widget bindings — the classes of mistakes that otherwise fail *silently* at runtime. -See [Validating Metadata](/docs/getting-started/validating-metadata). +See [Validating Metadata](/docs/deployment/validating-metadata). Beyond pass/fail, `npx os lint --score` grades the data model 0–100 against the platform's design conventions (relationship patterns, missing select options, @@ -302,7 +302,7 @@ sync with the schemas you run. /> diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 1e7243c256..625571e48d 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -41,7 +41,7 @@ Each module documents one capability in depth — overview first, then guides, w - + diff --git a/content/docs/meta.json b/content/docs/meta.json index 685febfa3b..a8d55b4453 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -1,17 +1,21 @@ { "title": "Documentation", "pages": [ + "---Learn---", "getting-started", "concepts", + "---Build---", "data-modeling", + "ui", "automation", "permissions", - "ui", - "api", "ai", + "api", + "---Operate---", + "deployment", + "---Extend & Reference---", "plugins", "kernel", - "deployment", "protocol", "references", "releases" diff --git a/content/docs/plugins/packages.mdx b/content/docs/plugins/packages.mdx index 64dcc9b4c3..1ae906ed16 100644 --- a/content/docs/plugins/packages.mdx +++ b/content/docs/plugins/packages.mdx @@ -453,7 +453,7 @@ ObjectStack composes packages at two layers: 1. **Metadata** is declared inside `defineStack({...})` (objects, views, flows, agents, …) and lives in `objectstack.config.ts`. 2. **Runtime** plugins/services/drivers are wired into the host kernel through `kernel.use(...)`, `@objectstack/runtime`, or a custom adapter host. -The snippets below illustrate which **runtime** packages you typically reach for in each scenario. See the [Quick Start](/docs/getting-started/quick-start) and [CLI guide](/docs/getting-started/cli) for the full bootstrap pattern. +The snippets below illustrate which **runtime** packages you typically reach for in each scenario. See the [Quick Start](/docs/getting-started/quick-start) and [CLI guide](/docs/deployment/cli) for the full bootstrap pattern. ### For New Projects (edge / AI-native) diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx index 5197cb2863..88e268717b 100644 --- a/content/docs/references/index.mdx +++ b/content/docs/references/index.mdx @@ -411,7 +411,7 @@ const result = ObjectSchema.safeParse(objectDefinition); description="Key terminology across all protocol namespaces" /> diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json index f768aa09e4..2515e862cf 100644 --- a/content/docs/ui/meta.json +++ b/content/docs/ui/meta.json @@ -1,5 +1,5 @@ { - "title": "UI Engine", + "title": "Views & Apps", "icon": "LayoutDashboard", "pages": [ "index", From 3dfcfb150d9117a9d55edce7f7ce2d9c7198b1f4 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 01:41:08 +0800 Subject: [PATCH 2/7] =?UTF-8?q?docs(i18n):=20English-only=20by=20decision?= =?UTF-8?q?=20=E2=80=94=20remove=20the=20cn=20shell?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- apps/docs/lib/i18n.ts | 6 ++++-- apps/docs/middleware.ts | 42 ++++++----------------------------------- content/docs.site.json | 10 +++++++--- 3 files changed, 17 insertions(+), 41 deletions(-) diff --git a/apps/docs/lib/i18n.ts b/apps/docs/lib/i18n.ts index 977986aaab..e00fec1a92 100644 --- a/apps/docs/lib/i18n.ts +++ b/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', diff --git a/apps/docs/middleware.ts b/apps/docs/middleware.ts index fcc1a6000f..167fa2d014 100644 --- a/apps/docs/middleware.ts +++ b/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 = { - '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; diff --git a/content/docs.site.json b/content/docs.site.json index 7c610e2bd2..00d99abb39 100644 --- a/content/docs.site.json +++ b/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": { From d5907db834577543ace8c1e81cc0135a17701c64 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 09:46:34 +0800 Subject: [PATCH 3/7] =?UTF-8?q?docs(nav):=20declutter=20the=20sidebar=20?= =?UTF-8?q?=E2=80=94=20text-only,=20three=20sections,=20one=20screen?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- apps/docs/lib/layout.shared.tsx | 4 ---- content/docs/ai/meta.json | 1 - content/docs/api/meta.json | 1 - content/docs/automation/meta.json | 1 - content/docs/concepts/meta.json | 1 - content/docs/data-modeling/meta.json | 1 - content/docs/deployment/meta.json | 1 - content/docs/getting-started/meta.json | 2 -- content/docs/kernel/meta.json | 1 - content/docs/meta.json | 7 ++----- content/docs/permissions/meta.json | 1 - content/docs/plugins/meta.json | 1 - content/docs/protocol/meta.json | 1 - content/docs/references/meta.json | 3 +-- content/docs/releases/meta.json | 12 ++++++++++-- content/docs/ui/meta.json | 1 - 16 files changed, 13 insertions(+), 26 deletions(-) diff --git a/apps/docs/lib/layout.shared.tsx b/apps/docs/lib/layout.shared.tsx index e976ca3478..777a661cf7 100644 --- a/apps/docs/lib/layout.shared.tsx +++ b/apps/docs/lib/layout.shared.tsx @@ -17,10 +17,6 @@ export function baseOptions(): BaseLayoutProps { ), }, - links: [ - { text: 'Docs', url: '/docs', active: 'nested-url' }, - { text: 'Blog', url: '/blog', active: 'nested-url' }, - ], githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`, }; } diff --git a/content/docs/ai/meta.json b/content/docs/ai/meta.json index 6fdbbcf2ef..6d8375bfb3 100644 --- a/content/docs/ai/meta.json +++ b/content/docs/ai/meta.json @@ -1,6 +1,5 @@ { "title": "AI", - "icon": "Bot", "pages": [ "index", "connect-mcp", diff --git a/content/docs/api/meta.json b/content/docs/api/meta.json index 0d3ef025cc..6bd5e30c3b 100644 --- a/content/docs/api/meta.json +++ b/content/docs/api/meta.json @@ -1,6 +1,5 @@ { "title": "API & SDK", - "icon": "Plug", "pages": [ "index", "data-api", diff --git a/content/docs/automation/meta.json b/content/docs/automation/meta.json index 7b9c2678b7..011acd27dc 100644 --- a/content/docs/automation/meta.json +++ b/content/docs/automation/meta.json @@ -1,6 +1,5 @@ { "title": "Automation", - "icon": "Workflow", "pages": [ "index", "hooks", diff --git a/content/docs/concepts/meta.json b/content/docs/concepts/meta.json index c9bff39747..a22d51daac 100644 --- a/content/docs/concepts/meta.json +++ b/content/docs/concepts/meta.json @@ -1,6 +1,5 @@ { "title": "Core Concepts", - "icon": "Lightbulb", "pages": [ "index", "architecture", diff --git a/content/docs/data-modeling/meta.json b/content/docs/data-modeling/meta.json index 5e21d6bd09..8f867221a6 100644 --- a/content/docs/data-modeling/meta.json +++ b/content/docs/data-modeling/meta.json @@ -1,6 +1,5 @@ { "title": "Data Modeling", - "icon": "Database", "pages": [ "index", "schema-design", diff --git a/content/docs/deployment/meta.json b/content/docs/deployment/meta.json index 1a4434dbc6..84498c36e3 100644 --- a/content/docs/deployment/meta.json +++ b/content/docs/deployment/meta.json @@ -1,6 +1,5 @@ { "title": "Deployment & Operations", - "icon": "Cloud", "pages": [ "index", "cli", diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index e9d66d1795..f398aa46d0 100644 --- a/content/docs/getting-started/meta.json +++ b/content/docs/getting-started/meta.json @@ -1,7 +1,5 @@ { "title": "Get Started", - "icon": "Rocket", - "defaultOpen": true, "pages": [ "---Start Here---", "index", diff --git a/content/docs/kernel/meta.json b/content/docs/kernel/meta.json index 918f4d08f6..081e9463d1 100644 --- a/content/docs/kernel/meta.json +++ b/content/docs/kernel/meta.json @@ -1,6 +1,5 @@ { "title": "Kernel & Services", - "icon": "Cpu", "pages": [ "index", "architecture", diff --git a/content/docs/meta.json b/content/docs/meta.json index a8d55b4453..d6e0124ec1 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -11,13 +11,10 @@ "permissions", "ai", "api", - "---Operate---", + "---Platform---", "deployment", - "---Extend & Reference---", "plugins", "kernel", - "protocol", - "references", - "releases" + "protocol" ] } diff --git a/content/docs/permissions/meta.json b/content/docs/permissions/meta.json index 380e12fca9..d8e9385db9 100644 --- a/content/docs/permissions/meta.json +++ b/content/docs/permissions/meta.json @@ -1,6 +1,5 @@ { "title": "Permissions & Identity", - "icon": "Shield", "pages": [ "index", "administrator-guide", diff --git a/content/docs/plugins/meta.json b/content/docs/plugins/meta.json index b126a898e0..7b82331439 100644 --- a/content/docs/plugins/meta.json +++ b/content/docs/plugins/meta.json @@ -1,6 +1,5 @@ { "title": "Plugins & Packages", - "icon": "Puzzle", "pages": [ "index", "anatomy", diff --git a/content/docs/protocol/meta.json b/content/docs/protocol/meta.json index feaa9ac495..820a01f096 100644 --- a/content/docs/protocol/meta.json +++ b/content/docs/protocol/meta.json @@ -1,6 +1,5 @@ { "title": "Protocol Spec", - "icon": "Network", "pages": [ "index", "diagram", diff --git a/content/docs/references/meta.json b/content/docs/references/meta.json index 357008a34a..e098e161ab 100644 --- a/content/docs/references/meta.json +++ b/content/docs/references/meta.json @@ -1,6 +1,5 @@ { "title": "Reference", - "icon": "FileCode", "pages": [ "ai", "api", @@ -17,4 +16,4 @@ "system", "ui" ] -} \ No newline at end of file +} diff --git a/content/docs/releases/meta.json b/content/docs/releases/meta.json index 567ab0a947..68ca39dccb 100644 --- a/content/docs/releases/meta.json +++ b/content/docs/releases/meta.json @@ -1,5 +1,13 @@ { "title": "Releases", - "icon": "Tag", - "pages": ["index", "v16", "v15", "v14", "v13", "v12", "v9", "implementation-status"] + "pages": [ + "index", + "v16", + "v15", + "v14", + "v13", + "v12", + "v9", + "implementation-status" + ] } diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json index 2515e862cf..d4f688de6e 100644 --- a/content/docs/ui/meta.json +++ b/content/docs/ui/meta.json @@ -1,6 +1,5 @@ { "title": "Views & Apps", - "icon": "LayoutDashboard", "pages": [ "index", "apps", From 90247930a8b8fb572036f0f334c784aa5317be97 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 09:49:55 +0800 Subject: [PATCH 4/7] docs(nav): surface the business-facing pages at the top of Learn MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit '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 --- content/docs/{getting-started => }/build-without-code.mdx | 0 content/docs/concepts/index.mdx | 4 ++-- content/docs/getting-started/meta.json | 2 -- content/docs/index.mdx | 2 ++ content/docs/meta.json | 2 ++ content/docs/{getting-started => }/platform-capabilities.mdx | 0 6 files changed, 6 insertions(+), 4 deletions(-) rename content/docs/{getting-started => }/build-without-code.mdx (100%) rename content/docs/{getting-started => }/platform-capabilities.mdx (100%) diff --git a/content/docs/getting-started/build-without-code.mdx b/content/docs/build-without-code.mdx similarity index 100% rename from content/docs/getting-started/build-without-code.mdx rename to content/docs/build-without-code.mdx diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index ea42d3a3ad..9a9cfecca3 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -14,8 +14,8 @@ Before diving into code, understanding these foundational ideas will make everyt Different readers need different doors into this documentation — pick yours: - - + + diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index f398aa46d0..872357106d 100644 --- a/content/docs/getting-started/meta.json +++ b/content/docs/getting-started/meta.json @@ -3,12 +3,10 @@ "pages": [ "---Start Here---", "index", - "platform-capabilities", "how-ai-development-works", "build-with-claude-code", "your-first-project", "quick-start", - "build-without-code", "examples", "---Cheatsheets---", "common-patterns", diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 625571e48d..c14caaba3c 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -27,6 +27,8 @@ flowchart LR ## Start here +- [What Can It Do?](/docs/platform-capabilities) — the platform's capabilities in business language, no code — start here if you're evaluating +- [Build Without Code](/docs/build-without-code) — what admins and analysts do visually in Console, Studio, and Setup - [Build with Claude Code](/docs/getting-started/build-with-claude-code) — the main workflow: an agent builds the app, you verify it in the Console - [How AI Development Works](/docs/getting-started/how-ai-development-works) — why AI-builds / human-verifies is fast and safe - [What is ObjectStack?](/docs/getting-started) — the protocol model and runtime layers diff --git a/content/docs/meta.json b/content/docs/meta.json index d6e0124ec1..c17c3e91cc 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -2,6 +2,8 @@ "title": "Documentation", "pages": [ "---Learn---", + "platform-capabilities", + "build-without-code", "getting-started", "concepts", "---Build---", diff --git a/content/docs/getting-started/platform-capabilities.mdx b/content/docs/platform-capabilities.mdx similarity index 100% rename from content/docs/getting-started/platform-capabilities.mdx rename to content/docs/platform-capabilities.mdx From 191742639d01b2032d4494f8d54e2942a8f84c06 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 10:07:35 +0800 Subject: [PATCH 5/7] docs(capabilities): expand the business tour into a full section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit '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 --- content/docs/build-without-code.mdx | 1 - content/docs/capabilities/ai.mdx | 29 ++++++++ content/docs/capabilities/analytics.mdx | 32 +++++++++ content/docs/capabilities/approvals.mdx | 34 +++++++++ content/docs/capabilities/automation.mdx | 29 ++++++++ content/docs/capabilities/data.mdx | 46 ++++++++++++ content/docs/capabilities/forms.mdx | 30 ++++++++ content/docs/capabilities/index.mdx | 33 +++++++++ content/docs/capabilities/integrations.mdx | 30 ++++++++ content/docs/capabilities/meta.json | 16 +++++ content/docs/capabilities/permissions.mdx | 29 ++++++++ .../docs/capabilities/request-template.mdx | 42 +++++++++++ content/docs/capabilities/views.mdx | 34 +++++++++ content/docs/concepts/index.mdx | 2 +- content/docs/index.mdx | 2 +- content/docs/meta.json | 2 +- content/docs/platform-capabilities.mdx | 71 ------------------- content/docs/references/meta.json | 3 +- 18 files changed, 389 insertions(+), 76 deletions(-) create mode 100644 content/docs/capabilities/ai.mdx create mode 100644 content/docs/capabilities/analytics.mdx create mode 100644 content/docs/capabilities/approvals.mdx create mode 100644 content/docs/capabilities/automation.mdx create mode 100644 content/docs/capabilities/data.mdx create mode 100644 content/docs/capabilities/forms.mdx create mode 100644 content/docs/capabilities/index.mdx create mode 100644 content/docs/capabilities/integrations.mdx create mode 100644 content/docs/capabilities/meta.json create mode 100644 content/docs/capabilities/permissions.mdx create mode 100644 content/docs/capabilities/request-template.mdx create mode 100644 content/docs/capabilities/views.mdx delete mode 100644 content/docs/platform-capabilities.mdx diff --git a/content/docs/build-without-code.mdx b/content/docs/build-without-code.mdx index 64e3d16b9a..0e14a66039 100644 --- a/content/docs/build-without-code.mdx +++ b/content/docs/build-without-code.mdx @@ -3,7 +3,6 @@ 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. diff --git a/content/docs/capabilities/ai.mdx b/content/docs/capabilities/ai.mdx new file mode 100644 index 0000000000..2afdf26e62 --- /dev/null +++ b/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). diff --git a/content/docs/capabilities/analytics.mdx b/content/docs/capabilities/analytics.mdx new file mode 100644 index 0000000000..758cf00ad6 --- /dev/null +++ b/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). diff --git a/content/docs/capabilities/approvals.mdx b/content/docs/capabilities/approvals.mdx new file mode 100644 index 0000000000..dc2e1422f4 --- /dev/null +++ b/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). diff --git a/content/docs/capabilities/automation.mdx b/content/docs/capabilities/automation.mdx new file mode 100644 index 0000000000..c0f1162610 --- /dev/null +++ b/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**: sixteen 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. +> Open any of them in Studio's Automation pillar to read the diagram. + +**For developers**: triggers, nodes, and flow metadata in [Automation](/docs/automation). diff --git a/content/docs/capabilities/data.mdx b/content/docs/capabilities/data.mdx new file mode 100644 index 0000000000..815a3d2e9b --- /dev/null +++ b/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). diff --git a/content/docs/capabilities/forms.mdx b/content/docs/capabilities/forms.mdx new file mode 100644 index 0000000000..756e8684f1 --- /dev/null +++ b/content/docs/capabilities/forms.mdx @@ -0,0 +1,30 @@ +--- +title: Forms & Data Quality +description: Sectioned and wizard forms, validation at the moment of entry, legal stage transitions, and public forms for anonymous submission +--- + + +Bad data is cheapest to stop at the moment it is typed. Forms, validation rules, and stage machines catch problems on save — not at month-end reconciliation. + +## Forms that fit the work + +- **Sectioned forms**: fields grouped under "Basics / Commercial terms / Internal notes". +- **Multi-step wizards**: complex entry split into steps — e.g. lead conversion: confirm the account → create the opportunity → carry over products. +- **Conditional visibility**: show or require fields only when relevant — *"Closed-won" makes "Contract date" visible and required; "Closed-lost" requires a loss reason.* +- **Inline line items**: master-detail children (opportunity products) edited as a grid inside the parent form, saved atomically. +- **Defaults**: owner defaults to the current user, dates default to today, values can derive from context. + +## Validation that actually blocks bad saves + +- **Required fields** — cannot save without them. +- **Format checks** — email, phone, and code patterns rejected inline. +- **Cross-field logic** — *end date cannot precede start date; discounts above 40% cannot be saved* (route exceptions through an [approval](/docs/capabilities/approvals) instead). +- **Stage machines** — declare which status transitions are legal (*negotiation → won or lost only; no skipping from first-contact to won*). The runtime enforces this on every write — API and import included — so process discipline does not depend on memory. + +## Public forms (web-to-lead) + +Publish a form to a URL and put it on your website, a landing page, or a QR code. Anonymous visitors submit; each submission lands as a record (typically a lead) containing only the fields you chose to expose. Pair it with [automation](/docs/capabilities/automation) to assign and notify instantly. + +> **In HotCRM**: the lead-conversion wizard, opportunity stage machine, and a guest-portal permission profile for public submission are all wired in — try saving an opportunity backwards through its stages and watch the platform refuse. + +**For developers**: [validation and state machines](/docs/data-modeling/validation) in Data Modeling. diff --git a/content/docs/capabilities/index.mdx b/content/docs/capabilities/index.mdx new file mode 100644 index 0000000000..e7b105ff47 --- /dev/null +++ b/content/docs/capabilities/index.mdx @@ -0,0 +1,33 @@ +--- +title: What Can It Do? +description: The platform's capabilities in business language — data, views, automation, approvals, permissions, analytics, AI, integrations — each with a real CRM as the running example +--- + + +This section answers one question: **"can the platform do the business feature I need?"** — in business language, with no code. Everything described here ships in the platform today, and the official **HotCRM** template (one-click install from the Marketplace) implements all of it end to end — every page below points at the running example, so nothing is hypothetical. + +If you are a developer, the [Build sections](/docs/data-modeling) cover the same ground with full technical depth; each page here links to its technical counterpart. + +## The capabilities + + + + + + + + + + + + + + +## 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: 15 business objects, 16 automation flows, 6 permission profiles, 4 dashboards, 6 reports, and 2 AI copilots — every page in this section names where to look inside it. diff --git a/content/docs/capabilities/integrations.mdx b/content/docs/capabilities/integrations.mdx new file mode 100644 index 0000000000..fe404e021e --- /dev/null +++ b/content/docs/capabilities/integrations.mdx @@ -0,0 +1,30 @@ +--- +title: Integrations & Everyday Work +description: Import/export, generated APIs, webhooks, connectors, federated external databases, marketplace templates — plus collaboration and languages +--- + + +A business system earns its keep by fitting into the systems — and habits — you already have. + +## Connect other systems + +- **Bulk import / export** — move spreadsheets in and out; migrate the old system's accounts in one pass. +- **Generated REST APIs** — every object gets standard endpoints automatically, so your website, mini-program, or ERP reads and writes through the same permission gate as people. +- **Webhooks out** — data changes notify external systems (*deal won → billing system opens an invoice*). +- **Triggers in** — external systems start platform [flows](/docs/capabilities/automation). +- **Connectors** — ready-made Slack and generic REST connectors drop into flows. +- **Federated external databases** — point at an existing database and query it in place: no migration, visible in views, usable in flows. +- **Marketplace templates** — install complete apps (HotCRM among them) with one click: objects, views, flows, dashboards, and seed data included, then customize in Studio. +- **Deploy anywhere** — cloud or fully self-hosted; your data and your app definition stay yours. + +## Everyday collaboration + +Discussion threads on every record (@-mention colleagues in context) · file attachments · an activity timeline of key changes · a unified notification center for approvals, flow alerts, and mentions · full change history on tracked objects · a recycle bin for soft-deleted records · one-click record cloning · recently-visited lists. + +## Languages + +Interface text — labels, options, messages — is translatable per language, and each user reads the UI in their own locale. Coverage reporting shows what remains untranslated before launch. + +> **In HotCRM**: the interface ships in four languages (English, Chinese, Japanese, Spanish); the Slack connector and web-to-lead intake demonstrate both directions of integration. + +**For developers**: [API & SDK](/docs/api), [connectors and webhooks](/docs/automation), and [translations](/docs/ui/translations). diff --git a/content/docs/capabilities/meta.json b/content/docs/capabilities/meta.json new file mode 100644 index 0000000000..993aafaa55 --- /dev/null +++ b/content/docs/capabilities/meta.json @@ -0,0 +1,16 @@ +{ + "title": "What Can It Do?", + "pages": [ + "index", + "data", + "views", + "forms", + "automation", + "approvals", + "permissions", + "analytics", + "ai", + "integrations", + "request-template" + ] +} diff --git a/content/docs/capabilities/permissions.mdx b/content/docs/capabilities/permissions.mdx new file mode 100644 index 0000000000..848d20747f --- /dev/null +++ b/content/docs/capabilities/permissions.mdx @@ -0,0 +1,29 @@ +--- +title: Permissions — Who Sees What +description: Four layers from object capability to per-field visibility, five data-depth scopes, sharing rules, audit, and an explain facility +--- + + +Access control here is not an account setting — it is a four-layer model the runtime enforces **on every request**, whether it arrives from the UI, a report, the API, or an AI agent. There is no back door to forget about. + +## The four layers + +1. **Capability** — which personas may create, read, edit, or delete each object. Granted through permission sets; effective access is the union of everything granted. +2. **Data depth** — how far each person's read reaches, in five scopes: *own records only* → *own and reports* (follows the management chain) → *business unit* → *unit and below* → *organization-wide*. A rep sees their deals; their manager sees the team's; the regional lead sees the region's. +3. **Record sharing** — declarative rules that widen the baseline (*opportunities above ¥1M auto-share to the national sales VP, editable*), plus one-off manual shares to a person, position, or department. +4. **Field-level security** — the same record shows different fields to different people: cost price and commission rate visible to managers only. Hidden fields are stripped server-side, so they are absent from reports and API responses too — not merely hidden on screen. + +## Organization model + +People sit in a **business-unit tree** and hold **positions**; reporting lines drive the "own and reports" scope. Permissions follow the position, so a transfer is a reassignment, not a re-grant. + +## Safe by default, explainable always + +- Every object must declare its sharing posture explicitly — "forgot to configure, so everyone can see it" cannot happen. +- **Audit** records who changed what, when, with old and new values; tracked objects expose a history timeline on the record. +- **Explain** answers "why can this person see this record?" layer by layer — permission questions get diagnosed, not guessed at. +- Sign-in hardening for the enterprise tier: SSO, enforced MFA, password policy and breach checks, lockout throttling. + +> **In HotCRM**: six ready-made permission profiles — system admin, sales manager, sales rep, marketing, service agent, and a guest portal profile that can only submit the public form — plus sharing rules on accounts, opportunities, and cases, and a sales position ladder. Start from these and adjust. + +**For developers**: the full model in [Permissions & Identity](/docs/permissions). diff --git a/content/docs/capabilities/request-template.mdx b/content/docs/capabilities/request-template.mdx new file mode 100644 index 0000000000..2978adfd7d --- /dev/null +++ b/content/docs/capabilities/request-template.mdx @@ -0,0 +1,42 @@ +--- +title: How to Request Features +description: A one-page template that turns business needs into the platform's vocabulary — hand it to your implementation team or an AI agent and get a running system +--- + + +The fastest requirement conversations happen in the platform's own vocabulary. Answer these seven questions and what you hand over is not a requirements document — it is most of the configuration. + +```text +【Objects】 What data will you manage? What fields does each need? + e.g. Opportunity = name, account (lookup), amount, stage + (select: prospecting / qualified / proposal / negotiation / + closed), expected close date, win probability, + expected revenue (formula), product line items (master-detail) + +【Views】 Who looks at it, and through which lens? + e.g. reps → kanban by stage; managers → team table; + executives → dashboard + +【Rules】 What must be blocked at entry? Which stage moves are legal? + e.g. discounts over 40% cannot save; negotiation → won/lost only + +【Automation】When should the system act on its own? + e.g. amount crosses 500k → notify the regional manager; + 30 days before contract expiry → create a renewal task + +【Approvals】 Which actions need a human yes? Who? What counts as passed? + e.g. discount > 30% → finance and sales director group + sign-off; 24h overdue → escalate to VP + +【Access】 Who sees which records — and which fields? + e.g. regions isolated; cost price managers-only; + deals > 1M auto-share to the VP + +【Reports】 What numbers do leaders watch, and how often? + e.g. funnel + monthly trend dashboard; Monday email digest +``` + +Two habits make this even faster: + +1. **Point at HotCRM**: *"like HotCRM's opportunity approval, but with a second tier above 2M"* — referencing a running example beats describing from scratch. Explore it via [What Can It Do?](/docs/capabilities) or install it from the Marketplace. +2. **Hand the filled template to an AI agent**: the platform is built so that agents author configuration from exactly this kind of description — see [How AI Development Works](/docs/getting-started/how-ai-development-works). diff --git a/content/docs/capabilities/views.mdx b/content/docs/capabilities/views.mdx new file mode 100644 index 0000000000..bb31e3a950 --- /dev/null +++ b/content/docs/capabilities/views.mdx @@ -0,0 +1,34 @@ +--- +title: Views — See Data Your Way +description: Nine list views over the same records — table, kanban, calendar, gantt, gallery, timeline, map, tree, chart — plus saved filters and global search +--- + + +The same records can be opened through different lenses, and each team picks the lens that matches how they work. Views are declared, named, saved, and shared — not coded. + +## Nine list views + +| View | What it looks like | Typical CRM use | +|---|---|---| +| **Table** | Spreadsheet-style list: sort, filter, group, hide columns | The opportunity master list | +| **Kanban** | Cards in columns by stage; drag a card to change stage | Sales pipeline by stage, with amount and owner on each card | +| **Calendar** | Records on a date grid | Follow-up tasks, visits, expected close dates | +| **Gantt** | Time bars with dependencies | Delivery and implementation plans | +| **Gallery** | Large-image cards | Product catalogs, reference cases | +| **Timeline** | Records along a time axis | Customer interaction history | +| **Map** | Records pinned by location | Territory coverage, field-visit routing | +| **Tree** | Expandable hierarchy | Corporate account structures | +| **Chart** | The list rendered as a chart | See [Analytics](/docs/capabilities/analytics) | + +One object can carry many named views at once — "My open deals (table)", "East-region pipeline (kanban)", "Delivery schedule (gantt)" — and a default can be set per team. + +## Finding anything + +- **Global search** (`⌘K`) spans objects and understands partial matches — including **pinyin search**, so typing `zhangsan` finds 张三. +- **Filters** combine any fields with and/or logic and a full operator set (equals, contains, greater than, between, is empty…). +- **Relative dates**: "this quarter", "last month", "past 7 days", "next 30 days" — 36 built-in tokens plus custom offsets. A saved view filtered on "this quarter" rolls forward every day by itself. +- **Per-person scoping**: views like "My accounts" or "My team's opportunities" resolve per viewer automatically, following the permission model. + +> **In HotCRM**: twelve view files cover every object — open the Opportunity object and switch between its pipeline kanban, forecast table, and close-date calendar to feel the difference lenses make. + +**For developers**: view metadata in [Views & Apps](/docs/ui). diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index 9a9cfecca3..770a241834 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -14,7 +14,7 @@ Before diving into code, understanding these foundational ideas will make everyt Different readers need different doors into this documentation — pick yours: - + diff --git a/content/docs/index.mdx b/content/docs/index.mdx index c14caaba3c..ab66088b98 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -27,7 +27,7 @@ flowchart LR ## Start here -- [What Can It Do?](/docs/platform-capabilities) — the platform's capabilities in business language, no code — start here if you're evaluating +- [What Can It Do?](/docs/capabilities) — the platform's capabilities in business language, no code — start here if you're evaluating - [Build Without Code](/docs/build-without-code) — what admins and analysts do visually in Console, Studio, and Setup - [Build with Claude Code](/docs/getting-started/build-with-claude-code) — the main workflow: an agent builds the app, you verify it in the Console - [How AI Development Works](/docs/getting-started/how-ai-development-works) — why AI-builds / human-verifies is fast and safe diff --git a/content/docs/meta.json b/content/docs/meta.json index c17c3e91cc..1855420376 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -2,7 +2,7 @@ "title": "Documentation", "pages": [ "---Learn---", - "platform-capabilities", + "capabilities", "build-without-code", "getting-started", "concepts", diff --git a/content/docs/platform-capabilities.mdx b/content/docs/platform-capabilities.mdx deleted file mode 100644 index 2cc3ffec56..0000000000 --- a/content/docs/platform-capabilities.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -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/references/meta.json b/content/docs/references/meta.json index e098e161ab..357008a34a 100644 --- a/content/docs/references/meta.json +++ b/content/docs/references/meta.json @@ -1,5 +1,6 @@ { "title": "Reference", + "icon": "FileCode", "pages": [ "ai", "api", @@ -16,4 +17,4 @@ "system", "ui" ] -} +} \ No newline at end of file From 1c352f11794595bd3917ee2fdc55a769a64a2946 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 10:10:19 +0800 Subject: [PATCH 6/7] docs(capabilities): correct HotCRM flow count to 17 (verified against src/flows) Co-Authored-By: Claude Fable 5 --- content/docs/capabilities/automation.mdx | 4 ++-- content/docs/capabilities/index.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/capabilities/automation.mdx b/content/docs/capabilities/automation.mdx index c0f1162610..a5137af8df 100644 --- a/content/docs/capabilities/automation.mdx +++ b/content/docs/capabilities/automation.mdx @@ -22,8 +22,8 @@ Create, update, and delete records · send notifications (in-app, email, chat) 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**: sixteen 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. +> **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). diff --git a/content/docs/capabilities/index.mdx b/content/docs/capabilities/index.mdx index e7b105ff47..e8753070e6 100644 --- a/content/docs/capabilities/index.mdx +++ b/content/docs/capabilities/index.mdx @@ -30,4 +30,4 @@ npm create objectstack@latest my-app && cd my-app npx os dev --ui # → http://localhost:3000/_console/ ``` -Install **HotCRM** from the Marketplace: 15 business objects, 16 automation flows, 6 permission profiles, 4 dashboards, 6 reports, and 2 AI copilots — every page in this section names where to look inside it. +Install **HotCRM** from the Marketplace: 15 business objects, 17 automation flows, 6 permission profiles, 4 dashboards, 6 reports, and 2 AI copilots — every page in this section names where to look inside it. From 9ac28e68fa830ecfa6037ef0a640af14de364585 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 24 Jul 2026 19:50:23 +0800 Subject: [PATCH 7/7] chore(ratchet): migrate role-word baseline entry for relocated cli.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- scripts/role-word-baseline.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/role-word-baseline.json b/scripts/role-word-baseline.json index 61794f0e4f..6b38802901 100644 --- a/scripts/role-word-baseline.json +++ b/scripts/role-word-baseline.json @@ -5,8 +5,8 @@ "content/docs/automation/approvals.mdx": 1, "content/docs/concepts/architecture.mdx": 4, "content/docs/data-modeling/seed-data.mdx": 2, + "content/docs/deployment/cli.mdx": 1, "content/docs/deployment/migration-from-objectql.mdx": 2, - "content/docs/getting-started/cli.mdx": 1, "content/docs/getting-started/common-patterns.mdx": 1, "content/docs/getting-started/index.mdx": 1, "content/docs/getting-started/quick-start.mdx": 1,