@vibesdotdev/docs 0.0.0-stage → 1.0.0-rc.3

package/dist/docs/getting-started.docs.descriptor.js

@@ -0,0 +1,63 @@
+const gettingStartedMarkdown = `---
+title: Getting Started
+summary: What vibes is, the core mental model, and your first working code
+tags: [getting-started, introduction, overview, concepts]
+order: -10
+---
+
+# Getting Started
+
+Vibes is a **runtime-first** platform: every capability — AI generation, storage, auth, tools,
+integrations — is published as a **descriptor** of a **kind** and resolved at use time through a
+shared **runtime**, rather than imported directly. Learn that one idea and the whole suite becomes
+predictable.
+
+\`\`\`ts
+import { getVibesAIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesAIClient(runtime); // resolves runtime/client#ai on the handed runtime
+\`\`\`
+
+## Start here
+
+:::card{title="New to vibes?"}
+1. [Core concepts](getting-started.concepts) — the five words you need: runtime, descriptor, kind, scope, resolve.
+2. [Your first query](getting-started.first-query) — resolve and call a capability, hands-on.
+3. [Build a real app](tutorials.build-an-app) — wire a SvelteKit app on the runtime end-to-end.
+:::
+
+## Choose your path
+
+:::card{title="What are you here to do?"}
+- **Building an app** — compose existing capabilities. Start with [AI](ai), [Chat](chat), [Storage](storage), [Auth](auth), and the [Tutorials](tutorials).
+- **Extending the platform** — publish your own capabilities. Read [Core concepts](getting-started.concepts), then [Runtime](runtime) and [Build a runtime plugin](tutorials.runtime-plugin).
+- **Operating & deploying** — run the system. See [PM](pm), [Workers](workers), [CLI](cli), [Secrets](secrets), and [Logging](logging).
+:::
+
+## Why runtime-first?
+
+Direct imports bind you to one implementation at build time. Resolving by kind lets the same
+application code run against different implementations depending on **hardware** (local \`consumer\`
+vs \`cloud\`), **surface** (cli / web / in-app), and **scope** (the active account, org, or project) —
+without changing the call site. That is the platform's core idea; everything else is an instance of it.
+
+## Related
+
+- [\`runtime.query\`](runtime.query) — the resolution API in full
+- [\`runtime.plugins\`](runtime.plugins) — how capabilities are registered
+- [\`app.config\`](app.config) — the per-app \`vibes.config.ts\` manifest
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'getting-started',
+    title: 'Getting Started',
+    summary: 'What vibes is, the core mental model, and your first working code',
+    body: { type: 'markdown', sourceType: 'raw', source: gettingStartedMarkdown },
+    order: -10,
+    tags: ['getting-started', 'introduction', 'overview', 'concepts'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=getting-started.docs.descriptor.js.map

package/dist/docs/getting-started.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/getting-started.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgD9B,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,mEAAmE;IAC5E,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE;IAC7E,KAAK,EAAE,CAAC,EAAE;IACV,IAAI,EAAE,CAAC,iBAAiB,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,CAAC;IACjE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/getting-started.first-query.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=getting-started.first-query.docs.descriptor.d.ts.map

package/dist/docs/getting-started.first-query.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.first-query.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/getting-started.first-query.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAmFvE,QAAA,MAAM,UAAU,EAAE,mBAYjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/getting-started.first-query.docs.descriptor.js

@@ -0,0 +1,95 @@
+const firstQueryMarkdown = `---
+title: Your first query
+summary: Resolve a canonical runtime client and call it, then learn the lower-level query API
+tags: [getting-started, runtime, query, tutorial]
+parent: getting-started
+order: 2
+---
+
+# Your first query
+
+Application code starts with a domain's canonical runtime client. The client resolves its underlying
+descriptors through the runtime, preserving scope and implementation selection without exposing that
+plumbing at every call site.
+
+## 1. Get the canonical client
+
+\`\`\`ts
+import { getVibesAIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesAIClient(runtime); // resolves runtime/client#ai on the handed runtime
+\`\`\`
+
+## 2. Call it
+
+\`\`\`ts
+const response = await ai.text({
+  messages: [{ role: 'user', content: 'Hello, vibes.' }]
+});
+console.log(response.content);
+\`\`\`
+
+The client owns the stable public API. Internally it resolves the eligible \`ai/generation\`
+implementation for the current scope; application code does not select that executor directly.
+
+## 3. Use the lower-level query API for platform infrastructure
+
+Runtime/plugin code can query kinds directly. Get the runtime, then chain filters before terminating:
+
+\`\`\`ts
+// \`runtime\` is the VibesRuntime you were handed: \`context.runtime\` in a tool, command or job, or the plugin's \`RuntimeRef\`.
+\`\`\`
+
+The filters compose:
+
+\`\`\`ts
+// a specific implementation by id
+const fsRead = await runtime.query('tools/tool').withId('fs-read').resolve();
+
+// the adapter that fits a target environment
+const adapter = await runtime.query('storage/adapter').forHardware('cloud').first();
+\`\`\`
+
+## 4. List without loading
+
+\`.descriptors()\` returns metadata only — no implementation code is imported. Use it to enumerate
+what's available (this is how tool pickers and the docs sidebar are built):
+
+\`\`\`ts
+const tools = runtime.query('tools/tool').descriptors();
+for (const t of tools) console.log(t.id, t.title);
+\`\`\`
+
+## The shape to remember
+
+\`\`\`
+runtime.query(<kind>)
+  .withId(id) | .withTag(tag) | .forHardware('consumer'|'cloud') | .matching(scope)   // narrow (optional)
+  .first() | .resolve()      // → one implementation (loads code)
+  .descriptors()             // → metadata only (no code)
+\`\`\`
+
+That's the lower-level contract behind every canonical client and plugin. Product code prefers the
+domain client; platform code uses \`runtime.query\` when composing or implementing capabilities.
+
+## Next
+
+- [Build a real app](tutorials.build-an-app) — put this in a running SvelteKit app
+- [Generate text with an AI provider](tutorials.ai-text-generation) — go deeper on \`ai/generation\`
+- [\`runtime.query\`](runtime.query) — every filter and terminator
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'getting-started.first-query',
+    title: 'Your first query',
+    summary: 'Resolve a canonical runtime client and call it, then learn the lower-level query API',
+    body: { type: 'markdown', sourceType: 'raw', source: firstQueryMarkdown },
+    parent: 'getting-started',
+    order: 2,
+    tags: ['getting-started', 'runtime', 'query', 'tutorial'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=getting-started.first-query.docs.descriptor.js.map

package/dist/docs/getting-started.first-query.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.first-query.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/getting-started.first-query.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+E1B,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,6BAA6B;IACjC,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,sFAAsF;IAC/F,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE;IACzE,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,iBAAiB,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC;IACzD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/guided-flows.flows.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Descriptor for guided-flows.flows
+ */
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    parent: string;
+    order: number;
+    tags: string[];
+    surfaces: readonly ["cli", "web", "in-app"];
+    hardware: readonly ["consumer"];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=guided-flows.flows.docs.descriptor.d.ts.map

package/dist/docs/guided-flows.flows.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guided-flows.flows.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/guided-flows.flows.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+FH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;CAgBf,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/guided-flows.flows.docs.descriptor.js

@@ -0,0 +1,114 @@
+/**
+ * Descriptor for guided-flows.flows
+ */
+const guidedFlowsFlowsMarkdown = `---
+title: Guided Flows
+summary: Onboarding and feature discovery flow engine with cloud-synced state
+tags: [guided-flows, onboarding, feature-discovery, ui, tours]
+parent: guided-flows
+order: 1
+id: guided-flows.flows
+---
+
+# Guided Flows
+
+\`@vibesdotdev/guided-flows\` provides the runtime client, Zod schemas, and storage manifest for guided onboarding and feature-discovery flows. A flow is a definition stored on the server (name, type, ordered steps); the client fetches definitions, reads the current user's execution state, and records progress over HTTP. Flow definitions, executions, and completions persist through the package's storage manifest.
+
+## What this provides
+
+- **Runtime client** — \`GuidedFlowsClient\` (a \`runtime/client\` extending \`BaseRuntimeClient\`) fetches flow definitions and user executions and writes progress/dismiss/complete/reset over HTTP.
+- **Schemas** — Zod schemas and inferred types for flow definitions, steps, completions, analytics, and the request/response payloads.
+- **Storage manifest** — \`guidedFlowsStorageDescriptor\` (namespace \`guided-flows.executions\`, \`ownerApp: 'account'\`) persists execution + completion state, syncing to \`/api/guided-flows\` via the cloud-api adapter.
+- **Plugin** — \`guidedFlowsPlugin\` registers the client + storage manifest with the runtime.
+
+## Public exports
+
+\`\`\`ts
+import {
+  GuidedFlowsClient,
+  type GuidedFlowsHttpOverrides,
+  guidedFlowsStorageDescriptor,
+  type GuidedFlowsState,
+  guidedFlowsPlugin
+} from '@vibesdotdev/guided-flows';
+\`\`\`
+
+Schema types (\`FlowDefinition\`, \`StepDefinition\`, \`FlowCompletion\`, \`FlowExecutionsResponse\`, \`SaveProgressRequest\`, \`DismissFlowRequest\`, \`CompleteFlowRequest\`, \`ResetFlowRequest\`, and others) are also re-exported from the package root.
+
+## Client API
+
+\`GuidedFlowsClient\` is HTTP-backed. Use \`configureHttp\` to point it at a base URL (and optionally inject \`fetch\`/\`headers\`); the default base URL is empty, so requests resolve against the current origin.
+
+\`\`\`ts
+import { GuidedFlowsClient } from '@vibesdotdev/guided-flows';
+
+const client = new GuidedFlowsClient();
+client.configureHttp({ baseUrl: 'https://system.vibes.dev' });
+
+// Read definitions and the active user's execution state
+const flows = await client.fetchFlowDefinitions();          // FlowDefinition[]
+const onboarding = await client.fetchFlowById('onboarding'); // FlowDefinition | null
+const executions = await client.fetchUserExecutions();       // FlowExecutionsResponse
+
+// Record progress for a step
+await client.saveProgress({
+  flowId: 'onboarding',
+  stepId: 'connect-storage',
+  status: 'completed' // 'completed' | 'skipped'
+});
+
+// Lifecycle
+await client.dismissFlow({ flowId: 'onboarding', reason: 'not-now' });
+await client.completeFlow({ flowId: 'onboarding' });
+await client.resetFlow({ flowId: 'onboarding' }); // omit the arg to reset all
+
+// Analytics
+await client.trackEvent({ flowId: 'onboarding', event: 'viewed' });
+\`\`\`
+
+| Method | Returns | Endpoint |
+| --- | --- | --- |
+| \`fetchFlowDefinitions()\` | \`FlowDefinitionData[]\` | GET \`/api/guided-flow-definitions\` |
+| \`fetchFlowById(id)\` | \`FlowDefinitionData | null\` | (filters definitions client-side) |
+| \`fetchUserExecutions()\` | \`FlowExecution[]\` | GET \`/api/guided-flows\` |
+| \`saveProgress(request)\` | \`void\` | PATCH \`/api/guided-flows/{flowId}\` |
+| \`dismissFlow(request)\` | \`void\` | POST \`/api/guided-flows/{flowId}/dismiss\` |
+| \`completeFlow(request)\` | \`void\` | POST \`/api/guided-flows/{flowId}/complete\` |
+| \`resetFlow(request?)\` | \`void\` | DELETE \`/api/guided-flows[/{flowId}]\` |
+| \`trackEvent(event)\` | \`void\` | POST \`/api/guided-flow-analytics\` |
+
+## Flow definitions
+
+A \`FlowDefinition\` (validated by \`flowDefinitionSchema\`) carries an \`id\`, \`name\`, \`slug\`, a \`type\` (\`'onboarding' | 'admin-config' | 'feature-intro' | 'system-health'\`), and an ordered array of \`steps\`. Each \`StepDefinition\` has an \`id\`, \`title\`, optional \`description\`, an optional \`type\` (\`'form' | 'selection' | 'configuration' | 'confirmation' | 'intro' | 'success'\`), \`required\`/\`skippable\` flags, and an optional \`highlight\` config. Definitions may also set \`priority\`, \`dependencies\`, \`targetRole\`, \`dismissible\`, \`persistence\` (\`'db' | 'session' | 'local'\`), and \`userTypes\`.
+
+## Storage manifest
+
+\`guidedFlowsStorageDescriptor\` declares namespace \`guided-flows.executions\` with a \`GuidedFlowsState\` shape (\`executions\`, \`completions\`, \`activeFlowId\`, \`activeStepId\`). It allows the \`storage.json\`, \`storage.localdb\`, \`storage.cloud-api\`, and \`storage.memory\` adapters (default \`storage.json\`), and its cloud-api config syncs to \`/api/guided-flows\` under \`ownerApp: 'account'\`.
+
+## Svelte surface
+
+The companion \`@vibesdotdev/guided-flows/svelte\` package provides the rendering layer: a \`guidedFlowsState\` singleton, a non-visual \`<GuidedFlowsLoader />\`, the orchestrating \`<GuidedFlowsHost />\`, plus \`<GuidedFlowsRenderer />\`, \`<FlowStepNav />\`, and \`<FlowProgressBar />\`.
+
+## CLI
+
+Guided flows is consumed programmatically from app surfaces — there are no dedicated CLI commands.
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'guided-flows.flows',
+    title: 'Guided Flows',
+    summary: 'Onboarding and feature discovery flow engine with cloud-synced state',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: guidedFlowsFlowsMarkdown
+    },
+    parent: 'guided-flows',
+    order: 1,
+    tags: ['guided-flows', 'onboarding', 'feature-discovery', 'ui', 'tours'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=guided-flows.flows.docs.descriptor.js.map

package/dist/docs/guided-flows.flows.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guided-flows.flows.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/guided-flows.flows.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2FhC,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,sEAAsE;IAC/E,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,wBAAwB;KACjC;IACD,MAAM,EAAE,cAAc;IACtB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,IAAI,EAAE,OAAO,CAAC;IACxE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAU;IAC3C,QAAQ,EAAE,CAAC,UAAU,CAAU;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runtime-rpc-relay.docs.descriptor.d.ts

@@ -0,0 +1,19 @@
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    parent: string;
+    order: number;
+    tags: string[];
+    surfaces: readonly ["web", "in-app"];
+    hardware: readonly ["consumer", "cloud"];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=runtime-rpc-relay.docs.descriptor.d.ts.map

package/dist/docs/runtime-rpc-relay.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-rpc-relay.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/runtime-rpc-relay.docs.descriptor.ts"],"names":[],"mappings":"AAAA,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;CA0If,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/runtime-rpc-relay.docs.descriptor.js

@@ -0,0 +1,140 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'runtime.rpc.relay',
+    title: 'Runtime RPC — Relay Transport',
+    summary: 'Reach a fleet daemon behind NAT via a Cloudflare Durable Object broker. The daemon dials out over WebSocket; the consumer reaches it via HTTP. The L5 authz/friction pipeline fires on every invoke by construction.',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Runtime RPC — Relay Transport
+summary: Reach a fleet daemon behind NAT via a Cloudflare Durable Object broker. The daemon dials out over WebSocket; the consumer reaches it via HTTP.
+tags: [runtime, rpc, relay, fleet, websocket, durable-objects]
+parent: runtime.rpc
+order: 4
+surfaces: [web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Runtime RPC — Relay Transport
+
+The \`relay\` transport is a fourth \`runtime/rpc\` transport that routes through a
+Cloudflare **Durable Object broker** (\`HostRelay\`), solving the NAT-traversal problem
+for home fleet machines. The daemon dials **out** to the broker over a WebSocket;
+the worker consumer reaches the daemon through the broker's HTTP endpoints.
+
+Everything above the transport layer — \`execution.session()\`, the terminal component,
+\`.on(hostRef)\`, the L5 authz/friction gates — is unchanged.
+
+## Design
+
+\`\`\`
+  home machine                     platform.vibes.dev (worker + DO)
+ ┌─────────────┐   wss outbound   ┌───────────────────────────────┐
+ │ fleet daemon│ ───────────────► │ /api/relay/connect?hostId=<id>│
+ │  (loopback) │  Bearer host_…   │   HostRelay DO instance       │
+ │ runtime/exec│ ◄══ duplex ════► │   (CF WebSocket Hibernation)  │
+ └─────────────┘   RPC frames     └───────────────────────────────┘
+                                              ▲
+                                    POST /api/relay/rpc?hostId
+                                    GET  /api/relay/stream?hostId
+                                              │
+                                   ┌──────────────────┐
+                                   │ hq-web worker    │
+                                   └──────────────────┘
+\`\`\`
+
+## Descriptor
+
+\`\`\`ts
+{
+  kind: 'runtime/rpc',
+  transport: 'relay',
+  target: {
+    transport: 'relay',
+    brokerOrigin: 'https://platform.vibes.dev',
+    hostId: 'the-daemons-host-id'
+  },
+  auth: { source: 'secret', key: 'HOST_TOKEN' }  // durable host-token
+}
+\`\`\`
+
+## Wire format
+
+| Message          | Direction              | Encoding                                      |
+|------------------|------------------------|-----------------------------------------------|
+| RpcRequest       | consumer→broker→daemon | JSON text: \`{type:'rpc_request',consumerId,request}\` |
+| RpcResponse      | daemon→broker→consumer | JSON text: \`{type:'rpc_response',consumerId,response}\` |
+| Stream DATA      | bidirectional          | Binary: \`[36-byte channelId][0x00][payload]\` |
+| Stream CLOSE     | bidirectional          | Binary: \`[36-byte channelId][0x01]\`         |
+
+## Security
+
+1. **Connect auth ≠ invoke authz.** The host-token WS upgrade authenticates the socket only.
+   Every \`RpcRequest\` at the daemon passes the L5 pipeline (\`authz → friction\`).
+2. **Host-binding.** A token for host A opens only A's DO instance.
+3. **Reverse leg supported.** Unlike the http transport, the duplex WS supports callback
+   refs — \`RPC_NO_REVERSE_CHANNEL\` is never raised on relay.
+
+## Usage
+
+\`\`\`ts
+import { createFleetRegistryBridgePlugin, toDiscoveredEntry } from '@vibesdotdev/platform/fleets';
+import { createRelayRpcDescriptor } from '@vibesdotdev/kernel-rpc/relay';
+
+const descriptor = createRelayRpcDescriptor(
+  'https://platform.vibes.dev',
+  hostId,
+  'my-home-mac',
+  { source: 'secret', key: 'HOST_TOKEN' }
+);
+
+registry.register(toDiscoveredEntry('fleet/discovery/platform', descriptor));
+const bridge = createFleetRegistryBridgePlugin({
+  registry,
+  credentialResolution: { environment: 'production', secretsStore }
+});
+\`\`\`
+
+The bridge projects relay and HTTP registry entries into \`runtime/rpc\`. For a
+specialized host that registers a descriptor directly, import
+\`registerRelayRpcLoader\` or \`registerDynamicRelayRpcAsset\` from
+\`@vibesdotdev/kernel-rpc/relay\`; both are the same loader values the bridge
+uses for relay identities.
+
+The daemon side wires the adapter in \`startFleetDaemon\`:
+
+\`\`\`ts
+import { createRelayServerAdapter } from '@vibesdotdev/kernel-rpc/relay';
+
+// ws is a CF WebSocket from acceptWebSocket()
+const adapter = createRelayServerAdapter({
+  socket: ws,          // RelaySocket interface
+  root: daemonRoot,
+  pipeline,            // L5 pipeline — required, wires authz/friction by construction
+  lifecycle: runtime.lifecycle, // bounds and cancels the handshake (RC07)
+  classifyResult,
+  bindChannel
+});
+// Register adapter.rootRef with the broker.
+\`\`\`
+
+## Code paths
+
+- Package: \`runtime-rpc-relay/\`
+- Wire constants: \`src/wire.ts\`
+- Consumer connection: \`src/relay-connection.ts\`
+- Daemon server adapter + relay-listen-session: \`src/relay-transport.impl.ts\`, \`src/relay-listen-session.ts\`
+- Loader registration helpers: \`src/relay-rpc-loader.ts\`
+- Descriptor helper: \`src/descriptors/relay.rpc.descriptor.ts\`
+`
+    },
+    parent: 'runtime.rpc',
+    order: 4,
+    tags: ['runtime', 'rpc', 'relay', 'fleet', 'websocket', 'durable-objects'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=runtime-rpc-relay.docs.descriptor.js.map

package/dist/docs/runtime-rpc-relay.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-rpc-relay.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/runtime-rpc-relay.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,mBAAmB;IACvB,KAAK,EAAE,+BAA+B;IACtC,OAAO,EACN,sNAAsN;IACvN,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyHT;KACC;IACD,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,CAAC;IAC1E,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAU;IACpC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IACxC,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.ai-text-generation.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=tutorials.ai-text-generation.docs.descriptor.d.ts.map

package/dist/docs/tutorials.ai-text-generation.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.ai-text-generation.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/tutorials.ai-text-generation.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAmGvE,QAAA,MAAM,UAAU,EAAE,mBAiBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.ai-text-generation.docs.descriptor.js

@@ -0,0 +1,115 @@
+const aiTextGenMarkdown = `---
+title: Generate text with an AI provider
+summary: Generate and stream text through the canonical AI runtime client, locally or in the cloud
+tags: [tutorial, ai, generation, streaming, lmstudio, anthropic]
+parent: tutorials
+order: 2
+---
+
+# Generate text with an AI provider
+
+AI generation in vibes goes through the canonical AI runtime client, not a provider SDK or a raw
+executor selected by application code. The client resolves the eligible \`ai/generation\`
+implementation for the current scope. The same call site can run locally or in the cloud.
+
+## 1. Resolve the canonical client
+
+:::usage{language="ts"}
+import { getVibesAIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesAIClient(runtime); // the runtime your context was handed
+:::
+
+## 2. One-shot generation
+
+The request carries a \`messages\` array. \`temperature\`, \`maxTokens\`, \`topP\`,
+\`stopSequences\`, and \`tools\` are optional; the client supplies the text modality.
+
+:::usage{language="ts"}
+const response = await ai.text({
+  messages: [{ role: 'user', content: 'Explain the vibes runtime in one sentence.' }],
+  maxTokens: 512,
+  temperature: 0.7
+});
+
+console.log(response.content);
+:::
+
+## 3. Streaming
+
+\`stream()\` returns an async generator of \`StreamEvent\`s. Each event has a \`type\` —
+\`'chunk'\` carries incremental \`content\`; \`'tool_call'\`, \`'thinking'\`, \`'error'\`, and \`'done'\` mark
+other phases. Pass a \`surface\` so usage is attributed correctly:
+
+:::usage{language="ts"}
+const stream = ai.stream(
+  {
+    modality: 'text',
+    messages: [{ role: 'user', content: 'Write a haiku about edge runtimes.' }]
+  },
+  { surface: 'cli' }
+);
+
+for await (const event of stream) {
+  if (event.type === 'chunk') process.stdout.write(event.content);
+  else if (event.type === 'error') console.error(event.error.message);
+}
+:::
+
+## 4. Choose a model
+
+Model ids are colon-namespaced as \`provider:model\`. Catalog defaults ship in
+\`ai-metadata/src/provider-models\`:
+
+| Model id | Provider | Notes |
+|---|---|---|
+| \`anthropic:claude-opus-4-7\` | Anthropic | Highest capability |
+| \`anthropic:claude-sonnet-4-6\` | Anthropic | Balanced default |
+| \`anthropic:claude-haiku-4-5\` | Anthropic | Fast / cheap |
+| \`digitalocean:claude-opus-4-7\` | DigitalOcean Gradient | Cloud-hosted Claude |
+| \`lmstudio:llama-3.1-8b-instruct\` | LM Studio | Runs on your machine |
+
+## 5. Run it locally with LM Studio
+
+For local development, the \`ai-provider-lmstudio\` provider talks to LM Studio's OpenAI-compatible
+server (default \`http://localhost:1234/v1\`). Compose and configure that provider in the runtime;
+the application call stays identical and no cloud key is required:
+
+:::usage{language="ts"}
+const response = await ai.text({
+  messages: [{ role: 'user', content: 'Hello from my laptop.' }]
+});
+:::
+
+The CLI exercises this same path:
+
+:::shell
+vibes ai ask 'Summarize this repo'
+:::
+
+## Related
+
+- [\`ai.generation\`](ai.generation) — the generation executor API
+- [\`ai.streaming\`](ai.streaming) — streaming events in detail
+- [\`ai.models\`](ai.models) — the model registry and descriptors
+- [\`ai.providers\`](ai.providers) — registering and configuring providers
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tutorials.ai-text-generation',
+    title: 'Generate text with an AI provider',
+    summary: 'Generate and stream text through the canonical AI runtime client, locally or in the cloud',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: aiTextGenMarkdown
+    },
+    parent: 'tutorials',
+    order: 2,
+    tags: ['tutorial', 'ai', 'generation', 'streaming', 'lmstudio', 'anthropic'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=tutorials.ai-text-generation.docs.descriptor.js.map

package/dist/docs/tutorials.ai-text-generation.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.ai-text-generation.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/tutorials.ai-text-generation.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+FzB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,8BAA8B;IAClC,KAAK,EAAE,mCAAmC;IAC1C,OAAO,EACN,2FAA2F;IAC5F,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,iBAAiB;KACzB;IACD,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,CAAC;IAC5E,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.build-an-app.docs.descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+declare const descriptor: DocsTopicDescriptor;
+export default descriptor;
+//# sourceMappingURL=tutorials.build-an-app.docs.descriptor.d.ts.map

package/dist/docs/tutorials.build-an-app.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.build-an-app.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/tutorials.build-an-app.docs.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AA4JvE,QAAA,MAAM,UAAU,EAAE,mBAiBjB,CAAC;AAEF,eAAe,UAAU,CAAC"}