@tokenoftrust/cli 1.4.1 → 2.0.0

package/src/plan.mjs

@@ -1,11 +1,11 @@
 /**
- * The shared "operation plan" affordance (unit U10) — the load-bearing
- * cross-cutting requirement from decision `operator-verb-and-hosting-model`:
- * every MUTATING operator verb (build / accept / ship / retire) must STATE
+ * The shared "operation plan" affordance — the load-bearing
+ * cross-cutting requirement that
+ * every MUTATING operator verb (build / accept / ship / cleanup) must STATE
  * EXACTLY what it will do — which PR is queued/integrated/deployed, which
  * deploy targets (preview / live) are touched, and their URLs — and get an
  * explicit confirm before acting. (`accept` now queue-integrates a PR into the
- * `preview` aggregate — unit b08 — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
+ * `preview` aggregate — rather than merging it to main.) No silent multi-step mutations, in either surface (the CLI
  * here, and `AdminPublishTab.astro`'s confirm dialog, which renders the same
  * shape of plan text server-side/inline).
  *
@@ -15,8 +15,8 @@
  * half — print the plan, then gate on an explicit yes (reusing `prompt.mjs`'s
  * TTY-safe `promptYesNo`; a non-TTY without `--yes` never silently proceeds).
  *
- * SHIP has ONE meaning (unit b10 — supersedes the retired context-dependent
- * ship, decision `ship-context-dependent-semantics`): it publishes the
+ * SHIP has ONE meaning (supersedes the retired context-dependent ship
+ * semantics): it publishes the
  * tenant's CURRENT GREEN AGGREGATE — the batch of PRs that integrated
  * cleanly — to live. No merge, no PR/candidate targeting, no developer-vs-
  * operator branching. The plan states the pinned aggregate sha, its
@@ -46,7 +46,7 @@ function targetLabel({ pr, changeId }) {
  * console output, no network, no prompting.
  *
  * @param {{
- *   action: "build"|"accept"|"ship"|"retire"|"revert"|"cleanup"|"hotfix",
+ *   action: "build"|"accept"|"ship"|"revert"|"cleanup"|"hotfix",
  *   tenant: string,
  *   pr?: number|string|null,
  *   changeId?: string|null,
@@ -57,11 +57,11 @@ function targetLabel({ pr, changeId }) {
  *   context?: "developer"|"operator",
  *   pinnedSha?: string|null,
  *   artifactDigest?: string|null,
- *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   includedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
  *   rollbackTarget?: { receiptId: string, aggregateSha: string } | null,
  *   paywall?: { allowed: boolean, message?: string|null } | null,
- *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>,
- *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>,
+ *   refs?: Array<{ ref: string, sha?: string|null, reason?: string|null }>|null,
+ *   bypassedPrs?: Array<{ prNumber?: number|null, changeId?: string|null, headSha?: string|null }>|null,
  *   bypassedPreviewSha?: string|null,
  * }} params
  * @returns {string[]} plan lines (no leading/trailing blank line)
@@ -105,7 +105,7 @@ export function planForAction({
       break;
     }
     case "accept": {
-      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW (unit b08), NOT merge-to-main:
+      // Accept now means QUEUE-INTEGRATE-INTO-PREVIEW, NOT merge-to-main:
       // the candidate lands in the protected `preview` aggregate (serialized merge →
       // rebuild → combined-evidence gate), and the aggregate goes live only later via
       // `tot ship`. So the plan states the integration, never a merge or a go-live.
@@ -116,8 +116,8 @@ export function planForAction({
       break;
     }
     case "ship": {
-      // ONE meaning (b10): publish the tenant's CURRENT GREEN AGGREGATE to live.
-      // No merge — b09's orchestrator ships the already-materialized, already-
+      // ONE meaning: publish the tenant's CURRENT GREEN AGGREGATE to live.
+      // No merge — the orchestrator ships the already-materialized, already-
       // reviewed digest. State exactly WHAT that is: the pinned sha, the
       // content-addressed artifact digest, every included PR, the rollback
       // target, and the go-live paywall verdict — so the human reviews the
@@ -145,12 +145,8 @@ export function planForAction({
       }
       break;
     }
-    case "retire": {
-      lines.push(`  effect:    evict ${label}'s preview environment + version (rebuildable).`);
-      break;
-    }
     case "cleanup": {
-      // Branch GC (P1 items 9/10): delete ONLY the exact terminal refs a fresh
+      // Branch GC: delete ONLY the exact terminal refs a fresh
       // server-side classification (candidate_list) marked eligible — never by
       // age alone, never main/preview, never an orphan. State the exact set so
       // the human confirms precisely what will be removed, not "some branches".
@@ -166,7 +162,7 @@ export function planForAction({
       break;
     }
     case "revert": {
-      // Revert (b21): REMOVE already-integrated content from the protected `preview`
+      // Revert: REMOVE already-integrated content from the protected `preview`
       // aggregate by creating a NEW auditable revert commit — never a force-reset,
       // never a branch delete. The aggregate rebuilds and ships only when green
       // again. State exactly that: preview-only, a new commit, NO touch to main.
@@ -178,7 +174,7 @@ export function planForAction({
       break;
     }
     case "hotfix": {
-      // Hotfix (b22): the EXPLICIT EXCEPTION lane. Release the reviewed fix from
+      // Hotfix: the EXPLICIT EXCEPTION lane. Release the reviewed fix from
       // `main` to live, EXCLUDING the unshipped `preview` work — then automatically
       // forward-integrate `main` into `preview` and re-validate. State exactly that,
       // and — critically — list the unshipped preview work this deliberately BYPASSES,
@@ -223,7 +219,6 @@ function titleFor(action) {
   if (action === "build") return "Build-on-demand";
   if (action === "accept") return "Accept";
   if (action === "ship") return "Ship";
-  if (action === "retire") return "Retire";
   if (action === "revert") return "Revert";
   if (action === "cleanup") return "Cleanup";
   if (action === "hotfix") return "Hotfix (owner-only exception lane)";

package/src/sample.mjs

@@ -21,7 +21,7 @@
  *
  * (Earlier this borrowed a real vape merchant's identity + content to get a
  * populated catalog; that leaked private merchant IP into public npm and was
- * replaced — see the H1/H2 runner-sanitization work — with this generic sample.)
+ * replaced — see the runner-sanitization work — with this generic sample.)
  *
  * Dependency-free (node:fs + node:path only).
  */
