diff --git a/app/(app)/projects/[id]/stats/careers/careers-install.tsx b/app/(app)/projects/[id]/stats/careers/careers-install.tsx
index a49d0e7..29fe553 100644
--- a/app/(app)/projects/[id]/stats/careers/careers-install.tsx
+++ b/app/(app)/projects/[id]/stats/careers/careers-install.tsx
@@ -3,9 +3,14 @@
 // "Add a real /careers page to my repo" — the crawlable counterpart to the
 // drop-in widget.
 //
-// Two steps on purpose. Detection is read-only and tells the user what we
-// found before anything is written; only the second button opens a PR. People
-// are reasonably wary of a button that commits to their repo sight unseen.
+// Two steps on purpose. Scanning is read-only and shows what we found before
+// anything is written; only the second button opens a PR. People are reasonably
+// wary of a button that commits to their repo sight unseen.
+//
+// The scan lists every place the route could go, ranked, the way the stats
+// tracker installer does. Asking someone to type their own monorepo path and
+// answering a miss with "not supported" was the wrong shape: in a monorepo the
+// site is rarely at the root, and a wrong guess looked like a missing feature.
 
 import { useState } from "react";
 import type { RepoOption } from "@/lib/github/repo-options";
@@ -17,6 +22,11 @@ interface Detected {
   evidence: string;
 }
 
