diff --git a/.objectui-sha b/.objectui-sha index 70a5447d09..c4974acc1e 100644 --- a/.objectui-sha +++ b/.objectui-sha @@ -1 +1 @@ -6cbccf386cf3fe15d1b8e79ab69fcf8f08c4cadf +c27bd3264f394bec5f5f71326118bfb115fbe884 diff --git a/apps/docs/app/[lang]/docs/layout.tsx b/apps/docs/app/[lang]/docs/layout.tsx index 38c912a629..1a15cb1ce8 100644 --- a/apps/docs/app/[lang]/docs/layout.tsx +++ b/apps/docs/app/[lang]/docs/layout.tsx @@ -13,10 +13,9 @@ export default async function Layout({ const { lang } = await params; return ( - {children} diff --git a/apps/docs/lib/layout.shared.tsx b/apps/docs/lib/layout.shared.tsx index aff3b86c24..a566acdc15 100644 --- a/apps/docs/lib/layout.shared.tsx +++ b/apps/docs/lib/layout.shared.tsx @@ -22,13 +22,6 @@ export function baseOptions(): BaseLayoutProps { ), }, - links: [ - { - text: 'Documentation', - url: '/docs/', - active: 'nested-url', - }, - ], githubUrl: `https://github.com/${gitConfig.user}/${gitConfig.repo}`, }; } diff --git a/content/docs/ai/actions-as-tools.mdx b/content/docs/ai/actions-as-tools.mdx index 921b1dd82f..78f13745cb 100644 --- a/content/docs/ai/actions-as-tools.mdx +++ b/content/docs/ai/actions-as-tools.mdx @@ -7,6 +7,8 @@ description: Expose declarative Action metadata as AI-callable tools with explic Part of the [AI module](/docs/ai) — how existing Action metadata becomes LLM-callable, and the guardrails around it. +This is what makes the app you built **AI-operable**: connect an MCP client (Claude Code, Cursor, …) and your business Actions become callable tools — so an agent can "resolve this ticket" or "convert this lead" through the same logic and permissions as the Console button. + Any business `Action` you already have — a `script` action or a Flow — can be reached by an LLM as a callable tool. On the **open edition** this happens through [`@objectstack/mcp`](/docs/ai): your own AI (Claude, Cursor, any MCP diff --git a/content/docs/ai/agents.mdx b/content/docs/ai/agents.mdx index b6c90b6fa0..2437261c55 100644 --- a/content/docs/ai/agents.mdx +++ b/content/docs/ai/agents.mdx @@ -11,7 +11,10 @@ skills are **typed metadata**: you author them as source with `defineAgent` / external AI client (Claude, Cursor, a local model — any MCP client) reaches your objects, queries, and business **Actions** through `@objectstack/mcp` (BYO-AI), all governed by RLS. This page describes that metadata and the `AgentSchema` it -validates against. +validates against. Like the rest of your metadata, you don't hand-write agents — +Claude Code authors them from the `objectstack-ai` [skill](/docs/ai/skills); you +`os validate` and test the tools in the Console +([the loop](/docs/getting-started/build-with-claude-code)). **Cloud / Enterprise — the in-product chat runtime.** The authoring format on diff --git a/content/docs/ai/index.mdx b/content/docs/ai/index.mdx index 5a335ea43e..08337814f5 100644 --- a/content/docs/ai/index.mdx +++ b/content/docs/ai/index.mdx @@ -7,6 +7,12 @@ description: Complete guide to leveraging AI agents, RAG pipelines, and intellig AI in ObjectStack is a **cross-protocol capability layer**: agents, tools, and knowledge retrieval sit on top of the same objects, actions, permissions, and automation that power the rest of the platform. This module covers the architecture and each of its moving parts. + +**Two different "AI" stories — don't confuse them:** +- **AI *builds* your app** (authoring) — Claude Code writes the typed metadata; you verify in the Console. That's the [Build with Claude Code](/docs/getting-started/build-with-claude-code) workflow, in *Get Started* — a different thing from this section. +- **Your app *exposes/uses* AI** (runtime) — agents, tools, RAG, natural-language queries, and an MCP server that let an AI operate the app you built, under the same permissions. **This section covers that.** + + **The open framework does AI bring-your-own-AI** — your keys, your models, zero platform AI cost. Everything on this page is part of the open edition unless a section is explicitly marked **cloud / Enterprise**: @@ -34,20 +40,11 @@ The **cloud / Enterprise** tier adds an in-product chat *runtime* on top of thes ObjectStack provides a comprehensive AI platform: -``` -┌─────────────────────────────────────┐ -│ AI Agents │ ← Persona + skills/tools -│ Skills & Tools │ ← Actions/Flows exposed to the LLM -├─────────────────────────────────────┤ -│ Knowledge Protocol │ ← search_knowledge via adapters -│ - memory / ragflow / custom │ -│ - Permission-aware retrieval │ -├─────────────────────────────────────┤ -│ Model Registry │ ← LLM management -│ - openai, azure_openai, │ -│ anthropic, local │ -│ - Token accounting / cost │ -└─────────────────────────────────────┘ +```mermaid +flowchart TD + A["AI Agents — persona + skills/tools"] --> T["Skills & Tools
Actions / Flows exposed to the LLM"] + T --> K["Knowledge Protocol — search_knowledge via adapters
memory / ragflow / custom · permission-aware retrieval"] + K --> R["Model Registry — LLM management
openai · azure_openai · anthropic · local · token accounting / cost"] ``` --- diff --git a/content/docs/ai/skills.mdx b/content/docs/ai/skills.mdx index 7e1ec554d8..12408e9ebd 100644 --- a/content/docs/ai/skills.mdx +++ b/content/docs/ai/skills.mdx @@ -7,7 +7,7 @@ import { Bot, Brain, Cpu, Database, Globe, Layout, Shield, Workflow, Wrench, Lan # AI Skills System -ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code. +ObjectStack introduces a **Skills System** — structured, domain-specific knowledge modules that enable AI assistants (GitHub Copilot, Claude Code, Cursor, etc.) to understand and generate protocol-compliant code. Skills are what make [building with Claude Code](/docs/getting-started/build-with-claude-code) reliable: they teach the agent the protocol's rules up front, so it authors correct metadata instead of guessing. Skills are **not runtime code**. They are machine-readable knowledge definitions that teach AI assistants the ObjectStack protocol — its schemas, patterns, constraints, and best practices. @@ -186,6 +186,10 @@ Read skills/objectstack-query/SKILL.md and help me build a query that filters opportunities by stage and aggregates revenue by quarter. ``` +For the end-to-end workflow — scaffold, let Claude Code author the metadata, +validate, and verify in the Console — follow +[Build with Claude Code](/docs/getting-started/build-with-claude-code). + ### With Cursor Add the skill files to your Cursor rules or reference them in prompts: @@ -224,4 +228,4 @@ The `evals/` directory in each skill is reserved for test cases that validate an - [AI Skills Reference](/docs/ai/skills-reference) — Detailed guide to each skill with usage examples - [AI Capabilities](/docs/ai) — AI agents, RAG pipelines, and intelligent automation - [Plugin Development](/docs/plugins/development) — Build custom plugins -- [Quick Start](/docs/getting-started/quick-start) — Build your first ObjectStack app +- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build your first ObjectStack app with an agent diff --git a/content/docs/api/index.mdx b/content/docs/api/index.mdx index 7ea6622d36..dd863fd9f4 100644 --- a/content/docs/api/index.mdx +++ b/content/docs/api/index.mdx @@ -23,6 +23,40 @@ ObjectStack exposes a fully typed REST API. All endpoints use JSON request/respo **Base URL**: Configurable, defaults to `/api/v1`. All paths below are relative to the base URL. +## Your app as an MCP server + +REST and GraphQL are how *code* consumes your app. **MCP is how *AI* consumes it.** +Because every object and action is typed metadata, ObjectStack can expose the whole app +as a [Model Context Protocol](https://modelcontextprotocol.io) server — so an AI client +(Claude Code, Claude Desktop, Cursor, a local model) can inspect and *operate* the app +you built, under the same permissions and RLS as the UI. Enable it with +`OS_MCP_SERVER_ENABLED=true` (see [environment variables](/docs/deployment/environment-variables#mcp-server)). + +The generated tools mirror the surfaces you already defined: +`list_objects` / `describe_object` (discover the schema), `query_records` / `get_record` +(read), `create_record` / `update_record` / `delete_record` (write), and +`list_actions` / `run_action` (invoke your business actions by name). Every call runs as +the caller — RBAC, RLS, and field-level security all apply. + +```mermaid +sequenceDiagram + participant AI as AI client (Claude / Cursor) + participant MCP as MCP server (@objectstack/mcp) + participant Eng as Action / ObjectQL engine + participant Sec as RBAC · RLS · FLS + participant DB as Data + + AI->>MCP: run_action("resolve", { recordId }) + MCP->>Eng: dispatch as the caller's principal + Eng->>Sec: check permissions on this record + Sec-->>Eng: allowed (or denied — fail-closed) + Eng->>DB: apply the change + DB-->>AI: result, same as the Console would return +``` + +See [Actions as Tools](/docs/ai/actions-as-tools) for the `run_action` bridge and the +[MCP reference](/docs/references/ai/mcp) for binding external MCP servers into your agents. + ## What's in this module - [Data API](/docs/api/data-api) — CRUD, batch operations, record cloning, and analytics queries diff --git a/content/docs/concepts/architecture.mdx b/content/docs/concepts/architecture.mdx index 7d6127c9c0..653e6138d8 100644 --- a/content/docs/concepts/architecture.mdx +++ b/content/docs/concepts/architecture.mdx @@ -9,6 +9,15 @@ import { Database, Layout, Cpu, ArrowRight, CheckCircle, Workflow, Bot, Cloud } The architecture is built on foundational protocols that work together as a unified system: + +**This is the engine-level view.** When you *build*, you work by area — data, +automation, interface, access, AI (see [What you build](/docs/getting-started/quick-start#what-you-build)). +This page zooms one level down, into the runtime engines that implement those areas: +**ObjectQL** (data), **ObjectOS** (control — automation, access, governance), and +**ObjectUI** (interface). You rarely think in these three while building; they're the +machinery underneath. + + } @@ -48,25 +57,22 @@ Traditional applications tightly couple data, business logic, and presentation. ObjectStack enforces **Separation of Concerns** through protocol boundaries: +```mermaid +flowchart TD + UI["UI Protocol & AI Protocol
Apps · Views · Dashboards · Agents · RAG
How do users and agents interact?"] + OS["System · Automation · Cloud Protocol
Auth · Permissions · Orchestration · Multi-tenancy
Who / what can do what, when, and where?"] + DATA["Data Protocol
Objects · Fields · Queries · Drivers
What is the data structure?"] + UI -->|Interface| OS + OS -->|Control| DATA ``` -┌───────────────────────────────────────────────────────────┐ -│ UI Protocol & AI Protocol │ -│ Apps, Views, Dashboards, Agents, RAG │ -│ "How do users and agents interact?" │ -└───────────────────────────┬───────────────────────────────┘ - │ Interface -┌───────────────────────────┴───────────────────────────────┐ -│ System Protocol & Automation Protocol & Cloud Protocol │ -│ Auth, Permissions, Orchestration, Multi-tenancy │ -│ "Who/What can do what, when, and where?" │ -└───────────────────────────┬───────────────────────────────┘ - │ Control -┌───────────────────────────┴───────────────────────────────┐ -│ Data Protocol │ -│ Objects, Fields, Queries, Drivers │ -│ "What is the data structure?" │ -└───────────────────────────────────────────────────────────┘ -``` + + +**Who writes this?** In practice, Claude Code authors across every area from your +description — data (objects), automation (flows), access (permissions), and interface +(views, apps) — guided by the matching [skills](/docs/ai/skills). Each passes +`os validate` before you review it in the Console. See +[How AI Development Works](/docs/getting-started/how-ai-development-works). + ## Layer 1: ObjectQL (Data Protocol) diff --git a/content/docs/concepts/index.mdx b/content/docs/concepts/index.mdx index e6ab829667..619569e1e6 100644 --- a/content/docs/concepts/index.mdx +++ b/content/docs/concepts/index.mdx @@ -187,5 +187,5 @@ ObjectStack enforces strict naming rules for consistency: ## Next Steps - [Architecture](/docs/concepts/architecture) — How the protocol layers work together -- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes +- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build your first app end-to-end with an agent - [Glossary](/docs/getting-started/glossary) — Key terminology diff --git a/content/docs/concepts/metadata-driven.mdx b/content/docs/concepts/metadata-driven.mdx index 41b663f080..08593350dc 100644 --- a/content/docs/concepts/metadata-driven.mdx +++ b/content/docs/concepts/metadata-driven.mdx @@ -9,6 +9,13 @@ import { Database, Code, Link, Laptop } from 'lucide-react'; Metadata-driven development is a paradigm shift where **business intent is defined by declarative, analyzable metadata instead of scattered imperative code.** + +This is also what makes ObjectStack **AI-native**: because the whole app is a few hundred +lines of typed, analyzable metadata — not tens of thousands of lines of glue — it fits in +an agent's context window. Claude Code authors it, `os validate` catches mistakes, and you +verify in the Console. See [How AI Development Works](/docs/getting-started/how-ai-development-works). + + ## The Problem with Code-First In traditional development, the "Intent" (e.g., *"This field is a required email address"*) is scattered across multiple layers: diff --git a/content/docs/deployment/environment-variables.mdx b/content/docs/deployment/environment-variables.mdx index 03034915ac..f2632211a5 100644 --- a/content/docs/deployment/environment-variables.mdx +++ b/content/docs/deployment/environment-variables.mdx @@ -215,11 +215,22 @@ Provider credentials keep their upstream names. ObjectStack does not rename ## MCP Server +Enable this to make **the app you built AI-operable**: with the MCP server on, an +MCP client — Claude Code, Claude Desktop, Cursor, or a local model — connects to your +running app and gets a generated tool surface over your objects and actions +(`query_records`, `run_action`, …), bound to the caller's principal and governed by the +same RBAC / RLS as the Console. No custom tooling, no separate API. See +[Actions as Tools](/docs/ai/actions-as-tools) for the tool set. + +```bash +OS_MCP_SERVER_ENABLED=true os start # boot with the MCP server (stdio by default) +``` + | Variable | Type | Default | Description | |:---|:---|:---|:---| -| `OS_MCP_SERVER_ENABLED` | boolean | `false` | When `true`, start the Model Context Protocol server at boot. | +| `OS_MCP_SERVER_ENABLED` | boolean | `false` | When `true`, start the Model Context Protocol server at boot — exposing your objects and actions to MCP clients. | | `OS_MCP_SERVER_NAME` | string | `objectstack` | Server name advertised to MCP clients. | -| `OS_MCP_SERVER_TRANSPORT` | enum | `stdio` | `stdio` \| `http`. | +| `OS_MCP_SERVER_TRANSPORT` | enum | `stdio` | `stdio` \| `http`. Use `http` (Streamable HTTP) for a remote client; `stdio` for a local one. | --- diff --git a/content/docs/deployment/index.mdx b/content/docs/deployment/index.mdx index 9c62b799fb..66658cd049 100644 --- a/content/docs/deployment/index.mdx +++ b/content/docs/deployment/index.mdx @@ -133,6 +133,14 @@ settings are the exception — they route through the settings env-override convention as `OS_MAIL_` (e.g. `OS_MAIL_SMTP_HOST`, `OS_MAIL_SMTP_PORT`), not a raw `SMTP_*` name. + +**Make the deployed app AI-operable:** set `OS_MCP_SERVER_ENABLED=true` to start an MCP +server alongside any deployment mode, exposing your objects and actions to AI clients +under the same permissions and RLS. See +[MCP Server env vars](/docs/deployment/environment-variables#mcp-server) and +[Your app as an MCP server](/docs/api#your-app-as-an-mcp-server). + + **Set `OS_SECRET_KEY` for any containerized or multi-node deployment.** The default `LocalCryptoProvider` encrypts every `sys_secret` value under one diff --git a/content/docs/getting-started/build-with-claude-code.mdx b/content/docs/getting-started/build-with-claude-code.mdx new file mode 100644 index 0000000000..4add949061 --- /dev/null +++ b/content/docs/getting-started/build-with-claude-code.mdx @@ -0,0 +1,356 @@ +--- +title: Build with Claude Code +description: The core ObjectStack workflow — Claude Code authors the metadata, you verify in the visual Console, guardrails catch mistakes, and the app you build is itself AI-operable over MCP. +--- + +# Build with Claude Code + +This is the **main way you build on ObjectStack**: you describe what you want in +plain language, **Claude Code (or Cursor, Copilot, …) writes the typed metadata**, +a validation gate catches the mistakes that fail silently at runtime, and **you +verify the result by clicking through the real app** in the Console. Then you say +what to change, and the loop repeats. + +The thing you end up with isn't just an app — it's an app that AI can *operate*, +because the same metadata generates an MCP server. + + +Want to understand the pieces the agent writes before you review them? +[Anatomy of an ObjectStack App](/docs/getting-started/quick-start) is a tour of +the metadata — objects, actions, views — and how to read it. This page is the +workflow; that one is the map. + + +## The build loop + +```mermaid +flowchart TD + S["Scaffold, once — npm create objectstack@latest
installs the skills bundle + AGENTS.md"] --> A + A["1 · Describe in plain language"] --> B["2 · Claude Code authors the typed metadata"] + B --> G{"3 · os validate
the gate"} + G -->|"fails: located, corrective error"| B + G -->|passes| V["4 · You verify in the Console UI"] + V -->|needs a change| A + V -->|looks right| M["5 · MCP — your app is AI-operable"] +``` + +Steps 3–5 are the heartbeat: **AI authors, the gate checks, you verify.** Nobody +hand-edits generated glue, and no metadata mistake reaches the browser unchecked. + +## Before you start + +| You need | Why | +|:---|:---| +| **Node.js 18+** and **pnpm** | Runs the scaffolder and the dev server (see [prerequisites](/docs/getting-started#prerequisites)). | +| **[Claude Code](https://claude.com/claude-code)** (or Cursor / Copilot) | Your agent reads `AGENTS.md` + the ObjectStack skills and authors the metadata. | + +## 1. Scaffold the project + +```bash +npm create objectstack@latest support-desk +cd support-desk +``` + +The scaffolder does more than copy files. It: + +- derives a **namespace** from the name (`support-desk` → `support_desk`), so + every object you create is named `support_desk_*`; +- installs dependencies; +- runs `npx skills add objectstack-ai/framework --all` to install the **AI skills + bundle**; +- writes an **`AGENTS.md`** (and `.github/copilot-instructions.md`) that teach your + coding agent the project layout, the naming rules, and — critically — *to run + `npm run validate` after every metadata change*. + +``` + ╔═══════════════════════════════════╗ + ║ ◆ Create ObjectStack v6.x ║ + ╚═══════════════════════════════════╝ + +◆ New Environment +──────────────────────────────────────── + Environment: support-desk + Namespace: support_desk + Template: blank — Minimal starter — one object, REST API, ready to extend + … + → Installing AI skills for your coding agent... + ✓ Environment created! +``` + +This is why AI authoring is reliable rather than a guessing game: **the agent +starts with the protocol's schemas and rules already loaded**, not with generic +"write me some TypeScript" priors. See [AI Skills](/docs/ai/skills) for how the +bundle works. + +## 2. Open the project in Claude Code and describe the app + +From the project directory, launch Claude Code and give it the goal in plain +language: + +> Build a support-desk app. Add a `ticket` object with a subject, a long-text +> description, a `priority` select (low/normal/high/urgent) and a `status` select +> (open/pending/resolved/closed). Add a **Resolve** action that only shows on +> tickets that aren't already resolved or closed. Add a list view (subject, +> status, priority) with an "Open tickets" filter, and an app with a Support nav +> group. Run `npm run validate` when you're done. + +You don't specify field types in TypeScript, wire barrel exports, or remember the +CEL scoping rules — the agent does, because the skills told it how. + +## 3. What Claude Code writes + +The agent authors ordinary project files. You review them — you don't type them. +A representative result: + +```typescript title="src/objects/ticket.object.ts" +import { ObjectSchema, Field } from '@objectstack/spec/data'; + +export const Ticket = ObjectSchema.create({ + name: 'support_desk_ticket', + label: 'Ticket', + pluralLabel: 'Tickets', + icon: 'life-buoy', + description: 'A customer support request.', + + fields: { + subject: Field.text({ label: 'Subject', required: true, searchable: true, maxLength: 200 }), + description: Field.longText({ label: 'Description' }), + + priority: Field.select({ + label: 'Priority', + required: true, + options: [ + { label: 'Low', value: 'low', default: true }, + { label: 'Normal', value: 'normal' }, + { label: 'High', value: 'high' }, + { label: 'Urgent', value: 'urgent' }, + ], + }), + + status: Field.select({ + label: 'Status', + required: true, + options: [ + { label: 'Open', value: 'open', color: '#3B82F6', default: true }, + { label: 'Pending', value: 'pending', color: '#F59E0B' }, + { label: 'Resolved', value: 'resolved', color: '#10B981' }, + { label: 'Closed', value: 'closed', color: '#6B7280' }, + ], + }), + }, + + enable: { apiEnabled: true, searchable: true }, +}); +``` + +```typescript title="src/actions/ticket.actions.ts" +import { defineAction } from '@objectstack/spec/ui'; + +export const ResolveTicketAction = defineAction({ + name: 'resolve_ticket', + label: 'Resolve', + objectName: 'support_desk_ticket', + icon: 'check-circle', + type: 'script', + target: 'resolveTicket', + locations: ['record_header', 'list_item'], + // Only offer "Resolve" on tickets that aren't already resolved or closed. + // Predicates are CEL, record-scoped — `record.status`, never bare `status`. + visible: 'record.status != "resolved" && record.status != "closed"', + successMessage: 'Ticket resolved.', + refreshAfter: true, + ai: { + exposed: true, + description: 'Mark a support ticket as resolved. Use when the issue is fixed.', + }, +}); +``` + +```typescript title="src/views/ticket.view.ts" +import { defineView } from '@objectstack/spec'; + +const data = { provider: 'object' as const, object: 'support_desk_ticket' }; + +export const TicketViews = defineView({ + list: { + label: 'All Tickets', + type: 'grid', + data, + columns: [{ field: 'subject' }, { field: 'status' }, { field: 'priority' }], + }, + listViews: { + open: { + label: 'Open Tickets', + type: 'grid', + data, + columns: [{ field: 'subject' }, { field: 'priority' }], + filter: [{ field: 'status', operator: 'equals', value: 'open' }], + sort: [{ field: 'priority', order: 'desc' }], + }, + }, +}); +``` + +This is the same metadata that powers the REST API, the Console UI, **and the MCP +tools exposed to AI** — define it once, and ObjectStack derives the rest. + +## 4. The gate: `os validate` catches AI mistakes + +The most common way AI-authored metadata goes wrong is a mistake that **type-checks +cleanly and then fails silently at runtime** — there's no stack trace to feed back +to the agent. ObjectStack turns those into loud, located build errors. + +Suppose the agent wrote the Resolve action's predicate as a **bare field +reference** — `status` instead of `record.status`: + +```typescript +// ✗ Wrong — bare `status`. Type-checks (it's just a string), but at runtime +// it resolves to null, so the action is hidden on EVERY ticket. +visible: 'status != "resolved"' +``` + +`npm run validate` (which `AGENTS.md` tells the agent to run) refuses it: + +``` +◆ Validate +──────────────────────────────────────── + → Validating against ObjectStack Protocol... + → Validating expressions (ADR-0032)... + + ✗ Expression validation failed (1 issue) + • stack · action 'resolve_ticket' visible: bare reference `status` — a + formula/validation expression binds the record as the `record` namespace, + not at top level, so `status` resolves to nothing and the expression + silently evaluates to null. Write `record.status`. + source: `status != "resolved"` + + ✗ EEXIT: 1 +``` + +The message is **located** (which action, which predicate) and **corrective** +("Write `record.status`") — so the agent fixes it in one step instead of you +discovering a dead button three screens deep in the browser. This is the +["contract-first" guarantee](/docs/getting-started/how-ai-development-works#why-its-safe): +the error is rejected at the authoring gate, not tolerated by a lenient runtime. +For the full list of what the gate checks, see +[Validating Metadata](/docs/getting-started/validating-metadata). + +Once it's clean: + +``` + ✓ Validation passed (37ms) + + Support Desk v0.1.0 + Data: 1 Objects 6 Fields + UI: 1 Apps 1 Views 1 Actions +``` + + +**Never accept a metadata change as done until `os validate` passes.** It's the +same gate `os build` runs, so anything that validates will also compile. + + +## 5. Verify in the visual UI — your job in the loop + +Validation proves the metadata is *well-formed*. It can't prove the app does what +*you* meant. That's the human half of the loop: **run it and look.** + +```bash +os dev --ui +``` + +Open [http://localhost:3000/_console/](http://localhost:3000/_console/) and drive +the app like a user: + +- Create a ticket. Confirm the fields, labels, and picklist colors match intent. +- Check the **Resolve** action shows on an open ticket — and **disappears** once + the ticket is resolved (that's the `record.status` predicate doing its job). +- Open the **Support → Open** nav item; confirm the filter shows only open tickets. + +{/* screenshot placeholder: /_console/ ticket list with the Support nav group */} +{/* screenshot placeholder: ticket record with the Resolve action in the header */} + +This is where you catch the things static checks never will — a confusing label, a +missing field, the wrong default, an action that shows when it shouldn't. You're +the product reviewer; the Console is your cockpit. + +## 6. Iterate + +Found something? Don't hand-patch it — tell the agent, in the same plain language: + +> The list is missing who a ticket is assigned to. Add an `assignee` lookup to +> `sys_user`, show it as a column in the list view, and re-run validate. + +Claude Code edits the metadata, re-runs `os validate`, and you refresh the Console +to confirm. **That's the whole loop** — describe → author → gate → verify — +tightening on each pass until the app is right. See +[How AI development works](/docs/getting-started/how-ai-development-works) for why +this stays fast and safe as the app grows. + +## 7. Your app is natively AI-operable (MCP) + +Here's the payoff that a hand-built CRUD app doesn't give you for free: because +the whole app is typed metadata, ObjectStack can expose it as an **MCP server** — +so an AI client can inspect and *operate* the app you just built, under the exact +same permissions and row-level security as the UI. + +Point your own AI (Claude Code, Claude Desktop, Cursor, any MCP client) at the +running app, and it gets a generated tool surface over your objects and actions: + +| Tool | What the AI can do | +|:---|:---| +| `list_objects` / `describe_object` | Discover the `support_desk_ticket` schema. | +| `query_records` / `get_record` | "Show me all urgent open tickets." | +| `create_record` / `update_record` | File or edit a ticket. | +| `list_actions` / `run_action` | Run your **Resolve** action by name — "resolve ticket #42" — through the same business logic the toolbar button uses. | + +Every call is bound to the caller's principal, so RBAC, RLS, and field-level +security apply to the agent exactly as they do to a person. The support desk you +built in six steps is now a backend an agent can *run* — not just a database it +can read. + +See [Actions as Tools](/docs/ai/actions-as-tools) for the `run_action` bridge and +[the MCP reference](/docs/references/ai/mcp) for enabling the server and connecting +a client. + +## Recap — where each guardrail sat + +``` + describe ─▶ Claude authors ─▶ os validate ─▶ you verify in UI ─▶ iterate ─▶ MCP + │ │ │ + skills+AGENTS.md the gate rejects Console is the + taught the rules silent-runtime human review + up front mistakes loudly surface +``` + +- **Skills + `AGENTS.md`** meant the agent authored to the protocol, not from + generic priors. +- **`os validate`** turned a silent-at-runtime bug into a located, corrective + build error — the AI fixes it before you ever see it. +- **The Console** let you verify intent visually, which no schema check can. +- **MCP** made the finished app itself AI-operable, under the same guardrails. + +## Next steps + + + + + + + diff --git a/content/docs/getting-started/cli.mdx b/content/docs/getting-started/cli.mdx index 3e96df2ae8..7aeac64c4d 100644 --- a/content/docs/getting-started/cli.mdx +++ b/content/docs/getting-started/cli.mdx @@ -53,6 +53,14 @@ os compile # Build production artifact → dist/objectstack.json + +**These commands *are* the AI build loop.** In day-to-day work, Claude Code writes the +metadata and runs two of them for you: `os validate` is **the gate** (it rejects +predicate/schema/binding mistakes that fail silently at runtime), and `os dev --ui` is +**the human verify surface** (the Console, where you confirm the app matches intent). See +[Build with Claude Code](/docs/getting-started/build-with-claude-code) for the full loop. + + `os dev --ui` starts a dev server with the bundled Console UI, auto-loads ObjectQL, an in-memory driver when appropriate, and the Hono HTTP server. diff --git a/content/docs/getting-started/examples.mdx b/content/docs/getting-started/examples.mdx index 389c9b244f..dd6aa0e89a 100644 --- a/content/docs/getting-started/examples.mdx +++ b/content/docs/getting-started/examples.mdx @@ -9,6 +9,15 @@ import { CheckSquare, Building2, BarChart3, Server } from 'lucide-react'; The monorepo ships three ready-to-run examples in `examples/` that progressively demonstrate ObjectStack features — from a simple Todo app to a full CRM and a kitchen-sink reference. For a larger external enterprise reference, see the [HotCRM repository](https://github.com/objectstack-ai/hotcrm). + +**Read these as reference, then build your own with an agent.** Each example is the same +kind of typed metadata Claude Code authors for you — so they double as a catalog of +patterns to point your agent at ("build me a CRM like `app-crm`, but for support +tickets"). To *extend* one, describe the change in plain language, let the agent edit the +metadata, run `os validate`, and verify in the Console — the loop in +[Build with Claude Code](/docs/getting-started/build-with-claude-code). + + } diff --git a/content/docs/getting-started/how-ai-development-works.mdx b/content/docs/getting-started/how-ai-development-works.mdx new file mode 100644 index 0000000000..3043dc806f --- /dev/null +++ b/content/docs/getting-started/how-ai-development-works.mdx @@ -0,0 +1,111 @@ +--- +title: How AI Development Works +description: The division of labor behind ObjectStack — AI authors the typed metadata, you verify in the visual UI, and layered guardrails keep the AI from shipping mistakes. +--- + +# How AI Development Works + +ObjectStack is built for a specific way of working: **an AI agent writes the +application; a human verifies it in a visual UI; and a stack of guardrails keeps +the AI from shipping mistakes.** This page explains why that division of labor is +both *fast* and *safe*. For the hands-on walkthrough, see +[Build with Claude Code](/docs/getting-started/build-with-claude-code). + +## The division of labor + +| The AI does | You do | +|:---|:---| +| Author typed metadata — objects, fields, views, actions, flows, permissions | Say what you want, in plain language | +| Run the validation gate and fix what it flags | **Verify the result in the Console** — click through the real app | +| Apply your feedback and re-verify | Decide when it's right | + +The agent handles the mechanical, error-prone surface (field types, CEL scoping, +barrel wiring, naming rules). You handle the part no schema can check: *did it +build the thing I actually meant?* + +## Why it's fast + +A typical enterprise app is tens of thousands of lines of CRUD, forms, queries, +permissions, and API glue spread across dozens of files. ObjectStack collapses the +same surface into **a few hundred lines of typed metadata** — roughly two orders +of magnitude less code to read, write, and maintain. + +The point isn't lines of code; it's **fit in an agent's context window.** When the +entire business system is small, typed, and declarative, an agent can load it +end-to-end, reason about every dependency, and safely refactor across data, API, +UI, and permissions in a single change. That's what turns AI from an autocomplete +tool into a real co-maintainer of production business software. + +## Why it's safe + +The AI's speed is only useful if its mistakes can't reach production. Five layers +stand between "the agent wrote something" and "it shipped": + +### 1. Skills + `AGENTS.md` — the agent knows the rules up front + +Every scaffolded project installs the [ObjectStack skills bundle](/docs/ai/skills) +and an `AGENTS.md`. The agent authors *to the protocol's schemas and conventions* +— `snake_case` names, Zod-first shapes, `record.`-scoped predicates — instead of +from generic "write me some TypeScript" priors. Most mistakes never happen. + +### 2. `os validate` / `os build` — the authoring gate + +Metadata is data, not code paths, so most mistakes **pass `tsc` and then fail +silently at runtime** — a bare-field predicate hides an action on every record; a +dangling widget binding renders an empty chart. `os validate` parses every CEL +predicate, checks each `record.` resolves, and verifies widget bindings — +failing with a **located, corrective** message. It's the same gate `os build` +runs. See [Validating Metadata](/docs/getting-started/validating-metadata). + +### 3. Contract-first — reject at the gate, never patch the runtime + +When metadata "doesn't work," the fix is to correct the **producer** and make the +gate reject the bad input loudly — *not* to add a lenient fallback in the consumer +that silently tolerates it. Loud rejection at authoring time is what keeps AI +mistakes from accumulating into quiet, compounding drift. + +### 4. Draft-gating + human review + +AI-authored metadata changes can land as **drafts** rather than being published +directly. In Studio, a change set surfaces as a reviewable diff ("Review N +changes") that a human approves before it goes live — so an agent's write is a +*proposal*, not an unattended commit. + +### 5. Worktree isolation + +Multiple agents can work the same repo in parallel without clobbering each other, +because each works in its own git worktree and branch. Their changes converge +through normal review, not by racing on a shared checkout. + +## The verification layer + +Guardrails 1–3 prove the metadata is *well-formed*. They can't prove it's *what +you meant*. That's what the **Console** (and Studio) are for: run `os dev --ui`, +open the real app, and drive it as a user or admin. Wrong default, confusing +label, an action that shows when it shouldn't — you catch those by looking, and +then feed the correction back to the agent. The visual UI is the human's half of +every loop. + +## The output is AI-operable too + +Because the whole app is typed metadata, ObjectStack also generates an **MCP +server** from it. The app you build isn't just AI-*built* — it's AI-*operable*: +an MCP client can `query_records` and `run_action` against it, governed by the +same RBAC, RLS, and audit as the UI. The guardrails that protect authoring also +protect what agents do to real data at runtime. See +[Actions as Tools](/docs/ai/actions-as-tools). + +## Next steps + + + + + diff --git a/content/docs/getting-started/index.mdx b/content/docs/getting-started/index.mdx index eac36f6eaf..e7418e505a 100644 --- a/content/docs/getting-started/index.mdx +++ b/content/docs/getting-started/index.mdx @@ -7,6 +7,41 @@ import { Database, Layout, Cog } from 'lucide-react'; **ObjectStack** is not just a framework; it is an **AI-native business backend protocol** for building enterprise software. It decouples the *Business Intent* (defined as typed metadata) from the *Technical Execution* (handled by the Kernel), so APIs, UI metadata, workflows, and agent tools can all derive from the same source of truth. +## How you'll build + +ObjectStack is designed around one workflow: **an AI agent authors the app; you +verify it in a visual UI; guardrails keep the agent from shipping mistakes.** + +``` + describe ─▶ Claude Code authors ─▶ os validate ─▶ you verify in ─▶ iterate ─▶ MCP + in plain the typed metadata (the gate) the Console (app is + language AI-operable) +``` + +You say what you want; Claude Code (or Cursor, Copilot, …) writes the typed +metadata, because the [skills bundle](/docs/ai/skills) and a scaffolded `AGENTS.md` +taught it the protocol. A validation gate rejects the mistakes that fail silently +at runtime, and you confirm the result by clicking through the real app. Then the +app you built is itself AI-operable, because the same metadata generates an MCP +server. + + + + + + +The rest of this page explains *why* an agent can build an enterprise app +end-to-end safely: the protocol, and how everything derives from one source of +truth. + ## The Problem In traditional development, application logic is scattered: @@ -21,23 +56,33 @@ When requirements change, you update code in multiple places. When AI agents nee ## The Solution -We centralize the "Intent" into a single TypeScript-authored, Zod-validated protocol definition. The implementation layers (React, Node.js, SQL, MCP tools) act as **Runtime Engines** that interpret this protocol. +We centralize the "Intent" into a single TypeScript-authored, Zod-validated definition. You (and the agent) work in the same areas an app naturally divides into — data, automation, interface, access, AI — and the implementation layers (SQL, React, MCP tools) act as **Runtime Engines** that interpret that metadata. } - title="Data Protocol" - description="Define business objects, fields, queries, and constraints. Database-agnostic abstraction layer." + title="Data" + description="Business objects, fields, relationships, validation — the source of truth." + /> + } + title="Automation" + description="Flows, workflows, triggers, and approvals — the process logic." /> } - title="UI Protocol" - description="Presentation metadata for apps, views, dashboards, and actions." + title="Interface" + description="Apps, views, dashboards, and actions — the server-driven UI." /> } - title="System Protocol" - description="Runtime kernel, plugins, security, automation, audit, and agent boundaries." + title="Access" + description="Roles, permissions, sharing, and row-level security." + /> + } + title="AI" + description="Agents, tools, RAG, and the generated MCP surface." /> @@ -147,4 +192,5 @@ For more troubleshooting, see the [Troubleshooting & FAQ](/docs/deployment/troub - [Core Concepts](/docs/concepts) — Metadata-driven development & design principles - [Architecture](/docs/concepts/architecture) — The three-layer protocol stack - [Glossary](/docs/getting-started/glossary) — Key terminology -- [Quick Start](/docs/getting-started/quick-start) — Build your first app in 5 minutes +- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build your first app end-to-end with an agent +- [Anatomy of an ObjectStack App](/docs/getting-started/quick-start) — Read the metadata an agent writes, so you can verify it diff --git a/content/docs/getting-started/meta.json b/content/docs/getting-started/meta.json index de00dc59e7..4958782f6b 100644 --- a/content/docs/getting-started/meta.json +++ b/content/docs/getting-started/meta.json @@ -4,6 +4,8 @@ "defaultOpen": true, "pages": [ "index", + "how-ai-development-works", + "build-with-claude-code", "quick-start", "examples", "cli", diff --git a/content/docs/getting-started/quick-start.mdx b/content/docs/getting-started/quick-start.mdx index b861e752b5..71ba54326c 100644 --- a/content/docs/getting-started/quick-start.mdx +++ b/content/docs/getting-started/quick-start.mdx @@ -1,190 +1,186 @@ --- -title: Quick Start -description: Learn to build enterprise applications with the ObjectStack Protocol +title: Anatomy of an ObjectStack App +description: A tour of the metadata an AI agent writes for you — objects, actions, views, apps — and how to read it so you can verify the result in the Console. --- -# Quick Start +# Anatomy of an ObjectStack App -This guide teaches you how to **build real applications** using the ObjectStack Protocol. Each section is hands-on, with code examples derived from the [HotCRM reference app](https://github.com/objectstack-ai/hotcrm). +An ObjectStack app *is* its metadata: a few hundred lines of typed definitions for +objects, actions, views, apps, automation, and permissions. In the +[AI-first workflow](/docs/getting-started/build-with-claude-code), **an agent +writes these files for you** — you rarely type them by hand. + +But you do need to **read** them. In AI development the human's job shifts from +writing code to *verifying* what the agent produced: is the object modelled right, +is that predicate scoped correctly, does the app match what you asked for? This +page is a tour of the pieces so you can review an agent's work with confidence — +and catch the things the [validation gate](/docs/getting-started/validating-metadata) +can't. -**New to ObjectStack?** Start with the [Example Apps](/docs/getting-started/examples) to see working code, or read the [Introduction](/docs/getting-started) for the architecture overview. +Want to *build* something, not just read about the pieces? Follow +[Build with Claude Code](/docs/getting-started/build-with-claude-code) — it runs +the whole loop (describe → agent authors → validate → verify) on a live app. New +here? The [Example Apps](/docs/getting-started/examples) are working code you can +run today. -## Quick Start - - - -### Create a project - -```bash -npx @objectstack/cli init my-app -cd my-app -``` +## What you build -The `os` commands below use the CLI that `init` installs into your project — if `os` isn't on your PATH, run them as `npx os …` (or `pnpm exec os …`). +Everything an agent writes falls into one of a few areas — the same way the work +divides when you build an app. This is the map to hold in your head when you read +a project: -### Add AI skills to your editor +| Area | The metadata you author (`src/…`) | What ObjectStack derives from it | +| :--- | :--- | :--- | +| **Data** | Objects, fields, relationships, validation (`src/objects`) | Database schema, CRUD APIs, type safety | +| **Automation** | Flows, workflows, triggers, approvals (`src/flows`) | Event handlers, approval chains, scheduled jobs | +| **Interface** | Views, apps, dashboards, actions (`src/views`, `src/apps`) | The Console UI, navigation, responsive layout | +| **Access** | Roles, permissions, sharing, row-level security | Middleware, RLS policies, field masking | +| **AI** | Agents, tools, RAG, MCP exposure (`src/agents`) | Chat, search indexes, an MCP server | -Install the ObjectStack skill bundle so your AI assistant (Claude Code, Copilot, Cursor, …) knows the protocol's schemas and conventions: +The through-line: **you author intent once as metadata, and the runtime derives the +database, the API, the UI, and the AI tool surface from it.** That's why an agent +can build across all of these in one coherent change — and why reading the +metadata tells you everything about how the app behaves. -```bash -npx skills add objectstack-ai/framework --all -``` - -Re-run the same command any time to update — the bundle is versioned as one unit. See the [AI Skills Reference](/docs/ai/skills-reference) for the full catalog. - - -Scaffolding with `npm create objectstack@latest` runs this step automatically. - +## Reading an object -### Define your first object +The object is the heart of every app. Here's a representative one, in the same +`ObjectSchema.create` + `Field.*` form the scaffolder and the agent use: -The scaffolded project includes a sample object. Open `src/objects/my_app_item.ts`: +```typescript title="src/objects/ticket.object.ts" +import { ObjectSchema, Field } from '@objectstack/spec/data'; -```typescript -import * as Data from '@objectstack/spec/data'; +export const Ticket = ObjectSchema.create({ + name: 'support_desk_ticket', // ← snake_case, namespace-prefixed + label: 'Ticket', + pluralLabel: 'Tickets', + icon: 'life-buoy', + description: 'A customer support request.', -const myAppItem: Data.Object = { - name: 'my_app_item', - label: 'My App Item', fields: { - name: { - type: 'text', - label: 'Name', - required: true, - }, - description: { - type: 'textarea', - label: 'Description', - }, - status: { - type: 'select', + subject: Field.text({ label: 'Subject', required: true, searchable: true, maxLength: 200 }), + description: Field.longText({ label: 'Description' }), + + status: Field.select({ label: 'Status', + required: true, options: [ - { label: 'Draft', value: 'draft' }, - { label: 'Active', value: 'active' }, - { label: 'Archived', value: 'archived' }, + { label: 'Open', value: 'open', color: '#3B82F6', default: true }, + { label: 'Pending', value: 'pending', color: '#F59E0B' }, + { label: 'Resolved', value: 'resolved', color: '#10B981' }, + { label: 'Closed', value: 'closed', color: '#6B7280' }, ], - defaultValue: 'draft', - }, + }), }, -}; -export default myAppItem; + enable: { apiEnabled: true, searchable: true }, +}); ``` +**What to check when you read one:** + +- **Names** are `snake_case` and namespace-prefixed (`support_desk_ticket`) — the + scaffolder derives the prefix from your project name. +- **Field types** are `Field.*` builders (`text`, `longText`, `select`, `date`, + `lookup`, …), not raw strings. A `select`'s `options` carry the exact labels, + values, and colors you'll see in the UI — verify these match your intent. +- **`required`, `default`, `searchable`** encode behavior the UI and API inherit + automatically. + -This is the same metadata that powers the REST API, Studio editors, and the MCP tools exposed to AI agents — define it once, and ObjectStack derives the rest. +This one definition powers the REST API, the Console UI, **and the MCP tools +exposed to AI agents**. Define it once, and ObjectStack derives the rest — see +[Data Modeling](/docs/data-modeling) for the full field catalog and relationships. -### Launch the Console +## Reading the other pieces -```bash -os dev --ui -``` +The remaining domains follow the same shape — a typed factory call per file. When +reviewing an agent's work, these are the two things most worth a close read: -Open [http://localhost:3000/_console/](http://localhost:3000/_console/) to browse your objects, test the REST API, and inspect metadata. The server automatically provides: +- **Actions** (`defineAction`) — buttons and bulk operations. Their `visible` / + `disabled` **predicates are CEL, record-scoped**: `record.status`, never a bare + `status`. A bare reference silently hides the action on every record — the single + most common AI mistake, which is exactly why `os validate` rejects it. See it in + action in [Build with Claude Code → the gate](/docs/getting-started/build-with-claude-code#4-the-gate-os-validate-catches-ai-mistakes). +- **Views & Apps** (`defineView`, `App.create`) — the list/form lenses and the + navigation. Reading these tells you what the user will actually see and click. -- **ObjectQL Engine** — Query layer with CRUD operations -- **InMemory Driver** — Zero-config data storage for development -- **Hono HTTP Server** — REST API at `/api/v1/data/{object}` -- **Console UI** — Admin interface at `/_console/` +For the full authoring surface of each, load the matching +[skill](/docs/ai/skills) or read [UI Metadata](/docs/ui) and +[Automation](/docs/automation). -### Add more metadata +## Reading a project's layout -```bash -os g object customer # Generate a new object -os g action approve # Generate an action -os g flow onboarding # Generate an automation flow +Metadata is grouped by domain under `src/`. This map lets you navigate any +ObjectStack project — including one an agent just generated: + +``` +support-desk/ +├── objectstack.config.ts # defineStack() — the single entry point, wires it all +├── src/ +│ ├── objects/ # Data models (required) +│ ├── actions/ # Buttons, bulk operations +│ ├── views/ # List / form / kanban lenses +│ ├── apps/ # Navigation shells +│ ├── flows/ # Automation logic +│ ├── dashboards/ # Analytics +│ └── agents/ # AI agents +└── test/ # Tests ``` -### Validate, build, and run +Each folder has an `index.ts` barrel that re-exports its metadata; those barrels +are imported into `objectstack.config.ts`. There is **no filename-suffix magic** — +metadata is wired in through those explicit imports, so `objectstack.config.ts` is +the one place that tells you what's actually in the app. -```bash -os validate # Check schema correctness -os compile # Generate production artifact → dist/objectstack.json -os start # Boot from the compiled artifact (no config file needed) -``` +## How you verify -The compiled `dist/objectstack.json` is a portable, self-describing deployment unit — see -[CLI → Source vs Artifact](/docs/getting-started/cli#source-vs-artifact) for details. +Reading the metadata is half of verification; running the app is the other half. +Two commands, both of which the agent runs for you but you can run yourself: - +```bash +os validate # the gate — schema + CEL predicates + widget bindings (no artifact) +os dev --ui # boot the app, then open http://localhost:3000/_console/ +``` -## Learning Path +`os validate` proves the metadata is *well-formed*; the **Console** at `/_console/` +proves it does what you *meant* — create a record, watch an action show/hide, +confirm the nav and filters. That visual check is the human's half of every build +loop. See [Validating Metadata](/docs/getting-started/validating-metadata) for what +the gate catches, and [Build with Claude Code](/docs/getting-started/build-with-claude-code) +for the full describe → author → validate → verify cycle. -Follow these guides in order for the best experience: +## Go deeper - -## Project Structure - -A typical ObjectStack application layout (`os init` scaffolds only the minimal core of this — see [Example Apps](/docs/getting-started/examples)): - -``` -my-app/ -├── objectstack.config.ts # App manifest + metadata wiring -├── package.json -├── tsconfig.json -├── src/ -│ ├── objects/ # Data models (required) -│ │ ├── index.ts # Barrel export -│ │ └── my_app_item.ts # Object definition -│ ├── actions/ # Buttons, batch operations -│ ├── flows/ # Automation logic -│ ├── apps/ # Navigation definitions -│ ├── dashboards/ # Analytics dashboards -│ ├── agents/ # AI agents -│ └── rag/ # RAG pipelines -└── test/ # Tests -``` - -**File naming conventions** (recommended, not enforced — `os g ` always emits `{name}.ts`, so rename as you prefer): -- **Object files:** `{name}.object.ts` or `{name}.ts` (one object per file) -- **Action files:** `{name}.actions.ts` -- **Flow files:** `{name}.flow.ts` -- **Barrel exports:** Each directory has an `index.ts` that re-exports everything. Metadata is wired into your app through these barrel imports in `objectstack.config.ts` — there is no filename-suffix discovery. - -## Key Concepts - -| Concept | Protocol | You Define | ObjectStack Provides | -| :--- | :--- | :--- | :--- | -| Data Model | ObjectQL | Objects, Fields, Validation | CRUD APIs, database schema, type safety | -| User Interface | ObjectUI | Views, Apps, Dashboards | React components, navigation, responsive layout | -| Business Logic | Automation | Flows, Workflows, Triggers | Event handlers, approval chains, scheduled jobs | -| Access Control | Security | Profiles, Permissions, Sharing | Middleware, RLS policies, field masking | -| Intelligence | AI | Agents, RAG, Models | Chat interfaces, search indexes, predictions | - -## Next Steps +## Next steps -- [Example Apps](/docs/getting-started/examples) — Run the Todo, CRM, and BI examples -- [Data Modeling Guide](/docs/data-modeling) — Deep dive into objects and fields +- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — Build a real app end-to-end with an agent +- [Example Apps](/docs/getting-started/examples) — Run the Todo, CRM, and showcase examples - [CLI Reference](/docs/getting-started/cli) — All available commands - [Protocol Reference](/docs/references) — Complete schema documentation diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 389830bcef..013a8f6b64 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -5,14 +5,33 @@ description: Technical documentation for ObjectStack. # ObjectStack Documentation -ObjectStack is an AI-native business backend protocol for structured, auditable business applications. You author your application — data model, logic, permissions, and UI — as typed metadata in TypeScript (`defineStack()`), compile it to a self-contained artifact (`objectstack.json`), and the runtime derives everything else: the database schema on interchangeable drivers, a generated REST + realtime API, permission-checked automation, and server-driven UI. AI agents act through the same typed, permission-aware surface — never through raw SQL or scraped UI. Every engine (SQL, React, MCP) is a consumer of the same source of truth. +ObjectStack is an **AI-native business backend protocol** for structured, auditable +business applications. The way you build it: **an AI agent (Claude Code) authors your +application as typed metadata — data model, logic, permissions, UI — a validation gate +rejects mistakes that would fail silently at runtime, and you verify the result in a +visual Console.** From that one source of truth the runtime derives everything else — the +database schema on interchangeable drivers, a generated REST + realtime API, +permission-checked automation, server-driven UI, and an **MCP server**, so the app you +build is itself AI-operable. Agents act through the same typed, permission-aware surface — +never raw SQL or scraped UI. + +```mermaid +flowchart LR + A["Describe
in plain language"] --> B["Claude Code authors
typed metadata"] + B --> G{"os validate
the gate"} + G -->|fails| B + G -->|passes| V["You verify in
the Console"] + V -->|iterate| A + V -->|ship| M["MCP — your app
is AI-operable"] +``` ## Start here +- [Build with Claude Code](/docs/getting-started/build-with-claude-code) — the main workflow: an agent builds the app, you verify it in the Console +- [How AI Development Works](/docs/getting-started/how-ai-development-works) — why AI-builds / human-verifies is fast and safe - [What is ObjectStack?](/docs/getting-started) — the protocol model and runtime layers -- [Quick Start](/docs/getting-started/quick-start) — create an app and run the Console locally - [Core Concepts](/docs/concepts) — the ideas behind metadata-driven development -- [Architecture](/docs/concepts/architecture) — how ObjectQL, ObjectOS, and ObjectUI fit together +- [Architecture](/docs/concepts/architecture) — how the runtime turns your metadata into a database, API, UI, and MCP surface ## Platform modules diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json index 24ee2654d9..5a47c4b7ed 100644 --- a/content/docs/ui/meta.json +++ b/content/docs/ui/meta.json @@ -1,6 +1,6 @@ { "title": "UI Engine", - "icon": "Layout", + "icon": "LayoutDashboard", "pages": [ "index", "apps",