From 126ca62fa2ff25b21642eb555629e85181aa7948 Mon Sep 17 00:00:00 2001
From: Gerard Kavanagh <gerard161@gmail.com>
Date: Mon, 5 Oct 2026 11:50:23 +0100
Subject: [PATCH 1/3] feat(signup): remember a Dr Green ?ref= landing code in
 the bs_ref cookie (BS-A01)

Middleware adds a 30-day HttpOnly SameSite=Lax first-party cookie to
storefront page responses when ?ref= matches Dr Green's code format
(upper-cased; malformed values set nothing). /register keeps its query
string on the redirect to /consultation. bs_ref is listed as an essential
storefront cookie in lib/cookie-utils.ts. PRD copied to tasks/.
---
 .../app/store/[slug]/register/page.tsx        |   8 +-
 nextjs_space/lib/affiliate/affiliate-code.ts  |  70 +++++++++++
 nextjs_space/lib/affiliate/referral-cookie.ts |  64 ++++++++++
 nextjs_space/lib/cookie-utils.ts              |  40 ++++++
 nextjs_space/middleware.ts                    |  26 +++-
 .../unit/affiliate-referral-cookie.test.ts    | 114 ++++++++++++++++++
 tasks/prd-drgreen-affiliate-codes.md          |  77 ++++++++++++
 7 files changed, 394 insertions(+), 5 deletions(-)
 create mode 100644 nextjs_space/lib/affiliate/affiliate-code.ts
 create mode 100644 nextjs_space/lib/affiliate/referral-cookie.ts
 create mode 100644 nextjs_space/tests/unit/affiliate-referral-cookie.test.ts
 create mode 100644 tasks/prd-drgreen-affiliate-codes.md

diff --git a/nextjs_space/app/store/[slug]/register/page.tsx b/nextjs_space/app/store/[slug]/register/page.tsx
index 436e855d..4de10341 100644
--- a/nextjs_space/app/store/[slug]/register/page.tsx
+++ b/nextjs_space/app/store/[slug]/register/page.tsx
@@ -9,7 +9,7 @@ import { getTenantBasePath } from "@/lib/tenant/tenant-utils";
  * Registration Redirect
  *
  * All customer signups must go through the consultation form for KYC compliance.
- * This page redirects to the consultation page.
+ * This page redirects to the consultation page, query string included.
  */
 export default function RegisterRedirectPage() {
   const params = useParams();
@@ -19,7 +19,11 @@ export default function RegisterRedirectPage() {
   useEffect(() => {
     if (slug) {
       const basePath = getTenantBasePath(slug);
-      router.replace(`${basePath}/consultation`);
+      // BS-A01: keep the query string so a holder's /register?ref=CODE link
+      // still pre-fills the referral code. Read from window.location (this
+      // effect only runs in the browser) rather than useSearchParams, which
+      // would need a Suspense boundary around this page.
+      router.replace(`${basePath}/consultation${window.location.search}`);
     }
   }, [slug, router]);
 
diff --git a/nextjs_space/lib/affiliate/affiliate-code.ts b/nextjs_space/lib/affiliate/affiliate-code.ts
new file mode 100644
index 00000000..1c60c6ff
--- /dev/null
+++ b/nextjs_space/lib/affiliate/affiliate-code.ts
@@ -0,0 +1,70 @@
+/**
+ * Dr Green affiliate codes — the BudStacks capture side (BS-A01..A03,
+ * tasks/prd-drgreen-affiliate-codes.md). Dr Green defines the code (its
+ * US-A02) and decides what it links to (US-A04); BudStacks only remembers the
+ * code a visitor arrived with, lets them type one, and forwards it.
+ *
+ * A code never changes a price and never blocks a sign-up.
+ *
+ * Pure and runtime-agnostic: imported by middleware (edge), the consultation
+ * page and route (node) and the sign-up form (browser).
+ */
+
+/**
+ * Dr Green US-A02: 4–20 characters, letters, digits and hyphens, starting and
+ * ending with a letter or digit. Stored upper-case, matched case-insensitively.
+ */
+export const AFFILIATE_CODE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9-]{2,18}[A-Za-z0-9]$/;
+export const AFFILIATE_CODE_MAX_LENGTH = 20;
+
+/** The query parameter a holder's share link carries (`?ref=CODE`). */
+export const REFERRAL_QUERY_PARAM = "ref";
+
+/** First-party landing cookie — strictly functional (lib/cookie-utils.ts). */
+export const REFERRAL_COOKIE_NAME = "bs_ref";
+export const REFERRAL_COOKIE_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+
+/** Sent to Dr Green as `affiliateCodeSource` (US-A04). */
+export const AFFILIATE_CODE_SOURCE = {
+  LINK: "link",
+  TYPED: "typed",
+} as const;
+
+export type AffiliateCodeSource =
+  (typeof AFFILIATE_CODE_SOURCE)[keyof typeof AFFILIATE_CODE_SOURCE];
+
+/** Field copy for the sign-up forms. */
+export const AFFILIATE_CODE_LABEL = "Referral code (optional)";
+export const AFFILIATE_CODE_HELP = "Does not change any price.";
+export const AFFILIATE_CODE_FORMAT_ERROR =
+  "Referral codes are 4 to 20 letters, numbers or hyphens. Check the code, or leave the field empty.";
+
+/** True when `value` is a well-formed code (case-insensitive). */
+export function isAffiliateCodeFormat(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length <= AFFILIATE_CODE_MAX_LENGTH &&
+    AFFILIATE_CODE_PATTERN.test(value)
+  );
+}
+
+/**
+ * The canonical (trimmed, upper-cased) code, or null for anything absent or
+ * malformed. Malformed input is never an error at this layer: it is simply
+ * not a code.
+ */
+export function normaliseAffiliateCode(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return isAffiliateCodeFormat(trimmed) ? trimmed.toUpperCase() : null;
+}
+
+/**
+ * Inline field error for the sign-up forms: null when the field is empty (it
+ * is optional) or well-formed, the format message otherwise.
+ */
+export function affiliateCodeFieldError(value: string | null | undefined): string | null {
+  const trimmed = (value ?? "").trim();
+  if (trimmed === "") return null;
+  return isAffiliateCodeFormat(trimmed) ? null : AFFILIATE_CODE_FORMAT_ERROR;
+}
diff --git a/nextjs_space/lib/affiliate/referral-cookie.ts b/nextjs_space/lib/affiliate/referral-cookie.ts
new file mode 100644
index 00000000..1a5a9d76
--- /dev/null
+++ b/nextjs_space/lib/affiliate/referral-cookie.ts
@@ -0,0 +1,64 @@
+/**
+ * The `bs_ref` landing cookie (BS-A01): written by middleware when a storefront
+ * URL carries a well-formed `?ref=`, read by the consultation page (pre-fill)
+ * and the consultation submit route (link vs typed), cleared by that route on
+ * a successful sign-up (BS-A02).
+ *
+ * Host-only (no Domain attribute): it lives on the storefront host the visitor
+ * landed on — subdomain or custom domain — which is the same host the sign-up
+ * form posts to. HttpOnly, so the form never reads it; the page passes the
+ * value down as an initial value instead.
+ *
+ * Edge-safe: middleware imports this.
+ */
+import type { NextResponse } from "next/server";
+import {
+  REFERRAL_COOKIE_MAX_AGE_SECONDS,
+  REFERRAL_COOKIE_NAME,
+  normaliseAffiliateCode,
+} from "./affiliate-code";
+
+type ResponseWithCookies = Pick<NextResponse, "cookies">;
+
+// Secure in production, as the impersonation cookie does; plain-http local dev
+// (Safari refuses Secure cookies on http://localhost) would otherwise drop it.
+function baseCookieOptions() {
+  return {
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax" as const,
+    path: "/",
+  };
+}
+
+/**
+ * Remember a landing code. A malformed or absent `ref` sets nothing and leaves
+ * any earlier cookie alone; a well-formed one is stored upper-cased and
+ * restarts the 30 days (the latest link the visitor followed wins).
+ * Returns whether a cookie was written.
+ */
+export function setReferralCookie(
+  response: ResponseWithCookies,
+  ref: string | null | undefined,
+): boolean {
+  const code = normaliseAffiliateCode(ref);
+  if (!code) return false;
+  response.cookies.set(REFERRAL_COOKIE_NAME, code, {
+    ...baseCookieOptions(),
+    maxAge: REFERRAL_COOKIE_MAX_AGE_SECONDS,
+  });
+  return true;
+}
+
+/** Expire the landing cookie — called once the sign-up has succeeded. */
+export function clearReferralCookie(response: ResponseWithCookies): void {
+  response.cookies.set(REFERRAL_COOKIE_NAME, "", {
+    ...baseCookieOptions(),
+    maxAge: 0,
+  });
+}
+
+/** The remembered code from a cookie value, or null when absent or tampered. */
+export function readReferralCookie(value: string | null | undefined): string | null {
+  return normaliseAffiliateCode(value);
+}
diff --git a/nextjs_space/lib/cookie-utils.ts b/nextjs_space/lib/cookie-utils.ts
index af87e330..11e13543 100644
--- a/nextjs_space/lib/cookie-utils.ts
+++ b/nextjs_space/lib/cookie-utils.ts
@@ -5,6 +5,8 @@
  * Provides region-based consent logic for GDPR, CCPA, POPIA compliance
  */
 