+interface Candidate extends Detected {
+  score: number;
+  existingPath?: string;
+}
+
 interface InstallResult {
   status: "opened" | "noop";
   prUrl?: string;
@@ -45,12 +55,25 @@ export function CareersInstall({
   const [rootPath, setRootPath] = useState("");
   const [busy, setBusy] = useState(false);
   const [error, setError] = useState<string | null>(null);
-  const [detected, setDetected] = useState<Detected | null | undefined>(undefined);
+  const [candidates, setCandidates] = useState<Candidate[] | undefined>(undefined);
+  const [truncated, setTruncated] = useState(false);
+  const [chosenDir, setChosenDir] = useState("");
+  const [manualDir, setManualDir] = useState("");
   const [result, setResult] = useState<InstallResult | null>(null);
 
   const selected = repos.find((r) => r.full_name === repo);
+  const chosen = candidates?.find((c) => c.dir === chosenDir);
+  const targetDir = chosenDir || manualDir.trim();
+
+  /** Any change to repo or root invalidates a scan taken against the old one. */
+  function resetScan() {
+    setCandidates(undefined);
+    setChosenDir("");
+    setResult(null);
+    setError(null);
+  }
 
-  async function call(mode: "detect" | "submit") {
+  async function call(mode: "candidates" | "submit") {
     if (!selected) return;
     const [owner, name] = selected.full_name.split("/");
     setBusy(true);
@@ -65,6 +88,7 @@ export function CareersInstall({
           installation_id: selected.installation_id,
           default_branch: selected.default_branch ?? undefined,
           root_path: rootPath.trim() || undefined,
+          target_dir: mode === "submit" ? targetDir || undefined : undefined,
           mode,
         }),
       });
@@ -73,8 +97,16 @@ export function CareersInstall({
         setError(payload?.error ?? "Something went wrong.");
         return;
       }
-      if (mode === "detect") setDetected(payload.data.detected);
-      else setResult(payload.data);
+      if (mode === "candidates") {
+        const found: Candidate[] = payload.data.candidates ?? [];
+        setCandidates(found);
+        setTruncated(Boolean(payload.data.truncated));
+        // Preselect the best match; it is right in the common case and the
+        // list is there when it isn't.
+        setChosenDir(found[0]?.dir ?? "");
+      } else {
+        setResult(payload.data);
+      }
     } catch {
       setError("Could not reach GitHub. Try again.");
     } finally {
@@ -119,8 +151,7 @@ export function CareersInstall({
               value={repo}
               onChange={(e) => {
                 setRepo(e.target.value);
-                setDetected(undefined);
-                setResult(null);
+                resetScan();
               }}
               className="w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2 text-sm"
             >
@@ -135,34 +166,102 @@ export function CareersInstall({
 
           <div className="space-y-1">
             <label className="text-xs text-[var(--color-muted)]">
-              Site subdirectory (optional, for monorepos)
+              Limit the scan to a subdirectory (optional)
             </label>
             <input
               type="text"
               value={rootPath}
               onChange={(e) => {
                 setRootPath(e.target.value);
-                setDetected(undefined);
+                resetScan();
               }}
-              placeholder="apps/web — leave blank for the repo root"
+              placeholder="apps/web — leave blank to scan the whole repo"
               className="w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2 text-sm"
             />
           </div>
 
           {error && <p className="text-sm text-[var(--color-danger,#dc2626)]">{error}</p>}
 
-          {detected === null && (
+          {candidates?.length === 0 && (
             <p className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2 text-sm text-[var(--color-muted)]">
-              No Next.js App Router or Astro site found there. Nothing was changed — your
-              board still works through the tracker snippet, it just renders client-side.
+              No Next.js App Router or Astro site found in this repo. Nothing was changed —
+              your board still works through the tracker snippet, it just renders
+              client-side. If the site lives somewhere unusual, enter the directory holding{" "}
+              <code className="font-mono">layout.tsx</code> below.
             </p>
           )}
 
-          {detected && (
+          {!!candidates?.length && (
+            <div className="space-y-1">
+              <p className="text-xs text-[var(--color-muted)]">
+                {candidates.length === 1
+                  ? "Found one place the page can go:"
+                  : `Found ${candidates.length} places the page can go, best match first:`}
+              </p>
+              <ul className="max-h-60 divide-y divide-[var(--color-border)] overflow-y-auto rounded-md border border-[var(--color-border)]">
+                {candidates.map((c) => (
+                  <li key={c.dir}>
+                    <label className="flex cursor-pointer items-start gap-3 p-2">
+                      <input
+                        type="radio"
+                        name="careers-dir"
+                        className="mt-1"
+                        checked={chosenDir === c.dir}
+                        onChange={() => {
+                          setChosenDir(c.dir);
+                          setManualDir("");
+                          setResult(null);
+                        }}
+                      />
+                      <span className="min-w-0">
+                        <span className="block truncate font-mono text-sm">{c.dir}</span>
+                        <span className="block text-xs text-[var(--color-muted)]">
+                          {FRAMEWORK_LABEL[c.framework]} · from{" "}
+                          <code className="font-mono">{c.evidence}</code>
+                        </span>
+                        {c.existingPath && (
+                          <span className="block text-xs text-[var(--color-muted)]">
+                            Already has <code className="font-mono">{c.existingPath}</code> —
+                            CrawlProof will leave it alone.
+                          </span>
+                        )}
+                      </span>
+                    </label>
+                  </li>
+                ))}
+              </ul>
+              {truncated && (
+                <p className="text-xs text-[var(--color-muted)]">
+                  This repo is large enough that GitHub truncated the file listing, so the
+                  scan may have missed a location. Enter it below if it isn&apos;t here.
+                </p>
+              )}
+            </div>
+          )}
+
+          {candidates !== undefined && (
+            <div className="space-y-1">
+              <label className="text-xs text-[var(--color-muted)]">
+                Or enter the route directory yourself
+              </label>
+              <input
+                type="text"
+                value={manualDir}
+                onChange={(e) => {
+                  setManualDir(e.target.value);
+                  setChosenDir("");
+                  setResult(null);
+                }}
+                placeholder="apps/web/src/app — the directory containing layout.tsx"
+                className="w-full rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2 font-mono text-sm"
+              />
+            </div>
+          )}
+
+          {chosen && (
             <p className="rounded-md border border-[var(--color-border)] bg-[var(--color-bg)] px-3 py-2 text-sm text-[var(--color-muted)]">
-              Found <strong>{FRAMEWORK_LABEL[detected.framework]}</strong> from{" "}
-              <code className="font-mono">{detected.evidence}</code>. The PR will add the
-              page under <code className="font-mono">{detected.dir}</code>.
+              The PR will add the page under <code className="font-mono">{chosen.dir}</code>{" "}
+              as {FRAMEWORK_LABEL[chosen.framework]}.
             </p>
           )}
 
@@ -185,16 +284,16 @@ export function CareersInstall({
           <div className="flex flex-wrap gap-2">
             <button
               type="button"
-              onClick={() => call("detect")}
+              onClick={() => call("candidates")}
               disabled={busy || !selected}
               className="btn btn-secondary text-sm"
             >
-              {busy ? "Checking…" : "Check repo"}
+              {busy ? "Scanning…" : candidates === undefined ? "Scan repo" : "Rescan"}
             </button>
             <button
               type="button"
               onClick={() => call("submit")}
-              disabled={busy || !selected || detected === null || !!result}
+              disabled={busy || !selected || !targetDir || !!result}
               className="btn btn-primary text-sm"
             >
               {busy ? "Working…" : "Open pull request"}
diff --git a/app/api/projects/[id]/github/install-careers/route.ts b/app/api/projects/[id]/github/install-careers/route.ts
index 6648949..083c84b 100644
--- a/app/api/projects/[id]/github/install-careers/route.ts
+++ b/app/api/projects/[id]/github/install-careers/route.ts
@@ -1,8 +1,12 @@
 // POST /api/projects/[id]/github/install-careers
-// Body: { owner, repo, installation_id, root_path?, default_branch?, mode? }
+// Body: { owner, repo, installation_id, root_path?, target_dir?, default_branch?, mode? }
 //
-// mode=detect  → report the framework we'd write for, without touching the repo.
-// mode=submit  → open the PR (default).
+// mode=candidates → scan the repo and rank every place a careers route could
+//                   go. Read-only, no PR, no run row.
+// mode=detect     → report the framework we'd write for at one root, without
+//                   touching the repo.
+// mode=submit     → open the PR (default). Honours target_dir when the user
+//                   picked a location, after re-verifying it server-side.
 //
 // Auth mirrors install-tracker: a signed-in user, with access to the project,
 // using an installation connected to their own account.
@@ -13,7 +17,12 @@ import { createClient } from "@/lib/supabase/server";
 import { serviceClient } from "@/lib/supabase/service";
 import { requireProjectAccess } from "@/lib/lx/currentSite";
 import { getOrMintInstallationToken } from "@/lib/github/installations";
-import { detectFramework, installCareersPage } from "@/lib/github/install-careers";
+import {
+  detectFramework,
+  findCareersCandidates,
+  installCareersPage,
+  verifyCareersDir,
+} from "@/lib/github/install-careers";
 import { getRepo } from "@/lib/github/repos";
 
 export const runtime = "nodejs";
@@ -23,8 +32,9 @@ const bodySchema = z.object({
   repo: z.string().min(1),
   installation_id: z.number().int().positive(),
   root_path: z.string().max(500).optional(),
+  target_dir: z.string().max(500).optional(),
   default_branch: z.string().max(200).optional(),
-  mode: z.enum(["detect", "submit"]).optional(),
+  mode: z.enum(["candidates", "detect", "submit"]).optional(),
 });
 
 export async function POST(
@@ -79,6 +89,23 @@ export async function POST(
 
   const mode = body.mode ?? "submit";
 
+  // Read-only scan: no PR, no run row.
+  if (mode === "candidates") {
+    try {
+      const token = await getOrMintInstallationToken(body.installation_id);
+      const { candidates, truncated } = await findCareersCandidates({
+        token,
+        owner: body.owner,
+        repo: body.repo,
+        rootPath: body.root_path,
+      });
+      return NextResponse.json({ data: { candidates, truncated } });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return NextResponse.json({ error: msg }, { status: 500 });
+    }
+  }
+
   if (mode === "detect") {
     try {
       const token = await getOrMintInstallationToken(body.installation_id);
@@ -123,12 +150,36 @@ export async function POST(
 
   try {
     const token = await getOrMintInstallationToken(body.installation_id);
+
+    // A directory chosen in the browser is never trusted on its own — re-probe
+    // for the framework marker so we still only write where we can see a site.
+    let detected;
+    if (body.target_dir?.trim()) {
+      const repoMeta = await getRepo({ token, owner: body.owner, repo: body.repo });
+      detected =
+        (await verifyCareersDir({
+          token,
+          owner: body.owner,
+          repo: body.repo,
+          ref: repoMeta.default_branch,
+          dir: body.target_dir.trim(),
+        })) ?? undefined;
+      if (!detected) {
+        const msg =
+          `No Next.js App Router or Astro site at ${body.target_dir.trim()}. ` +
+          "Pick one of the scanned locations, or point at the directory holding layout.tsx.";
+        await finalize({ status: "failed", error: msg });
+        return NextResponse.json({ error: msg }, { status: 422 });
+      }
+    }
+
     const result = await installCareersPage({
       token,
       owner: body.owner,
       repo: body.repo,
       projectId,
       rootPath: body.root_path,
+      detected,
     });
     await finalize({
       status: result.status,
diff --git a/lib/github/install-careers.ts b/lib/github/install-careers.ts
index 20b69df..94d3ca8 100644
--- a/lib/github/install-careers.ts
+++ b/lib/github/install-careers.ts
@@ -20,7 +20,14 @@ import {
   conflictingPaths,
   type CareersFramework,
 } from "@/lib/careers/page-templates";
-import { createBranch, getFileContent, getRepo, openPullRequest, putFile } from "./repos";
+import {
+  createBranch,
+  getFileContent,
+  getRepo,
+  listRepoTree,
+  openPullRequest,
+  putFile,
+} from "./repos";
 
 const ORIGIN = env.siteUrl.replace(/\/+$/, "");
 const BRANCH_PREFIX = "crawlproof/careers-page";
@@ -120,6 +127,238 @@ export async function detectFramework(input: {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Candidate discovery
+//
+// detectFramework() answers "is there a site exactly here?", which is the wrong
+// question for a monorepo: the customer has to already know their own route
+// directory and type it in, and one wrong guess reads as "CrawlProof doesn't
+// support my repo". The tracker installer solved this by scanning and ranking
+// (findInstallCandidates); this is the same idea for careers routes. One
+// recursive tree request gets the whole file list, so the UI can offer real
+// locations instead of asking anyone to guess.
+// ---------------------------------------------------------------------------
+
+/** `app/layout.tsx` at any depth — a Next App Router root layout, not a nested one. */
+const NEXT_ROOT_LAYOUT = /(?:^|\/)app\/layout\.(tsx|jsx|js)$/;
+/** An Astro project marker at any depth. */
+const ASTRO_CONFIG = /(?:^|\/)astro\.config\.(mjs|ts|js|cjs)$/;
+
+/** Paths we never want to offer: vendored code and tooling scratch space. */
+const IGNORED_PATH = /(^|\/)(node_modules|\.git|\.next|dist|build|out|coverage|vendor)(\/|$)/;
+
+export interface CareersCandidate extends DetectedFramework {
+  /** Higher is better; the UI shows the list best-first. */
+  score: number;
+  /** Set when a careers page already lives here. The UI offers it but warns. */
+  existingPath?: string;
+}
+
+/**
+ * Rank a route directory. Tuned like rankCandidatePath in install-tracker: the
+ * production app in a monorepo lives under apps/* or sites/*, and example or
+ * fixture directories are never what someone wants a public careers page in.
+ */
+function rankCareersDir(dir: string, repoName: string): number {
+  let score = 0;
+  if (
+    /(^|\/)(boilerplates?|examples?|templates?|samples?|fixtures?|__tests__|tests?|spec|stories|playground|sandbox|demo)(\/|$)/i.test(
+      dir,
+    )
+  ) {
+    score -= 100;
+  }
+  if (/(^|\/)(docs?|documentation)(\/|$)/i.test(dir)) score -= 20;
+  if (/(^|\/)apps\//i.test(dir)) score += 30;
+  if (/(^|\/)sites\//i.test(dir)) score += 30;
+  if (/(^|\/)(web|www|site|frontend|marketing)(\/|$)/i.test(dir)) score += 20;
+  // A repo-name match disambiguates sites/acme.com from sites/scratch. Skip
+  // very short names, where the substring hit would be noise.
+  if (repoName.length >= 3 && dir.toLowerCase().includes(repoName.toLowerCase())) {
+    score += 25;
+  }
+  // The single-app repo: the route dir sits right at the top.
+  if (dir === "app" || dir === "src/app" || dir === "src/pages") score += 50;
+  // Shorter paths are closer to the canonical site.
+  score -= dir.length * 0.05;
+  return score;
+}
+
+/** Turn a repo file list into the set of places a careers route could go. */
+export function careersCandidatesFromTree(
+  files: string[],
+  opts: { repoName: string; rootPath?: string },
+): CareersCandidate[] {
+  const root = (opts.rootPath ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+  const inScope = (path: string) =>
+    !IGNORED_PATH.test(path) && (!root || path === root || path.startsWith(`${root}/`));
+
+  const byDir = new Map<string, CareersCandidate>();
+
+  for (const path of files) {
+    if (!inScope(path)) continue;
+
+    if (ASTRO_CONFIG.test(path)) {
+      const siteRoot = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) : "";
+      const dir = siteRoot ? `${siteRoot}/src/pages` : "src/pages";
+      if (!byDir.has(dir)) {
+        byDir.set(dir, {
+          framework: "astro",
+          dir,
+          typescript: true, // Astro frontmatter is TypeScript regardless.
+          evidence: path,
+          score: rankCareersDir(dir, opts.repoName),
+        });
+      }
+      continue;
+    }
+
+    const next = NEXT_ROOT_LAYOUT.exec(path);
+    if (next) {
+      const dir = path.replace(/\/layout\.[a-z]+$/, "");
+      if (!byDir.has(dir)) {
+        byDir.set(dir, {
+          framework: "next-app",
+          dir,
+          typescript: next[1] === "tsx",
+          evidence: path,
+          score: rankCareersDir(dir, opts.repoName),
+        });
+      }
+    }
+  }
+
+  // Flag the ones that already have a page, rather than hiding them — "you
+  // already have this" is a more useful answer than an empty list.
+  const present = new Set(files);
+  const candidates = [...byDir.values()].map((c) => {
+    const clash = conflictingPaths(c.framework, c.dir).find((p) => present.has(p));
+    return clash ? { ...c, existingPath: clash } : c;
+  });
+
+  candidates.sort((a, b) => b.score - a.score || a.dir.localeCompare(b.dir));
+  return candidates;
+}
+
+/**
+ * Scan a repo for every place a careers route could go, best first.
+ *
+ * Falls back to the single-root probe when the tree is unavailable or GitHub
+ * truncated it, so a huge repo degrades to the old behaviour instead of
+ * claiming the site doesn't exist.
+ */
+export async function findCareersCandidates(input: {
+  token: string;
+  owner: string;
+  repo: string;
+  rootPath?: string;
+  ref?: string;
+}): Promise<{ candidates: CareersCandidate[]; truncated: boolean }> {
+  let ref = input.ref;
+  if (!ref) {
+    const repoMeta = await getRepo({
+      token: input.token,
+      owner: input.owner,
+      repo: input.repo,
+    });
+    ref = repoMeta.default_branch;
+  }
+
+  let tree: Awaited<ReturnType<typeof listRepoTree>> = null;
+  try {
+    tree = await listRepoTree({
+      token: input.token,
+      owner: input.owner,
+      repo: input.repo,
+      ref,
+    });
+  } catch {
+    // Tree is the fast path, not the only path.
+  }
+
+  const candidates = tree
+    ? careersCandidatesFromTree(tree.files, {
+        repoName: input.repo,
+        rootPath: input.rootPath,
+      })
+    : [];
+
+  // Union with the direct probe. It costs a few contents calls and it is the
+  // only thing that still works on a truncated tree.
+  if (!tree || tree.truncated || candidates.length === 0) {
+    const detected = await detectFramework({
+      token: input.token,
+      owner: input.owner,
+      repo: input.repo,
+      ref,
+      rootPath: input.rootPath,
+    });
+    if (detected && !candidates.some((c) => c.dir === detected.dir)) {
+      candidates.push({
+        ...detected,
+        score: rankCareersDir(detected.dir, input.repo),
+      });
+      candidates.sort((a, b) => b.score - a.score || a.dir.localeCompare(b.dir));
+    }
+  }
+
+  return { candidates, truncated: Boolean(tree?.truncated) };
+}
+
+/**
+ * Confirm a directory really is what it claims before writing to it.
+ *
+ * The picker and the manual-path box both hand us a directory chosen in the
+ * browser; trusting it would let a stray value drop a page into an arbitrary
+ * folder. Re-probing for the framework marker keeps the installer's promise
+ * that it only writes where it positively identified a site.
+ */
+export async function verifyCareersDir(input: {
+  token: string;
+  owner: string;
+  repo: string;
+  ref: string;
+  dir: string;
+}): Promise<DetectedFramework | null> {
+  const dir = input.dir.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (!dir || dir.split("/").includes("..")) return null;
+
+  const probe = async (path: string) =>
+    getFileContent({
+      token: input.token,
+      owner: input.owner,
+      repo: input.repo,
+      path,
+      ref: input.ref,
+    });
+
+  // "…/src/pages" is Astro's route directory; its marker is the config file
+  // that sits two levels up.
+  if (/(^|\/)src\/pages$/.test(dir)) {
+    const siteRoot = dir.replace(/(^|\/)src\/pages$/, "").replace(/\/+$/, "");
+    for (const config of ["astro.config.mjs", "astro.config.ts", "astro.config.js", "astro.config.cjs"]) {
+      const path = siteRoot ? `${siteRoot}/${config}` : config;
+      if (await probe(path)) {
+        return { framework: "astro", dir, typescript: true, evidence: path };
+      }
+    }
+    return null;
+  }
+
+  for (const [ext, typescript] of [
+    ["tsx", true],
+    ["jsx", false],
+    ["js", false],
+  ] as Array<[string, boolean]>) {
+    const path = `${dir}/layout.${ext}`;
+    if (await probe(path)) {
+      return { framework: "next-app", dir, typescript, evidence: path };
+    }
+  }
+
+  return null;
+}
+
 const UNSUPPORTED =
   "Could not find a Next.js App Router or Astro site in this repo, so nothing was changed. " +
   "Your careers board still works through the tracker snippet — it just renders client-side.";
diff --git a/lib/github/repos.ts b/lib/github/repos.ts
index e231ca7..2122969 100644
--- a/lib/github/repos.ts
+++ b/lib/github/repos.ts
@@ -183,6 +183,50 @@ export interface DirectoryEntry {
   size?: number;
 }
 
+export interface RepoTree {
+  /** Every blob path in the repo, repo-relative. */
+  files: string[];
+  /**
+   * GitHub caps the recursive tree response. When true the list is a
+   * prefix of the repo, so callers should treat a miss as "unknown"
+   * rather than "absent" and keep their canonical probes.
+   */
+  truncated: boolean;
+}
+
+/**
+ * List every file in a repo in one request.
+ *
+ * The contents API can only answer "does this exact path exist?", which is
+ * fine when you already know the layout and useless when you don't. The git
+ * trees API returns the whole file list at once, so a picker can offer real
+ * locations instead of asking the customer to guess their own directory
+ * structure. One request also beats N probes on rate limit.
+ */
+export async function listRepoTree(input: {
+  token: string;
+  owner: string;
+  repo: string;
+  ref: string;
+}): Promise<RepoTree | null> {
+  const res = await gh(
+    `/repos/${input.owner}/${input.repo}/git/trees/${encodeURIComponent(input.ref)}?recursive=1`,
+    { token: input.token },
+  );
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`listRepoTree ${res.status}: ${await res.text()}`);
+  }
+  const body = (await res.json()) as {
+    tree?: Array<{ path: string; type: string }>;
+    truncated?: boolean;
+  };
+  return {
+    files: (body.tree ?? []).filter((e) => e.type === "blob").map((e) => e.path),
+    truncated: Boolean(body.truncated),
+  };
+}
+
 /**
  * List the immediate children of a directory in a repo. Returns null
  * for paths that don't exist (or aren't directories). Use empty string
diff --git a/tests/careers-install-pr.test.ts b/tests/careers-install-pr.test.ts
index edf70c0..b508d75 100644
--- a/tests/careers-install-pr.test.ts
+++ b/tests/careers-install-pr.test.ts
@@ -20,6 +20,7 @@ const github = vi.hoisted(() => {
       return { path, sha: `sha-${path}`, content };
     }),
     searchRepoCode: vi.fn(async () => []),
+    listRepoTree: vi.fn(async () => ({ files: [...files.keys()], truncated: false })),
     createBranch: vi.fn(async (_input: { newBranch: string; fromBranch: string }) => ({
       created: true,
     })),
@@ -41,12 +42,19 @@ vi.mock("@/lib/github/repos", () => ({
   getRepo: github.getRepo,
   getFileContent: github.getFileContent,
   searchRepoCode: github.searchRepoCode,
+  listRepoTree: github.listRepoTree,
   createBranch: github.createBranch,
   putFile: github.putFile,
   openPullRequest: github.openPullRequest,
 }));
 
-import { detectFramework, installCareersPage } from "@/lib/github/install-careers";
+import {
+  careersCandidatesFromTree,
+  detectFramework,
+  findCareersCandidates,
+  installCareersPage,
+  verifyCareersDir,
+} from "@/lib/github/install-careers";
 
 const BASE = { token: "token", owner: "owner", repo: "repo" };
 const PROJECT = "af9ab953-caa6-4a2b-a306-42fb4eac4630";
@@ -56,6 +64,7 @@ beforeEach(() => {
   for (const fn of [
     github.getRepo,
     github.getFileContent,
+    github.listRepoTree,
     github.createBranch,
     github.putFile,
     github.openPullRequest,
@@ -203,3 +212,163 @@ describe("installCareersPage", () => {
     expect(pr.base).toBe("trunk");
   });
 });
+
+// The scan is the difference between "we don't support your repo" and "pick
+// one of these". Most of the interesting behaviour is in the pure tree->list
+// step, so that gets tested without any network mocking at all.
+describe("careersCandidatesFromTree", () => {
+  it("finds every app dir in a monorepo, not just the root", () => {
+    const found = careersCandidatesFromTree(
+      [
+        "package.json",
+        "apps/web/src/app/layout.tsx",
+        "apps/admin/app/layout.tsx",
+        "packages/ui/package.json",
+      ],
+      { repoName: "acme" },
+    );
+    expect(found.map((c) => c.dir).sort()).toEqual([
+      "apps/admin/app",
+      "apps/web/src/app",
+    ]);
+  });
+
+  it("ranks the real app above examples and fixtures", () => {
+    const found = careersCandidatesFromTree(
+      ["examples/starter/app/layout.tsx", "apps/web/app/layout.tsx"],
+      { repoName: "acme" },
+    );
+    expect(found[0].dir).toBe("apps/web/app");
+    expect(found[1].dir).toBe("examples/starter/app");
+  });
+
+  it("puts a root-level app dir first in a single-app repo", () => {
+    const found = careersCandidatesFromTree(
+      ["apps/legacy/app/layout.tsx", "app/layout.tsx"],
+      { repoName: "acme" },
+    );
+    expect(found[0].dir).toBe("app");
+  });
+
+  it("maps an Astro config to its pages directory", () => {
+    const found = careersCandidatesFromTree(
+      ["sites/blog/astro.config.mjs", "sites/blog/src/pages/index.astro"],
+      { repoName: "acme" },
+    );
+    expect(found).toHaveLength(1);
+    expect(found[0]).toMatchObject({
+      framework: "astro",
+      dir: "sites/blog/src/pages",
+      evidence: "sites/blog/astro.config.mjs",
+      typescript: true,
+    });
+  });
+
+  it("ignores nested route layouts — only the root layout marks an app dir", () => {
+    const found = careersCandidatesFromTree(
+      ["app/layout.tsx", "app/blog/layout.tsx", "app/(marketing)/layout.tsx"],
+      { repoName: "acme" },
+    );
+    expect(found.map((c) => c.dir)).toEqual(["app"]);
+  });
+
+  it("skips vendored and build output", () => {
+    const found = careersCandidatesFromTree(
+      ["node_modules/pkg/app/layout.tsx", ".next/app/layout.tsx", "dist/app/layout.tsx"],
+      { repoName: "acme" },
+    );
+    expect(found).toEqual([]);
+  });
+
+  it("honours a rootPath filter", () => {
+    const found = careersCandidatesFromTree(
+      ["apps/web/app/layout.tsx", "apps/admin/app/layout.tsx"],
+      { repoName: "acme", rootPath: "apps/admin" },
+    );
+    expect(found.map((c) => c.dir)).toEqual(["apps/admin/app"]);
+  });
+
+  it("surfaces a location that already has a careers page instead of hiding it", () => {
+    const found = careersCandidatesFromTree(
+      ["app/layout.tsx", "app/careers/page.tsx"],
+      { repoName: "acme" },
+    );
+    expect(found[0].existingPath).toBe("app/careers/page.tsx");
+  });
+
+  it("infers JavaScript from a .jsx layout", () => {
+    const found = careersCandidatesFromTree(["app/layout.jsx"], { repoName: "acme" });
+    expect(found[0]).toMatchObject({ typescript: false, framework: "next-app" });
+  });
+});
+
+describe("findCareersCandidates", () => {
+  it("scans the whole repo in one tree call", async () => {
+    github.files.set("apps/web/src/app/layout.tsx", "export default function L() {}");
+    const { candidates, truncated } = await findCareersCandidates({ ...BASE });
+    expect(candidates.map((c) => c.dir)).toEqual(["apps/web/src/app"]);
+    expect(truncated).toBe(false);
+    expect(github.listRepoTree).toHaveBeenCalledTimes(1);
+  });
+
+  it("falls back to the direct probe when the tree is unavailable", async () => {
+    github.listRepoTree.mockRejectedValueOnce(new Error("409 empty repository"));
+    github.files.set("app/layout.tsx", "export default function L() {}");
+    const { candidates } = await findCareersCandidates({ ...BASE });
+    expect(candidates.map((c) => c.dir)).toEqual(["app"]);
+  });
+
+  it("keeps probing when GitHub truncates the tree", async () => {
+    github.files.set("app/layout.tsx", "export default function L() {}");
+    github.listRepoTree.mockResolvedValueOnce({ files: [], truncated: true });
+    const { candidates, truncated } = await findCareersCandidates({ ...BASE });
+    expect(truncated).toBe(true);
+    expect(candidates.map((c) => c.dir)).toEqual(["app"]);
+  });
+
+  it("returns an empty list rather than throwing on a repo with no site", async () => {
+    github.files.set("README.md", "# hi");
+    const { candidates } = await findCareersCandidates({ ...BASE });
+    expect(candidates).toEqual([]);
+  });
+});
+
+// A directory picked in the browser is user input. The installer's promise is
+// that it only writes where it can see a site, so submit re-checks the marker.
+describe("verifyCareersDir", () => {
+  it("accepts a directory that really holds a root layout", async () => {
+    github.files.set("apps/web/app/layout.tsx", "export default function L() {}");
+    const found = await verifyCareersDir({ ...BASE, ref: "main", dir: "apps/web/app" });
+    expect(found).toMatchObject({
+      framework: "next-app",
+      dir: "apps/web/app",
+      typescript: true,
+      evidence: "apps/web/app/layout.tsx",
+    });
+  });
+
+  it("rejects a directory with no framework marker", async () => {
+    github.files.set("apps/web/app/layout.tsx", "export default function L() {}");
+    const found = await verifyCareersDir({ ...BASE, ref: "main", dir: "docs" });
+    expect(found).toBeNull();
+  });
+
+  it("rejects traversal", async () => {
+    const found = await verifyCareersDir({ ...BASE, ref: "main", dir: "../../etc" });
+    expect(found).toBeNull();
+  });
+
+  it("verifies an Astro pages dir against the config above it", async () => {
+    github.files.set("sites/blog/astro.config.ts", "export default {};");
+    const found = await verifyCareersDir({
+      ...BASE,
+      ref: "main",
+      dir: "sites/blog/src/pages",
+    });
+    expect(found).toMatchObject({
+      framework: "astro",
+      dir: "sites/blog/src/pages",
+      evidence: "sites/blog/astro.config.ts",
+    });
+  });
+});