@domino-sdk/relay-cli 0.4.0 → 0.5.0

package/cli/commands/discovery.mjs

@@ -1,11 +1,18 @@
 import { readFile } from "node:fs/promises";
 import { action } from "../runtime.mjs";
 
-const references = ["authoring", "participant-api", "referrals", "troubleshooting"];
+const references = [
+  "authoring",
+  "participant-api",
+  "referrals",
+  "troubleshooting",
+];
 export function registerDiscoveryCommands(program) {
   program
     .command("capabilities")
-    .description("Discover supported Domino features and their limitations")
+    .description(
+      "Read this CLI release's bundled capability catalog (not a server probe)",
+    )
     .argument("[id]", "Capability identifier")
     .action(
       action(async (_, id) => {
@@ -15,13 +22,25 @@ export function registerDiscoveryCommands(program) {
             "utf8",
           ),
         );
-        if (!id) return catalog;
+        const { version } = JSON.parse(
+          await readFile(
+            new URL("../../package.json", import.meta.url),
+            "utf8",
+          ),
+        );
+        const provenance = {
+          kind: "bundled-catalog",
+          cliVersion: version,
+          serverVerified: false,
+          note: "Describes this CLI release. Scope flags do not make it project-specific. Verify the deployed contract before treating missing or conflicting entries as unsupported.",
+        };
+        if (!id) return { ...catalog, provenance };
         const capability = catalog.capabilities.find((item) => item.id === id);
         if (!capability)
           throw new Error(
             `Unknown capability. Choose: ${catalog.capabilities.map((item) => item.id).join(", ")}`,
           );
-        return capability;
+        return { ...capability, provenance };
       }),
     );
   program

package/cli/commands/project.mjs

@@ -1,4 +1,5 @@
-import { writeFile } from "node:fs/promises";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
 import { action } from "../runtime.mjs";
 import { request } from "../connection.mjs";
 import { initialize, bundleProject } from "../project.mjs";
