@spacefast/common 0.0.26 → 0.2.1

package/dist/agents/registry/deeplink-probes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Deeplink probe results, keyed `<agentId>:<methodId>`.
+ *
+ * Deeplinks are volatile vendor behavior, so the registry never asserts they
+ * work — it records what a probe last observed. This module is the ONLY place a
+ * status stronger than `declared` may come from, and it is written by
+ * `scripts/marketplaces/probe-deeplinks.mjs` (scheduled weekly by
+ * `.github/workflows/deeplink-probe.yml`). A `failed` entry demotes its deeplink
+ * out of `interactive-primary` automatically, so the page falls through to the
+ * method's declared fallback.
+ *
+ * Browser-safe by construction: plain data, no filesystem, no network.
+ *
+ * TODO(deeplink-probe): the probe currently only writes this file by hand-run.
+ * Wire the scheduled workflow to open a PR with the regenerated map so a broken
+ * vendor deeplink demotes itself without a human in the loop.
+ */
+export type DeeplinkProbeResult = Readonly<{
+    checkedAt: string;
+    evidence?: string;
+    status: "probed" | "failed";
+}>;
+export declare const DEEPLINK_PROBE_RESULTS: Readonly<Record<string, DeeplinkProbeResult>>;

package/dist/agents/registry/deeplink-probes.js

@@ -0,0 +1,18 @@
+/**
+ * Deeplink probe results, keyed `<agentId>:<methodId>`.
+ *
+ * Deeplinks are volatile vendor behavior, so the registry never asserts they
+ * work — it records what a probe last observed. This module is the ONLY place a
+ * status stronger than `declared` may come from, and it is written by
+ * `scripts/marketplaces/probe-deeplinks.mjs` (scheduled weekly by
+ * `.github/workflows/deeplink-probe.yml`). A `failed` entry demotes its deeplink
+ * out of `interactive-primary` automatically, so the page falls through to the
+ * method's declared fallback.
+ *
+ * Browser-safe by construction: plain data, no filesystem, no network.
+ *
+ * TODO(deeplink-probe): the probe currently only writes this file by hand-run.
+ * Wire the scheduled workflow to open a PR with the regenerated map so a broken
+ * vendor deeplink demotes itself without a human in the loop.
+ */
+export const DEEPLINK_PROBE_RESULTS = {};

package/dist/agents/registry/node.d.ts

