docs(ai): document actions-as-tools (api + flow dispatch)

- content/docs/guides/ai-capabilities.mdx: new "Actions as Tools
  (auto-exposed)" section between AI Agents and RAG Pipelines —
  what gets exposed, plugin wiring (apiActionBaseUrl /
  apiActionHeaders), type:'api' body assembly rules, diagnostics.
- skills/objectstack-ai/SKILL.md: add "Auto-Exposed Actions"
  subsection under Tool Configuration so action authors don't
  hand-author tool defs for headless invocation.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: os-zhuang

content/docs/guides/ai-capabilities.mdx

@@ -11,10 +11,11 @@ Complete guide to leveraging AI agents, RAG pipelines, and intelligent automatio
 
 1. [AI Architecture](#ai-architecture)
 2. [AI Agents](#ai-agents)
-3. [RAG Pipelines](#rag-pipelines)
-4. [Natural Language Queries](#natural-language-queries)
-5. [Predictive Analytics](#predictive-analytics)
-6. [Best Practices](#best-practices)
+3. [Actions as Tools (auto-exposed)](#actions-as-tools-auto-exposed)
+4. [RAG Pipelines](#rag-pipelines)
+5. [Natural Language Queries](#natural-language-queries)
+6. [Predictive Analytics](#predictive-analytics)
+7. [Best Practices](#best-practices)
 
 ---
 
@@ -356,6 +357,56 @@ Use statistical analysis and ML.`,
 
 ---
 
+## Actions as Tools (auto-exposed)
+
+Every declarative {@link Action} you attach to an object is **automatically exposed as an AI tool**, named `action_<actionName>`. When the LLM picks one, the AI runtime dispatches to the same handler Studio's row toolbar would invoke — your business logic stays in one place.
+
+### What gets exposed
+
+The AI runtime walks every registered object's `actions[]` and exposes the ones that pass safety + wiring checks. 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`) |
+| `flow` | `IAutomationService.execute(target, { triggerData })` | `automation` service registered |
+
+Studio-only types (`url`, `modal`, `form`) and any action with `confirmText`, `mode: 'delete'`, or `variant: 'danger'` are skipped — those require Phase-3 HITL approval. Owners can also opt out per action with `aiExposed: false`.
+
+### Wiring it up
+
+```typescript
+import { AIServicePlugin } from '@objectstack/service-ai';
+
+kernel.use(
+  new AIServicePlugin({
+    // Enables type:'api' action dispatch. Relative `target` paths
+    // ('/api/v1/...') are resolved against this base URL.
+    apiActionBaseUrl: process.env.OS_AI_ACTION_API_BASE_URL,
+    // Forwarded on every api-action HTTP call (auth, environment id, ...).
+    apiActionHeaders: { Authorization: `Bearer ${process.env.SERVICE_TOKEN}` },
+  }),
+);
+```
+
+If `automation` is already registered with the kernel, `type:'flow'` actions are picked up automatically — no extra wiring needed.
+
+### `type:'api'` body assembly
+
+For api actions, the request body is built from three sources (last wins):
+
+1. **User-collected params** (the keys the LLM filled in).
+2. **`recordIdParam`** — when row-context, the id is placed flat at `action.recordIdParam`, using `recordIdField` (default `'id'`) to pick the value off the record.
+3. **`bodyExtra`** — constant fields that always override.
+
+`bodyShape: { wrap: 'data' }` nests the user params under `data` while keeping `recordIdParam` flat — matching shapes like better-auth's `organization/update`.
+
+### Diagnostics
+
+`registerActionsAsTools()` returns `{ registered, skipped }`. Studio surfaces the skipped list with reasons (e.g. `"no apiClient or apiBaseUrl configured"`, `"mode='delete' — destructive"`) so action authors can see at a glance whether their action will be LLM-callable.
+
+---
+
 ## RAG Pipelines
 
 Retrieval-Augmented Generation (RAG) provides AI with access to your knowledge base.

skills/objectstack-ai/SKILL.md

@@ -219,6 +219,27 @@ Tools are the atomic operations that skills expose to agents.
 }
 ```
 
+### Auto-Exposed Actions
+
+You usually **don't author tool definitions by hand** for action invocation. Every `Action` you attach to an object via `defineObject({ actions: [...] })` is auto-exposed as a tool named `action_<actionName>` by `registerActionsAsTools()` (invoked from `AIServicePlugin`).
+
+Three action types dispatch headlessly:
+
+| `action.type` | Dispatch | Wiring |
+|:---|:---|:---|
+| `script` | `IDataEngine.executeAction(object, target, ctx)` — same as Studio's row toolbar | none |
+| `api` | HTTP call to `action.target` (`fetch`-based by default) | `AIServicePlugin({ apiActionBaseUrl, apiActionHeaders })` or custom `apiClient` |
+| `flow` | `IAutomationService.execute(target, { triggerData })` | `automation` service registered with the kernel |
+
+**Skipped automatically:**
+- UI-only types (`url`, `modal`, `form`).
+- Dangerous variants (`confirmText` set, `mode: 'delete'`, `variant: 'danger'`) — Phase 3 HITL.
+- Owner opt-outs (`aiExposed: false`).
+
+**`type:'api'` body assembly** (last wins): user params → `recordIdParam` (using `recordIdField`, default `'id'`) → `bodyExtra`. `bodyShape: { wrap: 'data' }` nests user params under `data` while keeping `recordIdParam` flat.
+
+Use `actionSkipReason(action, ctx)` (exported from `@objectstack/service-ai`) when authoring an action and you want to know *why* it isn't surfacing in chat. Studio's "AI exposure" diagnostics use the same predicate.
+
 ---
 
 ## RAG Pipeline Configuration