@@ -76,6 +77,7 @@ async function build({ project, connection, options }, deploy) {
     return publish(connection, preview.id);
   }
   if (options.out) {
+    await mkdir(dirname(options.out), { recursive: true });
     await writeFile(options.out, JSON.stringify(payload, null, 2) + "\n");
     return {
       file: options.out,

package/cli/commands/staging.mjs

@@ -20,9 +20,9 @@ export function registerStagingCommands(program) {
       action(async ({ connection, project, options }) => {
         if (!project)
           throw new Error("Run stage inside a hosted campaign checkout.");
-        if (project.config.app?.kind !== "static")
+        if (!project.config.app)
           throw new Error(
-            "Cloud staging currently supports static campaign checkouts with app.kind=static in relay.json. This project is not configured for cloud staging. SSR Worker apps use the Cloudflare Worker deployment workflow.",
+            "Configure app.kind as static or worker in relay.json before staging.",
           );
         const scoped = { ...connection, environment: "test" };
         const preflight = await request(scoped, "/preflight");

package/cli/connected-dev.mjs

@@ -22,7 +22,7 @@ export async function connectedDev(project, connection, options) {
   const preflight = await request(connection, "/preflight");
   if (preflight.development?.status !== "configured")
     throw new Error(
-      "Hosted development is not configured. Run domino doctor --remote --json; a Domino operator must enable previews and test sign-in.",
+      "Hosted development is not configured. Run domino doctor --remote --json; a Domino operator must enable preview hosting.",
     );
   const root = dirname(project.path);
   const connector = await previewConnector(options.cloudflared);
@@ -126,6 +126,7 @@ export async function connectedDev(project, connection, options) {
     session = await request(connection, "/development/session", "POST", {
       ...lease,
       port,
+      routing: project.config.app.routing,
     });
     const sync = developmentSync(connection, project.path);
     await sync();
@@ -143,6 +144,7 @@ export async function connectedDev(project, connection, options) {
     start("pnpm", ["run", project.config.app.devScript], {
       DOMINO_APP_PORT: String(port),
       DOMINO_PREVIEW_ORIGIN: session.url,
+      DOMINO_PARTICIPANT_API: connection.apiUrl,
     });
     let appReady = false;
     for (let attempt = 0; attempt < 150 && !stopping; attempt++) {
@@ -190,7 +192,7 @@ export async function connectedDev(project, connection, options) {
         )
       );
     process.stderr.write(
-      `Preview: ${session.url}\nUses this project's hosted test data and real sign-in. Keep this terminal running. Use domino stage for a preview that stays online.\n`,
+      `Preview: ${session.url}\nKeep this terminal running. Use domino stage for a preview that stays online.\n`,
     );
     let renewed = Date.now();
     while (!stopping) {

package/cli/doctor.mjs

@@ -5,10 +5,12 @@ import { access, readFile } from "node:fs/promises";
 import { inspectAgentSkills } from "./agents.mjs";
 import { request } from "./connection.mjs";
 import { discoverEntries } from "./discovery.mjs";
+import { packageManager } from "./package-manager.mjs";
 
-export async function diagnose({ project, connection, options }) {
+export async function diagnose({ project, connection, options, scopeSources }) {
   const checks = [];
   const root = project ? dirname(project.path) : process.cwd();
+  const manager = await packageManager(root);
   checks.push(
     project
       ? { id: "manifest", status: "ok", message: "Project manifest is valid." }
@@ -170,6 +172,13 @@ export async function diagnose({ project, connection, options }) {
     development: { status: "not-checked" },
     staging: "not-checked",
   };
+  if (options.remote && !project)
+    checks.push({
+      id: "remote-access",
+      status: "warning",
+      message:
+        "Remote access was not checked because no relay.json was found. This does not diagnose a failed checkout. Use its checkout error details; do not install skills in the parent directory to repair remote access.",
+    });
   if (options.remote && project) {
     try {
       const value = await request(connection, "/access");
@@ -238,6 +247,8 @@ export async function diagnose({ project, connection, options }) {
       project: connection.project,
       environment: connection.environment,
     },
+    scopeSources,
+    packageManager: manager,
     agents,
     readiness,
     remoteAccess,
@@ -245,6 +256,10 @@ export async function diagnose({ project, connection, options }) {
       ? "static-app-configured"
       : "use-existing-app-workflow",
     checks,
-    next: "After setup, run the project's checks and verify a real participant action. Setup diagnostics do not prove preview or live readiness.",
+    next:
+      checks.some((check) => check.id === "sdk" && check.status === "error") &&
+      manager.installCommand
+        ? `Run ${manager.installCommand} in ${root} and wait for it to finish before rerunning doctor. Then verify a participant action.`
+        : "After setup, run the project's checks and verify a real participant action. Setup diagnostics do not prove preview or live readiness.",
   };
 }

package/cli/git.mjs

@@ -3,6 +3,7 @@ import { access, mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { apiUrl, request, savedToken } from "./connection.mjs";
+import { packageManager } from "./package-manager.mjs";
 
 export function runGit(args, { cwd, input, env = {} } = {}) {
   return new Promise((resolve, reject) => {
@@ -20,11 +21,13 @@ export function runGit(args, { cwd, input, env = {} } = {}) {
       stderr += data;
     });
     child.on("error", reject);
-    child.on("close", (code) =>
-      code === 0
-        ? resolve(stdout.trim())
-        : reject(new Error(`Git failed (${code}): ${stderr.trim()}`)),
-    );
+    child.on("close", (code) => {
+      if (code === 0) return resolve(stdout.trim());
+      const error = new Error(`Git failed (${code}): ${stderr.trim()}`);
+      error.exitCode = code;
+      error.gitCommand = args[0];
+      reject(error);
+    });
     child.stdin.end(input);
   });
 }
@@ -86,7 +89,7 @@ export async function requireNewDirectory(directory) {
 export async function checkout(connection, repository, directory) {
   if (repository.status !== "ready")
     throw new Error(
-      "Repository provisioning is incomplete. Retry domino create.",
+      `Repository provisioning is incomplete (status: ${repository.status}). Inspect the existing project in Console, then retry domino checkout. Do not create a replacement project.`,
     );
   const remote = new URL(repository.remote);
   if (
@@ -152,14 +155,42 @@ export async function checkout(connection, repository, directory) {
         environment: "test",
       }) + "\n",
     );
+    const manager = await packageManager(root);
     return {
       directory: root,
       remote: repository.remote,
-      next: "Install dependencies with pnpm install, then run domino dev.",
+      packageManager: manager,
+      scopeFile: resolve(root, ".git/domino.json"),
+      next: manager.installCommand
+        ? `In ${root}, run ${manager.installCommand} and wait for success. Then run the project's installed domino doctor --remote --json before domino dev.`
+        : "Read package.json and install with the project's declared package manager and lockfile. Wait for success before running the installed domino doctor --remote --json.",
     };
   } catch (error) {
     // This directory was created exclusively by this operation and has no user edits.
     await rm(root, { recursive: true, force: true });
+    if (error.gitCommand) {
+      error.code = "CHECKOUT_GIT_FAILED";
+      error.details = {
+        phase: error.gitCommand,
+        exitCode: error.exitCode,
+        classification: /repository not found/i.test(error.message)
+          ? "repository-unavailable"
+          : /authentication failed|401|403/i.test(error.message)
+            ? "access-denied"
+            : "git-failure",
+        repositoryStatus: repository.status,
+        organization: repository.organization,
+        project: repository.project,
+        remote: repository.remote,
+      };
+      error.message += ` Repository API reported ${repository.status}; Git ${error.gitCommand} failed.`;
+      error.message +=
+        error.gitCommand === "fetch"
+          ? " This does not establish whether provisioning, access, or transport caused the failure. Retry checkout once with the same scope; if it repeats, share these diagnostics with the operator."
+          : " Resolve the Git error above before retrying checkout.";
+      error.message +=
+        " Do not recreate the project or install dependencies in its parent directory.";
+    }
     throw error;
   }
 }

package/cli/package-manager.mjs

@@ -0,0 +1,31 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+// Only generate a runnable command for a validated, exact package-manager pin.
+// Never interpolate arbitrary package.json content into a suggested shell command.
+export async function packageManager(directory) {
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(directory, "package.json"), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT")
+      return { declared: null, installCommand: null };
+    return {
+      declared: null,
+      installCommand: null,
+      error:
+        "Cannot read package.json. Restore valid JSON before installing dependencies.",
+    };
+  }
+  const declared =
+    typeof pkg?.packageManager === "string" ? pkg.packageManager : null;
+  const pin =
+    /^(pnpm|npm)@(\d+\.\d+\.\d+(?:-[\w.-]+)?)(?:\+sha\d+\.[a-fA-F0-9]+)?$/.exec(
+      declared ?? "",
+    );
+  if (!pin) return { declared, installCommand: null };
+  const [, name, version] = pin;
+  const install = name === "pnpm" ? "install --frozen-lockfile" : "ci";
+  const runner = `npx --yes ${name}@${version}`;
+  return { declared, installCommand: `${runner} ${install}` };
+}

package/cli/project.mjs

@@ -1,3 +1,4 @@
+import { hostedAppSchema } from "@domino-sdk/relay-cli";
 import { readFile, writeFile, mkdir, access } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { z } from "zod";
@@ -41,16 +42,7 @@ export const projectSchema = z
       })
       .strict()
       .optional(),
-    app: z
-      .object({
-        kind: z.literal("static"),
-        directory: z.string().min(1),
-        devScript: z.string().min(1),
-        checkScript: z.string().min(1),
-        buildScript: z.string().min(1),
-      })
-      .strict()
-      .optional(),
+    app: hostedAppSchema.optional(),
     questTypes: z
       .array(
         z
@@ -136,7 +128,14 @@ export async function readJson(path) {
 }
 
 async function loadProject(path) {
-  const config = projectSchema.parse(await readJson(path));
+  const raw = await readJson(path);
+  const config = projectSchema.parse(raw);
+  const scopeSources = Object.fromEntries(
+    ["apiUrl", "organization", "project", "environment"].map((key) => [
+      key,
+      raw[key] === undefined ? { kind: "default" } : { kind: "manifest", path },
+    ]),
+  );
   const dir = dirname(path);
   // Worktrees keep shared connection metadata in the common Git directory.
   const gitDir = await runGit(["rev-parse", "--git-common-dir"], {
@@ -154,11 +153,16 @@ async function loadProject(path) {
         .strict()
         .parse(await readJson(resolve(dir, gitDir, "domino.json")));
       Object.assign(config, local);
+      for (const key of Object.keys(local))
+        scopeSources[key] = {
+          kind: "checkout",
+          path: resolve(dir, gitDir, "domino.json"),
+        };
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
     }
   }
-  return { path, config };
+  return { path, config, scopeSources };
 }
 
 export async function findProject(path) {

package/cli/runtime.mjs

@@ -8,11 +8,18 @@ export function action(handler) {
     const options = command.optsWithGlobals();
     const project = await findProject(options.config);
     const connection = {};
+    const scopeSources = {};
     for (const key of ["apiUrl", "organization", "project", "environment"]) {
       const env =
         key === "apiUrl" ? "RELAY_API_URL" : `RELAY_${key.toUpperCase()}`;
       connection[key] =
         options[key] ?? process.env[env] ?? project?.config[key];
+      scopeSources[key] =
+        options[key] !== undefined
+          ? { kind: "flag", name: key === "apiUrl" ? "--api-url" : `--${key}` }
+          : process.env[env] !== undefined
+            ? { kind: "environment", name: env }
+            : (project?.scopeSources[key] ?? { kind: "default" });
     }
     connection.apiUrl = apiUrl(connection.apiUrl ?? "https://relay.domino.run");
     if (
@@ -21,7 +28,7 @@ export function action(handler) {
     )
       throw new Error("Environment must be test or live.");
     const result = await handler(
-      { options, project, connection },
+      { options, project, connection, scopeSources },
       ...command.processedArgs,
     );
     console.log(JSON.stringify(result, null, options.json ? undefined : 2));

package/cli/skills/domino/SKILL.md

@@ -42,7 +42,7 @@ Use `domino login` for browser authorization when remote work is needed. As soon
 
 Keep the login process running while the user approves in their browser. The CLI polls for approval and saves the credential itself; never ask the user to paste credentials into chat. Wait for the CLI to confirm success before continuing. If the attempt expires, run `domino login` again and send the new code first, then the new link.
 
-Run `domino doctor --remote --json` to verify access and inspect the effective organization, project, API, and environment before remote operations. Flags and RELAY_* environment variables override relay.json.
+Run `domino doctor --remote --json` after dependency installation finishes to verify access before remote operations. Inspect `scope` and `scopeSources`: flags override `RELAY_*` environment variables, then the Git common directory's `domino.json`, then `relay.json`. Checkout writes the untracked local connection file; starter values such as `local` and `campaign` in the manifest may therefore be valid defaults. Credentials live separately in the user config directory. For scope or setup failures, read [troubleshooting](references/troubleshooting.md).
 
 Choose the reference that matches the task:
 
@@ -51,7 +51,7 @@ Choose the reference that matches the task:
 - Before authoring a quest, read [authoring](references/authoring.md#find-a-snippet) and check the live snippet catalog for a suitable starting point. The same reference covers reusable types, collections, leaderboards, external points, and publication.
 - For standings, own rank, nearby participants, or pagination, read [participant API](references/participant-api.md#leaderboard-reads).
 
-Before designing referrals, rankings, milestones, or rewards for another participant, run `domino capabilities --json`. Read `domino capabilities <id> --json` for the support boundary. Treat an unlisted capability as unknown and inspect its contract before promising it.
+Before designing referrals, rankings, milestones, or rewards for another participant, run `domino capabilities --json`. Read `domino capabilities <id> --json` for the support boundary. The output's `provenance` identifies a bundled CLI catalog, not a project-specific server probe. Treat an unlisted capability or a disagreement with the deployed API as unknown and inspect its contract before promising it. Check recurrence, daily limits, social verification, and prize fulfillment separately; points or leaderboards alone do not establish those mechanics.
 
 For browser integration and submission recovery, read [participant API](references/participant-api.md). For invitation links, qualification, inviter bonuses, or referral milestones, read [referrals](references/referrals.md). For startup, staging, or version failures, read [troubleshooting](references/troubleshooting.md).
 
@@ -61,4 +61,4 @@ If no CLI is installed, install `@domino-sdk/relay-cli` and `@domino-sdk/relay`
 
 Run the app's checks and exercise the requested participant action through the running app. Verify the resulting progress or completion state. Keep fixture-provider results distinct from real external verification.
 
-Return the working preview or local URL, what participant action you verified, and any remaining launch dependency. A successful build, installed skill, or healthy doctor result is not proof of participant behavior. Live publication requires human review in Console; hosted staging uses test data and real sign-in.
+Return the working preview or local URL, what participant action you verified, and any remaining launch dependency. Report failed or blocked browser checks explicitly, including a missing browser executable. A successful build, installed skill, or healthy doctor result is not proof of participant behavior. Live publication requires human review in Console; hosted staging uses test data and real sign-in.

package/cli/skills/domino/references/authoring.md

@@ -31,7 +31,7 @@ Source owns reusable quest definitions, collection slots, and deployment default
 
 Entry `settings` supplies deployment defaults. Remote custom values take precedence on subsequent deployments. A removed or incompatible setting can block the batch. Use `settingRenames` for a deliberate rename, or have the operator reset the custom value in Console under **Quests**. Changing source defaults does not clear overrides.
 
-Use `domino build --json` or `domino deploy --dry-run --json` for offline bundling. These do not validate effective remote settings. Use `domino deploy --preview --json` to resolve and validate the remote batch without publishing. Check the selected scope before publication.
+Use `domino build --json` or `domino deploy --dry-run --json` for offline bundling. To save the bundle, use `domino build --out .domino-build/deployment.json --json`; the CLI creates missing parent directories. These checks do not validate effective remote settings. Use `domino deploy --preview --json` to resolve and validate the remote batch without publishing. Check the selected scope before publication.
 
 Use `domino deploy --environment test --json` when test publication is part of the task. It publishes configured quests, types, collections, and supported interactions together. After a lost publication response, use the returned `domino deploy --resume <id>` recovery command. Starting another deployment may create another immutable release.
 
@@ -110,3 +110,13 @@ The platform supplies a read-only client bound to the project's configured serve
 Successful reads, including absent membership, are stored with the account revision, integration revision, server, and observation time. Recovery reuses captured facts. Changing either connection invalidates unfinished reads. After a failed attempt, start a new submission if a connection changed. Membership screening (`pending`) and role requirements remain author decisions.
 
 The campaign starter includes participant identity controls. Existing apps use the same APIs through `createParticipantBackend`; see [participant API](participant-api.md#connected-accounts). The managed bot is configured by the platform, never by a quest author. Do not invent message, reaction, or write capabilities: `member` is the only Discord operation currently available. X remains unavailable.
+
+The release's `provider` setting selects the photo-check backend used by `ctx.review.photo`; it does not select the evaluator for Discord, quizzes, or other authored checks. `humanReview` allows quest code to return a review decision. It does not automatically route Discord failures to staff. The Discord membership snippet returns accept or reject decisions and leaves provider outages as errors.
+
+## Entry after app-owned pass verification
+
+Author the entry quest with `manual({ actor: "staff" })` and no evidence input. The participant app verifies its event pass on its server, resolves the signed-in member, and calls `POST /management/v1/passes/verify` with `{ provider, event, subject, member, quest }`. Use a server-only management key with `confirm` permission in the intended project and environment. Relay records unique pass ownership and submits the entry attempt; it does not decide whether the external ticket is valid. Repeating the same pass for the same member reuses the durable attempt. A different member cannot claim that pass, and one member cannot link a second pass for the same provider and event.
+
+## Hosted server applications
+
+Quest discovery and private resource artifacts work the same way for static and Worker apps. Keep quest definitions outside the public asset directory. For server-rendered applications, configure the Worker module output and browser asset output separately in `relay.json`; see [hosted apps](hosted.md). With `app.routing="transparent"`, hosting reserves no paths. Omitting the setting preserves legacy routing. The starter owns its `/relay/*` proxy as ordinary application code; custom handlers can take precedence.

package/cli/skills/domino/references/hosted.md

@@ -6,9 +6,9 @@ If Console already created the project and repository, run `domino checkout <pro
 
 For a failure after remote project creation, inspect the existing project's state before repeating creation. Keep partially created local directories intact while recovering. Checkout accepts `--directory` for a fresh destination.
 
-Install dependencies from the lockfile. The starter includes pinned SDK, CLI, and local-runtime archives in `.domino`; upgrade them through a platform package release rather than modifying their contents. Read CAMPAIGN.md for the owner's brief.
+Enter the checked-out directory before installing guidance or dependencies. Use checkout's `packageManager.installCommand`, which selects the exact version declared in package.json and preserves the lockfile. For `pnpm@10.34.5`, this is `npx --yes pnpm@10.34.5 install --frozen-lockfile`. Wait for installation to succeed before running doctor; a missing SDK during installation is not a new fault. If guidance is already installed, do not reinstall it as a remedy for checkout or authentication failures. The starter includes pinned SDK, CLI, and local-runtime archives in `.domino`; upgrade them through a platform package release rather than modifying their contents. Read CAMPAIGN.md for the owner's brief.
 
-The starter is a static Vite app using React, TanStack Router file-based routes, and Tailwind CSS v4. Its look is neutral on purpose (greyscale color tokens in `src/styles.css`, no logo or accent) and it ships sample quests and copy that introduce Domino; replace them with the owner's campaign. Its AGENTS.md maps the source and describes the `src/relay` hooks for session, quest state, submission, and recovery. Build the interface on those hooks and keep their recovery behavior.
+The starter uses Vite, React, TanStack Router file-based routes, and Tailwind CSS v4, with an app-owned Worker in `server/index.ts` for participant requests and browser assets. Its look is neutral on purpose (greyscale color tokens in `src/styles.css`, no logo or accent) and it ships sample quests and copy that introduce Domino; replace them with the owner's campaign. Its AGENTS.md maps the source and describes the `src/relay` hooks for session, quest state, submission, and recovery. Build the interface on those hooks and keep their recovery behavior.
 
 The starter's relay.json declares discovery patterns for `quests/**/*.quest.ts` and `quests/**/*.quest-type.ts`. Add a matching default-exported file to include it in builds and development sync. Installed snippets use these paths. Use explicit entries only for named exports or per-resource overrides.
 
@@ -22,7 +22,7 @@ When the task includes sharing a preview, commit the intended changes and push u
 
 If stage submission loses its response, repeat the printed commit and request ID. Use `domino builds --json` and `domino logs <build-id> --json` to recover progress after disconnecting. A failed build leaves the previous preview active. Report the URL returned for the successful build rather than constructing one.
 
-Cloud staging supports the starter's static app contract. It does not host arbitrary SSR or customer Worker code. New staging builds use the same project test data as development and real participant sign-in. Existing previews created before this update remain simulated until rebuilt. Test data does not imply that external provider operations are simulated. Hosted app live activation remains a separate platform milestone.
+Cloud staging supports static apps and compiled Cloudflare Worker apps, including SSR and server routes. Configure `app.kind="worker"`, `directory` for private modules, `main` relative to that directory, `compatibilityDate`, optional `compatibilityFlags`, and optional `assetsDirectory` for browser assets. Keep `devScript`, `checkScript`, and `buildScript`. TanStack Start with Cloudflare Vite typically uses `dist/server`, `index.js`, `dist/client`, and `nodejs_compat`. The dev server must honor `DOMINO_APP_PORT` and `DOMINO_PREVIEW_ORIGIN`. The build must also emit the starter's private `.domino-build` quest/catalog artifacts. Set `app.routing="transparent"` to preserve methods, cookies, and app authorization. Hosting reserves no URL paths and forwards requests and responses unchanged. The starter explicitly proxies `/relay/*` in its own server, used in both development and staging; apps can override or remove that handler. Use `proxyParticipant(request, { baseUrl, fetch, hosted: true })` to integrate Domino-managed sign-in explicitly. The API validates the registered app origin, session, and CSRF headers. `DOMINO_PARTICIPANT_API` supplies the selected upstream during connected development. `runWorkerFirst: true` lets your Worker handle even requests matching browser assets through its ASSETS binding. Non-secret string `vars` are supported; customer secrets and resource bindings are not provisioned by this contract. New staging builds use the same project test data as development and real participant sign-in. Omitted routing or `app.routing="legacy"` preserves existing gateway behavior, including implicit `/relay/` routes. To migrate, add the app-owned proxy, explicitly select transparent routing, restart and test the preview with the updated CLI, then commit and stage. Routing is recorded per build and preview session; old records and old CLI requests remain legacy. Test data does not imply that external provider operations are simulated. Hosted app live activation remains a separate platform milestone.
 
 For referral programs, register authored modules in `referrals`. `domino check` and `domino dev` include them even without quests. Preserve invitation codes across the app's sign-in redirect and verify acceptance through the configured participant proxy before any quest completes. See [referrals](referrals.md).
 

package/cli/skills/domino/references/participant-api.md

@@ -1,6 +1,6 @@
 # Participant API
 
-Create `createBrowserRelayClient({ baseUrl: "/relay" })` from `@domino-sdk/relay/browser`. The browser client uses cookies and durable submission recovery. The app's server must route `/relay` through the supported participant proxy. Management tokens are not participant credentials.
+Create `createBrowserRelayClient({ baseUrl: "/relay" })` from `@domino-sdk/relay/browser`. The browser client uses cookies and durable submission recovery. With `app.routing="transparent"`, the app explicitly mounts its participant integration at `/relay/*`; hosting does not intercept or reserve that prefix. Existing apps without that setting retain the gateway participant proxy. Management tokens are not participant credentials.
 
 ## Sign in
 
@@ -40,7 +40,7 @@ The browser still uses `createBrowserRelayClient({ baseUrl: "/relay" })`. Reques
 
 The adapter uses `POST /v1/auth/exchange` with `{ subject, previousToken? }` and the integration key as a server bearer credential. Scope and the member role come from the registered integration, never from request input. It adds a server-only integration header when proxying participant requests. A plain exchange result is not a substitute for configuring that routing; use the adapter.
 
-`https://console.domino.run/relay` proxies management requests only. Use the participant API origin for the adapter. The lower-level `proxyParticipant` remains available for deployments with preconfigured participant routing; it deliberately excludes browser Authorization and organization/project/environment selectors.
+`https://console.domino.run/relay` proxies management requests only. Use the participant API origin for the adapter. For Domino-managed sign-in in a hosted preview or staging app, explicitly call `proxyParticipant(request, { baseUrl: "https://relay.domino.run", fetch, hosted: true })` from an app-owned route. The API resolves the app origin against its registration and still validates sessions and CSRF. The lower-level `proxyParticipant` also supports deployments with preconfigured participant routing; it deliberately excludes browser Authorization and organization/project/environment selectors.
 
 ## Display and complete quests
 
@@ -107,3 +107,11 @@ To choose a different identity, first call `relay.auth.disconnect("discord")`. T
 The campaign starter includes these account controls. Apps using `createParticipantBackend` retain their own login and use the same APIs. The adapter preserves OAuth binding cookies and its session during return navigation; the application's own login cookie must also support top-level OAuth returns. If the app session changes during consent, start connection again.
 
 After changing an account or integration during a failed attempt, use the quest controller's `discard()` to clear the saved failed submission, then submit again. The starter labels this **Start a new submission**. Discard is allowed only after a confirmed failed or rejected attempt. It keeps server history and cannot discard an active or accepted attempt. Use `resume()` when the connection has not changed to preserve captured facts.
+
+## Resource IDs
+
+Treat resource IDs as opaque strings and store the complete value. New generated IDs keep their resource prefix, such as `member_`, `session_`, or `attempt_`, followed by 22 random alphanumeric characters. Existing IDs remain valid. Do not parse the suffix as a UUID.
+
+## Removed demo shortcuts
+
+`auth.demoSignIn` and the campaign template endpoint are no longer supported. Use managed sign-in or a registered identity integration. The platform participant `me.linkPass` route remains unconfigured. An app can handle that route itself and verify a pass on its server, then call `POST /management/v1/passes/verify` with a server-only management key carrying `confirm` permission. Send `{ provider, event, subject, member, quest }` and the usual organization, project, and environment headers. Resolve the member from the authenticated participant session, never from browser input. The quest must be staff-confirmed with no evidence. Relay binds ownership uniquely per provider/event in that project, preserves the authenticated management actor, and retries the same entry attempt. There is no built-in event-code verifier.

package/cli/skills/domino/references/troubleshooting.md

@@ -1,5 +1,23 @@
 # Development and staging diagnostics
 
+## Scope and installation
+
+Read `scopeSources` next to `scope` in `domino doctor --json`. Each value comes from a command flag, a named `RELAY_*` environment variable, the checkout's local connection file, the manifest, or a default. Precedence is flags > environment > checkout connection > manifest. `domino checkout` writes `.git/domino.json`; linked Git worktrees read the file in their shared Git common directory. This untracked file contains API, organization, project, and environment identifiers, not credentials. Do not rewrite starter manifest values merely because they differ from the effective scope.
+
+Use the `packageManager.installCommand` printed by checkout or doctor. It selects the declared version with a frozen lockfile. Wait for the install process to finish before diagnosing missing dependencies. Run checks from the project directory. Without a manifest, `doctor --remote` does not probe the remote and cannot explain why checkout failed.
+
+For `CHECKOUT_GIT_FAILED`, retain the original Git message and the structured `details`: failed phase, exit code, error classification, repository status reported by the API, project, and remote. A `ready` API status combined with a Git "Repository not found" error does not establish whether provisioning, permissions, or transport caused the failure. Retry the same checkout once. If it fails again, send the diagnostics to the operator and keep the existing Console project. Do not create a replacement, reinstall skills in a parent directory, or repeatedly run unrelated diagnostics.
+
+## Capability disagreements
+
+`domino capabilities` reads the catalog bundled with the CLI version in `provenance.cliVersion`. It does not request server capabilities; `serverVerified` is false even when project flags are supplied. Compare the installed version, the applicable public contract, and the actual deployed endpoint before changing the architecture. A successful management route does not by itself prove participant access or payout support. A missing route or catalog entry does not prove platform-wide non-support.
+
+## Verification failures
+
+Keep build results, browser rendering, and participant behavior separate. If a browser executable is missing or a check fails, report the exact blocked check and leave its behavior unverified. Do not turn a generated visual sample or a successful build into a claim that the app works in a browser.
+
+## Preview diagnostics
+
 Start with `domino doctor --json`. Add `--remote` to verify project access, publication permission, hosting configuration and repository readiness. Configuration checks do not prove a successful build or real participant sign-in. If cloud hosting is missing, a Domino operator must configure it; changing quest code will not fix it.
 
 `domino check` runs the app's checks and bundles authored entries. `domino deploy --preview --environment test --json` validates the effective deployment against the server without publishing. Test and live data are separate; test does not imply external provider requests are fake.

package/cli.mjs

@@ -82,7 +82,8 @@ const program = new Command()
   .addHelpText(
     "after",
     `
-Scope: flags > RELAY_* environment variables > nearest relay.json.
+Scope: flags > RELAY_* environment variables > Git-common-directory domino.json > nearest relay.json.
+Run domino doctor --json to see effective scope values and their sources.
 API default: https://relay.domino.run. Init defaults to test.
 Credentials: RELAY_MANAGEMENT_TOKEN > saved token for the API origin.
 Run domino login for browser sign-in. Live publication requires Console.
@@ -108,6 +109,8 @@ try {
         ? JSON.stringify({
             error: error.message,
             ...(error.status ? { status: error.status } : {}),
+            ...(error.code ? { code: error.code } : {}),
+            ...(error.details ? { details: error.details } : {}),
           })
         : `Error: ${error.message}`,
     );

package/dist/index.d.ts

@@ -1,6 +1,37 @@
 import { pointsMutationSchema, referralControlSchema, leaderboardQuerySchema, leaderboardExclusionSchema, leaderboardGroupSchema, projectDeploymentSchema, publishDeploymentSchema, catalogDeploymentSchema, saveQuestDraftSchema, publishQuestDraftSchema, collectionBeginSchema, configurePickupSchema } from '@domino-sdk/relay';
 import { z } from 'zod';
 
+declare const appRoutingSchema: z.ZodDefault<z.ZodEnum<{
+    legacy: "legacy";
+    transparent: "transparent";
+}>>;
+declare const hostedAppSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    routing: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        transparent: "transparent";
+    }>>;
+    devScript: z.ZodString;
+    checkScript: z.ZodString;
+    buildScript: z.ZodString;
+    kind: z.ZodLiteral<"static">;
+    directory: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    runWorkerFirst: z.ZodDefault<z.ZodBoolean>;
+    main: z.ZodString;
+    compatibilityDate: z.ZodString;
+    compatibilityFlags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    vars: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    routing: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        transparent: "transparent";
+    }>>;
+    devScript: z.ZodString;
+    checkScript: z.ZodString;
+    buildScript: z.ZodString;
+    kind: z.ZodLiteral<"worker">;
+    directory: z.ZodString;
+    assetsDirectory: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
 declare const repositorySchema: z.ZodObject<{
     id: z.ZodString;
     organization: z.ZodString;
@@ -32,6 +63,11 @@ declare const stageRequestSchema: z.ZodObject<{
     requestId: z.ZodString;
 }, z.core.$strict>;
 declare const buildIdentitySchema: z.ZodObject<{
+    routing: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        transparent: "transparent";
+    }>>;
+    slug: z.ZodOptional<z.ZodString>;
     runtime: z.ZodDefault<z.ZodEnum<{
         simulation: "simulation";
         "hosted-test": "hosted-test";
@@ -82,6 +118,11 @@ declare const buildStatusSchema: z.ZodObject<{
 }, z.core.$strip>;
 type BuildStatus = z.infer<typeof buildStatusSchema>;
 declare const hostedBuildSchema: z.ZodObject<{
+    routing: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        transparent: "transparent";
+    }>>;
+    slug: z.ZodOptional<z.ZodString>;
     runtime: z.ZodDefault<z.ZodEnum<{
         simulation: "simulation";
         "hosted-test": "hosted-test";
@@ -123,6 +164,11 @@ declare const hostedBuildSchema: z.ZodObject<{
 type HostedBuild = z.infer<typeof hostedBuildSchema>;
 declare const buildSnapshotSchema: z.ZodObject<{
     builds: z.ZodArray<z.ZodObject<{
+        routing: z.ZodDefault<z.ZodEnum<{
+            legacy: "legacy";
+            transparent: "transparent";
+        }>>;
+        slug: z.ZodOptional<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
             simulation: "simulation";
             "hosted-test": "hosted-test";
@@ -162,6 +208,11 @@ declare const buildSnapshotSchema: z.ZodObject<{
         message: z.ZodString;
     }, z.core.$strip>>;
     current: z.ZodNullable<z.ZodObject<{
+        routing: z.ZodDefault<z.ZodEnum<{
+            legacy: "legacy";
+            transparent: "transparent";
+        }>>;
+        slug: z.ZodOptional<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
             simulation: "simulation";
             "hosted-test": "hosted-test";
@@ -201,6 +252,11 @@ declare const buildSnapshotSchema: z.ZodObject<{
         message: z.ZodString;
     }, z.core.$strip>>;
     selected: z.ZodNullable<z.ZodObject<{
+        routing: z.ZodDefault<z.ZodEnum<{
+            legacy: "legacy";
+            transparent: "transparent";
+        }>>;
+        slug: z.ZodOptional<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
             simulation: "simulation";
             "hosted-test": "hosted-test";
@@ -245,6 +301,27 @@ type BuildSnapshot = z.infer<typeof buildSnapshotSchema>;
 declare const assetPathSchema: z.ZodString;
 declare const buildArtifactsSchema: z.ZodObject<{
     format: z.ZodLiteral<1>;
+    routing: z.ZodDefault<z.ZodEnum<{
+        legacy: "legacy";
+        transparent: "transparent";
+    }>>;
+    worker: z.ZodOptional<z.ZodObject<{
+        modules: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            type: z.ZodEnum<{
+                "application/javascript+module": "application/javascript+module";
+                "application/wasm": "application/wasm";
+                "text/plain": "text/plain";
+                "application/octet-stream": "application/octet-stream";
+            }>;
+            content: z.ZodString;
+        }, z.core.$strict>>;
+        runWorkerFirst: z.ZodDefault<z.ZodBoolean>;
+        main: z.ZodString;
+        compatibilityDate: z.ZodString;
+        compatibilityFlags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        vars: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strict>>;
     assets: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         content: z.ZodString;
@@ -319,6 +396,7 @@ declare const projectSetupSchema: z.ZodObject<{
     brief: z.ZodString;
 }, z.core.$strict>;
 declare const projectSchema: z.ZodObject<{
+    slug: z.ZodString;
     setup: z.ZodOptional<z.ZodObject<{
         mode: z.ZodEnum<{
             new: "new";
@@ -378,6 +456,7 @@ declare const accessSchema: z.ZodObject<{
     admin: z.ZodBoolean;
     local: z.ZodBoolean;
     projects: z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
         setup: z.ZodOptional<z.ZodObject<{
             mode: z.ZodEnum<{
                 new: "new";
@@ -5615,6 +5694,7 @@ declare function createManagementClient(options: {
         admin: boolean;
         local: boolean;
         projects: {
+            slug: string;
             id: string;
             organization: string;
             project: string;
@@ -5631,6 +5711,7 @@ declare function createManagementClient(options: {
         }[];
     }>;
     createProject: (input: z.infer<typeof projectInputSchema>) => Promise<{
+        slug: string;
         id: string;
         organization: string;
         project: string;
@@ -6781,4 +6862,4 @@ declare function createManagementClient(options: {
     }>;
 };
 
-export { type Access, type AuditRecord, type BuildArtifacts, type BuildIdentity, type BuildSnapshot, type BuildStatus, type HostedBuild, type ListQuery, type ManagementPage, type Permission, type Project, accessSchema, accountProfileSchema, assetPathSchema, auditRecordSchema, buildArtifactsSchema, buildIdentitySchema, buildPhaseSchema, buildSnapshotSchema, buildStatusSchema, commitSchema, createManagementClient, createRepositorySchema, developmentPreflightSchema, deviceApproveSchema, deviceRedeemSchema, deviceStartSchema, environmentSchema, grantSchema, hostedBuildSchema, inventorySchema, memberAccountSchema, memberDetailSchema, memberSchema, metricsSchema, operationInputSchema, operationSchema, pageSchema, permissionSchema, projectInputSchema, projectSchema, projectSetupSchema, querySchema, readinessSchema, repositorySchema, rolePermissions, roleSchema, stageRequestSchema, stockInputSchema, tokenInputSchema, tokenSchema };
+export { type Access, type AuditRecord, type BuildArtifacts, type BuildIdentity, type BuildSnapshot, type BuildStatus, type HostedBuild, type ListQuery, type ManagementPage, type Permission, type Project, accessSchema, accountProfileSchema, appRoutingSchema, assetPathSchema, auditRecordSchema, buildArtifactsSchema, buildIdentitySchema, buildPhaseSchema, buildSnapshotSchema, buildStatusSchema, commitSchema, createManagementClient, createRepositorySchema, developmentPreflightSchema, deviceApproveSchema, deviceRedeemSchema, deviceStartSchema, environmentSchema, grantSchema, hostedAppSchema, hostedBuildSchema, inventorySchema, memberAccountSchema, memberDetailSchema, memberSchema, metricsSchema, operationInputSchema, operationSchema, pageSchema, permissionSchema, projectInputSchema, projectSchema, projectSetupSchema, querySchema, readinessSchema, repositorySchema, rolePermissions, roleSchema, stageRequestSchema, stockInputSchema, tokenInputSchema, tokenSchema };

package/dist/index.js

@@ -32,6 +32,46 @@ import { z as z3 } from "zod";
 // src/hosting.ts
 import { z } from "zod";
 import { identifier } from "@domino-sdk/relay";
+var outputPathSchema = z.string().min(1).max(512).refine(
+  (path) => path.split("/").every(
+    (part) => /^[\w-][\w.-]*$/.test(part) && part !== "node_modules"
+  ),
+  "Expected a relative build output path without hidden segments"
+);
+var appRoutingSchema = z.enum(["legacy", "transparent"]).default("legacy");
+var appScripts = {
+  routing: appRoutingSchema,
+  devScript: z.string().regex(/^[\w:-]+$/),
+  checkScript: z.string().regex(/^[\w:-]+$/),
+  buildScript: z.string().regex(/^[\w:-]+$/)
+};
+var workerSettings = {
+  runWorkerFirst: z.boolean().default(false),
+  main: outputPathSchema.refine(
+    (path) => /\.m?js$/.test(path),
+    "Expected a compiled JavaScript entry"
+  ),
+  compatibilityDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+  compatibilityFlags: z.array(z.string().min(1)).max(50).default([]),
+  vars: z.record(
+    z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/).refine((name) => name !== "ASSETS"),
+    z.string()
+  ).default({})
+};
+var hostedAppSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("static"),
+    directory: outputPathSchema,
+    ...appScripts
+  }).strict(),
+  z.object({
+    kind: z.literal("worker"),
+    directory: outputPathSchema,
+    assetsDirectory: outputPathSchema.optional(),
+    ...appScripts,
+    ...workerSettings
+  }).strict()
+]);
 var repositorySchema = z.object({
   id: z.string().uuid(),
   organization: identifier,
@@ -60,6 +100,8 @@ var stageRequestSchema = z.object({
   requestId: z.string().uuid()
 }).strict();
 var buildIdentitySchema = z.object({
+  routing: appRoutingSchema,
+  slug: z.string().min(1).max(35).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional(),
   runtime: z.enum(["simulation", "hosted-test"]).default("simulation"),
   id: z.string().uuid(),
   repository: z.string().uuid(),
@@ -99,11 +141,29 @@ var buildSnapshotSchema = z.object({
   logs: z.string()
 });
 var assetPathSchema = z.string().max(512).refine(
-  (path) => path.startsWith("/") && !/[\\\u0000-\u001f?#%]/.test(path) && path.slice(1).split("/").every((part) => part.length > 0 && !part.startsWith(".")) && !path.startsWith("/relay/") && !path.startsWith("/__domino/"),
-  "Expected a public asset path without hidden or reserved segments"
+  (path) => path.startsWith("/") && !/[\\\u0000-\u001f?#%]/.test(path) && path.slice(1).split("/").every((part) => part.length > 0 && !part.startsWith(".")),
+  "Expected a public asset path without hidden segments"
 );
 var buildArtifactsSchema = z.object({
   format: z.literal(1),
+  routing: appRoutingSchema,
+  worker: z.object({
+    ...workerSettings,
+    modules: z.array(
+      z.object({
+        path: outputPathSchema.refine((path) => path !== "metadata"),
+        type: z.enum([
+          "application/javascript+module",
+          "application/wasm",
+          "text/plain",
+          "application/octet-stream"
+        ]),
+        content: z.string().max(14e6).regex(
+          /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/
+        )
+      }).strict()
+    ).min(1).max(500)
+  }).strict().optional(),
   assets: z.array(
     z.object({
       path: assetPathSchema,
@@ -112,13 +172,36 @@ var buildArtifactsSchema = z.object({
       ),
       size: z.number().int().min(0).max(1e7)
     }).strict()
-  ).min(1).max(500),
+  ).max(500),
   quests: z.unknown(),
   catalog: z.unknown()
 }).strict().superRefine((value, ctx) => {
+  if (value.worker) {
+    const modules = value.worker.modules;
+    if (new Set(modules.map((m) => m.path)).size !== modules.length)
+      ctx.addIssue({
+        code: "custom",
+        message: "Duplicate Worker module paths"
+      });
+    if (!modules.some(
+      (m) => m.path === value.worker?.main && m.type === "application/javascript+module"
+    ))
+      ctx.addIssue({
+        code: "custom",
+        message: "Worker entry module is missing"
+      });
+    if (modules.reduce(
+      (sum, m) => sum + m.content.length * 3 / 4 - (m.content.endsWith("==") ? 2 : m.content.endsWith("=") ? 1 : 0),
+      0
+    ) > 1e7)
+      ctx.addIssue({
+        code: "custom",
+        message: "Worker modules exceed 10 MB"
+      });
+  }
   if (new Set(value.assets.map((a) => a.path)).size !== value.assets.length)
     ctx.addIssue({ code: "custom", message: "Duplicate asset paths" });
-  if (!value.assets.some((a) => a.path === "/index.html"))
+  if (!value.worker && !value.assets.some((a) => a.path === "/index.html"))
     ctx.addIssue({
       code: "custom",
       message: "Build must include index.html"
@@ -193,6 +276,7 @@ var projectSetupSchema = z3.object({
   brief: z3.string().trim().min(1).max(4e3)
 }).strict();
 var projectSchema = z3.object({
+  slug: z3.string().min(1).max(35).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
   setup: projectSetupSchema.optional(),
   id: z3.string().min(1),
   organization: identifier2,
@@ -526,6 +610,7 @@ function createManagementClient(options) {
 export {
   accessSchema,
   accountProfileSchema,
+  appRoutingSchema,
   assetPathSchema,
   auditRecordSchema,
   buildArtifactsSchema,
@@ -542,6 +627,7 @@ export {
   deviceStartSchema,
   environmentSchema,
   grantSchema,
+  hostedAppSchema,
   hostedBuildSchema,
   inventorySchema,
   memberAccountSchema,

package/package.json

@@ -10,9 +10,9 @@
   "dependencies": {
     "commander": "15.0.0",
     "zod": "4.3.6",
-    "@domino-sdk/relay": "0.4.0"
+    "@domino-sdk/relay": "0.5.0"
   },
-  "version": "0.4.0",
+  "version": "0.5.0",
   "bin": {
     "domino": "./cli.mjs"
   },