From a14d03112248872ca8bf1bdf9a9962225e07b5b3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 23:01:38 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20one=20North=20Star=20=E2=80=94=20do?= =?UTF-8?q?cs/NORTH-STAR.md;=20the=20architecture=20page=20becomes=20conce?= =?UTF-8?q?pts/architecture-overview?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ruling A' on the North Star card: content/docs/concepts/north-star.mdx is renamed architecture-overview (redirect entry in apps/docs/redirects.mjs), keeps Principles, Runtime Shape, Environment Artifact, Request Resolution and Non-Goals, and drops the Built and Drift To Keep Shrinking status sections. AGENTS.md line 7 and Prime Directive 8, ROADMAP, CONTRIBUTING and README name docs/NORTH-STAR.md as the one North Star; the two hand-written pages that link the old slug move to the new one; docs/NORTH-STAR.md gains an English summary under the unedited Chinese text. handwritten-docs.json regenerated. Claude-Session: https://claude.ai/code/session_01QSeKYmTYfaPbLQD4BJfomW Co-authored-by: Claude --- AGENTS.md | 6 +-- CONTRIBUTING.md | 3 +- README.md | 2 +- ROADMAP.md | 2 +- apps/docs/redirects.mjs | 3 ++ ...rth-star.mdx => architecture-overview.mdx} | 42 +++------------ content/docs/concepts/meta.json | 2 +- content/docs/concepts/metadata-lifecycle.mdx | 2 +- content/docs/data-modeling/formulas.mdx | 4 +- docs/NORTH-STAR.md | 53 +++++++++++++++++++ scripts/docs-audit/handwritten-docs.json | 2 +- 11 files changed, 75 insertions(+), 46 deletions(-) rename content/docs/concepts/{north-star.mdx => architecture-overview.mdx} (72%) diff --git a/AGENTS.md b/AGENTS.md index 539d10d88f2..c188781aea7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 one North Star (先做什么: goals, priority), 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 index a383e227013..8772676d402 100644 --- 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 index 77c89c0fb4f..787eda17755 100644 --- 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 index b394222e6f4..1fd70f5c01b 100644 --- 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 index b65d361bf81..2c59e548cc8 100644 --- 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 b/content/docs/concepts/architecture-overview.mdx similarity index 72% rename from content/docs/concepts/north-star.mdx rename to content/docs/concepts/architecture-overview.mdx index 4a851856433..41f2f7db480 100644 --- a/content/docs/concepts/north-star.mdx +++ b/content/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 index f5a0e76f60f..47b57ddd731 100644 --- 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 index f1f947ca949..f0b55cb6071 100644 --- 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 index 4eea04956ed..2c1469779bf 100644 --- 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) diff --git a/docs/NORTH-STAR.md b/docs/NORTH-STAR.md index 5a07cbfd0b6..931965b4eac 100644 --- a/docs/NORTH-STAR.md +++ b/docs/NORTH-STAR.md @@ -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 index a7173d8f65e..20ddede3713 100644 --- 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", From 2ee65f96273d3c8d6e18b7457a2e084828cbfd99 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 27 Oct 2026 23:15:25 +0000 Subject: [PATCH 2/2] docs(agents): keep AGENTS.md line 7 inside the 120-byte line budget Claude-Session: https://claude.ai/code/session_01QSeKYmTYfaPbLQD4BJfomW Co-authored-by: Claude --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index c188781aea7..3334f6e0b14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`, the one North Star (先做什么: goals, priority), outranks it; `content/docs/concepts/architecture-overview.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.