+import { REFERRAL_COOKIE_NAME } from "@/lib/affiliate/affiliate-code";
+
 // EU countries requiring GDPR opt-in consent
 const EU_COUNTRIES = [
   "AT",
@@ -148,6 +150,44 @@ export function getRegionBannerText(countryCode: string | null | undefined): {
 export const CONSENT_COOKIE_NAME = "budstack_cookie_consent";
 export const CONSENT_CATEGORIES_COOKIE_NAME = "budstack_cookie_categories";
 
+export interface CookieDescriptor {
+  name: string;
+  category: keyof ConsentCategories;
+  purpose: string;
+  duration: string;
+}
+
+/**
+ * First-party cookies BudStacks itself sets on a storefront, by consent
+ * category. `essential` ones are set without asking (they are needed for
+ * something the visitor started) and are never gated on the banner.
+ */
+export const STOREFRONT_COOKIES: readonly CookieDescriptor[] = [
+  {
+    name: CONSENT_COOKIE_NAME,
+    category: "essential",
+    purpose: "Records that you have answered the cookie banner.",
+    duration: "1 year",
+  },
+  {
+    name: CONSENT_CATEGORIES_COOKIE_NAME,
+    category: "essential",
+    purpose: "Records which cookie categories you accepted.",
+    duration: "1 year",
+  },
+  {
+    // BS-A01 (Dr Green affiliate codes): set by middleware from a valid
+    // `?ref=` so the sign-up the visitor started can carry the code they
+    // arrived with. Never read by script (HttpOnly), never changes a price,
+    // cleared once sign-up succeeds.
+    name: REFERRAL_COOKIE_NAME,
+    category: "essential",
+    purpose:
+      "Remembers the referral code in the link you followed, so the sign-up you start can include it. Cleared when you sign up.",
+    duration: "30 days",
+  },
+];
+
 /**
  * Default consent categories based on consent model
  */
diff --git a/nextjs_space/middleware.ts b/nextjs_space/middleware.ts
index 19fcbb59..0b7c4ac6 100644
--- a/nextjs_space/middleware.ts
+++ b/nextjs_space/middleware.ts
@@ -4,6 +4,8 @@ import { parseHostToTenantHint, wwwRedirectHost } from "@/lib/parse-host";
 import { customDomainRewritePath } from "@/lib/custom-domain-rewrite";
 import { resolvePlatformRedirect, resolveStoreRedirect } from "@/lib/seo/redirect-lookup";
 import { applyCsp, buildCsp, generateNonce, variantForServedPath } from "@/lib/security/csp";
+import { REFERRAL_QUERY_PARAM } from "@/lib/affiliate/affiliate-code";
+import { setReferralCookie } from "@/lib/affiliate/referral-cookie";
 
 // Define public routes
 const isPublicRoute = createRouteMatcher([
@@ -109,6 +111,16 @@ function resolveTenantHost(req: NextRequest): string {
     : req.headers.get('host') || '';
 }
 
+// BS-A01 (Dr Green affiliate codes): a storefront PAGE response remembers a
+// well-formed `?ref=CODE` in the first-party `bs_ref` cookie (30 days). Only a
+// Set-Cookie header is added — the rewrite target, headers and CSP are the
+// ones the caller built, so tenant/host routing is untouched. Malformed values
+// set nothing. API routes, admin redirects and /auth never get here.
+function withReferralCookie<T extends NextResponse>(res: T, req: NextRequest): T {
+  setReferralCookie(res, req.nextUrl.searchParams.get(REFERRAL_QUERY_PARAM));
+  return res;
+}
+
 const clerkHandler = clerkMiddleware(async (auth, req) => {
   // 1. Tenant Routing Logic (must run BEFORE auth check)
   // Subdomain rewrites change /products → /store/slug/products which matches
@@ -250,7 +262,10 @@ const clerkHandler = clerkMiddleware(async (auth, req) => {
 
     // Page routes: rewrite to internal store route
     url.pathname = `/store/${subdomain}${pathname}`;
-    return applyCsp(NextResponse.rewrite(url, { request: { headers: requestHeaders } }), nonce, "store");
+    return withReferralCookie(
+      applyCsp(NextResponse.rewrite(url, { request: { headers: requestHeaders } }), nonce, "store"),
+      req,
+    );
   }
 
   // PRIORITY 2: Custom domain routing (REWRITE)
@@ -304,7 +319,10 @@ const clerkHandler = clerkMiddleware(async (auth, req) => {
     // (PRD-212). hint.host is the real custom domain; the derived cd-<hash>
     // segment isolates this domain's ISR cache from every other custom domain.
     url.pathname = customDomainRewritePath(hint.host, pathname);
-    return applyCsp(NextResponse.rewrite(url, { request: { headers: requestHeaders } }), nonce, "store");
+    return withReferralCookie(
+      applyCsp(NextResponse.rewrite(url, { request: { headers: requestHeaders } }), nonce, "store"),
+      req,
+    );
   }
 
   // 2. Authentication Check (only for non-subdomain, non-custom-domain requests)
@@ -325,11 +343,13 @@ const clerkHandler = clerkMiddleware(async (auth, req) => {
   // All requests forward with the nonce + per-request CSP. The static
   // next.config.js CSP was removed (PRD-218) — every response must carry the
   // policy from here so no page renders without it.
-  return applyCsp(
+  const response = applyCsp(
     NextResponse.next({ request: { headers: requestHeaders } }),
     nonce,
     variantForServedPath(pathname),
   );
+  // Path-based storefronts (/store/<slug>/…, localhost) remember ?ref= too.
+  return storeMatch ? withReferralCookie(response, req) : response;
 });
 
 // Clerk derives every absolute URL it builds — most visibly the dev-browser
diff --git a/nextjs_space/tests/unit/affiliate-referral-cookie.test.ts b/nextjs_space/tests/unit/affiliate-referral-cookie.test.ts
new file mode 100644
index 00000000..602a92ab
--- /dev/null
+++ b/nextjs_space/tests/unit/affiliate-referral-cookie.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it } from "vitest";
+import { NextResponse } from "next/server";
+import {
+  AFFILIATE_CODE_FORMAT_ERROR,
+  REFERRAL_COOKIE_MAX_AGE_SECONDS,
+  REFERRAL_COOKIE_NAME,
+  affiliateCodeFieldError,
+  isAffiliateCodeFormat,
+  normaliseAffiliateCode,
+} from "@/lib/affiliate/affiliate-code";
+import {
+  clearReferralCookie,
+  readReferralCookie,
+  setReferralCookie,
+} from "@/lib/affiliate/referral-cookie";
+import { STOREFRONT_COOKIES } from "@/lib/cookie-utils";
+
+/**
+ * BS-A01 — the landing code matcher and the `bs_ref` cookie. The pattern is
+ * Dr Green's (US-A02), so these cases are the contract both sides share.
+ */
+describe("affiliate code matcher (Dr Green US-A02 format)", () => {
+  it.each([
+    "ABCD",
+    "abcd",
+    "TEST-CODE",
+    "a1-b2-c3",
+    "12345678901234567890", // 20 = max
+    "A--B",
+  ])("accepts %s", (code) => {
+    expect(isAffiliateCodeFormat(code)).toBe(true);
+  });
+
+  it.each([
+    "",
+    "ABC", // 3 < min 4
+    "123456789012345678901", // 21 > max 20
+    "-ABCD", // leading hyphen
+    "ABCD-", // trailing hyphen
+    "AB CD", // space
+    "AB_CD", // underscore
+    "AB/CD", // slash (the WordPress json_encode trap)
+    "ÄBCD", // non-ASCII letter
+    "ABCD\n",
+  ])("rejects %j", (code) => {
+    expect(isAffiliateCodeFormat(code)).toBe(false);
+  });
+
+  it("rejects non-strings", () => {
+    expect(isAffiliateCodeFormat(undefined)).toBe(false);
+    expect(isAffiliateCodeFormat(null)).toBe(false);
+    expect(isAffiliateCodeFormat(1234)).toBe(false);
+  });
+
+  it("normalises to trimmed upper-case, null when malformed", () => {
+    expect(normaliseAffiliateCode("  test-code ")).toBe("TEST-CODE");
+    expect(normaliseAffiliateCode("AB")).toBeNull();
+    expect(normaliseAffiliateCode(undefined)).toBeNull();
+  });
+
+  it("gives a field error only for a non-empty malformed value", () => {
+    expect(affiliateCodeFieldError("")).toBeNull();
+    expect(affiliateCodeFieldError("   ")).toBeNull();
+    expect(affiliateCodeFieldError(undefined)).toBeNull();
+    expect(affiliateCodeFieldError("TEST-CODE")).toBeNull();
+    expect(affiliateCodeFieldError("AB")).toBe(AFFILIATE_CODE_FORMAT_ERROR);
+  });
+});
+
+describe("bs_ref landing cookie", () => {
+  it("stores a well-formed ref upper-cased for 30 days, HttpOnly, Lax, path /", () => {
+    const res = NextResponse.json({});
+    expect(setReferralCookie(res, "test-code")).toBe(true);
+
+    const cookie = res.cookies.get(REFERRAL_COOKIE_NAME);
+    expect(cookie?.value).toBe("TEST-CODE");
+    expect(cookie?.maxAge).toBe(REFERRAL_COOKIE_MAX_AGE_SECONDS);
+    expect(REFERRAL_COOKIE_MAX_AGE_SECONDS).toBe(30 * 24 * 60 * 60);
+    expect(cookie?.httpOnly).toBe(true);
+    expect(cookie?.sameSite).toBe("lax");
+    expect(cookie?.path).toBe("/");
+  });
+
+  it.each([null, undefined, "", "AB", "<script>", "AB/CD"])(
+    "sets nothing for %j",
+    (ref) => {
+      const res = NextResponse.json({});
+      expect(setReferralCookie(res, ref)).toBe(false);
+      expect(res.cookies.get(REFERRAL_COOKIE_NAME)).toBeUndefined();
+      expect(res.headers.get("set-cookie")).toBeNull();
+    },
+  );
+
+  it("clears the cookie with Max-Age 0", () => {
+    const res = NextResponse.json({ ok: true });
+    clearReferralCookie(res);
+    const cookie = res.cookies.get(REFERRAL_COOKIE_NAME);
+    expect(cookie?.value).toBe("");
+    expect(cookie?.maxAge).toBe(0);
+    expect(cookie?.path).toBe("/");
+  });
+
+  it("reads back only a well-formed value", () => {
+    expect(readReferralCookie("TEST-CODE")).toBe("TEST-CODE");
+    expect(readReferralCookie("x")).toBeNull();
+    expect(readReferralCookie(undefined)).toBeNull();
+  });
+
+  it("is listed as an essential storefront cookie", () => {
+    const entry = STOREFRONT_COOKIES.find((c) => c.name === REFERRAL_COOKIE_NAME);
+    expect(entry?.category).toBe("essential");
+    expect(entry?.duration).toBe("30 days");
+  });
+});
diff --git a/tasks/prd-drgreen-affiliate-codes.md b/tasks/prd-drgreen-affiliate-codes.md
new file mode 100644
index 00000000..cddce9da
--- /dev/null
+++ b/tasks/prd-drgreen-affiliate-codes.md
@@ -0,0 +1,77 @@
+# PRD — BudStacks: capture Dr Green affiliate codes at sign-up
+
+| | |
+|---|---|
+| **Version** | v1 draft 2026-10-05 |
+| **Owner** | Gerard Kavanagh (CTO; owns and releases BudStacks) |
+| **Surface** | `budstack-saas` (`nextjs_space/`) |
+| **Related** | Dr Green `dr-green-backend/docs/prd/affiliate-codes.prd.md` (US-A04 defines the field); design https://claude.ai/artifact/6X9giM6SSdadKH9oH4d5xk (section C) |
+| **Depends on** | Can ship before Dr Green Phase A: the backend strips unknown DTO fields (`ValidationPipe({ whitelist: true })`), so `affiliateCode` is ignored until the backend accepts it. End-to-end verification needs Dr Green Phase A on staging. |
+| **Estimate** | 2 engineer-days |
+
+## 0. Status
+
+In progress on `feat/drgreen-affiliate-capture` (from `origin/main` @ `79e0b098`), one commit per story. Typecheck / lint / unit tests have not been run (house rule: nothing executes on the workstation; a PR to `main` is a production deploy). Run before opening the PR: `pnpm -C nextjs_space exec tsc --noEmit && pnpm -C nextjs_space lint && pnpm -C nextjs_space test`.
+
+## 1. Introduction / Overview
+
+A Dr Green KEY holder hands out tracking codes; a customer who arrives at a BudStacks storefront with `?ref=CODE` (or types the code at sign-up) should be linked to it on the Dr Green side. BudStacks only captures and forwards; it stores the code for its own records but makes no decision on it. A code never changes a price.
+
+Verified in code 2026-10-02 (`origin/main` 79e0b098):
+
+- `/store/[slug]/register` client-redirects to `/consultation` and drops the query string (`app/store/[slug]/register/page.tsx:19-24`); `middleware.ts` reads no search params or cookies for attribution; the consultation page reads none.
+- `consultationSchema` is a strict `z.object` that strips unknown keys (`app/api/consultation/submit/route.ts:63-132`); the forms spread `formData` (`components/consultation/consultation-form.tsx:124-133`, `id-upload-form.tsx:137-149`).
+- Dr Green client payloads are built in `lib/drgreen/kyc-client-payload.ts:114-172` (KYC) and `lib/drgreen-identity.ts:304-344` (SA ID); `consentSource` shows the pattern for an optional attribution field.
+- No `referral`/`affiliate`/`utm` handling exists; `users` has `marketingConsentSource` and `title` from BS-302/303 as the nearest precedent.
+
+## 2. Goals
+
+- A `?ref=` on any storefront URL survives to sign-up and is sent to Dr Green with the new client.
+- A customer can also type a code on the sign-up form; a typed code wins.
+- BudStacks keeps the code on the local user for the tenant admin's reference.
+
+## 3. User stories
+
+### BS-A01: Remember the landing code — ✅ built
+**Acceptance Criteria:**
+- [x] In `middleware.ts` (or the storefront `app/store/[slug]/layout.tsx` if middleware cannot set cookies on that path), when `?ref=` matches `^[A-Za-z0-9][A-Za-z0-9-]{2,18}[A-Za-z0-9]$`, set cookie `bs_ref` = upper-cased value, 30 days, `SameSite=Lax`, `HttpOnly`, `Secure`, path `/`. Malformed values set nothing. — *Middleware: `withReferralCookie` adds the Set-Cookie to the three storefront page responses only (subdomain rewrite, custom-domain rewrite, path-based `/store/<slug>/…`); rewrite target, headers and CSP unchanged. A layout cannot set cookies in Next 14 (Server Components are read-only), so middleware is the only server-side place. Host-only cookie; `Secure` in production (same rule as the impersonation cookie, so plain-http local dev still works).*
+- [x] The `register` → `consultation` redirect preserves the query string so direct `/register?ref=` links work.
+- [x] Cookie consent: the cookie is strictly functional (needed to complete the sign-up the visitor started); document it in the cookie policy list in `lib/cookie-utils.ts` under the necessary category. — *There was no list; `STOREFRONT_COOKIES` added (the two consent cookies + `bs_ref`, all `essential`). See §0 on whether "strictly necessary" holds.*
+- [x] Unit test for the matcher (`tests/unit/affiliate-referral-cookie.test.ts`: matcher, normalise, set/skip/clear, essential listing).
+- [ ] Typecheck/lint passes — *pending: run before the PR (see §0).*
+
+### BS-A02: Sign-up field and forwarding
+**Acceptance Criteria:**
+- [ ] The consultation contact step and the ID-upload form gain an optional "Referral code (optional)" input, pre-filled from `bs_ref` (read server-side and passed as an initial value), with the helper text "Does not change any price."
+- [ ] `consultationSchema` gains `affiliateCode: z.string().regex(...).max(20).optional()`; the route sets `affiliateCodeSource = 'typed'` when the submitted value differs from the cookie, else `'link'`.
+- [ ] `buildKycClientPayload` and `createSaIdClient` add `affiliateCode` and `affiliateCodeSource` only when present (same shape as `consentSource`).
+- [ ] The cookie is cleared on successful sign-up.
+- [ ] Unit tests: link-only, typed-overrides-link, malformed-typed-rejected-with-field-error (not a 400 on the whole form), absent = unchanged payload.
+- [ ] Typecheck/lint passes; verify in browser after deploy.
+
+### BS-A03: Local record
+**Acceptance Criteria:**
+- [ ] `users` gains `affiliateCode String?` and `affiliateCodeSource String?` (hand-run SQL per `prisma/schema.prisma:573` convention; additive).
+- [ ] Tenant-admin customers table shows the code as a read-only column and the CSV includes it.
+- [ ] Verify in browser; typecheck/lint passes.
+
+## 4. Functional requirements
+
+- FR-1: `?ref=` is captured once, validated, and kept 30 days.
+- FR-2: Sign-up forwards `affiliateCode` + `affiliateCodeSource` to Dr Green when present; never blocks sign-up.
+- FR-3: The code is stored locally for reference only.
+
+## 5. Non-goals
+
+- Any price, discount or reward tied to a code (Dr Green PRD non-goals; CPA s38 risk).
+- Capturing a code at checkout for existing customers (Dr Green links at sign-up only).
+- Showing marketers anything.
+
+## 6. Technical considerations
+
+- Run `pnpm -C nextjs_space exec tsc --noEmit && pnpm -C nextjs_space lint && pnpm -C nextjs_space test` before the PR; a PR to `main` is a production deploy.
+- The orders submit schema is `.strict()`; no change needed since the code is not sent at checkout.
+
+## 7. Success metrics
+
+- A test sign-up via `?ref=TEST-CODE` against Dr Green staging shows the code on the client in the dApp.

From 5b2232286c43dab105aa0e685a087ff2631e3c26 Mon Sep 17 00:00:00 2001
From: Gerard Kavanagh <gerard161@gmail.com>
Date: Mon, 5 Oct 2026 11:55:35 +0100
Subject: [PATCH 2/3] feat(signup): referral code field forwarded to Dr Green
 as affiliateCode (BS-A02)

The consultation and ID-upload forms gain an optional 'Referral code
(optional)' input pre-filled server-side from ?ref= or the bs_ref cookie,
validated inline. The submit route resolves affiliateCodeSource ('link'
when the submitted code is the remembered one, else 'typed'), forwards
affiliateCode + affiliateCodeSource through buildKycClientPayload and
createSaIdClient only when present, and clears bs_ref on success. A
malformed code is dropped, never a 400 for the registration.

The Dr Green error classifier is lifted out of the route unchanged
(lib/drgreen/registration-error.ts) to stay under the 800-line cap.
---
 .../app/api/consultation/submit/route.ts      |  53 ++--
 .../app/store/[slug]/consultation/page.tsx    |  38 ++-
 .../consultation/consultation-form-types.ts   |   3 +
 .../consultation/consultation-form.tsx        |   5 +
 .../consultation/id-upload-form.tsx           |  10 +-
 .../steps/contact-details-step.tsx            |  43 +++
 .../lib/affiliate/affiliate-code-schema.ts    |  47 ++++
 nextjs_space/lib/affiliate/affiliate-code.ts  |  46 ++++
 nextjs_space/lib/drgreen-identity.ts          |   6 +
 .../lib/drgreen/kyc-client-payload.ts         |   8 +
 .../lib/drgreen/registration-error.ts         |  52 ++++
 .../tests/unit/affiliate-attribution.test.ts  | 123 +++++++++
 .../consultation-submit-affiliate.test.ts     | 258 ++++++++++++++++++
 .../unit/drgreen-registration-error.test.ts   |  33 +++
 .../tests/unit/drgreen-sa-client.test.ts      |  22 ++
 .../tests/unit/kyc-client-payload.test.ts     |  22 ++
 tasks/prd-drgreen-affiliate-codes.md          |  15 +-
 17 files changed, 749 insertions(+), 35 deletions(-)
 create mode 100644 nextjs_space/lib/affiliate/affiliate-code-schema.ts
 create mode 100644 nextjs_space/lib/drgreen/registration-error.ts
 create mode 100644 nextjs_space/tests/unit/affiliate-attribution.test.ts
 create mode 100644 nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
 create mode 100644 nextjs_space/tests/unit/drgreen-registration-error.test.ts

diff --git a/nextjs_space/app/api/consultation/submit/route.ts b/nextjs_space/app/api/consultation/submit/route.ts
index e3e7ce74..60186828 100644
--- a/nextjs_space/app/api/consultation/submit/route.ts
+++ b/nextjs_space/app/api/consultation/submit/route.ts
@@ -23,6 +23,7 @@ import {
 
 import { prisma } from "@/lib/db";
 import { buildKycClientPayload } from '@/lib/drgreen/kyc-client-payload';
+import { classifyDrGreenRegistrationError } from '@/lib/drgreen/registration-error';
 import crypto from "crypto";
 import { z } from "zod";
 
@@ -34,6 +35,9 @@ import { apiError, apiValidationError } from '@/lib/api-error';
 import { checkPolicyGate } from '@/lib/legal/policy-gate';
 import { CUSTOMER_TITLES, normaliseCustomerTitle } from '@/lib/customers/titles';
 import { CONSENT_SOURCE } from '@/lib/customers/marketing-consent';
+import { REFERRAL_COOKIE_NAME, resolveAffiliateAttribution } from '@/lib/affiliate/affiliate-code';
+import { affiliateCodeField, parseSignUpWithOptionalAffiliateCode } from '@/lib/affiliate/affiliate-code-schema';
+import { clearReferralCookie } from '@/lib/affiliate/referral-cookie';
 
 /** 409 for "that address already belongs to an account you have not proven you own". */
 function accountExistsResponse() {
@@ -88,6 +92,10 @@ const consultationSchema = z.object({
   // BS-303: optional salutation from the fixed list; "" = not chosen.
   title: z.union([z.enum(CUSTOMER_TITLES), z.literal("")]).optional(),
 
+  // BS-A02: optional Dr Green affiliate code (US-A02 format, max 20). A
+  // malformed one is dropped, never a 400 — parseSignUpWithOptionalAffiliateCode.
+  affiliateCode: affiliateCodeField,
+
   // SA ID-upload (idMode) — see idDocumentSchema above.
   idDocument: idDocumentSchema.optional(),
 
@@ -143,7 +151,11 @@ export async function POST(request: NextRequest) {
 
     const rawBody = await request.json();
 
-    const parseResult = consultationSchema.safeParse(rawBody);
+    const { result: parseResult, affiliateCodeIssue } =
+      parseSignUpWithOptionalAffiliateCode(consultationSchema, rawBody);
+    if (affiliateCodeIssue) {
+      logger.info("[Consultation] malformed affiliate code ignored; sign-up continues");
+    }
     if (!parseResult.success) {
       const firstError = parseResult.error.errors[0];
       return apiValidationError(
@@ -221,6 +233,11 @@ export async function POST(request: NextRequest) {
     const customerTitle = normaliseCustomerTitle(body.title);
     // US-023: consent only on an explicit tick — never inferred.
     const consented = body.marketingConsent === true;
+    // BS-A02: 'link' when the submitted code is the remembered bs_ref one, else 'typed'.
+    const affiliate = resolveAffiliateAttribution(
+      body.affiliateCode,
+      request.cookies.get(REFERRAL_COOKIE_NAME)?.value,
+    );
 
     // A storefront with no published privacy notice tells visitors exactly that
     // — so taking a consultation here would collect special-category data with
@@ -500,6 +517,8 @@ export async function POST(request: NextRequest) {
           title: customerTitle,
           marketingConsent: consented,
           consentSource: registrationSource,
+          affiliateCode: affiliate?.affiliateCode,
+          affiliateCodeSource: affiliate?.affiliateCodeSource,
           shipping: {
             address1: body.addressLine1,
             address2: body.addressLine2 || "",
@@ -561,6 +580,8 @@ export async function POST(request: NextRequest) {
         title: customerTitle,
         marketingConsent: consented,
         consentSource: registrationSource,
+        affiliateCode: affiliate?.affiliateCode ?? null,
+        affiliateCodeSource: affiliate?.affiliateCodeSource ?? null,
       });
 
       // Submit to Dr. Green API via shared client
@@ -684,7 +705,7 @@ export async function POST(request: NextRequest) {
         },
       });
 
-      return NextResponse.json({
+      const response = NextResponse.json({
         success: true,
         message: "Consultation submitted successfully",
         questionnaireId: questionnaire.id,
@@ -692,6 +713,8 @@ export async function POST(request: NextRequest) {
         kycLink: kycLink,
         adminApproval: "PENDING",
       });
+      clearReferralCookie(response); // BS-A02: the landing code has done its job.
+      return response;
     } catch (drGreenError: any) {
       // Message only — the Dr Green error object/body can echo back the
       // submitted PHI; never log the whole thing.
@@ -700,29 +723,9 @@ export async function POST(request: NextRequest) {
         message: drGreenError instanceof Error ? drGreenError.message : String(drGreenError),
       });
 
-      // Parse Dr Green error for user-friendly messages
-      const errorMsg = drGreenError.message || "";
-      let userMessage = "Registration failed. Please try again or contact support.";
-      let statusCode = 500;
-      let failureCode = "UNKNOWN";
-
-      if (errorMsg.includes("Phone Number already exists") || errorMsg.includes("phone") && errorMsg.includes("exists")) {
-        userMessage = "This phone number is already registered. Please use a different phone number or contact support.";
-        statusCode = 409;
-        failureCode = "PHONE_EXISTS";
-      } else if (errorMsg.includes("email") && errorMsg.includes("exists")) {
-        userMessage = "This email address is already registered. Please use a different email or try logging in.";
-        statusCode = 409;
-        failureCode = "EMAIL_EXISTS";
-      } else if (errorMsg.includes("409")) {
-        userMessage = "An account with these details already exists. Please use different details or contact support.";
-        statusCode = 409;
-        failureCode = "CONFLICT";
-      } else if (errorMsg.includes("400")) {
-        userMessage = "Invalid information provided. Please check your details and try again.";
-        statusCode = 400;
-        failureCode = "BAD_REQUEST";
-      }
+      // Parse Dr Green error for user-friendly messages (lib/drgreen/registration-error.ts)
+      const { userMessage, statusCode, failureCode } =
+        classifyDrGreenRegistrationError(drGreenError.message);
 
       // Persist a stable classification, NOT the upstream message. Dr Green
       // error bodies echo back submitted values (see the logger note above), so
diff --git a/nextjs_space/app/store/[slug]/consultation/page.tsx b/nextjs_space/app/store/[slug]/consultation/page.tsx
index cea716c5..2d240d30 100644
--- a/nextjs_space/app/store/[slug]/consultation/page.tsx
+++ b/nextjs_space/app/store/[slug]/consultation/page.tsx
@@ -1,4 +1,5 @@
 import type { Metadata } from "next";
+import { cookies } from "next/headers";
 import { ConsultationForm } from "@/components/consultation/consultation-form";
 import { notFound } from "next/navigation";
 import { generateStoreRouteMetadata } from "@/lib/seo/generate-page-metadata";
@@ -10,6 +11,28 @@ import {
   getTenantVerificationMode,
   isSaIdUploadEnabled,
 } from "@/lib/verification-mode";
+import {
+  REFERRAL_COOKIE_NAME,
+  REFERRAL_QUERY_PARAM,
+  normaliseAffiliateCode,
+} from "@/lib/affiliate/affiliate-code";
+
+/**
+ * BS-A02: the referral-code field's initial value. A `?ref=` on this very
+ * request wins (middleware sets `bs_ref` on this response, so the cookie is
+ * not on the request yet); otherwise the remembered `bs_ref` cookie. The
+ * cookie is HttpOnly, so it is read here and handed down, never by the form.
+ */
+function initialAffiliateCode(
+  searchParams: Record<string, string | string[] | undefined> | undefined,
+): string {
+  const ref = searchParams?.[REFERRAL_QUERY_PARAM];
+  return (
+    normaliseAffiliateCode(Array.isArray(ref) ? ref[0] : ref) ??
+    normaliseAffiliateCode(cookies().get(REFERRAL_COOKIE_NAME)?.value) ??
+    ""
+  );
+}
 
 /**
  * SEO US-007 — nav- and footer-linked (components/navigation.tsx:104,
@@ -37,8 +60,10 @@ export async function generateMetadata(): Promise<Metadata> {
 
 export default async function ConsultationPage({
   params,
+  searchParams,
 }: {
   params: { slug: string };
+  searchParams?: Record<string, string | string[] | undefined>;
 }) {
   const tenant = await getCurrentTenant();
 
@@ -54,6 +79,7 @@ export default async function ConsultationPage({
   // SA ID-upload tenants skip the medical consultation: register + upload an ID.
   const idMode =
     isSaIdUploadEnabled() && getTenantVerificationMode(tenant) === "ID_UPLOAD";
+  const affiliateCode = initialAffiliateCode(searchParams);
 
   return (
     <div
@@ -74,7 +100,11 @@ export default async function ConsultationPage({
                 >
                   Register &amp; verify with your ID
                 </h2>
-                <IdUploadForm tenantSlug={tenant.subdomain} storeName={tenant.businessName} />
+                <IdUploadForm
+                  tenantSlug={tenant.subdomain}
+                  storeName={tenant.businessName}
+                  initialAffiliateCode={affiliateCode}
+                />
               </div>
             </div>
           </section>
@@ -95,7 +125,11 @@ export default async function ConsultationPage({
                   >
                     Register here
                   </h2>
-                  <ConsultationForm tenantSlug={tenant.subdomain} storeName={tenant.businessName} />
+                  <ConsultationForm
+                    tenantSlug={tenant.subdomain}
+                    storeName={tenant.businessName}
+                    initialAffiliateCode={affiliateCode}
+                  />
                 </div>
               </div>
             </section>
diff --git a/nextjs_space/components/consultation/consultation-form-types.ts b/nextjs_space/components/consultation/consultation-form-types.ts
index 5d9d063f..04f0764f 100644
--- a/nextjs_space/components/consultation/consultation-form-types.ts
+++ b/nextjs_space/components/consultation/consultation-form-types.ts
@@ -16,6 +16,9 @@ export interface ConsultationFormData {
   marketingConsent: boolean;
   // BS-303: optional salutation from lib/customers/titles.ts; "" = not chosen.
   title: string;
+  // BS-A02: optional Dr Green referral code, pre-filled from the bs_ref
+  // landing cookie; "" = none. Never changes a price.
+  affiliateCode: string;
 
   // Shipping Address
   addressLine1: string;
diff --git a/nextjs_space/components/consultation/consultation-form.tsx b/nextjs_space/components/consultation/consultation-form.tsx
index c87e8cbb..f6354dc3 100644
--- a/nextjs_space/components/consultation/consultation-form.tsx
+++ b/nextjs_space/components/consultation/consultation-form.tsx
@@ -26,11 +26,14 @@ interface ConsultationFormProps {
   tenantSlug: string;
   /** The store's business name — read into the marketing-consent copy (BS-302). */
   storeName?: string;
+  /** BS-A02: referral code from ?ref= / the bs_ref cookie, read server-side. */
+  initialAffiliateCode?: string;
 }
 
 export function ConsultationForm({
   tenantSlug,
   storeName,
+  initialAffiliateCode,
 }: ConsultationFormProps) {
   const router = useRouter();
   const [currentStep, setCurrentStep] = useState(1);
@@ -47,6 +50,7 @@ export function ConsultationForm({
     confirmPassword: "",
     marketingConsent: false,
     title: "",
+    affiliateCode: initialAffiliateCode ?? "",
 
     addressLine1: "",
     addressLine2: "",
@@ -126,6 +130,7 @@ export function ConsultationForm({
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           ...formData,
+          affiliateCode: formData.affiliateCode.trim(),
           // SECURITY: Send the tenant SLUG (public, in URL) — NEVER the
           // internal tenantId UUID. Server resolves tenant from request
           // host first; this slug is only used as a localhost dev fallback.
diff --git a/nextjs_space/components/consultation/id-upload-form.tsx b/nextjs_space/components/consultation/id-upload-form.tsx
index 9c3a9868..ef7c8640 100644
--- a/nextjs_space/components/consultation/id-upload-form.tsx
+++ b/nextjs_space/components/consultation/id-upload-form.tsx
@@ -25,6 +25,8 @@ interface IdUploadFormProps {
   tenantSlug: string;
   /** The store's business name — read into the marketing-consent copy (BS-302). */
   storeName?: string;
+  /** BS-A02: referral code from ?ref= / the bs_ref cookie, read server-side. */
+  initialAffiliateCode?: string;
 }
 
 const fileToBase64 = (file: File): Promise<string> =>
@@ -39,7 +41,11 @@ const fileToBase64 = (file: File): Promise<string> =>
     reader.readAsDataURL(file);
   });
 
-export function IdUploadForm({ tenantSlug, storeName }: IdUploadFormProps) {
+export function IdUploadForm({
+  tenantSlug,
+  storeName,
+  initialAffiliateCode,
+}: IdUploadFormProps) {
   const router = useRouter();
   const [currentStep, setCurrentStep] = useState(1);
   const [isSubmitting, setIsSubmitting] = useState(false);
@@ -62,6 +68,7 @@ export function IdUploadForm({ tenantSlug, storeName }: IdUploadFormProps) {
     confirmPassword: "",
     marketingConsent: false,
     title: "",
+    affiliateCode: initialAffiliateCode ?? "",
 
     addressLine1: "",
     addressLine2: "",
@@ -139,6 +146,7 @@ export function IdUploadForm({ tenantSlug, storeName }: IdUploadFormProps) {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           ...formData,
+          affiliateCode: formData.affiliateCode.trim(),
           tenantSlug,
           idDocument: {
             fileBase64,
diff --git a/nextjs_space/components/consultation/steps/contact-details-step.tsx b/nextjs_space/components/consultation/steps/contact-details-step.tsx
index 49ea43a4..cbecb201 100644
--- a/nextjs_space/components/consultation/steps/contact-details-step.tsx
+++ b/nextjs_space/components/consultation/steps/contact-details-step.tsx
@@ -23,6 +23,12 @@ import type { ConsultationFormData } from "../consultation-form-types";
 import { COUNTRY_CODES } from "@/lib/consultation-constants";
 import { CUSTOMER_TITLES } from "@/lib/customers/titles";
 import { marketingConsentCopy } from "@/lib/customers/marketing-consent";
+import {
+  AFFILIATE_CODE_HELP,
+  AFFILIATE_CODE_LABEL,
+  AFFILIATE_CODE_MAX_LENGTH,
+  affiliateCodeFieldError,
+} from "@/lib/affiliate/affiliate-code";
 import { cn } from "@/lib/utils";
 
 interface ContactDetailsStepProps {
@@ -66,6 +72,10 @@ export function ContactDetailsStep({
       newErrors.confirmPassword = "Please confirm password";
     else if (data.password !== data.confirmPassword)
       newErrors.confirmPassword = "Passwords do not match";
+    // BS-A02: optional — empty is always valid; a malformed code is an error
+    // on this field only (correct it or clear it).
+    const affiliateCodeError = affiliateCodeFieldError(data.affiliateCode);
+    if (affiliateCodeError) newErrors.affiliateCode = affiliateCodeError;
 
     setErrors(newErrors);
     return Object.keys(newErrors).length === 0;
@@ -370,6 +380,39 @@ export function ContactDetailsStep({
         )}
       </div>
 
+      {/* BS-A02: Dr Green referral code — optional, pre-filled from the link
+          the customer arrived by. Attribution only; never a discount. */}
+      <div className="md:w-1/2 md:pr-2">
+        <Label htmlFor="affiliateCode">{AFFILIATE_CODE_LABEL}</Label>
+        <Input
+          id="affiliateCode"
+          value={data.affiliateCode}
+          maxLength={AFFILIATE_CODE_MAX_LENGTH}
+          autoComplete="off"
+          autoCapitalize="characters"
+          spellCheck={false}
+          aria-describedby="affiliateCode-help"
+          aria-invalid={Boolean(errors.affiliateCode)}
+          onChange={(e) => {
+            onUpdate({ affiliateCode: e.target.value });
+            if (errors.affiliateCode) {
+              setErrors(({ affiliateCode: _cleared, ...rest }) => rest);
+            }
+          }}
+          onBlur={() => {
+            const error = affiliateCodeFieldError(data.affiliateCode);
+            if (error) setErrors((prev) => ({ ...prev, affiliateCode: error }));
+          }}
+          className={errors.affiliateCode ? "border-red-500" : ""}
+        />
+        <p id="affiliateCode-help" className="text-xs text-muted-foreground mt-1">
+          {AFFILIATE_CODE_HELP}
+        </p>
+        {errors.affiliateCode && (
+          <p className="text-sm text-red-500 mt-1">{errors.affiliateCode}</p>
+        )}
+      </div>
+
       {/* US-023 (POPIA): marketing consent — optional and UNTICKED by default.
           No validation on purpose: leaving it unticked is always valid. */}
       <label className="flex items-start space-x-2 cursor-pointer">
diff --git a/nextjs_space/lib/affiliate/affiliate-code-schema.ts b/nextjs_space/lib/affiliate/affiliate-code-schema.ts
new file mode 100644
index 00000000..e2a06cd8
--- /dev/null
+++ b/nextjs_space/lib/affiliate/affiliate-code-schema.ts
@@ -0,0 +1,47 @@
+/**
+ * BS-A02 — the `affiliateCode` field of the consultation submit schema, and
+ * the parse that keeps a malformed code from failing the whole sign-up.
+ *
+ * Kept apart from affiliate-code.ts so middleware (edge) never bundles zod.
+ */
+import { z } from "zod";
+import { AFFILIATE_CODE_MAX_LENGTH, AFFILIATE_CODE_PATTERN } from "./affiliate-code";
+
+export const AFFILIATE_CODE_FIELD = "affiliateCode";
+
+/** Optional; "" = the customer left the field empty (or cleared it). */
+export const affiliateCodeField = z
+  .union([
+    z.literal(""),
+    z.string().trim().regex(AFFILIATE_CODE_PATTERN).max(AFFILIATE_CODE_MAX_LENGTH),
+  ])
+  .optional();
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Parse a sign-up body whose schema declares `affiliateCode`. A malformed code
+ * is a field error on that one input — the form shows it inline before submit
+ * (`affiliateCodeFieldError`) — and never a 400 for the whole registration:
+ * the body is re-parsed without it, so the sign-up proceeds with no code (Dr
+ * Green FR-2: a code never blocks sign-up), and when something else is also
+ * wrong the error reported is that other field's, as it was before this field
+ * existed.
+ */
+export function parseSignUpWithOptionalAffiliateCode<S extends z.ZodTypeAny>(
+  schema: S,
+  raw: unknown,
+): { result: z.SafeParseReturnType<z.input<S>, z.output<S>>; affiliateCodeIssue: z.ZodIssue | null } {
+  const first = schema.safeParse(raw);
+  if (first.success || !isPlainObject(raw)) {
+    return { result: first, affiliateCodeIssue: null };
+  }
+  const codeIssue = first.error.issues.find((issue) => issue.path[0] === AFFILIATE_CODE_FIELD);
+  if (!codeIssue) {
+    return { result: first, affiliateCodeIssue: null };
+  }
+  const { [AFFILIATE_CODE_FIELD]: _malformed, ...rest } = raw;
+  return { result: schema.safeParse(rest), affiliateCodeIssue: codeIssue };
+}
diff --git a/nextjs_space/lib/affiliate/affiliate-code.ts b/nextjs_space/lib/affiliate/affiliate-code.ts
index 1c60c6ff..dcc30719 100644
--- a/nextjs_space/lib/affiliate/affiliate-code.ts
+++ b/nextjs_space/lib/affiliate/affiliate-code.ts
@@ -68,3 +68,49 @@ export function affiliateCodeFieldError(value: string | null | undefined): strin
   if (trimmed === "") return null;
   return isAffiliateCodeFormat(trimmed) ? null : AFFILIATE_CODE_FORMAT_ERROR;
 }
+
+/** What BudStacks forwards to Dr Green and keeps on the local user. */
+export interface AffiliateAttribution {
+  affiliateCode: string;
+  affiliateCodeSource: AffiliateCodeSource;
+}
+
+/**
+ * BS-A02. The submitted field is the only source of the code: the form is
+ * pre-filled from the `bs_ref` cookie, so a customer who clears the field has
+ * removed the code and nothing is sent. The cookie decides attribution only —
+ * `link` when the submitted code is the remembered one, `typed` otherwise (a
+ * typed code wins over a remembered link: Dr Green design decision).
+ *
+ * Returns null when there is no well-formed submitted code.
+ */
+export function resolveAffiliateAttribution(
+  submitted: unknown,
+  rememberedCookieValue: string | null | undefined,
+): AffiliateAttribution | null {
+  const affiliateCode = normaliseAffiliateCode(submitted);
+  if (!affiliateCode) return null;
+  const remembered = normaliseAffiliateCode(rememberedCookieValue);
+  return {
+    affiliateCode,
+    affiliateCodeSource:
+      remembered === affiliateCode ? AFFILIATE_CODE_SOURCE.LINK : AFFILIATE_CODE_SOURCE.TYPED,
+  };
+}
+
+/**
+ * The two Dr Green client-create fields (US-A04), present only together and
+ * only for a well-formed code — so a sign-up without a code sends exactly the
+ * payload it sent before this feature. Same conditional-spread shape as
+ * `consentSource` in both payload builders.
+ */
+export function affiliatePayloadFields(input: {
+  affiliateCode?: string | null;
+  affiliateCodeSource?: string | null;
+}): Partial<AffiliateAttribution> {
+  const affiliateCode = normaliseAffiliateCode(input.affiliateCode);
+  const source = input.affiliateCodeSource;
+  if (!affiliateCode) return {};
+  if (source !== AFFILIATE_CODE_SOURCE.LINK && source !== AFFILIATE_CODE_SOURCE.TYPED) return {};
+  return { affiliateCode, affiliateCodeSource: source };
+}
diff --git a/nextjs_space/lib/drgreen-identity.ts b/nextjs_space/lib/drgreen-identity.ts
index a9484b3f..032a7206 100644
--- a/nextjs_space/lib/drgreen-identity.ts
+++ b/nextjs_space/lib/drgreen-identity.ts
@@ -17,6 +17,7 @@
 import { generateDrGreenSignature, callDrGreenAPI } from './drgreen/drgreen-api-client';
 import { DR_GREEN_SA_COUNTRY_CODE } from './verification-mode';
 import { withDrgClientHeader } from './drgreen/client-version';
+import { affiliatePayloadFields } from './affiliate/affiliate-code';
 
 export type IdentityDocumentType = 'ID' | 'PASSPORT' | 'DRIVING_LICENCE';
 
@@ -279,6 +280,10 @@ export interface CreateSaIdClientParams {
   title?: string | null;
   marketingConsent?: boolean;
   consentSource?: string;
+  // BS-A02 (Dr Green US-A04): resolved affiliate code + 'link' | 'typed';
+  // sent only together and only when present (same rule as the KYC payload).
+  affiliateCode?: string | null;
+  affiliateCodeSource?: string | null;
   config: DrGreenIdentityConfig;
   baseUrl?: string;
 }
@@ -326,6 +331,7 @@ export async function createSaIdClient(
     ...(params.title ? { title: params.title } : {}),
     marketingConsent: params.marketingConsent === true,
     ...(params.consentSource ? { consentSource: params.consentSource } : {}),
+    ...affiliatePayloadFields(params),
   };
 
   const response = await callDrGreenAPI<any>(DAPP_CLIENTS_ENDPOINT, {
diff --git a/nextjs_space/lib/drgreen/kyc-client-payload.ts b/nextjs_space/lib/drgreen/kyc-client-payload.ts
index eea1003a..9890d35b 100644
--- a/nextjs_space/lib/drgreen/kyc-client-payload.ts
+++ b/nextjs_space/lib/drgreen/kyc-client-payload.ts
@@ -10,6 +10,7 @@
  */
 import { mapMedicalConditionsForDrGreen } from "@/lib/drgreen/dr-green-mapping";
 import { toAlpha3 } from "@/lib/country-codes";
+import { affiliatePayloadFields } from "@/lib/affiliate/affiliate-code";
 
 const OTHER_CONDITION_KEYS = [
   "lupus",
@@ -67,6 +68,12 @@ export interface KycRegistrationInput {
   title?: string | null;
   marketingConsent?: boolean;
   consentSource?: string;
+
+  // BS-A02 (Dr Green US-A04): the resolved affiliate code and 'link' | 'typed'.
+  // Sent only together and only when present; stripped by the Dr Green DTO
+  // whitelist until the backend accepts them.
+  affiliateCode?: string | null;
+  affiliateCodeSource?: string | null;
 }
 
 /** YYYY-MM-DD; today when the form sent nothing (unchanged legacy default). */
@@ -136,6 +143,7 @@ export function buildKycClientPayload(body: KycRegistrationInput) {
     ...(body.title ? { title: body.title } : {}),
     marketingConsent: body.marketingConsent === true,
     ...(body.consentSource ? { consentSource: body.consentSource } : {}),
+    ...affiliatePayloadFields(body),
 
     medicalRecord: {
       dob: formatDateOfBirth(body.dateOfBirth),
diff --git a/nextjs_space/lib/drgreen/registration-error.ts b/nextjs_space/lib/drgreen/registration-error.ts
new file mode 100644
index 00000000..7d617cc0
--- /dev/null
+++ b/nextjs_space/lib/drgreen/registration-error.ts
@@ -0,0 +1,52 @@
+/**
+ * Customer-facing classification of a Dr Green client-create failure, lifted
+ * out of app/api/consultation/submit/route.ts (BS-A02, to keep that route under
+ * the 800-line lint ceiling). Behaviour-preserving: same checks, same order,
+ * same copy, same status codes as the inline block it replaces.
+ *
+ * Only the stable `failureCode (statusCode)` is ever persisted; the upstream
+ * message can echo submitted values and stays in the (redacted) logs.
+ */
+export interface DrGreenRegistrationFailure {
+  userMessage: string;
+  statusCode: number;
+  failureCode: "PHONE_EXISTS" | "EMAIL_EXISTS" | "CONFLICT" | "BAD_REQUEST" | "UNKNOWN";
+}
+
+export function classifyDrGreenRegistrationError(errorMessage: string | undefined): DrGreenRegistrationFailure {
+  const errorMsg = errorMessage || "";
+
+  if (errorMsg.includes("Phone Number already exists") || errorMsg.includes("phone") && errorMsg.includes("exists")) {
+    return {
+      userMessage: "This phone number is already registered. Please use a different phone number or contact support.",
+      statusCode: 409,
+      failureCode: "PHONE_EXISTS",
+    };
+  }
+  if (errorMsg.includes("email") && errorMsg.includes("exists")) {
+    return {
+      userMessage: "This email address is already registered. Please use a different email or try logging in.",
+      statusCode: 409,
+      failureCode: "EMAIL_EXISTS",
+    };
+  }
+  if (errorMsg.includes("409")) {
+    return {
+      userMessage: "An account with these details already exists. Please use different details or contact support.",
+      statusCode: 409,
+      failureCode: "CONFLICT",
+    };
+  }
+  if (errorMsg.includes("400")) {
+    return {
+      userMessage: "Invalid information provided. Please check your details and try again.",
+      statusCode: 400,
+      failureCode: "BAD_REQUEST",
+    };
+  }
+  return {
+    userMessage: "Registration failed. Please try again or contact support.",
+    statusCode: 500,
+    failureCode: "UNKNOWN",
+  };
+}
diff --git a/nextjs_space/tests/unit/affiliate-attribution.test.ts b/nextjs_space/tests/unit/affiliate-attribution.test.ts
new file mode 100644
index 00000000..2414b1a1
--- /dev/null
+++ b/nextjs_space/tests/unit/affiliate-attribution.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import {
+  AFFILIATE_CODE_SOURCE,
+  affiliatePayloadFields,
+  resolveAffiliateAttribution,
+} from "@/lib/affiliate/affiliate-code";
+import {
+  affiliateCodeField,
+  parseSignUpWithOptionalAffiliateCode,
+} from "@/lib/affiliate/affiliate-code-schema";
+
+/**
+ * BS-A02 — which code is forwarded and how it is attributed. The submitted
+ * field is the only source of the code; the bs_ref cookie decides link vs
+ * typed. A malformed code is a field error, never a failed registration.
+ */
+describe("resolveAffiliateAttribution", () => {
+  it("link-only: the pre-filled code left as it was is attributed to the link", () => {
+    expect(resolveAffiliateAttribution("TEST-CODE", "TEST-CODE")).toEqual({
+      affiliateCode: "TEST-CODE",
+      affiliateCodeSource: AFFILIATE_CODE_SOURCE.LINK,
+    });
+  });
+
+  it("matches the remembered code case-insensitively and forwards it upper-cased", () => {
+    expect(resolveAffiliateAttribution(" test-code ", "TEST-CODE")).toEqual({
+      affiliateCode: "TEST-CODE",
+      affiliateCodeSource: "link",
+    });
+  });
+
+  it("typed-overrides-link: a different code wins and is attributed as typed", () => {
+    expect(resolveAffiliateAttribution("MY-OWN-CODE", "TEST-CODE")).toEqual({
+      affiliateCode: "MY-OWN-CODE",
+      affiliateCodeSource: "typed",
+    });
+  });
+
+  it("a code typed with no landing cookie is typed", () => {
+    expect(resolveAffiliateAttribution("TYPED1", undefined)?.affiliateCodeSource).toBe("typed");
+  });
+
+  it("a cleared field sends nothing, even with a landing cookie", () => {
+    expect(resolveAffiliateAttribution("", "TEST-CODE")).toBeNull();
+    expect(resolveAffiliateAttribution(undefined, "TEST-CODE")).toBeNull();
+  });
+
+  it("a malformed code sends nothing", () => {
+    expect(resolveAffiliateAttribution("AB", "TEST-CODE")).toBeNull();
+    expect(resolveAffiliateAttribution("AB/CD", undefined)).toBeNull();
+  });
+
+  it("a tampered cookie cannot turn a typed code into a link", () => {
+    expect(resolveAffiliateAttribution("TEST-CODE", "test code")?.affiliateCodeSource).toBe("typed");
+  });
+});
+
+describe("affiliatePayloadFields", () => {
+  it("returns both fields together for a code and a known source", () => {
+    expect(affiliatePayloadFields({ affiliateCode: "TEST-CODE", affiliateCodeSource: "link" })).toEqual({
+      affiliateCode: "TEST-CODE",
+      affiliateCodeSource: "link",
+    });
+  });
+
+  it("returns nothing when either is missing or invalid", () => {
+    expect(affiliatePayloadFields({})).toEqual({});
+    expect(affiliatePayloadFields({ affiliateCode: null, affiliateCodeSource: null })).toEqual({});
+    expect(affiliatePayloadFields({ affiliateCode: "TEST-CODE" })).toEqual({});
+    expect(affiliatePayloadFields({ affiliateCode: "TEST-CODE", affiliateCodeSource: "other" })).toEqual({});
+    expect(affiliatePayloadFields({ affiliateCode: "AB", affiliateCodeSource: "typed" })).toEqual({});
+  });
+});
+
+describe("parseSignUpWithOptionalAffiliateCode", () => {
+  const schema = z.object({
+    email: z.string().email(),
+    affiliateCode: affiliateCodeField,
+  });
+
+  it("passes a well-formed code through, trimmed", () => {
+    const { result, affiliateCodeIssue } = parseSignUpWithOptionalAffiliateCode(schema, {
+      email: "a@example.com",
+      affiliateCode: " test-code ",
+    });
+    expect(result.success && result.data.affiliateCode).toBe("test-code");
+    expect(affiliateCodeIssue).toBeNull();
+  });
+
+  it("accepts an empty field and an absent field", () => {
+    expect(parseSignUpWithOptionalAffiliateCode(schema, { email: "a@example.com", affiliateCode: "" }).result.success).toBe(true);
+    expect(parseSignUpWithOptionalAffiliateCode(schema, { email: "a@example.com" }).result.success).toBe(true);
+  });
+
+  it("malformed typed code: a field error on affiliateCode, and the rest still parses", () => {
+    const { result, affiliateCodeIssue } = parseSignUpWithOptionalAffiliateCode(schema, {
+      email: "a@example.com",
+      affiliateCode: "AB",
+    });
+    expect(affiliateCodeIssue?.path[0]).toBe("affiliateCode");
+    expect(result.success).toBe(true);
+    expect(result.success && "affiliateCode" in result.data).toBe(false);
+  });
+
+  it("rejects a code over 20 characters as a field error, not a failed parse", () => {
+    const { result, affiliateCodeIssue } = parseSignUpWithOptionalAffiliateCode(schema, {
+      email: "a@example.com",
+      affiliateCode: "A".repeat(21),
+    });
+    expect(affiliateCodeIssue).not.toBeNull();
+    expect(result.success).toBe(true);
+  });
+
+  it("still fails on any other invalid field, reporting that field", () => {
+    const { result } = parseSignUpWithOptionalAffiliateCode(schema, {
+      email: "not-an-email",
+      affiliateCode: "AB",
+    });
+    expect(result.success).toBe(false);
+    expect(!result.success && result.error.issues.map((i) => i.path[0])).toEqual(["email"]);
+  });
+});
diff --git a/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts b/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
new file mode 100644
index 00000000..b972c720
--- /dev/null
+++ b/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
@@ -0,0 +1,258 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { NextRequest } from "next/server";
+
+/**
+ * BS-A02 on the consultation submit route: the referral code reaches Dr Green
+ * as `affiliateCode` + `affiliateCodeSource` on both client-create paths, a
+ * malformed code never fails the registration, a sign-up without a code sends
+ * exactly what it sent before, and the bs_ref cookie is cleared once the
+ * sign-up succeeds. Same mock harness as consultation-submit-sa-id.test.ts.
+ */
+
+const clerkMock = vi.hoisted(() => ({
+  currentUser: vi.fn(),
+  createUser: vi.fn(),
+  clerkClient: vi.fn(),
+}));
+const prismaMock = vi.hoisted(() => ({
+  users: { findUnique: vi.fn(), create: vi.fn(), update: vi.fn() },
+  consultation_questionnaires: { create: vi.fn(), update: vi.fn() },
+}));
+const libMock = vi.hoisted(() => ({
+  checkRateLimit: vi.fn(),
+  getTenantFromRequest: vi.fn(),
+  resolveTenant: vi.fn(),
+  checkPolicyGate: vi.fn(),
+  getTenantVerificationMode: vi.fn(),
+  isSaIdUploadEnabled: vi.fn(),
+  isSaIdEligibleTenant: vi.fn(),
+  getTenantDrGreenConfig: vi.fn(),
+  callDrGreenAPI: vi.fn(),
+  createSaIdClient: vi.fn(),
+  uploadIdentityDocument: vi.fn(),
+  recordIdDocumentOutcome: vi.fn(),
+  createAuditLog: vi.fn(),
+  triggerWebhook: vi.fn(),
+  mapMedicalConditionsForDrGreen: vi.fn(),
+}));
+
+vi.mock("@clerk/nextjs/server", () => ({
+  currentUser: clerkMock.currentUser,
+  clerkClient: clerkMock.clerkClient,
+}));
+vi.mock("@/lib/db", () => ({ prisma: prismaMock }));
+vi.mock("@/lib/security/rate-limit", () => ({ checkRateLimit: libMock.checkRateLimit }));
+vi.mock("@/lib/tenant/tenant", () => ({ getTenantFromRequest: libMock.getTenantFromRequest }));
+vi.mock("@/lib/tenant/tenant-resolver", () => ({ resolveTenant: libMock.resolveTenant }));
+vi.mock("@/lib/legal/policy-gate", () => ({ checkPolicyGate: libMock.checkPolicyGate }));
+vi.mock("@/lib/verification-mode", () => ({
+  getTenantVerificationMode: libMock.getTenantVerificationMode,
+  isSaIdUploadEnabled: libMock.isSaIdUploadEnabled,
+  isSaIdEligibleTenant: libMock.isSaIdEligibleTenant,
+}));
+vi.mock("@/lib/tenant/tenant-config", () => ({
+  getTenantDrGreenConfig: libMock.getTenantDrGreenConfig,
+}));
+vi.mock("@/lib/drgreen/drgreen-api-client", () => ({ callDrGreenAPI: libMock.callDrGreenAPI }));
+vi.mock("@/lib/drgreen-identity", () => ({
+  createSaIdClient: libMock.createSaIdClient,
+  uploadIdentityDocument: libMock.uploadIdentityDocument,
+}));
+vi.mock("@/lib/verification/id-document-status", () => ({
+  recordIdDocumentOutcome: libMock.recordIdDocumentOutcome,
+}));
+vi.mock("@/lib/drgreen/dr-green-mapping", () => ({
+  mapMedicalConditionsForDrGreen: libMock.mapMedicalConditionsForDrGreen,
+}));
+vi.mock("@/lib/audit-log", () => ({
+  createAuditLog: libMock.createAuditLog,
+  AUDIT_ACTIONS: { CONSULTATION_SUBMITTED: "consultation.submitted" },
+  getClientInfo: () => ({}),
+}));
+vi.mock("@/lib/integrations/webhook", () => ({
+  triggerWebhook: libMock.triggerWebhook,
+  WEBHOOK_EVENTS: { CONSULTATION_SUBMITTED: "consultation.submitted" },
+}));
+
+import { POST } from "@/app/api/consultation/submit/route";
+
+const KYC_TENANT = { id: "tenant-pt", subdomain: "lisboa", countryCode: "PT", settings: {} };
+const ZA_TENANT = {
+  id: "tenant-za",
+  subdomain: "lekker",
+  countryCode: "ZA",
+  settings: { verificationMode: "ID_UPLOAD" },
+};
+
+function kycSubmission(over: Record<string, unknown> = {}) {
+  return {
+    firstName: "Ana",
+    lastName: "Silva",
+    email: "ana-new@example.com",
+    password: "sup3rsecret!",
+    phoneCode: "+351",
+    phoneNumber: "912345678",
+    countryCode: "PT",
+    country: "Portugal",
+    addressLine1: "Rua A 1",
+    city: "Lisboa",
+    state: "Lisboa",
+    postalCode: "1000-001",
+    dateOfBirth: "1990-01-01",
+    gender: "Female",
+    ...over,
+  };
+}
+
+function request(body: unknown, cookie?: string) {
+  return new NextRequest("http://lisboa.localhost/api/consultation/submit", {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      "x-forwarded-for": "203.0.113.10",
+      ...(cookie ? { cookie } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+/** The body the KYC branch posted to Dr Green /dapp/clients. */
+function drGreenBody(): Record<string, unknown> {
+  expect(libMock.callDrGreenAPI).toHaveBeenCalledTimes(1);
+  const [endpoint, opts] = libMock.callDrGreenAPI.mock.calls[0];
+  expect(endpoint).toBe("/dapp/clients");
+  return opts.body;
+}
+
+function setCookieHeader(res: Response): string {
+  return res.headers.get("set-cookie") ?? "";
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  libMock.checkRateLimit.mockResolvedValue({ success: true });
+  libMock.getTenantFromRequest.mockResolvedValue(KYC_TENANT);
+  libMock.checkPolicyGate.mockResolvedValue({ allowed: true });
+  libMock.getTenantVerificationMode.mockReturnValue("KYC");
+  libMock.isSaIdUploadEnabled.mockReturnValue(false);
+  libMock.isSaIdEligibleTenant.mockReturnValue(false);
+  libMock.getTenantDrGreenConfig.mockResolvedValue({
+    apiKey: "k",
+    secretKey: "s",
+    apiUrl: "https://stage/api/v1",
+  });
+  libMock.callDrGreenAPI.mockResolvedValue({ data: { client: { id: "drg-kyc", kycLink: "https://kyc" } } });
+  libMock.createSaIdClient.mockResolvedValue({ clientId: "drg-id" });
+  libMock.uploadIdentityDocument.mockResolvedValue({ id: "doc-1" });
+  libMock.recordIdDocumentOutcome.mockResolvedValue(true);
+  libMock.mapMedicalConditionsForDrGreen.mockReturnValue([]);
+  libMock.createAuditLog.mockResolvedValue(undefined);
+  libMock.triggerWebhook.mockResolvedValue(undefined);
+  clerkMock.currentUser.mockResolvedValue(null);
+  clerkMock.createUser.mockResolvedValue({ id: "clerk_new" });
+  clerkMock.clerkClient.mockResolvedValue({ users: { createUser: clerkMock.createUser } });
+  prismaMock.users.findUnique.mockResolvedValue(null);
+  prismaMock.users.create.mockResolvedValue({ id: "clerk_new" });
+  prismaMock.users.update.mockResolvedValue({});
+  prismaMock.consultation_questionnaires.create.mockResolvedValue({ id: "q-1" });
+  prismaMock.consultation_questionnaires.update.mockResolvedValue({});
+});
+
+describe("consultation submit — affiliate code (BS-A02)", () => {
+  it("link-only: the remembered code, left as pre-filled, is forwarded as 'link'", async () => {
+    const res = await POST(request(kycSubmission({ affiliateCode: "test-code" }), "bs_ref=TEST-CODE"));
+
+    expect(res.status).toBe(200);
+    const body = drGreenBody();
+    expect(body.affiliateCode).toBe("TEST-CODE");
+    expect(body.affiliateCodeSource).toBe("link");
+  });
+
+  it("typed-overrides-link: a different code replaces the remembered one as 'typed'", async () => {
+    const res = await POST(request(kycSubmission({ affiliateCode: "MY-OWN-CODE" }), "bs_ref=TEST-CODE"));
+
+    expect(res.status).toBe(200);
+    const body = drGreenBody();
+    expect(body.affiliateCode).toBe("MY-OWN-CODE");
+    expect(body.affiliateCodeSource).toBe("typed");
+  });
+
+  it("malformed typed code: no 400 — the sign-up completes without a code", async () => {
+    const res = await POST(request(kycSubmission({ affiliateCode: "X!" }), "bs_ref=TEST-CODE"));
+
+    expect(res.status).toBe(200);
+    expect(clerkMock.createUser).toHaveBeenCalledTimes(1);
+    const body = drGreenBody();
+    expect("affiliateCode" in body).toBe(false);
+    expect("affiliateCodeSource" in body).toBe(false);
+  });
+
+  it("a malformed code beside another invalid field reports the other field", async () => {
+    const res = await POST(
+      request(kycSubmission({ affiliateCode: "X!", email: "not-an-email" })),
+    );
+
+    expect(res.status).toBe(400);
+    const error = JSON.stringify(await res.json());
+    expect(error).toMatch(/email/);
+    expect(error).not.toMatch(/affiliateCode/);
+    expect(clerkMock.createUser).not.toHaveBeenCalled();
+  });
+
+  it("absent = unchanged payload: no field, no cookie sends no affiliate keys", async () => {
+    const res = await POST(request(kycSubmission()));
+
+    expect(res.status).toBe(200);
+    const body = drGreenBody();
+    expect("affiliateCode" in body).toBe(false);
+    expect("affiliateCodeSource" in body).toBe(false);
+  });
+
+  it("a cleared field sends nothing even when the landing cookie is set", async () => {
+    await POST(request(kycSubmission({ affiliateCode: "" }), "bs_ref=TEST-CODE"));
+
+    const body = drGreenBody();
+    expect("affiliateCode" in body).toBe(false);
+  });
+
+  it("ID-upload path: createSaIdClient receives the code and its source", async () => {
+    libMock.getTenantFromRequest.mockResolvedValue(ZA_TENANT);
+    libMock.getTenantVerificationMode.mockReturnValue("ID_UPLOAD");
+    libMock.isSaIdUploadEnabled.mockReturnValue(true);
+    libMock.isSaIdEligibleTenant.mockReturnValue(true);
+
+    const res = await POST(
+      request(
+        kycSubmission({
+          countryCode: "ZA",
+          country: "South Africa",
+          affiliateCode: "TEST-CODE",
+        }),
+        "bs_ref=TEST-CODE",
+      ),
+    );
+
+    expect(res.status).toBe(200);
+    expect(libMock.createSaIdClient).toHaveBeenCalledWith(
+      expect.objectContaining({ affiliateCode: "TEST-CODE", affiliateCodeSource: "link" }),
+    );
+  });
+
+  it("clears the bs_ref cookie after a successful sign-up", async () => {
+    const res = await POST(request(kycSubmission({ affiliateCode: "TEST-CODE" }), "bs_ref=TEST-CODE"));
+
+    expect(res.status).toBe(200);
+    const header = setCookieHeader(res);
+    expect(header).toMatch(/bs_ref=;/);
+    expect(header).toMatch(/Max-Age=0/i);
+  });
+
+  it("keeps the cookie when Dr Green refuses the registration (the customer will retry)", async () => {
+    libMock.callDrGreenAPI.mockRejectedValue(new Error("Dr Green API error: 409 Phone Number already exists"));
+
+    const res = await POST(request(kycSubmission({ affiliateCode: "TEST-CODE" }), "bs_ref=TEST-CODE"));
+
+    expect(res.status).toBe(409);
+    expect(setCookieHeader(res)).not.toMatch(/bs_ref/);
+  });
+});
diff --git a/nextjs_space/tests/unit/drgreen-registration-error.test.ts b/nextjs_space/tests/unit/drgreen-registration-error.test.ts
new file mode 100644
index 00000000..7f42fd60
--- /dev/null
+++ b/nextjs_space/tests/unit/drgreen-registration-error.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { classifyDrGreenRegistrationError } from "@/lib/drgreen/registration-error";
+
+/**
+ * Lifted unchanged out of the consultation submit route (BS-A02 line budget).
+ * Pins the order of the checks and the persisted failure codes.
+ */
+describe("classifyDrGreenRegistrationError", () => {
+  it.each([
+    ["Dr Green API error: 409 Phone Number already exists", 409, "PHONE_EXISTS"],
+    ["the phone already exists", 409, "PHONE_EXISTS"],
+    ["the email already exists", 409, "EMAIL_EXISTS"],
+    ["Dr Green API error: 409", 409, "CONFLICT"],
+    ["Dr Green API error: 400 Bad Request", 400, "BAD_REQUEST"],
+    ["socket hang up", 500, "UNKNOWN"],
+    ["", 500, "UNKNOWN"],
+  ])("%j → %i %s", (message, statusCode, failureCode) => {
+    const result = classifyDrGreenRegistrationError(message);
+    expect(result.statusCode).toBe(statusCode);
+    expect(result.failureCode).toBe(failureCode);
+    expect(result.userMessage.length).toBeGreaterThan(0);
+  });
+
+  it("treats an undefined message as unknown", () => {
+    expect(classifyDrGreenRegistrationError(undefined).failureCode).toBe("UNKNOWN");
+  });
+
+  it("checks phone before the bare 409", () => {
+    expect(
+      classifyDrGreenRegistrationError("409 conflict: phone exists").failureCode,
+    ).toBe("PHONE_EXISTS");
+  });
+});
diff --git a/nextjs_space/tests/unit/drgreen-sa-client.test.ts b/nextjs_space/tests/unit/drgreen-sa-client.test.ts
index 8ce15b71..340fcf3f 100644
--- a/nextjs_space/tests/unit/drgreen-sa-client.test.ts
+++ b/nextjs_space/tests/unit/drgreen-sa-client.test.ts
@@ -72,6 +72,28 @@ describe("createSaIdClient", () => {
     expect("consentSource" in body).toBe(false);
   });
 
+  it("forwards affiliateCode and affiliateCodeSource when present (BS-A02)", async () => {
+    (callDrGreenAPI as any).mockResolvedValue({ client: { id: "client-5" } });
+    await createSaIdClient({
+      ...baseParams,
+      affiliateCode: "TEST-CODE",
+      affiliateCodeSource: "typed",
+    });
+    const body = (callDrGreenAPI as any).mock.calls[0][1].body;
+    expect(body.affiliateCode).toBe("TEST-CODE");
+    expect(body.affiliateCodeSource).toBe("typed");
+  });
+
+  it("absent affiliate code = the payload it sent before (BS-A02)", async () => {
+    (callDrGreenAPI as any).mockResolvedValue({ client: { id: "client-6" } });
+    await createSaIdClient(baseParams);
+    await createSaIdClient({ ...baseParams, affiliateCode: undefined, affiliateCodeSource: undefined });
+    const [first, second] = (callDrGreenAPI as any).mock.calls.map((c: any[]) => c[1].body);
+    expect(JSON.stringify(second)).toBe(JSON.stringify(first));
+    expect("affiliateCode" in first).toBe(false);
+    expect("affiliateCodeSource" in first).toBe(false);
+  });
+
   it("throws MISSING_CREDENTIALS when keys are absent", async () => {
     await expect(
       createSaIdClient({ ...baseParams, config: { apiKey: "", secretKey: "" } }),
diff --git a/nextjs_space/tests/unit/kyc-client-payload.test.ts b/nextjs_space/tests/unit/kyc-client-payload.test.ts
index e0a105bc..31ac17da 100644
--- a/nextjs_space/tests/unit/kyc-client-payload.test.ts
+++ b/nextjs_space/tests/unit/kyc-client-payload.test.ts
@@ -105,6 +105,28 @@ describe("buildKycClientPayload", () => {
     expect("consentSource" in plain).toBe(false);
   });
 
+  it("forwards affiliateCode and affiliateCodeSource together when present (BS-A02)", () => {
+    const linked = loose(
+      buildKycClientPayload({ ...base, affiliateCode: "TEST-CODE", affiliateCodeSource: "link" }),
+    );
+    expect(linked.affiliateCode).toBe("TEST-CODE");
+    expect(linked.affiliateCodeSource).toBe("link");
+
+    const typed = loose(
+      buildKycClientPayload({ ...base, affiliateCode: "MY-CODE", affiliateCodeSource: "typed" }),
+    );
+    expect(typed.affiliateCodeSource).toBe("typed");
+  });
+
+  it("absent affiliate code = byte-for-byte the payload it sent before (BS-A02)", () => {
+    const before = buildKycClientPayload(base);
+    const after = buildKycClientPayload({ ...base, affiliateCode: null, affiliateCodeSource: null });
+    expect(after).toEqual(before);
+    expect(JSON.stringify(after)).toBe(JSON.stringify(before));
+    expect("affiliateCode" in after).toBe(false);
+    expect("affiliateCodeSource" in after).toBe(false);
+  });
+
   it("includes clientBusiness only when both type and name are present", () => {
     const withBusiness = buildKycClientPayload({
       ...base,
diff --git a/tasks/prd-drgreen-affiliate-codes.md b/tasks/prd-drgreen-affiliate-codes.md
index cddce9da..814df4f0 100644
--- a/tasks/prd-drgreen-affiliate-codes.md
+++ b/tasks/prd-drgreen-affiliate-codes.md
@@ -40,14 +40,15 @@ Verified in code 2026-10-02 (`origin/main` 79e0b098):
 - [x] Unit test for the matcher (`tests/unit/affiliate-referral-cookie.test.ts`: matcher, normalise, set/skip/clear, essential listing).
 - [ ] Typecheck/lint passes — *pending: run before the PR (see §0).*
 
-### BS-A02: Sign-up field and forwarding
+### BS-A02: Sign-up field and forwarding — ✅ built
 **Acceptance Criteria:**
-- [ ] The consultation contact step and the ID-upload form gain an optional "Referral code (optional)" input, pre-filled from `bs_ref` (read server-side and passed as an initial value), with the helper text "Does not change any price."
-- [ ] `consultationSchema` gains `affiliateCode: z.string().regex(...).max(20).optional()`; the route sets `affiliateCodeSource = 'typed'` when the submitted value differs from the cookie, else `'link'`.
-- [ ] `buildKycClientPayload` and `createSaIdClient` add `affiliateCode` and `affiliateCodeSource` only when present (same shape as `consentSource`).
-- [ ] The cookie is cleared on successful sign-up.
-- [ ] Unit tests: link-only, typed-overrides-link, malformed-typed-rejected-with-field-error (not a 400 on the whole form), absent = unchanged payload.
-- [ ] Typecheck/lint passes; verify in browser after deploy.
+- [x] The consultation contact step and the ID-upload form gain an optional "Referral code (optional)" input, pre-filled from `bs_ref` (read server-side and passed as an initial value), with the helper text "Does not change any price." — *Both forms render `ContactDetailsStep`, so the input lives there once. `consultation/page.tsx` reads `?ref=` on the same request first (middleware sets the cookie on that response, so it is not on the request yet), then the `bs_ref` cookie.*
+- [x] `consultationSchema` gains `affiliateCode: z.string().regex(...).max(20).optional()`; the route sets `affiliateCodeSource = 'typed'` when the submitted value differs from the cookie, else `'link'`. — *`affiliateCodeField` (`lib/affiliate/affiliate-code-schema.ts`) = `"" | z.string().trim().regex(...).max(20)`, optional. The submitted field is the only source of the code: a customer who clears the pre-filled field sends nothing, cookie or not. Comparison is case-insensitive; the code is forwarded upper-cased.*
+- [x] `buildKycClientPayload` and `createSaIdClient` add `affiliateCode` and `affiliateCodeSource` only when present (same shape as `consentSource`). — *Both through `affiliatePayloadFields`: the two keys travel together or not at all.*
+- [x] The cookie is cleared on successful sign-up. — *On the 200 response only; a Dr Green refusal keeps it so the retry still carries the code.*
+- [x] Unit tests: link-only, typed-overrides-link, malformed-typed-rejected-with-field-error (not a 400 on the whole form), absent = unchanged payload. — *`tests/unit/affiliate-attribution.test.ts`, `consultation-submit-affiliate.test.ts` (route, both paths, cookie cleared/kept), `kyc-client-payload.test.ts` and `drgreen-sa-client.test.ts` (absent = byte-identical payload). Malformed: the form shows the error inline on the input and will not advance until it is fixed or cleared; if one still reaches the route, `parseSignUpWithOptionalAffiliateCode` records the field issue, drops the code and lets the sign-up complete (Dr Green FR-2).*
+- [ ] Typecheck/lint passes — *pending (see §0).*
+- [ ] Verify in browser after deploy.
 
 ### BS-A03: Local record
 **Acceptance Criteria:**

From 8524ceba7a5f7271849995ea9dfcf80bad078eb5 Mon Sep 17 00:00:00 2001
From: Gerard Kavanagh <gerard161@gmail.com>
Date: Mon, 5 Oct 2026 11:57:41 +0100
Subject: [PATCH 3/3] feat(signup): keep the Dr Green referral code on users
 for the tenant admin (BS-A03)

users gains nullable affiliateCode + affiliateCodeSource (idempotent
migration 20261005000000_affiliate_code_on_users, applied by migrate
deploy on boot). The consultation route writes them alongside
drGreenClientId once the client is created with that code. The tenant
customers table shows a read-only Referral column and the CSV gains
Referral code / Referral source. GDPR erasure nulls both.
---
 .../app/api/consultation/submit/route.ts      |  1 +
 .../customers/customers-table.tsx             | 28 ++++++++++++++++
 .../app/tenant-admin/customers/page.tsx       |  4 +++
 nextjs_space/lib/gdpr/erasure.ts              |  5 +++
 .../migration.sql                             | 23 +++++++++++++
 nextjs_space/prisma/schema.prisma             |  2 ++
 .../consultation-submit-affiliate.test.ts     | 22 +++++++++++++
 nextjs_space/tests/unit/gdpr-erasure.test.ts  |  3 ++
 tasks/prd-drgreen-affiliate-codes.md          | 32 +++++++++++++++----
 9 files changed, 114 insertions(+), 6 deletions(-)
 create mode 100644 nextjs_space/prisma/migrations/20261005000000_affiliate_code_on_users/migration.sql

diff --git a/nextjs_space/app/api/consultation/submit/route.ts b/nextjs_space/app/api/consultation/submit/route.ts
index 60186828..89a8e47e 100644
--- a/nextjs_space/app/api/consultation/submit/route.ts
+++ b/nextjs_space/app/api/consultation/submit/route.ts
@@ -666,6 +666,7 @@ export async function POST(request: NextRequest) {
           data: {
             drGreenClientId: clientId,
             tenantId,
+            ...(affiliate ?? {}), // BS-A03: the code sent with this client, for reference
             updatedAt: new Date(),
           },
         });
diff --git a/nextjs_space/app/tenant-admin/customers/customers-table.tsx b/nextjs_space/app/tenant-admin/customers/customers-table.tsx
index aaecd952..fec9f324 100644
--- a/nextjs_space/app/tenant-admin/customers/customers-table.tsx
+++ b/nextjs_space/app/tenant-admin/customers/customers-table.tsx
@@ -33,6 +33,10 @@ export interface Customer {
   createdAt: Date;
   /** BS-305: when the customer opted in to marketing; null = no consent. */
   marketingConsentAt?: Date | null;
+  /** BS-A03: Dr Green referral code sent with the sign-up (read-only). */
+  affiliateCode?: string | null;
+  /** BS-A03: link | typed. */
+  affiliateCodeSource?: string | null;
   _count: {
     orders: number;
   };
@@ -182,6 +186,9 @@ export function CustomersTable({
       marketingConsentAt: c.marketingConsentAt
         ? format(new Date(c.marketingConsentAt), "yyyy-MM-dd HH:mm")
         : "",
+      // BS-A03: the Dr Green referral code the customer signed up with.
+      affiliateCode: c.affiliateCode || "",
+      affiliateCodeSource: c.affiliateCodeSource || "",
     }));
 
     const csvHeaders = [
@@ -193,6 +200,8 @@ export function CustomersTable({
       { key: "createdAt" as const, label: "Joined" },
       { key: "marketingConsent" as const, label: "Marketing consent" },
       { key: "marketingConsentAt" as const, label: "Consent given" },
+      { key: "affiliateCode" as const, label: "Referral code" },
+      { key: "affiliateCodeSource" as const, label: "Referral source" },
     ];
 
     await exportToCSV(
@@ -364,6 +373,7 @@ export function CustomersTable({
                   />
                   <th className="text-left hidden sm:table-cell">Status</th>
                   <th className="text-left hidden lg:table-cell">Marketing</th>
+                  <th className="text-left hidden xl:table-cell">Referral</th>
                   <th className="text-center hidden sm:table-cell">
                     <span className="flex items-center justify-center gap-1.5">
                       <ShoppingBag className="h-3.5 w-3.5 text-bs-fg-muted" aria-hidden="true" />
@@ -439,6 +449,24 @@ export function CustomersTable({
                         <RowPill tone="slate">No consent</RowPill>
                       )}
                     </td>
+                    {/* BS-A03: read-only — Dr Green owns the link; this is
+                        the code that travelled with the sign-up. */}
+                    <td className="hidden xl:table-cell">
+                      {customer.affiliateCode ? (
+                        <span
+                          className="font-mono text-sm text-bs-fg"
+                          title={
+                            customer.affiliateCodeSource === "typed"
+                              ? "Typed at sign-up"
+                              : "From the link the customer followed"
+                          }
+                        >
+                          {customer.affiliateCode}
+                        </span>
+                      ) : (
+                        <span className="text-xs text-bs-fg-muted">—</span>
+                      )}
+                    </td>
                     <td className="text-center hidden sm:table-cell">
                       <RowPill tone="gold">{customer._count.orders}</RowPill>
                     </td>
diff --git a/nextjs_space/app/tenant-admin/customers/page.tsx b/nextjs_space/app/tenant-admin/customers/page.tsx
index 08382ce6..af2caa80 100644
--- a/nextjs_space/app/tenant-admin/customers/page.tsx
+++ b/nextjs_space/app/tenant-admin/customers/page.tsx
@@ -166,6 +166,8 @@ export default async function CustomersListPage({
           phone: true,
           createdAt: true,
           marketingConsentAt: true,
+          affiliateCode: true, // BS-A03: read-only reference column + CSV
+          affiliateCodeSource: true,
           _count: {
             select: {
               orders: true,
@@ -284,6 +286,8 @@ export default async function CustomersListPage({
       name: string | null;
       phone: string | null;
       marketingConsentAt: Date | null;
+      affiliateCode: string | null;
+      affiliateCodeSource: string | null;
     }) => {
       const q = questionnaireByEmail.get(customer.email.toLowerCase());
       return {
diff --git a/nextjs_space/lib/gdpr/erasure.ts b/nextjs_space/lib/gdpr/erasure.ts
index 555c74e3..e7cf3717 100644
--- a/nextjs_space/lib/gdpr/erasure.ts
+++ b/nextjs_space/lib/gdpr/erasure.ts
@@ -149,6 +149,8 @@ export function buildAnonymizedUserData(userId: string): {
   title: null;
   marketingConsentAt: null;
   marketingConsentSource: null;
+  affiliateCode: null;
+  affiliateCodeSource: null;
 } {
   return {
     email: `deleted-${userId}@${ERASURE_EMAIL_DOMAIN}`,
@@ -168,6 +170,9 @@ export function buildAnonymizedUserData(userId: string): {
     title: null,
     marketingConsentAt: null,
     marketingConsentSource: null,
+    // BS-A03: acquisition attribution is about the person; it goes too.
+    affiliateCode: null,
+    affiliateCodeSource: null,
   };
 }
 
diff --git a/nextjs_space/prisma/migrations/20261005000000_affiliate_code_on_users/migration.sql b/nextjs_space/prisma/migrations/20261005000000_affiliate_code_on_users/migration.sql
new file mode 100644
index 00000000..ae5de941
--- /dev/null
+++ b/nextjs_space/prisma/migrations/20261005000000_affiliate_code_on_users/migration.sql
@@ -0,0 +1,23 @@
+-- Dr Green affiliate codes (BS-A03) — the referral code a customer signed up
+-- with, kept on users for the tenant admin's reference. See
+-- tasks/prd-drgreen-affiliate-codes.md.
+--
+-- entrypoint.sh runs `prisma migrate deploy` on boot, which only APPLIES
+-- migration files. Hand-written and IDEMPOTENT (IF NOT EXISTS) so it is safe
+-- to (re)apply by hand on any environment before the deploy — PRD-213/220/301
+-- and BS-302 pattern. Additive, nullable, no default, no index, no backfill:
+-- a metadata-only ALTER on Postgres 11+ (no table rewrite, brief lock only).
+--
+-- `affiliateCode` is the upper-cased code forwarded to Dr Green with the
+-- client (Dr Green US-A02 format, max 20). `affiliateCodeSource` is
+-- 'link' (from the bs_ref landing cookie) or 'typed'. Reference only: Dr
+-- Green decides what the code links to, and a code never changes a price.
+--
+-- Canonical form (what `prisma migrate diff --from-schema-datamodel
+-- <pre-story schema> --to-schema-datamodel prisma/schema.prisma --script`
+-- emits for the two `String?` fields):
+-- => ALTER TABLE "users" ADD COLUMN "affiliateCode" TEXT, ADD COLUMN "affiliateCodeSource" TEXT;
+
+ALTER TABLE "users"
+  ADD COLUMN IF NOT EXISTS "affiliateCode" TEXT,
+  ADD COLUMN IF NOT EXISTS "affiliateCodeSource" TEXT;
diff --git a/nextjs_space/prisma/schema.prisma b/nextjs_space/prisma/schema.prisma
index aed9d0aa..138fb793 100644
--- a/nextjs_space/prisma/schema.prisma
+++ b/nextjs_space/prisma/schema.prisma
@@ -986,6 +986,8 @@ model users {
   marketingConsentAt  DateTime? // Email Phase 2 (US-016/US-023): when this customer opted in to marketing. NULL = no consent, never mail them a campaign.
   marketingConsentSource String? // BS-302: which registration path or settings action last changed consent (budstacks-consultation | budstacks-id-upload | budstacks-shop-register | budstacks-settings). Attribution only — marketingConsentAt stays the consent test.
   title               String? // BS-303: salutation the customer chose (Mr | Mrs | Ms | Mx | Dr | Prof); forwarded to Dr Green, never derived from an identity document.
+  affiliateCode       String? // BS-A03: Dr Green referral code forwarded with this customer's sign-up (upper-case, Dr Green US-A02 format). Reference only for the tenant admin — never a price input; Dr Green owns the link.
+  affiliateCodeSource String? // BS-A03: how the code arrived — link (the bs_ref landing cookie) | typed (entered on the form).
   reorderReminderAt   DateTime? // US-028: when the reorder-reminder automation last mailed this customer. NULL = never. The once-per-window guard is a conditional write against this column.
   reorderReminderToken String?  @unique // US-028: this customer's permanent opt-out credential for the reorder reminder. Minted on the first reminder and never rotated — the link lives in an inbox and has to keep working.
   consultations       consultations[]
diff --git a/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts b/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
index b972c720..be3a6477 100644
--- a/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
+++ b/nextjs_space/tests/unit/consultation-submit-affiliate.test.ts
@@ -238,6 +238,28 @@ describe("consultation submit — affiliate code (BS-A02)", () => {
     );
   });
 
+  it("BS-A03: keeps the forwarded code on the local user with the Dr Green client id", async () => {
+    await POST(request(kycSubmission({ affiliateCode: "MY-OWN-CODE" }), "bs_ref=TEST-CODE"));
+
+    const linkWrite = prismaMock.users.update.mock.calls
+      .map((c: any[]) => c[0])
+      .find((arg: any) => arg.data.drGreenClientId === "drg-kyc");
+    expect(linkWrite?.data).toEqual(
+      expect.objectContaining({ affiliateCode: "MY-OWN-CODE", affiliateCodeSource: "typed" }),
+    );
+  });
+
+  it("BS-A03: writes no affiliate columns when there is no code", async () => {
+    await POST(request(kycSubmission()));
+
+    for (const [arg] of prismaMock.users.update.mock.calls) {
+      expect("affiliateCode" in arg.data).toBe(false);
+      expect("affiliateCodeSource" in arg.data).toBe(false);
+    }
+    const created = prismaMock.users.create.mock.calls[0][0].data;
+    expect("affiliateCode" in created).toBe(false);
+  });
+
   it("clears the bs_ref cookie after a successful sign-up", async () => {
     const res = await POST(request(kycSubmission({ affiliateCode: "TEST-CODE" }), "bs_ref=TEST-CODE"));
 
diff --git a/nextjs_space/tests/unit/gdpr-erasure.test.ts b/nextjs_space/tests/unit/gdpr-erasure.test.ts
index 36c660de..295ff85e 100644
--- a/nextjs_space/tests/unit/gdpr-erasure.test.ts
+++ b/nextjs_space/tests/unit/gdpr-erasure.test.ts
@@ -78,6 +78,9 @@ describe("buildAnonymizedUserData", () => {
     expect(data.marketingConsentAt).toBeNull();
     expect(data.marketingConsentSource).toBeNull();
     expect(data.title).toBeNull();
+    // BS-A03: referral attribution goes with the identity.
+    expect(data.affiliateCode).toBeNull();
+    expect(data.affiliateCodeSource).toBeNull();
   });
 
   it("returns a NEW object (no shared reference between calls)", () => {
diff --git a/tasks/prd-drgreen-affiliate-codes.md b/tasks/prd-drgreen-affiliate-codes.md
index 814df4f0..ccb14916 100644
--- a/tasks/prd-drgreen-affiliate-codes.md
+++ b/tasks/prd-drgreen-affiliate-codes.md
@@ -9,9 +9,28 @@
 | **Depends on** | Can ship before Dr Green Phase A: the backend strips unknown DTO fields (`ValidationPipe({ whitelist: true })`), so `affiliateCode` is ignored until the backend accepts it. End-to-end verification needs Dr Green Phase A on staging. |
 | **Estimate** | 2 engineer-days |
 
-## 0. Status
+## 0. Status (2026-10-05)
 
-In progress on `feat/drgreen-affiliate-capture` (from `origin/main` @ `79e0b098`), one commit per story. Typecheck / lint / unit tests have not been run (house rule: nothing executes on the workstation; a PR to `main` is a production deploy). Run before opening the PR: `pnpm -C nextjs_space exec tsc --noEmit && pnpm -C nextjs_space lint && pnpm -C nextjs_space test`.
+All three stories are built on `feat/drgreen-affiliate-capture` (from `origin/main` @ `79e0b098`), one commit per story, with unit tests. Not pushed; no PR. Not yet done, and why:
+
+- **Typecheck / lint / unit tests have not been run.** Nothing executes on the workstation (house rule) and a PR to `main` is a production deploy. Run before opening the PR: `pnpm -C nextjs_space exec tsc --noEmit && pnpm -C nextjs_space lint && pnpm -C nextjs_space test`.
+- **Migration:** `20261005000000_affiliate_code_on_users` is applied by `prisma migrate deploy` on boot; it is idempotent, so it can also be run by hand on the BudStacks database before the deploy.
+- **Browser verification** needs a deployed build (no staging): open `/<anything>?ref=TEST-CODE` on a tenant, check `bs_ref` in devtools (HttpOnly, 30 days), go to `/register`, confirm the field is pre-filled, sign up with a test account, confirm `bs_ref` is gone and the customers table shows `TEST-CODE`.
+- **End-to-end** (the code on the client in the dApp) needs Dr Green Phase A US-A04 on staging; until then Dr Green's DTO whitelist strips both fields and the sign-up behaves as today.
+
+### Decisions taken while building
+
+1. **Cookie set in middleware**, not the layout: Server Components cannot set cookies in Next 14, so a layout would need a client component and a round-trip. Middleware only appends a Set-Cookie to the three storefront page responses (subdomain rewrite, custom-domain rewrite, path-based `/store/<slug>/…`); routing, rewrite targets and CSP are untouched. `www` and SEO redirects keep the query, so the cookie is set on the hop that lands.
+2. **`Secure` in production only**, the same rule the impersonation cookie uses, so plain-http local dev keeps working. Production is always HTTPS.
+3. **Malformed typed code:** the form shows the error inline on the input and does not advance until it is fixed or cleared. If one reaches the route anyway, the code is dropped and the registration completes (Dr Green FR-2); it is never a 400 for the form, and when another field is also invalid that other field's error is the one returned.
+4. **The submitted field is the only source of the code.** The cookie pre-fills it and decides `link` vs `typed`; a customer who clears the field sends nothing.
+5. **Cookie kept when Dr Green refuses the registration** (only the 200 clears it), so a retry still carries the code.
+6. **Route line budget:** the Dr Green error classifier was lifted unchanged to `lib/drgreen/registration-error.ts` (tested); the route is 762 lines.
+7. **Shop register path** (`/api/shop/register`, `ClientOnboarding.tsx`) is not wired: no page renders it (phase-alignment §0 item 4).
+
+### Open for Gerard
+
+- **Is `bs_ref` "strictly necessary"?** The PRD files it under essential cookies. A cookie whose purpose is attributing a sign-up to a marketer is arguably not needed for the service the visitor asked for (ICO guidance on PECR reg. 6 treats affiliate/referral tracking as non-essential). If legal disagrees with the PRD, the fix is one condition in `withReferralCookie` (only set when the consent cookie allows it) and moving the `STOREFRONT_COOKIES` entry. The operator cookie notice text (`lib/legal/documents/cookies-template.ts`) does not list individual cookies and was not changed.
 
 ## 1. Introduction / Overview
 
@@ -50,11 +69,12 @@ Verified in code 2026-10-02 (`origin/main` 79e0b098):
 - [ ] Typecheck/lint passes — *pending (see §0).*
 - [ ] Verify in browser after deploy.
 
-### BS-A03: Local record
+### BS-A03: Local record — ✅ built
 **Acceptance Criteria:**
-- [ ] `users` gains `affiliateCode String?` and `affiliateCodeSource String?` (hand-run SQL per `prisma/schema.prisma:573` convention; additive).
-- [ ] Tenant-admin customers table shows the code as a read-only column and the CSV includes it.
-- [ ] Verify in browser; typecheck/lint passes.
+- [x] `users` gains `affiliateCode String?` and `affiliateCodeSource String?` (hand-run SQL per `prisma/schema.prisma:573` convention; additive). — *`prisma/migrations/20261005000000_affiliate_code_on_users/migration.sql`, idempotent (`ADD COLUMN IF NOT EXISTS`), the BS-302 pattern: `entrypoint.sh` applies it with `prisma migrate deploy` on boot, and it is safe to run by hand first. Written on the same `users.update` that stores `drGreenClientId`, i.e. only when the Dr Green client was created with that code; never cleared by a later submission without one. GDPR erasure (`buildAnonymizedUserData`) nulls both.*
+- [x] Tenant-admin customers table shows the code as a read-only column and the CSV includes it. — *"Referral" column (xl screens and up; hover shows link/typed); CSV gains "Referral code" and "Referral source".*
+- [ ] Verify in browser.
+- [ ] Typecheck/lint passes — *pending (see §0).*
 
 ## 4. Functional requirements