@domino-sdk/relay-cli 0.3.0 → 0.5.0

package/cli/project.mjs

@@ -1,8 +1,23 @@
+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";
 import { buildQuest } from "@domino-sdk/relay/build";
 import { runGit } from "./git.mjs";
+import { defaultDiscovery, discoverEntries } from "./discovery.mjs";
+
+const discoveryPattern = z
+  .string()
+  .min(1)
+  .refine(
+    (pattern) =>
+      !pattern.startsWith("/") &&
+      !pattern.startsWith("!") &&
+      !pattern.includes("\\") &&
+      !pattern.includes(":") &&
+      !pattern.split("/").includes(".."),
+    "Discovery patterns must be relative to relay.json, without parent traversal or negation.",
+  );
 
 export const projectSchema = z
   .object({
@@ -11,16 +26,23 @@ export const projectSchema = z
     organization: z.string().min(1),
     project: z.string().min(1),
     environment: z.enum(["test", "live"]).default("test"),
-    app: z
+    discover: 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),
+        quests: z.array(discoveryPattern).default([]),
+        questTypes: z.array(discoveryPattern).default([]),
+        provider: z
+          .enum([
+            "workers-ai",
+            "fixture-pass",
+            "fixture-fail",
+            "fixture-unclear",
+            "fixture-error",
+          ])
+          .default("workers-ai"),
       })
       .strict()
       .optional(),
+    app: hostedAppSchema.optional(),
     questTypes: z
       .array(
         z
@@ -35,10 +57,32 @@ export const projectSchema = z
                 "fixture-unclear",
                 "fixture-error",
               ])
-              .default("workers-ai"),
+              .optional(),
+          })
+          .strict(),
+      )
+      .default([]),
+    leaderboards: z
+      .array(
+        z
+          .object({
+            entry: z.string().min(1),
+            exportName: z.string().optional(),
           })
           .strict(),
       )
+      .max(50)
+      .default([]),
+    referrals: z
+      .array(
+        z
+          .object({
+            entry: z.string().min(1),
+            exportName: z.string().optional(),
+          })
+          .strict(),
+      )
+      .max(50)
       .default([]),
     collections: z
       .array(
@@ -70,7 +114,7 @@ export const projectSchema = z
                 "fixture-error",
                 "workers-ai",
               ])
-              .default("workers-ai"),
+              .optional(),
           })
           .strict(),
       )
@@ -84,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"], {
@@ -102,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) {
@@ -124,9 +180,34 @@ export async function findProject(path) {
   }
 }
 