@@ -94,7 +94,7 @@ export function pickNvmrcVersion(env = process.env) {
     const best = readdirSync(root)
       .map((name) => /^v(\d+)\.(\d+)\.(\d+)$/.exec(name))
       .filter((m) => m && nodeMeetsFloor(m.slice(1).join(".")))
-      .map((m) => m.slice(1).map(Number))
+      .map((m) => /** @type {RegExpExecArray} */ (m).slice(1).map(Number))
       .sort((a, b) => b[0] - a[0] || b[1] - a[1] || b[2] - a[2])[0];
     if (best) return best.join(".");
   } catch {
@@ -177,7 +177,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
     const err = new Error(
       `${dir} isn't empty and isn't a sample checkout — scaffold into an empty directory (or pass a new --workspace)`,
     );
-    err.code = "ENOTEMPTY_SAMPLE";
+    /** @type {any} */ (err).code ="ENOTEMPTY_SAMPLE";
     throw err;
   }
 
@@ -187,7 +187,7 @@ export function scaffoldSample(destDir, { force = false, log = () => {} } = {})
       "the sample store isn't available in this release yet — it's coming soon. " +
         "To build a real store now: `tot login --code <invite>` then `tot start`.",
     );
-    err.code = "SAMPLE_UNAVAILABLE";
+    /** @type {any} */ (err).code ="SAMPLE_UNAVAILABLE";
     throw err;
   }
 

package/src/validate.mjs

@@ -130,31 +130,110 @@ function validateRawHtmlBody(html) {
   if (!html.includes("<")) return "no markup tags found";
   return null;
 }
