@domino-sdk/relay-cli 0.2.0 → 0.4.0

package/cli/capabilities.json

@@ -12,7 +12,36 @@
         "auth.emailVerify",
         "auth.session"
       ],
-      "evidence": ["tests/auth.test.mjs", "tests/email-auth.test.mjs"]
+      "evidence": [
+        "tests/auth.test.mjs",
+        "tests/email-auth.test.mjs"
+      ]
+    },
+    {
+      "id": "connected-accounts",
+      "support": "native",
+      "description": "Operators connect a Discord server and install the managed bot in Console Integrations. Participants sign in with Discord or link its identity. Declare integrations: [discord] and use ctx.discord.member() without a server ID. Captured membership and role reads survive recovery. No messages, writes, or X verification.",
+      "entrypoints": [
+        "auth.accounts",
+        "auth.start",
+        "auth.disconnect"
+      ],
+      "reference": "authoring",
+      "evidence": [
+        "tests/connected-accounts.test.mjs",
+        "apps/api/src/provider-registry.ts"
+      ]
+    },
+    {
+      "id": "identity-exchange",
+      "support": "native",
+      "description": "Keep an existing application login using createParticipantBackend on its server. A Console administrator creates a project/environment identity integration key. The adapter verifies the application session, exchanges its stable subject for a member-only Domino session, and routes participant requests with trusted scope. Keys expire after 90 days and support rotation and revocation.",
+      "entrypoints": [],
+      "reference": "participant-api",
+      "evidence": [
+        "tests/identity-integration.test.mjs",
+        "apps/api/src/identity-integration.ts"
+      ]
     },
     {
       "id": "quests",
@@ -38,38 +67,45 @@
     {
       "id": "milestones",
       "support": "composed",
-      "description": "Compose same-participant completion prerequisites with requires: [completed(quest)]. Arbitrary aggregate thresholds and cross-participant conditions need application logic.",
+      "description": "Compose same-participant completion prerequisites with requires: [completed(quest)]. Referral programs support milestones based on distinct qualified friends. Other aggregate thresholds need application logic.",
       "entrypoints": ["completed", "automatic", "defineQuest"],
       "evidence": ["tests/availability.test.mjs"]
     },
     {
       "id": "referrals",
-      "support": "own-backend",
-      "description": "No native referral attribution service. Your backend must issue invite codes, attribute the authenticated invitee, deduplicate claims and prevent self-referrals. A URL parameter alone is not verified attribution.",
-      "entrypoints": [],
+      "support": "native",
+      "description": "Project-scoped invitation codes, immutable inviter attribution, configurable signup, quest or external qualification, fixed rewards and distinct-friend milestones. Selective one-level inviter bonuses add points without reducing invitee awards. Code-defined rules publish through reviewed project deployments.",
+      "entrypoints": [
+        "defineReferral",
+        "referrals.list",
+        "referrals.summary",
+        "referrals.accept",
+        "referrals.history"
+      ],
       "reference": "referrals",
-      "evidence": [
-        "packages/sdk/src/authoring.ts",
-        "packages/sdk/src/schema.ts"
-      ]
+      "evidence": ["tests/referrals.test.mjs", "packages/sdk/src/referrals.ts"]
     },
     {
       "id": "cross-participant-rewards",
-      "support": "unsupported",
-      "description": "Quest rewards target the completing participant. There is no supported inviter-targeted reward operation. Do not promise automatic inviter points; an application-owned reward ledger requires its own implementation.",
-      "entrypoints": [],
+      "support": "native",
+      "description": "Referral programs can reward inviter and invitee independently and award a selective percentage of eligible points to the inviter. Bonuses accumulate fractions and support limits, suspension and correction recovery. Arbitrary participant-to-participant transfers and multi-level commissions are not supported.",
+      "entrypoints": ["defineReferral", "referrals.summary"],
       "reference": "referrals",
-      "evidence": [
-        "packages/sdk/src/authoring.ts",
-        "packages/sdk/src/schema.ts"
-      ]
+      "evidence": ["tests/referrals.test.mjs", "apps/api/src/referrals.ts"]
     },
     {
       "id": "rankings",
-      "support": "own-backend",
-      "description": "No participant leaderboard or referral queue ranking API. Build an authorized backend projection with explicit privacy and tie-breaking rules; never expose management credentials in a browser.",
-      "entrypoints": [],
-      "evidence": ["packages/sdk/src/index.ts"]
+      "support": "native",
+      "description": "Publish project-scoped points leaderboards through project deployments. Read paginated standings, your rank, and nearby competitors with shared tie ranks. Code defines balance, earned, or net calculations and time windows. Public access is explicit; participant rows use board-specific aliases. Scoped management APIs supply external points, corrections, groups, and exclusions. Referral bonus points contribute to their named balance. Cross-project balances, finalized results, and rank-based prizes are separate work.",
+      "entrypoints": [
+        "defineLeaderboard",
+        "leaderboards.list",
+        "leaderboards.standings"
+      ],
+      "evidence": [
+        "tests/leaderboards.test.mjs",
+        "packages/sdk/src/leaderboards.ts"
+      ]
     },
     {
       "id": "wallet-verification",

package/cli/commands/discovery.mjs

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { action } from "../runtime.mjs";
 
-const references = ["participant-api", "referrals", "troubleshooting"];
+const references = ["authoring", "participant-api", "referrals", "troubleshooting"];
 export function registerDiscoveryCommands(program) {
   program
     .command("capabilities")

package/cli/commands/hosting.mjs

@@ -7,7 +7,7 @@ import { action } from "../runtime.mjs";
 import { request } from "../connection.mjs";
 import { checkout, requireNewDirectory } from "../git.mjs";
 import { dev } from "../dev.mjs";
-import { bundleCatalog, bundleProject } from "../project.mjs";
+import { bundleProject } from "../project.mjs";
 
 export function registerHostingCommands(program) {
   program
@@ -29,15 +29,14 @@ export function registerHostingCommands(program) {
             throw new Error(error.stdout || error.stderr || error.message);
           }
         }
-        const quests = project.config.quests.length
-          ? await bundleProject(project)
-          : { releases: [] };
-        const catalog = await bundleCatalog(project);
+        const bundle = await bundleProject(project, { allowEmpty: true });
         return {
           checked: true,
-          quests: quests.releases.length,
-          types: catalog.types.length,
-          collections: catalog.collections.length,
+          quests: bundle.releases.length,
+          leaderboards: bundle.leaderboards.length,
+          referrals: bundle.referrals.length,
+          types: bundle.types.length,
+          collections: bundle.collections.length,
         };
       }),
     );