-export async function bundleProject(project) {
+export async function bundleProject(project, { allowEmpty = false } = {}) {
+  const quests = await discoverEntries(project, "quests");
+  const questTypes = await discoverEntries(project, "questTypes");
+  if (quests.length > 50)
+    throw new Error("A project deployment supports at most 50 quests.");
+  const questEntries = new Set(
+    quests.map((q) =>
+      JSON.stringify([
+        resolve(dirname(project.path), q.entry),
+        q.exportName ?? "default",
+      ]),
+    ),
+  );
+  for (const type of questTypes) {
+    if (
+      questEntries.has(
+        JSON.stringify([
+          resolve(dirname(project.path), type.entry),
+          type.exportName ?? "default",
+        ]),
+      )
+    )
+      throw new Error(
+        `Entry is registered as both a quest and a quest type: ${type.entry}`,
+      );
+  }
   const releases = [];
-  for (const quest of project.config.quests) {
+  for (const quest of quests) {
     const artifact = await buildQuest(
       resolve(dirname(project.path), quest.entry),
       { exportName: quest.exportName },
@@ -138,30 +219,68 @@ export async function bundleProject(project) {
       provider: quest.provider,
     });
   }
-  const catalog = await bundleCatalog(project);
+  const types = [];
+  for (const type of questTypes) {
+    const artifact = await buildQuest(
+      resolve(dirname(project.path), type.entry),
+      { exportName: type.exportName },
+    );
+    types.push({ ...artifact, provider: type.provider });
+  }
+  const catalog = {
+    types,
+    collections: project.config.collections,
+    ...(project.config.supportedInteractions
+      ? { supportedInteractions: project.config.supportedInteractions }
+      : {}),
+  };
+  const leaderboards = await Promise.all(
+    project.config.leaderboards.map((board) =>
+      buildQuest(resolve(dirname(project.path), board.entry), {
+        exportName: board.exportName,
+      }),
+    ),
+  );
+  const referrals = await Promise.all(
+    project.config.referrals.map((entry) =>
+      buildQuest(resolve(dirname(project.path), entry.entry), {
+        exportName: entry.exportName,
+      }),
+    ),
+  );
   if (
+    !allowEmpty &&
+    !referrals.length &&
     !releases.length &&
+    !leaderboards.length &&
     !catalog.types.length &&
     !catalog.collections.length &&
     !catalog.supportedInteractions
   )
     throw new Error(
-      "No resources configured. Add quests, questTypes, collections, or supportedInteractions to relay.json.",
+      "No resources configured. Add files matching discover in relay.json, or configure quests, questTypes, leaderboards, referrals, collections, or supportedInteractions.",
     );
-  return { releases, ...catalog };
+  return { releases, leaderboards, referrals, ...catalog };
 }
 
 export async function initialize(directory, config) {
   const root = resolve(directory);
   const files = {
-    "relay.json": JSON.stringify(projectSchema.parse(config), null, 2) + "\n",
+    "relay.json":
+      JSON.stringify(
+        projectSchema.parse({ discover: defaultDiscovery, ...config }),
+        null,
+        2,
+      ) + "\n",
     "RELAY.md": `# Relay project
 
-Use Codex or Claude to author your quests with @domino-sdk/relay/authoring. Project scope and quest entries are in relay.json. Relay imposes no framework, source directory, package manager, or application build configuration. Keep your existing project setup. Add @domino-sdk/relay with your package manager, or link the local SDK while it is unpublished. The CLI is supplied by @domino-sdk/relay-cli, separately from the runtime SDK. Commit relay.json and RELAY.md; credentials live in your user config directory.
+Use Codex or Claude to author your quests with @domino-sdk/relay/authoring. Project scope, discovery patterns, and optional quest entries are in relay.json. Relay imposes no framework, source directory, package manager, or application build configuration. Keep your existing project setup. Add @domino-sdk/relay with your package manager. The CLI is supplied by @domino-sdk/relay-cli, separately from the runtime SDK. Commit relay.json and RELAY.md; credentials live in your user config directory.
+
+Before authoring a new quest, run domino reference authoring for the snippet discovery and installation workflow. The public catalog is https://snippets.domino.run/r/registry.json. Install project agent guidance with domino agents install so Codex and Claude can find this workflow automatically.
 
 Run domino build or domino deploy --dry-run to bundle the complete manifest locally. Run domino deploy --preview to inspect effective remote settings without publishing, and domino deploy to atomically publish quests, questTypes, collections, and supportedInteractions to test. For live, export domino deploy --dry-run --out deployment.json and review the project bundle in Console. Run domino quests or domino releases to inspect the server. Live publication requires Console.
 
-Author quests with @domino-sdk/relay/authoring. Each entry points to any authored module relative to relay.json and default-exports defineQuest, or specifies exportName. No dedicated quests directory is required. Example entry: {"entry":"src/community/welcome.ts","settings":{},"provider":"fixture-pass"}. Fixture providers simulate verification; use workers-ai only on an API with the AI binding configured. Settings are deployment defaults validated by the server at publication. Console custom values persist in Relay and take precedence on every deployment; no source edits are needed to retain them. Deploy output reports defaults, custom values, and effective values. Use Console to reset a setting to its deployment default. Removing or invalidating a custom setting blocks the whole batch. For a rename, add settingRenames: {"oldName":"newName"} to the quest entry to carry custom values forward. A dry run builds locally and does not preview remote custom values. Multiple quests deploy as one batch so prerequisites can refer to other quests in the batch.
+Author quests with @domino-sdk/relay/authoring. The discover patterns in relay.json select default-exported quests and quest types. Init configures quests/**/*.quest.ts and quests/**/*.quest-type.ts. Add matching files without registering each one. Customize the patterns for other source layouts. Discovery never executes modules on the build host. Set discover.provider for local fixture verification; it defaults to workers-ai. Explicit entries override matching discovered default exports and can supply settings, provider, and settingRenames. Each entry points to any authored module relative to relay.json and default-exports defineQuest, or specifies exportName. No dedicated quests directory is required. Example entry: {"entry":"src/community/welcome.ts","settings":{},"provider":"fixture-pass"}. Fixture providers simulate verification; use workers-ai only on an API with the AI binding configured. Settings are deployment defaults validated by the server at publication. Console custom values persist in Relay and take precedence on every deployment; no source edits are needed to retain them. Deploy output reports defaults, custom values, and effective values. Use Console to reset a setting to its deployment default. Removing or invalidating a custom setting blocks the whole batch. For a rename, add settingRenames: {"oldName":"newName"} to the quest entry to carry custom values forward. A dry run builds locally and does not preview remote custom values. Multiple quests deploy as one batch so prerequisites can refer to other quests in the batch.
 
 References: @domino-sdk/relay/authoring provides declarations; @domino-sdk/relay/build bundles without executing author code on the host; domino --help lists commands. Set RELAY_MANAGEMENT_TOKEN for CI. Use --json for machine-readable output. Never put tokens in relay.json or source files.
 `,
@@ -183,24 +302,6 @@ References: @domino-sdk/relay/authoring provides declarations; @domino-sdk/relay
   return {
     directory: root,
     files: Object.keys(files),
-    next: "Add @domino-sdk/relay to your existing package with your package manager, then configure quest entries in relay.json and run domino build.",
-  };
-}
-
-export async function bundleCatalog(project) {
-  const types = [];
-  for (const type of project.config.questTypes) {
-    const artifact = await buildQuest(
-      resolve(dirname(project.path), type.entry),
-      { exportName: type.exportName },
-    );
-    types.push({ ...artifact, provider: type.provider });
-  }
-  return {
-    types,
-    collections: project.config.collections,
-    ...(project.config.supportedInteractions
-      ? { supportedInteractions: project.config.supportedInteractions }
-      : {}),
+    next: "Add @domino-sdk/relay, then add default-exported quests in quests/*.quest.ts or reusable types in quests/*.quest-type.ts and run domino build. Customize discover in relay.json for other layouts.",
   };
 }

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

@@ -1,29 +1,59 @@
 ---
 name: domino
-description: Set up a Domino project, integrate Domino into an existing app, author quests, or verify and stage a participant experience with the Domino CLI and SDK.
+description: Set up a Domino project, integrate Domino into an existing app, find and adapt quest snippets, author quests, leaderboards, or referrals, supply external points, or verify and stage a participant experience with the Domino CLI and SDK.
 ---
 
 # Build with Domino
 
 Deliver the requested participant experience and evidence that its main action works. Domino owns verification, completion, points, and reward execution. The app owns its presentation and integration with participant identity.
 
+## Discover and confirm the campaign
+
+Read existing project instructions and saved decisions first. If the owner already confirmed the relevant campaign, reuse that evidence; reopen only decisions affected by a material change. Choose the procedure for the app being built.
+
+### Existing apps: confirm the campaign
+
+Preserve the app's current design, components, and UI conventions. Skip brand discovery, brand-name or website questions, visual samples, and brand approval unless the owner explicitly requests a redesign.
+
+Ask only for missing campaign basics: goal, intended participants, desired actions, and reason to participate. If these are missing, ask a few short questions, end the turn, and wait for answers before setup or implementation. Use answers already supplied. Inspect the app to identify where the participant flow belongs, then propose the campaign and smallest integration that fits its existing UI. Resolve consequential rewards, timing, and eligibility gaps with the owner. Wait for explicit campaign confirmation before implementing, and save the confirmed brief and remaining open decisions in the app's established project document. Reuse prior confirmation when it covers the work. Continue with [existing apps](references/existing-app.md) for integration steps.
+
+### New apps: discover the brand and campaign
+
+Before implementing a new app, establish the brand direction and campaign brief with the owner. A starter, initial prompt, or Console brief is input to discovery, not confirmation. The procedure below applies to new apps only.
+
+1. **Ask before researching or designing.** Check the supplied brief and prior owner answers for a brand name, official website or reference, campaign goal, intended participants, desired actions, and reason to participate. Ask for missing basics in a few short questions, then end the turn and wait for the owner's answers. For an empty or vague brief, ask both which brand this is for and what the campaign should achieve. The owner may confirm there is no website or established brand. A project name, repository name, starter, or sample quest is not evidence of brand identity or campaign intent. Create a new brand only when the owner explicitly requests it. If the basics are already supplied, summarize them for confirmation instead of asking the same questions again. Complete this intake before login, setup commands, research, or a visual proposal.
+2. **Research and prepare the proposal.** After intake, inspect the owner's website, project documents, and supplied assets, including rendered appearance and styles. Record source URLs or file paths. If a source is inaccessible or identity remains ambiguous, ask the owner for a reference and wait rather than guessing. Show a concise brand interpretation and a small visual sample using the proposed colors, type, and voice. Draft the campaign goal, success measure, intended participants, desired actions, participant motivation, and journey from the owner's answers. Include timing, rewards, eligibility, and constraints where relevant. Suggest improvements tied to the goal and check Domino capabilities before promising supported behavior.
+3. **Resolve consequential gaps.** Separate observed facts, recommendations, and assumptions. Ask only questions whose answers materially change the experience, a few at a time, with a recommended answer where possible. Use research and existing answers instead of giving the owner a questionnaire. Keep unconfirmed rewards, budgets, inventory, dates, and eligibility explicit as open decisions; do not turn guesses into participant promises.
+4. **Confirm and save.** Present the proposed brand direction and campaign brief together for the owner to confirm or correct. End the turn and wait for their explicit response before implementation; silence and your own confidence are not confirmation. After intake, you may inspect and connect the project, research, write the draft brief, and prepare the visual sample. Keep app implementation and campaign configuration until after confirmation. Save the agreed direction, evidence of the owner's confirmation, sources, and remaining open decisions in CAMPAIGN.md, or the existing app's established brief document. Preserve the original request and link to the brief if it lives elsewhere.
+
+Discovery is complete when the owner has confirmed the brand direction and campaign intent, including the goal, participants, actions, and motivation. Optional details can remain open if they do not affect the first implementation; record what must wait for those decisions. On subsequent sessions, read the saved brief and continue without repeating onboarding.
+
 ## Establish the project
 
 Read the project's agent instructions and owner brief, such as CAMPAIGN.md, when present. Inspect package scripts and relay.json before selecting commands. Use the installed CLI through the project's package manager, such as `pnpm exec domino`; the examples below abbreviate this to `domino`.
 
 Run `domino doctor --json` to inspect setup without running application code or contacting the service. Missing setup produces exit 1 with diagnostic JSON on stdout. Invalid configuration uses the CLI's standard error JSON on stderr. Fix the reported prerequisite, then rerun the check.
 
-Use `domino login` for browser authorization when remote work is needed. The user approves the displayed code in Console. Credentials stay in the CLI credential store. 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.
+Use `domino login` for browser authorization when remote work is needed. As soon as the CLI prints the login details, send the user the code first, then the clickable sign-in link, in the same message. Always preserve this order, even if the CLI prints the link first. Use the exact code and URL from the current login attempt:
+
+> Code: `<code from CLI>`
+>
+> [Open Domino to sign in](<URL from CLI>) and enter this code to approve the CLI connection.
+
+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` 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:
 
 - For a new Domino-hosted app, checkout, or hosted preview, read [hosted projects](references/hosted.md).
 - For integration into an existing codebase, read [existing apps](references/existing-app.md).
-- For quest definitions, reusable types, collections, or publication, read [authoring](references/authoring.md).
+- 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 referral campaigns, read [referrals](references/referrals.md). For startup, staging, or version failures, read [troubleshooting](references/troubleshooting.md).
+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).
 
 If no CLI is installed, install `@domino-sdk/relay-cli` and `@domino-sdk/relay` through the app's package manager. Starter archives pin the packages they were verified with; retain their lockfile and `.domino/release.json` when diagnosing compatibility.
 
@@ -31,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

@@ -2,14 +2,121 @@
 
 Read the installed `@domino-sdk/relay/authoring` declarations and the project's existing quest modules. Define the requested behavior with the supported SDK helpers rather than inventing capabilities. Authored entries in relay.json resolve relative to that manifest and can select a named export with `exportName`.
 
+The `discover.quests` and `discover.questTypes` arrays in relay.json select default-exported resource files. New projects use `quests/**/*.quest.ts` and `quests/**/*.quest-type.ts`. Add matching files without individual registration. Existing manifests without `discover` keep explicit-entry behavior. An explicit entry overrides the matching discovered default export; omitted providers inherit `discover.provider` for those files. Discovery does not execute authored modules on the build host, publish them, or archive omitted resources.
+
+## Find a snippet
+
+Before writing a new quest, fetch the public catalog. It requires no authentication:
+
+```sh
+curl -fsS https://snippets.domino.run/r/registry.json
+```
+
+1. Match the requested behavior against each item's `title`, `description`, and `categories`. Use the catalog's `name` to fetch `https://snippets.domino.run/r/<name>.json`; inspect its `docs` and `files` contents, targets, and prerequisites before installing. The live catalog is the source of available recipes, so newly published snippets need no skill update.
+2. If a recipe fits, install it from the project root containing `relay.json` and `package.json`. For example, when the catalog lists `photo-quest`:
+
+   ```sh
+   pnpm dlx shadcn@4.21.0 add https://snippets.domino.run/r/photo-quest.json
+   ```
+
+   Preserve existing customized files; adapt those in place when the recipe is already installed. Use the project's package manager equivalent when it is not pnpm.
+3. Read the installed `docs/snippets/<name>.md`. Adapt the source to the requested behavior, choose unique IDs for new quests, and configure settings, rewards, and verification prerequisites. Keep existing quest IDs stable and verification source out of the browser bundle.
+4. Confirm the source matches `discover` in `relay.json`. Move it to a matching directory for custom layouts, or add an explicit entry if discovery is disabled or unsupported by the installed CLI. Run the project's checks and `domino build --json`, then exercise the requested participant behavior using the verification workflow in the Domino skill. Installation only copies source; publication is a separate step below.
+
+If no recipe fits or the catalog is unavailable, author with the installed SDK declarations and existing project examples. Report an unavailable catalog as unchecked, rather than claiming no matching snippet exists. Snippets are editable starting points; check compatibility with the project's installed SDK before changing package versions.
+
+## Publish the authored resources
+
 Source owns reusable quest definitions, collection slots, and deployment defaults. Console owns operator-created quest instances, their placement, and custom setting values. Keep identifiers stable. Registering a new reusable type version does not upgrade existing instances.
 
-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 a custom value in Console. Changing source defaults does not clear overrides.
+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.
 
 For human live review, export `domino deploy --dry-run --out deployment.json` and present that bundle for Console approval. This publishes community behavior, not the participant application. Existing attempts retain their pinned releases and promised rewards.
 
 Fixture providers simulate verification. `workers-ai` requires a configured service binding. A fixture success demonstrates the flow but does not establish that a real external activity was verified.
+
+## Leaderboard definitions
+
+Default-export `defineLeaderboard({ id, title, balance, score, access, group })` from `@domino-sdk/relay/authoring`. Add `{ "entry": "src/leaderboard.ts" }` to `leaderboards` in `relay.json`; optional `exportName` selects a named export. Deploy through the existing project bundle workflow. Definitions and standings previews appear in Console Releases before live publication.
+
+```ts
+import { defineLeaderboard } from "@domino-sdk/relay/authoring";
+
+export default defineLeaderboard({
+  id: "weekly",
+  title: "Weekly contributors",
+  balance: "community",
+  access: "participants",
+  score: {
+    kind: "earned",
+    window: { kind: "calendar", period: "week", timeZone: "Europe/Budapest" },
+  },
+});
+```
+
+Score defaults to `{ kind: "balance" }`. Use `{ kind: "earned", window, quests? }` or `{ kind: "net", window }` for period calculations. Windows are `all-time`, `fixed` with epoch-millisecond `start`/`end`, `rolling` with `days`, or `calendar` with `period: "day" | "week" | "month"` and an IANA `timeZone`. Only earned scores can filter quest IDs. Access defaults to `participants`; `public` allows anonymous reads through the configured project endpoint. A named `group` narrows eligibility.
+
+Leaderboards and points remain project/environment-scoped. Custom scoring runs before points ingestion. Management keys with `points` permission can award, spend, adjust, reverse, or set totals through `management.points.update`. Every command requires an action ID and reason; exact retries return the original result. `set` requires the current `expectedTotal` and explicit `earned`/`spend` classification. Reversals reference an original award and correct its original period. Do not implement negative clamping, direct database writes, browser awards, shared organization balances, or automatic top-rank prizes.
+
+## External points
+
+Run this on a trusted backend with a management key scoped to the project and environment. The member must already be a project participant. Quest awards to the board's balance count automatically; use this API for externally verified activity or corrections.
+
+```ts
+import { createManagementClient } from "@domino-sdk/relay-cli";
+
+const management = createManagementClient({
+  baseUrl: "https://relay.domino.run",
+  organization: "my-organization",
+  project: "community",
+  environment: "test",
+  getToken: async () => process.env.DOMINO_MANAGEMENT_KEY!,
+});
+
+await management.points.update({
+  kind: "award",
+  actionId: "external-activity-42",
+  member: "member_existing",
+  balance: "community",
+  amount: 100,
+  reason: "Verified external activity 42",
+});
+```
+
+Persist the action ID with the source event and reuse the same payload after an uncertain response. Amounts are safe whole-number integers. Backdating uses `effectiveAt` in epoch milliseconds; future dates fail. Deductions cannot make the balance negative or consume reserved points. Read operations such as `management.points.balance(member, balance)` and `history(member, balance)` require `read` permission.
+
+For externally owned totals, dedicate a balance to that source. Read its current total before a `set` command; on an `expectedTotal` conflict, read again and decide whether to issue a new command with a new action ID. A set replaces the whole balance, including any quest awards written there.
+
+## Verify a leaderboard
+
+Publish to test and read through the participant endpoint described in [participant API](https://console.domino.run/docs/reference/participant-api#leaderboard-reads). Award known points to existing test participants and verify the expected ordering, shared ties, signed-in `me`, and access after sign-out. Confirm that retrying one external event does not award twice. For a period board, check an entry inside and outside the window. Report the tested project, environment, board, and observed scores.
+
+Treat top-rank prizes as a separate reward workflow with an explicit tie policy and finalization time. Board exclusion changes eligibility only; Console or management calls with `publish` permission handle exclusions and named group membership.
+
+## Referral programs
+
+For `defineReferral`, invitation qualification, fixed rewards, and selective inviter bonuses, read [referrals](referrals.md). Register modules in the manifest's `referrals` array; they publish atomically with quests and leaderboards. Referral bonuses use the existing project points ledger.
+
+## Verify Discord membership
+
+Use the `discord-membership` snippet for a server membership check, with an optional role requirement. An organization administrator first connects the project's server in Console **Integrations**. Declare `integrations: ["discord"]` on the quest and call `await ctx.discord.member()` inside `evaluate`. There is no server ID setting. The result is `null` for absent membership, or `{ roles, joinedAt, pending }`. Author code decides eligibility and the quest's declared rewards.
+
+The platform supplies a read-only client bound to the project's configured server and the participant's Discord identity. Quest code cannot supply a user ID, server ID, access token, or arbitrary URL. Discord permission failures and outages fail verification; they are not evidence that the participant is ineligible. Bot access problems appear in Console Integrations. Participants signing in with Discord need no extra permission flow; members using another login link their Discord identity once.
+
+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/existing-app.md

@@ -1,5 +1,7 @@
 # Existing apps
 
+Before the first implementation, follow the Domino skill's existing-app campaign confirmation procedure. Ask for missing campaign basics, prepare the campaign and integration proposal, and obtain the owner's confirmation. Preserve the app's current design and components; brand discovery and visual approval are not prerequisites. Reuse an already confirmed brief in later sessions.
+
 Inspect the app's framework, package manager, workspace boundaries, authentication, and deployment scripts. Identify where the requested participant experience belongs. Keep its repository, UI conventions, login, and hosting.
 
 Use the Domino project selected by the user. If no remote project exists, create it in Console. `domino create` provisions a hosted repository and is not the existing-app integration path.

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

@@ -1,17 +1,29 @@
 # Hosted projects
 
+Before the first implementation, follow the Domino skill's intake, discovery, and confirmation procedure. Ask for missing brand and campaign basics and wait for answers before research or design. Then prepare a concrete proposal and obtain the owner's confirmation. Reuse an already confirmed brief in later sessions.
+
 If Console already created the project and repository, run `domino checkout <project>`. Use `domino create <name>` only when the requested hosted project does not exist. Both require authentication. Use `domino whoami --json` to inspect accessible projects when the target is unclear.
 
 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 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.
 
 Run `domino dev` to start the app with hosted test data and real sign-in. Share its HTTPS preview URL. The CLI prepares the tunnel connector automatically. The URL goes offline when development stops; use `domino stage` for a preview that stays online. Use `domino dev --offline --review-mode fixture-pass` only when you explicitly need an isolated runtime with simulated photo verification. This is not evidence that an external action happened.
 
 Use `domino check` and the app's build script to verify source. Exercise the requested participant flow in the running app before staging.
 
+For leaderboards, register authored modules in the manifest's `leaderboards` list. `domino check` bundles them even when the project has no quests. `domino dev` synchronizes their definitions with the other project resources. Verify signed-in rank reads through the participant proxy; a successful build alone does not establish access or scoring behavior.
+
 When the task includes sharing a preview, commit the intended changes and push using the repository's configured remote. Run `domino stage --json` after the push. The command builds the exact pushed commit and returns its staging URL. Git pushes alone save source; they do not activate a preview or publish live.
 
 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).
+
+Quests declare `integrations: ["discord"]`; Relay derives the participant identities required by each quest. The campaign starter renders account controls from the quest view’s `connections` field. The Discord membership snippet needs a project Discord integration configured in Console. Sign in with Discord (or link its identity) and check membership before staging; offline photo fixtures do not simulate Discord. See [connected accounts](participant-api.md#connected-accounts).