@@ -0,0 +1,56 @@
+import { type AgentCapability, type AgentId } from "./core.js";
+export type AgentRegistryEnvironment = Readonly<Record<string, string | undefined>>;
+export type AgentMcpFormat = "codex-toml" | "flat-json" | "mcp-json" | "opencode-json" | "vscode-json" | "zed-json";
+export type AgentMcpMethod = "local" | "remote-proxy" | "remote-oauth";
+export type AgentMcpValue = boolean | null | number | string | readonly AgentMcpValue[] | Readonly<{
+    [key: string]: AgentMcpValue;
+}>;
+export type AgentMcpServerConfig = Readonly<{
+    [key: string]: AgentMcpValue;
+}>;
+export type AgentMcpServerConfigEncoder = Readonly<{
+    format: AgentMcpFormat;
+    rootKey: "context_servers" | "mcp" | "mcpServers" | "servers" | null;
+    schemaUrl?: string;
+    build: (input: {
+        command: string;
+        endpoint: string;
+        method: AgentMcpMethod;
+        resource: string | null;
+    }) => AgentMcpServerConfig;
+}>;
+export type AgentNodeEntry = Readonly<{
+    capabilities: readonly AgentCapability[];
+    detectionPaths: (home: string, cwd: string, env: AgentRegistryEnvironment) => readonly string[];
+    id: AgentId;
+    mcp: Readonly<{
+        configPath: (home: string, cwd: string, env: AgentRegistryEnvironment) => string;
+        format: AgentMcpFormat;
+        serverConfigEncoder: AgentMcpServerConfigEncoder;
+    }> | null;
+    name: string;
+    skillDir: Readonly<{
+        alternativeGlobalPaths: (home: string, cwd: string, env: AgentRegistryEnvironment) => readonly string[];
+        global: (home: string, cwd: string, env: AgentRegistryEnvironment) => string;
+        project: (home: string, cwd: string, env: AgentRegistryEnvironment) => string;
+    }> | null;
+}>;
+export declare const MACHINE_AGENT_IDS: ("amp" | "hermes" | "claude-code" | "claude-app" | "claude-desktop" | "cursor" | "codex" | "chatgpt" | "vscode" | "github-copilot" | "devin-desktop" | "devin-cloud" | "zed" | "gemini-cli" | "opencode" | "warp" | "factory-droid" | "cline" | "continue" | "raycast" | "poke" | "pi" | "indent" | "openclaw")[];
+export declare function agentNodeCatalog(input: {
+    cwd: string;
+    env?: AgentRegistryEnvironment;
+    home: string;
+}): readonly AgentNodeEntry[];
+export declare function getAgentNodeEntry(id: AgentId, input: {
+    cwd: string;
+    env?: AgentRegistryEnvironment;
+    home: string;
+}): AgentNodeEntry | null;
+export declare function buildAgentMcpServerConfig(input: {
+    agentId: AgentId;
+    command: string;
+    endpoint: string;
+    method: AgentMcpMethod;
+    resource: string | null;
+}): AgentMcpServerConfig;
+export declare function agentEnvironmentHint(env: AgentRegistryEnvironment): AgentId | null;

package/dist/agents/registry/node.js

