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

package/dist/docs/charts.usage.docs.descriptor.js

@@ -0,0 +1,90 @@
+/**
+ * Descriptor for charts.usage
+ *
+ * Charts is a surface-only feature (no base @vibesdotdev/charts plugin in the
+ * standard umbrella); the components live in @vibesdotdev/kit/components/viz.
+ * This descriptor is registered through the docs plugin so the topic is
+ * discoverable from `vibes docs list`.
+ */
+const chartsUsageMarkdown = `---
+title: Charts Usage
+summary: Dependency-free SVG chart primitives for Svelte — sparklines, usage bars, trend cards
+tags: [charts, svelte, ui, visualization, sparkline]
+parent: charts
+order: 1
+---
+
+# Charts Usage
+
+\`@vibesdotdev/kit/components/viz\` provides a tiny set of dependency-free SVG chart primitives mounted on app dashboards: sparklines, usage bars, trend cards, and a minimal multi-series chart. No external charting library is required — components render directly into SVG with sensible defaults.
+
+## What this provides
+
+- **\`<Sparkline>\`** — inline mini-line chart for trend visualization in a small footprint.
+- **\`<UsageBar>\`** — horizontal usage/quota bar with label, value, and limit.
+- **\`<TrendCard>\`** — a sparkline + numeric delta in a card layout for dashboard tiles.
+- **\`<MultiSeriesChart>\`** — minimal multi-series line/area chart with axis labels.
+
+## Types and clients
+
+\`\`\`ts
+import {
+  Sparkline,
+  UsageBar,
+  TrendCard,
+  MultiSeriesChart
+} from '@vibesdotdev/kit/components/viz';
+\`\`\`
+
+## Usage examples
+
+\`\`\`svelte
+<script lang="ts">
+  import { Sparkline, UsageBar, TrendCard } from '@vibesdotdev/kit/components/viz';
+
+  const requests = [12, 18, 15, 22, 30, 28, 34];
+</script>
+
+<Sparkline data={requests} width={120} height={32} />
+
+<UsageBar
+  label="API requests"
+  value={3210}
+  max={5000}
+/>
+
+<TrendCard
+  label="Last 7 days"
+  value={3210}
+  delta={+12.4}
+  data={requests}
+/>
+\`\`\`
+
+## Commands available
+
+Charts is a UI-only surface — there are no CLI commands. Charts components mount on app dashboards (e.g. \`apps/account-web\`, \`apps/system-web\`) and consume data from app-specific server endpoints.
+
+## Related topics
+
+- (no related topics in the base catalog yet)
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'charts.usage',
+    title: 'Charts Usage',
+    summary: 'Dependency-free SVG chart primitives for Svelte — sparklines, usage bars, trend cards',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: chartsUsageMarkdown
+    },
+    parent: 'charts',
+    order: 1,
+    tags: ['charts', 'svelte', 'ui', 'visualization', 'sparkline'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=charts.usage.docs.descriptor.js.map

package/dist/docs/charts.usage.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"charts.usage.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/charts.usage.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8D3B,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,uFAAuF;IAChG,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,mBAAmB;KAC5B;IACD,MAAM,EAAE,QAAQ;IAChB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,eAAe,EAAE,WAAW,CAAC;IAC9D,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/command-palette.actions.docs.descriptor.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Descriptor for command-palette.actions
+ *
+ * Command-palette is a surface-only feature; this docs topic lives in the
+ * docs package so it's reachable via the standard docs umbrella.
+ */
+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=command-palette.actions.docs.descriptor.d.ts.map

package/dist/docs/command-palette.actions.docs.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-palette.actions.docs.descriptor.d.ts","sourceRoot":"","sources":["../../src/docs/command-palette.actions.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA0DH,QAAA,MAAM,UAAU;;;;;;;;;;;;;;;;CAgBf,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/command-palette.actions.docs.descriptor.js

@@ -0,0 +1,80 @@
+/**
+ * Descriptor for command-palette.actions
+ *
+ * Command-palette is a surface-only feature; this docs topic lives in the
+ * docs package so it's reachable via the standard docs umbrella.
+ */
+const commandPaletteActionsMarkdown = `---
+title: Command Palette Actions
+summary: Federated search + actions surface — sources, results, and renderers across web, TUI, CLI, and bridge
+tags: [command-palette, actions, search, federator, palette]
+parent: command-palette
+order: 1
+---
+
+# Command Palette Actions
+
+The command palette is a federated search-and-act surface that aggregates results from multiple **sources** (app navigation, recent items, knowledge, pages, actions) and renders them through pluggable renderers. It runs on web, TUI, CLI, and bridge surfaces.
+
+## What this provides
+
+- **\`command-palette/source\` kind** — pluggable result sources (app-navigation, recent-items, actions, knowledge, pages).
+- **\`command-palette/surface\` kind** — per-surface configuration (web, tui, cli, bridge).
+- **Federator** — merges and ranks results from registered sources.
+- **Renderers** — default and navigation-specific result rendering primitives.
+- **\`<AppCommandPalette>\`** — Svelte component mounted in the app shell.
+
+## Types and clients
+
+\`\`\`ts
+import { CommandPaletteClient } from '@vibesdotdev/command-palette';
+import type {
+  CommandPaletteResult,
+  PageDef,
+  RegisteredAction
+} from '@vibesdotdev/command-palette/schemas';
+\`\`\`
+
+## Built-in sources
+
+| Source | Purpose | Priority |
+|---|---|---|
+| \`app-navigation\` | Search across all registered apps | 100 |
+| \`recent-items\` | Recently visited entries from session history | 90 |
+| \`actions\` | Registered \`RegisteredAction\` entries (run, navigate, modal) | 80 |
+| \`knowledge\` | Knowledge-base search | 70 |
+| \`pages\` | App pages and routes | 60 |
+
+## Commands available
+
+Command palette is invoked via keyboard shortcut (e.g. \`Cmd+K\`) inside an app surface — there are no dedicated CLI commands. The palette client is consumed programmatically:
+
+\`\`\`ts
+const palette = new CommandPaletteClient();
+const results = await palette.search('settings');
+\`\`\`
+
+## Related topics
+
+- [\`knowledge.search\`](knowledge.search) — knowledge source backing palette search
+- (other action-surface integrations as they land)
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'command-palette.actions',
+    title: 'Command Palette Actions',
+    summary: 'Federated search + actions surface — sources, results, and renderers across web, TUI, CLI, and bridge',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: commandPaletteActionsMarkdown
+    },
+    parent: 'command-palette',
+    order: 1,
+    tags: ['command-palette', 'actions', 'search', 'federator', 'palette'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=command-palette.actions.docs.descriptor.js.map

package/dist/docs/command-palette.actions.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-palette.actions.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/command-palette.actions.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,6BAA6B,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsDrC,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,yBAAyB;IAC7B,KAAK,EAAE,yBAAyB;IAChC,OAAO,EAAE,uGAAuG;IAChH,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,6BAA6B;KACtC;IACD,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,iBAAiB,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC;IACtE,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/docs.directives.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Descriptor for docs.directives
+ */
+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=docs.directives.docs.descriptor.d.ts.map

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

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

package/dist/docs/docs.directives.docs.descriptor.js

@@ -0,0 +1,104 @@
+/**
+ * Descriptor for docs.directives
+ */
+const docsDirectivesMarkdown = `---
+title: Docs Directives
+summary: Markdown directives like :::card, :::usage, :::endpoint that render as structured components
+tags: [docs, directives, markdown, components]
+parent: docs
+order: 2
+id: docs.directives
+---
+
+# Docs Directives
+
+The docs renderer understands a small set of **directive blocks** — fenced \`:::name{attrs}\` regions that render as structured UI components on web and degrade gracefully to plain text when a topic body is formatted for the terminal.
+
+## What this provides
+
+- **Directive registry** — \`@vibesdotdev/docs/directives\` exports the six builtin directive descriptors plus \`builtinDirectives\` and \`indexDirectives()\`.
+- **Parser** — \`@vibesdotdev/docs/render\` exposes \`parseMarkdown()\`, which lexes a topic body (frontmatter + tokens); \`tokenToDirectiveNode()\` maps a directive token onto the \`DirectiveNode\` shape consumed by renderers.
+- **Renderers** — CLI rendering lives in \`@vibesdotdev/docs/directives\` (\`renderDirectiveCli(node, ansi)\`); web rendering lives in \`@vibesdotdev/docs/svelte\` (\`DirectiveDispatch.svelte\`, surfaced through \`MarkdownView\`).
+
+## Built-in directives
+
+Exactly six directives are registered in \`builtinDirectives\`. There are no other directive names.
+
+| Directive | Attributes | Body? | Purpose |
+|---|---|---|---|
+| \`:::card{title="..."}\` | \`title?\` | yes | Titled bordered card around the body content |
+| \`:::usage{language=ts}\` | \`language\` (default \`ts\`) | yes | Code-usage example block |
+| \`:::shell{...}\` | free-form \`key=val\` | yes | Shell command block with a copy affordance |
+| \`:::install{package="..."}\` | \`package\` | yes | Install card with copy-able shell commands |
+| \`:::endpoint{method=GET path=/api/...}\` | \`method\`, \`path\`, \`appId?\` | no | One-line HTTP endpoint card |
+| \`:::descriptor{kind=... id=...}\` | \`kind\`, \`id\` | no | Kit-styled reference card for a runtime descriptor |
+
+\`method\` accepts \`GET\`, \`POST\`, \`PUT\`, \`PATCH\`, or \`DELETE\`.
+
+## Authoring examples
+
+:::usage{language=md}
+:::card{title="See also"}
+A bordered callout. Markdown inside the body renders normally.
+:::
+
+:::usage{language=ts}
+import { parseMarkdown, tokenToDirectiveNode } from '@vibesdotdev/docs/render';
+:::
+
+:::endpoint{method=GET path=/api/docs/topics}
+
+:::descriptor{kind=docs/topic id=docs.directives}
+:::
+
+## Parsing and rendering
+
+\`\`\`ts
+import { renderDirectiveCli, builtinDirectives, indexDirectives } from '@vibesdotdev/docs/directives';
+import { parseMarkdown, tokenToDirectiveNode, createAnsi, readAnsiEnv } from '@vibesdotdev/docs/render';
+
+import { writeStdoutLine } from '@vibesdotdev/cli/output';
+
+const ansi = createAnsi(readAnsiEnv(runtime)); // the handed runtime's no-color env
+const { tokens } = parseMarkdown(topicBody);
+for (const token of tokens) {
+  const node = tokenToDirectiveNode(token);
+  if (node) {
+    // CLI: degrade to plain text; web uses DirectiveDispatch.svelte instead
+    await writeStdoutLine(runtime, renderDirectiveCli(node, ansi));
+  }
+}
+\`\`\`
+
+The directive descriptors themselves are available for validation or tooling:
+
+\`\`\`ts
+
+const byName = indexDirectives(builtinDirectives);
+const card = byName.get('card'); // { name, attrs (zod), hasBody, description }
+\`\`\`
+
+## Related topics
+
+- [docs.topics](docs.topics) — descriptor shape and body types
+- [docs.cli](docs.cli) — the \`vibes docs\` surface
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'docs.directives',
+    title: 'Docs Directives',
+    summary: 'Markdown directives like :::card, :::usage, :::endpoint that render as structured components',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: docsDirectivesMarkdown
+    },
+    parent: 'docs',
+    order: 2,
+    tags: ['docs', 'directives', 'markdown', 'components'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=docs.directives.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs.directives.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/docs.directives.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiF9B,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,8FAA8F;IACvG,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,sBAAsB;KAC/B;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,EAAE,YAAY,CAAC;IACtD,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/docs.topics.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Descriptor for docs.topics
+ */
+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=docs.topics.docs.descriptor.d.ts.map

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

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

package/dist/docs/docs.topics.docs.descriptor.js

@@ -0,0 +1,90 @@
+/**
+ * Descriptor for docs.topics
+ */
+const docsTopicsMarkdown = `---
+title: Docs Topics
+summary: The docs/topic runtime kind — discoverable, addressable units of user-facing documentation
+tags: [docs, topics, descriptors, runtime]
+parent: docs
+order: 1
+---
+
+# Docs Topics
+
+A **docs/topic** is a runtime descriptor that defines a single, addressable unit of user-facing documentation. Topics are discovered via the runtime registry, rendered by the docs client, and surfaced in CLI (\`vibes docs list\`), web (\`/docs\`), in-app help, and MCP prompts.
+
+## What this provides
+
+- **\`docs/topic\` runtime kind** — registered by \`@vibesdotdev/docs\`, validated against \`DocsTopicDescriptorSchema\` from \`@vibesdotdev/docs-contracts\`.
+- **Hardware-aware resolution** — when multiple topics share an id, the runtime picks the candidate whose \`hardware\` field matches the active scope (defaults to consumer).
+- **Surface filtering** — topics declare which surfaces (\`cli\`, \`web\`, \`in-app\`, \`mcp\`) they should appear on.
+- **Body types** — topics carry their content as inline markdown, package-source markdown, components, OpenAPI/GraphQL refs, route paths, or descriptor refs.
+
+## Types and clients
+
+\`\`\`ts
+import { DocsTopicDescriptorSchema, type DocsTopicDescriptor } from '@vibesdotdev/docs-contracts';
+import { getVibesDocsClient } from '@vibesdotdev/docs';
+
+const docs = await getVibesDocsClient(runtime);
+const topics = docs.list();
+\`\`\`
+
+## Descriptor shape
+
+\`\`\`ts
+const myTopic: DocsTopicDescriptor = {
+  kind: 'docs/topic',
+  id: 'feature.subtopic',
+  title: 'Feature Subtopic',
+  summary: 'One-line summary that shows in lists and search results',
+  body: { type: 'markdown', sourceType: 'raw', source: '# ...' },
+  parent: 'feature',
+  order: 1,
+  tags: ['feature'],
+  surfaces: ['cli', 'web', 'in-app'],
+  hardware: ['consumer'],
+  enabled: true
+};
+\`\`\`
+
+## Commands available
+
+\`\`\`bash
+# List every registered topic
+vibes docs list
+
+# Filter by tag or parent
+vibes docs list --tag tools
+vibes docs list --parent runtime
+
+# Show a topic as man-page
+vibes docs show <topic-id>
+vibes man <topic-id>
+\`\`\`
+
+## Related topics
+
+- [\`docs.directives\`](docs.directives) — \`:::card\`, \`:::endpoint\` and other markdown directives
+- [\`docs.cli\`](docs.cli) — \`vibes docs\` and \`vibes man\` command reference
+- [\`runtime.query\`](runtime.query) — how topics are discovered at runtime
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'docs.topics',
+    title: 'Docs Topics',
+    summary: 'The docs/topic runtime kind — discoverable, addressable units of user-facing documentation',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: docsTopicsMarkdown
+    },
+    parent: 'docs',
+    order: 1,
+    tags: ['docs', 'topics', 'descriptors', 'runtime'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=docs.topics.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs.topics.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/docs.topics.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmE1B,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,aAAa;IACpB,OAAO,EAAE,4FAA4F;IACrG,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,kBAAkB;KAC3B;IACD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,CAAC;IAClD,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/fleet-pairing-direct.docs.descriptor.d.ts

@@ -0,0 +1,30 @@
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    parent: string;
+    order: number;
+    title: string;
+    summary: string;
+    tags: string[];
+    surfaces: readonly ["cli", "web", "in-app"];
+    hardware: readonly ["consumer", "cloud"];
+    enabled: boolean;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    man: {
+        name: string;
+        section: number;
+        synopsis: string;
+        options: never[];
+        examples: {
+            description: string;
+            command: string;
+        }[];
+        seeAlso: string[];
+    };
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing-direct.docs.descriptor.d.ts.map

package/dist/docs/fleet-pairing-direct.docs.descriptor.d.ts.map

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

package/dist/docs/fleet-pairing-direct.docs.descriptor.js

@@ -0,0 +1,93 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'fleet-pairing.direct',
+    parent: 'fleet-pairing',
+    order: 1,
+    title: 'Direct-IP Discovery',
+    summary: 'Register an operator-supplied host:port or https:// origin as a runtime/rpc target',
+    tags: ['fleet', 'discovery', 'direct', 'runtime-rpc'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Direct-IP Discovery
+summary: Register an operator-supplied host:port or https:// origin as a runtime/rpc target
+tags: [fleet, discovery, direct, runtime-rpc]
+parent: fleet-pairing
+order: 1
+id: fleet-pairing.direct
+---
+
+# Direct-IP Discovery (\`fleet/discovery/direct\`)
+
+The simplest discovery adapter: an operator supplies a host address and the
+adapter registers a \`runtime/rpc\` descriptor for it. No socket scan, no cloud
+call, no liveness probe — reachability is verified later by the
+resolver/connect.
+
+## Setup
+
+\`\`\`ts
+import { createDirectDiscoveryAdapter } from '@vibesdotdev/platform/fleets/pairing/direct';
+import { startFleetBootstrap } from '@vibesdotdev/platform/fleets/bootstrap';
+
+const adapter = createDirectDiscoveryAdapter([
+  { id: 'edge-1', address: '10.0.0.5:7777' },
+  { id: 'edge-v6', address: '[2001:db8::1]:9000' },
+  { id: 'box', address: 'https://box.lan', auth: { source: 'secret', key: 'box-lan-token' } }
+]);
+
+// The owning app supplies its reachable-runtime registry; the loop runs on the
+// handed runtime's lifecycle.
+const bootstrap = startFleetBootstrap([adapter], registry, { lifecycle: runtime.lifecycle });
+\`\`\`
+
+## Bootstrap lifecycle
+
+\`startFleetBootstrap(adapters, registry, { lifecycle, refreshIntervalMs?, ttlSeconds?, onEvent?, signal? })\`
+takes the owning runtime's \`lifecycle\` (\`runtime.lifecycle\`). The periodic
+refresh (default 60 000 ms) is that runtime's \`lifecycle.interval\`, so its
+disposal clears the tick and stops the loop, as does the optional \`signal\`.
+A finite host refuses the interval (\`lifecycle-interval-finite\`): pass
+\`refreshIntervalMs: Infinity\` there and call \`refresh()\` on demand.
+
+## Address forms
+
+- \`'10.0.0.5:7777'\` / \`'tcp://box.lan:9000'\` → tcp target
+- \`'[::1]:8080'\` / \`'tcp://[fe80::1]:9000'\` → tcp target (IPv6 must be bracketed)
+- \`'https://box.lan'\` / \`'http://10.0.0.5:8080'\` → http target (origin normalized)
+
+A port-less address, an out-of-range port, or an unbracketed bare IPv6
+literal throws — a direct target must be concrete and is never guessed at.
+
+## Credentials
+
+\`auth\` on a host input is a **CredentialReference** into secrets/store, never
+a bare token; the transport resolves it at connect time.
+
+## Lifecycle
+
+None. The adapter has no \`destroy\` — it did not create the host. If the
+operator-supplied host is a provisioned sandbox, \`infra/sandbox\` owns its
+teardown.
+`
+    },
+    man: {
+        name: 'fleet-pairing.direct — direct-IP fleet discovery',
+        section: 1,
+        synopsis: 'vibes man fleet-pairing.direct',
+        options: [],
+        examples: [
+            {
+                description: 'Create a direct discovery adapter for fleet bootstrap',
+                command: "createDirectDiscoveryAdapter([{ id: 'edge-1', address: '10.0.0.5:7777' }])"
+            }
+        ],
+        seeAlso: ['fleet-pairing', 'fleet-pairing.mdns', 'fleet-pairing.platform']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing-direct.docs.descriptor.js.map

package/dist/docs/fleet-pairing-direct.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pairing-direct.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/fleet-pairing-direct.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,sBAAsB;IAC1B,MAAM,EAAE,eAAe;IACvB,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,qBAAqB;IAC5B,OAAO,EAAE,oFAAoF;IAC7F,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,CAAC;IACrD,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAU;IAC3C,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAU;IACxC,OAAO,EAAE,IAAI;IACb,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6DT;KACC;IACD,GAAG,EAAE;QACJ,IAAI,EAAE,kDAAkD;QACxD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,gCAAgC;QAC1C,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,uDAAuD;gBACpE,OAAO,EAAE,4EAA4E;aACrF;SACD;QACD,OAAO,EAAE,CAAC,eAAe,EAAE,oBAAoB,EAAE,wBAAwB,CAAC;KAC1E;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/fleet-pairing-mdns.docs.descriptor.d.ts

@@ -0,0 +1,30 @@
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    parent: string;
+    order: number;
+    title: string;
+    summary: string;
+    tags: string[];
+    surfaces: readonly ["cli", "web", "in-app"];
+    hardware: readonly ["consumer"];
+    enabled: boolean;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    man: {
+        name: string;
+        section: number;
+        synopsis: string;
+        options: never[];
+        examples: {
+            description: string;
+            command: string;
+        }[];
+        seeAlso: string[];
+    };
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing-mdns.docs.descriptor.d.ts.map

package/dist/docs/fleet-pairing-mdns.docs.descriptor.d.ts.map

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