@synap-core/cli 1.7.0 → 1.10.0

package/dist/lib/installed.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Installed-awareness — which packages are already on the active pod.
+ * ===================================================================
+ *
+ * The pod stamps `workspace.settings.packageSlug` on every workspace it
+ * provisions from a package (Hub `GET /workspaces` surfaces it — see
+ * `workspaces.ts:508`). Cross-referencing the discovery catalog against that set
+ * lets `launch --list` / the picker / `market` mark what is already installed
+ * instead of re-offering it.
+ *
+ * NON-FATAL by design: if the pod is unreachable, unconfigured, or on an older
+ * build, this degrades to an empty set (no markers) rather than failing the
+ * discovery command — you can always browse the catalog offline.
+ */
+/** An installed workspace's package identity — slug plus (when the pod stamped one) its content version. */
+export interface InstalledTemplateInfo {
+    slug: string;
+    /**
+     * `settings.packageVersion`, when the pod stamped one — `GET /api/hub/workspaces`
+     * (`hub-protocol/rest/workspaces.ts`) projects it off `workspace.settings`.
+     * Undefined for workspaces the pod never version-stamped: installs that
+     * predate versioning, OR any install whose template only resolved from the
+     * frozen bundle (no CP cache hit — `resolveWorkspaceTemplate` returns no
+     * `version` for a bundle fallback). `market update` treats undefined as
+     * "can't check" rather than "outdated" — see `market.ts`'s `computeUpdates`.
+     */
+    version?: string;
+    workspaceId: string;
+    workspaceName: string;
+}
+/**
+ * Every installed workspace's `{slug, version, workspaceId, workspaceName}` —
+ * the raw material for "what's installed" (`fetchInstalledSlugs`) and "what's
+ * out of date" (`market update`'s `computeUpdates`). One Hub call, derived
+ * views. Unions TWO install shapes, mirroring the browser's
+ * `useInstalledPackageSlugs` (see that hook's doc for the full rationale):
+ *
+ *  1. `workspace.packageSlug` — a workspace-creating install (template).
+ *  2. `workspace.settings.installedPacks[]` — additive packs (profile/view/
+ *     bento) that create no workspace of their own, so never set `packageSlug`.
+ *
+ * A workspace carrying BOTH contributes one row per shape — they're different
+ * package identities layered onto the same workspace.
+ */
+export declare function fetchInstalledTemplates(): Promise<InstalledTemplateInfo[]>;
+/**
+ * The set of `packageSlug`s installed on the active pod. Empty on ANY failure
+ * (no pod configured, unreachable, older build without the field) — the caller
+ * simply shows no "installed" markers.
+ */
+export declare function fetchInstalledSlugs(): Promise<Set<string>>;

package/dist/lib/installed.js

