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

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

@@ -0,0 +1,88 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'fleet-pairing.mdns',
+    parent: 'fleet-pairing',
+    order: 2,
+    title: 'mDNS LAN Discovery',
+    summary: 'LAN runtimes advertising _vibes-rpc._tcp become runtime/rpc tcp targets',
+    tags: ['fleet', 'discovery', 'mdns', 'lan', 'runtime-rpc'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true,
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: mDNS LAN Discovery
+summary: LAN runtimes advertising _vibes-rpc._tcp become runtime/rpc tcp targets
+tags: [fleet, discovery, mdns, lan, runtime-rpc]
+parent: fleet-pairing
+order: 2
+id: fleet-pairing.mdns
+---
+
+# mDNS LAN Discovery (\`fleet/discovery/mdns\`)
+
+Finds LAN runtimes advertising a \`_vibes-rpc._tcp\` service and registers each
+as a \`runtime/rpc\` **tcp** target. Discovered hosts are evictable (the mDNS
+record TTL becomes the registry entry's eviction TTL) — never sticky.
+
+## Setup
+
+\`\`\`ts
+import { createMdnsDiscoveryAdapter } from '@vibesdotdev/platform/fleets/pairing/mdns';
+import { startFleetBootstrap } from '@vibesdotdev/platform/fleets/bootstrap';
+
+// A production LAN build injects its scanner; the default is capability-gated
+// and safely yields nothing where multicast is unavailable.
+const adapter = createMdnsDiscoveryAdapter(realMulticastScanner);
+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.
+
+## The scanner port
+
+The multicast socket scan is an injected \`MdnsScanner\`
+(\`scan(signal?) → AsyncIterable<MdnsServiceAdvertisement>\`). The default stub
+is capability-gated and degrades to empty rather than throwing — no real
+multicast runs in CI. Each advertisement
+(\`instanceName\`/\`host\`/\`port\`/\`ttlSeconds\`) maps to a descriptor with the id
+\`mdns:<instanceName>\`.
+
+## Credentials
+
+LAN descriptors carry **no \`auth\`** — discovery relies on the local-network
+trust boundary for the connection, and per-invoke authorization still runs on
+every host-side invoke. If connection credentials are ever added they must be
+CredentialReferences, never bare tokens.
+
+## Lifecycle
+
+None. The adapter found a host that already exists on the LAN; it has no
+\`destroy\`.
+`
+    },
+    man: {
+        name: 'fleet-pairing.mdns — mDNS LAN fleet discovery',
+        section: 1,
+        synopsis: 'vibes man fleet-pairing.mdns',
+        options: [],
+        examples: [
+            {
+                description: 'Create the adapter over an injected scanner',
+                command: 'createMdnsDiscoveryAdapter(scanner)'
+            }
+        ],
+        seeAlso: ['fleet-pairing', 'fleet-pairing.direct', 'fleet-pairing.platform']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing-mdns.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pairing-mdns.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/fleet-pairing-mdns.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,oBAAoB;IACxB,MAAM,EAAE,eAAe;IACvB,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,oBAAoB;IAC3B,OAAO,EAAE,yEAAyE;IAClF,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,CAAC;IAC1D,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAU;IAC3C,QAAQ,EAAE,CAAC,UAAU,CAAU;IAC/B,OAAO,EAAE,IAAI;IACb,IAAI,EAAE;QACL,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwDT;KACC;IACD,GAAG,EAAE;QACJ,IAAI,EAAE,+CAA+C;QACrD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,8BAA8B;QACxC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,6CAA6C;gBAC1D,OAAO,EAAE,qCAAqC;aAC9C;SACD;QACD,OAAO,EAAE,CAAC,eAAe,EAAE,sBAAsB,EAAE,wBAAwB,CAAC;KAC5E;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/fleet-pairing-platform.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-platform.docs.descriptor.d.ts.map

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

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

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

@@ -0,0 +1,101 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'fleet-pairing.platform',
+    parent: 'fleet-pairing',
+    order: 3,
+    title: 'Platform-Pairing Discovery',
+    summary: 'Platform-known active hosts become runtime/rpc http targets with a connection credential',
+    tags: ['fleet', 'discovery', 'platform', 'pairing', 'runtime-rpc', 'credentials'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Platform-Pairing Discovery
+summary: Platform-known active hosts become runtime/rpc http targets with a connection credential
+tags: [fleet, discovery, platform, pairing, runtime-rpc, credentials]
+parent: fleet-pairing
+order: 3
+id: fleet-pairing.platform
+---
+
+# Platform-Pairing Discovery (\`fleet/discovery/platform\`)
+
+Finds hosts the *platform record API* already knows (\`status: active\`) and
+registers each as a \`runtime/rpc\` **http** target (the host's daemon URL).
+It is also the *connection-credential* adapter: it stamps a per-host
+\`CredentialReference\` into the descriptor's \`auth\`.
+
+## Setup
+
+\`\`\`ts
+import { createPlatformDiscoveryAdapter } from '@vibesdotdev/platform/fleets/pairing/platform';
+import { startFleetBootstrap } from '@vibesdotdev/platform/fleets/bootstrap';
+
+// The platform record API is an injected port; production wires the real
+// host record API, tests a mock. This package never calls a cloud endpoint.
+const adapter = createPlatformDiscoveryAdapter(platformHostDirectory);
+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.
+
+## Two boundaries
+
+1. **It does not own enrollment.** The operator mints a one-time token
+   (\`vibes fleet enroll-token create --host-id <id>\`) and runs the daemon
+   (\`vibes fleet daemon --host-id <id> --enroll-token <token>\`); the platform
+   record API validates the enrollment and writes the host record. This adapter
+   consumes the *result* — an active host, reachable via the relay broker or a
+   direct daemon URL — and makes it discoverable.
+2. **\`auth\` is a connection credential only.** The adapter emits a
+   \`{ source: 'secret', key, scope? }\` reference resolved by the transport at
+   connect time via secrets/store; it never resolves the secret to a
+   plaintext token, and the token never authorizes the invokes that ride the
+   connection (per-invoke authorization + friction run on every invoke).
+
+## The daemon's connection bearer
+
+On the host side, \`vibes fleet daemon\` resolves its connection bearer through
+\`runtime.resolveCredential({ source: 'secret', key: 'FLEET_DAEMON_TOKEN', store: 'fleet.daemon-credentials' })\`.
+That store is the by-id \`secrets/store\` the daemon composes on its runtime for
+its host id: \`<vibesHome>/hosts/<host-id>.daemon-token\`, mode 0600, refused
+\`credential-file-exposed\` when group- or other-readable. Put the bearer there
+with \`vibes fleet daemon install --host-id <id> --token-file <0600 path>\`; no
+credential value enters the service definition. The daemon never reads the
+bearer from its environment. \`--token\` still overrides the store but rides
+argv, and the daemon warns that it is \`ps\`-visible. \`credential-not-set\`
+means no bearer: a loopback listener stays anonymous and a non-loopback bind is
+refused; any other resolution failure is thrown typed.
+
+## Lifecycle
+
+None. Platform owns the host records; \`infra/sandbox\` owns provisioned
+sandbox teardown. The adapter has no \`destroy\`.
+`
+    },
+    man: {
+        name: 'fleet-pairing.platform — platform-pairing fleet discovery',
+        section: 1,
+        synopsis: 'vibes man fleet-pairing.platform',
+        options: [],
+        examples: [
+            {
+                description: 'Create a platform discovery adapter for fleet bootstrap',
+                command: 'createPlatformDiscoveryAdapter(directory)'
+            }
+        ],
+        seeAlso: ['fleet-pairing', 'fleet-pairing.direct', 'fleet-pairing.mdns']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing-platform.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pairing-platform.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/fleet-pairing-platform.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,wBAAwB;IAC5B,MAAM,EAAE,eAAe;IACvB,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,4BAA4B;IACnC,OAAO,EAAE,0FAA0F;IACnG,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,CAAC;IACjF,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqET;KACC;IACD,GAAG,EAAE;QACJ,IAAI,EAAE,2DAA2D;QACjE,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,kCAAkC;QAC5C,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,yDAAyD;gBACtE,OAAO,EAAE,2CAA2C;aACpD;SACD;QACD,OAAO,EAAE,CAAC,eAAe,EAAE,sBAAsB,EAAE,oBAAoB,CAAC;KACxE;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

@@ -0,0 +1,28 @@
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    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.docs.descriptor.d.ts.map

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

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

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

@@ -0,0 +1,89 @@
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'fleet-pairing',
+    title: 'Fleet Discovery Adapters',
+    summary: 'Find already-running reachable runtimes and register them as runtime/rpc targets',
+    tags: ['fleet', 'discovery', 'pairing', 'runtime-rpc'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true,
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: `---
+title: Fleet Discovery Adapters
+summary: Find already-running reachable runtimes and register them as runtime/rpc targets
+tags: [fleet, discovery, pairing, runtime-rpc]
+id: fleet-pairing
+---
+
+# Fleet Discovery Adapters
+
+A **discovery adapter** finds an already-running reachable runtime and yields
+a \`runtime/rpc\` descriptor for it. \`@vibesdotdev/platform/fleets/pairing\` owns the base
+contract and the \`fleet/discovery\` runtime kind; three sibling packages ship
+the concrete adapters.
+
+## The contract
+
+\`\`\`ts
+interface FleetDiscoveryAdapter {
+  readonly id: string; // 'fleet/discovery/direct' etc.
+  /** Pure read — yields runtime/rpc descriptors until \`signal\` aborts. */
+  discover(signal?: AbortSignal): AsyncIterable<RuntimeRpcDescriptor>;
+}
+\`\`\`
+
+Discovery has **no teardown**: the interface deliberately has no \`destroy\`.
+An adapter surfaces runtimes that already exist; their lifecycle belongs to
+whoever created them (an operator, the LAN host owner, or — for a provisioned
+sandbox — \`infra/sandbox\`). Only the provisioning adapter
+(\`@vibesdotdev/fleet\`) carries \`destroy\`.
+
+## The three adapters
+
+- [\`fleet-pairing.direct\`](fleet-pairing.direct) — an operator-supplied
+  \`host:port\` / \`[ipv6]:port\` / \`https://\` origin becomes a target.
+- [\`fleet-pairing.mdns\`](fleet-pairing.mdns) — LAN runtimes advertising
+  \`_vibes-rpc._tcp\` become tcp targets.
+- [\`fleet-pairing.platform\`](fleet-pairing.platform) — platform-known active
+  hosts become http targets carrying a connection credential.
+
+## Driving discovery into the registry
+
+\`\`\`ts
+import { registerDiscovered } from '@vibesdotdev/platform/fleets/pairing';
+
+const registered = await registerDiscovered(adapter, registry);
+\`\`\`
+
+\`registerDiscovered\` validates every yielded descriptor against the frozen
+\`RuntimeRpcDescriptorSchema\` and registers it with \`origin: 'discovered'\` and
+a staleness TTL (default 120s) — discovered entries are evictable, provisioned
+ones are sticky.
+
+## Credential rules
+
+A descriptor's \`auth\` is always a **CredentialReference**
+(\`{ source, key, scope? }\` into secrets/store), never a bare token. The
+transport resolves it at connect time. A bearer token authorizes a
+*connection* only — per-invoke authorization and friction run on every invoke
+that arrives over the transport.
+`
+    },
+    man: {
+        name: 'fleet-pairing — fleet discovery adapter base',
+        section: 1,
+        synopsis: 'vibes man fleet-pairing',
+        options: [],
+        examples: [
+            {
+                description: 'Drive an adapter into the reachable-runtime registry',
+                command: 'await registerDiscovered(adapter, registry)'
+            }
+        ],
+        seeAlso: ['fleet-pairing.direct', 'fleet-pairing.mdns', 'fleet-pairing.platform']
+    }
+};
+export default descriptor;
+//# sourceMappingURL=fleet-pairing.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fleet-pairing.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/fleet-pairing.docs.descriptor.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,GAAG;IAClB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,eAAe;IACnB,KAAK,EAAE,0BAA0B;IACjC,OAAO,EAAE,kFAAkF;IAC3F,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC;IACtD,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2DT;KACC;IACD,GAAG,EAAE;QACJ,IAAI,EAAE,8CAA8C;QACpD,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,yBAAyB;QACnC,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,sDAAsD;gBACnE,OAAO,EAAE,6CAA6C;aACtD;SACD;QACD,OAAO,EAAE,CAAC,sBAAsB,EAAE,oBAAoB,EAAE,wBAAwB,CAAC;KACjF;CACD,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/getting-started-cli.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-cli.docs.descriptor.d.ts.map

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

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

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

@@ -0,0 +1,141 @@
+const gettingStartedCliMarkdown = `---
+title: Getting Started (CLI)
+summary: Install the vibes CLI, authenticate, and run your first command — end-to-end in five steps
+tags: [getting-started, cli, install, auth, hq, fleet]
+parent: getting-started
+order: 1
+---
+
+# Getting Started (CLI)
+
+This guide is for **end users of the CLI** — developers who want to install \`vibes\`, authenticate,
+and start using the platform from the terminal.  If you are building an app on top of the vibes
+runtime (SDK-level), see [Getting Started](getting-started) instead.
+
+## 1. Install
+
+**macOS / Linux**
+
+\`\`\`bash
+curl -fsSL https://cli.vibes.dev/install.sh | sh
+\`\`\`
+
+**Windows (PowerShell)**
+
+\`\`\`powershell
+irm https://cli.vibes.dev/install.ps1 | iex
+\`\`\`
+
+**npm / bun (any platform)**
+
+\`\`\`bash
+npm install -g @vibesdotdev/bin
+# or
+bun add -g @vibesdotdev/bin
+\`\`\`
+
+All installers write a single \`vibes\` binary and add it to your PATH:
+
+| Platform | Default install path |
+|----------|----------------------|
+| macOS / Linux | \`~/.local/bin/vibes\` |
+| Windows | \`%LOCALAPPDATA%\\vibes\\bin\\vibes.exe\` |
+
+Verify:
+
+\`\`\`bash
+vibes --version
+\`\`\`
+
+## 2. Authenticate
+
+\`\`\`bash
+vibes auth login
+\`\`\`
+
+This opens a browser-based device-auth flow.  After approval your credential is stored at
+\`~/.vibes/\` and all subsequent commands use it automatically.
+
+To use an API key instead:
+
+\`\`\`bash
+vibes auth login --token <your-api-key>
+\`\`\`
+
+## 3. First-time setup
+
+\`\`\`bash
+vibes hq init
+\`\`\`
+
+\`hq init\` ensures the runtime directory structure exists, runs the installer preset, checks
+permissions, and verifies system health.  It also prompts for auth when no credential is stored
+(pass \`--no-auth\` to skip).
+
+Common options:
+
+| Option | Purpose |
+|--------|---------|
+| \`--preset minimal\` | Minimal install (skips optional tooling) |
+| \`--preset recommended\` | Default — balanced install |
+| \`--preset full\` | Full install including all optional tools |
+| \`--no-auth\` | Skip the auth prompt |
+| \`--dry-run\` | Show what would run without making changes |
+| \`--enroll-fleet\` | Prompt for platform origin + enroll as fleet worker |
+
+## 4. Configure an AI provider
+
+\`\`\`bash
+vibes ai setup
+\`\`\`
+
+Walks through selecting a model provider (Digital Ocean, local LM Studio, etc.) and stores the
+configuration.
+
+## 5. (Optional) Enroll as a fleet worker
+
+If you want this machine to run builds dispatched by the platform:
+
+\`\`\`bash
+vibes hq init --enroll-fleet
+# or
+vibes fleet install --host-id <your-machine-name>
+\`\`\`
+
+The fleet daemon starts automatically at login and accepts build jobs from the platform.
+
+---
+
+## Useful first commands
+
+\`\`\`bash
+vibes --help                      # top-level help
+vibes docs list                   # browse all docs topics
+vibes docs show getting-started-cli   # re-read this guide
+vibes auth status                 # check authentication status
+vibes hq health                   # system health check
+vibes fleet status                # fleet / daemon status
+\`\`\`
+
+## Related
+
+- [Auth](auth) — full authentication reference
+- [HQ](hq.terminal) — runtime management commands
+- [Fleet pairing](fleet-pairing) — enrolling machines into your fleet
+- [Docs CLI](docs.cli) — browsing and searching documentation from the terminal
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'getting-started-cli',
+    title: 'Getting Started (CLI)',
+    summary: 'Install the vibes CLI, authenticate, and run your first command — end-to-end in five steps',
+    body: { type: 'markdown', sourceType: 'raw', source: gettingStartedCliMarkdown },
+    parent: 'getting-started',
+    order: 1,
+    tags: ['getting-started', 'cli', 'install', 'auth', 'hq', 'fleet'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=getting-started-cli.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started-cli.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/getting-started-cli.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,yBAAyB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6HjC,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,qBAAqB;IACzB,KAAK,EAAE,uBAAuB;IAC9B,OAAO,EACN,4FAA4F;IAC7F,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE;IAChF,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,iBAAiB,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC;IAClE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/getting-started.concepts.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.concepts.docs.descriptor.d.ts.map

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

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

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

@@ -0,0 +1,100 @@
+const conceptsMarkdown = `---
+title: Core concepts
+summary: The five words that explain the whole platform — runtime, descriptor, kind, scope, resolve
+tags: [concepts, mental-model, runtime, descriptor, kind, scope]
+parent: getting-started
+order: 1
+---
+
+# Core concepts
+
+Almost every page in these docs assumes five terms. Here they are, in the order they build on each other.
+
+## Runtime
+
+The **runtime** is the registry and resolver that every vibes app and CLI shares. Your code is
+handed it: \`context.runtime\` in a tool, command or job, and the \`RuntimeRef\` in a plugin's
+\`onRegister\`/\`onActivate\`. Only a host entry file, which boots the runtime, calls
+\`getVibesRuntime()\`. Instead of importing a concrete implementation, you ask the runtime for a
+capability and it hands you the right one for the current context.
+
+\`\`\`ts
+// \`runtime\` is the VibesRuntime you were handed.
+const tool = await runtime.query('tools/tool').withId('web-search').resolve();
+\`\`\`
+
+## Kind
+
+A **kind** is a category of capability with a stable contract — a string like \`runtime/client\`,
+\`tools/tool\`, \`storage/adapter\`, or \`integration/provider\`. You never import a kind; you query for it.
+Kinds are the vocabulary of the platform.
+
+## Descriptor
+
+A **descriptor** is a small, static declaration that a capability of some kind exists — its \`id\`,
+its \`kind\`, and metadata (tags, target hardware, surfaces). Descriptors are cheap to load and safe to
+enumerate, so the runtime can list what's available without running anything. The actual code — the
+**implementation** — is loaded lazily only when you resolve it. (This doc system is itself built on
+descriptors: every page is a \`docs/topic\` descriptor.)
+
+## Scope
+
+A **scope** is the actor context a resolution happens in: \`{ account, tier, org?, team?, project?, system? }\`.
+It answers "who is this for, and where." Scope lets the same query return account-private data in a
+personal workspace and org-shared data inside an organization, without the call site changing.
+
+## Hardware & surfaces
+
+Two more descriptor facets shape resolution:
+- **hardware** — the target environment: \`consumer\` (a local machine) or \`cloud\` (the edge / workerd). Filter with \`.forHardware('cloud')\`.
+- **surfaces** — where a capability is exposed: \`cli\`, \`web\`, \`in-app\`, or \`mcp\`.
+
+A storage adapter might be registered for \`consumer\` and a different one for \`cloud\`; your code asks for
+\`storage/adapter\` and the runtime picks the one that fits.
+
+## Resolve
+
+**Resolving** is asking the runtime for a capability. Product code normally uses the domain's
+canonical client helper, which resolves the appropriate \`runtime/client\` descriptor:
+
+\`\`\`ts
+import { getVibesAIClient } from '@vibesdotdev/ai/client';
+
+const ai = await getVibesAIClient(runtime); // the runtime your context was handed
+const response = await ai.text({ messages: [{ role: 'user', content: 'Hello, vibes.' }] });
+\`\`\`
+
+\`query(kind)\` is the lower-level builder that clients and platform code can narrow (\`.withId()\`, \`.withTag()\`, \`.forHardware()\`,
+\`.matching(scope)\`) before terminating with \`.first()\` / \`.resolve()\` (one implementation) or
+\`.descriptors()\` (list metadata without loading code). That's the whole loop: **declare descriptors,
+register them via a plugin, resolve them by kind.**
+
+## Where capabilities come from
+
+Descriptors and their lazy implementations are bundled into a **plugin** and registered per app in
+\`vibes.config.ts\`. Product code normally calls the domain's canonical client; runtime and plugin
+authors use \`query\` to compose or implement capabilities. To add your own, see
+[Build a runtime plugin](tutorials.runtime-plugin).
+
+## Related
+
+- [Your first query](getting-started.first-query) — do this hands-on
+- [\`runtime.query\`](runtime.query) — the full query/resolution API
+- [\`runtime.plugins\`](runtime.plugins) — registering descriptors and implementations
+- [\`scope.actors\`](scope.actors) — scopes and actors in depth
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'getting-started.concepts',
+    title: 'Core concepts',
+    summary: 'The five words that explain the whole platform — runtime, descriptor, kind, scope, resolve',
+    body: { type: 'markdown', sourceType: 'raw', source: conceptsMarkdown },
+    parent: 'getting-started',
+    order: 1,
+    tags: ['concepts', 'mental-model', 'runtime', 'descriptor', 'kind', 'scope'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=getting-started.concepts.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"getting-started.concepts.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/getting-started.concepts.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoFxB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,0BAA0B;IAC9B,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,4FAA4F;IACrG,IAAI,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE;IACvE,MAAM,EAAE,iBAAiB;IACzB,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,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/getting-started.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.docs.descriptor.d.ts.map

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

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