objectstack-ai
diff --git a/‎.changeset/retire-objectos-layer-naming.md‎
Lines changed: 5 additions & 0 deletions b/‎.changeset/retire-objectos-layer-naming.md‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎ARCHITECTURE.md‎
Lines changed: 4 additions & 4 deletions b/‎ARCHITECTURE.md‎
Lines changed: 4 additions & 4 deletions
diff --git a/‎LICENSING.md‎
Lines changed: 13 additions & 3 deletions b/‎LICENSING.md‎
Lines changed: 13 additions & 3 deletions
diff --git a/‎README.md‎
Lines changed: 11 additions & 11 deletions b/‎README.md‎
Lines changed: 11 additions & 11 deletions
diff --git a/‎content/docs/ai/actions-as-tools.mdx‎
Lines changed: 22 additions & 28 deletions b/‎content/docs/ai/actions-as-tools.mdx‎
Lines changed: 22 additions & 28 deletions
@@ -0,0 +1,5 @@
+---
+"@objectstack/spec": patch
+---
+
+Retire "ObjectOS" as the control-layer name in the published agent prompts (`prompts/`): the open control layer is now called the **Kernel**; **ObjectOS** exclusively names the commercial runtime environment. Layer vocabulary is now ObjectQL (data) / Kernel (control) / ObjectUI (view). Prompt text only — no schema changes.
@@ -121,7 +121,7 @@ ObjectStack is organized as a **monorepo** with distinct package layers:
 **Location**: `packages/spec/`  
 **Role**: Protocol Definitions (The "Constitution")
 
-- Zod schemas for all protocols (ObjectQL, ObjectOS, ObjectUI)
+- Zod schemas for all protocols (ObjectQL, Kernel/System, ObjectUI)
 - TypeScript type definitions
 - JSON Schema generation
 - Constants and enums
@@ -131,7 +131,7 @@ ObjectStack is organized as a **monorepo** with distinct package layers:
 // packages/spec/src/
 ├── data/           # ObjectQL schemas (Object, Field, Query, etc.)
 ├── ui/             # ObjectUI schemas (App, View, Dashboard, etc.)
-├── system/         # ObjectOS schemas (Manifest, Driver, Plugin, etc.)
+├── system/         # System schemas (Manifest, Driver, Plugin, etc.)
 ├── automation/     # Workflow, Flow, Trigger schemas
 ├── ai/             # Agent, RAG, Model schemas
 ├── api/            # API contract schemas
@@ -306,7 +306,7 @@ ObjectStack follows a **Three-Layer Protocol Stack**:
 └────────────────┬─────────────────────────────────┘
                  │ REST API / GraphQL
 ┌────────────────▼─────────────────────────────────┐
-│         Layer 2: ObjectOS (Control)              │
+│         Layer 2: Kernel (Control)                │
 │  ┌────────────────────────────────────────────┐  │
 │  │  Auth, Permissions, Workflows, Events      │  │
 │  │  "Who can do what, when?"                  │  │
@@ -338,7 +338,7 @@ Foundation:
 | Layer | Knows About | Doesn't Know About |
 |-------|-------------|-------------------|
 | **ObjectQL** | Schema, fields, queries, drivers | Users, permissions, UI |
-| **ObjectOS** | Auth, workflows, events | Data structure, UI layout |
+| **Kernel** | Auth, workflows, events | Data structure, UI layout |
 | **ObjectUI** | Layout, navigation, actions | Business logic, storage |
 
 ---
 
@@ -2,8 +2,18 @@
 
 ObjectStack Framework is licensed under the Apache License, Version 2.0.
 
