@domino-sdk/relay-cli 0.4.0 → 0.6.0

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/output.mjs

@@ -0,0 +1,76 @@
+// Keep presentation separate from the result contracts consumed with --json.
+const label = (key) => {
+  const words = key.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_-]/g, " ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+};
+const scalar = (value) =>
+  value == null
+    ? "—"
+    : typeof value === "boolean"
+      ? value
+        ? "yes"
+        : "no"
+      : String(value);
+
+export function formatDetails(value, indent = "") {
+  if (value === null || typeof value !== "object")
+    return indent + scalar(value);
+  if (Array.isArray(value)) {
+    if (!value.length) return indent + "None";
+    return value
+      .map((item) => {
+        if (item === null || typeof item !== "object")
+          return `${indent}- ${scalar(item)}`;
+        return formatDetails(item, indent + "  ").replace(
+          indent + "  ",
+          indent + "- ",
+        );
+      })
+      .join("\n");
+  }
+  const entries = Object.entries(value).filter(
+    ([, item]) => item !== undefined,
+  );
+  if (!entries.length) return indent + "None";
+  return entries
+    .map(([key, item]) =>
+      item !== null && typeof item === "object"
+        ? `${indent}${label(key)}:\n${formatDetails(item, indent + "  ")}`
+        : `${indent}${label(key)}: ${scalar(item)}`,
+    )
+    .join("\n");
+}
+
+export function formatResult(command, result, options = {}) {
+  if (options.json || command === "api")
+    return JSON.stringify(result, null, options.json ? undefined : 2);
+  if (command === "logs") return result.logs.trimEnd();
+  if (command === "reference" && result.markdown)
+    return result.markdown.trimEnd();
+  if (command === "whoami") {
+    const identity = formatDetails({
+      actor: result.actor,
+      organization: result.organization,
+    });
+    const projects = result.projects.map(
+      (item) =>
+        `  ${item.name && item.name !== item.project ? `${item.name} (${item.project})` : item.project}  [${item.environments.join(", ")}]`,
+    );
+    return `${identity}\n\nAccessible projects:\n${projects.length ? projects.join("\n") : "  None"}\n\nRun domino checkout to choose a hosted project, or domino init to link this app.`;
+  }
+  if (
+    (command === "build" || (command === "deploy" && options.dryRun)) &&
+    result.releases
+  ) {
+    return formatDetails({
+      result: "Bundle ready",
+      quests: result.releases.length,
+      types: result.types.length,
+      collections: result.collections.length,
+      leaderboards: result.leaderboards.length,
+      referrals: result.referrals.length,
+      next: "Use --out FILE to save the bundle, or --json to print it.",
+    });
+  }
+  return formatDetails(result);
+}

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/prompts.mjs

@@ -0,0 +1,92 @@
+import { createInterface } from "node:readline/promises";
+
+export function canPrompt(
+  options,
+  input = process.stdin,
+  output = process.stderr,
+) {
+  return (
+    !options.json &&
+    options.interactive !== false &&
+    !process.env.CI &&
+    Boolean(input.isTTY && output.isTTY)
+  );
+}
+
+export async function promptText(
+  message,
+  {
+    defaultValue,
+    validate = (value) => (value ? undefined : "Enter a value."),
+  } = {},
+  { input = process.stdin, output = process.stderr } = {},
+) {
+  const prompt = createInterface({ input, output });
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  prompt.on("SIGINT", cancel);
+  prompt.on("close", cancel);
+  try {
+    for (;;) {
+      const answer = (
+        await prompt.question(
+          `${message}${defaultValue === undefined ? "" : ` [${defaultValue}]`} (q to cancel): `,
+          { signal: controller.signal },
+        )
+      ).trim();
+      if (answer.toLowerCase() === "q") throw new Error("Selection cancelled.");
+      const value = answer || defaultValue || "";
+      const error = await validate(value);
+      if (!error) return value;
+      output.write(`${error}\n`);
+    }
+  } catch (error) {
+    if (controller.signal.aborted) throw new Error("Selection cancelled.");
+    throw error;
+  } finally {
+    prompt.close();
+  }
+}
+
+export async function promptSelect(
+  title,
+  choices,
+  { input = process.stdin, output = process.stderr } = {},
+) {
+  if (!choices.length)
+    throw new Error(`No choices available for ${title.toLowerCase()}.`);
+  output.write(`${title}:\n`);
+  choices.forEach((choice, index) =>
+    output.write(`  ${index + 1}. ${choice.label}\n`),
+  );
+  const answer = await promptText(
+    "Selection number",
+    {
+      validate: (value) =>
+        /^\d+$/.test(value) &&
+        Number(value) >= 1 &&
+        Number(value) <= choices.length
+          ? undefined
+          : `Enter a number from 1 to ${choices.length}.`,
+    },
+    { input, output },
+  );
+  return choices[Number(answer) - 1].value;
+}
+
+export async function confirmAction(options, details, io = {}) {
+  if (options.yes || !canPrompt(options, io.input, io.output)) return;
+  const output = io.output ?? process.stderr;
+  output.write(`${details}\n`);
+  const answer = await promptText(
+    "Continue?",
+    {
+      defaultValue: "no",
+      validate: (value) =>
+        /^(y|yes|n|no)$/i.test(value) ? undefined : "Enter yes or no.",
+    },
+    io,
+  );
+  if (!/^y(es)?$/i.test(answer))
+    throw new Error("Operation cancelled. Nothing was published.");
+}

