objectstack-ai · os-zhuang · Jul 5, 2026 · Jul 5, 2026
diff --git a/content/docs/ai/actions-as-tools.mdx b/content/docs/ai/actions-as-tools.mdx
@@ -41,7 +41,7 @@ Three action types are supported:
 | `action.type` | Dispatch path | Wiring needed |
 |:---|:---|:---|
 | `script` | `IDataEngine.executeAction(object, target, ctx)` — the same call Studio makes | none beyond the metadata service |
-| `api` | HTTP call to `action.target` via `ApiActionClient` (default: `fetch`) | `apiBaseUrl` (or a custom `apiClient`) |
+| `api` | HTTP call to `action.target` via the configured `apiClient` (default: `fetch`) | `apiActionBaseUrl` (or a custom `apiClient`) |
 | `flow` | `IAutomationService.execute(target, { triggerData })` | `automation` service registered |
 
 Console-only types (`url`, `modal`, `form`) are always skipped. Dangerous
@@ -158,7 +158,7 @@ automatically scope what an agent can see and do. There is no separate
 **How it works:**
 
 1. The REST routes for `/api/v1/ai/assistant/chat` and
-   `/api/v1/ai/agents/:id/chat` pull the authenticated principal out of
+   `/api/v1/ai/agents/:agentName/chat` pull the authenticated principal out of
    `req.user` and forward it to `aiService.chatWithTools(...)` as
    `toolExecutionContext: { actor, conversationId, environmentId }`.
    Both **cookie session** (`better-auth.session_token`) and **Bearer
@@ -197,8 +197,10 @@ Omit `toolExecutionContext` to keep the previous system-level behaviour
 
 ## LLM-generated conversation titles
 
-Auto-titling is **opt-in** (disabled by default; enable it via the `ai`
-settings namespace from Console → Settings → AI). Once enabled, after a
+Auto-titling is **on by default** for any configured LLM provider (the
+memory/echo provider never triggers it, since no real LLM call is made);
+toggle `title_generation_enabled` off via the `ai` settings namespace from
+Console → Settings → AI if you'd rather leave conversations unnamed. Once a
 conversation has at least one user + assistant exchange (≥ 2 messages) and
 still has no title, the AI service fires a short, out-of-band LLM call
 (default cap **16 characters**, single-line, no quotes) to summarise what the

diff --git a/content/docs/ai/chatbot-integration.mdx b/content/docs/ai/chatbot-integration.mdx
@@ -30,7 +30,7 @@ contract.
 
 On a cloud / EE dev host (where `@objectstack/service-ai` is available —
 see the callout above), the `default` and `full` plugin tier presets both
-include the `ai` capability, so `objectstack dev` boots the AI services
+include the `ai` capability, so `os dev` boots the AI services
 unless you opt out with `--preset minimal`. Provide a Vercel AI Gateway
 model and key via env vars:
 
@@ -106,7 +106,7 @@ const chat = useObjectChat({
 ## 4. HITL (Human-in-the-Loop) flow
 
 When the agent picks a dangerous action (e.g. `delete_task`) the tool
-handler enqueues an `ai_pending_action` row and the chat returns a
+handler enqueues an `ai_pending_actions` row and the chat returns a
 `pending_approval` tool result. Your Console UI then:
 
 1. Polls `GET /api/v1/ai/pending-actions?status=pending`.

diff --git a/content/docs/ai/skills-reference.mdx b/content/docs/ai/skills-reference.mdx
@@ -46,7 +46,7 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI
 | # | Skill | Domain | Path | What it covers |
 | :--- | :--- | :--- | :--- | :--- |
 | 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). |
-| 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. |
+| 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed definitions (`defineSeed()`) that load fixtures and reference data alongside them. |
 | 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. |
 | 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). |
 | 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. |