-This repository contains the open-source framework foundation. Enterprise
-editions, official cloud services, and marketplace commercial terms live
-outside this repository and are governed by their own agreements.
+This repository contains everything you need to **build, run, and self-host
+your own applications** under that license: the protocol (`@objectstack/spec`),
+kernel, SDK, CLI, production runtime (`os start`), and the official Docker
+image definition ([`docker/`](./docker), published as
+`ghcr.io/objectstack-ai/objectstack`). There is no feature gate between
+development and production in this repository.
+
+**ObjectOS** — the official runtime environment for end-user organizations,
+delivered as **ObjectOS Cloud** (managed) and **ObjectOS Enterprise**
+(self-managed) — is a separate commercial product and is not part of this
+repository. Its editions, official cloud services, and marketplace commercial
+terms are governed by their own agreements. See
+[docs.objectos.ai](https://docs.objectos.ai).
 
 The full Apache 2.0 license text is available in [LICENSE](./LICENSE).
@@ -8,11 +8,11 @@
 > **A metadata protocol and TypeScript toolkit for AI-native business apps.** Describe your objects, permissions, workflows, APIs, UI, and AI tools once as typed, version-controlled Zod metadata — and ObjectStack derives the TypeScript types, REST API, client SDK, UI, and MCP tools from that single definition.
 
 ```
-ObjectStack (this repo)  →  how a business app is described — the protocol + toolkit
-ObjectOS                 →  where it runs, and where AI plugs in — the runtime
+ObjectStack (this repo)  →  for builders — the open-source protocol, toolkit, and production runtime
+ObjectOS                 →  for end users — the commercial runtime environment (Cloud & Enterprise)
 ```
 
-This repo is the **framework**: the protocol, kernel, SDK, and CLI you build with. To *run* apps and let AI operate them under your permissions, deploy on **[ObjectOS](https://github.com/objectstack-ai/objectos)**. · Try a live app in ~30s on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no install).
+This repo is the **framework**: the protocol, kernel, SDK, CLI, and production runtime you build — and ship — with. `os start` or the official Docker image [`ghcr.io/objectstack-ai/objectstack`](./docker) runs your compiled app in production, Console and governance included, entirely on open source. For a managed, organization-scale runtime environment (multi-environment control plane, provisioning, marketplace), deploy to **[ObjectOS](https://docs.objectos.ai)** — the commercial Cloud & Enterprise product. · Try a live app in ~30s on [StackBlitz](https://stackblitz.com/github/objectstack-ai/hotcrm) (no install).
 
 <p align="center">
   <img src="docs/screenshots/architecture.png" width="940" alt="ObjectStack architecture: author typed Zod metadata (objects, flows, views, policies); the microkernel compiles it into a versioned JSON artifact and loads plugins, drivers, and services; it generates a REST API, client SDK, Console and Studio UI, and MCP tools used by developers and AI agents, governed by Auth, RBAC, RLS, FLS, and audit, over PostgreSQL, MySQL, SQLite, or MongoDB">
@@ -21,7 +21,7 @@ This repo is the **framework**: the protocol, kernel, SDK, and CLI you build wit
 
 ## What is ObjectStack?
 
-ObjectStack is an **open-source** metadata protocol and toolkit for *describing* business applications — so one typed definition powers your data model, API, UI, and AI tools. Apps run, and AI operates them under your permissions, on the [ObjectOS](https://github.com/objectstack-ai/objectos) runtime.
+ObjectStack is an **open-source** (Apache-2.0) metadata protocol and toolkit for *describing* business applications — so one typed definition powers your data model, API, UI, and AI tools — plus the production runtime that serves them. AI operates your app under your permissions through the built-in MCP server. **[ObjectOS](https://docs.objectos.ai)** is the separate, commercial runtime environment that operates ObjectStack apps for end-user organizations (Cloud & Enterprise editions).
 
 Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScript strings, ObjectStack makes the business system explicit:
 
@@ -30,12 +30,12 @@ Instead of hiding business logic inside ad-hoc SQL queries, UI state, or JavaScr
 - **Business logic** is represented as analyzable metadata: flows, conditions, policies, and artifacts.
 - **Business runtime** is a microkernel that loads plugins, drivers, services, and compiled environment artifacts.
 
-The goal is not to be another low-code UI builder. ObjectStack is the structured *definition* layer for AI-native business software — agent-ready, versioned, and analyzable; permissions and audit are enforced at runtime by ObjectOS.
+The goal is not to be another low-code UI builder. ObjectStack is the structured *definition* layer for AI-native business software — agent-ready, versioned, and analyzable; permissions and audit are enforced by the runtime.
 
-ObjectStack is built around three protocol layers:
+ObjectStack is built around three layers:
 
 - **ObjectQL** (Data Layer) — Objects, fields, queries, relations, validation, and data access.
-- **ObjectOS** (Control Layer) — Runtime, permissions, automation, plugins, environments, and artifact loading.
+- **Kernel** (Control Layer) — Runtime, permissions, automation, plugins, environments, and artifact loading.
 - **ObjectUI** (View Layer) — Apps, views, dashboards, actions, and presentation metadata.
 
 All core definitions start with **Zod schemas** (1,600+ exported schemas across 200 schema files). TypeScript types, JSON Schemas, REST routes, UI metadata, and agent tools are derived from the same source of truth.
@@ -77,7 +77,7 @@ Prefer clicking? Author the same metadata visually in **Studio** — objects, re
 </p>
 <p align="center"><sub><b>Model</b> objects as typed metadata &nbsp;·&nbsp; <b>Automate</b> with visual flows — both produce the same analyzable metadata.</sub></p>
 
-> **Want to see it running?** Deploy on **[ObjectOS](https://github.com/objectstack-ai/objectos)** for the live Console — dashboards, boards, calendars, records, and AI working your data under your permissions.
+> **Want to see it running?** `os dev` serves the live Console locally, and `os start` (or the official Docker image) ships the same Console to production — dashboards, boards, calendars, records, and AI working your data under your permissions.
 
 ## Key Features
 
@@ -105,7 +105,7 @@ The point isn't lines of code. The point is **fit in an agent's context window.*
 | AI maintainability | Agents must crawl sprawling app code | Whole app fits in an agent's context window |
 | Governance | App-level conventions | Auth, RBAC, RLS, FLS, audit, and versioned artifacts |
 
-Described in ObjectStack and deployed on [ObjectOS](https://github.com/objectstack-ai/objectos), this is the substrate for AI-native business apps — CRM, support, operations, and workflow agents acting on real business data without bypassing permissions or audit.
+Described in ObjectStack and served by its runtime, this is the substrate for AI-native business apps — CRM, support, operations, and workflow agents acting on real business data without bypassing permissions or audit.
 
 ## Quick Start
 
@@ -288,10 +288,10 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation
 
 ## Architecture
 
-ObjectStack uses a **microkernel architecture** where the kernel provides only the essential infrastructure (DI, EventBus, lifecycle), and all capabilities are delivered as plugins. The three protocol layers sit above the kernel:
+ObjectStack uses a **microkernel architecture** where the kernel provides only the essential infrastructure (DI, EventBus, lifecycle), and all capabilities are delivered as plugins. The three layers sit above the microkernel:
 
 <p align="center">
-  <img src="docs/screenshots/layers.png" width="900" alt="ObjectStack layered architecture: the ObjectQL data layer, ObjectOS control layer, and ObjectUI view layer sit on a microkernel (plugin lifecycle, service registry / DI, event bus); every capability — drivers, server, auth, security, automation, AI — is a plugin">
+  <img src="docs/screenshots/layers.png" width="900" alt="ObjectStack layered architecture: the ObjectQL data layer, the kernel control layer, and the ObjectUI view layer sit on a microkernel (plugin lifecycle, service registry / DI, event bus); every capability — drivers, server, auth, security, automation, AI — is a plugin">
 </p>
 
 See [ARCHITECTURE.md](./ARCHITECTURE.md) for the complete design documentation including the plugin lifecycle state machine, dependency graph, and design decisions.
 
@@ -16,11 +16,10 @@ client, or a local model) connects over the Model Context Protocol, and the
 server exposes two business-action tools — `list_actions` and `run_action` —
 bound to the caller's principal. The agent operates the app the same way the
 Console toolbar does, under the same row-level security and permissions. No
-cloud service and no `@objectstack/service-ai` are required.
+cloud service and no ObjectOS runtime are required.
 
 <Callout type="info">
-**Cloud / Enterprise** layers an in-product chat *runtime*
-(`@objectstack/service-ai`, cloud [ADR-0025](https://github.com/objectstack-ai/cloud/blob/main/docs/adr/0025-service-ai-to-cloud-open-mcp-only.md))
+**ObjectOS** layers an in-product chat *runtime*
 on top of these same actions: it generates one `action_<name>` tool per action,
 gates them behind an `ai.exposed` opt-in, and adds a server-side approval queue.
 Those pieces are called out below. The open path — the same Action reachable as
@@ -70,8 +69,8 @@ export const triageCaseAction = {
 ```
 
 <Callout type="info">
-**Cloud / Enterprise** — the `ai.exposed` flag is a governance gate for the
-in-product chat *runtime*: the cloud `@objectstack/service-ai` bridge registers
+**ObjectOS** — the `ai.exposed` flag is a governance gate for the
+in-product chat *runtime*: the ObjectOS bridge registers
 an `action_<name>` tool **only** when `ai.exposed === true` (and then
 `ai.description` is required, ≥ 40 chars). The open MCP path does **not** use
 `ai.exposed` — it filters by permission, returning every action the caller is
@@ -86,9 +85,9 @@ System objects (`sys_*`) are held back fail-closed.
 
 | `action.type` | Dispatch path | Available where |
 |:---|:---|:---|
-| `script` | `IDataEngine.executeAction(object, target, ctx)` — the same call Studio makes | open (MCP) + cloud |
-| `flow` | automation flow runner — `execute(target, { triggerData })` | open (MCP) + cloud; needs the `automation` service registered |
-| `api` | HTTP call to `action.target` via a configured `apiClient` | **cloud / Enterprise** runtime only |
+| `script` | `IDataEngine.executeAction(object, target, ctx)` — the same call Studio makes | open (MCP) + ObjectOS |
+| `flow` | automation flow runner — `execute(target, { triggerData })` | open (MCP) + ObjectOS; needs the `automation` service registered |
+| `api` | HTTP call to `action.target` via a configured `apiClient` | **ObjectOS** runtime only |
 
 Console-only types (`url`, `modal`, `form`) are always skipped.
 
@@ -120,14 +119,11 @@ is registered. Point your MCP client at the server; the caller's API key acts as
 the user, so every `run_action` runs under that principal's RLS.
 
 <Callout type="info">
-**Cloud / Enterprise** — the in-product runtime wires actions through
-`@objectstack/service-ai` instead, e.g.
-`new AIServicePlugin({ apiActionBaseUrl, apiActionHeaders })`. `apiActionBaseUrl`
-enables `type:'api'` dispatch (relative `/api/v1/...` targets resolve against it)
-and `apiActionHeaders` are forwarded on every api-action call. The plugin's
-`registerActionsAsTools()` returns `{ registered, skipped, warnings }` with
-reasons like `"not AI-exposed"` or `"requires confirmation … wire HITL approval"`
-so authors can see whether an action is LLM-callable.
+**ObjectOS** — the in-product runtime wires actions through its own bridge
+(including `type:'api'` dispatch), and reports per-action registration results
+with reasons like `"not AI-exposed"` or `"requires confirmation … wire HITL
+approval"` so authors can see whether an action is LLM-callable. See the
+[ObjectOS docs](https://docs.objectos.app/docs/ai) for its configuration.
 </Callout>
 
 ### Example
@@ -155,19 +151,17 @@ operator to approve the call before it runs. The human stays in the loop at the
 point of invocation, and the action still executes under the caller's RLS.
 
 <Callout type="info">
-**Cloud / Enterprise** — the in-product chat runtime adds a *server-side*
-approval queue for its own `action_<name>` tools. Enable it with
-`new AIServicePlugin({ enableActionApproval: true })`: a gated tool call persists
-an `ai_pending_actions` row (`status: 'pending'`) and returns
-`{ status: 'pending_approval', pendingActionId }` to the model instead of
-executing. An operator resolves it from the **AI Pending Actions** Studio inbox —
-`POST /api/v1/ai/pending-actions/:id/approve` (`ai:approve` permission) re-runs
-the same dispatcher, or `.../reject` with a reason. The queue is also available
-programmatically via
-`IAIService.{proposePendingAction, approvePendingAction, rejectPendingAction, listPendingActions}`.
+**ObjectOS** — the in-product chat runtime adds a *server-side*
+approval queue for its own `action_<name>` tools: a gated tool call is
+persisted as pending and returned to the model as
+`{ status: 'pending_approval', … }` instead of executing, and an operator
+resolves it from the **AI Pending Actions** Studio inbox (approve re-runs the
+same dispatcher; reject records a reason).
 A dedicated queue (rather than the multi-step `IApprovalService`) fits AI
 tool-call HITL: the subject is the proposed *call*, there is no predefined
-process, and operators expect single-click yes/no.
+process, and operators expect single-click yes/no. See the
+[ObjectOS docs](https://docs.objectos.app/docs/ai) for configuration and the
+queue API.
 </Callout>
 
 ## Permission-aware execution (RLS for agents)
@@ -193,7 +187,7 @@ On the open MCP path this is automatic:
    "AI Assistant" principal.
 
 <Callout type="info">
-**Cloud / Enterprise** — the in-product chat routes
+**ObjectOS** — the in-product chat routes
 (`/api/v1/ai/assistant/chat`, `/api/v1/ai/agents/:agentName/chat`) resolve the
 authenticated principal from `req.user` — both cookie session
 (`better-auth.session_token`) and Bearer token are handled — and forward it to
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@objectstack/spec": patch
 +---
++
 +Retire "ObjectOS" as the control-layer name in the published agent prompts (`prompts/`): the open control layer is now called the **Kernel**; **ObjectOS** exclusively names the commercial runtime environment. Layer vocabulary is now ObjectQL (data) / Kernel (control) / ObjectUI (view). Prompt text only — no schema changes.