docs: complete public API documentation

guest-room/mod.ts

@@ -20,8 +20,7 @@
 // path; nothing here names a guest — a test enforces that the engine source is
 // guest-agnostic, so the seam can't silently re-couple.
 
-/** A door name lands in a mount path (`/run/<name>.sock`) and an env var, so it
- *  must be path-safe — no `/`, no `..`, no injection into the mount spec. */
+/** Regex validating door names: must be lowercase alphanumeric and hyphens only (path-safe). */
 export const DOOR_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
 
 // ── Door transport ───────────────────────────────────────────────────────────
@@ -68,6 +67,7 @@ export function transportString(t: DoorTransport): string {
   }
 }
 
+/** Environment variable record. */
 export type Env = Record<string, string | undefined>;
 
 /** Default host socket for a daemon, private-dir-first. Pure (no I/O) so door

guest-room/protocol.ts

@@ -14,12 +14,14 @@ import type { Socket } from "bun";
 
 // ── Protocol types (shared across all doors) ────────────────────────────────
 
+/** Request envelope sent to a door daemon. */
 export type RequestEnvelope = {
   id: string;
   method: string;
   params?: Record<string, unknown>;
 };
 
+/** Response envelope from a door daemon. */
 export type ResponseEnvelope = {
   id: string;
   ok: boolean;
@@ -41,10 +43,12 @@ export function err(id: string, code: string, message: string): ResponseEnvelope
 
 // ── Connection handler ──────────────────────────────────────────────────────
 
+/** Handler function for a door method. */
 export type MethodHandler = (
   params: Record<string, unknown>,
 ) => Promise<unknown> | unknown;
 
+/** Registry mapping method names to handler functions. */
 export type MethodRegistry = Record<string, MethodHandler>;
 
 /**

lib/concierge.ts

@@ -32,6 +32,7 @@ function conciergeSocket(): string {
   return `${home}/.claude-box/concierged.sock`;
 }
 
+/** Options for registering a capability provider with the concierge. */
 export type RegisterOptions = {
   /** Logical capability name, e.g. "scout", "egress". */
   capability: string;
@@ -60,6 +61,7 @@ export async function resolve(capability: string, want: string[] = []): Promise<
   return door;
 }
 
+/** Summary of a capability currently served in the concierge registry. */
 export type CapabilityRow = { capability: string; grants: string; providers: number };
 
 /** List the capabilities currently served (discovery/introspection). */

lib/keeper.ts

@@ -24,6 +24,7 @@ const connect = Bun.connect;
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
+/** Options for creating a signed commit via keeperd. */
 export type CommitOptions = {
   /** Repository path */
   repo: string;
@@ -39,6 +40,7 @@ export type CommitOptions = {
   amend?: boolean;
 };
 
+/** Result of a signed commit operation via keeperd. */
 export type CommitResult = {
   commit: string;
   attestation?: {
@@ -49,6 +51,7 @@ export type CommitResult = {
   };
 };
 
+/** Options for pushing to a remote repository via keeperd. */
 export type PushOptions = {
   /** Repository path */
   repo: string;
@@ -62,27 +65,32 @@ export type PushOptions = {
   setUpstream?: boolean;
 };
 
+/** Result of a push operation via keeperd. */
 export type PushResult = {
   pushed: string;
   commits: string[];
 };
 
+/** Result of a sign operation via keeperd. */
 export type SignResult = {
   signature: string;
   keyId: string;
 };
 
+/** Result of a signature verification via keeperd. */
 export type VerifyResult = {
   valid: boolean;
   keyId?: string;
 };
 
+/** Health and status information from keeperd. */
 export type KeeperStatus = {
   version: string;
   uptime: number;
   signing: { enabled: boolean; keyId?: string };
 };
 
+/** Error from keeperd operations, with an error code for pattern matching. */
 export class KeeperError extends Error {
   code: string;
   constructor(code: string, message: string) {
@@ -260,10 +268,7 @@ export async function push(options: PushOptions): Promise<PushResult> {
   });
 }
 
-/** Model-A keeper write input: the host has already done the local, keyless
- *  `commit-tree` and ships the new commits as a commit-range bundle; keeperd
- *  imports them and performs ONLY the signed push. The host never grants the
- *  daemon commit authorship — that asymmetry is the isolation. */
+/** Options for import-and-push: the host builds commits locally (keyless) and keeperd signs the push. */
 export type ImportAndPushOptions = {
   /** Commit-range git bundle (base64) carrying the new commits the host built. */
   bundleBase64: string;
@@ -282,10 +287,7 @@ export type ImportAndPushOptions = {
   notesRef?: string;
 };
 
-/** keeperd's verdict for an import-and-push: `ok` carries the pushed identity
- *  (and the signed derivation when a ledger was requested; plus a `note` status
- *  when a `notesRef` was projected); `error` carries a branchable code. A
- *  non-`ok` verdict is data, not an exception. */
+/** Result of an import-and-push operation: either success with pushed identity or an error verdict. */
 export type ImportAndPushResult =
   | {
       status: "ok";
@@ -316,18 +318,15 @@ export async function importAndPush(
   });
 }
 
-/** A launch (L2) attestation request: attest that a room was launched holding
- *  exactly these doors. `manifest` is the room's resolved door set — authority is
- *  the held references, so the daemon digests it into the attestation. */
+/** Options for attesting a room launch: captures the doors held at launch time. */
 export type AttestLaunchOptions = {
   /** The launched room/box id (the subject of the launch attestation). */
   subject: string;
   /** The room's resolved door set / manifest (authority = held references). */
   manifest: unknown;
 };
 
-/** keeperd's verdict for an attest-launch: `ok` carries the signed L2 plus its
- *  content-address (`l2LaunchDigest`, what an L3 write links back to). */
+/** Result of a launch attestation: either a signed L2 with content address or an error. */
 export type AttestLaunchResult =
   | {
       status: "ok";

lib/runtime.ts

@@ -18,7 +18,7 @@ import {
   type RunDirFn,
 } from "../guest-room/daemon.ts";
 
-// Re-export protocol types for convenience
+// Re-export protocol types and functions for convenience.
 export {
   type RequestEnvelope,
   type ResponseEnvelope,
@@ -30,7 +30,7 @@ export {
   type MethodRegistry,
 } from "../guest-room/protocol.ts";
 
-// Re-export daemon utilities
+// Re-export daemon utilities.
 export { prepareSocket, type Env };
 
 /**

lib/scout.ts

@@ -20,13 +20,15 @@ const connect = Bun.connect;
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
+/** Options for fetching repository metadata via scoutd. */
 export type RepoOptions = {
   /** GitHub repo URL or owner/repo */
   url: string;
   /** Git ref (default: HEAD) */
   ref?: string;
 };
 
+/** Repository metadata fetched via scoutd. */
 export type RepoResult = {
   owner: string;
   repo: string;
@@ -36,6 +38,7 @@ export type RepoResult = {
   tarballUrl: string;
 };
 
+/** Options for fetching a pull request via scoutd. */
 export type PrOptions = {
   /** GitHub repo (owner/repo or URL) */
   repo: string;
@@ -47,6 +50,7 @@ export type PrOptions = {
   comments?: boolean;
 };
 
+/** Pull request details fetched via scoutd. */
 export type PrResult = {
   number: number;
   title: string;
@@ -69,6 +73,7 @@ export type PrResult = {
   }>;
 };
 
+/** Options for fetching a GitHub issue via scoutd. */
 export type IssueOptions = {
   /** GitHub repo (owner/repo or URL) */
   repo: string;
@@ -78,6 +83,7 @@ export type IssueOptions = {
   comments?: boolean;
 };
 
+/** GitHub issue details fetched via scoutd. */
 export type IssueResult = {
   number: number;
   title: string;
@@ -94,6 +100,7 @@ export type IssueResult = {
   }>;
 };
 
+/** Options for fetching a URL via scoutd. */
 export type FetchOptions = {
   /** URL to fetch */
   url: string;
@@ -103,6 +110,7 @@ export type FetchOptions = {
   maxSize?: number;
 };
 
+/** Response from fetching a URL via scoutd. */
 export type FetchResult = {
   url: string;
   status: number;
@@ -111,13 +119,15 @@ export type FetchResult = {
   body: string;
 };
 
+/** Options for downloading a file via scoutd. */
 export type DownloadOptions = {
   /** URL to download */
   url: string;
   /** Max size in bytes (default 100MB) */
   maxSize?: number;
 };
 
+/** Downloaded file content via scoutd (base64 encoded). */
 export type DownloadResult = {
   url: string;
   size: number;
@@ -126,13 +136,15 @@ export type DownloadResult = {
   data: string; // base64
 };
 
+/** Health and status information from scoutd. */
 export type ScoutStatus = {
   version: string;
   uptime: number;
   hasToken: boolean;
   allowlist: string[];
 };
 
+/** Error from scoutd operations, with an error code for pattern matching. */
 export class ScoutError extends Error {
   code: string;
   constructor(code: string, message: string) {

lib/spawn.ts

@@ -21,6 +21,7 @@ const connect = Bun.connect;
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
+/** Options for spawning a sub-box via launcherd. */
 export type SpawnOptions = {
   /** Account name (default: "personal") */
   account?: string;
@@ -40,6 +41,7 @@ export type SpawnOptions = {
   depth?: number;
 };
 
+/** Result of spawning a sub-box via launcherd. */
 export type SpawnResult = {
   launchId: string;
   pid: number;
@@ -57,6 +59,7 @@ export type SpawnResult = {
   };
 };
 
+/** Health, policy, and capability status from launcherd. */
 export type LauncherdStatus = {
   version: string;
   uptime: number;
@@ -74,6 +77,7 @@ export type LauncherdStatus = {
   rooms: Record<string, string>;
 };
 
+/** Information about a running or exited box. */
 export type BoxInfo = {
   launchId: string;
   account: string;
@@ -85,6 +89,7 @@ export type BoxInfo = {
   status: "running" | "exited";
 };
 
+/** Error from launcherd operations, with an error code for pattern matching. */
 export class LauncherdError extends Error {
   code: string;
   constructor(code: string, message: string) {