@@ -0,0 +1,70 @@
+/**
+ * Installed-awareness — which packages are already on the active pod.
+ * ===================================================================
+ *
+ * The pod stamps `workspace.settings.packageSlug` on every workspace it
+ * provisions from a package (Hub `GET /workspaces` surfaces it — see
+ * `workspaces.ts:508`). Cross-referencing the discovery catalog against that set
+ * lets `launch --list` / the picker / `market` mark what is already installed
+ * instead of re-offering it.
+ *
+ * NON-FATAL by design: if the pod is unreachable, unconfigured, or on an older
+ * build, this degrades to an empty set (no markers) rather than failing the
+ * discovery command — you can always browse the catalog offline.
+ */
+import { resolveHubConfig, hubGet } from "./hub-client.js";
+/**
+ * Every installed workspace's `{slug, version, workspaceId, workspaceName}` —
+ * the raw material for "what's installed" (`fetchInstalledSlugs`) and "what's
+ * out of date" (`market update`'s `computeUpdates`). One Hub call, derived
+ * views. Unions TWO install shapes, mirroring the browser's
+ * `useInstalledPackageSlugs` (see that hook's doc for the full rationale):
+ *
+ *  1. `workspace.packageSlug` — a workspace-creating install (template).
+ *  2. `workspace.settings.installedPacks[]` — additive packs (profile/view/
+ *     bento) that create no workspace of their own, so never set `packageSlug`.
+ *
+ * A workspace carrying BOTH contributes one row per shape — they're different
+ * package identities layered onto the same workspace.
+ */
+export async function fetchInstalledTemplates() {
+    const out = [];
+    try {
+        const cfg = await resolveHubConfig();
+        const res = (await hubGet("/workspaces", {}, cfg));
+        for (const ws of res.workspaces ?? []) {
+            if (ws.packageSlug) {
+                out.push({
+                    slug: ws.packageSlug,
+                    version: ws.packageVersion ?? undefined,
+                    workspaceId: ws.id,
+                    workspaceName: ws.name,
+                });
+            }
+            for (const pack of ws.installedPacks ?? []) {
+                if (pack?.slug) {
+                    out.push({
+                        slug: pack.slug,
+                        version: pack.version,
+                        workspaceId: ws.id,
+                        workspaceName: ws.name,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // Non-fatal: degrade to empty. Discovery never depends on the pod.
+    }
+    return out;
+}
+/**
+ * The set of `packageSlug`s installed on the active pod. Empty on ANY failure
+ * (no pod configured, unreachable, older build without the field) — the caller
+ * simply shows no "installed" markers.
+ */
+export async function fetchInstalledSlugs() {
+    const templates = await fetchInstalledTemplates();
+    return new Set(templates.map((t) => t.slug));
+}
+//# sourceMappingURL=installed.js.map

package/dist/lib/installed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installed.js","sourceRoot":"","sources":["../../src/lib/installed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAmB3D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB;IAC3C,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,gBAAgB,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,EAAE,EAAE,EAAE,GAAG,CAAC,CAQhD,CAAC;QACF,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;YACtC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC;oBACP,IAAI,EAAE,EAAE,CAAC,WAAW;oBACpB,OAAO,EAAE,EAAE,CAAC,cAAc,IAAI,SAAS;oBACvC,WAAW,EAAE,EAAE,CAAC,EAAE;oBAClB,aAAa,EAAE,EAAE,CAAC,IAAI;iBACvB,CAAC,CAAC;YACL,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,EAAE,CAAC,cAAc,IAAI,EAAE,EAAE,CAAC;gBAC3C,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;oBACf,GAAG,CAAC,IAAI,CAAC;wBACP,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,OAAO,EAAE,IAAI,CAAC,OAAO;wBACrB,WAAW,EAAE,EAAE,CAAC,EAAE;wBAClB,aAAa,EAAE,EAAE,CAAC,IAAI;qBACvB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,SAAS,GAAG,MAAM,uBAAuB,EAAE,CAAC;IAClD,OAAO,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC"}

package/dist/lib/next-steps.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The guided path — one graph of "what to run next", shared by the journey
+ * commands so the CLI reads as a coherent flow instead of a pile of one-off
+ * `log.dim("Run synap …")` hints.
+ *
+ * Two consumers, one source of truth:
+ *   - HUMANS get a consistent, dim `Next:` block via `renderNextSteps()`.
+ *   - AGENTS get the SAME `NextStep[]` in every journey command's `--json`
+ *     output (a `nextSteps` field), so a script/agent can parse the graph and
+ *     chain the next call without scraping prose.
+ *
+ * `command` is a full, runnable `synap …` invocation (paste-able / executable);
+ * `why` is a crisp one-liner. Placeholders like `<id>` / `<slug>` stay literal
+ * where the concrete value isn't known yet.
+ */
+export interface NextStep {
+    /** A full runnable command, e.g. `synap market --list`. */
+    command: string;
+    /** Why you'd run it next — one crisp line. */
+    why: string;
+}
+/**
+ * Print a consistent, dim `Next:` block (aligned `command  — why`). No-op on an
+ * empty list. Goes to stdout via the `log.*` helpers, alongside ordinary output
+ * detail (a next-step block is guidance, not an error).
+ */
+export declare function renderNextSteps(steps: NextStep[]): void;
+/**
+ * The canonical flow graph. Each edge is a small function returning 1–3
+ * `NextStep`s for "you just did X → here's the sensible next move(s)."
+ */
+export declare const FLOW: {
+    /** After switching the active pod. */
+    afterPodUse(podName: string): NextStep[];
+    /** After logging in to the Synap account (control plane). */
+    afterLogin(email?: string): NextStep[];
+    /** After pinning a project as the active lens. */
+    afterProjectUse(name: string): NextStep[];
+    /** After creating a new project. */
+    afterProjectNew(name: string, id: string): NextStep[];
+    /** After listing projects (or after orient). */
+    afterProjectList(): NextStep[];
+    /** After browsing the marketplace. */
+    afterMarketList(): NextStep[];
+    /** After a market install. `proposed` = governance queued it for approval. */
+    afterMarketInstall(args: {
+        slug: string;
+        proposed: boolean;
+        projectName?: string;
+    }): NextStep[];
+    /** After `synap launch` stands up a company/OS (pod-wide, or under a project). */
+    afterLaunch(projectName?: string): NextStep[];
+    /** After orienting on the pod. */
+    afterOrient(): NextStep[];
+    /** After `synap market update` found drift but didn't apply (no --yes / no slug). */
+    afterMarketUpdateCheck(slugsWithUpdates: string[]): NextStep[];
+    /** After `synap market installed` inventoried the pod (found drift or not). */
+    afterMarketInstalledCheck(slugsWithUpdates: string[]): NextStep[];
+    /** After `synap market update` applied one or more updates. */
+    afterMarketUpdateApply(): NextStep[];
+};

package/dist/lib/next-steps.js

@@ -0,0 +1,146 @@
+/**
+ * The guided path — one graph of "what to run next", shared by the journey
+ * commands so the CLI reads as a coherent flow instead of a pile of one-off
+ * `log.dim("Run synap …")` hints.
+ *
+ * Two consumers, one source of truth:
+ *   - HUMANS get a consistent, dim `Next:` block via `renderNextSteps()`.
+ *   - AGENTS get the SAME `NextStep[]` in every journey command's `--json`
+ *     output (a `nextSteps` field), so a script/agent can parse the graph and
+ *     chain the next call without scraping prose.
+ *
+ * `command` is a full, runnable `synap …` invocation (paste-able / executable);
+ * `why` is a crisp one-liner. Placeholders like `<id>` / `<slug>` stay literal
+ * where the concrete value isn't known yet.
+ */
+import chalk from "chalk";
+import { log } from "../utils/logger.js";
+/**
+ * Print a consistent, dim `Next:` block (aligned `command  — why`). No-op on an
+ * empty list. Goes to stdout via the `log.*` helpers, alongside ordinary output
+ * detail (a next-step block is guidance, not an error).
+ */
+export function renderNextSteps(steps) {
+    if (steps.length === 0)
+        return;
+    const width = Math.max(...steps.map((s) => s.command.length));
+    log.blank();
+    console.log(chalk.dim("  Next:"));
+    for (const s of steps) {
+        console.log(chalk.dim(`    ${s.command.padEnd(width)}  — ${s.why}`));
+    }
+}
+/**
+ * The canonical flow graph. Each edge is a small function returning 1–3
+ * `NextStep`s for "you just did X → here's the sensible next move(s)."
+ */
+export const FLOW = {
+    /** After switching the active pod. */
+    afterPodUse(podName) {
+        return [
+            { command: "synap project use <id>", why: `focus a project on ${podName} to scope your work` },
+            { command: "synap market --list", why: "see what you can install" },
+            { command: "synap orient", why: "map this pod's projects + workspaces" },
+        ];
+    },
+    /** After logging in to the Synap account (control plane). */
+    afterLogin(email) {
+        return [
+            {
+                command: "synap market --list",
+                why: email ? `your private packages (${email}) are now visible` : "your private packages are now visible",
+            },
+            { command: "synap market install <slug>", why: "install an OS / template pod-wide" },
+        ];
+    },
+    /** After pinning a project as the active lens. */
+    afterProjectUse(name) {
+        return [
+            { command: "synap market install <slug>", why: `add a package to ${name}` },
+            { command: "synap market --list", why: "browse installable packages" },
+            { command: "synap orient", why: "see what's already in this pod" },
+        ];
+    },
+    /** After creating a new project. */
+    afterProjectNew(name, id) {
+        return [
+            { command: "synap launch", why: `stand up an OS (project + core workspaces) in ${name}` },
+            { command: `synap market install <slug> --project ${id}`, why: `add a single package to ${name}` },
+        ];
+    },
+    /** After listing projects (or after orient). */
+    afterProjectList() {
+        return [
+            { command: "synap project use <id>", why: "focus a project (cross-cutting lens)" },
+            { command: "synap project new <name>", why: "create a new company / initiative" },
+        ];
+    },
+    /** After browsing the marketplace. */
+    afterMarketList() {
+        return [
+            { command: "synap market install <slug>", why: "install it pod-wide" },
+            { command: "synap market install <slug> --project <id>", why: "optionally also tag its seeded entities to a project" },
+        ];
+    },
+    /** After a market install. `proposed` = governance queued it for approval. */
+    afterMarketInstall(args) {
+        if (args.proposed) {
+            return [{ command: "synap proposals list", why: `approve the queued install of ${args.slug}` }];
+        }
+        return [
+            { command: "synap orient", why: `see ${args.slug} in ${args.projectName ?? "your pod"}` },
+            { command: "synap open", why: "open it in the browser" },
+        ];
+    },
+    /** After `synap launch` stands up a company/OS (pod-wide, or under a project). */
+    afterLaunch(projectName) {
+        return [
+            {
+                command: "synap orient",
+                why: projectName
+                    ? `see the new workspaces under ${projectName}`
+                    : "see the new workspaces",
+            },
+            { command: "synap market --list", why: "add more packages" },
+        ];
+    },
+    /** After orienting on the pod. */
+    afterOrient() {
+        return [
+            { command: "synap project use <id>", why: "focus a project (cross-cutting lens)" },
+            { command: "synap market --list", why: "browse installable packages" },
+        ];
+    },
+    /** After `synap market update` found drift but didn't apply (no --yes / no slug). */
+    afterMarketUpdateCheck(slugsWithUpdates) {
+        if (slugsWithUpdates.length === 0)
+            return [];
+        const steps = slugsWithUpdates
+            .slice(0, 3)
+            .map((slug) => ({ command: `synap market update ${slug}`, why: "apply this template's update" }));
+        if (slugsWithUpdates.length > 1) {
+            steps.push({ command: "synap market update --yes", why: "apply every available update, no prompt" });
+        }
+        return steps;
+    },
+    /** After `synap market installed` inventoried the pod (found drift or not). */
+    afterMarketInstalledCheck(slugsWithUpdates) {
+        if (slugsWithUpdates.length === 0)
+            return [];
+        const steps = slugsWithUpdates
+            .slice(0, 3)
+            .map((slug) => ({ command: `synap market update ${slug}`, why: "preview this package's update" }));
+        if (slugsWithUpdates.length > 1) {
+            steps.push({ command: "synap market update --yes", why: "apply every available update, no prompt" });
+        }
+        return steps;
+    },
+    /** After `synap market update` applied one or more updates. */
+    afterMarketUpdateApply() {
+        return [
+            { command: "synap orient", why: "see what changed in the pod" },
+            { command: "synap market update", why: "re-check for further drift" },
+        ];
+    },
+};
+//# sourceMappingURL=next-steps.js.map

package/dist/lib/next-steps.js.map

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

package/dist/lib/pod.d.ts

@@ -10,10 +10,39 @@ export interface LocalPodConfig {
     label?: string;
     savedAt: string;
 }
-export type SurfaceName = "raycast" | "claude-code" | "claude-desktop" | "cursor" | "openclaw";
+/** SSOT for every connect/surface agent identity. The type is derived from this
+ *  array so the two can't drift. */
+export declare const SURFACE_NAMES: readonly ["raycast", "claude-code", "claude-desktop", "cursor", "codex", "opencode", "aider", "windsurf", "goose", "zed", "vscode", "discord"];
+export type SurfaceName = (typeof SURFACE_NAMES)[number];
+/**
+ * agentTypes already owned by OTHER doors — `POST /setup/agent` treats agentType
+ * as a POD-WIDE SINGLETON, so `agents create` deriving a slug that collides with
+ * one of these would silently hijack that door's agent + key. Superset of the
+ * surfaces above plus the non-surface provisioning types (generic/openwebui MCP
+ * mappings; openclaw/cli/memory). Single source of truth for the collision guard.
+ */
+export declare const RESERVED_AGENT_TYPES: ReadonlySet<string>;
 export interface SurfaceAgentKey {
     hubApiKey: string;
     agentUserId: string;
+    /**
+     * Pod the key was provisioned against. Consumers (e.g. the Raycast extension)
+     * must only use the key when this matches the pod they're talking to —
+     * a surface pointed at another pod falls back to that pod's own profile key.
+     */
+    podUrl?: string;
+}
+/** Agent workspace routing — persisted by `synap connect` wizard. */
+export interface AgentWorkspaceRouting {
+    /** Private workspace for agent-only captures (gotchas, lessons, patterns). Auto-approved. */
+    memoryWorkspaceId?: string;
+    /** Shared workspaces the agent writes team-visible data to. */
+    productWorkspaceIds?: string[];
+}
+/** The active project pinned together with the pod profile it lives on. */
+export interface ActiveProjectBinding {
+    projectId: string;
+    podName: string;
 }
 export interface MultiPodConfig {
     activePod: string;
@@ -22,9 +51,26 @@ export interface MultiPodConfig {
     pods: Record<string, LocalPodConfig>;
     /** Active workspace override — set by `synap use <workspaceId>`. Takes priority over the pod's default workspaceId. */
     activeWorkspaceId?: string;
+    /** Active project override — set by `synap project use <projectId>`. Peer of activeWorkspaceId; independent (composable). */
+    activeProjectId?: string;
+    /** Pod-aware binding of the active project — set by cross-pod `synap project use <ref>` so later drift (active pod changed under the pin) can warn. */
+    activeProject?: ActiveProjectBinding;
     /** Per-surface dedicated agent keys (provisioned with named agentType). Separate from pod profile keys. */
     agentKeys?: Partial<Record<SurfaceName, SurfaceAgentKey>>;
+    /** Workspace routing set by `synap connect` wizard — drives capture/recall defaults. */
+    agentWorkspaceRouting?: AgentWorkspaceRouting;
 }
+/**
+ * The ONE "pod profile not found" message.
+ *
+ * Names the profile that missed, the pods that DO exist, and the command that
+ * adds one. Every site that fails to resolve a profile name renders through
+ * this — a bare `not found` leaves the user with no next move, and the known-pods
+ * list is usually the whole answer (a typo).
+ */
+export declare function podNotFoundMessage(name: string): string;
+/** Throwing form of {@link podNotFoundMessage}. */
+export declare function podNotFoundError(name: string): Error;
 /** Get the pod config for a specific surface, falling back to the global activePod. */
 export declare function getSurfacePod(surface: SurfaceName): LocalPodConfig | null;
 /** Get the name of the pod assigned to a surface (or the global active pod name). */
@@ -39,14 +85,43 @@ export declare function listPodProfiles(): Array<{
     config: LocalPodConfig;
     active: boolean;
 }>;
+export declare function getPodOverride(): LocalPodConfig | null;
+/** Resolve a saved pod profile by name and set it as this invocation's override. */
+export declare function setPodOverrideByName(name: string): LocalPodConfig;
+/**
+ * Consume a position-independent `--pod <name>` (or `--pod=<name>`) from argv and
+ * register it as the per-invocation override. Mutates `argv` in place so commander
+ * never sees the flag (it isn't registered per-command). No-op when the argv
+ * targets a command that owns `--pod` itself (agents, bridge-setup). Throws with a
+ * helpful message when the named profile is unknown.
+ */
+export declare function bootstrapPodOverride(argv: string[]): void;
 export declare function addPodProfile(name: string, podConfig: LocalPodConfig): void;
 export declare function setActivePod(name: string): LocalPodConfig;
 /** Get the active workspace ID: explicit override first, then the pod default. */
 export declare function getActiveWorkspaceId(): string | undefined;
 /** Persist a workspace as the active context for all subsequent commands. */
 export declare function setActiveWorkspaceId(workspaceId: string): void;
+/** Get the active project ID: durable override set by `synap project use`. */
+export declare function getActiveProjectId(): string | undefined;
+/** Persist a project as the active context for all subsequent commands. */
+export declare function setActiveProjectId(projectId: string): void;
+/**
+ * Pin project AND the pod it lives on together — the cross-pod `project use`
+ * door. Stores the binding so later drift (active pod switched away from the
+ * pinned project's pod) can warn.
+ */
+export declare function setActiveProjectBinding(binding: ActiveProjectBinding): void;
+/** The pod-aware active-project binding, when set by cross-pod `project use`. */
+export declare function getActiveProjectBinding(): ActiveProjectBinding | undefined;
+/** Remove the active project override — subsequent commands see all projects. */
+export declare function clearActiveProjectId(): void;
 /** Store a dedicated agent key for a specific surface (e.g. "raycast", "claude-code"). */
 export declare function setSurfaceAgentKey(surface: SurfaceName, key: SurfaceAgentKey): void;
+/** Read back the stored agent key for a surface. Returns null if not provisioned. */
+export declare function getSurfaceAgentKey(surface: SurfaceName): SurfaceAgentKey | null;
+export declare function setAgentWorkspaceRouting(routing: AgentWorkspaceRouting): void;
+export declare function getAgentWorkspaceRouting(): AgentWorkspaceRouting | undefined;
 /** Remove the active workspace override — subsequent commands see all workspaces. */
 export declare function clearActiveWorkspaceId(): void;
 export declare function removePodProfile(name: string): void;
@@ -63,15 +138,6 @@ export interface PodStatus {
  * Check if a Synap pod is healthy.
  */
 export declare function checkPodHealth(podUrl: string): Promise<PodStatus>;
-/**
- * Create an agent user and API key on the pod.
- * Uses the PROVISIONING_TOKEN for auth.
- */
-export declare function setupAgent(podUrl: string, provisioningToken: string, agentType?: string): Promise<{
-    hubApiKey: string;
-    agentUserId: string;
-    workspaceId: string;
-}>;
 /**
  * Install Docker and start a self-hosted Synap pod.
  */
@@ -80,17 +146,31 @@ export declare function startSelfHostedPod(): void;
  * Install the synap skill into OpenClaw.
  */
 /**
- * Provision the CP-authenticated user on their pod.
- * Calls the CP to get a handshake JWT, then calls /api/handshake on the pod.
- * This ensures the user exists in the pod's users table before setup/agent runs.
- * Safe to call multiple times — idempotent (Kratos upserts by email).
+ * Open a Pod session for the CP-authenticated user.
+ * Calls the issuer for a short-lived generic assertion, then exchanges that
+ * assertion directly with the Pod. The issuer never receives a Pod session.
+ *
+ * Returns the Kratos session token the Pod mints after its own membership check.
+ * That token authenticates subsequent pod tRPC calls (e.g.
+ * `apiKeys.connectIntegration`) as the pod user, via the X-Session-Token header.
+ * `sessionToken` is null only if the pod handshake returned no token (e.g. 409).
  */
-export declare function provisionUserOnPod(podUrl: string, cpToken: string): Promise<void>;
+export declare function provisionUserOnPod(podUrl: string, cpToken: string): Promise<{
+    sessionToken: string | null;
+}>;
 /**
- * Generate an API key via the Control Plane (for authenticated users).
- * The CP relays the request to the pod using its own authority.
+ * Issue a scoped Hub Protocol API key on the pod for an authenticated user.
+ *
+ * Canonical path: the pod's `apiKeys.connectIntegration` tRPC procedure — the
+ * same one the pod-admin `/connect` page and the browser's LocalCliRow use.
+ * Auth is the Kratos session token minted by {@link provisionUserOnPod},
+ * forwarded as the `X-Session-Token` header. (Replaces the removed CP relay
+ * `POST /pods/setup-agent`, which now returns 410.)
+ *
+ * Backend tRPC uses the superjson transformer, so the input rides in a
+ * `{ json: ... }` envelope and the output is unwrapped from `result.data.json`.
  */
-export declare function setupAgentViaCp(podUrl: string, cpToken: string, agentType?: string): Promise<{
+export declare function setupAgentViaPod(podUrl: string, sessionToken: string, integration?: "cli" | "openclaw" | "raycast" | "custom"): Promise<{
     hubApiKey: string;
     agentUserId: string;
     workspaceId: string;
@@ -98,6 +178,11 @@ export declare function setupAgentViaCp(podUrl: string, cpToken: string, agentTy
 /**
  * Enable OpenClaw as a free addon on a SELF-HOSTED pod.
  * Uses the PROVISIONING_TOKEN directly against the pod.
+ *
+ * Routes through the shared `provisionAgentKey()` wrapper (dynamic import to
+ * avoid a circular pod.ts <-> targets.ts static import). `workspaceId` is no
+ * longer part of the response — agents are pod-wide singletons now; scope is
+ * granted separately via `enrollAgentIfNeeded()`, not returned from setup.
  */
 export declare function enableOpenClawAddon(podUrl: string, provisioningToken: string): Promise<{
     hubApiKey: string;
@@ -143,7 +228,7 @@ export declare function findSynapDeployDir(): string | null;
  *
  * Returns the deploy dir used.
  */
-export declare function startOpenClawOnServer(hubApiKey: string, agentUserId: string, workspaceId: string, podUrl: string): string;
+export declare function startOpenClawOnServer(hubApiKey: string, agentUserId: string, workspaceId: string, podUrl: string, projectId?: string): string;
 /**
  * Install the synap skill into OpenClaw.
  * Automatically chooses the right execution path: