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

package/dist/docs/tutorials.build-an-app.docs.descriptor.js

@@ -0,0 +1,172 @@
+const buildAnAppMarkdown = `---
+title: Build a real app
+summary: Scaffold a SvelteKit app on the vibes runtime with the VibesKit AppShell and a runtime-backed chat surface
+tags: [tutorial, app, vibeskit, runtime, sveltekit, chat]
+parent: tutorials
+order: 1
+---
+
+# Build a real app
+
+This walks through a complete vibes app: a SvelteKit project wired to the runtime, wrapped in the
+VibesKit \`AppShell\`, with a runtime-backed chat surface dropped in. The fastest start is to copy the
+canonical template at \`apps/vibes-app-template\` and rename it — everything below describes the wiring
+that template already contains.
+
+## 1. Project shape
+
+A vibes app is a normal SvelteKit app plus three things: a Vite config from the SvelteKit surface, a
+\`vibes.config.ts\` plugin manifest, and server hooks. Dependencies (from the template's
+\`package.json\`):
+
+:::install{package="@vibesdotdev/kit @vibesdotdev/kernel @vibesdotdev/surface-sveltekit"}
+:::
+
+## 2. Vite config — mount the runtime surface
+
+\`createAppViteConfig\` registers the SvelteKit runtime surface (SSR + client) and dev hosts for your slug.
+
+:::usage{language="ts"}
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { createAppViteConfig } from '@vibesdotdev/surface-sveltekit/vite';
+
+export default defineConfig(
+  createAppViteConfig({
+    slug: 'template',
+    extraHosts: ['app-template.vibes.local']
+  })
+);
+:::
+
+## 3. Server hooks
+
+Compose the standard server handles. They come from \`@vibesdotdev/kit/server\` and are chained with
+SvelteKit's \`sequence\`:
+
+:::usage{language="ts"}
+// src/hooks.server.ts
+import { sequence } from '@sveltejs/kit/hooks';
+import {
+  applySecurityHeaders,
+  createCacheControlHandle,
+  createCorsHandle
+} from '@vibesdotdev/kit/server';
+
+export const handle = sequence(
+  applySecurityHeaders(),
+  createCacheControlHandle(),
+  createCorsHandle()
+);
+:::
+
+## 4. Wrap the layout in AppShell
+
+\`AppShell\` (from \`@vibesdotdev/kit/components/app-shell\`) renders the sidebar, header, app switcher,
+and the scroll container. Pass your \`appId\`, the current \`pathname\`, your sidebar \`navigation\`, and the
+loaded \`user\`:
+
+:::usage{language="svelte"}
+<!-- src/routes/app/+layout.svelte -->
+<script lang="ts">
+  import { AppShell } from '@vibesdotdev/kit/components/app-shell';
+  import {
+    AppCommandPalette,
+    AppCommandPaletteTrigger
+  } from '@vibesdotdev/command-palette/svelte';
+  import { page } from '$app/state';
+
+  let { data, children } = $props();
+
+  const navigation = [
+    { title: 'Overview', items: [{ id: 'home', label: 'Home', href: '/app' }] }
+  ];
+</script>
+
+<AppShell
+  appId="template"
+  appLabel="Template"
+  appIcon="lucide:layout-template"
+  pathname={page.url.pathname}
+  {navigation}
+  user={data?.user}
+  signInHref="/auth/signin"
+  signOutHref="/auth/signout"
+>
+  {#snippet headerActions()}
+    <AppCommandPaletteTrigger appId="template" />
+  {/snippet}
+  <AppCommandPalette appId="template" pages={[]} actions={[]} />
+  {@render children()}
+</AppShell>
+:::
+
+The shell owns the scrollable \`#main-content\` region and resets it on navigation — render your page
+content directly as the children; you do not need to add your own scroll container.
+
+## 5. Declare your plugins
+
+\`vibes.config.ts\` is the per-app manifest of runtime plugins, loaded lazily. Add only what your app
+uses; the runtime resolves capabilities from these at boot:
+
+:::usage{language="ts"}
+// vibes.config.ts
+import type { VibesAppConfig } from '@vibesdotdev/kernel/config';
+
+export default {
+  plugins: [
+    () => import('@vibesdotdev/kernel/context/context.plugin'),
+    () => import('@vibesdotdev/kernel/client/plugin')
+    // add capability plugins here (ai, chat, storage, integrations, …)
+  ]
+} satisfies VibesAppConfig;
+:::
+
+## 6. Drop in a runtime-backed chat surface
+
+\`@vibesdotdev/chat/svelte\` renders a chat UI that talks to the runtime. Mount the loader inside a
+route that has the runtime Svelte context available:
+
+:::usage{language="svelte"}
+<!-- src/routes/app/chat/+page.svelte -->
+<script lang="ts">
+  import { ChatLoader } from '@vibesdotdev/chat/svelte';
+</script>
+
+<ChatLoader />
+:::
+
+## Run it
+
+:::shell
+vibes pm start template-dev
+:::
+
+Then open your dev host (e.g. \`https://app-template.vibes.local\`).
+
+## Related
+
+- [\`app.config\`](app.config) — the \`vibes.config.ts\` plugin manifest in depth
+- [\`runtime.plugins\`](runtime.plugins) — how plugins register and resolve capabilities
+- [\`tutorials.ai-text-generation\`](tutorials.ai-text-generation) — add AI generation to your app
+- [\`tutorials.runtime-plugin\`](tutorials.runtime-plugin) — author your own capability plugin
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tutorials.build-an-app',
+    title: 'Build a real app',
+    summary: 'Scaffold a SvelteKit app on the vibes runtime with the VibesKit AppShell and a runtime-backed chat surface',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: buildAnAppMarkdown
+    },
+    parent: 'tutorials',
+    order: 1,
+    tags: ['tutorial', 'app', 'vibeskit', 'runtime', 'sveltekit', 'chat'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=tutorials.build-an-app.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.build-an-app.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/tutorials.build-an-app.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwJ1B,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,wBAAwB;IAC5B,KAAK,EAAE,kBAAkB;IACzB,OAAO,EACN,4GAA4G;IAC7G,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,kBAAkB;KAC1B;IACD,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,CAAC;IACrE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.crud-collection.docs.descriptor.d.ts

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

package/dist/docs/tutorials.crud-collection.docs.descriptor.d.ts.map

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

package/dist/docs/tutorials.crud-collection.docs.descriptor.js

@@ -0,0 +1,142 @@
+const crudMarkdown = `---
+title: Cloud-backed CRUD collection
+summary: Stand up typed list/create/update/delete routes over a storage transform with vibesCrudCollection
+tags: [tutorial, crud, storage, kit, server, routes]
+parent: tutorials
+order: 3
+---
+
+# Cloud-backed CRUD collection
+
+\`vibesCrudCollection\` (from \`@vibesdotdev/kit/server/crud\`) turns a storage-backed resource into a
+set of SvelteKit route handlers — list, create, read, update, delete — with auth and validation hooks
+wired in. You supply how to fetch and persist; it supplies the HTTP surface and a typed JSON contract.
+
+## 1. The wire contract
+
+A collection produces these endpoints and response shapes:
+
+| Method | Route | Response |
+|---|---|---|
+| \`GET\` | \`/api/<resource>\` | \`{ results: T[] }\` |
+| \`POST\` | \`/api/<resource>\` | \`{ result: T }\` |
+| \`GET\` | \`/api/<resource>/[id]\` | \`{ result: T }\` |
+| \`PATCH\` | \`/api/<resource>/[id]\` | \`{ result: T }\` |
+| \`DELETE\` | \`/api/<resource>/[id]\` | \`204 No Content\` |
+
+## 2. Define the collection
+
+Point it at a \`storageDescriptorId\` (the storage transform that maps stored rows to API shape) and
+give each operation an auth guard plus a data function. \`quick.auth()\` applies the standard
+authenticated-actor guard. Each callback receives \`(event, context)\`; validated input is read from
+\`context.validated!.body | query | params\`:
+
+:::usage{language="ts"}
+// src/routes/api/widgets/+server.ts
+import { vibesCrudCollection, quick } from '@vibesdotdev/kit/server/crud';
+import { db, widgets } from '$lib/server/db';
+import { widgetCreateSchema, type WidgetCreate } from '$lib/schemas';
+
+const { GET, POST } = vibesCrudCollection({
+  storageDescriptorId: 'app.widgets',
+  list: {
+    ...quick.auth(),
+    fetch: async (event) =>
+      db.query.widgets.findMany({ where: ownedBy(event.locals.actor) })
+  },
+  create: {
+    ...quick.auth(),
+    validation: { body: widgetCreateSchema },
+    insert: async (event, context) => {
+      const body = context.validated!.body as WidgetCreate;
+      const [row] = await db
+        .insert(widgets)
+        .values({ ...body, ownerId: event.locals.actor.id })
+        .returning();
+      return row;
+    }
+  }
+});
+
+export { GET, POST };
+:::
+
+## 3. The item route
+
+\`vibesCrudItem\` mounts the per-id handlers under \`[id]\` — \`get.fetch\` returns the row or \`null\`
+(the helper sends a 404), \`update.patch\` applies a partial update, and \`delete.remove\` erases it:
+
+:::usage{language="ts"}
+// src/routes/api/widgets/[id]/+server.ts
+import { vibesCrudItem, quick } from '@vibesdotdev/kit/server/crud';
+import { db, widgets, eq } from '$lib/server/db';
+import { widgetUpdateSchema, type WidgetUpdate } from '$lib/schemas';
+
+const { GET, PATCH, DELETE } = vibesCrudItem({
+  storageDescriptorId: 'app.widgets',
+  get: {
+    ...quick.auth(),
+    fetch: (event) =>
+      db.query.widgets.findFirst({ where: eq(widgets.id, event.params.id) }) ?? null
+  },
+  update: {
+    ...quick.auth(),
+    validation: { body: widgetUpdateSchema },
+    patch: async (event, context) => {
+      const body = context.validated!.body as WidgetUpdate;
+      const [row] = await db
+        .update(widgets)
+        .set(body)
+        .where(eq(widgets.id, event.params.id))
+        .returning();
+      return row;
+    }
+  },
+  delete: {
+    ...quick.auth(),
+    remove: async (event) => {
+      await db.delete(widgets).where(eq(widgets.id, event.params.id));
+    }
+  }
+});
+
+export { GET, PATCH, DELETE };
+:::
+
+## 4. The storage transform
+
+\`storageDescriptorId\` resolves a storage transform from the runtime at first request — it maps stored
+rows (\`TRow\`) to the descriptor shape (\`TDescriptor\`) returned to clients, so persistence columns and
+API fields can differ. See [\`storage.transform\`](storage.transform) for declaring one.
+
+## 5. Lifecycle hooks
+
+Each operation accepts \`onBefore*\`/\`onAfter*\` hooks for validation side-effects, audit logging, or
+cache invalidation — e.g. \`onAfterCreate\` to enqueue a notification.
+
+## Related
+
+- [\`storage.transform\`](storage.transform) — map stored rows to API shape
+- [\`storage.records\`](storage.records) — the record storage protocol
+- [\`storage.adapters\`](storage.adapters) — where records are persisted
+- [\`app.apis\`](app.apis) — app route conventions
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tutorials.crud-collection',
+    title: 'Cloud-backed CRUD collection',
+    summary: 'Stand up typed list/create/update/delete routes over a storage transform with vibesCrudCollection',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: crudMarkdown
+    },
+    parent: 'tutorials',
+    order: 3,
+    tags: ['tutorial', 'crud', 'storage', 'kit', 'server', 'routes'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=tutorials.crud-collection.docs.descriptor.js.map

package/dist/docs/tutorials.crud-collection.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.crud-collection.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/tutorials.crud-collection.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0HpB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,2BAA2B;IAC/B,KAAK,EAAE,8BAA8B;IACrC,OAAO,EACN,mGAAmG;IACpG,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,YAAY;KACpB;IACD,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC;IAChE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.docs.descriptor.d.ts

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

package/dist/docs/tutorials.docs.descriptor.d.ts.map

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

package/dist/docs/tutorials.docs.descriptor.js

@@ -0,0 +1,52 @@
+const tutorialsMarkdown = `---
+title: Tutorials
+summary: End-to-end, copy-runnable guides for building on the vibes platform
+tags: [tutorials, guides, getting-started]
+order: 0
+---
+
+# Tutorials
+
+Task-focused, end-to-end guides that wire real vibes packages together. Every code sample on
+these pages is checked against the actual source — copy them as a starting point.
+
+:::card{title="Build something"}
+- [Build a real app](tutorials.build-an-app) — scaffold a SvelteKit app on the vibes runtime with the VibesKit AppShell and a runtime-backed chat surface.
+- [Generate text with an AI provider](tutorials.ai-text-generation) — resolve a generation executor and stream tokens, locally (LM Studio) or in the cloud.
+- [Cloud-backed CRUD collection](tutorials.crud-collection) — stand up typed list/create/update/delete routes over a storage transform with \`vibesCrudCollection\`.
+- [Understand OAuth integration](auth.oauth) — use the canonical authentication and provider authorization contract.
+- [Build a runtime plugin](tutorials.runtime-plugin) — register descriptors and lazy implementations and resolve them with \`runtime.query()\`.
+:::
+
+## How these fit together
+
+The vibes platform is **runtime-first**: capabilities are published as descriptors against a
+[runtime](runtime.query) and resolved by kind, not imported directly. Most tutorials follow the
+same shape — register a plugin, then query the runtime for what it exposes. Start with
+[Build a real app](tutorials.build-an-app) for the end-to-end picture, then drill into the
+capability you need.
+
+## Related
+
+- [\`runtime.query\`](runtime.query) — resolve capabilities by kind
+- [\`runtime.plugins\`](runtime.plugins) — how plugins register descriptors and implementations
+- [\`app.config\`](app.config) — the per-app \`vibes.config.ts\` plugin manifest
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tutorials',
+    title: 'Tutorials',
+    summary: 'End-to-end, copy-runnable guides for building on the vibes platform',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: tutorialsMarkdown
+    },
+    order: 0,
+    tags: ['tutorials', 'guides', 'getting-started'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=tutorials.docs.descriptor.js.map

package/dist/docs/tutorials.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/tutorials.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCzB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,WAAW;IACf,KAAK,EAAE,WAAW;IAClB,OAAO,EAAE,qEAAqE;IAC9E,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,iBAAiB;KACzB;IACD,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,iBAAiB,CAAC;IAChD,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/tutorials.runtime-plugin.docs.descriptor.d.ts

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

package/dist/docs/tutorials.runtime-plugin.docs.descriptor.d.ts.map

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

package/dist/docs/tutorials.runtime-plugin.docs.descriptor.js

@@ -0,0 +1,121 @@
+const pluginMarkdown = `---
+title: Build a runtime plugin
+summary: Register descriptors and lazy implementations with createRuntimePlugin and resolve them via runtime.query
+tags: [tutorial, runtime, plugin, descriptors, query]
+parent: tutorials
+order: 5
+---
+
+# Build a runtime plugin
+
+The runtime is the platform's extensibility seam: capabilities are published as **descriptors** of a
+**kind**, backed by lazily-loaded **implementations**, and resolved by querying that kind. A plugin
+bundles those together. This is how AI providers, storage adapters, integrations, and chat surfaces all
+plug in.
+
+## 1. Author the plugin
+
+\`createRuntimePlugin\` (from \`@vibesdotdev/kernel/factory\`) takes static \`descriptors\` plus \`loaders\`
+that import the implementation on demand. \`loader(id, { kind }, importer)\` ties a descriptor id to its
+impl module:
+
+:::usage{language="ts"}
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel/factory';
+
+const greeterDescriptor = {
+  id: 'greeter/friendly',
+  kind: 'greeter/strategy',
+  label: 'Friendly greeter'
+};
+
+export default createRuntimePlugin({
+  id: 'greeter',
+  name: 'Greeter Module',
+  description: 'Pluggable greeting strategies',
+  descriptors: [greeterDescriptor],
+  loaders: [
+    loader(greeterDescriptor.id, { kind: 'greeter/strategy' }, async () => {
+      const { FriendlyGreeter } = await import('./friendly.impl.js');
+      return { default: FriendlyGreeter };
+    })
+  ]
+});
+:::
+
+## 2. Lifecycle hooks (optional)
+
+A plugin may run setup when it registers or after discovery completes. Use \`onRegister\` for work that
+only needs the runtime reference, and \`onActivate\` for cross-kind wiring once every plugin is present:
+
+:::usage{language="ts"}
+createRuntimePlugin({
+  id: 'greeter',
+  descriptors: [greeterDescriptor],
+  loaders: [/* … */],
+  onRegister: async (runtime) => {
+    // runtime is available; register extra descriptors, read scope, etc.
+  },
+  onActivate: async (runtime) => {
+    // all plugins discovered; safe to resolve other kinds here
+  }
+});
+:::
+
+## 3. Register the plugin
+
+Apps and packages select plugins lazily in \`vibes.config.ts\` (see [\`app.config\`](app.config));
+bootstrap registers them once. A test composes the plugin into its own test runtime:
+
+:::usage{language="ts"}
+import { createTestRuntime } from '@vibesdotdev/testing/runtime';
+import greeterPlugin from '@vibesdotdev/greeter/plugin';
+
+const { runtime, cleanup } = await createTestRuntime({ plugins: [greeterPlugin] });
+:::
+
+## 4. Resolve and use it
+
+Query the kind. \`.first()\` resolves the highest-priority implementation; \`.withId()\` targets a
+specific one; \`.descriptors()\` lists what's registered without instantiating:
+
+:::usage{language="ts"}
+const greeter = await runtime
+  .query('greeter/strategy')
+  .withId('greeter/friendly')
+  .resolve();
+
+console.log(await greeter.greet('world'));
+
+// list everything registered for this kind (no impls loaded)
+const available = runtime.query('greeter/strategy').descriptors();
+:::
+
+The implementation module is imported only when first resolved, so registering a plugin is cheap and
+server-only impls never ship to the browser bundle.
+
+## Related
+
+- [\`runtime.plugins\`](runtime.plugins) — the plugin model
+- [\`runtime.query\`](runtime.query) — the full query API (\`first\`, \`withId\`, \`forHardware\`, \`descriptors\`, \`resolve\`)
+- [\`runtime.scopes\`](runtime.scopes) — runtime scopes and where impls run
+- [\`auth.oauth\`](auth.oauth) — the canonical OAuth contract used by integration hosts
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tutorials.runtime-plugin',
+    title: 'Build a runtime plugin',
+    summary: 'Register descriptors and lazy implementations with createRuntimePlugin and resolve them via runtime.query',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: pluginMarkdown
+    },
+    parent: 'tutorials',
+    order: 5,
+    tags: ['tutorial', 'runtime', 'plugin', 'descriptors', 'query'],
+    surfaces: ['web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=tutorials.runtime-plugin.docs.descriptor.js.map

package/dist/docs/tutorials.runtime-plugin.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tutorials.runtime-plugin.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/tutorials.runtime-plugin.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqGtB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,0BAA0B;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,OAAO,EACN,2GAA2G;IAC5G,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,cAAc;KACtB;IACD,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC;IAC/D,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs.plugin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Docs Plugin
+ *
+ * Registers:
+ *   - the `docs/topic` runtime kind (descriptor schema + hardware-filtered resolve)
+ *   - the canonical `runtime/client` with id `docs`
+ *
+ * Tier 1 of `docs/architecture/DOCS-RUNTIME.md`.
+ */
+export declare const docsPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default docsPlugin;
+//# sourceMappingURL=docs.plugin.d.ts.map

package/dist/docs.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.plugin.d.ts","sourceRoot":"","sources":["../src/docs.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoGH,eAAO,MAAM,UAAU,6CAyBrB,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/dist/docs.plugin.js

@@ -0,0 +1,118 @@
+/**
+ * Docs Plugin
+ *
+ * Registers:
+ *   - the `docs/topic` runtime kind (descriptor schema + hardware-filtered resolve)
+ *   - the canonical `runtime/client` with id `docs`
+ *
+ * Tier 1 of `docs/architecture/DOCS-RUNTIME.md`.
+ */
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import { DocsTopicDescriptorSchema } from "./schemas/topic.schema.js";
+import docsToolDescriptor from "./tools/docs.descriptor.js";
+import vibesPlatformPromptDescriptor from "./prompts/descriptors/vibes-platform.prompt.descriptor.js";
+import docsTopicsDocsDescriptor from "./docs/docs.topics.docs.descriptor.js";
+import docsDirectivesDocsDescriptor from "./docs/docs.directives.docs.descriptor.js";
+import docsCliDocsDescriptor from "./cli/docs/docs.cli.docs.descriptor.js";
+import chartsUsageDocsDescriptor from "./docs/charts.usage.docs.descriptor.js";
+import commandPaletteActionsDocsDescriptor from "./docs/command-palette.actions.docs.descriptor.js";
+import guidedFlowsFlowsDocsDescriptor from "./docs/guided-flows.flows.docs.descriptor.js";
+import gettingStartedDocsDescriptor from "./docs/getting-started.docs.descriptor.js";
+import gettingStartedCliDocsDescriptor from "./docs/getting-started-cli.docs.descriptor.js";
+import gettingStartedConceptsDocsDescriptor from "./docs/getting-started.concepts.docs.descriptor.js";
+import gettingStartedFirstQueryDocsDescriptor from "./docs/getting-started.first-query.docs.descriptor.js";
+import tutorialsDocsDescriptor from "./docs/tutorials.docs.descriptor.js";
+import tutorialsAiTextGenerationDocsDescriptor from "./docs/tutorials.ai-text-generation.docs.descriptor.js";
+import tutorialsBuildAnAppDocsDescriptor from "./docs/tutorials.build-an-app.docs.descriptor.js";
+import tutorialsCrudCollectionDocsDescriptor from "./docs/tutorials.crud-collection.docs.descriptor.js";
+import tutorialsRuntimePluginDocsDescriptor from "./docs/tutorials.runtime-plugin.docs.descriptor.js";
+import fleetPairingDocsDescriptor from "./docs/fleet-pairing.docs.descriptor.js";
+import fleetPairingDirectDocsDescriptor from "./docs/fleet-pairing-direct.docs.descriptor.js";
+import fleetPairingMdnsDocsDescriptor from "./docs/fleet-pairing-mdns.docs.descriptor.js";
+import fleetPairingPlatformDocsDescriptor from "./docs/fleet-pairing-platform.docs.descriptor.js";
+import agentVoiceDocsDescriptor from "./docs/agent-voice.docs.descriptor.js";
+import runtimeRpcRelayDocsDescriptor from "./docs/runtime-rpc-relay.docs.descriptor.js";
+import docsSvelteConfigDescriptor from "./config/docs.svelte.config.descriptor.js";
+/**
+    * `docs/topic` kind — hardware-filtered resolve, consumer-default.
+    */
+const docsTopicKind = {
+    id: 'docs/topic',
+    descriptorSchema: DocsTopicDescriptorSchema,
+    defaultImplementation: class DefaultDocsTopic {
+        descriptor;
+        _context;
+        constructor(descriptor, _context) {
+            this.descriptor = descriptor;
+            this._context = _context;
+        }
+    },
+    resolve(candidates, scope) {
+        if (candidates.length === 0)
+            return undefined;
+        if (candidates.length === 1)
+            return candidates[0];
+        const matches = candidates.filter((d) => {
+            if (!d.hardware || d.hardware.length === 0)
+                return true;
+            return d.hardware.some((h) => h === scope.hardware);
+        });
+        return matches.length > 0 ? matches[0] : undefined;
+    },
+    contexts: ['runtime']
+};
+function registerDocsRuntimeClient(runtime) {
+    runtime.registerDescriptor('runtime/client', {
+        id: 'docs',
+        kind: 'runtime/client',
+        description: 'Canonical Docs client — topic descriptor discovery, subject lookup, body resolution',
+        config: { citations: { links: [{ kind: 'docs', source: 'docs' }], queryPolicy: 'literal', originPolicy: 'declared' } }
+    });
+    runtime.registerLoader('runtime/client', 'docs', async () => {
+        const { DocsClient } = await import("./client/docs-client.js");
+        return { impl: DocsClient };
+    });
+}
+const builtInTopicDescriptors = [
+    docsTopicsDocsDescriptor,
+    docsDirectivesDocsDescriptor,
+    docsCliDocsDescriptor,
+    chartsUsageDocsDescriptor,
+    commandPaletteActionsDocsDescriptor,
+    guidedFlowsFlowsDocsDescriptor,
+    gettingStartedDocsDescriptor,
+    gettingStartedCliDocsDescriptor,
+    gettingStartedConceptsDocsDescriptor,
+    gettingStartedFirstQueryDocsDescriptor,
+    tutorialsDocsDescriptor,
+    tutorialsAiTextGenerationDocsDescriptor,
+    tutorialsBuildAnAppDocsDescriptor,
+    tutorialsCrudCollectionDocsDescriptor,
+    tutorialsRuntimePluginDocsDescriptor,
+    fleetPairingDocsDescriptor,
+    fleetPairingDirectDocsDescriptor,
+    fleetPairingMdnsDocsDescriptor,
+    fleetPairingPlatformDocsDescriptor,
+    agentVoiceDocsDescriptor,
+    runtimeRpcRelayDocsDescriptor
+];
+export const docsPlugin = createRuntimePlugin({
+    id: 'docs',
+    name: 'Docs',
+    description: 'Documentation runtime kind and docs client',
+    kinds: [docsTopicKind],
+    descriptors: [
+        docsToolDescriptor,
+        vibesPlatformPromptDescriptor,
+        docsSvelteConfigDescriptor,
+        ...builtInTopicDescriptors
+    ],
+    loaders: [
+        loader('docs', { kind: 'tools/tool' }, () => import("./tools/docs.impl.js"))
+    ],
+    async onActivate(runtime) {
+        registerDocsRuntimeClient(runtime);
+    }
+});
+export default docsPlugin;
+//# sourceMappingURL=docs.plugin.js.map