+// Compact structural mirror of @tot/public-runtime chrome.ts's `ChromeConfig`
+// shape — the consolidated header/footer schema (retired both the old lean
+// `SiteChrome` and the `sharedChrome: true`-gated `TenantChrome`). This is
+// NOT a full validateChromeConfig() pass — deep per-item errors (a nav item
+// missing its `id`, an invalid header `variant`, ...) are the write-path's
+// job (packages/private-controlplane/src/customization-chrome.ts, which does
+// call the real validateChromeConfig()); this only decides whether the
+// tenant's chrome.json looks enough like a ChromeConfig to opt the tenant
+// into shared chrome for the html-fragment check below. The published `tot`
+// CLI bundle can't reach the repo's public-runtime package at runtime (same
+// constraint as the KNOWN_EMBEDS mirror above), so this is a copy — parity
+// test: packages/public-runtime/tests/chrome-config-shape-parity.test.ts.
+const CHROME_HEADER_VARIANTS = new Set(["primary", "minimal"]);
+const CHROME_FOOTER_VARIANTS = new Set(["default"]);
+export function looksLikeChromeConfig(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) return false;
+  const header = value.header;
+  if (header == null || typeof header !== "object" || Array.isArray(header)) return false;
+  if (!CHROME_HEADER_VARIANTS.has(header.variant)) return false;
+  const brand = header.brand;
+  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string" || brand.label.trim() === "") return false;
+  if (!Array.isArray(header.nav)) return false;
+  const footer = value.footer;
+  if (footer == null || typeof footer !== "object" || Array.isArray(footer)) return false;
+  if (!CHROME_FOOTER_VARIANTS.has(footer.variant)) return false;
+  if (!Array.isArray(footer.columns)) return false;
+  return true;
+}
+
 /**
- * Does the tenant provide chrome to wrap body-only fragments? True when it ships
- * EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json` that
- * opts into the canonical shared chrome. Mirrors the serve-time resolution in
- * apps/storefront getChromeHtml() → parseChromeConfig(): an opted-in config is
- * rendered into the wrapper (renderRawChrome), so a fragment is NOT served naked.
- * Kept in step with lib/chrome/parseConfig.ts's opt-in gate.
+ * Does the tenant provide chrome to wrap body-only fragments? True when it
+ * ships EITHER a hand-authored `content/chrome.html`, OR a `content/chrome.json`
+ * that looks like a consolidated `ChromeConfig` (see {@link looksLikeChromeConfig}).
+ * Mirrors the serve-time resolution in apps/storefront getChromeHtml() →
+ * parseChromeConfig(): a config that parses is rendered into the wrapper
+ * (renderRawChrome), so a fragment is NOT served naked.
  */
 function providesChrome(contentDir) {
   if (existsSync(join(contentDir, "chrome.html"))) return true;
   const configPath = join(contentDir, "chrome.json");
   if (!existsSync(configPath)) return false;
   const { value } = readJsonSafe(configPath);
-  if (value == null || typeof value !== "object") return false;
-  if (value.sharedChrome !== true) return false;
-  const brand = value.brand;
-  if (brand == null || typeof brand !== "object" || typeof brand.label !== "string") return false;
-  if (!Array.isArray(value.nav)) return false;
-  const footer = value.footer;
-  if (footer == null || typeof footer !== "object" || !Array.isArray(footer.columns)) return false;
-  return true;
+  return looksLikeChromeConfig(value);
 }
 
 const CAPABILITY_KEYS = new Set(["cartCheckout", "ageVerification", "exciseTax"]);
 
