objectstack-fleet · Oct 28, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026 · Oct 27, 2026
@@ -4,7 +4,7 @@ Primary AI instruction file for this repo — and the human contributors' source
 Read natively by Claude Code, GitHub Copilot (coding agent + CLI), and other agents — no
 separate `.github/copilot-instructions.md` mirror needed. When any other instruction file
 in this repo (including `.claude/skills/**`) conflicts with this one, **AGENTS.md wins**.
-`docs/NORTH-STAR.md` (先做什么: goals, priority) outranks it; `content/docs/concepts/north-star.mdx` = architecture.
+`docs/NORTH-STAR.md`, the North Star, outranks it; `content/docs/concepts/architecture-overview.mdx` = architecture.
 
 > **v5.0 breaking rename: `project` → `environment`** everywhere (CLI `-e`, `/api/v1/environments/:id`, header `X-Environment-Id`, `OS_ENVIRONMENT_ID`, DB column `environment_id` [control-plane tables; on the metadata tables since deprecated in favour of `organization_id`, ADR-0006 v4]). No aliases. See ADR-0006. "Project" now only means the npm/monorepo sense.
 
@@ -194,8 +194,8 @@ localStorage / auth gotchas.
 7. **One Zod source per metadata type.** Each type (`view`, `flow`, `agent`, …) has exactly one schema in
    `packages/spec/src/{domain}/`. Environment-overlay opt-in lives only in `allowEnvironmentOverlay` on
    `DEFAULT_METADATA_TYPE_REGISTRY` — no parallel whitelists. See ADR-0005, amended by ADR-0131 C5.
