feat: add server-side data access

AGENTS.md

@@ -57,6 +57,48 @@ onRouteRender, onRouteError
 onBefore*PageRendered
 ```
 
+### Server-side API Factory (`api`)
+
+Every backend plugin can expose a typed `api` surface for direct server-side or SSG data access (no HTTP roundtrip). Add an `api` factory alongside `routes`:
+
+```typescript
+// src/plugins/{name}/api/getters.ts  — pure DB functions, no hooks/HTTP context
+export async function listItems(adapter: Adapter): Promise<Item[]> { ... }
+export async function getItemById(adapter: Adapter, id: string): Promise<Item | null> { ... }
+
+// src/plugins/{name}/api/plugin.ts
+export const myBackendPlugin = defineBackendPlugin({
+  name: "{name}",
+  dbPlugin: dbSchema,
+  api: (adapter) => ({          // ← bound to shared adapter
+    listItems: () => listItems(adapter),
+    getItemById: (id: string) => getItemById(adapter, id),
+  }),
+  routes: (adapter) => { /* HTTP endpoints */ },
+})
+
+// src/plugins/{name}/api/index.ts  — re-export getters for direct import
+export { listItems, getItemById } from "./getters";
+```
+
+After calling `stack()`, the result exposes `api` (namespaced per plugin) and `adapter`:
+
+```typescript
+export const myStack = stack({ basePath, plugins, adapter })
+export const { handler, dbSchema } = myStack
+
+// Use in Server Components, generateStaticParams, scripts, etc.
+const items = await myStack.api["{name}"].listItems()
+const item  = await myStack.api["{name}"].getItemById("abc")
+```
+
+**Rules:**
+- Keep getters in a separate `getters.ts` — no HTTP context, no lifecycle hooks
+- The `api` factory and `routes` factory share the same adapter instance
+- If the plugin has a one-time init/sync step (like CMS `syncContentTypes`), call it inside each getter wrapper — not just inside `routes`
+- Re-export getters from `api/index.ts` for consumers who need direct import (SSG/build-time)
+- Authorization hooks are **not** called via `stack().api.*` — callers are responsible for access control
+
 ### Query Keys Factory
 
 Create a query keys file for React Query integration:
@@ -522,3 +564,7 @@ The `AutoTypeTable` component automatically pulls from TypeScript files, so ensu
 9. **Suspense errors not caught** - If errors from `useSuspenseQuery` aren't caught by ErrorBoundary, add the manual throw pattern: `if (error && !isFetching) { throw error; }`
 
 10. **Missing ComposedRoute wrapper** - Page components must be wrapped with `ComposedRoute` to get proper Suspense + ErrorBoundary handling. Without it, errors crash the entire app.
+
+11. **`stack().api` bypasses authorization hooks** - Getters accessed via `myStack.api.*` skip all `onBefore*` hooks. Never use them as a substitute for authenticated HTTP endpoints — enforce access control at the call site.
+
+12. **Plugin init steps not called via `api`** - If a plugin's `routes` factory runs a one-time setup (e.g. CMS `syncContentTypes`), that same setup must also be awaited inside the `api` getter wrappers, otherwise direct getter calls will query an uninitialised database.

docs/content/docs/plugins/ai-chat.mdx

@@ -929,3 +929,43 @@ overrides={{
 #### AiChatLocalization
 
 <AutoTypeTable path="../packages/stack/src/plugins/ai-chat/client/localization/index.ts" name="AiChatLocalization" />
+
+## Server-side Data Access
+
+The AI Chat plugin exposes standalone getter functions for server-side use cases, giving you direct access to conversation history without going through HTTP.
+
+### Two patterns
+
+**Pattern 1 — via `stack().api`**
+
+```ts title="app/lib/stack.ts"
+import { myStack } from "./stack";
+
+// List all conversations (optionally scoped to a user)
+const all        = await myStack.api["ai-chat"].getAllConversations();
+const userConvs  = await myStack.api["ai-chat"].getAllConversations("user-123");
+
+// Get a conversation with its full message history
+const conv       = await myStack.api["ai-chat"].getConversationById("conv-456");
+if (conv) {
+  console.log(conv.messages); // Message[]
+}
+```
+
+**Pattern 2 — direct import**
+
+```ts
+import {
+  getAllConversations,
+  getConversationById,
+} from "@btst/stack/plugins/ai-chat/api";
+
+const conv = await getConversationById(myAdapter, conversationId);
+```
+
+### Available getters
+
+| Function | Description |
+|---|---|
+| `getAllConversations(adapter, userId?)` | Returns all conversations, optionally filtered by userId |
+| `getConversationById(adapter, id)` | Returns a conversation with messages, or `null` |

docs/content/docs/plugins/blog.mdx

@@ -527,3 +527,57 @@ You can import the hooks from `"@btst/stack/plugins/blog/client/hooks"` to use i
 #### PostUpdateInput
 
 <AutoTypeTable path="../packages/stack/src/plugins/blog/client/hooks/blog-hooks.tsx" name="PostUpdateInput" />
+
+## Server-side Data Access
+
+The blog plugin exposes standalone getter functions for server-side and SSG use cases. These bypass the HTTP layer entirely and query the database directly.
+
+### Two patterns
+
+**Pattern 1 — via `stack().api` (recommended for runtime server code)**
+
+After calling `stack()`, the returned object includes a fully-typed `api` namespace. Getters are pre-bound to the adapter:
+
+```ts title="app/lib/stack.ts"
+import { myStack } from "./stack"; // your stack() instance
+
+// In a Server Component, generateStaticParams, etc.
+const result = await myStack.api.blog.getAllPosts({ published: true });
+// result.items  — Post[]
+// result.total  — total count before pagination
+// result.limit  — applied limit
+// result.offset — applied offset
+
+const post = await myStack.api.blog.getPostBySlug("hello-world");
+const tags = await myStack.api.blog.getAllTags();
+```
+
+**Pattern 2 — direct import (SSG, build-time, or custom adapter)**
+
+Import getters directly and pass any `Adapter`:
+
+```ts
+import { getAllPosts, getPostBySlug, getAllTags } from "@btst/stack/plugins/blog/api";
+
+// e.g. in Next.js generateStaticParams
+export async function generateStaticParams() {
+  const { items } = await getAllPosts(myAdapter, { published: true });
+  return items.map((p) => ({ slug: p.slug }));
+}
+```
+
+### Available getters
+
+| Function | Returns | Description |
+|---|---|---|
+| `getAllPosts(adapter, params?)` | `PostListResult` | Paginated posts matching optional filter params |
+| `getPostBySlug(adapter, slug)` | `Post \| null` | Single post by slug, or `null` if not found |
+| `getAllTags(adapter)` | `Tag[]` | All tags, sorted alphabetically |
+
+### `PostListParams`
+
+<AutoTypeTable path="../packages/stack/src/plugins/blog/api/getters.ts" name="PostListParams" />
+
+### `PostListResult`
+
+<AutoTypeTable path="../packages/stack/src/plugins/blog/api/getters.ts" name="PostListResult" />

docs/content/docs/plugins/cms.mdx

@@ -1248,3 +1248,42 @@ const result = zodSchema.safeParse(data)
 <AutoTypeTable path="../packages/ui/src/lib/schema-converter.ts" name="FormStep" />
 
 <AutoTypeTable path="../packages/ui/src/lib/schema-converter.ts" name="FormSchemaMetadata" />
+
+## Server-side Data Access
+
+The CMS plugin exposes standalone getter functions for server-side and SSG use cases.
+
+### Two patterns
+
+**Pattern 1 — via `stack().api`**
+
+```ts title="app/lib/stack.ts"
+import { myStack } from "./stack";
+
+const types  = await myStack.api.cms.getAllContentTypes();
+const items  = await myStack.api.cms.getAllContentItems("posts", { limit: 10 });
+const item   = await myStack.api.cms.getContentItemBySlug("posts", "my-first-post");
+```
+
+**Pattern 2 — direct import**
+
+```ts
+import {
+  getAllContentTypes,
+  getAllContentItems,
+  getContentItemBySlug,
+} from "@btst/stack/plugins/cms/api";
+
+export async function generateStaticParams() {
+  const result = await getAllContentItems(myAdapter, "posts", { limit: 100 });
+  return result.items.map((item) => ({ slug: item.slug }));
+}
+```
+
+### Available getters
+
+| Function | Description |
+|---|---|
+| `getAllContentTypes(adapter)` | Returns all registered content types, sorted by name |
+| `getAllContentItems(adapter, typeSlug, params?)` | Returns paginated items for a content type |
+| `getContentItemBySlug(adapter, typeSlug, slug)` | Returns a single item by slug, or `null` |