+// Compact mirror of EMBED_PROVIDERS (packages/public-runtime/src/embed-catalog.mjs)
+// for the embed-CSP shift-left scan. The published `tot` CLI bundle can't reach
+// the repo's public-runtime package at runtime, so this is a copy — but a parity
+// test (packages/public-runtime/tests/embed-catalog-parity.test.ts) pins it to
+// the shared source so it can't silently drift. markers = substrings meaning the
+// embed is on the page; origins = the exact hosts it needs.
+export const KNOWN_EMBEDS = [
+  {
+    slug: "pipedrive",
+    label: "Pipedrive Web Forms",
+    markers: ["webforms.pipedrive.com", "pipedriveWebForms"],
+    origins: ["https://webforms.pipedrive.com"],
+  },
+];
+const KNOWN_EMBED_SLUGS = new Set(KNOWN_EMBEDS.map((p) => p.slug));
+const EMBED_ALWAYS_ALLOWED = new Set(["static.cloudflareinsights.com", "cloudflareinsights.com"]);
+const EMBED_SRC_RE = /<(?:script|iframe)\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi;
+
+/** Classify one HTML doc: which known providers + unknown external src origins. */
+function scanHtmlForEmbeds(html) {
+  const knownSlugs = KNOWN_EMBEDS.filter((p) => p.markers.some((m) => html.includes(m))).map((p) => p.slug);
+  const catalogOrigins = new Set(KNOWN_EMBEDS.flatMap((p) => p.origins));
+  const unknown = new Set();
+  EMBED_SRC_RE.lastIndex = 0;
+  let m;
+  while ((m = EMBED_SRC_RE.exec(html))) {
+    let origin;
+    try {
+      origin = new URL(m[1]).origin;
+    } catch {
+      continue;
+    }
+    const host = new URL(origin).hostname;
+    if (EMBED_ALWAYS_ALLOWED.has(host) || catalogOrigins.has(origin)) continue;
+    unknown.add(origin);
+  }
+  return { knownSlugs, unknownOrigins: [...unknown] };
+}
+
+function validateEmbedsDoc(doc, file) {
+  // embeds.json: the tenant's self-serve third-party embed opt-in — a JSON array
+  // of catalogued provider slugs (e.g. ["pipedrive"]). Unknown slug = WARNING
+  // (resolveEffectiveEmbeds drops it, so it's inert, not dangerous).
+  if (!Array.isArray(doc)) {
+    return [mk(ERROR, "embeds-root", file, 'embeds.json must be a JSON array of provider slugs, e.g. ["pipedrive"]')];
+  }
+  const out = [];
+  for (const slug of doc) {
+    if (typeof slug !== "string") {
+      out.push(mk(ERROR, "embeds-shape", file, `every entry must be a string slug; got ${typeof slug}`));
+    } else if (!KNOWN_EMBED_SLUGS.has(slug)) {
+      out.push(mk(WARN, "embed-unknown", file, `"${slug}" is not a known embed provider — it will be ignored (the CSP will still block that embed). Known: ${[...KNOWN_EMBED_SLUGS].join(", ")}.`));
+    }
+  }
+  return out;
+}
+
 function complianceObligations(config) {
   const compliance = config?.compliance || {};
   return {
@@ -513,6 +592,16 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  const embedsPath = join(tenantDir, "embeds.json");
+  if (existsSync(embedsPath)) {
+    const { value, error } = readJsonSafe(embedsPath);
+    if (error) {
+      findings.push(mk(ERROR, "embeds-parse", "embeds.json", `invalid JSON: ${error}`));
+    } else {
+      findings.push(...validateEmbedsDoc(value, "embeds.json"));
+    }
+  }
+
   // 3. content JSON — parse + blocks shape
   for (const name of ["home.json", "chrome.json"]) {
     const p = join(contentDir, name);
@@ -551,7 +640,7 @@ export function validateTenant(tenantDir, opts = {}) {
       findings.push(
         mk(ERROR, "html-fragment", r,
           "is an HTML fragment but the tenant ships no chrome to wrap it — it will serve unwrapped/naked",
-          "make it a full <!doctype html> document, add a content/chrome.json with \"sharedChrome\": true (brand + nav + footer), or add content/chrome.html with <!--PAGE_BODY-->"),
+          "make it a full <!doctype html> document, add a content/chrome.json with header.variant/header.brand.label/header.nav and footer.variant/footer.columns, or add content/chrome.html with <!--PAGE_BODY-->"),
       );
     }
     if (STYLE_OPEN_WITH_ATTRS_RE.test(html)) {
@@ -591,6 +680,33 @@ export function validateTenant(tenantDir, opts = {}) {
     }
   }
 
+  // Embed CSP shift-left: warn (in the dev loop) about third-party embeds that
+  // the strict CSP will silently block, instead of leaving a blank spot. A known
+  // provider not opted into embeds.json, or an unknown external <script>/<iframe>
+  // origin, is blocking; advisory (info) when there's no embeds.json to compare.
+  {
+    let declaredEmbeds = null;
+    const embedsFile = join(tenantDir, "embeds.json");
+    if (existsSync(embedsFile)) {
+      const { value } = readJsonSafe(embedsFile);
+      if (Array.isArray(value)) declaredEmbeds = new Set(value.filter((s) => typeof s === "string"));
+    }
+    for (const file of walk(contentDir, (p) => p.endsWith(".html"))) {
+      const { knownSlugs, unknownOrigins } = scanHtmlForEmbeds(readFileSync(file, "utf8"));
+      for (const slug of knownSlugs) {
+        const label = KNOWN_EMBEDS.find((p) => p.slug === slug)?.label ?? slug;
+        if (declaredEmbeds && !declaredEmbeds.has(slug)) {
+          findings.push(mk(ERROR, "embed-csp", rel(file), `embeds ${label} but "${slug}" is not in embeds.json — the CSP will block it. Add "${slug}" to embeds.json.`));
+        } else if (!declaredEmbeds) {
+          findings.push(mk("info", "embed-csp", rel(file), `embeds ${label}: ensure "${slug}" is in embeds.json, or the CSP will block it.`));
+        }
+      }
+      for (const origin of unknownOrigins) {
+        findings.push(mk(ERROR, "embed-csp", rel(file), `embeds ${origin}, which is not a known embed provider — the CSP will block it. Needs a platform catalog entry, or remove the embed.`));
+      }
+    }
+  }
+
   const ok = !findings.some((f) => f.level === ERROR);
   return { ok, findings };
 }
@@ -607,6 +723,10 @@ function buildPageTargetSet(contentDir, pagesDir) {
   return set;
 }
 
+/**
+ * @param {any} href @param {any} file @param {any} scope @param {any} pageTargets
+ * @param {(path: string) => boolean} [ownsPlatformRoute]
+ */
 function checkLink(href, file, scope, pageTargets, ownsPlatformRoute = () => false) {
   const out = [];
   if (!href || href.startsWith("#") || href.startsWith("mailto:") || href.startsWith("tel:")) return out;

package/src/vendor/private-apps-devkit.mjs

@@ -1,7 +1,7 @@
 /**
- * Vendored subset of `@tokenoftrust/private-apps-devkit` (PrivateApps epic D6
- * Chunk B, `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts`) — for
- * `tot app` (D6 Chunk C+D) to sign/verify webhook deliveries, mint dev JWTs,
+ * Vendored subset of `@tokenoftrust/private-apps-devkit` (PrivateApps epic,
+ * `packages/private-apps-devkit/src/{signing,jwt,manifest}.ts`) — for
+ * `tot app` to sign/verify webhook deliveries, mint dev JWTs,
  * and validate `tot-app.json` manifests WITHOUT a package.json dependency on
  * that package.
  *

package/src/viewer-session.mjs

@@ -0,0 +1,118 @@
+/**
+ * Viewer-session transport for the ship surface — the NO-operator-secret path.
+ *
+ * An invited developer holds a `tot login` MCP session but no operator secret and no
+ * storefront cookie, so the old ship-surface transport dead-ended on them. This mints
+ * a storefront VIEWER session from the developer's OWN MCP token (POST
+ * /api/dev/cli-session on the tenant's own host, which resolves WHO the opaque token
+ * is via the MCP and hands back a `tot_session` cookie), then hands the caller a
+ * cookie-based transport pointed at the tenant host. Authorization is still the
+ * developer's live `ship-on-behalf` grant, enforced server-side at the ship route —
+ * this only carries their identity, it grants nothing.
+ *
+ * Minted FRESH per call (no disk cache): a `tot accept` is interactive + infrequent,
+ * and minting-per-call means a revoked session/grant is never honored past its life.
+ */
+import { resolveDeveloperSession, AuthUnavailableError } from "./auth.mjs";
+
+const SESSION_COOKIE = "tot_session";
+
+/** The tenant's own storefront host — the dev-viewer admission derives the tenant
+ *  from the request host, so the session + integrate MUST target it (not the generic
+ *  storefront origin + X-Tot-Owner, which only steers the operator-secret path). */
+function tenantBase(tenant) {
+  return `https://${String(tenant || "").trim().toLowerCase()}`;
+}
+
+/** Pull `tot_session=<id>` out of a (possibly comma-folded) Set-Cookie header. The
+ *  id is base64url — no comma/semicolon — so a non-greedy stop-set is unambiguous. */
+export function parseSessionCookie(setCookie) {
+  if (!setCookie) return null;
+  const m = new RegExp(`${SESSION_COOKIE}=([^;,\\s]+)`).exec(setCookie);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve a viewer-session transport for `tenant`. Returns
+ *   { ok:true, base, authHeaders }               — base = tenant host; cookie transport
+ *   { ok:false, message, hint }                  — a clean, actionable refusal
+ * Never throws.
+ *
+ * @param {{ tenant:string, env?:NodeJS.ProcessEnv, fetchImpl?:typeof fetch,
+ *   resolveDev?:typeof resolveDeveloperSession }} params
+ * @returns {Promise<
+ *   { ok:true, base:string, authHeaders:Record<string,string> } |
+ *   { ok:false, message:string, hint:string }
+ * >}
+ */
+export async function resolveViewerTransport({
+  tenant,
+  env = process.env,
+  fetchImpl = fetch,
+  resolveDev = resolveDeveloperSession,
+}) {
+  // The developer's OWN MCP token (read + silently refreshed by the resolver). No
+  // client needed — resolveDeveloperSession tolerates a null client.
+  let dev;
+  try {
+    dev = await resolveDev(null, env, { fetchImpl });
+  } catch (e) {
+    if (e instanceof AuthUnavailableError) {
+      return { ok: false, message: e.message, hint: e.hint || "run `tot login`, then re-run." };
+    }
+    return {
+      ok: false,
+      message: `couldn't read your Token of Trust session: ${e?.message || e}`,
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+
+  const base = tenantBase(tenant);
+  let res;
+  try {
+    res = await fetchImpl(`${base}/api/dev/cli-session`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${dev.token}` },
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      message: `couldn't reach ${base} to start a session: ${e?.message || e}`,
+      hint: "check the --tenant domain / your network, then re-run.",
+    };
+  }
+  if (res.status === 401) {
+    return {
+      ok: false,
+      message: "your `tot` session wasn't recognized for this store.",
+      hint: "run `tot login`, then re-run.",
+    };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      message: `couldn't start a session at ${base} (HTTP ${res.status}).`,
+      hint: "retry shortly; if it persists, this store may not be set up for CLI publishing yet.",
+    };
+  }
+
+  const cookie = parseSessionCookie(res.headers.get("set-cookie"));
+  if (!cookie) {
+    return {
+      ok: false,
+      message: "the store started a session but returned no session cookie.",
+      hint: "re-run; if it persists, report it via `tot` feedback.",
+    };
+  }
+
+  return {
+    ok: true,
+    base,
+    authHeaders: {
+      cookie: `${SESSION_COOKIE}=${cookie}`,
+      // Matches the admin browser client; the server IGNORES this hint and re-reads
+      // the live ship-on-behalf grant, so it authorizes nothing on its own.
+      "x-tot-capability": "ship-on-behalf",
+    },
+  };
+}

package/template/private-app/README.md

@@ -1,17 +1,22 @@
 # my-app
 
-A Storefront Private App, scaffolded by `tot app scaffold`. See
-[the Private Apps devbook](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/devbook/private-apps-devbook.md)
-for the full contract this manifest and receiver implement.
+A Storefront Private App, scaffolded by `tot app scaffold`. Start with the
+[public Storefront Devkit Apps / Private track](https://github.com/tokenoftrust/storefront-devkit/tree/main/apps/private)
+for the canonical contract this manifest and receiver implement. The Devkit's
+root [`README.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/README.md),
+[`AGENTS.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/AGENTS.md), and
+[`manifest.json`](https://github.com/tokenoftrust/storefront-devkit/blob/main/manifest.json)
+are the stable human and LLM entry points.
 
 ## What's here
 
 - **`tot-app.json`** — your app's manifest: identity, scopes, webhook
   subscriptions, widgets. Validated against
-  [`tot-app.schema.json`](https://github.com/tokenoftrust/storefront/blob/main/docs/private-apps/contract/tot-app.schema.json).
+  [`tot-app.schema.json`](https://github.com/tokenoftrust/storefront-devkit/blob/main/apps/private/contract/tot-app.schema.json).
   Everything here is a PLACEHOLDER — edit `id`, `owner`, `webhooks.endpoint`,
   and `scopes` for your real app before you install it anywhere.
-- **`fixtures/`** — sample CloudEvents (from `docs/private-apps/contract/examples/`)
+- **`fixtures/`** — sample CloudEvents (from the Devkit's
+  [`apps/private/contract/examples/`](https://github.com/tokenoftrust/storefront-devkit/tree/main/apps/private/contract/examples/))
   you can sign and deliver to your own receiver locally, before you have a
   real install. Add one fixture per topic you subscribe to.
 - **`server.js`** — a minimal Node HTTP receiver for `webhooks.endpoint`. It
@@ -42,4 +47,5 @@ for the full command surface.
 2. Get your manifest installed for a real `(tenant, env)` — this issues your
    real client credentials; nothing above touches them.
 3. Swap the dev-only signature verification for the real gateway's published
-   JWKS/signing-key metadata (see the devbook's Signature Verification section).
+   JWKS/signing-key metadata (see the Devkit's
+   [`webhooks-and-api.md`](https://github.com/tokenoftrust/storefront-devkit/blob/main/apps/private/webhooks-and-api.md)).