@vibesdotdev/tools 0.0.0-stage → 1.0.0-rc.4

package/dist/docs/authoring.docs.descriptor.js

@@ -0,0 +1,172 @@
+const markdown = `---
+title: Authoring tools (schemas + MCP)
+summary: Write tools/tool descriptors that agents can discover, validate, and call correctly
+tags: [tools, mcp, schema, authoring, agent]
+parent: tools
+order: 2
+---
+
+# Authoring tools for agents and MCP
+
+End-user developers and repository-collection authors share the same \`tools/tool\` contract.
+A tool that is only “registered” is not enough — the **schema** and
+**mcpDescription** are what agents see.
+
+## Descriptor checklist
+
+1. **\`id\`** — stable, feature-prefixed when possible (\`workspace-fs\`, not \`fs\`).
+2. **\`mcpDescription\`** — single line, ≤ **1024** characters (\`MCP_DESCRIPTION_LIMIT\`).
+   **This is the only place usage instructions belong.** It is what the agent reads at
+   the moment it decides whether to call your tool, and it is the field that reaches the
+   wire — the long \`description\` does not. Do not restate it in a system prompt or a
+   skill file (constitution §THE RULES #14a).
+
+   Spend the budget on what the agent cannot infer from the schema: **when to reach for
+   this tool over a neighbouring one** (the highest-value sentence, and the one nothing
+   else supplies), **preconditions and failure modes**, and **consequences** (does it
+   mutate, publish, cost money, need approval).
+
+   Do **not** spend it restating parameter names, types, or defaults — the client already
+   receives \`schemas.input\` as JSON Schema, so a prose copy is a second home that drifts.
+   Prefer an expressive schema (enums, precise field names, \`.describe()\`) over prose
+   explaining a vague one; examples narrow a capable model to the shapes you demonstrate,
+   so keep at most one and only where the shape is genuinely non-obvious.
+
+   The budget is per-tool, but the real constraint is the **catalog**: ~106 tools served
+   at once is the cost deferred loading exists to avoid. A tool whose name and schema say
+   everything deserves one line.
+
+   Note: CLI \`tools run\` with no \`--input\` still recovers a sample payload from an
+   **\`Ex:\`** fragment (shared \`extractExExampleFromMcpDescription\`). Keep an \`Ex:\` only
+   when you want that CLI affordance, not as the default teaching device.
+3. **\`schemas.input\`** — Zod (preferred). Discriminated unions on \`action\` are
+   first-class; the runtime flattens them for MCP \`tools/list\` and the invoke
+   gate without laundering args.
+4. **First-party widgets.** Vibes-owned tools MUST register a \`tools/ui\` widget
+   for both Svelte (\`surfaces: ['web']\`) and TUI (\`surfaces: ['tui']\`). The Kit
+   \`DefaultToolCard\` / TUI \`DefaultToolWidgetCard\` is reserved for user-authored
+   tools (\`custom:*\`) that have not declared a widget yet. JSON in that fallback
+   renders through the Kit syntax surface, not a raw \`<pre>\`.
+5. **\`purpose\`** — include \`mcp\` and/or \`agent\` if the tool should be host-facing.
+6. **\`hardware\`** — match the surfaces that register your plugin (\`consumer\`,
+   \`cloud\`). Wrong hardware looks like “tool not found.”
+7. **\`safety\`** — declare \`'read'\`, \`'write'\` or \`'execute'\` from what the
+   implementation does, and \`schemas.actionSafety\` per action when actions differ.
+   External hosts run only a declared \`read\` without approval; an undeclared tool
+   always asks, and \`requiresApproval: true\` asks whatever the safety. The
+   read-only sandbox reads the same declarations and nothing else — it never
+   classifies a tool by words in its name, description or tags, and refuses a
+   call whose safety nothing declares.
+
+:::usage{language="ts"}
+import * as z from 'zod/v4';
+
+export default {
+  kind: 'tools/tool',
+  id: 'workspace-fs',
+  name: 'Workspace Filesystem',
+  description: 'Read and write files in the bound workspace environment.',
+  mcpDescription:
+    'Workspace FS read/write/list. Ex: {action:"read",path:"/src/index.ts"}.',
+  purpose: ['direct', 'worker', 'mcp', 'agent'],
+  hardware: ['consumer', 'cloud'],
+  safety: 'write',
+  schemas: {
+    actionSafety: { read: 'read', list: 'read', write: 'write' },
+    input: z.discriminatedUnion('action', [
+      z.object({ action: z.literal('read'), path: z.string() }),
+      z.object({ action: z.literal('list'), dir: z.string() }),
+      z.object({ action: z.literal('write'), path: z.string(), content: z.string() })
+    ]),
+    output: z.unknown()
+  },
+  enabled: true
+};
+:::
+
+## Wire rules you should know
+
+- **Missing tools never vanish silently.** Declared \`toolIds\` that fail to resolve
+  inject a degraded-toolset notice and job metadata (\`missingToolIds\`).
+- **Invoke validation does not launder DU inputs.** The flattened wire object is
+  shape-only; per-action parse happens after the discriminator is known.
+- **Empty catalogs are not success** for configured API/remote/DB providers that
+  fail to list — they throw.
+
+## Local project tools (end-user apps)
+
+:::shell
+vibes tools init --example
+vibes tools list --local
+vibes tools inspect example-echo
+vibes tools run example-echo --input '{"action":"echo","message":"hi"}'
+# omit --input on purpose → preflight prints Ex: sample + inspect/dry-run tips
+vibes tools run example-echo
+:::
+
+\`init --example\` writes \`.vibes/tools/example-echo.descriptor.ts\` — a real
+\`tools/tool\` TypeScript descriptor **plus** \`export async function execute\`.
+When \`.vibes/tools\` exists, \`list\` / \`inspect\` / \`run\` and MCP serve
+**auto-load** that catalog into the current process (stderr notices on load /
+partial failure — rule 13). You do **not** need a manual \`scan --load\` for
+the happy path.
+
+Project tools are tagged for operators and agents:
+
+- CLI list: \`source: local\` (filter with \`--local\`)
+- MCP tools/list: \`[local]\` description prefix + \`_meta.vibes.origin=local\`
+
+Still use explicit scan for honesty gates and re-bind:
+
+:::shell
+vibes tools scan --json          # failures + scannedFiles + scannedPaths
+vibes tools scan --strict        # CI: non-zero if any descriptor file failed
+vibes tools scan --load          # mid-session re-scan after editing descriptors
+:::
+
+\`scan --load\` re-registers descriptors and source loaders into the live process
+(it does **not** only print "loaded"). \`--strict\` fails when any
+\`.descriptor.ts\` failed to parse — use it in CI so partial catalogs cannot
+look green. Do **not** use ad-hoc JSON \`inputSchema\` files; that shape is not
+the registry contract.
+
+## CLI dogfood (repository-collection / installed tools)
+
+:::shell
+vibes tools list
+vibes tools inspect workspace-fs
+vibes tools run workspace-fs --dry-run --input '{"action":"list","dir":"."}'
+:::
+
+\`list\` / \`inspect\` prefer \`mcpDescription\` so you see what agents see.
+\`run --dry-run\` prints the projected JSON Schema (and warns if projection is degraded).
+Validation failures list field issues and point at \`inspect\` / \`--dry-run\`.
+
+## Related
+
+:::card{title="See also"}
+- \`tools.list\` — enumerate the registry
+- \`tools.invoke\` — invoke path and hooks
+- \`tools.providers\` — discovery adapters
+- \`@vibesdotdev/ai-schemas\` \`MCP_DESCRIPTION_LIMIT\` — single description cap
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tools.authoring',
+    title: 'Authoring tools (schemas + MCP)',
+    summary: 'Write tools/tool descriptors that agents can discover, validate, and call correctly',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'tools',
+    order: 2,
+    tags: ['tools', 'mcp', 'schema', 'authoring', 'agent'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=authoring.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/authoring.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwJhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,iBAAiB;IACrB,KAAK,EAAE,iCAAiC;IACxC,OAAO,EAAE,qFAAqF;IAC9F,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,CAAC;IACtD,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/custom-tools.docs.descriptor.d.ts

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

package/dist/docs/custom-tools.docs.descriptor.d.ts.map

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

package/dist/docs/custom-tools.docs.descriptor.js

@@ -0,0 +1,54 @@
+const markdown = `---
+title: Custom Tools
+summary: Storage-backed user-authored tool definitions hosted by ai-web
+tags: [tools, storage, custom-tools]
+parent: tools
+order: 6
+surfaces: [web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Custom Tools
+
+\`tools.custom-tools\` is the storage manifest for user-authored executable tool
+definitions. The schema lives in \`@vibesdotdev/tools/tools/schemas/storage\`;
+ai-web owns the app-local Drizzle table and exposes the canonical
+\`/api/custom-tools\` CRUD surface for \`storage.cloud-api\`.
+
+:::descriptor{kind="storage/manifest" id="tools.custom-tools"}
+:::
+
+## Wire Shape
+
+The owner endpoint follows the standard CRUD contract:
+
+- \`GET /api/custom-tools\` returns \`{ results: CustomToolStorageRecord[] }\`
+- \`POST /api/custom-tools\` returns \`{ result: CustomToolStorageRecord }\`
+- \`GET /api/custom-tools/:id\` returns \`{ result: CustomToolStorageRecord }\`
+- \`PATCH /api/custom-tools/:id\` returns \`{ result: CustomToolStorageRecord }\`
+- \`DELETE /api/custom-tools/:id\` returns \`204\`
+
+The mixed \`/api/tools\` endpoint remains an ai-web presentation surface that
+combines system descriptors with custom records. Storage consumers use
+\`tools.custom-tools\` instead.
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tools.custom-tools',
+    title: 'Custom Tools',
+    summary: 'Storage-backed user-authored tool definitions hosted by ai-web',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'tools',
+    order: 6,
+    tags: ['tools', 'storage', 'custom-tools'],
+    surfaces: ['web', 'in-app'],
+    subject: { kind: 'storage/manifest', id: 'tools.custom-tools' },
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=custom-tools.docs.descriptor.js.map

package/dist/docs/custom-tools.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-tools.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/custom-tools.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiChB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,oBAAoB;IACxB,KAAK,EAAE,cAAc;IACrB,OAAO,EAAE,gEAAgE;IACzE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,cAAc,CAAC;IAC1C,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;IAC3B,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,EAAE,EAAE,oBAAoB,EAAE;IAC/D,QAAQ,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC;IAC/B,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/docs/invoke.docs.descriptor.js

@@ -0,0 +1,200 @@
+const markdown = `---
+title: Tool Invocation
+summary: Tool invocation API, input validation, execution context, and result handling
+tags: [tools, invocation, execution, validation]
+parent: tools
+order: 2
+surfaces: [cli, web, in-app]
+hardware: [consumer, cloud]
+---
+
+# Tool Invocation
+
+\`invokeTool\` is the canonical path for **universal tools** (\`tools/tool\`). Use \`runtime.query('tools/adapter')\` only for **adapter-shaped** capabilities (filesystem, browser, …) — not for MCP transport or external host install.
+
+## Basic invocation
+
+:::usage{language="ts"}
+import type { VibesRuntime } from '@vibesdotdev/kernel';
+import { invokeTool } from '@vibesdotdev/tools/execution/invoke';
+
+// The handed runtime: context.runtime in a command, event.locals.runtime in
+// SvelteKit, the onActivate runtime in a plugin.
+declare const runtime: VibesRuntime;
+
+const result = await invokeTool({
+  runtime,
+  toolId: 'workspace-fs',
+  input: { action: 'read', path: '/src/index.ts' },
+  ctx: { callId: 'call-123', surface: 'cli' }
+});
+:::
+
+## MCP vs External Projection
+
+| Layer | Kind / package | Role |
+|-------|----------------|------|
+| Universal tools | \`tools/tool\` + \`invokeTool\` | Execution spine |
+| MCP | \`@vibesdotdev/mcp\` | Protocol surface for external agents — not \`tools/adapter\` |
+| External hosts | \`external/host\` + \`external/adapter\` + agent pack | MCP/skills/hooks install into Claude, Cursor, … |
+
+Install MCP with \`vibes dev mcp install\`. Configure hosts with \`vibes dev external\`. The \`external\` config's \`collaboration.toolTiers.enabled\` runs tier checks from harness hooks via the \`tools/tool\` bus.
+
+## Tool call context
+
+Execution context provides runtime access and metadata:
+
+:::usage{language="ts"}
+const context = {
+  toolCallId: 'call-123',
+  toolId: 'workspace-fs',
+  runtime,  // VibesRuntime instance for queries
+  scope: runtime.scope,  // Hardware + purpose scope
+  workspacePath: '/path/to/workspace',
+  // Additional surface-specific context
+  mcpSessionId: 'session-456'  // MCP surface
+};
+:::
+
+## Input validation
+
+Tools validate inputs against their schema:
+
+:::usage{language="ts"}
+// Tool descriptor includes input schema
+const tool = runtime.query('tools/tool')
+  .withId('workspace-fs')
+  .firstDescriptor();
+
+// Schema validation before execution
+import * as z from 'zod/v4';
+
+const inputSchema = z.object({
+  path: z.string(),
+  encoding: z.enum(['utf-8', 'base64']).optional()
+});
+
+const validated = inputSchema.parse({
+  path: '/src/index.ts'
+});
+:::
+
+## Agent Skills adapter (\`tool-adapter.skill\`)
+
+Codegen-only \`tools/adapter\` surface — generates \`SKILL.md\` trees (not execution). Used by \`vibes dev external skills generate\` and the in-package External agent-pack projection. Implementation: \`@vibesdotdev/tools/adapters/skill\`.
+
+## Progress reporting
+
+Tools can report progress during execution via \`ToolCallContext.sendProgress\`:
+
+:::usage{language="ts"}
+await invokeTool({
+  runtime,
+  toolId: 'long-running-tool',
+  input: {},
+  ctx: {
+    callId: 'call-1',
+    logger,
+    sendProgress: (p) => console.log(p.status, p.percent)
+  }
+});
+:::
+
+Progress object structure:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| \`percent\` | number | 0-100 completion |
+| \`status\` | string | Human-readable status |
+| \`detail\` | unknown | Surface-specific detail |
+
+## Result handling
+
+\`invokeTool\` returns the tool implementation result directly. Validation and tier denials throw before the runner executes:
+
+:::usage{language="ts"}
+import { invokeTool } from '@vibesdotdev/tools/execution/invoke';
+
+const content = await invokeTool({
+  runtime,
+  toolId: 'workspace-fs',
+  input: { action: 'read', path: '/src/index.ts' },
+  ctx: { callId: 'call-1', logger }
+});
+:::
+
+## Error handling
+
+Failures surface as thrown errors (validation, tier enforcement, tool implementation). Hook-bus \`tools/tool.error\` subscribers may attach \`recoveryHint\` metadata:
+
+:::usage{language="ts"}
+import { ToolInputValidationError } from '@vibesdotdev/tools/execution/core';
+
+try {
+  await invokeTool({ runtime, toolId: 'workspace-fs', input: {}, ctx });
+} catch (error) {
+  if (error instanceof ToolInputValidationError) {
+    console.error('Invalid input:', error.issues);
+  }
+  throw error;
+}
+:::
+
+## Tool calling from AI
+
+MCP and in-app loops map model tool calls to \`invokeTool\` — not \`tools/adapter.execute\`:
+
+:::usage{language="ts"}
+for (const call of modelToolCalls) {
+  const result = await invokeTool({
+    runtime,
+    toolId: call.name,
+    input: call.arguments,
+    ctx: { callId: call.id, logger }
+  });
+}
+:::
+
+## Codegen adapters (no execution)
+
+These \`tools/adapter\` ids emit host-native documentation artifacts; they do not
+generate executable code or run tools. Executable tool projection belongs to host
+plugins that consume the shared harness (\`external/harness/tool-projection\`).
+
+| Adapter id | Package | Output |
+|------------|---------|--------|
+| \`tool-adapter.skill\` | \`@vibesdotdev/tools/adapters/skill\` | \`SKILL.md\` trees |
+| \`tool-adapter.cursor\` | \`@vibesdotdev/integrations-cursor/adapters/plugin\` | \`.cursor/rules\` + skills |
+
+Protocol MCP serving lives in \`@vibesdotdev/mcp\`, not in \`tools/adapter\`.
+
+## Related descriptors
+
+:::descriptor{kind="docs/topic" id="tools.providers"}
+:::
+
+:::descriptor{kind="docs/topic" id="tools.ui"}
+:::
+
+:::descriptor{kind="docs/topic" id="ai.generation"}
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tools.invoke',
+    title: 'Tool Invocation',
+    summary: 'Tool invocation API, input validation, execution context, and result handling',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'tools',
+    order: 2,
+    tags: ['tools', 'invocation', 'execution', 'validation'],
+    surfaces: ['cli', 'web', 'in-app'],
+    hardware: ['consumer', 'cloud'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=invoke.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"invoke.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/invoke.docs.descriptor.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoLhB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,cAAc;IAClB,KAAK,EAAE,iBAAiB;IACxB,OAAO,EAAE,+EAA+E;IACxF,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC;IACxD,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/list.docs.descriptor.d.ts

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

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

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

package/dist/docs/list.docs.descriptor.js

@@ -0,0 +1,107 @@
+// Inlined markdown body — avoids readFileSync at module init time, which
+// breaks in bundled contexts (e.g., compiled vibes binary where
+// import.meta.url resolves to /$bunfs/root/).
+const listMarkdown = `---
+title: Tools List
+summary: Enumerate registered tools available to the current runtime
+tags: [tools, cli, agent]
+---
+
+The \`tools.list\` command enumerates every \`tools/tool\` descriptor registered
+with the runtime. Each entry shows the tool's id, the adapter it resolves
+through, and a short description.
+
+:::descriptor{kind="cli/command" id="tools.list"}
+:::
+
+## Common use
+
+Most agent surfaces (\`bridge\`, MCP servers, the in-app palette) consume the
+same registry. A registered tool is reachable everywhere; an unregistered one
+is reachable nowhere — there is no scoped fallback.
+
+:::shell
+vibes tools list
+vibes tools list --local
+vibes tools list --json | jq '.[] | select(.source=="local") | .id'
+:::
+
+Project tools auto-loaded from \`.vibes/tools\` are tagged \`source: "local"\`
+(and sort first in the table). \`--local\` shows only that catalog.
+
+## Programmatic access
+
+The same registry is reachable from any package via the runtime query API:
+
+:::usage{language="ts"}
+const tools = runtime.query('tools/tool').descriptors();
+for (const t of tools) {
+  console.log(t.id, t.description);
+}
+:::
+
+## Descriptions agents see
+
+When a tool declares \`mcpDescription\`, list and inspect prefer it over the long
+\`description\` field (that is the MCP / agent surface, including \`Ex:\` examples).
+
+## Related
+
+:::card{title="See also"}
+- \`vibes tools inspect <id>\` — describe a single tool (schema + mcpDescription)
+- \`tools.authoring\` — how to write descriptors agents can call correctly
+- \`vibes docs man cli/command tools.list\` — this page via the subject form
+:::
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'tools.list',
+    title: 'Tools List',
+    summary: 'Enumerate registered tools available to the current runtime',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: listMarkdown
+    },
+    parent: 'tools',
+    order: 1,
+    tags: ['tools', 'cli', 'agent'],
+    surfaces: ['cli', 'web', 'in-app'],
+    subject: { kind: 'cli/command', id: 'tools.list' },
+    man: {
+        name: 'tools.list — enumerate registered tools',
+        section: 1,
+        synopsis: 'vibes tools list [--local] [--scope <scope>] [-c <category>] [--json]',
+        options: [
+            {
+                flag: '--local',
+                description: 'Only project tools from .vibes/tools (source=local after auto-load)'
+            },
+            {
+                flag: '--scope <scope>',
+                description: 'Filter by hardware scope (consumer|cloud)'
+            },
+            { flag: '-c, --category <category>', description: 'Filter by category' },
+            { flag: '--json', description: 'Output as JSON instead of a table' }
+        ],
+        examples: [
+            {
+                description: 'List all tools as a table',
+                command: 'vibes tools list'
+            },
+            {
+                description: 'Only project-local tools',
+                command: 'vibes tools list --local'
+            },
+            {
+                description: 'List ids only, one per line',
+                command: "vibes tools list --json | jq -r '.[] | .id'"
+            }
+        ],
+        seeAlso: ['tools.info', 'tools.invoke']
+    },
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=list.docs.descriptor.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/list.docs.descriptor.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,gEAAgE;AAChE,8CAA8C;AAC9C,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDpB,CAAC;AAEF,MAAM,UAAU,GAAwB;IACvC,IAAI,EAAE,YAAY;IAClB,EAAE,EAAE,YAAY;IAChB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,6DAA6D;IACtE,IAAI,EAAE;QACL,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK;QACjB,MAAM,EAAE,YAAY;KACpB;IACD,MAAM,EAAE,OAAO;IACf,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC;IAClC,OAAO,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,YAAY,EAAE;IAClD,GAAG,EAAE;QACJ,IAAI,EAAE,yCAAyC;QAC/C,OAAO,EAAE,CAAC;QACV,QAAQ,EAAE,uEAAuE;QACjF,OAAO,EAAE;YACR;gBACC,IAAI,EAAE,SAAS;gBACf,WAAW,EAAE,qEAAqE;aAClF;YACD;gBACC,IAAI,EAAE,iBAAiB;gBACvB,WAAW,EAAE,2CAA2C;aACxD;YACD,EAAE,IAAI,EAAE,2BAA2B,EAAE,WAAW,EAAE,oBAAoB,EAAE;YACxE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE;SACpE;QACD,QAAQ,EAAE;YACT;gBACC,WAAW,EAAE,2BAA2B;gBACxC,OAAO,EAAE,kBAAkB;aAC3B;YACD;gBACC,WAAW,EAAE,0BAA0B;gBACvC,OAAO,EAAE,0BAA0B;aACnC;YACD;gBACC,WAAW,EAAE,6BAA6B;gBAC1C,OAAO,EAAE,6CAA6C;aACtD;SACD;QACD,OAAO,EAAE,CAAC,YAAY,EAAE,cAAc,CAAC;KACvC;IACD,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,OAAO,EAAE,IAAI;CACb,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/openapi-ui/lib/json-schema.d.ts

@@ -0,0 +1,7 @@
+/**
+ * JSON Schema Types
+ *
+ * Re-export from schemas.
+ */
+export type { JSONSchema } from './schemas/index.ts';
+//# sourceMappingURL=json-schema.d.ts.map

package/dist/docs/openapi-ui/lib/json-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.d.ts","sourceRoot":"","sources":["../../../../src/docs/openapi-ui/lib/json-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/docs/openapi-ui/lib/json-schema.js

@@ -0,0 +1,7 @@
+/**
+ * JSON Schema Types
+ *
+ * Re-export from schemas.
+ */
+export {};
+//# sourceMappingURL=json-schema.js.map

package/dist/docs/openapi-ui/lib/json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema.js","sourceRoot":"","sources":["../../../../src/docs/openapi-ui/lib/json-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/docs/openapi-ui/lib/schema-example.d.ts

@@ -0,0 +1,5 @@
+import type { JsonValue } from "@vibesdotdev/kernel/schemas/json";
+import type { JSONSchema } from "./schemas/index.ts";
+export declare function jsonSchemaToExample(schema?: JSONSchema, key?: string): JsonValue;
+export declare function jsonSchemaToExampleString(schema?: JSONSchema): string;
+//# sourceMappingURL=schema-example.d.ts.map

package/dist/docs/openapi-ui/lib/schema-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-example.d.ts","sourceRoot":"","sources":["../../../../src/docs/openapi-ui/lib/schema-example.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AA6BrD,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CA8ChF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAGrE"}