package/cli/commands/project.mjs

@@ -26,6 +26,8 @@ function summary(value) {
     })),
     collections: value.collections,
     supportedInteractions: value.supportedInteractions,
+    leaderboards: value.leaderboards,
+    referrals: value.referrals,
   };
 }
 async function publish(connection, id) {
@@ -80,6 +82,8 @@ async function build({ project, connection, options }, deploy) {
       quests: payload.releases.length,
       types: payload.types.length,
       collections: payload.collections.length,
+      leaderboards: payload.leaderboards.length,
+      referrals: payload.referrals.length,
     };
   }
   return payload;

package/cli/discovery.mjs

@@ -0,0 +1,62 @@
+import { glob } from "node:fs/promises";
+import { dirname, relative, resolve } from "node:path";
+
+export const defaultDiscovery = {
+  quests: ["quests/**/*.quest.ts"],
+  questTypes: ["quests/**/*.quest-type.ts"],
+};
+
+// These directories contain dependencies, build output, or local runtime data.
+const excluded =
+  /(^|[/\\])(node_modules|dist|\.git|\.domino|\.domino-build|\.wrangler|\.artifacts)([/\\]|$)/;
+
+export async function discoverEntries(project, kind) {
+  const root = dirname(project.path);
+  const discovery = project.config.discover;
+  const entries = new Map();
+  const key = (entry) =>
+    JSON.stringify([resolve(root, entry.entry), entry.exportName ?? "default"]);
+
+  for (const entry of project.config[kind]) {
+    const identity = key(entry);
+    if (entries.has(identity))
+      throw new Error(`Duplicate ${kind} entry: ${entry.entry}`);
+    entries.set(identity, entry);
+  }
+
+  if (discovery) {
+    const paths = [];
+    for await (const file of glob(discovery[kind], {
+      cwd: root,
+      withFileTypes: true,
+      exclude: (file) =>
+        excluded.test(relative(root, resolve(file.parentPath, file.name))),
+    })) {
+      if (file.isFile()) paths.push(resolve(file.parentPath, file.name));
+    }
+    for (const path of paths.sort()) {
+      const entry = {
+        entry: path,
+        exportName: "default",
+        provider: discovery.provider,
+        ...(kind === "quests" ? { settings: {} } : {}),
+      };
+      // Explicit entries customize a discovered default export without adding it twice.
+      const explicit = entries.get(key(entry));
+      entries.set(
+        key(entry),
+        explicit
+          ? {
+              ...explicit,
+              exportName: "default",
+              provider: explicit.provider ?? discovery.provider,
+            }
+          : entry,
+      );
+    }
+  }
+  return [...entries.values()].map((entry) => ({
+    ...entry,
+    provider: entry.provider ?? "workers-ai",
+  }));
+}