package/cli/runtime.mjs

@@ -1,18 +1,27 @@
 import { findProject } from "./project.mjs";
+import { formatResult } from "./output.mjs";
+import { projectConnection } from "./select-project.mjs";
 import { apiUrl } from "./connection.mjs";
 
 // Share scope resolution and output across commands; build and HTTP modules stay independent.
-export function action(handler) {
+export function action(handler, { projectScope = false, environment } = {}) {
   return async (...args) => {
     const command = args.at(-1);
     const options = command.optsWithGlobals();
     const project = await findProject(options.config);
-    const connection = {};
+    let 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 (
@@ -20,19 +29,19 @@ export function action(handler) {
       !["test", "live"].includes(connection.environment)
     )
       throw new Error("Environment must be test or live.");
+    if (environment) connection.environment = environment;
+    if (projectScope) connection = await projectConnection(connection, options);
     const result = await handler(
-      { options, project, connection },
+      { options, project, connection, scopeSources },
       ...command.processedArgs,
     );
-    console.log(JSON.stringify(result, null, options.json ? undefined : 2));
+    console.log(formatResult(command.name(), result, options));
   };
 }
 
 export async function readStdin() {
   if (process.stdin.isTTY)
-    throw new Error(
-      "Pipe input to stdin; interactive prompts are not supported.",
-    );
+    throw new Error("Pipe input to stdin for this option.");
   let input = "";
   for await (const chunk of process.stdin) input += chunk;
   return input;

package/cli/select-project.mjs

@@ -0,0 +1,64 @@
+import { canPrompt, promptSelect } from "./prompts.mjs";
+import { request } from "./connection.mjs";
+
+export function promptProject(projects, io) {
+  return promptSelect(
+    "Choose a project",
+    projects.map((item) => ({
+      label: `${item.name && item.name !== item.project ? `${item.name} (${item.project})` : item.project}  [${item.environments.join(", ")}]${item.organization ? ` • ${item.organization}` : ""}`,
+      value: item,
+    })),
+    io,
+  );
+}
+
+export async function projectConnection(connection, options) {
+  if (connection.project) return connection;
+  const access = await request(connection, "/access");
+  const selected = await selectProject(access, connection, options);
+  return {
+    ...connection,
+    project: selected.project,
+    organization: selected.organization ?? access.organization,
+  };
+}
+
+export async function selectProject(
+  access,
+  connection,
+  options,
+  { interactive = canPrompt(options), choose = promptProject } = {},
+) {
+  const environment = connection.environment ?? "test";
+  const projects = access.projects.filter(
+    (item) =>
+      item.environments.includes(environment) &&
+      (!connection.organization ||
+        !item.organization ||
+        item.organization === connection.organization),
+  );
+  if (connection.project) {
+    const matches = projects.filter(
+      (item) => item.project === connection.project,
+    );
+    if (matches.length > 1)
+      throw new Error(
+        "This project identifier exists in multiple organizations. Select one with --organization ID.",
+      );
+    const selected = matches[0];
+    if (!selected)
+      throw new Error(
+        `No access to project ${connection.project} in ${environment}. Run domino whoami to list accessible projects.`,
+      );
+    return selected;
+  }
+  if (!projects.length)
+    throw new Error(
+      `No accessible projects in ${environment}. Create a project in Console or select another organization with --organization ID.`,
+    );
+  if (interactive) return choose(projects);
+  if (projects.length === 1) return projects[0];
+  throw new Error(
+    "Select an accessible project with --project ID. Run domino whoami to list projects, or run this command in a terminal to choose interactively.",
+  );
+}

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

@@ -25,13 +25,25 @@ curl -fsS https://snippets.domino.run/r/registry.json
 
 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.
 
+## Resource and date/time settings
+
+Use `settings.resource({ label, source: discord.channels() })` for a Discord channel selector. Import `discord` alongside `settings` from `@domino-sdk/relay/authoring`. The connected project integration supplies the server; never add a guild ID setting. Filter with `discord.channels({ types: ["announcement"] })` when only announcement channels qualify. The default includes text and announcement channels. Resource values are stable IDs, not labels.
+
+Omit the resource default until the operator chooses a value in Console. Its empty string represents missing configuration. Code-authored quests publish paused when any resource setting is empty. Publishing a configured value activates the code-authored quest; clearing it pauses the quest again. Console-created quests must have every required resource configured before activating. Existing operation-level pauses remain independent.
+
+Use `settings.datetime({ label, default: "2026-09-21T00:00:00+02:00" })` for an exact cutoff instant. Values normalize to UTC ISO timestamps. Console displays date and time with the operator's local timezone explicitly labeled. Offset-free timestamps and invalid calendar dates are rejected. This is not a date-only setting.
+
+Resource selections are checked on the backend for Console and CLI publication, including final deployment publication after preview. The selected resource must belong to the current connected integration and be usable by its bot. Lookup caches do not replace publication validation. A temporary provider outage rejects the new publication without changing the existing release. Deleted selections remain visible for the operator to replace.
+
+Replacing a text field with a resource or datetime field preserves Console overrides when their values pass the new validation. Keep the field key stable. Invalid overrides must be updated or reset explicitly; they are not silently discarded.
+
 ## 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 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.
 
@@ -103,10 +115,55 @@ For `defineReferral`, invitation qualification, fixed rewards, and selective inv
 
 ## 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.
+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 `{ userId, roles, joinedAt, pending, nickname, displayName, boostingSince }`. 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 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. The injected Discord client supports `member()` and `message({ channelId, messageId })`. Automatic reaction additions arrive separately through observations; see the observation-triggered quest guidance below. Discord role grants are declared rewards, never evaluator writes. 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.
+
+## Observation-triggered and repeatable quests
+
+Use `automatic({ source, type })` for authenticated external activity. `automatic()` without arguments retains prerequisite-based triggering. Manual and automatic triggers are exclusive. Automatic quests never expose participant claim or retry actions. Set `visibility: "hidden"` to omit a quest from participant lists while it continues earning rewards.
+
+Choose `once()` for one successful completion per participant, or `keyed(ctx => key)` for one per author-defined key. The key is scoped to the project, quest, and participant. It must remain stable across deployments. For announcement reactions use the message ID; for a daily manual quest derive the UTC date from `ctx.eligibleAt`. `completed(quest)` still means ever completed.
+
+An observation has `id`, `source`, `type`, `member`, `occurredAt`, `receivedAt`, and JSON `data`. The evaluator reads `ctx.observation`, which is null for manual and prerequisite-triggered work. `ctx.eligibleAt` is fixed when admitted. The source delivery ID deduplicates transport; it is not the completion key. Only an accepted completion consumes a key. Replaying rejected evidence does not reconsider it, but a new observation can try an unconsumed key.
+
+Declare budgets with `budget({ id, scope: "member" | "project", period: "day" | "lifetime", limit, cost })`. Use `cost: 1` for completion counts or `cost: { balance: "community" }` for the awarded points amount. Quests can share a named budget, with matching scope, period, and limit. All budget spends, the completion key, and rewards commit together. UTC-day budgets use the admitted eligibility day. An exhausted observation is rejected permanently; it does not roll into tomorrow. Concurrent valid awards commit in whichever order wins the transaction.
+
+Admission pins the release and prerequisite result. Pausing stops new admissions while accepted work finishes. Republication does not clear successful completion keys. Observation execution errors retry with capped backoff and retain the original evidence and release. Points accumulate per completion. Tier rewards retain their existing entitlement upgrade behavior; repeating a quest does not create a new consumable handover.
+
+Install `discord-announcements` for the first integration example. The source is `discord`, type `reaction.add`; parse its data with `discordReactionSchema`. Filter the configured channel, emoji, and `messagePublishedAt` in quest code. The Gateway captures the reaction addition; do not query current reactions to cancel it. Unseen replayed events with unknown timing are skipped and reported as coverage gaps. Manual Discord membership remains `ctx.discord.member()`. Use `discordRole(roleId)` for a declared role reward; no arbitrary Discord writes or X verification are exposed.
+
+A trusted customer backend uses a management key with `observe` permission and calls `management.observations.submit({ id, source: "backend:orders", type: "paid", member, occurredAt, data })`. Use the stable delivery ID on retries. The backend supplies a trusted project member ID and action time, never browser claims. Backend sources must start with `backend:` and cannot impersonate `discord`. This endpoint can grant real rewards through matching quests; keep its credential on the server.
+
+## Discord contribution and recognition snippets
+
+Install `discord-contribution` for channel participation and `discord-moderator-recognition` for moderator heart reactions. Use one snippet per capability; customize predicates in code.
+
+- `message.create` targets the message author. Parse with `discordMessageSchema`. Fields are `guildId`, `channelId`, `messageId`, `userId`, nullable `content`, nullable `replyTo`, and `publishedAt`. Bots and webhooks are excluded. Content needs the platform bot's privileged Message Content intent and `DISCORD_MESSAGE_CONTENT=true`; treat null as unavailable evidence.
+- `reaction.add` targets the reactor. `reaction.received` targets the message author. Parse either payload with `discordReactionSchema`, which adds nullable `messageAuthorId` and `actorRoles`. Authorization roles come from capture time.
+- `observation.member` is the beneficiary; optional `observation.actor` is `{ provider, subject }` identifying the external actor. The beneficiary owns prerequisites, completion keys, budgets and rewards. A moderator need not link a Relay account. Reject self-tips and key by message ID to prevent repeated recognition rewards.
+- `ctx.discord.message({ channelId, messageId })` is server-scoped and returns null for deleted messages. For manual authorship checks, compare message `userId` to a non-null `userId` from `ctx.discord.member()`. Older captured member facts can return null; fail closed. For automatic events, use the trusted observation identity. Captured reads survive evaluation retries.
+
+Daily budgets are caps, not counters or streaks. Multi-action progress remains a separate design proposal.
+
+## Discord role rewards
+
+Import `discordRole` from `@domino-sdk/relay/authoring`. Declare `rewards: [discordRole(roleId)]`. Install `discord-role-reward` for a complete prerequisite-gated example. Its resource setting uses `discord.roles({ assignable: true })`; ordinary eligibility roles use `discord.roles()`.
+
+The ledger commits one durable delivery per completion and role. Delivery retries separately from quest evaluation using an idempotent role assignment. Never write to Discord inside evaluate. Pending delivery is bound to the original account/server, so reconnecting a different identity cannot redirect it. Restoring the original connection and permissions permits recovery. The bot needs Manage Roles and a role above the target. Managed/everyone roles cannot be reward roles.
+
+Use `relay.me.rewardDeliveries()` for the current member or `management.rewardDeliveries(member?)` for operator inspection. Lists contain the latest 500 deliveries in the selected scope. Each record contains quest, completion, role, status, attempts and retry details. Participant UI should show pending/granted status without operator error details. Referral reward definitions still accept points and tier rewards; qualify a role-granting quest if composing them.
+
+## 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.