@@ -75,7 +75,7 @@ Do not use for data schema design (see objectstack-data) or query patterns (see
 
 **Domain** `data` · **Path** `skills/objectstack-data/`
 
-Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them.
+Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed definitions (`defineSeed()`) that load fixtures and reference data alongside them.
 
 Use when the user is creating or modifying `*.object.ts` / `*.seed.ts` files, picking field types, modelling relationships, writing `beforeInsert`/`afterUpdate` hooks, configuring per-object access control, or authoring bootstrap / demo data. Use for `visibleWhen` / `readonlyWhen` / `requiredWhen` rules that belong on fields.
 
@@ -147,7 +147,7 @@ Do not use for general LLM prompting questions unrelated to ObjectStack metadata
 
 Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts.
 
-Use when the user is adding `*.endpoint.ts`, configuring auth providers, defining custom routes, or extending the REST/GraphQL generator.
+Use when the user is adding `ApiEndpoint` entries to the `apis:` array in `defineStack()`, configuring auth providers, defining custom routes, or extending the REST/GraphQL generator.
 
 Do not use for: consuming an ObjectStack API from a client (that is just standard HTTP — no skill needed); the auto-generated CRUD endpoints (those follow from objectstack-data); request-side query syntax (see objectstack-query). CEL expressions in route guards or auth predicates: load objectstack-formula alongside.
 

diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx
@@ -67,7 +67,7 @@ Each skill ships `SKILL.md` plus a generated `references/` index, and richer ski
 | **Overview** | `SKILL.md` | Yes | High-level guide with decision trees and quick-start examples |
 | **References** | `references/_index.md` | Generated | Pointers into the published `@objectstack/spec` Zod sources (present in every skill except Formula) |
 | **Rules** | `rules/*.md` | Optional | Detailed implementation rules with ✅ correct / ❌ incorrect code examples (today: Data, Platform, Query) |
-| **Evaluations** | `evals/*.md` | Optional | Test cases to validate AI assistant understanding |
+| **Evaluations** | `evals/*.md` | Optional | Test cases to validate AI assistant understanding (mostly planned — `objectstack-automation` ships the first worked example; other skills' `evals/` directories are still placeholders) |
 
 ### SKILL.md — The Entry Point
 
@@ -144,11 +144,11 @@ Each skill has **clear boundaries** — it knows what it's responsible for and e
             ▼             ▼             ▼
         ┌───────┐     ┌──────┐    ┌────────────┐
         │ Query │     │  UI  │    │ Automation │
-        └───────┘     └──────┘    └─────┬──────┘
-                          │             │
-                     ┌────▼────┐   ┌────▼────┐
-                     │   API   │   │   AI    │
-                     └─────────┘   └─────────┘
+        └───┬───┘     └──────┘    └─────┬──────┘
+            │                           │
+       ┌────▼────┐                 ┌────▼────┐
+       │   API   │                 │   AI    │
+       └─────────┘                 └─────────┘
 
   Formula and i18n are cross-cutting — load them alongside any host skill.
 ```
@@ -215,7 +215,7 @@ Each skill maps directly to an ObjectStack protocol domain. The schema skill tea
 
 ### 4. Testable
 
-The `evals/` directory in each skill allows teams to validate that their AI assistant correctly understands the protocol. This is analogous to test suites for runtime code — but for AI comprehension.
+The `evals/` directory in each skill is reserved for test cases that validate an AI assistant correctly understands the protocol — analogous to test suites for runtime code, but for AI comprehension. Most skills' `evals/` directories are still placeholders; `objectstack-automation` ships the first worked example (`evals/approvals/test-revise-loop.md`).
 
 ---
 

diff --git a/content/docs/api/client-sdk.mdx b/content/docs/api/client-sdk.mdx
@@ -35,11 +35,11 @@ const client = new ObjectStackClient({
 });
 
 async function main() {
-  // 1. Connect — fetches discovery manifest
-  await client.connect();
+  // 1. Connect — resolves with the discovery manifest
+  const discovery = await client.connect();
 
   // 2. Check available services
-  console.log('Services:', client.discovery?.services);
+  console.log('Services:', discovery.services);
   // → { metadata: { enabled: true, status: 'degraded' }, data: { enabled: true, status: 'available' }, auth: { enabled: false, ... } }
 
   // 3. Query data
@@ -80,17 +80,16 @@ When you call `client.connect()`, the client:
 3. Configures all API route paths dynamically
 
 ```typescript
-await client.connect();
+// connect() resolves with the discovery manifest — capture the return value
+const discovery = await client.connect();
 
-// Discovery result is available
-const discovery = client.discovery;
 console.log(discovery.version);      // "1.0.0"
 console.log(discovery.environment);  // "development"
 
 // Check if a service is available before using it
 if (discovery.services?.auth?.enabled) {
   // Auth plugin is installed — login is available
-  await client.auth.login({ username: 'admin', password: 'secret' });
+  await client.auth.login({ email: 'admin@example.com', password: 'secret' });
 } else {
   console.log(discovery.services?.auth?.message);
   // → "Install an auth plugin to enable"
@@ -105,7 +104,7 @@ if (discovery.services?.auth?.enabled) {
 
 ## Protocol Coverage
 
-The `@objectstack/client` SDK aims to implement the ObjectStack API protocol specification. The core namespaces are listed below; the client also exposes additional namespaces (`approvals`, `feed`, `organizations`, `projects`/environments) — see [`index.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/client/src/index.ts) for the full surface:
+The `@objectstack/client` SDK aims to implement the ObjectStack API protocol specification. The core namespaces are listed below; the client also exposes additional namespaces (`approvals`, `feed`, `organizations`, `oauth`, `projects`/environments) — see [`index.ts`](https://github.com/objectstack-ai/framework/blob/main/packages/client/src/index.ts) for the full surface:
 
 | Namespace | Status | Methods | Purpose |
 |:----------|:------:|:--------|:--------|
@@ -116,7 +115,7 @@ The `@objectstack/client` SDK aims to implement the ObjectStack API protocol spe
 | **permissions** | ✅ | 3 | Access control checks |
 | **packages** | ✅ | 6 | Plugin/package lifecycle management |
 | **views** | ✅ | 5 | UI view definitions |
-| **workflow** | ✅ | 5 | Workflow state transitions |
+| **workflow** | ✅ | 3 | Workflow state transitions |
 | **analytics** | ✅ | 3 | Analytics queries |
 | **automation** | ✅ | 1 | Automation triggers |
 | **storage** | ✅ | 2 | File upload & download |
@@ -217,7 +216,7 @@ const result = await client.analytics.query({
   cube: 'account',
   measures: ['revenue.sum', 'count'],
   dimensions: ['industry'],
-  filters: [{ member: 'status', operator: 'equals', values: ['active'] }],
+  where: { status: 'active' },
   limit: 100,
 });
 
@@ -235,10 +234,10 @@ const explained = await client.analytics.explain({
 
 ```typescript
 const packages = await client.packages.list();
-await client.packages.install({ name: 'plugin-auth', version: '1.0.0' });
-await client.packages.enable('plugin-auth');
-await client.packages.disable('plugin-auth');
-await client.packages.uninstall('plugin-auth');
+await client.packages.install({ id: 'com.objectstack.plugin-auth', version: '1.0.0' });
+await client.packages.enable('com.objectstack.plugin-auth');
+await client.packages.disable('com.objectstack.plugin-auth');
+await client.packages.uninstall('com.objectstack.plugin-auth');
 ```
 
 ### Additional Namespaces
@@ -248,7 +247,7 @@ The client also provides full implementations for:
 ```typescript
 // Auth — User authentication and session management
 await client.auth.login({ email: 'user@example.com', password: 'pass' });
-await client.auth.register({ email: 'new@example.com', password: 'pass' });
+await client.auth.register({ email: 'new@example.com', password: 'pass', name: 'New User' });
 await client.auth.me();
 await client.auth.logout();
 await client.auth.refreshToken('refresh-token-string');
@@ -272,10 +271,10 @@ await client.approvals.reject(requestId, { comment: 'Incomplete' });
 await client.approvals.listActions(requestId); // audit trail
 
 // Realtime — WebSocket subscriptions
-await client.realtime.connect({ protocol: 'websocket' });
-await client.realtime.subscribe({ channel: 'account', event: 'update' });
+await client.realtime.connect({ transport: 'websocket' });
+await client.realtime.subscribe({ channel: 'account', events: ['record.updated'] });
 await client.realtime.unsubscribe('subscription-id');
-await client.realtime.setPresence('account', { status: 'online' });
+await client.realtime.setPresence('account', { userId: 'user-123', status: 'online', lastSeen: new Date().toISOString() });
 await client.realtime.getPresence('account');
 await client.realtime.disconnect();
 
@@ -320,7 +319,7 @@ await client.views.delete('account', viewId);
 ```
 
 <Callout type="info">
-**Service availability**: Optional services (workflow, ai, etc.) are only available when the corresponding plugin is installed on the server. Always check `client.discovery?.services` to verify service availability before calling these methods.
+**Service availability**: Optional services (workflow, ai, etc.) are only available when the corresponding plugin is installed on the server. Always check the `services` map on the discovery result returned by `client.connect()` (cache it yourself — the client has no `discovery` getter) to verify service availability before calling these methods.
 </Callout>
 
 ---
@@ -381,8 +380,8 @@ The `find` method accepts an options object with **canonical** (recommended) fie
 | `offset` | `number` | Records to skip (OFFSET) | `0` |
 | `expand` | `Record<string, any>` or `string[]` | Relation loading (JOIN) | `{ owner: {} }` |
 
-<Callout type="warn">
-**Removed in 11:** the legacy query-field aliases were removed — use the canonical names: `fields` (was `select`), `where` (was `filter`/`filters`), `orderBy` (was `sort`), `limit` (was `top`), `offset` (was `skip`).
+<Callout type="info">
+**Canonical names recommended:** `find()` accepts the canonical names above; the legacy aliases (`select`, `filter`/`filters`, `sort`, `top`, `skip`) still work for backward compatibility, but new code should use the canonical names. (`@objectstack/client-react`'s `useQuery`/`useInfiniteQuery` hooks are stricter — the legacy aliases were removed there in v11; see `docs/upgrading-to-11.md`.)
 </Callout>
 
 ### Batch Options
@@ -418,9 +417,9 @@ try {
 |:-----|:-----|:---------|:----------|:------------|
 | `validation_error` | 400 | validation | No | Input validation failed |
 | `invalid_query` | 400 | validation | No | Malformed query expression |
-| `unauthenticated` | 401 | auth | No | Authentication required |
-| `permission_denied` | 403 | auth | No | Insufficient permissions |
-| `resource_not_found` | 404 | request | No | Resource does not exist |
+| `unauthenticated` | 401 | authentication | No | Authentication required |
+| `permission_denied` | 403 | authorization | No | Insufficient permissions |
+| `resource_not_found` | 404 | not_found | No | Resource does not exist |
 | `rate_limit_exceeded` | 429 | rate_limit | Yes | Too many requests |
 | `internal_error` | 500 | server | Yes | Unexpected server error |
 | `service_unavailable` | 503 | server | Yes | Service temporarily unavailable |
@@ -543,7 +542,7 @@ Integration tests verify end-to-end communication with a live ObjectStack server
 
 For detailed information about the client's protocol implementation:
 
-- **[Protocol Compliance Matrix](https://github.com/objectstack-ai/framework/blob/main/packages/client/CLIENT_SPEC_COMPLIANCE.md)** — Method-by-method verification of all API methods across 15 namespaces
+- **[Protocol Compliance Matrix](https://github.com/objectstack-ai/framework/blob/main/packages/client/CLIENT_SPEC_COMPLIANCE.md)** — Method-by-method verification of all API methods across 13 namespaces
 - **[Integration Test Specifications](https://github.com/objectstack-ai/framework/blob/main/packages/client/CLIENT_SERVER_INTEGRATION_TESTS.md)** — Comprehensive test cases for client-server communication
 - **[Package README](https://github.com/objectstack-ai/framework/blob/main/packages/client/README.md)** — Developer navigation and API reference