package/cli/doctor.mjs

@@ -4,6 +4,7 @@ import { createHash } from "node:crypto";
 import { access, readFile } from "node:fs/promises";
 import { inspectAgentSkills } from "./agents.mjs";
 import { request } from "./connection.mjs";
+import { discoverEntries } from "./discovery.mjs";
 
 export async function diagnose({ project, connection, options }) {
   const checks = [];
@@ -87,7 +88,12 @@ export async function diagnose({ project, connection, options }) {
   );
 
   if (project) {
-    const entries = [...project.config.quests, ...project.config.questTypes];
+    const entries = [
+      ...(await discoverEntries(project, "quests")),
+      ...(await discoverEntries(project, "questTypes")),
+      ...project.config.leaderboards,
+      ...project.config.referrals,
+    ];
     const directories = new Set(
       entries.map((entry) => dirname(resolve(root, entry.entry))),
     );
@@ -182,12 +188,13 @@ export async function diagnose({ project, connection, options }) {
         id: "remote-access",
         status: "ok",
         message:
-          "Management API verified project access. This does not verify participant sign-in or publication permission.",
+          "Management API verified project access. This does not verify participant sign-in or publication permission. Management credentials cannot issue participant sessions. Existing-login integration requires a dedicated server key and createParticipantBackend; run domino capabilities identity-exchange.",
       });
       const preflight = await request(connection, "/preflight");
       readiness = {
         development: preflight.development,
         staging: preflight.staging,
+        identity: preflight.identity ?? { exchange: "unknown" },
       };
       if (project.config.app)
         checks.push({

package/cli/project.mjs

@@ -3,6 +3,20 @@ 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,6 +25,22 @@ export const projectSchema = z
     organization: z.string().min(1),
     project: z.string().min(1),
     environment: z.enum(["test", "live"]).default("test"),
+    discover: z
+      .object({
+        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: z
       .object({
         kind: z.literal("static"),
@@ -35,11 +65,33 @@ 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(
         z
@@ -70,7 +122,7 @@ export const projectSchema = z
                 "fixture-error",
                 "workers-ai",
               ])
-              .default("workers-ai"),
+              .optional(),
           })
           .strict(),
       )
@@ -124,9 +176,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 +215,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 +298,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/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` to verify access and inspect the effective organization, project, API, and environment before remote operations. Flags and RELAY_* environment variables override relay.json.
 
 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.
 
-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.