@@ -0,0 +1,339 @@
+import path from "node:path";
+import { AGENT_REGISTRY, getAgentEntry, } from "./core.js";
+const commonEncoder = {
+    format: "mcp-json",
+    rootKey: "mcpServers",
+    build: ({ command, endpoint, method, resource }) => {
+        if (method !== "remote-oauth") {
+            return { command, args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"] };
+        }
+        return { type: "http", url: endpoint, oauth_resource: resource };
+    },
+};
+/**
+ * Cursor takes the same `type: "http"` remote entry every other `mcpServers`
+ * client does. The bare `{ url }` this used to write is the shape nobody ships:
+ * it disagreed with the registry's own Cursor config and with the comparable
+ * vendors, and several clients read a bare url as a stdio command.
+ */
+const cursorEncoder = commonEncoder;
+/**
+ * Gemini CLI's own dialect: `httpUrl` plus an explicit `oauth` block, not
+ * `type` + `url` (spec §5.13 dialect table).
+ */
+const geminiEncoder = {
+    ...commonEncoder,
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { httpUrl: endpoint, oauth: { enabled: true } }
+        : { command, args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"] },
+};
+const vscodeEncoder = {
+    format: "vscode-json",
+    rootKey: "servers",
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { type: "http", url: endpoint }
+        : {
+            type: "stdio",
+            command,
+            args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"],
+        },
+};
+const codexEncoder = {
+    format: "codex-toml",
+    rootKey: null,
+    build: ({ command, endpoint, method, resource }) => method === "remote-oauth"
+        ? { url: endpoint, oauth_resource: resource }
+        : { command, args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"] },
+};
+const opencodeEncoder = {
+    format: "opencode-json",
+    rootKey: "mcp",
+    schemaUrl: "https://opencode.ai/config.json",
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { type: "remote", url: endpoint, enabled: true }
+        : {
+            type: "local",
+            command: [command, ...(method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"])],
+            enabled: true,
+        },
+};
+const copilotEncoder = {
+    ...commonEncoder,
+    build: (input) => ({ ...commonEncoder.build(input), tools: ["*"] }),
+};
+const droidEncoder = {
+    ...commonEncoder,
+    build: (input) => ({
+        ...commonEncoder.build(input),
+        type: input.method === "remote-oauth" ? "http" : "stdio",
+        disabled: false,
+    }),
+};
+const zedEncoder = {
+    format: "zed-json",
+    rootKey: "context_servers",
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { source: "custom", url: endpoint, settings: {} }
+        : {
+            source: "custom",
+            command: {
+                path: command,
+                args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"],
+            },
+        },
+};
+const ampEncoder = {
+    format: "flat-json",
+    rootKey: null,
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { url: endpoint }
+        : { command, args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"] },
+};
+const clineEncoder = {
+    ...commonEncoder,
+    build: ({ command, endpoint, method }) => method === "remote-oauth"
+        ? { type: "streamableHttp", url: endpoint, disabled: false }
+        : {
+            type: "stdio",
+            command,
+            args: method === "remote-proxy" ? ["mcp", "proxy"] : ["mcp"],
+            disabled: false,
+        },
+};
+const universalSkill = {
+    global: ({ home }) => path.join(home, ".agents", "skills"),
+    project: ({ cwd }) => path.join(cwd, ".agents", "skills"),
+};
+const definitions = [
+    {
+        id: "claude-code",
+        detection: ({ home }) => [path.join(home, ".claude")],
+        skill: {
+            global: ({ home }) => path.join(home, ".claude", "skills"),
+            project: ({ cwd }) => path.join(cwd, ".claude", "skills"),
+            alternatives: ({ home }) => [path.join(home, ".agents", "skills")],
+        },
+        mcp: { config: ({ home }) => path.join(home, ".claude.json"), encoder: commonEncoder },
+    },
+    {
+        id: "cursor",
+        detection: ({ home }) => [path.join(home, ".cursor")],
+        skill: {
+            global: ({ home }) => path.join(home, ".cursor", "skills"),
+            project: universalSkill.project,
+            alternatives: ({ home }) => [
+                path.join(home, ".agents", "skills"),
+                path.join(home, ".claude", "skills"),
+            ],
+        },
+        mcp: { config: ({ home }) => path.join(home, ".cursor", "mcp.json"), encoder: cursorEncoder },
+    },
+    {
+        id: "codex",
+        detection: ({ env, home }) => [codexHome(home, env)],
+        skill: {
+            global: ({ env, home }) => path.join(codexHome(home, env), "skills"),
+            project: universalSkill.project,
+            alternatives: ({ home }) => [path.join(home, ".agents", "skills")],
+        },
+        mcp: {
+            config: ({ env, home }) => path.join(codexHome(home, env), "config.toml"),
+            encoder: codexEncoder,
+        },
+    },
+    {
+        id: "vscode",
+        detection: ({ home }) => [
+            path.join(home, ".vscode"),
+            path.join(home, "Library", "Application Support", "Code"),
+            path.join(home, ".config", "Code"),
+        ],
+        skill: universalSkill,
+        mcp: { config: ({ cwd }) => path.join(cwd, ".vscode", "mcp.json"), encoder: vscodeEncoder },
+    },
+    {
+        id: "github-copilot",
+        detection: ({ home }) => [path.join(home, ".copilot")],
+        skill: {
+            global: ({ home }) => path.join(home, ".copilot", "skills"),
+            project: universalSkill.project,
+            alternatives: ({ home }) => [path.join(home, ".agents", "skills")],
+        },
+        mcp: {
+            config: ({ home }) => path.join(home, ".copilot", "mcp-config.json"),
+            encoder: copilotEncoder,
+        },
+    },
+    {
+        id: "devin-desktop",
+        detection: ({ home }) => [path.join(home, ".devin")],
+        skill: universalSkill,
+        mcp: {
+            config: ({ home }) => path.join(home, ".devin", "mcp_config.json"),
+            encoder: commonEncoder,
+        },
+    },
+    {
+        id: "zed",
+        detection: ({ home }) => [path.join(home, ".config", "zed")],
+        skill: universalSkill,
+        mcp: {
+            config: ({ home }) => path.join(home, ".config", "zed", "settings.json"),
+            encoder: zedEncoder,
+        },
+    },
+    {
+        id: "gemini-cli",
+        detection: ({ home }) => [path.join(home, ".gemini")],
+        skill: {
+            ...universalSkill,
+            alternatives: ({ home }) => [path.join(home, ".gemini", "skills")],
+        },
+        mcp: {
+            config: ({ home }) => path.join(home, ".gemini", "settings.json"),
+            encoder: geminiEncoder,
+        },
+    },
+    {
+        id: "opencode",
+        detection: ({ home }) => [path.join(home, ".config", "opencode")],
+        skill: {
+            global: ({ home }) => path.join(home, ".config", "opencode", "skills"),
+            project: universalSkill.project,
+            alternatives: ({ home }) => [
+                path.join(home, ".agents", "skills"),
+                path.join(home, ".claude", "skills"),
+            ],
+        },
+        mcp: {
+            config: ({ home }) => path.join(home, ".config", "opencode", "opencode.json"),
+            encoder: opencodeEncoder,
+        },
+    },
+    {
+        id: "amp",
+        detection: ({ home }) => [path.join(home, ".config", "amp")],
+        skill: universalSkill,
+        mcp: {
+            config: ({ home }) => path.join(home, ".config", "amp", "mcp.json"),
+            encoder: ampEncoder,
+        },
+    },
+    {
+        id: "warp",
+        detection: ({ home }) => [path.join(home, ".warp")],
+        skill: universalSkill,
+        mcp: { config: ({ home }) => path.join(home, ".warp", "mcp.json"), encoder: commonEncoder },
+    },
+    {
+        id: "factory-droid",
+        detection: ({ home }) => [path.join(home, ".factory")],
+        skill: {
+            global: ({ home }) => path.join(home, ".factory", "skills"),
+            project: ({ cwd }) => path.join(cwd, ".factory", "skills"),
+            alternatives: ({ home }) => [path.join(home, ".agents", "skills")],
+        },
+        mcp: { config: ({ home }) => path.join(home, ".factory", "mcp.json"), encoder: droidEncoder },
+    },
+    {
+        id: "cline",
+        detection: ({ home }) => [path.join(home, ".cline")],
+        skill: {
+            global: ({ home }) => path.join(home, ".cline", "skills"),
+            project: ({ cwd }) => path.join(cwd, ".cline", "skills"),
+            alternatives: ({ home }) => [
+                path.join(home, ".agents", "skills"),
+                path.join(home, ".claude", "skills"),
+            ],
+        },
+        mcp: {
+            config: ({ home }) => path.join(home, ".cline", "data", "settings", "cline_mcp_settings.json"),
+            encoder: clineEncoder,
+        },
+    },
+    {
+        id: "continue",
+        detection: ({ cwd, home }) => [path.join(cwd, ".continue"), path.join(home, ".continue")],
+        skill: {
+            global: ({ home }) => path.join(home, ".continue", "skills"),
+            project: ({ cwd }) => path.join(cwd, ".continue", "skills"),
+            alternatives: ({ home }) => [path.join(home, ".claude", "skills")],
+        },
+    },
+    {
+        id: "pi",
+        detection: ({ home }) => [path.join(home, ".pi")],
+        skill: universalSkill,
+    },
+    {
+        id: "hermes",
+        detection: ({ home }) => [path.join(home, ".hermes")],
+        skill: universalSkill,
+    },
+    {
+        id: "openclaw",
+        detection: ({ home }) => [path.join(home, ".openclaw")],
+        skill: universalSkill,
+    },
+];
+const definitionById = new Map(definitions.map((definition) => [definition.id, definition]));
+export const MACHINE_AGENT_IDS = AGENT_REGISTRY.filter((entry) => entry.machineClient).map((entry) => entry.id);
+export function agentNodeCatalog(input) {
+    const context = { cwd: input.cwd, env: input.env ?? {}, home: input.home };
+    return definitions.map((definition) => materializeNodeEntry(definition, context));
+}
+export function getAgentNodeEntry(id, input) {
+    const definition = definitionById.get(id);
+    if (!definition)
+        return null;
+    return materializeNodeEntry(definition, {
+        cwd: input.cwd,
+        env: input.env ?? {},
+        home: input.home,
+    });
+}
+export function buildAgentMcpServerConfig(input) {
+    const definition = definitionById.get(input.agentId);
+    if (!definition?.mcp) {
+        return commonEncoder.build(input);
+    }
+    return definition.mcp.encoder.build(input);
+}
+export function agentEnvironmentHint(env) {
+    const termProgram = env.TERM_PROGRAM?.toLowerCase() ?? "";
+    if (env.CURSOR_TRACE_ID || termProgram.includes("cursor"))
+        return "cursor";
+    if (env.CLAUDECODE || env.CLAUDE_CODE)
+        return "claude-code";
+    if (env.CODEX_HOME)
+        return "codex";
+    if (env.VSCODE_PID || termProgram.includes("vscode"))
+        return "vscode";
+    return null;
+}
+function materializeNodeEntry(definition, context) {
+    const agent = getAgentEntry(definition.id);
+    return {
+        capabilities: agent.capabilities,
+        detectionPaths: () => definition.detection(context),
+        id: definition.id,
+        mcp: definition.mcp
+            ? {
+                configPath: () => definition.mcp?.config(context) ?? "",
+                format: definition.mcp.encoder.format,
+                serverConfigEncoder: definition.mcp.encoder,
+            }
+            : null,
+        name: agent.name,
+        skillDir: definition.skill
+            ? {
+                alternativeGlobalPaths: () => definition.skill?.alternatives?.(context) ?? [],
+                global: () => definition.skill?.global(context) ?? path.join(context.home, ".agents", "skills"),
+                project: () => definition.skill?.project(context) ?? path.join(context.cwd, ".agents", "skills"),
+            }
+            : null,
+    };
+}
+function codexHome(home, env) {
+    return env.CODEX_HOME?.trim() || path.join(home, ".codex");
+}

package/dist/brand-assets-build.js

@@ -27,8 +27,7 @@ function numericAttribute(name, value) {
 export function spacefastWordmarkSvg(options = {}) {
     const colors = resolvedColors(options.colors);
     const label = svgAttribute(options.ariaLabel ?? "Spacefast");
-    // The logotype is single-color: `plate` (ink) is its fill. The plate/shadow
-    // layer idiom retired with the riso system — the wordmark is bare letterforms.
+    // The logotype is single-color: `plate` (ink) is its fill.
     return `<svg xmlns="http://www.w3.org/2000/svg"${numericAttribute("width", options.width)}${numericAttribute("height", options.height)} viewBox="${SPACEFAST_WORDMARK_VIEW_BOX}" role="img" aria-label="${label}">
   <path fill="${svgAttribute(colors.plate)}" d="${SPACEFAST_WORDMARK_PATH}"/>
 </svg>

package/dist/brand-assets.js

@@ -6,18 +6,15 @@
  * build outputs of these constants, never independent sources of truth.
  */
 // The 2026-08 "printed matter" palette (DESIGN.md §3). `plate`/`paper` name the
-// icon serializers' layers; the wordmark itself is a single-color logotype and
-// takes whatever ink its surface supplies.
+// icon serializers' layers; the wordmark takes whatever ink its surface supplies.
 export const SPACEFAST_BRAND_COLORS = {
     shadow: "#d8f24b",
     plate: "#0c0c0c",
     paper: "#fcfcfa",
 };
-// The logotype: bare "SPACEFAST" letterforms in the right-angle stencil
-// alphabet — no plates, no offset shadow (that idiom retired with the riso
-// system). One path, one color; surfaces set the fill (ink on light grounds,
-// paper on dark). Exported from the Spacefast Figma file via the standalone
-// `www` repo (`public/static/brand/spacefast-wordmark.svg`).
+// The logotype: bare "SPACEFAST" letterforms, one path, one color. Surfaces set
+// the fill (ink on light grounds, paper on dark). Exported from the Spacefast
+// Figma file via the `www` repo (`public/static/brand/spacefast-wordmark.svg`).
 export const SPACEFAST_WORDMARK_VIEW_BOX = "0 0 152 28.9062";
 // This is a literal so browser consumers render ordinary SVG markup without
 // assembling path text at runtime.

package/dist/brand.d.ts

@@ -2,4 +2,21 @@ export declare const BRAND: {
     /** Consumer product name shown on every user surface. */
     readonly productName: "Spacefast";
 };
+/**
+ * What Spacefast is, in one paragraph, for a reader who has never heard of it.
+ *
+ * Every agent-facing surface leads with this: the copied page context, the
+ * `/v1/context` positioning fragment, the skill templates. An agent that
+ * only ever sees "here are three endpoints" cannot tell a user what it is
+ * working with, so the positioning is part of the context, not marketing.
+ *
+ * One constant, one wording. Do not paraphrase it at a call site.
+ */
+export declare const SPACEFAST_POSITIONING: string;
+/**
+ * The one-line positioning for lean agent prompts and handoff documents,
+ * where every word costs attention. The paragraph above stays for surfaces
+ * that can afford it. One constant, one wording — same rule as above.
+ */
+export declare const SPACEFAST_POSITIONING_SHORT = "Spacefast (https://spacefast.com) is Automattic's platform where agents publish and host sites and apps.";
 export declare const GITHUB_CHECK_RUN_NAME: "Spacefast Builds";

package/dist/brand.js

@@ -2,8 +2,28 @@ export const BRAND = {
     /** Consumer product name shown on every user surface. */
     productName: "Spacefast",
 };
-// The GitHub check-run name every build reports under. One constant because the
-// create and update paths live in different modules and drifted once
-// ("Stattic" vs "Spacefast") — GitHub keys check runs by name, so a mismatch
-// shows two orphaned checks per commit.
+/**
+ * What Spacefast is, in one paragraph, for a reader who has never heard of it.
+ *
+ * Every agent-facing surface leads with this: the copied page context, the
+ * `/v1/context` positioning fragment, the skill templates. An agent that
+ * only ever sees "here are three endpoints" cannot tell a user what it is
+ * working with, so the positioning is part of the context, not marketing.
+ *
+ * One constant, one wording. Do not paraphrase it at a call site.
+ */
+export const SPACEFAST_POSITIONING = "Spacefast is a batteries-included platform by Automattic to deploy any agentic artifacts, " +
+    "websites, generated static sites, full-stack TypeScript projects, PHP functions and Spacefast " +
+    "Zero capsules. Every space comes with database, storage, transactional emails, built-in auth " +
+    "for small or internal apps. Pages deployed to Spacefast are private by default but can be made " +
+    "public. Spacefast is built on the same infrastructure as WordPress.com, Tumblr, WordPress VIP " +
+    "and WP Cloud.";
+/**
+ * The one-line positioning for lean agent prompts and handoff documents,
+ * where every word costs attention. The paragraph above stays for surfaces
+ * that can afford it. One constant, one wording — same rule as above.
+ */
+export const SPACEFAST_POSITIONING_SHORT = "Spacefast (https://spacefast.com) is Automattic's platform where agents publish and host sites and apps.";
+// GitHub keys check runs by name, so the create and update paths (separate
+// modules) must both use this constant or a commit grows two orphaned checks.
 export const GITHUB_CHECK_RUN_NAME = `${BRAND.productName} Builds`;

package/dist/config/domains.d.ts

@@ -7,7 +7,7 @@ export type EnvDomains = {
     readonly apex: string;
     /** Cookie domain that scopes auth across every subdomain of this env. */
     readonly cookieDomain: string;
-    /** Scheme used to build origins. SSL everywhere — even local (via portless). */
+    /** Scheme used to build origins. SSL everywhere, even local (via portless). */
     readonly protocol: "http" | "https";
     /** Fully-qualified hostname per service. */
     readonly hosts: Readonly<Record<Service, string>>;
@@ -18,15 +18,13 @@ export declare const PROD_ENV_DOMAIN: "spacefast.com";
 export declare const DEV_ENV_DOMAIN: "sf.localhost";
 /** The deployed staging apex. Not local: staging is a hosted environment. */
 export declare const STAGING_ENV_DOMAIN: "stattic.net";
-/** The deployed dev apex — distinct from local dev, which stays on sf.localhost. */
+/** The deployed dev apex. Local dev is separate and stays on sf.localhost. */
 export declare const DEV_DEPLOY_ENV_DOMAIN: "stattic.xyz";
 /**
  * The three environments the deploy lanes ship to, keyed by the name each one
  * carries everywhere else: the branch map in scripts/deploy-environment.mjs,
- * the GitHub Environment, and `SPACEFAST_ENV` on the running service.
- *
- * Distinct from `DeployEnv` below, which names the *local* stacks (dev/test on
- * sf.localhost) beside prod.
+ * the GitHub Environment, and `SPACEFAST_ENV` on the running service. Distinct
+ * from `DeployEnv` above, which names the local stacks beside prod.
  */
 export type HostedEnv = "dev" | "staging" | "prod";
 export declare const HOSTED_ENV_DOMAINS: Readonly<Record<HostedEnv, string>>;
@@ -39,18 +37,25 @@ export declare function hostedEnvFor(environment: string | undefined): HostedEnv
 /** The apex a hosted environment serves from, or null when the name is not one. */
 export declare function hostedEnvDomain(environment: string | undefined): string | null;
 /**
- * Construct the full per-service host map from a single env domain
- * (`spacefast.com`, `stattic.net`, `sf.localhost`, …). One knob — services are
- * always `<service>.<domain>` over https, with three deliberate exceptions: the
- * marketing site sits on the bare apex of a hosted environment (so staging
- * rehearses production's shape rather than a `www.` variant of it), and both
- * Git push and the internal handbook live on their own apexes in prod.
+ * The per-service host map for one env domain (`spacefast.com`, `sf.localhost`,
+ * …). Services are `<service>.<domain>` over https, with three exceptions: the
+ * marketing site takes the bare apex of a hosted environment (so staging
+ * rehearses production's shape), and Git push and the internal handbook get
+ * their own apexes in prod.
  */
 export declare function envDomainsFor(domain: string): EnvDomains;
 /** Origin (scheme + host, no trailing slash) for a service in an environment. */
 export declare function serviceOrigin(service: Service, env: DeployEnv): string;
-/** Base URL every documentation link — catalog entries, skills, error pages — resolves against. */
+/** Base URL every documentation link resolves against: catalog entries, skills, error pages. */
 export declare const DOCS_BASE_URL: string;
+/**
+ * The API origin every first-party client falls back to when nothing else names
+ * a provider: no `--api-url`, no `SPACEFAST_API_URL`, no saved profile or
+ * checkout link. The CLI and the MCP server share this one literal so a caller
+ * cannot be pointed at two different "defaults" depending on which surface it
+ * came through.
+ */
+export declare const DEFAULT_API_URL: string;
 /**
  * The production infrastructure apex. Committed artifacts and anything
  * customer- or agent-facing (OpenAPI examples, docs, skills) must show this
@@ -63,23 +68,45 @@ export declare const DEV_VIEW_FAST_APEX: "preview.space";
 /**
  * Resolve the infrastructure apex, allowing an explicit deployment override.
  *
- * Only production has an apex here. Every other hosted environment names its
- * own through `SPACEFAST_VIEW_FAST_APEX`, because a space apex is a zone that
- * has to exist, be delegated, and be attached at the provider — not a name this
- * registry can pick on a deployment's behalf. Two environments allocating from
- * one apex race for the same hostname, and the one that loses is a customer's
- * site.
+ * Only production has an apex here. Every other hosted environment names its own
+ * through `SPACEFAST_VIEW_FAST_APEX`, because a space apex is a zone that must
+ * exist, be delegated, and be attached at the provider. Two environments
+ * allocating from one apex race for the same hostname, and the loser is a
+ * customer's site.
  *
- * When nothing names the apex, this falls back to the local one rather than
- * production's: a caller that cannot say which environment it is has no claim
- * on production's namespace. Holding deployments to naming it belongs to the
- * process that mints hostnames, not to this module — the control plane's env
- * schema refuses to boot without it, while builds and browser bundles import
- * this registry for its host scheme and must not explode over an environment
- * they do not have.
+ * When nothing names the apex this falls back to the local one: a caller that
+ * cannot say which environment it is has no claim on production's namespace. The
+ * control plane's env schema is what holds deployments to naming it; builds and
+ * browser bundles import this registry only for its host scheme.
  */
 export declare function resolveViewFastApex(environment: Readonly<Partial<Pick<NodeJS.ProcessEnv, "NODE_ENV" | "SPACEFAST_ENV" | "SPACEFAST_VIEW_FAST_APEX">>>): string;
 /** Infrastructure apex used for public managed/custom domains. */
 export declare const VIEW_FAST_APEX: string;
-/** Reserved first-label prefix for the management namespace; users may not register it. */
-export declare const MANAGEMENT_LABEL_PREFIX: "wpc-manage-";
+/**
+ * The Spacefast-owned apex under which a LINKED TEST TENANT's simulated sites and
+ * hostname namespaces materialize (partner-operations spec §1). It is never
+ * served by real infrastructure — nothing points DNS at it and no cert is
+ * provisioned — so it exists purely as a collision-free namespace: a test
+ * tenant's hostnames are `{label}.{tenant}.{TEST_APEX}` (per-tenant, see
+ * `testApexForTenant`), which is also the marker the runtime-API transport uses
+ * to recognize a simulated box and short-circuit rather than reach a real one.
+ *
+ * Defaults to `test.{VIEW_FAST_APEX}` so every environment gets a distinct test
+ * apex for free; a deployment can override it with `SPACEFAST_TEST_APEX`.
+ */
+export declare function resolveTestApex(environment: Readonly<Partial<Pick<NodeJS.ProcessEnv, "NODE_ENV" | "SPACEFAST_ENV" | "SPACEFAST_VIEW_FAST_APEX" | "SPACEFAST_TEST_APEX">>>): string;
+/** The resolved test-mode apex for this process. */
+export declare const TEST_APEX: string;
+export declare function testApexForTenant(tenantId: string, testApex?: string): string;
+/**
+ * Whether a hostname belongs to the test-mode apex (a simulated box).
+ *
+ * STRICTLY a suffix check — the apex ITSELF is never a simulated hostname. Every
+ * simulated hostname is `{label}.{tenant}.{TEST_APEX}` (two labels deep), while
+ * the bare apex is reachable as a LIVE space's hostname: `TEST_APEX` defaults to
+ * `test.{VIEW_FAST_APEX}`, so a live space slugged `test` is served at exactly
+ * `test.view.fast`. Matching the apex would make every Runtime-API call for that
+ * space short-circuit to a synthetic response — engine installs reporting
+ * `installed` and publishes reporting success while nothing ever reaches the box.
+ */
+export declare function isTestApexHostname(hostname: string, testApex?: string): boolean;