-8. **North Star alignment.** Read `content/docs/concepts/north-star.mdx` before structural changes. If a change doesn't
-   advance §7 Built, shrink Drift, or unlock Missing — it probably shouldn't ship.
+8. **North Star alignment.** Read `docs/NORTH-STAR.md` before structural changes. If a change doesn't advance a row of
+   its 路上的功能点 ladder, graded by its 优先级 — it probably shouldn't ship.
 9. **`OS_` env-var prefix + structure.** All ObjectStack-owned env vars MUST start with `OS_`, then follow
    **`OS_{DOMAIN}_{FEATURE}[_QUALIFIER]`** where `DOMAIN` is the subsystem (`AUTH`, `SEARCH`, `CORS`, `CLOUD`,
    `DATABASE`, `CLUSTER`, `MCP`, `SSO`, …) so related vars group together (cf. `OS_AUTH_*`, `OS_CORS_*`). Pick the

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -111,7 +111,8 @@ Other examples: `pnpm dev:crm`, `pnpm dev:todo`. Docs site: `pnpm docs:dev`.
 1. **Start from an issue.** Pick one from the
    [issue tracker](https://github.com/objectstack-ai/objectstack/issues), or open one
    that describes the bug or the proposal before you write code.
-   [docs/NORTH-STAR.md](./docs/NORTH-STAR.md) shows where the project is going.
+   [docs/NORTH-STAR.md](./docs/NORTH-STAR.md), the project's one North Star, shows where the project is going
+   and what comes first; an English summary closes it.
 2. **Branch off an up-to-date `main`, one branch and one pull request per issue**,
    with the issue number in the branch name:
 

diff --git a/README.md b/README.md
@@ -267,7 +267,7 @@ Every package in `packages/`, grouped by layer, plus the example apps, is in
 - ⭐ **Star this repo** if ObjectStack is useful — it helps others find it.
 - 🐛 Questions, bugs, or feature requests → [open an issue](https://github.com/objectstack-ai/objectstack/issues).
 - 💬 Ideas and open-ended questions → [GitHub Discussions](https://github.com/objectstack-ai/objectstack/discussions).
-- 🤝 Want to contribute? Start with [CONTRIBUTING.md](./CONTRIBUTING.md); [North Star](https://objectstack.ai/docs/concepts/north-star) says where the project is headed.
+- 🤝 Want to contribute? Start with [CONTRIBUTING.md](./CONTRIBUTING.md); [North Star](./docs/NORTH-STAR.md) says where the project is headed.
 - 📖 Full documentation at [objectstack.ai/docs](https://objectstack.ai/docs); upgrading between majors is covered in the [upgrade guide](https://objectstack.ai/docs/upgrading).
 - ☁️ Want it hosted, with Build & Ask AI built in? [ObjectOS](https://www.objectos.ai) Cloud runs these definitions for you — [objectstack-ai/objectos](https://github.com/objectstack-ai/objectos) is its public home.
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,7 +1,7 @@
 # ObjectStack Roadmap
 
 > **Last updated:** 2026-06-06
-> **Source of truth:** [content/docs/concepts/north-star.mdx](content/docs/concepts/north-star.mdx) for product direction, ADRs for architectural decisions, and code for shipped behavior.
+> **Source of truth:** [docs/NORTH-STAR.md](docs/NORTH-STAR.md), the one North Star, for product direction and priority, ADRs for architectural decisions, and code for shipped behavior.
 
 This roadmap tracks the current framework repository. Historical Cloud/ObjectOS
 milestone plans that referred to `apps/cloud`, `apps/objectos`,

diff --git a/apps/docs/redirects.mjs b/apps/docs/redirects.mjs
@@ -20,6 +20,9 @@ export const docsRedirects = [
   ['/docs/getting-started/core-concepts', '/docs/concepts'],
   ['/docs/getting-started/architecture', '/docs/concepts/architecture'],
   ['/docs/concepts/terminology', '/docs/getting-started/glossary'],
+  // The architecture page was published as `north-star`; "North Star" now names
+  // only docs/NORTH-STAR.md (goals and priority), so the page took an honest slug.
+  ['/docs/concepts/north-star', '/docs/concepts/architecture-overview'],
   // data-modeling
   ['/docs/guides/data-modeling', '/docs/data-modeling'],
   ['/docs/guides/metadata/object', '/docs/data-modeling/objects'],

diff --git a/content/docs/concepts/north-star.mdx → ...t/docs/concepts/architecture-overview.mdx b/content/docs/concepts/north-star.mdx → ...t/docs/concepts/architecture-overview.mdx
@@ -1,7 +1,7 @@
 ---
-title: North star — why this framework exists
-navTitle: North Star
-description: "Where ObjectStack is headed: a metadata-native backend that humans and AI agents can both operate safely — its principles, runtime shape and non-goals."
+title: Architecture overview — principles and runtime shape
+navTitle: Architecture Overview
+description: "What ObjectStack is built as: a metadata-native backend that humans and AI agents can both operate safely — its principles, runtime shape and non-goals."
 ---
 
 ObjectStack is the metadata-native backend for business software that humans and
@@ -16,6 +16,10 @@ The goal is a small, inspectable, governed application surface:
 Zod metadata -> compiled environment artifact -> ObjectStack runtime -> REST / UI / MCP / AI tools
 ```
 
+This page is the architecture. Where the project is headed and what comes first
+— its goals and priority ladder — is the
+[North Star](https://github.com/objectstack-ai/objectstack/blob/main/docs/NORTH-STAR.md).
+
 ---
 
 ## Principles
@@ -101,38 +105,6 @@ environments and are not themselves scoped data-plane requests.
 
 ---
 
-## Built
-
-- TS-to-JSON compile pipeline (`os compile`)
-- standalone runtime boot from source config or compiled artifact
-- environment-scoped REST routes
-- ObjectQL data engine and memory/SQL/MongoDB drivers
-- Flow engine with durable pause support
-- approval-as-flow-node runtime
-- notification pipeline through single ingress, outbox, preferences, templates,
-  quiet-hours, and digest collapse
-- explicit Action-to-AI tool opt-in
-- formula fields, server-side summary rollups, and autonumber fields
-- config-driven master-detail inline editing via relationship `inlineEdit`
-- bundled console serving from `packages/console`
-
----
-
-## Drift To Keep Shrinking
-
-- Some docs and source comments still use historical `project` wording where
-  current runtime identity is `environment`.
-- The SDK client still exposes `setProjectId` / `getProjectId`, and the REST API
-  config still spells its keys `enableProjectScoping` / `projectResolution`.
-  `getProjectId` is the harder one: it is a cross-package protocol contract that
-  `packages/runtime` and `packages/metadata-protocol` both speak, so it is a
-  coordinated rename rather than a local one.
-- The notification framework pipeline is ahead of the objectui bell cut-over;
-  read-state should move through `sys_notification_receipt`.
-- Some generated references need regeneration after Zod description updates.
-
----
-
 ## Non-Goals
 
 - Do not reintroduce `namespace` or `tableName` as object identity fields.

diff --git a/content/docs/concepts/meta.json b/content/docs/concepts/meta.json
@@ -8,6 +8,6 @@
     "when-to-use",
     "metadata-lifecycle",
     "design-principles",
-    "north-star"
+    "architecture-overview"
   ]
 }
diff --git a/content/docs/concepts/metadata-lifecycle.mdx b/content/docs/concepts/metadata-lifecycle.mdx
@@ -171,7 +171,7 @@ The hash is `sha256:` + 64-hex of a canonical JSON serialization of the body, wi
 - [ADR-0008 §0 amendment (2026-04): project/branch removal](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0008-metadata-repository-and-change-log.md#0-2026-04-13-amendment--drop-project-and-branch-from-metaref) — why `MetaRef.project` and `MetaRef.branch` are dead.
 - [ADR-0008: Metadata Repository & Change Log](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0008-metadata-repository-and-change-log.md) — the four-primitive architecture.
 - [IMetadataService Contract](/docs/kernel/contracts/metadata-service) — the runtime API plugins call.
-- [North Star](/docs/concepts/north-star) — the product shape these primitives serve.
+- [Architecture Overview](/docs/concepts/architecture-overview) — the product shape these primitives serve.
 
 ---
 

diff --git a/content/docs/data-modeling/formulas.mdx b/content/docs/data-modeling/formulas.mdx
@@ -26,7 +26,7 @@ plus the ObjectStack standard library.
 > emit it natively), AST-first persistence, and sandboxed execution with
 > bounded cost. ObjectStack does **not** ship a Salesforce-flavor DSL — the
 > previous custom 22-function engine was deleted in M9. See the
-> [north-star](/docs/concepts/north-star) principles on typed metadata over
+> [architecture overview](/docs/concepts/architecture-overview) principles on typed metadata over
 > custom DSLs.
 
 ---
@@ -692,4 +692,4 @@ agent-callable `validate_expression` tool), so an expression is checked before i
 - [Seed Data](/docs/data-modeling/seed-data) — using `cel\`...\`` for dynamic install-time values
 - [Hook Bodies](/docs/automation/hook-bodies) — when to use a JS hook vs a CEL `condition`
 - [`packages/formula/`](https://github.com/objectstack-ai/objectstack/tree/main/packages/formula) — engine + stdlib source
-- [North Star](/docs/concepts/north-star) — architecture principles (typed metadata over custom DSLs)
+- [Architecture Overview](/docs/concepts/architecture-overview) — architecture principles (typed metadata over custom DSLs)
@@ -123,3 +123,56 @@
 **现在不做**:云服务的旅程(注册、控制面、托管)另有自己的清单;企业版内置 Agent 属 cloud 仓,不在本仓的路与清单里;计费未建。
 
 **账本**:能力与验证的账本是 `docs/qa/platform-checklist/`,本页不复制它。本页不带任何数字;数字从命令来。
+
+---
+
+## English summary
+
+A reading aid for readers without Chinese. The Chinese text above is the original and is what governs; this summary
+restates its opening, its one measure and how to read its ladder, and adds nothing to them.
+
+**The four opening questions**
+
+- **What we are** (我们是什么) — the ontology is the software: an executable business ontology (objects and fields,
+  relationships, actions, permissions, flows, agent and tool definitions) that AI writes, the runtime runs, people and
+  agents use, and you own; startup stage. Views, dashboards, apps and translations are projections of the ontology —
+  the surfaces through which people use, see and verify it today.
+- **Who it is for** (给谁) — third-party developers, AI agents first with a human accepting: the AI writes applications
+  in our metadata protocol, the human looks at the result and decides. The applications' end users are business staff
+  in companies, who use them through agents and the UI.
+- **What gets built** (做出来的是什么) — **AI-native enterprise management applications**: business objects and records,
+  views to see the data, forms that work, permissions that really hold, approvals and automation, business reports,
+  sign-in and identity, an API others can call, files, the customer's language, and changing the application while it
+  runs without writing code. AI-native means the application carries an agent that can operate it for the user: this
+  repository (the community edition) exposes objects and actions over MCP and users connect their own agent; the
+  enterprise edition builds the agent into the UI, and that half lives in the cloud repository. Missing any one of
+  these, it is not this application. The line is a definition, not a checklist — what each item must do and how it is
+  verified is in `docs/qa/platform-checklist/`. Reference implementation: hotcrm. Two kinds of user: today business
+  staff through the UI and acceptors through the console, tomorrow agents through MCP; every step of the road must hold
+  for both.
+- **What counts as done** (什么算做好) — an application built on the protocol is done only once it passes verification:
+  the checklist items its metadata maps to pass in one run, and `objectstack verify` is green on it. A delivery that
+  has not passed verification is not done.
+
+**The one measure: the road** (唯一的度量,那条路)
+
+A new AI developer, a human accepting alongside, starts from `npm create objectstack`: ① write metadata → ② run it
+locally and see it → ③ verification loudly rejects what is wrong and lets through what is right → ④ publish and
+install into an environment → ⑤ connect an agent (MCP in the community edition) and have it complete one real business
+operation in the application → ⑥ iterate once on a one-sentence customer request. Walk it for real every week and
+record the result as a run record. The first step that breaks is the current P0; a step that runs but gives a wrong
+result is P2. Each promise is kept by a step: ① AI can write it · ②③ it executes · ④ you own it · ⑤ agents can operate
+it · ⑥ it closes the loop.
+
+**How to read the ladder** (路上的功能点)
+
+- The ladder lists the features the platform has to deliver, one per line, under the road's steps ① to ⑥; top to
+  bottom is the order. The table is the roadmap: editing it changes priority.
+- Each row reads `axis · feature (in business language) · checklist area · item ids`, and one feature is a whole strip
+  from protocol through runtime to the frontend. Every item in `docs/qa/platform-checklist/` belongs to exactly one
+  row; a feature whose items are not written yet is marked 「清单项待写」 (checklist item to be written). An id without a
+  prefix belongs to the checklist area before it; an id from another area is written in full.
+- Grading reads the ladder (优先级): safety and data integrity always come first and do not wait for the road; a broken
+  road step or a broken checklist capability is P0/P1, one that runs but is wrong is P2, and work on neither the road
+  nor the checklist is p3 or not done. Change the table to change priority — ⛔ never re-grade card by card. The rest
+  of 优先级 and the paragraphs after it (阶段姿态, 仪器为车队服务, 现在不做, 账本) are read in the Chinese text above.
diff --git a/scripts/docs-audit/handwritten-docs.json b/scripts/docs-audit/handwritten-docs.json
@@ -63,13 +63,13 @@
     "content/docs/capabilities/permissions.mdx",
     "content/docs/capabilities/request-template.mdx",
     "content/docs/capabilities/views.mdx",
+    "content/docs/concepts/architecture-overview.mdx",
     "content/docs/concepts/architecture.mdx",
     "content/docs/concepts/compare.mdx",
     "content/docs/concepts/design-principles.mdx",
     "content/docs/concepts/index.mdx",
     "content/docs/concepts/metadata-driven.mdx",
     "content/docs/concepts/metadata-lifecycle.mdx",
-    "content/docs/concepts/north-star.mdx",
     "content/docs/concepts/ontology.mdx",
     "content/docs/concepts/when-to-use.mdx",
     "content/docs/data-modeling/analytics.mdx",