@vibesdotdev/hq 0.0.0-stage → 1.0.0-rc.1

package/dist/dashboard.js

@@ -0,0 +1,371 @@
+/**
+ * OS Dashboard Projections
+ *
+ * Dashboard helpers for rendering surface artifacts and machine info.
+ * Originally from vibesos-system, migrated to os.
+ */
+// Keep the server store behind a dynamic wall so browser dashboard consumers do
+// not load storage adapters.
+async function listSurfaceNotifications(...args) {
+    const mod = await import('@vibesdotdev/os/surface');
+    return mod.listSurfaceNotifications(...args);
+}
+async function getSurfaceNotification(...args) {
+    const mod = await import('@vibesdotdev/os/surface');
+    return mod.getSurfaceNotification(...args);
+}
+import { selectAppletArtifactIndex } from '@vibesdotdev/applets';
+import * as z from 'zod/v4';
+export const DashboardArtifactStatusSchema = z.enum([
+    'pending',
+    'complete',
+    'error',
+    'approved',
+    'discarded'
+]);
+/**
+ * Map a surface notification to a dashboard artifact summary
+ */
+export function mapDashboardArtifact(notification) {
+    // Authoritative server-stamped provenance when present; the brittle
+    // `channelId.split('-')[0]` parse is now only a legacy fallback.
+    const agentId = notification.agentId ?? notification.channelId.split('-')[0] ?? 'unknown';
+    const artifacts = notification.artifacts || [];
+    const selectedIndex = selectAppletArtifactIndex(notification);
+    const selectedArtifact = selectedIndex >= 0 ? artifacts[selectedIndex] : undefined;
+    const previewArtifact = selectedArtifact ?? artifacts[0];
+    const artifactType = selectedArtifact?.type ?? artifacts[0]?.type ?? 'note';
+    return {
+        id: notification.id,
+        artifactType,
+        status: DashboardArtifactStatusSchema.parse(notification.status),
+        agentId,
+        ownerType: notification.ownerType,
+        ownerId: notification.ownerId,
+        summary: notification.summary,
+        createdAt: notification.createdAt,
+        sessionId: notification.sessionId ?? null,
+        componentRef: previewArtifact?.componentRef ?? null,
+        source: previewArtifact?.source ?? null,
+        sourceFormat: previewArtifact?.sourceFormat ?? null,
+        browserRuntime: previewArtifact?.browserRuntime ?? false,
+        content: previewArtifact?.content ?? {},
+        actions: notification.actions.map((a) => ({
+            label: a.label,
+            command: a.command,
+            args: a.args ?? []
+        })),
+        scope: notification.scope
+    };
+}
+function countLabel(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+function formatSourceKind(sourceType) {
+    return sourceType.split(/[-_]/g).filter(Boolean).join(' ');
+}
+function stimulusNoun(sourceType) {
+    if (sourceType.includes('schedule'))
+        return 'scheduled task';
+    if (sourceType.includes('webhook'))
+        return 'webhook delivery';
+    if (sourceType.includes('integration'))
+        return 'integration event';
+    if (sourceType.includes('message') || sourceType.includes('channel'))
+        return 'message';
+    if (sourceType.includes('system'))
+        return 'system event';
+    return `${formatSourceKind(sourceType)} event`;
+}
+function identityValues(agent) {
+    return [agent.id, agent.agentId, agent.deploymentId, agent.name.toLowerCase()].filter((value) => Boolean(value));
+}
+function isDefaultAgent(agent, defaultAgentId) {
+    const normalizedDefault = defaultAgentId.toLowerCase();
+    return identityValues(agent).some((value) => value.toLowerCase() === normalizedDefault);
+}
+function sourceHasAgent(source, agent) {
+    const sourceAgentIds = new Set(source.agentIds);
+    return (identityValues(agent).some((value) => sourceAgentIds.has(value)) ||
+        (agent.eventSourceIds ?? []).includes(source.id));
+}
+function statusLabel(status) {
+    if (status === 'needs_agent')
+        return 'Needs agent';
+    if (status === 'agent_offline')
+        return 'Agent offline';
+    return status.charAt(0).toUpperCase() + status.slice(1);
+}
+function agentCanReceiveEvents(agent) {
+    return agent.status === undefined || agent.status === 'active' || agent.status === 'idle';
+}
+function policyStatus(source, boundAgents) {
+    if (source.status === 'error')
+        return 'error';
+    if (source.status === 'disconnected')
+        return 'disconnected';
+    if (source.status === 'paused')
+        return 'paused';
+    if (boundAgents.length === 0)
+        return 'needs_agent';
+    if (!boundAgents.some(agentCanReceiveEvents))
+        return 'agent_offline';
+    return 'live';
+}
+function policyHeadline(status, source, primaryAgentName) {
+    if (status === 'live') {
+        return primaryAgentName ? `Routes to ${primaryAgentName}` : 'Routes to bound agents';
+    }
+    if (status === 'needs_agent')
+        return 'Not routed to an agent';
+    if (status === 'agent_offline')
+        return primaryAgentName ? `${primaryAgentName} is offline` : 'Bound agent is offline';
+    if (status === 'paused')
+        return 'Paused before execution';
+    if (status === 'disconnected')
+        return 'Integration disconnected';
+    if (status === 'error')
+        return `${source.name} needs repair`;
+    return 'Not ready';
+}
+function policyDetail(status, source, primaryAgentName) {
+    const noun = stimulusNoun(source.sourceType);
+    if (status === 'live') {
+        return primaryAgentName
+            ? `Events from ${source.name} feed ${primaryAgentName}; each ${noun} can become a message, approval request, task, or generated artifact depending on policy.`
+            : `Events from ${source.name} feed live agents; each ${noun} can be triaged and routed through HQ surfaces.`;
+    }
+    if (status === 'needs_agent') {
+        return `${source.name} is configured, but no live-agent deployment is bound to this source.`;
+    }
+    if (status === 'agent_offline') {
+        return primaryAgentName
+            ? `${source.name} is bound to ${primaryAgentName}, but that agent is not currently receiving events.`
+            : `${source.name} is bound, but no bound agent is currently receiving events.`;
+    }
+    if (status === 'paused') {
+        return `${source.name} is paused; inbound ${noun}s are intentionally held before agent execution.`;
+    }
+    if (status === 'disconnected') {
+        return `${source.name} is disconnected; restore the integration before events can reach agents.`;
+    }
+    return `${source.name} is reporting an error; repair the source before trusting this trigger.`;
+}
+function nextPolicyAction(status) {
+    if (status === 'live')
+        return 'Monitor delivery and review agent actions.';
+    if (status === 'needs_agent')
+        return 'Bind Marshal or another live agent.';
+    if (status === 'agent_offline')
+        return 'Start or repair the bound agent.';
+    if (status === 'paused')
+        return 'Resume when the source policy is ready.';
+    if (status === 'disconnected')
+        return 'Reconnect the integration.';
+    return 'Inspect and repair the source.';
+}
+function bindingActionForStatus(status) {
+    if (status === 'needs_agent')
+        return 'bind_default_agent';
+    if (status === 'agent_offline')
+        return 'start_agent';
+    if (status === 'paused')
+        return 'resume_source';
+    if (status === 'live')
+        return 'review_live_route';
+    return 'repair_source';
+}
+function bindingIntentTitle(action, source, targetAgentName) {
+    if (action === 'bind_default_agent')
+        return `Bind ${targetAgentName} to ${source.name}`;
+    if (action === 'start_agent')
+        return `Start ${targetAgentName} for ${source.name}`;
+    if (action === 'resume_source')
+        return `Resume ${source.name}`;
+    if (action === 'repair_source')
+        return `Repair ${source.name}`;
+    return `Review ${source.name} routing`;
+}
+function bindingIntentDescription(action, source, targetAgentName) {
+    const noun = stimulusNoun(source.sourceType);
+    if (action === 'bind_default_agent') {
+        return `${source.name} is active but has no agent binding. Review a plan before new ${noun}s route to ${targetAgentName}.`;
+    }
+    if (action === 'start_agent') {
+        return `${source.name} is bound to ${targetAgentName}, but the agent is offline. Review a start plan before inbound ${noun}s execute.`;
+    }
+    if (action === 'resume_source') {
+        return `${source.name} is paused. Review the resume plan and guardrails before inbound ${noun}s execute again.`;
+    }
+    if (action === 'repair_source') {
+        return `${source.name} is not delivering events reliably. Review the repair plan before trusting this trigger.`;
+    }
+    return `${source.name} already routes to ${targetAgentName}. Review the current route, outcomes, and guardrails before changing the policy.`;
+}
+function bindingIntentCta(action) {
+    if (action === 'bind_default_agent')
+        return 'Request binding review';
+    if (action === 'start_agent')
+        return 'Request start review';
+    if (action === 'resume_source')
+        return 'Request resume review';
+    if (action === 'repair_source')
+        return 'Request repair review';
+    return 'Request route review';
+}
+function resolveDashboardStimulusBindingIntent(args) {
+    const action = bindingActionForStatus(args.status);
+    const targetAgentId = args.primaryAgentId ?? args.defaultAgentId;
+    const targetAgentName = args.primaryAgentName ?? args.defaultAgentName;
+    let outcomes;
+    if (action === 'bind_default_agent') {
+        outcomes = ['Attach source to target agent', 'Keep source identity on every event'];
+    }
+    else if (action === 'start_agent') {
+        outcomes = ['Start target agent', 'Verify source delivery after heartbeat'];
+    }
+    else if (action === 'repair_source') {
+        outcomes = ['Restore source delivery', 'Verify credentials and provider health'];
+    }
+    else if (action === 'resume_source') {
+        outcomes = ['Resume event delivery', 'Confirm guardrails before execution'];
+    }
+    else {
+        outcomes = ['Audit current routing', 'Confirm outcomes and guardrails'];
+    }
+    const plan = {
+        kind: 'hq.source.binding',
+        action,
+        sourceId: args.source.id,
+        sourceName: args.source.name,
+        sourceType: args.source.sourceType,
+        status: args.status,
+        targetAgentId,
+        targetAgentName,
+        requiredReview: true,
+        outcomes,
+        evidence: args.evidence
+    };
+    return {
+        sourceId: args.source.id,
+        sourceName: args.source.name,
+        sourceType: args.source.sourceType,
+        action,
+        title: bindingIntentTitle(action, args.source, targetAgentName),
+        description: bindingIntentDescription(action, args.source, targetAgentName),
+        ctaLabel: bindingIntentCta(action),
+        requestedBy: 'marshal',
+        targetAgentId,
+        targetAgentName,
+        plan,
+        evidence: args.evidence
+    };
+}
+function policyOutcomes(source, hasUserMessageSurface, hasPlanConfirmationSurface) {
+    const outcomes = [`Triage each ${stimulusNoun(source.sourceType)}`];
+    if (hasUserMessageSurface)
+        outcomes.push('Send user-visible messages');
+    if (hasPlanConfirmationSurface)
+        outcomes.push('Request plan confirmations');
+    outcomes.push('Create or update workboard tasks');
+    return outcomes;
+}
+function policyGuardrails(status, hasUserMessageSurface, hasPlanConfirmationSurface) {
+    if (status !== 'live') {
+        return ['No agent action should run until this source is active, bound, and receiving events.'];
+    }
+    const guardrails = ['Every inbound event keeps its source identity attached.'];
+    if (hasPlanConfirmationSurface) {
+        guardrails.push('Risky or irreversible plans require approval before execution.');
+    }
+    if (hasUserMessageSurface) {
+        guardrails.push('Agent-to-user messages land in the workboard notification surface.');
+    }
+    return guardrails;
+}
+export function resolveDashboardStimulusPolicies(input) {
+    const defaultAgentId = input.defaultAgentId ?? 'marshal';
+    const defaultAgentName = input.defaultAgentName ?? 'Marshal';
+    const hasUserMessageSurface = input.hasUserMessageSurface === true;
+    const hasPlanConfirmationSurface = input.hasPlanConfirmationSurface === true;
+    return input.sources.map((source) => {
+        const boundAgents = input.agents.filter((agent) => sourceHasAgent(source, agent));
+        const primaryAgent = boundAgents.find((agent) => isDefaultAgent(agent, defaultAgentId)) ?? boundAgents[0] ?? null;
+        const status = policyStatus(source, boundAgents);
+        const primaryAgentId = primaryAgent?.agentId ?? primaryAgent?.id ?? null;
+        const eventCount = Math.max(0, source.eventCount ?? 0);
+        const evidence = [
+            `source:${source.id}`,
+            `agents:${countLabel(boundAgents.length, 'binding')}`,
+            `events:${eventCount}`
+        ];
+        return {
+            sourceId: source.id,
+            sourceName: source.name,
+            sourceType: source.sourceType,
+            status,
+            statusLabel: statusLabel(status),
+            headline: policyHeadline(status, source, primaryAgent?.name ?? null),
+            detail: policyDetail(status, source, primaryAgent?.name ?? null),
+            primaryAgentId,
+            primaryAgentName: primaryAgent?.name ?? null,
+            agentCount: boundAgents.length,
+            eventCount,
+            lastEvent: source.lastEvent ?? null,
+            outcomes: policyOutcomes(source, hasUserMessageSurface, hasPlanConfirmationSurface),
+            guardrails: policyGuardrails(status, hasUserMessageSurface, hasPlanConfirmationSurface),
+            nextAction: nextPolicyAction(status),
+            evidence,
+            bindingIntent: resolveDashboardStimulusBindingIntent({
+                source,
+                status,
+                primaryAgentId,
+                primaryAgentName: primaryAgent?.name ?? null,
+                defaultAgentId,
+                defaultAgentName,
+                evidence
+            })
+        };
+    });
+}
+/**
+ * Load the owner's dashboard artifacts from surface notifications. `owner` is the
+ * server-derived tenancy gate (from `actingScopeFromLocals` at the endpoint, or
+ * `SYSTEM_OWNER` for the vibes-internal Marshal surface) — only that owner's rows
+ * are returned, so the previous client-supplied `agentId` query filter is no longer
+ * an authz control.
+ */
+export async function loadDashboardArtifacts(runtime, owner, limit = 20) {
+    const notifications = await listSurfaceNotifications(runtime, owner);
+    return notifications
+        .map(mapDashboardArtifact)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+        .slice(0, limit);
+}
+/**
+ * Load one of the owner's dashboard artifacts by id from its owning surface
+ * notification. A foreign-owner artifact is invisible (`null`) → 404 upstream.
+ */
+export async function getDashboardArtifactById(runtime, owner, id) {
+    const notification = await getSurfaceNotification(runtime, owner, id);
+    if (!notification)
+        return null;
+    return mapDashboardArtifact(notification);
+}
+/**
+ * Update the status of one of the owner's dashboard artifacts (resolves the surface
+ * notification). Owner-scoped end-to-end: a foreign-owner artifact resolves to
+ * `null` → 404 upstream, never mutating another owner's row.
+ */
+export async function updateDashboardArtifactStatus(runtime, owner, id, status) {
+    const existing = await getSurfaceNotification(runtime, owner, id);
+    if (!existing)
+        return null;
+    const { resolveSurfaceNotification } = await import('@vibesdotdev/os/surface');
+    await resolveSurfaceNotification(runtime, owner, id, status);
+    const updated = await getSurfaceNotification(runtime, owner, id);
+    if (!updated)
+        return null;
+    return mapDashboardArtifact(updated);
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/dashboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../src/dashboard.ts"],"names":[],"mappings":"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"}

package/dist/docs/hq.machines.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * User-flow docs for the HQ Machines surface (pairing, fleet view).
+ */
+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 ["in-app", "web"];
+    hardware: readonly ["consumer"];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=hq.machines.docs.descriptor.d.ts.map

package/dist/docs/hq.machines.docs.descriptor.d.ts.map

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

package/dist/docs/hq.machines.docs.descriptor.js

@@ -0,0 +1,65 @@
+/**
+ * User-flow docs for the HQ Machines surface (pairing, fleet view).
+ */
+const markdown = `---
+title: Machines
+summary: Connect and manage machines from HQ — pair by code, address, or install command
+tags: [hq, machines, fleet, pairing]
+parent: hq
+order: 10
+---
+
+# Machines
+
+The Machines page in HQ shows every computer you've connected — on your local network, paired by
+code, or added by address. From here you can open a terminal on any online machine.
+
+## Adding your first machine
+
+Click **Add your first machine** on the empty state. Copy the generated enrollment command and run it on the machine you want to connect. HQ polls automatically and closes the dialog when the machine comes online — usually within 30 seconds.
+
+For additional pairing options (6-digit codes, direct address entry), open your configured Platform host-management surface.
+
+## Machine status
+
+| Status | Meaning |
+|---|---|
+| **Online** | Reachable right now — you can open a terminal |
+| **Enrolled, not reachable** | Paired but currently offline or outside your network |
+| **Offline** | Not seen recently |
+
+## Opening a terminal
+
+Click **Open terminal** on any online machine. The Terminal page opens with that machine
+preselected. See [hq.terminal](hq.terminal) for keyboard shortcuts and session management.
+
+## Removing a machine
+
+Click the info icon (ⓘ) on any directly-added machine, then choose **Remove**. This closes any
+open terminal sessions to that machine and removes it from your fleet. You can re-add it at any
+time.
+
+## Related topics
+
+- [hq.terminal](hq.terminal) — open a terminal on a connected machine
+- [hq.sessions](hq.sessions) — create and manage code sessions on any machine
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'hq.machines',
+    title: 'Machines',
+    summary: 'Connect and manage machines from HQ — pair by code, address, or install command',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'hq',
+    order: 10,
+    tags: ['hq', 'machines', 'fleet', 'pairing'],
+    surfaces: ['in-app', 'web'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=hq.machines.docs.descriptor.js.map

package/dist/docs/hq.machines.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hq.machines.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/hq.machines.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ChB,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,UAAU;IACjB,OAAO,EAAE,iFAAiF;IAC1F,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,QAAQ;KACjB;IACD,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,SAAS,CAAC;IAC5C,QAAQ,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAU;IACpC,QAAQ,EAAE,CAAC,UAAU,CAAU;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/hq.sessions.docs.descriptor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * User-flow docs for the HQ Sessions surface (code sessions).
+ */
+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 ["in-app", "web"];
+    hardware: readonly ["consumer"];
+    enabled: boolean;
+};
+export default descriptor;
+//# sourceMappingURL=hq.sessions.docs.descriptor.d.ts.map

package/dist/docs/hq.sessions.docs.descriptor.d.ts.map

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

package/dist/docs/hq.sessions.docs.descriptor.js

@@ -0,0 +1,74 @@
+/**
+ * User-flow docs for the HQ Sessions surface (code sessions).
+ */
+const markdown = `---
+title: Sessions
+summary: Create and manage code sessions — interactive workspaces with persistent file access
+tags: [hq, sessions, code, workspace]
+parent: hq
+order: 30
+---
+
+# Sessions
+
+Sessions are persistent workspaces where you can run commands, edit files, and pick up where you
+left off across reloads. Sessions run on cloud infrastructure or on connected fleet machines.
+
+## Creating a session
+
+1. Click **New session** at the top right of the Sessions page.
+2. Choose a target (cloud session for running commands, or a connected fleet machine for interactive terminal).
+3. Optionally link a repository and branch.
+4. Click **Create** — you're taken to the new session.
+
+## Session types
+
+**Interactive terminal** (local or connected machines): a full shell you can attach to. Click
+**Open terminal** on the session detail page to connect. See [hq.terminal](hq.terminal) for
+keyboard shortcuts.
+
+**Run commands** (cloud sessions): enter individual commands and see their output as cards. You
+can re-run any card. This mode is clearly labeled so you know what to expect.
+
+## Resuming a session after reload
+
+Sessions listed on the Sessions page are still running. Click the session name to return to it.
+If you were mid-terminal, click **Open terminal** to reattach — the shell picks up from where
+you left off (scroll history replays automatically).
+
+## Browsing the workspace
+
+Session files are accessible from the session detail page. The workspace browser shows the files
+inside the session's working directory so you can navigate and reference them without a separate
+terminal.
+
+## Deleting a session
+
+Click the trash icon on any session (or on the session detail page). You'll see a confirmation
+that lists exactly what will be removed — the running session and its workspace files. This
+cannot be undone.
+
+## Related topics
+
+- [hq.machines](hq.machines) — add a machine to create sessions on it
+- [hq.terminal](hq.terminal) — attach to a running session as an interactive terminal
+`;
+const descriptor = {
+    kind: 'docs/topic',
+    id: 'hq.sessions',
+    title: 'Sessions',
+    summary: 'Create and manage code sessions — interactive workspaces with persistent file access',
+    body: {
+        type: 'markdown',
+        sourceType: 'raw',
+        source: markdown
+    },
+    parent: 'hq',
+    order: 30,
+    tags: ['hq', 'sessions', 'code', 'workspace'],
+    surfaces: ['in-app', 'web'],
+    hardware: ['consumer'],
+    enabled: true
+};
+export default descriptor;
+//# sourceMappingURL=hq.sessions.docs.descriptor.js.map

package/dist/docs/hq.sessions.docs.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hq.sessions.docs.descriptor.js","sourceRoot":"","sources":["../../src/docs/hq.sessions.docs.descriptor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDhB,CAAC;AAEF,MAAM,UAAU,GAAG;IACjB,IAAI,EAAE,YAAqB;IAC3B,EAAE,EAAE,aAAa;IACjB,KAAK,EAAE,UAAU;IACjB,OAAO,EAAE,sFAAsF;IAC/F,IAAI,EAAE;QACJ,IAAI,EAAE,UAAmB;QACzB,UAAU,EAAE,KAAc;QAC1B,MAAM,EAAE,QAAQ;KACjB;IACD,MAAM,EAAE,IAAI;IACZ,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,CAAC;IAC7C,QAAQ,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAU;IACpC,QAAQ,EAAE,CAAC,UAAU,CAAU;IAC/B,OAAO,EAAE,IAAI;CACd,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/docs/hq.surfaces.docs.descriptor.d.ts

@@ -0,0 +1,38 @@
+/**
+ * User-flow docs for HQ's fleet and terminal surfaces (Machines, Terminal, Sessions).
+ *
+ * Structurally typed, like the three sibling topics in this directory: this
+ * package does not depend on `@vibesdotdev/docs-contracts`, and the shape is
+ * validated for real against `DocsTopicDescriptorSchema` when the docs build
+ * reads it out of the registry.
+ */
+declare const descriptor: {
+    kind: "docs/topic";
+    id: string;
+    title: string;
+    summary: string;
+    body: {
+        type: "markdown";
+        sourceType: "raw";
+        source: string;
+    };
+    parent: string;
+    order: number;
+    tags: string[];
+    surfaces: readonly ["web"];
+    hardware: readonly ["cloud", "consumer"];
+    enabled: boolean;
+    man: {
+        name: string;
+        section: number;
+        synopsis: string;
+        options: never[];
+        examples: {
+            description: string;
+            command: string;
+        }[];
+        seeAlso: string[];
+    };
+};
+export default descriptor;
+//# sourceMappingURL=hq.surfaces.docs.descriptor.d.ts.map

package/dist/docs/hq.surfaces.docs.descriptor.d.ts.map

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