diff --git a/.changeset/bright-doctors-scan.md b/.changeset/bright-doctors-scan.md
new file mode 100644
index 00000000000..7d7b16d6df5
--- /dev/null
+++ b/.changeset/bright-doctors-scan.md
@@ -0,0 +1,5 @@
+---
+'@shopify/app': minor
+---
+
+Add `shopify app doctor scan` for Shopify-specific security reviews.
diff --git a/packages/app/package.json b/packages/app/package.json
index 4a3ed74a086..1c05bc2d306 100644
--- a/packages/app/package.json
+++ b/packages/app/package.json
@@ -42,6 +42,7 @@
   "scripts": {
     "build": "nx build",
     "clean": "nx clean",
+    "generate:app-doctor-checks": "node src/cli/services/app-doctor-engine/embed-checks.mjs",
     "lint": "nx lint",
     "lint:fix": "nx lint:fix",
     "prepack": "NODE_ENV=production pnpm nx build && cp ../../README.md README.md",
@@ -55,6 +56,7 @@
   },
   "dependencies": {
     "@graphql-typed-document-node/core": "3.2.0",
+    "@iarna/toml": "2.2.5",
     "@luckycatfactory/esbuild-graphql-loader": "3.8.1",
     "@oclif/core": "4.8.3",
     "@shopify/cli-kit": "4.7.0",
@@ -63,9 +65,12 @@
     "@shopify/theme": "4.7.0",
     "@shopify/theme-check-node": "3.29.0",
     "@shopify/toml-patch": "0.3.0",
+    "acorn": "8.17.0",
+    "acorn-walk": "8.3.5",
     "chokidar": "3.6.0",
     "diff": "5.2.2",
     "esbuild": "0.28.1",
+    "fast-glob": "3.3.3",
     "graphql-request": "6.1.0",
     "h3": "1.15.11",
     "http-proxy-node16": "1.0.6",
diff --git a/packages/app/src/cli/commands/app/doctor/scan.test.ts b/packages/app/src/cli/commands/app/doctor/scan.test.ts
new file mode 100644
index 00000000000..c69ad03b39d
--- /dev/null
+++ b/packages/app/src/cli/commands/app/doctor/scan.test.ts
@@ -0,0 +1,70 @@
+import DoctorScan from './scan.js'
+import doctor from '../../../services/doctor.js'
+import AppLinkedCommand from '../../../utilities/app-linked-command.js'
+import BaseCommand from '@shopify/cli-kit/node/base-command'
+import {resolvePath} from '@shopify/cli-kit/node/path'
+import {describe, expect, test, vi} from 'vitest'
+
+vi.mock('../../../services/doctor.js')
+
+describe('app doctor scan command', () => {
+  test('does not require linked app context', () => {
+    expect(DoctorScan.prototype).toBeInstanceOf(BaseCommand)
+    expect(DoctorScan.prototype).not.toBeInstanceOf(AppLinkedCommand)
+  })
+
+  test('forwards the directory and flags to the service', async () => {
+    await DoctorScan.run(
+      ['./fixtures/unlinked-app', '--json', '--verbose', '--blocking', 'high', '--skip-skill'],
+      import.meta.url,
+    )
+
+    expect(doctor).toHaveBeenCalledWith({
+      directory: resolvePath('./fixtures/unlinked-app'),
+      json: true,
+      verbose: true,
+      blocking: 'high',
+      yes: false,
+      skipSkill: true,
+      findingsPath: undefined,
+    })
+  })
+
+  test('forwards --yes without requiring an app configuration', async () => {
+    await DoctorScan.run(['/tmp/directory-without-shopify-toml', '--yes'], import.meta.url)
+
+    expect(doctor).toHaveBeenCalledWith({
+      directory: '/tmp/directory-without-shopify-toml',
+      json: false,
+      verbose: false,
+      blocking: 'none',
+      yes: true,
+      skipSkill: false,
+      findingsPath: undefined,
+    })
+  })
+
+  test('resolves and forwards an agent findings file', async () => {
+    await DoctorScan.run(['.', '--findings', './findings.json', '--skip-skill'], import.meta.url)
+
+    expect(doctor).toHaveBeenCalledWith(expect.objectContaining({findingsPath: resolvePath('./findings.json')}))
+  })
+
+  test('describes --yes as showing instructions and keeps it mutually exclusive with --skip-skill', () => {
+    expect(DoctorScan.flags.yes.description).toBe(
+      'Show optional App Doctor skill setup instructions without prompting.',
+    )
+    expect(DoctorScan.flags['skip-skill'].description).toBe("Don't offer App Doctor skill setup instructions.")
+    expect(DoctorScan.flags.yes.exclusive).toEqual(['skip-skill'])
+    expect(DoctorScan.flags['skip-skill'].exclusive).toEqual(['yes'])
+    expect(DoctorScan.descriptionWithMarkdown).toContain(
+      "Shopify CLI only shows instructions; it doesn't install or configure the skill.",
+    )
+  })
+
+  test('allows --yes in JSON mode while preserving non-interactive output behavior', async () => {
+    await DoctorScan.run(['--json', '--yes'], import.meta.url)
+
+    expect(doctor).toHaveBeenCalledWith(expect.objectContaining({json: true, yes: true}))
+  })
+})
diff --git a/packages/app/src/cli/commands/app/doctor/scan.ts b/packages/app/src/cli/commands/app/doctor/scan.ts
new file mode 100644
index 00000000000..4bf06a3a482
--- /dev/null
+++ b/packages/app/src/cli/commands/app/doctor/scan.ts
@@ -0,0 +1,67 @@
+import doctor from '../../../services/doctor.js'
+import {Args, Flags} from '@oclif/core'
+import BaseCommand from '@shopify/cli-kit/node/base-command'
+import {globalFlags, jsonFlag} from '@shopify/cli-kit/node/cli'
+import {cwd, resolvePath} from '@shopify/cli-kit/node/path'
+import type {AppDoctorBlockingLevel} from '../../../services/app-doctor-api.js'
+
+const blockingLevels: AppDoctorBlockingLevel[] = ['critical', 'high', 'medium', 'low', 'none']
+
+export default class DoctorScan extends BaseCommand {
+  static summary = 'Check an app for Shopify-specific security issues.'
+
+  static descriptionWithMarkdown = `Runs Shopify App Doctor locally and creates its review pack and trace.
+
+Pass \`--findings\` after completing the review pack to validate agent findings and compile them into the trace. In CI and other non-interactive environments, skill setup instructions aren't offered unless you pass \`--yes\`. JSON output never prompts or prints those instructions. Shopify CLI only shows instructions; it doesn't install or configure the skill.`
+
+  static description = this.descriptionWithoutMarkdown()
+
+  static args = {
+    directory: Args.string({
+      description: 'The app directory to check. Defaults to the current directory.',
+      parse: async (input) => resolvePath(input),
+    }),
+  }
+
+  static flags = {
+    ...globalFlags,
+    ...jsonFlag,
+    findings: Flags.string({
+      description: 'Validate agent findings from a JSON file and compile them into the trace.',
+      parse: async (input) => resolvePath(input),
+      env: 'SHOPIFY_FLAG_APP_DOCTOR_FINDINGS',
+    }),
+    blocking: Flags.string({
+      description: 'The minimum finding severity that causes a non-zero exit code.',
+      options: blockingLevels,
+      default: 'none',
+      env: 'SHOPIFY_FLAG_APP_DOCTOR_BLOCKING',
+    }),
+    yes: Flags.boolean({
+      description: 'Show optional App Doctor skill setup instructions without prompting.',
+      default: false,
+      exclusive: ['skip-skill'],
+      env: 'SHOPIFY_FLAG_YES',
+    }),
+    'skip-skill': Flags.boolean({
+      description: "Don't offer App Doctor skill setup instructions.",
+      default: false,
+      exclusive: ['yes'],
+      env: 'SHOPIFY_FLAG_SKIP_SKILL',
+    }),
+  }
+
+  public async run(): Promise<void> {
+    const {args, flags} = await this.parse(DoctorScan)
+
+    await doctor({
+      directory: args.directory ?? cwd(),
+      json: flags.json,
+      verbose: Boolean(flags.verbose),
+      blocking: flags.blocking as AppDoctorBlockingLevel,
+      yes: flags.yes,
+      skipSkill: flags['skip-skill'],
+      findingsPath: flags.findings,
+    })
+  }
+}
diff --git a/packages/app/src/cli/index.test.ts b/packages/app/src/cli/index.test.ts
new file mode 100644
index 00000000000..6c424c63cb0
--- /dev/null
+++ b/packages/app/src/cli/index.test.ts
@@ -0,0 +1,9 @@
+import {commands} from './index.js'
+import DoctorScan from './commands/app/doctor/scan.js'
+import {describe, expect, test} from 'vitest'
+
+describe('@shopify/app command registration', () => {
+  test('registers app:doctor:scan', () => {
+    expect(commands['app:doctor:scan']).toBe(DoctorScan)
+  })
+})
diff --git a/packages/app/src/cli/index.ts b/packages/app/src/cli/index.ts
index fc2d9c42b10..7df5089d0cc 100644
--- a/packages/app/src/cli/index.ts
+++ b/packages/app/src/cli/index.ts
@@ -7,6 +7,7 @@ import ConfigPull from './commands/app/config/pull.js'
 import DemoWatcher from './commands/app/demo/watcher.js'
 import Deploy from './commands/app/deploy.js'
 import Dev from './commands/app/dev.js'
+import DoctorScan from './commands/app/doctor/scan.js'
 import Logs from './commands/app/logs.js'
 import Sources from './commands/app/app-logs/sources.js'
 import EnvPull from './commands/app/env/pull.js'
@@ -48,6 +49,7 @@ export const commands: {[key: string]: typeof AppLinkedCommand | typeof AppUnlin
   'app:deploy': Deploy,
   'app:dev': Dev,
   'app:dev:clean': DevClean,
+  'app:doctor:scan': DoctorScan,
   'app:logs': Logs,
   'app:logs:sources': Sources,
   'app:import-custom-data-definitions': ImportCustomDataDefinitions,
diff --git a/packages/app/src/cli/services/app-doctor-api.test.ts b/packages/app/src/cli/services/app-doctor-api.test.ts
new file mode 100644
index 00000000000..3f6d7de7cd4
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-api.test.ts
@@ -0,0 +1,91 @@
+import {runAppDoctor} from './app-doctor-api.js'
+import {loadChecks} from './app-doctor-engine/index.js'
+import {inTemporaryDirectory, mkdir, readFile, writeFile} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import {describe, expect, test} from 'vitest'
+
+async function createApp(directory: string, source = 'export const loader = () => ({ok: true})'): Promise<string> {
+  const sourceDirectory = joinPath(directory, 'app', 'routes')
+  const sourcePath = joinPath(sourceDirectory, 'index.ts')
+  await mkdir(sourceDirectory)
+  await writeFile(joinPath(directory, 'shopify.app.toml'), 'name = "Test app"\nclient_id = "test"\n')
+  await writeFile(joinPath(directory, 'package.json'), '{"name":"test-app"}\n')
+  await writeFile(sourcePath, source)
+  return sourcePath
+}
+
+describe('App Doctor CLI integration', () => {
+  test('runs the in-tree engine and writes the review pack and trace', async () => {
+    await inTemporaryDirectory(async (directory) => {
+      await createApp(directory)
+
+      const result = await runAppDoctor({directory, format: 'human', verbose: true, blocking: 'none'})
+      const review = JSON.parse(await readFile(joinPath(directory, 'app-doctor-review.json')))
+      const trace = JSON.parse(await readFile(joinPath(directory, 'app-doctor-trace.json')))
+
+      expect(review.checks).toHaveLength(16)
+      expect(review.checks.every((check: {prompt: string}) => check.prompt.length > 0)).toBe(true)
+      expect(trace.schema_version).toBe(1)
+      expect(trace.engine.name).toBe('shopify-app-doctor')
+      expect(result.engine).toEqual(trace.engine)
+      expect(result.output).toContain('shopify app doctor scan --findings <findings.json>')
+      expect(result.exitCode).toBe(0)
+    })
+  })
+
+  test('preserves JSON output and applies the requested blocking severity', async () => {
+    await inTemporaryDirectory(async (directory) => {
+      const testToken = ['shpat', '0123456789abcdef0123456789abcdef'].join('_')
+      await createApp(directory, `const access_token = "${testToken}"`)
+
+      const result = await runAppDoctor({directory, format: 'json', verbose: false, blocking: 'high'})
+
+      expect(() => JSON.parse(result.output)).not.toThrow()
+      expect(result.output).not.toContain(testToken)
+      expect(result.exitCode).toBe(1)
+    })
+  })
+
+  test('validates agent findings and compiles them into the trace', async () => {
+    await inTemporaryDirectory(async (directory) => {
+      await createApp(directory)
+      const check = loadChecks().get('MISSING_TENANT_ISOLATION')!
+      const findingsPath = joinPath(directory, 'findings.json')
+      await writeFile(
+        findingsPath,
+        `${JSON.stringify({
+          checks_executed: [{check_id: check.id, check_version: check.version, prompt_hash: check.prompt_hash}],
+          findings: [
+            {
+              check_id: check.id,
+              check_version: check.version,
+              prompt_hash: check.prompt_hash,
+              file: 'app/routes/index.ts',
+              line: 1,
+              message: 'The query is not scoped to the current shop.',
+              evidence: [{file: 'app/routes/index.ts', line: 1, quote: 'loader'}],
+            },
+          ],
+        })}\n`,
+      )
+
+      const result = await runAppDoctor({
+        directory,
+        findingsPath,
+        format: 'json',
+        verbose: false,
+        blocking: 'none',
+      })
+      const trace = JSON.parse(result.output)
+
+      expect(trace.findings).toEqual(
+        expect.arrayContaining([expect.objectContaining({source: 'agent', check_id: 'MISSING_TENANT_ISOLATION'})]),
+      )
+      expect(trace.checks_executed).toEqual(
+        expect.arrayContaining([expect.objectContaining({id: 'MISSING_TENANT_ISOLATION', status: 'executed'})]),
+      )
+      expect(JSON.parse(await readFile(joinPath(directory, 'app-doctor-trace.json')))).toEqual(trace)
+      expect(result.exitCode).toBe(0)
+    })
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-api.ts b/packages/app/src/cli/services/app-doctor-api.ts
new file mode 100644
index 00000000000..3c8958cccea
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-api.ts
@@ -0,0 +1,154 @@
+import {
+  buildReviewPack,
+  compileTrace,
+  formatConsole,
+  formatJson,
+  getEngineVersion,
+  mergeFindings,
+  scan,
+  validateAgentChecksExecuted,
+} from './app-doctor-engine/index.js'
+import {computeResultHash} from './app-doctor-engine/scorer/index.js'
+import {AbortError} from '@shopify/cli-kit/node/error'
+import {readFile, writeFile} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import type {CheckExecution, Severity, Suppression} from './app-doctor-engine/types.js'
+import type {AgentFindingsDocument} from './app-doctor-engine/checks/index.js'
+
+const REVIEW_FILENAME = 'app-doctor-review.json'
+const TRACE_FILENAME = 'app-doctor-trace.json'
+
+export interface AppDoctorEngineMetadata {
+  name: string
+  version: string
+  ruleset: string
+}
+
+export type AppDoctorBlockingLevel = Severity | 'none'
+
+export interface AppDoctorRunOptions {
+  directory: string
+  format: 'human' | 'json'
+  verbose: boolean
+  blocking: AppDoctorBlockingLevel
+  findingsPath?: string
+}
+
+export interface AppDoctorRunResult {
+  output: string
+  engine: AppDoctorEngineMetadata
+  exitCode: number
+}
+
+interface FindingsDocument extends AgentFindingsDocument {
+  suppressions?: Suppression[]
+}
+
+const severityRank: Record<Severity, number> = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+}
+
+function shouldBlock(issues: {severity: Severity}[], blocking: AppDoctorBlockingLevel): boolean {
+  if (blocking === 'none') return false
+  return issues.some((issue) => severityRank[issue.severity] >= severityRank[blocking])
+}
+
+function humanScanOutput(scanOutput: string, checkCount: number, reviewPath: string, tracePath: string): string {
+  return [
+    scanOutput.trimEnd(),
+    '',
+    'Agentic review',
+    `${checkCount} check(s) ready for your coding agent.`,
+    `Wrote ${reviewPath}`,
+    `Trace written to ${tracePath}`,
+    '',
+    'After investigating the review pack, compile the final trace with:',
+    `  shopify app doctor scan --findings <findings.json>`,
+  ].join('\n')
+}
+
+function humanFindingsOutput(scanOutput: string, accepted: number, rejected: string[], tracePath: string): string {
+  return [
+    scanOutput.trimEnd(),
+    '',
+    `Merged ${accepted} agent finding(s) into the trace.`,
+    ...rejected.map((reason) => `Rejected: ${reason}`),
+    `Trace written to ${tracePath}`,
+  ].join('\n')
+}
+
+async function loadFindings(path: string): Promise<FindingsDocument> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(path))
+  } catch (error) {
+    throw new AbortError(
+      `Could not read App Doctor findings from ${path}.`,
+      error instanceof Error ? error.message : undefined,
+    )
+  }
+
+  if (!parsed || typeof parsed !== 'object' || !('findings' in parsed) || !Array.isArray(parsed.findings)) {
+    throw new AbortError('The App Doctor findings file must contain a findings array.')
+  }
+  if ('suppressions' in parsed && parsed.suppressions !== undefined && !Array.isArray(parsed.suppressions)) {
+    throw new AbortError('The App Doctor findings file suppressions field must be an array.')
+  }
+
+  return parsed as FindingsDocument
+}
+
+export async function runAppDoctor(options: AppDoctorRunOptions): Promise<AppDoctorRunResult> {
+  const startTime = Date.now()
+  const result = await scan(options.directory)
+  const elapsedMilliseconds = Date.now() - startTime
+  const engineVersion = getEngineVersion()
+  const reviewPath = joinPath(options.directory, REVIEW_FILENAME)
+  const tracePath = joinPath(options.directory, TRACE_FILENAME)
+  const scanOutput = formatConsole(result, {verbose: options.verbose, elapsedMilliseconds})
+
+  let rejected: string[] = []
+  let accepted = 0
+  let agentChecksExecuted: CheckExecution[] = []
+  let suppressions: Suppression[] = []
+
+  if (options.findingsPath) {
+    const document = await loadFindings(options.findingsPath)
+    const merged = mergeFindings(result.issues, document.findings, {
+      knownFiles: new Set(Object.keys(result.scan.file_hashes ?? {})),
+    })
+    const executed = validateAgentChecksExecuted(document)
+    accepted = merged.accepted
+    rejected = [...merged.rejected, ...executed.rejected]
+    agentChecksExecuted = executed.executions
+    suppressions = document.suppressions ?? []
+    result.scan.result_hash = computeResultHash(result.issues, result.score)
+  }
+
+  const trace = compileTrace(result, {engineVersion, agentChecksExecuted, suppressions})
+  await writeFile(tracePath, `${JSON.stringify(trace, null, 2)}\n`)
+
+  let output: string
+  if (options.findingsPath) {
+    output =
+      options.format === 'json'
+        ? JSON.stringify(trace, null, 2)
+        : humanFindingsOutput(scanOutput, accepted, rejected, tracePath)
+  } else {
+    const reviewPack = buildReviewPack(engineVersion)
+    await writeFile(reviewPath, `${JSON.stringify(reviewPack, null, 2)}\n`)
+    output =
+      options.format === 'json'
+        ? formatJson(result)
+        : humanScanOutput(scanOutput, reviewPack.checks.length, reviewPath, tracePath)
+  }
+
+  let exitCode = 0
+  if (rejected.length > 0) exitCode = 2
+  else if (shouldBlock(result.issues, options.blocking)) exitCode = 1
+
+  return {output, engine: trace.engine, exitCode}
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/capabilities/detect.ts b/packages/app/src/cli/services/app-doctor-engine/capabilities/detect.ts
new file mode 100644
index 00000000000..3863b43a7a0
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/capabilities/detect.ts
@@ -0,0 +1,92 @@
+import type {Capabilities} from '../types.js'
+import type {SourceFile, AppTomlContent, ExtensionInfo} from '../rules/types.js'
+
+/**
+ * Detect what the app does by examining config and source files.
+ * This determines which rules run and which are skipped.
+ */
+export function detectCapabilities(
+  appToml: AppTomlContent | null,
+  extensions: ExtensionInfo[],
+  sourceFiles: SourceFile[],
+): Capabilities {
+  // Shopify CLI uses type = "theme" for theme app extensions (not "theme_app_extension").
+  // See https://shopify.dev/docs/api/cli/app#extension-types
+  const themeExtension = extensions.some((extension) => extension.type === 'theme')
+  const appEmbed = extensions.some((extension) => extension.type === 'theme' && hasAppEmbedBlock(extension))
+
+  const scriptTags = sourceFiles.some((file) => {
+    if (!file.content) return false
+    // Match scriptTag, script_tag, ScriptTag in any language
+    return /script[_-]?tags?|ScriptTag/i.test(file.content)
+  })
+
+  const webhooks = Boolean(appToml?.webhooks?.length)
+
+  const appProxy = Boolean((appToml?.raw as Record<string, unknown>)?.app_proxy)
+
+  const storefrontMetafieldWrites = sourceFiles.some((file) => {
+    if (!file.content) return false
+    // Match metafield write patterns
+    return /metafields?Set|metafields?\/.*(?:POST|PUT|create|update)|write.*metafield|metafield.*write/i.test(
+      file.content,
+    )
+  })
+
+  const hasBackend = sourceFiles.some((file) => {
+    if (!file.content) return false
+    return detectRouteDefinitions(file)
+  })
+
+  const declaredIpAllowlist = Boolean(appToml?.ip_allowlist?.length)
+
+  // Shopify CLI uses type = "checkout_ui" for checkout UI extensions.
+  const checkoutExtension = extensions.some(
+    (extension) => extension.type === 'checkout_ui' || extension.type === 'checkout_ui_extension',
+  )
+
+  return {
+    theme_app_extension: themeExtension,
+    app_embed: appEmbed,
+    script_tags: scriptTags,
+    webhooks,
+    app_proxy: appProxy,
+    storefront_metafield_writes: storefrontMetafieldWrites,
+    has_backend: hasBackend,
+    declared_ip_allowlist: declaredIpAllowlist,
+    checkout_extension: checkoutExtension,
+  }
+}
+
+function hasAppEmbedBlock(extension: ExtensionInfo): boolean {
+  return extension.files.some(
+    (file) => file.ext === '.liquid' && file.content?.includes('"target"') && file.content?.includes('body'),
+  )
+}
+
+/**
+ * Detect route definitions across frameworks.
+ * Express: app.get/post/put/delete, router.get/post
+ * Rails: get/post/match in routes.rb
+ * Remix: export const loader/action
+ * PHP: Route::get/post
+ */
+function detectRouteDefinitions(file: SourceFile): boolean {
+  const content = file.content
+  if (!content) return false
+
+  // Express / Remix
+  if (/\b(?:app|router)\.(get|post|put|delete|patch)\s*\(/.test(content)) return true
+  if (/export\s+(?:async\s+)?(?:function|const)\s+(?:loader|action)\b/.test(content)) return true
+
+  // Rails
+  if (file.ext === '.rb' && /\b(?:get|post|put|delete|match)\s+['"]/.test(content)) return true
+
+  // PHP Laravel
+  if (file.ext === '.php' && /Route::(?:get|post|put|delete)\s*\(/.test(content)) return true
+
+  // Flask
+  if (file.ext === '.py' && /@(?:app|bp)\.route\s*\(/.test(content)) return true
+
+  return false
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/APP_PROXY_UNVERIFIED_SIGNATURE.md b/packages/app/src/cli/services/app-doctor-engine/checks/APP_PROXY_UNVERIFIED_SIGNATURE.md
new file mode 100644
index 00000000000..3e65846b6f9
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/APP_PROXY_UNVERIFIED_SIGNATURE.md
@@ -0,0 +1,87 @@
+---
+id: APP_PROXY_UNVERIFIED_SIGNATURE
+version: 1
+tier: agentic
+severity: high
+---
+
+Find app proxy endpoints that read proxy parameters without verifying
+the Shopify signature, allowing an attacker to impersonate Shopify and
+send fake proxy requests.
+
+App proxies let an app serve content directly on the merchant's store
+via a URL like `https://shop.example.com/apps/my-app/proxy`. Shopify
+signs every proxy request with an HMAC using the app's shared secret.
+If the app doesn't verify this signature, anyone can send requests to
+the proxy endpoint with forged parameters — including `shop`,
+`logged_in_customer_id`, and `path_prefix`.
+
+## What to look for
+
+1. **Find app proxy route handlers.** These are endpoints configured as
+   app proxies in `shopify.app.toml` under `[app_proxy]` or in the app's
+   routing config. They typically read parameters like:
+   - `shop` or `shop_id`
+   - `logged_in_customer_id`
+   - `path_prefix`
+   - `signature`
+   - `timestamp`
+
+2. **Check for signature verification.** The handler must verify the
+   HMAC signature before trusting any proxy parameter. Look for:
+   - **Remix:** `authenticate.public.appProxy(request)` — the official
+     verification function
+   - **Rails:** `verified_request?` or manual HMAC verification using
+     `ShopifyApp` utilities
+   - **Express:** Manual HMAC verification using the app secret
+   - **PHP:** `ShopifyUtils::verifyProxyRequest()` or equivalent
+
+3. **If no verification is present, check whether the handler:**
+   - Reads `shop` from the query string and uses it to scope data
+   - Reads `logged_in_customer_id` and uses it for authorisation
+   - Returns any shop-specific data
+
+   If any of these are true and there's no signature check, it's a real
+   finding.
+
+4. **Check for the HMAC pattern even if the function name isn't obvious.**
+   Some apps implement custom verification:
+   - `crypto.createHmac('sha256', API_SECRET)`
+   - `OpenSSL::HMAC.digest`
+   - `hash_hmac('sha256', ...)`
+   - Comparison with `timingSafeEqual` or `secure_compare`
+
+## What to report
+
+For each proxy handler that reads shop/customer parameters without
+signature verification:
+
+```json
+{
+  "file": "app/routes/proxy.ts",
+  "line": 15,
+  "message": "App proxy handler reads shop parameter without signature verification",
+  "snippet": "const shop = url.searchParams.get('shop')",
+  "evidence": [
+    {
+      "file": "app/routes/proxy.ts",
+      "line": 15,
+      "quote": "const shop = url.searchParams.get('shop')"
+    },
+    {
+      "file": "app/routes/proxy.ts",
+      "line": 1,
+      "quote": "no authenticate.public.appProxy or HMAC verification found"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The handler reads the shop parameter from the query string and uses it to query shop data, but no signature verification is present. An attacker can send requests with any shop parameter."
+}
+```
+
+Do not report:
+
+- Handlers that call `authenticate.public.appProxy(request)` (Remix)
+- Handlers with manual HMAC verification
+- Handlers that return only static content (no shop-specific data)
+- Test handlers
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/CSRF_MISSING_PROTECTION.md b/packages/app/src/cli/services/app-doctor-engine/checks/CSRF_MISSING_PROTECTION.md
new file mode 100644
index 00000000000..781c0c76eb9
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/CSRF_MISSING_PROTECTION.md
@@ -0,0 +1,88 @@
+---
+id: CSRF_MISSING_PROTECTION
+version: 1
+tier: agentic
+severity: medium
+---
+
+Find state-changing endpoints (POST, PUT, DELETE, PATCH) that don't
+verify CSRF protection, allowing an attacker to forge requests on
+behalf of an authenticated user.
+
+CSRF (Cross-Site Request Forgery) occurs when an app accepts
+state-changing requests without checking that the request came from
+the app's own UI. In Shopify apps, embedded apps use session tokens
+(JWT) that provide some CSRF protection, but server-rendered apps and
+app proxies still need explicit CSRF checks.
+
+## What to look for
+
+1. **Find state-changing handlers.** Search for:
+   - Rails: controller actions responding to POST/PUT/PATCH/DELETE
+     (check `routes.rb` or controller method names like `create`,
+     `update`, `destroy`)
+   - Remix: `action` exports in route files
+   - Express: `app.post()`, `app.put()`, `app.delete()`
+   - PHP: form handlers, POST routes
+
+2. **Check for CSRF protection on each.** Look for:
+   - Rails: `protect_from_forgery` (default in Rails, but check for
+     `skip_forgery_protection` or `protect_from_forgery with: :null_session`)
+   - Remix: session token validation (`authenticate.admin(request)`)
+   - Express: `csurf` middleware or equivalent
+   - PHP: CSRF token in form, `VerifyCsrfToken` middleware
+
+3. **Flag explicit opt-outs.** Search for:
+   - `skip_forgery_protection` — disables CSRF entirely for a controller
+   - `protect_from_forgery with: :null_session` — used for webhooks, but
+     if on a non-webhook endpoint, CSRF is missing
+   - `skip_before_action :verify_authenticity_token` — skips the Rails
+     CSRF check
+
+4. **Distinguish webhooks from user-facing endpoints.** Webhooks use
+   HMAC verification instead of CSRF tokens — `protect_from_forgery
+with: :null_session` is correct for webhooks. But the same pattern
+   on a user-facing POST handler is a CSRF vulnerability.
+
+5. **Check Shopify-specific patterns.** Embedded apps that use
+   `authenticate.admin(request)` get session token validation that
+   prevents CSRF. But if an action skips `authenticate.admin` and still
+   processes state changes, CSRF protection may be missing.
+
+## What to report
+
+For each state-changing endpoint without CSRF protection:
+
+```json
+{
+  "file": "app/controllers/settings_controller.rb",
+  "line": 5,
+  "message": "POST handler with CSRF protection disabled",
+  "snippet": "skip_forgery_protection",
+  "evidence": [
+    {
+      "file": "app/controllers/settings_controller.rb",
+      "line": 5,
+      "quote": "skip_forgery_protection"
+    },
+    {
+      "file": "app/controllers/settings_controller.rb",
+      "line": 10,
+      "quote": "def update"
+    }
+  ],
+  "confidence": "medium",
+  "reasoning": "The update action accepts POST requests but CSRF protection is explicitly skipped. This is not a webhook handler (no HMAC verification), so an attacker can forge a POST request from another site."
+}
+```
+
+Do not report:
+
+- Webhook handlers with `protect_from_forgery with: :null_session`
+  (HMAC is the CSRF protection for webhooks)
+- Endpoints protected by `authenticate.admin(request)` (session
+  token provides CSRF protection)
+- GET-only handlers (not state-changing)
+- API endpoints that use bearer token auth (not cookie-based, so
+  CSRF doesn't apply)
+- Test controllers
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_AUTHORIZATION_CHECK.md b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_AUTHORIZATION_CHECK.md
new file mode 100644
index 00000000000..dee1293b9b6
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_AUTHORIZATION_CHECK.md
@@ -0,0 +1,94 @@
+---
+id: MISSING_AUTHORIZATION_CHECK
+version: 1
+tier: agentic
+severity: high
+---
+
+Find controller actions or route handlers that access resources without
+checking whether the current user is authorized to access them, beyond
+authentication. Authentication verifies WHO you are; authorization verifies
+WHAT you can do. An app can be authenticated but still access resources
+belonging to another merchant if authorization checks are missing.
+
+This is distinct from `MISSING_TENANT_ISOLATION` (database query
+scoping) — this check looks for missing policy/permission checks on
+actions, even when the data access is scoped. For example, an app might
+scope queries by shop but not check whether the merchant has the right to
+delete a resource, or whether a staff member can access admin-only
+actions.
+
+## What to look for
+
+1. **Find authorization frameworks.** Check what the app uses:
+   - Rails: Pundit (`authorize`, `policy`, `Pundit`), CanCanCan
+     (`can?`, `ability`), action_access filters
+   - Remix/Express: middleware that checks roles/permissions
+   - Custom: `before_action :check_admin`, `if current_user.can?`
+
+2. **Find actions without authorization checks.** For each controller
+   action or route handler, determine:
+   - Is there a `before_action` that checks authorization (not just
+     authentication)?
+   - Is there a Pundit `authorize` call?
+   - Is there a CanCanCan `authorize!` or `can?` check?
+   - Is there a custom permission check?
+
+3. **Check for `skip_idor_protection` or equivalent opt-outs.** These
+   disable IDOR/authorization checks. For each, determine:
+   - Is the skip justified? (e.g., public endpoint, webhook, health check)
+   - Does the skip expose a state-changing action to unauthorised users?
+   - Is there a compensating control (HMAC, session token, etc.)?
+
+4. **Check for admin-only functionality reachable by merchants.** Look for:
+   - Controllers under `admin/` namespace that don't check staff vs merchant
+   - Actions that modify app configuration without checking the caller's role
+   - Staff-only operations accessible through the merchant-facing UI
+
+5. **Check for missing object-level authorization.** Even if the query
+   is scoped by shop, does the handler verify that the specific resource
+   belongs to the current merchant?
+   - `Order.find(params[:id])` scoped by shop — but does it check the
+     merchant can access this specific order?
+   - `Product.find(params[:id])` — is there a policy check, or just
+     tenant scoping?
+
+## What to report
+
+For each action that accesses resources without authorization checks:
+
+```json
+{
+  "file": "app/controllers/orders_controller.rb",
+  "line": 15,
+  "message": "Destroy action has no authorization check beyond authentication",
+  "snippet": "def destroy\n  Order.find(params[:id]).destroy\nend",
+  "evidence": [
+    {
+      "file": "app/controllers/orders_controller.rb",
+      "line": 15,
+      "quote": "def destroy"
+    },
+    {
+      "file": "app/controllers/orders_controller.rb",
+      "line": 5,
+      "quote": "before_action :authenticate_user (no authorize check)"
+    }
+  ],
+  "confidence": "medium",
+  "reasoning": "The destroy action authenticates the user but does not call authorize or check a policy. Any authenticated merchant can delete any order within their shop, even if they shouldn't have delete permissions."
+}
+```
+
+Do not report:
+
+- Actions with explicit `authorize` / `can?` / policy checks
+- Actions protected by a `before_action` that checks authorization
+- Public endpoints (health checks, static content)
+- Webhook handlers (HMAC is the authorization)
+- Actions that only read data the merchant owns (scoped by session.shop
+  AND no object-level access control needed)
+- Internal/staff-only controllers (under `Internal::` namespace, behind
+  employee SSO like `EmployeeIdentity`, `IdentityClient`, etc.)
+- Test files (under test/ or \*\_test.rb)
+- Test controllers
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_EMBEDDED_CSP.md b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_EMBEDDED_CSP.md
new file mode 100644
index 00000000000..5cd0b6fe1af
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_EMBEDDED_CSP.md
@@ -0,0 +1,74 @@
+---
+id: MISSING_EMBEDDED_CSP
+version: 2
+tier: agentic
+severity: medium
+---
+
+Find embedded Shopify apps that are missing a Content-Security-Policy
+`frame-ancestors` directive, allowing any origin to iframe the app.
+
+Shopify apps run inside an iframe in the admin. Without a
+`frame-ancestors` directive in the CSP header, any website can embed the
+app in an iframe — a clickjacking risk. The attacker overlays invisible
+elements on top of the app's UI to trick the merchant into clicking
+buttons they can't see.
+
+## What to look for
+
+1. **Determine if the app is embedded.** Check `shopify.app.toml` for
+   `app_embed` or `theme_app_extension` in the capabilities. If the app
+   is not embedded, this check does not apply.
+
+2. **Find where HTTP response headers are set.** Search for:
+   - `Content-Security-Policy` in any file
+   - `addDocumentResponseHeaders` (Shopify Remix helper)
+   - `response.headers.set`
+   - `frame-ancestors`
+   - CSP middleware configuration
+
+3. **If CSP headers are set, check for `frame-ancestors`.** The directive
+   must be present and must restrict embedding to:
+   - `https://admin.shopify.com`
+   - The authenticated shop's domain (e.g. `https://my-shop.myshopify.com`)
+
+   A wildcard `frame-ancestors *` is not safe. An absent `frame-ancestors`
+   is not safe (browsers default to allowing any origin).
+
+4. **Check for the Shopify Remix helper.** If the app uses
+   `@shopify/shopify-app-remix`, the `addDocumentResponseHeaders` function
+   sets the correct CSP automatically. If it's called, the app is safe.
+
+5. **Check for `X-Frame-Options` as a fallback.** Some apps use
+   `X-Frame-Options: ALLOW-FROM https://admin.shopify.com` instead of
+   CSP `frame-ancestors`. This is deprecated but functional in some
+   browsers. Note it but don't flag if CSP is also present.
+
+## What to report
+
+For embedded apps with no `frame-ancestors` directive:
+
+```json
+{
+  "file": "app/root.tsx",
+  "line": 1,
+  "message": "Embedded app has no frame-ancestors CSP directive — any origin can iframe it",
+  "evidence": [
+    { "file": "shopify.app.toml", "line": 5, "quote": "app_embed = true" },
+    {
+      "file": "app/root.tsx",
+      "line": 1,
+      "quote": "no addDocumentResponseHeaders or CSP header found"
+    }
+  ],
+  "confidence": "medium",
+  "reasoning": "The app declares app_embed capability but no file sets a Content-Security-Policy with frame-ancestors. Without it, any website can iframe the app."
+}
+```
+
+Do not report:
+
+- Non-embedded apps (no app_embed or theme_app_extension)
+- Apps that call `addDocumentResponseHeaders` (handles CSP automatically)
+- Apps with an explicit `frame-ancestors` directive in their CSP
+- Test files (under test/ or \*\_test.rb)
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_TENANT_ISOLATION.md b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_TENANT_ISOLATION.md
new file mode 100644
index 00000000000..1f4a8833328
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/MISSING_TENANT_ISOLATION.md
@@ -0,0 +1,86 @@
+---
+id: MISSING_TENANT_ISOLATION
+version: 3
+tier: agentic
+severity: high
+---
+
+Find controller actions where a database query can read or modify a row
+belonging to a shop other than the one making the request.
+
+This is a multi-tenant app: every merchant's data must be isolated by
+shop. A query that doesn't filter on the current shop is a cross-tenant
+leak. Static analysis can't catch these reliably because the scoping is
+often indirect — applied by a `before_action`, inherited from a parent
+controller, or baked into a default scope on the model. Your job is to
+follow those threads.
+
+## What to look for
+
+Search for ActiveRecord queries that filter on a column other than
+`shop_id` / `shop`, or that take no tenant filter at all:
+
+```ruby
+Product.where(id: params[:id])
+Order.where(shopify_id: params[:order_id])
+Token.where(shop_id: params[:shop_id]).delete_all
+```
+
+The last one looks scoped but isn't — `params[:shop_id]` comes from the
+request, not from the authenticated session. The caller can pass any
+shop's id.
+
+## How to investigate each candidate
+
+1. **Read the enclosing method and the whole controller.** The scope may
+   be applied on an adjacent line, or the flagged line may be a fragment
+   of a longer chain (`.or(...)`, `.merge(...)`) whose base scope is above.
+
+2. **Follow the receiver.** If the query is on a variable rather than a
+   model constant, find where it comes from. A relation passed in as a
+   method parameter may already be scoped by its caller — go look.
+
+3. **Read the controller's ancestors.** Authentication and tenant scoping
+   are usually inherited: `before_action`, `around_action`, a mixin, or a
+   parent class. Follow the chain to the top before concluding there's no
+   protection.
+
+4. **Check whether the model is tenant-scoped at all.** Read the model and
+   its schema. If the table has no shop/tenant column, there is nothing to
+   scope by. Global reference or catalog tables are a correct design.
+
+5. **Consider whether cross-tenant access is the deliberate purpose.**
+   Some queries exist to resolve which tenant owns a resource. Scoping
+   those by tenant is circular. If so, the risk is enumeration, not
+   isolation — note it but don't report it under this check.
+
+6. **Check for an explicit opt-out** like `skip_idor_protection`. That
+   tells you the author considered it. Decide whether their reasoning
+   holds — an unguessable capability token is a real control; a sequential
+   integer id is not.
+
+## What to report
+
+For each genuine cross-tenant risk you find, report:
+
+```json
+{
+  "file": "app/controllers/...",
+  "line": 42,
+  "message": "Query on Product is not scoped to the current shop",
+  "snippet": "Product.where(id: params[:id])",
+  "evidence": [
+    { "file": "path", "line": 12, "quote": "the line that shows the gap" }
+  ],
+  "confidence": "high",
+  "reasoning": "what you read and why it's a real risk"
+}
+```
+
+Be precise about the gap. "No shop filter" is not enough — explain where
+the scoping _should_ have come from and why it's missing. If you read a
+file and it turns out the query IS scoped, don't report it. You are not
+trying to find problems — you are trying to find the real ones.
+
+Every finding must cite at least one file and line you actually read.
+An finding with no evidence is not a finding.
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/OPEN_REDIRECT.md b/packages/app/src/cli/services/app-doctor-engine/checks/OPEN_REDIRECT.md
new file mode 100644
index 00000000000..468cdcfdc1c
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/OPEN_REDIRECT.md
@@ -0,0 +1,66 @@
+---
+id: OPEN_REDIRECT
+version: 1
+tier: agentic
+severity: medium
+---
+
+Find redirect URLs that are built from user input without validation,
+allowing an attacker to redirect users to a malicious site.
+
+An open redirect occurs when a web application redirects to a URL that
+comes from an untrusted source (query parameters, form fields, headers)
+without checking that the destination is safe. In Shopify apps, this is
+particularly dangerous because the app runs inside an iframe in the admin
+— a redirect to an external site can be used for phishing.
+
+## What to look for
+
+1. **Find redirect calls.** Search for:
+   - Rails: `redirect_to`, `head :redirect`, `redirect`
+   - Remix/Express: `redirect()`, `Response.redirect()`, `res.redirect()`
+   - PHP: `header("Location: ...")`, `Redirect::to()`
+   - Python: `redirect()`, `HttpResponseRedirect()`
+
+2. **Trace the URL source.** For each redirect, determine where the
+   destination URL comes from:
+   - `params[:return_url]`, `params[:redirect_url]`, `request.query_params`
+   - `url.searchParams.get("return_url")`
+   - `$_GET['redirect']`, `request.args.get('next')`
+
+3. **Check for validation.** Is the URL checked against an allowlist? Is
+   it restricted to relative paths? Is it compared to a known-safe list of
+   domains? If none of these, it's an open redirect.
+
+4. **Consider the `flow_redirect_url` pattern.** Shopify Flow connectors
+   use signed URLs for redirects — the URL is HMAC-signed, so it's not
+   user-controlled even though it comes from params. Verify the signature
+   check exists before flagging.
+
+## What to report
+
+```json
+{
+  "file": "app/controllers/...",
+  "line": 42,
+  "message": "Redirect to user-supplied URL without validation",
+  "snippet": "redirect_to(params[:return_url])",
+  "evidence": [
+    { "file": "path", "line": 42, "quote": "redirect_to(params[:return_url])" },
+    {
+      "file": "path",
+      "line": 30,
+      "quote": "no allowlist or validation found in this controller"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The redirect target comes from params[:return_url] with no allowlist, path validation, or signature check."
+}
+```
+
+Do not report:
+
+- Redirects to hardcoded paths (`redirect_to("/dashboard")`)
+- Redirects with allowlist validation (`if ALLOWED_HOSTS.include?(uri.host)`)
+- Signed redirect URLs (verify the HMAC check first)
+- Test controllers
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/OVERBROAD_DATA_ACCESS.md b/packages/app/src/cli/services/app-doctor-engine/checks/OVERBROAD_DATA_ACCESS.md
new file mode 100644
index 00000000000..e1a4ac61d21
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/OVERBROAD_DATA_ACCESS.md
@@ -0,0 +1,87 @@
+---
+id: OVERBROAD_DATA_ACCESS
+version: 1
+tier: agentic
+severity: medium
+---
+
+Find cases where an app returns more data than necessary in API
+responses, exposing sensitive information that the caller doesn't need.
+
+Overbroad data access is a privacy risk: returning full customer records
+when only an order status is needed, exposing PII (email, phone, address)
+in error messages, or selecting all fields in a GraphQL query when only
+a subset is required. This is how information disclosure happens in
+practice — not through a single vulnerability, but through
+carelessly broad data returns.
+
+## What to look for
+
+1. **Find API response patterns.** Search for:
+   - Rails: `render json: @orders`, `render json: order`,
+     `respond_with @resource`, `as_json`
+   - Remix: `return json(data)`, `return Response(data)`
+   - GraphQL: query resolvers that return full objects
+   - Any serialization that includes all model fields
+
+2. **Check what fields are returned.** For each API response:
+   - Does it return the full model (all columns) or a filtered set?
+   - Does it include sensitive fields like:
+     - `email`, `phone`, `address`, `name` (PII)
+     - `api_key`, `access_token`, `secret` (credentials)
+     - `shop_id`, `tenant_id` (internal identifiers)
+     - `password`, `password_digest` (auth data)
+   - Is there a serializer or field selection that limits the output?
+
+3. **Find GraphQL over-selection.** Search for:
+   - Queries that select all fields: `query { products { ...AllFields } }`
+   - Queries without field selection: `query { orders }` (returns everything)
+   - Mutations that return the full object after creation/update
+
+4. **Check error messages for information disclosure.** Search for:
+   - Error responses that include stack traces
+   - Error messages that reveal internal paths (`/app/services/...`)
+   - Error messages that include database details (table names, column names)
+   - Debug endpoints that expose app configuration
+
+5. **Check for missing field-level authorization.** Even if the caller
+   can access the resource, should they see all fields?
+   - A merchant can see their orders, but should they see internal
+     `cost` or `profit_margin` fields?
+   - A customer can see their order, but should they see the merchant's
+     internal notes?
+
+## What to report
+
+For each response that returns sensitive data unnecessarily:
+
+```json
+{
+  "file": "app/controllers/api/orders_controller.rb",
+  "line": 20,
+  "message": "API response returns full order including customer PII",
+  "snippet": "render json: @order",
+  "evidence": [
+    {
+      "file": "app/controllers/api/orders_controller.rb",
+      "line": 20,
+      "quote": "render json: @order"
+    },
+    {
+      "file": "app/models/order.rb",
+      "line": 15,
+      "quote": "has_many :line_items (includes customer email and shipping address)"
+    }
+  ],
+  "confidence": "medium",
+  "reasoning": "The response serializes the full order model including related customer PII (email, phone, address). No field selection or serializer limits the output. The caller only needs order status, but receives the customer's personal information."
+}
+```
+
+Do not report:
+
+- Responses with explicit field selection (serializers, `only:`, `except:`)
+- Responses that return only public/non-sensitive fields
+- Admin-only endpoints where full data access is intended
+- Internal diagnostic endpoints behind staff auth
+- Test files (under test/ or \*\_test.rb)
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/REQUEST_DERIVED_SHOP_SCOPE.md b/packages/app/src/cli/services/app-doctor-engine/checks/REQUEST_DERIVED_SHOP_SCOPE.md
new file mode 100644
index 00000000000..4374edd3cd1
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/REQUEST_DERIVED_SHOP_SCOPE.md
@@ -0,0 +1,122 @@
+---
+id: REQUEST_DERIVED_SHOP_SCOPE
+version: 2
+tier: agentic
+severity: high
+---
+
+Find cases where a shop identifier comes from request input (form data,
+query params, headers) instead of the authenticated session, and is used
+to scope a database query or select an Admin API context.
+
+The key insight: a shop filter that uses an attacker-controlled value is
+no filter at all. The attacker can pass any shop's identifier and access
+that shop's data. This is distinct from `MISSING_TENANT_ISOLATION` (no
+shop filter at all) — here the filter or context selection exists, but
+the value comes from the request, not the session.
+
+This bug appears in two forms:
+
+**Form 1: Database query scoped by request input.**
+
+```ruby
+# Rails — shop_id from params, not session
+Token.where(shop_id: params[:shop_id]).delete_all
+Order.find_by(shop_id: params[:shop])
+```
+
+**Form 2: Admin API context selected by request input.**
+
+```typescript
+// Remix — shop from formData, not session
+const shop = formData.get("shop");
+const { admin } = await unauthenticated.admin(shop);
+// Now admin is scoped to whatever shop the caller passed
+```
+
+Both are the same vulnerability: the caller chooses which shop's data to
+access. In Form 1, the query filter is attacker-controlled. In Form 2,
+the Admin API context is attacker-controlled. `unauthenticated.admin()`
+deliberately takes a shop parameter (it's for offline/background jobs),
+so using it with request input is an IDOR — the caller selects the shop.
+
+## What to look for
+
+1. **Find database queries that filter on a shop/tenant column.** Search for:
+   - `where(shop_id:`, `where(shop:`, `where(store_id:`, `where(tenant_id:`
+   - `.find_by(shop_id:`, `.find_or_initialize_by(shop_id:`
+
+2. **Find `unauthenticated.admin()` calls.** Search for:
+   - `unauthenticated.admin(` — this function takes a shop domain/id as
+     its argument. If that argument comes from request input, it's an IDOR.
+   - `unauthenticated.admin(shop)` where `shop` is traced to `formData.get()`,
+     `request.json()`, `url.searchParams.get()`, `params.shop`, etc.
+
+3. **Trace the shop value for every query or admin context call.** Determine
+   where it comes from:
+   - `params[:shop_id]`, `formData.get("shop")`, `url.searchParams.get("shop")`
+     — request input, attacker-controlled
+   - `request.headers["X-Shopify-Shop-Domain"]` — header, attacker-controlled
+   - `session.shop`, `current_shop.shop_id`, `shop.shop_id` — session-derived,
+     safe
+   - A local variable — trace it back to its assignment
+
+4. **Check for compensating controls.** The shop value may be safe even
+   if it comes from params, IF there's a prior verification:
+   - An HMAC signature on the URL (e.g., `validate_path` with a signing key)
+   - A `before_action` that validates the shop against the session
+   - A Pundit policy check
+   - The params were set by trusted backend code, not the client
+
+   Follow the control to its definition and verify it actually covers
+   this query's shop_id.
+
+5. **Check for the OAuth callback pattern.** In Shopify OAuth flows,
+   `shop_id` often comes from a signed URL that was generated by the
+   app's own backend using the session shop. The HMAC on that URL is
+   the control. This is safe — but verify the signing key isn't
+   hardcoded or leaked.
+
+6. **Distinguish `authenticate.admin` from `unauthenticated.admin`.**
+   `authenticate.admin(request)` derives the shop from the session — safe.
+   `unauthenticated.admin(shop)` takes the shop as an argument — only safe
+   if the argument is session-derived or verified, NOT if it comes from
+   request input.
+
+## What to report
+
+For each query or admin context call where the shop value is
+attacker-controlled with no compensating control:
+
+```json
+{
+  "file": "app/routes/api.orders.ts",
+  "line": 6,
+  "message": "Shop from formData passed to unauthenticated.admin() — IDOR",
+  "snippet": "const shop = formData.get(\"shop\"); const { admin } = await unauthenticated.admin(shop);",
+  "evidence": [
+    {
+      "file": "app/routes/api.orders.ts",
+      "line": 5,
+      "quote": "const shop = formData.get(\"shop\")"
+    },
+    {
+      "file": "app/routes/api.orders.ts",
+      "line": 6,
+      "quote": "unauthenticated.admin(shop)"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "Shop comes from formData (request input) and is passed to unauthenticated.admin(). No session verification. An attacker can set shop to any value and access that shop's Admin API context."
+}
+```
+
+Do not report:
+
+- Calls to `authenticate.admin(request)` — the shop comes from the
+  session, not from request input
+- Queries where shop_id comes from `current_shop`, `session.shop`, or
+  other session-derived sources
+- Queries guarded by an HMAC signature (verify the signature check first)
+- Queries on the Shop model itself (looking up a shop by id is normal)
+- Queries in webhook handlers (the HMAC verification covers the payload)
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/SCOPE_OVER_REQUEST.md b/packages/app/src/cli/services/app-doctor-engine/checks/SCOPE_OVER_REQUEST.md
new file mode 100644
index 00000000000..5c8a2d1386a
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/SCOPE_OVER_REQUEST.md
@@ -0,0 +1,90 @@
+---
+id: SCOPE_OVER_REQUEST
+version: 1
+tier: agentic
+severity: high
+---
+
+Find cases where an app requests OAuth scopes it does not use, or uses
+scopes in ways that exceed what the merchant authorised.
+
+When a merchant installs an app, they grant a set of access scopes (e.g.
+`read_orders`, `write_products`). The app should only access data covered
+by those scopes. Two risks:
+
+1. **Over-requested scopes:** the app declares scopes in its config that it
+   never references in code. This is a privacy violation — the merchant
+   granted access to data the app doesn't need.
+
+2. **Under-verified usage:** the app calls an API endpoint that requires a
+   scope, but doesn't check that the scope was granted before making the
+   call. This can fail at runtime or, worse, access data the merchant
+   didn't authorise if the scope was added by a different code path.
+
+## What to look for
+
+1. **Find the declared scopes.** Look in `shopify.app.toml` under
+   `[access_scopes]` → `scopes`, or in the app's OAuth redirect URL, or
+   in environment variables like `SCOPES`.
+
+2. **Find where scopes are used.** Search for API calls that reference
+   Shopify resources: `admin.rest.get`, `admin.graphql`, REST resource
+   classes, GraphQL queries on `orders`, `products`, `customers`, etc.
+
+3. **Match scopes to usage.** Each scope should map to at least one API
+   call:
+   - `read_orders` → queries on orders
+   - `write_products` → mutations on products
+   - `read_customers` → queries on customers
+   - etc.
+
+4. **Flag scopes with no matching usage.** If `read_analytics` is declared
+   but no code references analytics, that's an over-requested scope.
+
+5. **Flag API calls with no matching scope.** If code queries customers
+   but `read_customers` isn't declared, that's an under-verified usage.
+
+## What to report
+
+```json
+{
+  "file": "shopify.app.toml",
+  "line": 10,
+  "message": "Scope 'read_analytics' is declared but never referenced in app code",
+  "evidence": [
+    {
+      "file": "shopify.app.toml",
+      "line": 10,
+      "quote": "scopes = \"read_orders,read_analytics\""
+    }
+  ],
+  "confidence": "medium",
+  "reasoning": "Searched all source files for 'analytics' and found no API calls referencing analytics endpoints or resources."
+}
+```
+
+For under-verified usage, report the code location, not the TOML:
+
+```json
+{
+  "file": "app/services/customer_export.rb",
+  "line": 15,
+  "message": "Queries customers but 'read_customers' is not in declared scopes",
+  "evidence": [
+    {
+      "file": "app/services/customer_export.rb",
+      "line": 15,
+      "quote": "Customer.all"
+    },
+    {
+      "file": "shopify.app.toml",
+      "line": 10,
+      "quote": "scopes = \"read_orders\""
+    }
+  ],
+  "confidence": "high"
+}
+```
+
+Note: if the app has zero source files (config-only app), do not report
+over-requested scopes — you cannot verify usage from an empty corpus.
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/SCRIPT_TAG_URL_INJECTION.md b/packages/app/src/cli/services/app-doctor-engine/checks/SCRIPT_TAG_URL_INJECTION.md
new file mode 100644
index 00000000000..3a2e68a40ce
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/SCRIPT_TAG_URL_INJECTION.md
@@ -0,0 +1,81 @@
+---
+id: SCRIPT_TAG_URL_INJECTION
+version: 1
+tier: agentic
+severity: critical
+---
+
+Find cases where the ScriptTag API is used with a URL derived from user
+input, allowing an attacker to inject arbitrary scripts into every
+merchant's storefront.
+
+The ScriptTag API injects a `<script>` tag into the merchant's
+storefront. If the `src` URL comes from user input (settings, params,
+metafields), an attacker can point the script at any URL — a
+compromised server, a malicious CDN, or a data URI with inline script.
+
+Using ScriptTags at all is deprecated (theme app extensions should be
+used instead). But using them with user-controlled URLs is an active
+injection vector, not just a deprecation issue.
+
+## What to look for
+
+1. **Find all ScriptTag API calls.** Search for:
+   - GraphQL: `scriptTagCreate`, `scriptTagUpdate`, `scriptTagsCreate`
+   - REST: `ScriptTag.create`, `POST /admin/api/.../script_tags.json`
+   - Ruby: `ShopifyAPI::ScriptTag.new`, `script_tag.create!`
+   - Any code that creates or updates a script tag
+
+2. **Trace the `src` URL.** For each ScriptTag call, determine where
+   the `src` argument comes from:
+   - `params[:url]`, `formData.get("url")`, `request.json().url` —
+     user-controlled, injection vector
+   - A settings field that the merchant can edit — user-controlled
+   - A metafield value — merchant-writable, user-controlled
+   - A hardcoded URL (`"https://cdn.myapp.com/widget.js"`) — not
+     user-controlled, but still deprecated
+   - A variable — trace it back to its assignment
+
+3. **Check for URL validation.** Even if the URL comes from user input,
+   it may be safe if:
+   - The URL is validated against an allowlist of domains
+   - The URL scheme is restricted to https
+   - The URL is a relative path on the app's own domain
+
+4. **Check for event handler payloads.** ScriptTags can also include
+   `event` and `cache` parameters. If these come from user input, they
+   can be used to control when the script loads and how it's cached.
+
+## What to report
+
+For each ScriptTag with a user-controlled `src` URL:
+
+```json
+{
+  "file": "app/services/script_tag_manager.rb",
+  "line": 15,
+  "message": "ScriptTag created with src URL from merchant-configurable setting — injection vector",
+  "snippet": "ScriptTag.create(src: shop_setting.script_url)",
+  "evidence": [
+    {
+      "file": "app/services/script_tag_manager.rb",
+      "line": 15,
+      "quote": "ScriptTag.create(src: shop_setting.script_url)"
+    },
+    {
+      "file": "app/models/shop_setting.rb",
+      "line": 8,
+      "quote": "field :script_url, :string (merchant-configurable)"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The ScriptTag src URL comes from a merchant-configurable setting with no allowlist or domain validation. An attacker who controls the setting can inject a script from any URL into every installed merchant's storefront."
+}
+```
+
+Do not report:
+
+- ScriptTags with hardcoded URLs (deprecated but not an injection vector)
+- ScriptTags where the URL is validated against an allowlist
+- ScriptTags in test files
+- Code that only reads existing ScriptTags (no create/update)
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/SSRF_REQUEST_FORGERY.md b/packages/app/src/cli/services/app-doctor-engine/checks/SSRF_REQUEST_FORGERY.md
new file mode 100644
index 00000000000..f7ab91b9374
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/SSRF_REQUEST_FORGERY.md
@@ -0,0 +1,94 @@
+---
+id: SSRF_REQUEST_FORGERY
+version: 1
+tier: agentic
+severity: high
+---
+
+Find cases where the app makes server-side HTTP requests to URLs
+derived from user input, allowing an attacker to target internal
+services or third-party APIs (Server-Side Request Forgery).
+
+SSRF occurs when an application takes a URL from user input (form data,
+query params, API payload) and fetches it server-side. An attacker can
+use this to reach internal services, cloud metadata endpoints, or
+third-party APIs that are only accessible from the server's network.
+
+A related pattern is command injection — where user input flows into
+`exec()`, `system()`, or shell commands without sanitisation.
+
+## What to look for
+
+1. **Find server-side HTTP calls.** Search for:
+   - Rails: `HTTParty.get(url)`, `Net::HTTP.get(url)`, `Faraday.get(url)`,
+     `open(url)`, `URI.parse(url)`, `HTTP.get(url)`
+   - Remix/Node: `fetch(url)`, `axios.get(url)`, `http.get(url)`,
+     `https.get(url)`, `request(url)`
+   - PHP: `file_get_contents(url)`, `curl_exec($ch)`, `Guzzle::get(url)`
+   - Python: `requests.get(url)`, `urllib.request.urlopen(url)`
+
+2. **Trace the URL.** For each HTTP call, determine where the URL comes
+   from:
+   - `params[:url]`, `formData.get("url")`, `request.json().url` —
+     user-controlled, SSRF risk
+   - `request.headers["X-Callback-URL"]` — header, user-controlled
+   - A database record — check if the record was set by user input
+   - A config constant — safe
+   - A variable — trace it back to its assignment
+
+3. **Check for SSRF protections.** The call may be safe even with user
+   input if:
+   - The URL is validated against an allowlist of domains
+   - The URL is parsed and internal IPs are blocked (169.254.169.254,
+     localhost, 10.x.x.x, 192.168.x.x, etc.)
+   - The URL scheme is restricted to https only
+
+4. **Find command injection.** Search for:
+   - Ruby: `system(cmd)`, `exec(cmd)`, `Open3.capture3(cmd)`,
+     backticks `#{cmd}`, `IO.popen(cmd)`
+   - Node: `exec(cmd)`, `execSync(cmd)`, `spawn(cmd)`, `child_process`
+   - PHP: `system()`, `exec()`, `shell_exec()`, `passthru()`, backticks
+   - Python: `os.system()`, `subprocess.run()`, `os.popen()`
+
+   Trace the command argument — if it contains user input without
+   shell escaping, it's command injection.
+
+5. **Find GraphQL query injection.** Search for:
+   - String concatenation building a GraphQL query: `"query { " + field + " }"`
+   - Template literals with user input: `` `query { ${userField} }` ``
+   - User input in query variables that aren't typed/validated
+
+## What to report
+
+For each HTTP call, command, or query where user input flows in without
+validation:
+
+```json
+{
+  "file": "app/services/webhook_forwarder.rb",
+  "line": 15,
+  "message": "Server-side HTTP request to user-supplied URL — SSRF",
+  "snippet": "HTTParty.get(params[:callback_url])",
+  "evidence": [
+    {
+      "file": "app/services/webhook_forwarder.rb",
+      "line": 15,
+      "quote": "HTTParty.get(params[:callback_url])"
+    },
+    {
+      "file": "app/services/webhook_forwarder.rb",
+      "line": 10,
+      "quote": "params[:callback_url]"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The URL comes from params[:callback_url] (user-controlled) and is fetched server-side with no allowlist or internal-IP filtering. An attacker can target internal services."
+}
+```
+
+Do not report:
+
+- HTTP calls to hardcoded URLs (`fetch("https://api.shopify.com/...")`)
+- HTTP calls where the URL is validated against an allowlist
+- `exec()` with literal strings (no user input)
+- Shell calls with properly escaped arguments
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/TEXT_SETTING_HTML_SMUGGLING.md b/packages/app/src/cli/services/app-doctor-engine/checks/TEXT_SETTING_HTML_SMUGGLING.md
new file mode 100644
index 00000000000..961526d84b8
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/TEXT_SETTING_HTML_SMUGGLING.md
@@ -0,0 +1,97 @@
+---
+id: TEXT_SETTING_HTML_SMUGGLING
+version: 1
+tier: agentic
+severity: high
+---
+
+Find cases where merchant-configurable text settings are rendered as HTML
+without sanitisation, allowing HTML to be smuggled past custom-JS detection.
+
+Many apps have settings fields where merchants can enter custom text —
+header text, banner content, widget titles, custom CSS, "additional
+HTML" fields. If the app renders these settings as raw HTML server-side
+or in Liquid, the merchant can inject arbitrary HTML including script
+tags, iframes, or event handlers.
+
+This is distinct from `UNSAFE_INNERHTML` (which targets JavaScript
+DOM writes). HTML smuggling via text settings bypasses custom-JS detection
+because the HTML is rendered server-side or in Liquid, not via
+`innerHTML` in JavaScript. A scanner looking for `innerHTML` will miss it.
+
+## What to look for
+
+1. **Find text/settings fields that accept arbitrary input.** Search for:
+   - Rails: settings models, `ShopSetting`, `AppConfig`, preference columns
+     that store text/HTML
+   - Remix: settings mutations that store text in metafields or app data
+   - Liquid: theme settings schema with text fields (`"type": "text"`,
+     `"type": "richtext"`)
+   - Any field named `header_html`, `custom_html`, `banner_text`,
+     `additional_script`, `tracking_code`
+
+2. **Trace where the setting value is rendered.** For each setting:
+   - Rails: `render html: setting.value`, `render(inline: setting.value)`,
+     `<%= raw setting.value %>`, `setting.value.html_safe`
+   - Liquid: `{{ setting.value | raw }}`, `{{ setting.value }}` in a
+     context where the content type is `text/html` (not `text/plain`)
+   - JavaScript: if the setting value flows into `innerHTML` — this
+     overlaps with `UNSAFE_INNERHTML` but the entry point is a settings
+     field, not a URL param
+   - React: `dangerouslySetInnerHTML` where the HTML comes from a
+     settings/metafield value
+
+3. **Check whether the setting is merchant-configurable.** The key
+   question is: can the merchant (or an attacker who compromised the
+   merchant account) control this value?
+   - If the value is set by the app developer in code — not user-controlled
+   - If the value is set by the merchant through a settings UI — user-controlled
+   - If the value is stored in a metafield that the merchant can edit — user-controlled
+   - If the value comes from a product/customer metafield — user-controlled
+
+4. **Check for sanitisation.** Is the setting value sanitised before
+   rendering?
+   - `sanitize_html(setting.value)` or equivalent
+   - Content type set to `text/plain` instead of `text/html`
+   - Liquid auto-escape (no `| raw` filter)
+   - Allowlist of permitted HTML tags
+
+5. **Look for richtext settings.** Theme extension settings with
+   `"type": "richtext"` are designed to accept HTML — but if the app
+   renders them without sanitisation in a context where script execution
+   is possible, it's still a vulnerability.
+
+## What to report
+
+For each setting rendered as HTML without sanitisation:
+
+```json
+{
+  "file": "app/controllers/settings_controller.rb",
+  "line": 20,
+  "message": "Merchant-configurable header_text setting rendered as raw HTML",
+  "snippet": "render html: shop_setting.header_text",
+  "evidence": [
+    {
+      "file": "app/controllers/settings_controller.rb",
+      "line": 20,
+      "quote": "render html: shop_setting.header_text"
+    },
+    {
+      "file": "app/models/shop_setting.rb",
+      "line": 5,
+      "quote": "field :header_text, :text (merchant-configurable)"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The header_text setting is merchant-configurable and rendered as raw HTML without sanitisation. A merchant (or attacker who compromised the merchant account) can inject arbitrary HTML including script tags."
+}
+```
+
+Do not report:
+
+- Settings rendered as `text/plain` (no HTML parsing)
+- Settings that are developer-configured constants (not merchant-editable)
+- Settings with explicit HTML sanitisation (`sanitize_html`, allowlist)
+- Liquid `{{ setting }}` without `| raw` (auto-escaped)
+- Test files
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/THEME_EXTENSION_XSS.md b/packages/app/src/cli/services/app-doctor-engine/checks/THEME_EXTENSION_XSS.md
new file mode 100644
index 00000000000..9166117159e
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/THEME_EXTENSION_XSS.md
@@ -0,0 +1,94 @@
+---
+id: THEME_EXTENSION_XSS
+version: 1
+tier: agentic
+severity: critical
+---
+
+Find cases where theme app extensions render user-controlled data
+without escaping, creating XSS vulnerabilities in the merchant's
+storefront.
+
+Theme app extensions render Liquid in the merchant's storefront. If
+the Liquid renders user-controlled data (metafields, product data,
+customer input, URL parameters) without proper escaping, an attacker
+can inject script that executes on the merchant's store — affecting
+every visitor to that store.
+
+This is distinct from `UNSAFE_INNERHTML` (which targets JavaScript
+DOM writes). Theme extension XSS happens in Liquid, server-side,
+through Shopify's rendering pipeline. The entry point is a Liquid
+template, not a JavaScript file.
+
+## What to look for
+
+1. **Find all Liquid files in theme app extensions.** Search for:
+   - `*.liquid` files under `extensions/` or `theme-app-extension/`
+   - Liquid blocks, snippets, sections
+   - Theme extension entry points
+
+2. **Find `| raw` filter usage.** The `raw` filter bypasses Liquid's
+   auto-escaping:
+   - `{{ variable | raw }}` — renders unescaped HTML
+   - `{{ variable | raw }}` where variable is user-controlled — XSS
+   - Check whether the variable is proven trusted HTML (e.g. a constant
+     or app-generated content) or user-controlled
+
+3. **Trace Liquid data sources.** For each `{{ }}` output, determine
+   where the data comes from:
+   - `{{ product.metafield.custom.field }}` — merchant-writable, user-controlled
+   - `{{ customer.metafield.app.value }}` — customer-editable in some apps
+   - `{{ variant.metafield.custom.html }}` — could contain malicious HTML
+   - `{{ request.params.x }}` — URL parameter, user-controlled
+   - `{{ shop.metafield.app.config }}` — merchant-configurable
+   - `{{ block.settings.text }}` — theme settings, merchant-configurable
+   - `{{ app.metafield.namespace.key }}` — app metafield, could be
+     merchant-writable depending on permissions
+
+4. **Check Liquid rendering context.** Liquid auto-escapes `{{ }}`
+   output, but there are exceptions:
+   - `| raw` — bypasses escaping entirely
+   - `{% liquid %}` blocks with `echo` — auto-escaped
+   - `{% render %}` with `{{ }}` inside the rendered snippet — escaped,
+     but check the snippet's own output
+   - JSON responses with `{{ }}` — escaped for JSON, not for HTML context
+
+5. **Find JavaScript in theme extensions.** Theme extension assets
+   (`.js` files) that:
+   - Read from the DOM (URL params, metafield values rendered in hidden
+     elements) and write to innerHTML — overlaps with `UNSAFE_INNERHTML`
+   - Use `postMessage` with unvalidated origin — can receive XSS payloads
+     from other windows
+   - Read `window.Shopify` data that includes merchant-editable fields
+
+## What to report
+
+For each Liquid template or JS file that renders user-controlled data
+without escaping:
+
+```json
+{
+  "file": "extensions/theme-app-extension/blocks/widget.liquid",
+  "line": 15,
+  "message": "Metafield value rendered with | raw filter — XSS in storefront",
+  "snippet": "{{ product.metafield.custom.html | raw }}",
+  "evidence": [
+    {
+      "file": "extensions/.../blocks/widget.liquid",
+      "line": 15,
+      "quote": "{{ product.metafield.custom.html | raw }}"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The metafield value is merchant-writable (user-controlled) and rendered with the raw filter, bypassing Liquid's auto-escaping. An attacker who controls the metafield can inject script that executes on the merchant's storefront."
+}
+```
+
+Do not report:
+
+- `{{ variable }}` without `| raw` (auto-escaped by Liquid)
+- `{{ variable | raw }}` where the variable is a constant or app-generated
+  trusted HTML
+- `{{ variable | escape }}` or `{{ variable | escape_once }}` (escaped)
+- JavaScript `textContent` assignments (safe)
+- Test files
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/UNAUTHENTICATED_ENDPOINT.md b/packages/app/src/cli/services/app-doctor-engine/checks/UNAUTHENTICATED_ENDPOINT.md
new file mode 100644
index 00000000000..432f1c8f4c5
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/UNAUTHENTICATED_ENDPOINT.md
@@ -0,0 +1,93 @@
+---
+id: UNAUTHENTICATED_ENDPOINT
+version: 2
+tier: agentic
+severity: high
+---
+
+Find controller actions or route handlers that process requests without
+verifying the caller's identity or authority.
+
+An unauthenticated endpoint in a Shopify app is one where a request from
+outside the merchant's session — another app, a scraper, an attacker — can
+reach a handler that reads or modifies shop data. Authentication in Shopify
+apps comes in several forms, and the right one depends on the entry point:
+
+- **Embedded app pages** use `authenticate.admin(request)` (Remix) or
+  `ShopifyApp::EnsureHasSession` (Rails). The session is validated by a
+  JWT or session cookie.
+- **Webhooks** are verified by HMAC signature
+  (`ShopifyApp::WebhookVerification`, `@shopify/webhook-processer`).
+- **App proxies** are verified by signature query parameters.
+- **Service-to-service** endpoints use bearer tokens or mTLS.
+
+A handler is unauthenticated if none of these apply AND the handler
+accesses shop-scoped data. A public endpoint that returns static content
+is not a finding.
+
+## What to look for
+
+1. **Find every route handler.** In Rails, these are controller actions
+   (methods in a controller class). In Remix/Express, these are loader
+   and action exports, or route handlers. In PHP, these are controller
+   methods or route closures.
+
+2. **For each handler, check whether authentication is applied.** Look for:
+   - A `before_action` / `beforeAction` / middleware that validates the
+     session (often inherited from a parent controller — follow the chain)
+   - An `authenticate.admin(request)` call in a Remix loader/action
+   - An HMAC verification for webhook/proxy endpoints
+   - A bearer token check for service endpoints
+
+3. **Follow inheritance.** A controller with no visible `before_action`
+   may inherit one from `ApplicationController` or a parent. Read the
+   parent class before flagging.
+
+4. **Check for `skip_idor_protection` or `protect_from_forgery` exceptions.**
+   These are explicit opt-outs — the author chose to skip a protection.
+   Determine whether the remaining auth (if any) is sufficient.
+
+5. **Check for the try/catch fallback pattern:**
+   ```js
+   try {
+     authenticate.admin(request);
+   } catch {
+     url.searchParams.get("shop");
+   }
+   ```
+   This looks authenticated but falls back to user input on failure — the
+   catch block bypasses auth entirely. This is a real finding.
+
+## What to report
+
+For each genuinely unauthenticated handler that accesses shop data:
+
+```json
+{
+  "file": "app/controllers/...",
+  "line": 42,
+  "message": "Controller action processes shop data with no auth verification",
+  "snippet": "def export\n  Order.all.to_csv\nend",
+  "evidence": [
+    { "file": "path", "line": 12, "quote": "the line showing no auth" },
+    {
+      "file": "path",
+      "line": 5,
+      "quote": "class FooController < ApplicationController (no before_action in parent)"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "why this handler is reachable without authentication"
+}
+```
+
+Do not report:
+
+- Public endpoints that return static content (health checks, app metadata)
+- Handlers protected by inherited `before_action` (verify the parent first)
+- Webhook/proxy handlers with HMAC verification
+- Test controllers or development-only routes
+
+Every finding must cite the file and line where you determined auth is
+absent. If you couldn't read the parent controller, say so — do not assume
+auth is missing.
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/UNSAFE_INNERHTML.md b/packages/app/src/cli/services/app-doctor-engine/checks/UNSAFE_INNERHTML.md
new file mode 100644
index 00000000000..5911a42dea3
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/UNSAFE_INNERHTML.md
@@ -0,0 +1,110 @@
+---
+id: UNSAFE_INNERHTML
+version: 3
+tier: agentic
+severity: critical
+---
+
+Find cases where user-controlled data is written to the DOM without
+sanitisation, creating a cross-site scripting (XSS) vulnerability.
+
+XSS in a Shopify app is particularly dangerous because the app runs
+inside the admin iframe. A script injection can access the merchant's
+session, make API calls on their behalf, or exfiltrate data.
+
+## What to look for
+
+1. **Find all DOM write calls.** Search for every pattern that parses
+   HTML, not just innerHTML:
+   - `element.innerHTML = ...`
+   - `element.outerHTML = ...`
+   - `element.insertAdjacentHTML(position, ...)`
+   - `document.write(...)`
+   - `document.writeln(...)`
+   - `eval(...)` — code injection, not HTML, but same attacker entry point
+   - `setTimeout(string, ...)` / `setInterval(string, ...)` — evals string
+   - `new Function(string)` — evals string
+
+2. **Find React/Vue dangerous rendering.** These frameworks auto-escape
+   string interpolation, but have explicit escape hatches:
+   - `dangerouslySetInnerHTML={{ __html: ... }}` — React
+   - `v-html="..."` — Vue
+   - Any prop or attribute named `html` that receives raw HTML
+
+3. **Find Liquid unsafe rendering.** In theme app extensions:
+   - `{{ variable }}` — safe (auto-escaped)
+   - `{{ variable | raw }}` — unsafe (bypasses escaping)
+   - `{{ variable | escape_once }}` — partially safe
+
+4. **Trace the data source.** For each write, determine what's being
+   inserted. User-controlled sources include:
+   - URL parameters: `searchParams`, `URLSearchParams`, `params`
+   - Form input: `formData`, `request.json()`
+   - **Metafield values**: `product.metafield.value`,
+     `metafield.namespace.key`, `metafieldsSet` responses
+     — these are merchant-writable, so they are user-controlled even
+     though they look like app config
+   - GraphQL responses: product titles, customer names, review text
+   - API responses that include merchant-editable fields
+   - A literal string — not a finding
+   - A config constant — not user-controlled, not a finding
+
+5. **Check for sanitisation.** Is the data passed through:
+   - `DOMPurify.sanitize(...)` — but verify it handles event handler
+     attributes (onerror, onload, onfocus, onclick), not just tag removal
+   - `escapeHTML(...)` or a similar escaping function
+   - A textContent assignment instead (safe — textContent doesn't parse HTML)
+
+## XSS evasion patterns to check for
+
+When checking whether sanitisation is adequate, consider these evasion
+techniques that bypass naive string-matching:
+
+- **Event handler attributes**: `<img src=x onerror="...">` — a sanitizer
+  that strips `<script>` tags but leaves `onerror` attributes is bypassable
+- **Base64-encoded payloads**: `atob("...")` decoded at runtime — evades
+  static string matching for known XSS strings
+- **Data URI payloads**: `<iframe src="data:text/html,...">`
+- **SVG payloads**: `<svg onload="...">` — some sanitizers miss SVG events
+
+If the sanitizer is a custom function (not DOMPurify or a well-known
+library), flag it — custom sanitizers are frequently bypassable.
+
+## What to report
+
+For each DOM write where user-controlled data (including metafield values)
+reaches the DOM unsanitised:
+
+```json
+{
+  "file": "extensions/.../widget.js",
+  "line": 42,
+  "message": "User-controlled metafield value rendered via innerHTML without sanitisation",
+  "snippet": "el.innerHTML = product.metafield.custom.value",
+  "evidence": [
+    {
+      "file": "extensions/.../widget.js",
+      "line": 42,
+      "quote": "el.innerHTML = product.metafield.custom.value"
+    },
+    {
+      "file": "extensions/.../widget.js",
+      "line": 30,
+      "quote": "const metafield = await admin.rest.get({ path: 'metafields' })"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The metafield value is merchant-writable (user-controlled) and is inserted into innerHTML without DOMPurify or equivalent sanitisation. An attacker who controls the metafield value can inject script tags that execute in the storefront."
+}
+```
+
+Do not report:
+
+- Literal HTML strings (`el.innerHTML = "<b>Static</b>"`)
+- `textContent` assignments (safe — no HTML parsing)
+- React JSX with string interpolation (auto-escaped)
+- `dangerouslySetInnerHTML` with static/constant content (still risky but
+  if the content is a constant string, there's no XSS vector from user input)
+- Sanitised inputs (`DOMPurify.sanitize(userInput)`) — unless the sanitizer
+  is custom and might miss event handler attributes
+- `eval()` or `new Function()` with literal strings (no user input)
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/UNSCOPED_SHOP_CONFIG_WRITE.md b/packages/app/src/cli/services/app-doctor-engine/checks/UNSCOPED_SHOP_CONFIG_WRITE.md
new file mode 100644
index 00000000000..62f5cd31882
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/UNSCOPED_SHOP_CONFIG_WRITE.md
@@ -0,0 +1,78 @@
+---
+id: UNSCOPED_SHOP_CONFIG_WRITE
+version: 1
+tier: agentic
+severity: high
+---
+
+Find configuration writes where the target shop is determined by request
+input rather than the authenticated session, allowing an attacker to
+modify another shop's configuration.
+
+Some apps write per-shop configuration — metafields, app settings,
+webhook subscriptions. The target shop must come from the authenticated
+session, not from the request body or query string. If an attacker can
+control the target shop, they can write to another merchant's config.
+
+## What to look for
+
+1. **Find configuration write calls.** Search for:
+   - GraphQL mutations: `metafieldsSet`, `metafieldUpdate`, `appUpdate`,
+     `webhookSubscriptionCreate`, `webhookSubscriptionUpdate`
+   - REST writes: `admin.rest.put`, `admin.rest.post`
+   - Rails: `.save`, `.update`, `.create` on config models
+   - Any write that takes a shop identifier as a parameter
+
+2. **Trace the shop identifier.** For each write, determine where the
+   target shop comes from:
+   - `params[:shop_id]`, `request.body.shop`, `url.searchParams.get('shop')`
+     — request input, attacker-controlled
+   - `session.shop`, `current_shop.shop_id`, `authenticate.admin(request)`
+     — session-derived, safe
+   - A variable — trace it back
+
+3. **Check for session verification.** Is `authenticate.admin(request)`
+   called in this handler? Is there a `before_action` that establishes
+   the session? If the shop comes from the session, it's safe.
+
+4. **Check the Remix pattern.** In Remix apps, the admin context comes
+   from `authenticate.admin(request)`, which returns `{ admin, session }`.
+   The shop is `session.shop`. If code instead reads `shop` from the
+   request body and passes it to `unauthenticated.admin(shop)`, that's
+   the vulnerability — `unauthenticated.admin` doesn't verify the caller.
+
+## What to report
+
+```json
+{
+  "file": "app/routes/api.update-settings.ts",
+  "line": 20,
+  "message": "Configuration write targets shop from request body without session verification",
+  "snippet": "const shop = await request.json().then(d => d.shop)",
+  "evidence": [
+    {
+      "file": "path",
+      "line": 20,
+      "quote": "const shop = await request.json().then(d => d.shop)"
+    },
+    {
+      "file": "path",
+      "line": 25,
+      "quote": "await admin.rest.put({ path: 'metafields', shop })"
+    },
+    {
+      "file": "path",
+      "line": 1,
+      "quote": "no authenticate.admin(request) call found"
+    }
+  ],
+  "confidence": "high",
+  "reasoning": "The target shop comes from the request body and is passed to a configuration write. No session verification is present, so an attacker can write to any shop's config."
+}
+```
+
+Do not report:
+
+- Writes where the shop comes from `authenticate.admin(request)` session
+- Writes where the shop comes from an HMAC-verified webhook payload
+- Test handlers
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/embedded.ts b/packages/app/src/cli/services/app-doctor-engine/checks/embedded.ts
new file mode 100644
index 00000000000..7de4eb43ddb
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/embedded.ts
@@ -0,0 +1,22 @@
+// AUTO-GENERATED by app-doctor-engine/embed-checks.mjs — do not edit.
+// Source of truth: adjacent checks/*.md files.
+
+// prettier-ignore
+export const EMBEDDED_CHECK_SOURCES: readonly string[] = [
+  "---\nid: APP_PROXY_UNVERIFIED_SIGNATURE\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind app proxy endpoints that read proxy parameters without verifying\nthe Shopify signature, allowing an attacker to impersonate Shopify and\nsend fake proxy requests.\n\nApp proxies let an app serve content directly on the merchant's store\nvia a URL like `https://shop.example.com/apps/my-app/proxy`. Shopify\nsigns every proxy request with an HMAC using the app's shared secret.\nIf the app doesn't verify this signature, anyone can send requests to\nthe proxy endpoint with forged parameters — including `shop`,\n`logged_in_customer_id`, and `path_prefix`.\n\n## What to look for\n\n1. **Find app proxy route handlers.** These are endpoints configured as\n   app proxies in `shopify.app.toml` under `[app_proxy]` or in the app's\n   routing config. They typically read parameters like:\n   - `shop` or `shop_id`\n   - `logged_in_customer_id`\n   - `path_prefix`\n   - `signature`\n   - `timestamp`\n\n2. **Check for signature verification.** The handler must verify the\n   HMAC signature before trusting any proxy parameter. Look for:\n   - **Remix:** `authenticate.public.appProxy(request)` — the official\n     verification function\n   - **Rails:** `verified_request?` or manual HMAC verification using\n     `ShopifyApp` utilities\n   - **Express:** Manual HMAC verification using the app secret\n   - **PHP:** `ShopifyUtils::verifyProxyRequest()` or equivalent\n\n3. **If no verification is present, check whether the handler:**\n   - Reads `shop` from the query string and uses it to scope data\n   - Reads `logged_in_customer_id` and uses it for authorisation\n   - Returns any shop-specific data\n\n   If any of these are true and there's no signature check, it's a real\n   finding.\n\n4. **Check for the HMAC pattern even if the function name isn't obvious.**\n   Some apps implement custom verification:\n   - `crypto.createHmac('sha256', API_SECRET)`\n   - `OpenSSL::HMAC.digest`\n   - `hash_hmac('sha256', ...)`\n   - Comparison with `timingSafeEqual` or `secure_compare`\n\n## What to report\n\nFor each proxy handler that reads shop/customer parameters without\nsignature verification:\n\n```json\n{\n  \"file\": \"app/routes/proxy.ts\",\n  \"line\": 15,\n  \"message\": \"App proxy handler reads shop parameter without signature verification\",\n  \"snippet\": \"const shop = url.searchParams.get('shop')\",\n  \"evidence\": [\n    {\n      \"file\": \"app/routes/proxy.ts\",\n      \"line\": 15,\n      \"quote\": \"const shop = url.searchParams.get('shop')\"\n    },\n    {\n      \"file\": \"app/routes/proxy.ts\",\n      \"line\": 1,\n      \"quote\": \"no authenticate.public.appProxy or HMAC verification found\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The handler reads the shop parameter from the query string and uses it to query shop data, but no signature verification is present. An attacker can send requests with any shop parameter.\"\n}\n```\n\nDo not report:\n\n- Handlers that call `authenticate.public.appProxy(request)` (Remix)\n- Handlers with manual HMAC verification\n- Handlers that return only static content (no shop-specific data)\n- Test handlers\n",
+  "---\nid: CSRF_MISSING_PROTECTION\nversion: 1\ntier: agentic\nseverity: medium\n---\n\nFind state-changing endpoints (POST, PUT, DELETE, PATCH) that don't\nverify CSRF protection, allowing an attacker to forge requests on\nbehalf of an authenticated user.\n\nCSRF (Cross-Site Request Forgery) occurs when an app accepts\nstate-changing requests without checking that the request came from\nthe app's own UI. In Shopify apps, embedded apps use session tokens\n(JWT) that provide some CSRF protection, but server-rendered apps and\napp proxies still need explicit CSRF checks.\n\n## What to look for\n\n1. **Find state-changing handlers.** Search for:\n   - Rails: controller actions responding to POST/PUT/PATCH/DELETE\n     (check `routes.rb` or controller method names like `create`,\n     `update`, `destroy`)\n   - Remix: `action` exports in route files\n   - Express: `app.post()`, `app.put()`, `app.delete()`\n   - PHP: form handlers, POST routes\n\n2. **Check for CSRF protection on each.** Look for:\n   - Rails: `protect_from_forgery` (default in Rails, but check for\n     `skip_forgery_protection` or `protect_from_forgery with: :null_session`)\n   - Remix: session token validation (`authenticate.admin(request)`)\n   - Express: `csurf` middleware or equivalent\n   - PHP: CSRF token in form, `VerifyCsrfToken` middleware\n\n3. **Flag explicit opt-outs.** Search for:\n   - `skip_forgery_protection` — disables CSRF entirely for a controller\n   - `protect_from_forgery with: :null_session` — used for webhooks, but\n     if on a non-webhook endpoint, CSRF is missing\n   - `skip_before_action :verify_authenticity_token` — skips the Rails\n     CSRF check\n\n4. **Distinguish webhooks from user-facing endpoints.** Webhooks use\n   HMAC verification instead of CSRF tokens — `protect_from_forgery\nwith: :null_session` is correct for webhooks. But the same pattern\n   on a user-facing POST handler is a CSRF vulnerability.\n\n5. **Check Shopify-specific patterns.** Embedded apps that use\n   `authenticate.admin(request)` get session token validation that\n   prevents CSRF. But if an action skips `authenticate.admin` and still\n   processes state changes, CSRF protection may be missing.\n\n## What to report\n\nFor each state-changing endpoint without CSRF protection:\n\n```json\n{\n  \"file\": \"app/controllers/settings_controller.rb\",\n  \"line\": 5,\n  \"message\": \"POST handler with CSRF protection disabled\",\n  \"snippet\": \"skip_forgery_protection\",\n  \"evidence\": [\n    {\n      \"file\": \"app/controllers/settings_controller.rb\",\n      \"line\": 5,\n      \"quote\": \"skip_forgery_protection\"\n    },\n    {\n      \"file\": \"app/controllers/settings_controller.rb\",\n      \"line\": 10,\n      \"quote\": \"def update\"\n    }\n  ],\n  \"confidence\": \"medium\",\n  \"reasoning\": \"The update action accepts POST requests but CSRF protection is explicitly skipped. This is not a webhook handler (no HMAC verification), so an attacker can forge a POST request from another site.\"\n}\n```\n\nDo not report:\n\n- Webhook handlers with `protect_from_forgery with: :null_session`\n  (HMAC is the CSRF protection for webhooks)\n- Endpoints protected by `authenticate.admin(request)` (session\n  token provides CSRF protection)\n- GET-only handlers (not state-changing)\n- API endpoints that use bearer token auth (not cookie-based, so\n  CSRF doesn't apply)\n- Test controllers\n",
+  "---\nid: MISSING_AUTHORIZATION_CHECK\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind controller actions or route handlers that access resources without\nchecking whether the current user is authorized to access them, beyond\nauthentication. Authentication verifies WHO you are; authorization verifies\nWHAT you can do. An app can be authenticated but still access resources\nbelonging to another merchant if authorization checks are missing.\n\nThis is distinct from `MISSING_TENANT_ISOLATION` (database query\nscoping) — this check looks for missing policy/permission checks on\nactions, even when the data access is scoped. For example, an app might\nscope queries by shop but not check whether the merchant has the right to\ndelete a resource, or whether a staff member can access admin-only\nactions.\n\n## What to look for\n\n1. **Find authorization frameworks.** Check what the app uses:\n   - Rails: Pundit (`authorize`, `policy`, `Pundit`), CanCanCan\n     (`can?`, `ability`), action_access filters\n   - Remix/Express: middleware that checks roles/permissions\n   - Custom: `before_action :check_admin`, `if current_user.can?`\n\n2. **Find actions without authorization checks.** For each controller\n   action or route handler, determine:\n   - Is there a `before_action` that checks authorization (not just\n     authentication)?\n   - Is there a Pundit `authorize` call?\n   - Is there a CanCanCan `authorize!` or `can?` check?\n   - Is there a custom permission check?\n\n3. **Check for `skip_idor_protection` or equivalent opt-outs.** These\n   disable IDOR/authorization checks. For each, determine:\n   - Is the skip justified? (e.g., public endpoint, webhook, health check)\n   - Does the skip expose a state-changing action to unauthorised users?\n   - Is there a compensating control (HMAC, session token, etc.)?\n\n4. **Check for admin-only functionality reachable by merchants.** Look for:\n   - Controllers under `admin/` namespace that don't check staff vs merchant\n   - Actions that modify app configuration without checking the caller's role\n   - Staff-only operations accessible through the merchant-facing UI\n\n5. **Check for missing object-level authorization.** Even if the query\n   is scoped by shop, does the handler verify that the specific resource\n   belongs to the current merchant?\n   - `Order.find(params[:id])` scoped by shop — but does it check the\n     merchant can access this specific order?\n   - `Product.find(params[:id])` — is there a policy check, or just\n     tenant scoping?\n\n## What to report\n\nFor each action that accesses resources without authorization checks:\n\n```json\n{\n  \"file\": \"app/controllers/orders_controller.rb\",\n  \"line\": 15,\n  \"message\": \"Destroy action has no authorization check beyond authentication\",\n  \"snippet\": \"def destroy\\n  Order.find(params[:id]).destroy\\nend\",\n  \"evidence\": [\n    {\n      \"file\": \"app/controllers/orders_controller.rb\",\n      \"line\": 15,\n      \"quote\": \"def destroy\"\n    },\n    {\n      \"file\": \"app/controllers/orders_controller.rb\",\n      \"line\": 5,\n      \"quote\": \"before_action :authenticate_user (no authorize check)\"\n    }\n  ],\n  \"confidence\": \"medium\",\n  \"reasoning\": \"The destroy action authenticates the user but does not call authorize or check a policy. Any authenticated merchant can delete any order within their shop, even if they shouldn't have delete permissions.\"\n}\n```\n\nDo not report:\n\n- Actions with explicit `authorize` / `can?` / policy checks\n- Actions protected by a `before_action` that checks authorization\n- Public endpoints (health checks, static content)\n- Webhook handlers (HMAC is the authorization)\n- Actions that only read data the merchant owns (scoped by session.shop\n  AND no object-level access control needed)\n- Internal/staff-only controllers (under `Internal::` namespace, behind\n  employee SSO like `EmployeeIdentity`, `IdentityClient`, etc.)\n- Test files (under test/ or \\*\\_test.rb)\n- Test controllers\n",
+  "---\nid: MISSING_EMBEDDED_CSP\nversion: 2\ntier: agentic\nseverity: medium\n---\n\nFind embedded Shopify apps that are missing a Content-Security-Policy\n`frame-ancestors` directive, allowing any origin to iframe the app.\n\nShopify apps run inside an iframe in the admin. Without a\n`frame-ancestors` directive in the CSP header, any website can embed the\napp in an iframe — a clickjacking risk. The attacker overlays invisible\nelements on top of the app's UI to trick the merchant into clicking\nbuttons they can't see.\n\n## What to look for\n\n1. **Determine if the app is embedded.** Check `shopify.app.toml` for\n   `app_embed` or `theme_app_extension` in the capabilities. If the app\n   is not embedded, this check does not apply.\n\n2. **Find where HTTP response headers are set.** Search for:\n   - `Content-Security-Policy` in any file\n   - `addDocumentResponseHeaders` (Shopify Remix helper)\n   - `response.headers.set`\n   - `frame-ancestors`\n   - CSP middleware configuration\n\n3. **If CSP headers are set, check for `frame-ancestors`.** The directive\n   must be present and must restrict embedding to:\n   - `https://admin.shopify.com`\n   - The authenticated shop's domain (e.g. `https://my-shop.myshopify.com`)\n\n   A wildcard `frame-ancestors *` is not safe. An absent `frame-ancestors`\n   is not safe (browsers default to allowing any origin).\n\n4. **Check for the Shopify Remix helper.** If the app uses\n   `@shopify/shopify-app-remix`, the `addDocumentResponseHeaders` function\n   sets the correct CSP automatically. If it's called, the app is safe.\n\n5. **Check for `X-Frame-Options` as a fallback.** Some apps use\n   `X-Frame-Options: ALLOW-FROM https://admin.shopify.com` instead of\n   CSP `frame-ancestors`. This is deprecated but functional in some\n   browsers. Note it but don't flag if CSP is also present.\n\n## What to report\n\nFor embedded apps with no `frame-ancestors` directive:\n\n```json\n{\n  \"file\": \"app/root.tsx\",\n  \"line\": 1,\n  \"message\": \"Embedded app has no frame-ancestors CSP directive — any origin can iframe it\",\n  \"evidence\": [\n    { \"file\": \"shopify.app.toml\", \"line\": 5, \"quote\": \"app_embed = true\" },\n    {\n      \"file\": \"app/root.tsx\",\n      \"line\": 1,\n      \"quote\": \"no addDocumentResponseHeaders or CSP header found\"\n    }\n  ],\n  \"confidence\": \"medium\",\n  \"reasoning\": \"The app declares app_embed capability but no file sets a Content-Security-Policy with frame-ancestors. Without it, any website can iframe the app.\"\n}\n```\n\nDo not report:\n\n- Non-embedded apps (no app_embed or theme_app_extension)\n- Apps that call `addDocumentResponseHeaders` (handles CSP automatically)\n- Apps with an explicit `frame-ancestors` directive in their CSP\n- Test files (under test/ or \\*\\_test.rb)\n",
+  "---\nid: MISSING_TENANT_ISOLATION\nversion: 3\ntier: agentic\nseverity: high\n---\n\nFind controller actions where a database query can read or modify a row\nbelonging to a shop other than the one making the request.\n\nThis is a multi-tenant app: every merchant's data must be isolated by\nshop. A query that doesn't filter on the current shop is a cross-tenant\nleak. Static analysis can't catch these reliably because the scoping is\noften indirect — applied by a `before_action`, inherited from a parent\ncontroller, or baked into a default scope on the model. Your job is to\nfollow those threads.\n\n## What to look for\n\nSearch for ActiveRecord queries that filter on a column other than\n`shop_id` / `shop`, or that take no tenant filter at all:\n\n```ruby\nProduct.where(id: params[:id])\nOrder.where(shopify_id: params[:order_id])\nToken.where(shop_id: params[:shop_id]).delete_all\n```\n\nThe last one looks scoped but isn't — `params[:shop_id]` comes from the\nrequest, not from the authenticated session. The caller can pass any\nshop's id.\n\n## How to investigate each candidate\n\n1. **Read the enclosing method and the whole controller.** The scope may\n   be applied on an adjacent line, or the flagged line may be a fragment\n   of a longer chain (`.or(...)`, `.merge(...)`) whose base scope is above.\n\n2. **Follow the receiver.** If the query is on a variable rather than a\n   model constant, find where it comes from. A relation passed in as a\n   method parameter may already be scoped by its caller — go look.\n\n3. **Read the controller's ancestors.** Authentication and tenant scoping\n   are usually inherited: `before_action`, `around_action`, a mixin, or a\n   parent class. Follow the chain to the top before concluding there's no\n   protection.\n\n4. **Check whether the model is tenant-scoped at all.** Read the model and\n   its schema. If the table has no shop/tenant column, there is nothing to\n   scope by. Global reference or catalog tables are a correct design.\n\n5. **Consider whether cross-tenant access is the deliberate purpose.**\n   Some queries exist to resolve which tenant owns a resource. Scoping\n   those by tenant is circular. If so, the risk is enumeration, not\n   isolation — note it but don't report it under this check.\n\n6. **Check for an explicit opt-out** like `skip_idor_protection`. That\n   tells you the author considered it. Decide whether their reasoning\n   holds — an unguessable capability token is a real control; a sequential\n   integer id is not.\n\n## What to report\n\nFor each genuine cross-tenant risk you find, report:\n\n```json\n{\n  \"file\": \"app/controllers/...\",\n  \"line\": 42,\n  \"message\": \"Query on Product is not scoped to the current shop\",\n  \"snippet\": \"Product.where(id: params[:id])\",\n  \"evidence\": [\n    { \"file\": \"path\", \"line\": 12, \"quote\": \"the line that shows the gap\" }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"what you read and why it's a real risk\"\n}\n```\n\nBe precise about the gap. \"No shop filter\" is not enough — explain where\nthe scoping _should_ have come from and why it's missing. If you read a\nfile and it turns out the query IS scoped, don't report it. You are not\ntrying to find problems — you are trying to find the real ones.\n\nEvery finding must cite at least one file and line you actually read.\nAn finding with no evidence is not a finding.\n",
+  "---\nid: OPEN_REDIRECT\nversion: 1\ntier: agentic\nseverity: medium\n---\n\nFind redirect URLs that are built from user input without validation,\nallowing an attacker to redirect users to a malicious site.\n\nAn open redirect occurs when a web application redirects to a URL that\ncomes from an untrusted source (query parameters, form fields, headers)\nwithout checking that the destination is safe. In Shopify apps, this is\nparticularly dangerous because the app runs inside an iframe in the admin\n— a redirect to an external site can be used for phishing.\n\n## What to look for\n\n1. **Find redirect calls.** Search for:\n   - Rails: `redirect_to`, `head :redirect`, `redirect`\n   - Remix/Express: `redirect()`, `Response.redirect()`, `res.redirect()`\n   - PHP: `header(\"Location: ...\")`, `Redirect::to()`\n   - Python: `redirect()`, `HttpResponseRedirect()`\n\n2. **Trace the URL source.** For each redirect, determine where the\n   destination URL comes from:\n   - `params[:return_url]`, `params[:redirect_url]`, `request.query_params`\n   - `url.searchParams.get(\"return_url\")`\n   - `$_GET['redirect']`, `request.args.get('next')`\n\n3. **Check for validation.** Is the URL checked against an allowlist? Is\n   it restricted to relative paths? Is it compared to a known-safe list of\n   domains? If none of these, it's an open redirect.\n\n4. **Consider the `flow_redirect_url` pattern.** Shopify Flow connectors\n   use signed URLs for redirects — the URL is HMAC-signed, so it's not\n   user-controlled even though it comes from params. Verify the signature\n   check exists before flagging.\n\n## What to report\n\n```json\n{\n  \"file\": \"app/controllers/...\",\n  \"line\": 42,\n  \"message\": \"Redirect to user-supplied URL without validation\",\n  \"snippet\": \"redirect_to(params[:return_url])\",\n  \"evidence\": [\n    { \"file\": \"path\", \"line\": 42, \"quote\": \"redirect_to(params[:return_url])\" },\n    {\n      \"file\": \"path\",\n      \"line\": 30,\n      \"quote\": \"no allowlist or validation found in this controller\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The redirect target comes from params[:return_url] with no allowlist, path validation, or signature check.\"\n}\n```\n\nDo not report:\n\n- Redirects to hardcoded paths (`redirect_to(\"/dashboard\")`)\n- Redirects with allowlist validation (`if ALLOWED_HOSTS.include?(uri.host)`)\n- Signed redirect URLs (verify the HMAC check first)\n- Test controllers\n",
+  "---\nid: OVERBROAD_DATA_ACCESS\nversion: 1\ntier: agentic\nseverity: medium\n---\n\nFind cases where an app returns more data than necessary in API\nresponses, exposing sensitive information that the caller doesn't need.\n\nOverbroad data access is a privacy risk: returning full customer records\nwhen only an order status is needed, exposing PII (email, phone, address)\nin error messages, or selecting all fields in a GraphQL query when only\na subset is required. This is how information disclosure happens in\npractice — not through a single vulnerability, but through\ncarelessly broad data returns.\n\n## What to look for\n\n1. **Find API response patterns.** Search for:\n   - Rails: `render json: @orders`, `render json: order`,\n     `respond_with @resource`, `as_json`\n   - Remix: `return json(data)`, `return Response(data)`\n   - GraphQL: query resolvers that return full objects\n   - Any serialization that includes all model fields\n\n2. **Check what fields are returned.** For each API response:\n   - Does it return the full model (all columns) or a filtered set?\n   - Does it include sensitive fields like:\n     - `email`, `phone`, `address`, `name` (PII)\n     - `api_key`, `access_token`, `secret` (credentials)\n     - `shop_id`, `tenant_id` (internal identifiers)\n     - `password`, `password_digest` (auth data)\n   - Is there a serializer or field selection that limits the output?\n\n3. **Find GraphQL over-selection.** Search for:\n   - Queries that select all fields: `query { products { ...AllFields } }`\n   - Queries without field selection: `query { orders }` (returns everything)\n   - Mutations that return the full object after creation/update\n\n4. **Check error messages for information disclosure.** Search for:\n   - Error responses that include stack traces\n   - Error messages that reveal internal paths (`/app/services/...`)\n   - Error messages that include database details (table names, column names)\n   - Debug endpoints that expose app configuration\n\n5. **Check for missing field-level authorization.** Even if the caller\n   can access the resource, should they see all fields?\n   - A merchant can see their orders, but should they see internal\n     `cost` or `profit_margin` fields?\n   - A customer can see their order, but should they see the merchant's\n     internal notes?\n\n## What to report\n\nFor each response that returns sensitive data unnecessarily:\n\n```json\n{\n  \"file\": \"app/controllers/api/orders_controller.rb\",\n  \"line\": 20,\n  \"message\": \"API response returns full order including customer PII\",\n  \"snippet\": \"render json: @order\",\n  \"evidence\": [\n    {\n      \"file\": \"app/controllers/api/orders_controller.rb\",\n      \"line\": 20,\n      \"quote\": \"render json: @order\"\n    },\n    {\n      \"file\": \"app/models/order.rb\",\n      \"line\": 15,\n      \"quote\": \"has_many :line_items (includes customer email and shipping address)\"\n    }\n  ],\n  \"confidence\": \"medium\",\n  \"reasoning\": \"The response serializes the full order model including related customer PII (email, phone, address). No field selection or serializer limits the output. The caller only needs order status, but receives the customer's personal information.\"\n}\n```\n\nDo not report:\n\n- Responses with explicit field selection (serializers, `only:`, `except:`)\n- Responses that return only public/non-sensitive fields\n- Admin-only endpoints where full data access is intended\n- Internal diagnostic endpoints behind staff auth\n- Test files (under test/ or \\*\\_test.rb)\n",
+  "---\nid: REQUEST_DERIVED_SHOP_SCOPE\nversion: 2\ntier: agentic\nseverity: high\n---\n\nFind cases where a shop identifier comes from request input (form data,\nquery params, headers) instead of the authenticated session, and is used\nto scope a database query or select an Admin API context.\n\nThe key insight: a shop filter that uses an attacker-controlled value is\nno filter at all. The attacker can pass any shop's identifier and access\nthat shop's data. This is distinct from `MISSING_TENANT_ISOLATION` (no\nshop filter at all) — here the filter or context selection exists, but\nthe value comes from the request, not the session.\n\nThis bug appears in two forms:\n\n**Form 1: Database query scoped by request input.**\n\n```ruby\n# Rails — shop_id from params, not session\nToken.where(shop_id: params[:shop_id]).delete_all\nOrder.find_by(shop_id: params[:shop])\n```\n\n**Form 2: Admin API context selected by request input.**\n\n```typescript\n// Remix — shop from formData, not session\nconst shop = formData.get(\"shop\");\nconst { admin } = await unauthenticated.admin(shop);\n// Now admin is scoped to whatever shop the caller passed\n```\n\nBoth are the same vulnerability: the caller chooses which shop's data to\naccess. In Form 1, the query filter is attacker-controlled. In Form 2,\nthe Admin API context is attacker-controlled. `unauthenticated.admin()`\ndeliberately takes a shop parameter (it's for offline/background jobs),\nso using it with request input is an IDOR — the caller selects the shop.\n\n## What to look for\n\n1. **Find database queries that filter on a shop/tenant column.** Search for:\n   - `where(shop_id:`, `where(shop:`, `where(store_id:`, `where(tenant_id:`\n   - `.find_by(shop_id:`, `.find_or_initialize_by(shop_id:`\n\n2. **Find `unauthenticated.admin()` calls.** Search for:\n   - `unauthenticated.admin(` — this function takes a shop domain/id as\n     its argument. If that argument comes from request input, it's an IDOR.\n   - `unauthenticated.admin(shop)` where `shop` is traced to `formData.get()`,\n     `request.json()`, `url.searchParams.get()`, `params.shop`, etc.\n\n3. **Trace the shop value for every query or admin context call.** Determine\n   where it comes from:\n   - `params[:shop_id]`, `formData.get(\"shop\")`, `url.searchParams.get(\"shop\")`\n     — request input, attacker-controlled\n   - `request.headers[\"X-Shopify-Shop-Domain\"]` — header, attacker-controlled\n   - `session.shop`, `current_shop.shop_id`, `shop.shop_id` — session-derived,\n     safe\n   - A local variable — trace it back to its assignment\n\n4. **Check for compensating controls.** The shop value may be safe even\n   if it comes from params, IF there's a prior verification:\n   - An HMAC signature on the URL (e.g., `validate_path` with a signing key)\n   - A `before_action` that validates the shop against the session\n   - A Pundit policy check\n   - The params were set by trusted backend code, not the client\n\n   Follow the control to its definition and verify it actually covers\n   this query's shop_id.\n\n5. **Check for the OAuth callback pattern.** In Shopify OAuth flows,\n   `shop_id` often comes from a signed URL that was generated by the\n   app's own backend using the session shop. The HMAC on that URL is\n   the control. This is safe — but verify the signing key isn't\n   hardcoded or leaked.\n\n6. **Distinguish `authenticate.admin` from `unauthenticated.admin`.**\n   `authenticate.admin(request)` derives the shop from the session — safe.\n   `unauthenticated.admin(shop)` takes the shop as an argument — only safe\n   if the argument is session-derived or verified, NOT if it comes from\n   request input.\n\n## What to report\n\nFor each query or admin context call where the shop value is\nattacker-controlled with no compensating control:\n\n```json\n{\n  \"file\": \"app/routes/api.orders.ts\",\n  \"line\": 6,\n  \"message\": \"Shop from formData passed to unauthenticated.admin() — IDOR\",\n  \"snippet\": \"const shop = formData.get(\\\"shop\\\"); const { admin } = await unauthenticated.admin(shop);\",\n  \"evidence\": [\n    {\n      \"file\": \"app/routes/api.orders.ts\",\n      \"line\": 5,\n      \"quote\": \"const shop = formData.get(\\\"shop\\\")\"\n    },\n    {\n      \"file\": \"app/routes/api.orders.ts\",\n      \"line\": 6,\n      \"quote\": \"unauthenticated.admin(shop)\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"Shop comes from formData (request input) and is passed to unauthenticated.admin(). No session verification. An attacker can set shop to any value and access that shop's Admin API context.\"\n}\n```\n\nDo not report:\n\n- Calls to `authenticate.admin(request)` — the shop comes from the\n  session, not from request input\n- Queries where shop_id comes from `current_shop`, `session.shop`, or\n  other session-derived sources\n- Queries guarded by an HMAC signature (verify the signature check first)\n- Queries on the Shop model itself (looking up a shop by id is normal)\n- Queries in webhook handlers (the HMAC verification covers the payload)\n",
+  "---\nid: SCOPE_OVER_REQUEST\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind cases where an app requests OAuth scopes it does not use, or uses\nscopes in ways that exceed what the merchant authorised.\n\nWhen a merchant installs an app, they grant a set of access scopes (e.g.\n`read_orders`, `write_products`). The app should only access data covered\nby those scopes. Two risks:\n\n1. **Over-requested scopes:** the app declares scopes in its config that it\n   never references in code. This is a privacy violation — the merchant\n   granted access to data the app doesn't need.\n\n2. **Under-verified usage:** the app calls an API endpoint that requires a\n   scope, but doesn't check that the scope was granted before making the\n   call. This can fail at runtime or, worse, access data the merchant\n   didn't authorise if the scope was added by a different code path.\n\n## What to look for\n\n1. **Find the declared scopes.** Look in `shopify.app.toml` under\n   `[access_scopes]` → `scopes`, or in the app's OAuth redirect URL, or\n   in environment variables like `SCOPES`.\n\n2. **Find where scopes are used.** Search for API calls that reference\n   Shopify resources: `admin.rest.get`, `admin.graphql`, REST resource\n   classes, GraphQL queries on `orders`, `products`, `customers`, etc.\n\n3. **Match scopes to usage.** Each scope should map to at least one API\n   call:\n   - `read_orders` → queries on orders\n   - `write_products` → mutations on products\n   - `read_customers` → queries on customers\n   - etc.\n\n4. **Flag scopes with no matching usage.** If `read_analytics` is declared\n   but no code references analytics, that's an over-requested scope.\n\n5. **Flag API calls with no matching scope.** If code queries customers\n   but `read_customers` isn't declared, that's an under-verified usage.\n\n## What to report\n\n```json\n{\n  \"file\": \"shopify.app.toml\",\n  \"line\": 10,\n  \"message\": \"Scope 'read_analytics' is declared but never referenced in app code\",\n  \"evidence\": [\n    {\n      \"file\": \"shopify.app.toml\",\n      \"line\": 10,\n      \"quote\": \"scopes = \\\"read_orders,read_analytics\\\"\"\n    }\n  ],\n  \"confidence\": \"medium\",\n  \"reasoning\": \"Searched all source files for 'analytics' and found no API calls referencing analytics endpoints or resources.\"\n}\n```\n\nFor under-verified usage, report the code location, not the TOML:\n\n```json\n{\n  \"file\": \"app/services/customer_export.rb\",\n  \"line\": 15,\n  \"message\": \"Queries customers but 'read_customers' is not in declared scopes\",\n  \"evidence\": [\n    {\n      \"file\": \"app/services/customer_export.rb\",\n      \"line\": 15,\n      \"quote\": \"Customer.all\"\n    },\n    {\n      \"file\": \"shopify.app.toml\",\n      \"line\": 10,\n      \"quote\": \"scopes = \\\"read_orders\\\"\"\n    }\n  ],\n  \"confidence\": \"high\"\n}\n```\n\nNote: if the app has zero source files (config-only app), do not report\nover-requested scopes — you cannot verify usage from an empty corpus.\n",
+  "---\nid: SCRIPT_TAG_URL_INJECTION\nversion: 1\ntier: agentic\nseverity: critical\n---\n\nFind cases where the ScriptTag API is used with a URL derived from user\ninput, allowing an attacker to inject arbitrary scripts into every\nmerchant's storefront.\n\nThe ScriptTag API injects a `<script>` tag into the merchant's\nstorefront. If the `src` URL comes from user input (settings, params,\nmetafields), an attacker can point the script at any URL — a\ncompromised server, a malicious CDN, or a data URI with inline script.\n\nUsing ScriptTags at all is deprecated (theme app extensions should be\nused instead). But using them with user-controlled URLs is an active\ninjection vector, not just a deprecation issue.\n\n## What to look for\n\n1. **Find all ScriptTag API calls.** Search for:\n   - GraphQL: `scriptTagCreate`, `scriptTagUpdate`, `scriptTagsCreate`\n   - REST: `ScriptTag.create`, `POST /admin/api/.../script_tags.json`\n   - Ruby: `ShopifyAPI::ScriptTag.new`, `script_tag.create!`\n   - Any code that creates or updates a script tag\n\n2. **Trace the `src` URL.** For each ScriptTag call, determine where\n   the `src` argument comes from:\n   - `params[:url]`, `formData.get(\"url\")`, `request.json().url` —\n     user-controlled, injection vector\n   - A settings field that the merchant can edit — user-controlled\n   - A metafield value — merchant-writable, user-controlled\n   - A hardcoded URL (`\"https://cdn.myapp.com/widget.js\"`) — not\n     user-controlled, but still deprecated\n   - A variable — trace it back to its assignment\n\n3. **Check for URL validation.** Even if the URL comes from user input,\n   it may be safe if:\n   - The URL is validated against an allowlist of domains\n   - The URL scheme is restricted to https\n   - The URL is a relative path on the app's own domain\n\n4. **Check for event handler payloads.** ScriptTags can also include\n   `event` and `cache` parameters. If these come from user input, they\n   can be used to control when the script loads and how it's cached.\n\n## What to report\n\nFor each ScriptTag with a user-controlled `src` URL:\n\n```json\n{\n  \"file\": \"app/services/script_tag_manager.rb\",\n  \"line\": 15,\n  \"message\": \"ScriptTag created with src URL from merchant-configurable setting — injection vector\",\n  \"snippet\": \"ScriptTag.create(src: shop_setting.script_url)\",\n  \"evidence\": [\n    {\n      \"file\": \"app/services/script_tag_manager.rb\",\n      \"line\": 15,\n      \"quote\": \"ScriptTag.create(src: shop_setting.script_url)\"\n    },\n    {\n      \"file\": \"app/models/shop_setting.rb\",\n      \"line\": 8,\n      \"quote\": \"field :script_url, :string (merchant-configurable)\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The ScriptTag src URL comes from a merchant-configurable setting with no allowlist or domain validation. An attacker who controls the setting can inject a script from any URL into every installed merchant's storefront.\"\n}\n```\n\nDo not report:\n\n- ScriptTags with hardcoded URLs (deprecated but not an injection vector)\n- ScriptTags where the URL is validated against an allowlist\n- ScriptTags in test files\n- Code that only reads existing ScriptTags (no create/update)\n",
+  "---\nid: SSRF_REQUEST_FORGERY\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind cases where the app makes server-side HTTP requests to URLs\nderived from user input, allowing an attacker to target internal\nservices or third-party APIs (Server-Side Request Forgery).\n\nSSRF occurs when an application takes a URL from user input (form data,\nquery params, API payload) and fetches it server-side. An attacker can\nuse this to reach internal services, cloud metadata endpoints, or\nthird-party APIs that are only accessible from the server's network.\n\nA related pattern is command injection — where user input flows into\n`exec()`, `system()`, or shell commands without sanitisation.\n\n## What to look for\n\n1. **Find server-side HTTP calls.** Search for:\n   - Rails: `HTTParty.get(url)`, `Net::HTTP.get(url)`, `Faraday.get(url)`,\n     `open(url)`, `URI.parse(url)`, `HTTP.get(url)`\n   - Remix/Node: `fetch(url)`, `axios.get(url)`, `http.get(url)`,\n     `https.get(url)`, `request(url)`\n   - PHP: `file_get_contents(url)`, `curl_exec($ch)`, `Guzzle::get(url)`\n   - Python: `requests.get(url)`, `urllib.request.urlopen(url)`\n\n2. **Trace the URL.** For each HTTP call, determine where the URL comes\n   from:\n   - `params[:url]`, `formData.get(\"url\")`, `request.json().url` —\n     user-controlled, SSRF risk\n   - `request.headers[\"X-Callback-URL\"]` — header, user-controlled\n   - A database record — check if the record was set by user input\n   - A config constant — safe\n   - A variable — trace it back to its assignment\n\n3. **Check for SSRF protections.** The call may be safe even with user\n   input if:\n   - The URL is validated against an allowlist of domains\n   - The URL is parsed and internal IPs are blocked (169.254.169.254,\n     localhost, 10.x.x.x, 192.168.x.x, etc.)\n   - The URL scheme is restricted to https only\n\n4. **Find command injection.** Search for:\n   - Ruby: `system(cmd)`, `exec(cmd)`, `Open3.capture3(cmd)`,\n     backticks `#{cmd}`, `IO.popen(cmd)`\n   - Node: `exec(cmd)`, `execSync(cmd)`, `spawn(cmd)`, `child_process`\n   - PHP: `system()`, `exec()`, `shell_exec()`, `passthru()`, backticks\n   - Python: `os.system()`, `subprocess.run()`, `os.popen()`\n\n   Trace the command argument — if it contains user input without\n   shell escaping, it's command injection.\n\n5. **Find GraphQL query injection.** Search for:\n   - String concatenation building a GraphQL query: `\"query { \" + field + \" }\"`\n   - Template literals with user input: `` `query { ${userField} }` ``\n   - User input in query variables that aren't typed/validated\n\n## What to report\n\nFor each HTTP call, command, or query where user input flows in without\nvalidation:\n\n```json\n{\n  \"file\": \"app/services/webhook_forwarder.rb\",\n  \"line\": 15,\n  \"message\": \"Server-side HTTP request to user-supplied URL — SSRF\",\n  \"snippet\": \"HTTParty.get(params[:callback_url])\",\n  \"evidence\": [\n    {\n      \"file\": \"app/services/webhook_forwarder.rb\",\n      \"line\": 15,\n      \"quote\": \"HTTParty.get(params[:callback_url])\"\n    },\n    {\n      \"file\": \"app/services/webhook_forwarder.rb\",\n      \"line\": 10,\n      \"quote\": \"params[:callback_url]\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The URL comes from params[:callback_url] (user-controlled) and is fetched server-side with no allowlist or internal-IP filtering. An attacker can target internal services.\"\n}\n```\n\nDo not report:\n\n- HTTP calls to hardcoded URLs (`fetch(\"https://api.shopify.com/...\")`)\n- HTTP calls where the URL is validated against an allowlist\n- `exec()` with literal strings (no user input)\n- Shell calls with properly escaped arguments\n",
+  "---\nid: TEXT_SETTING_HTML_SMUGGLING\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind cases where merchant-configurable text settings are rendered as HTML\nwithout sanitisation, allowing HTML to be smuggled past custom-JS detection.\n\nMany apps have settings fields where merchants can enter custom text —\nheader text, banner content, widget titles, custom CSS, \"additional\nHTML\" fields. If the app renders these settings as raw HTML server-side\nor in Liquid, the merchant can inject arbitrary HTML including script\ntags, iframes, or event handlers.\n\nThis is distinct from `UNSAFE_INNERHTML` (which targets JavaScript\nDOM writes). HTML smuggling via text settings bypasses custom-JS detection\nbecause the HTML is rendered server-side or in Liquid, not via\n`innerHTML` in JavaScript. A scanner looking for `innerHTML` will miss it.\n\n## What to look for\n\n1. **Find text/settings fields that accept arbitrary input.** Search for:\n   - Rails: settings models, `ShopSetting`, `AppConfig`, preference columns\n     that store text/HTML\n   - Remix: settings mutations that store text in metafields or app data\n   - Liquid: theme settings schema with text fields (`\"type\": \"text\"`,\n     `\"type\": \"richtext\"`)\n   - Any field named `header_html`, `custom_html`, `banner_text`,\n     `additional_script`, `tracking_code`\n\n2. **Trace where the setting value is rendered.** For each setting:\n   - Rails: `render html: setting.value`, `render(inline: setting.value)`,\n     `<%= raw setting.value %>`, `setting.value.html_safe`\n   - Liquid: `{{ setting.value | raw }}`, `{{ setting.value }}` in a\n     context where the content type is `text/html` (not `text/plain`)\n   - JavaScript: if the setting value flows into `innerHTML` — this\n     overlaps with `UNSAFE_INNERHTML` but the entry point is a settings\n     field, not a URL param\n   - React: `dangerouslySetInnerHTML` where the HTML comes from a\n     settings/metafield value\n\n3. **Check whether the setting is merchant-configurable.** The key\n   question is: can the merchant (or an attacker who compromised the\n   merchant account) control this value?\n   - If the value is set by the app developer in code — not user-controlled\n   - If the value is set by the merchant through a settings UI — user-controlled\n   - If the value is stored in a metafield that the merchant can edit — user-controlled\n   - If the value comes from a product/customer metafield — user-controlled\n\n4. **Check for sanitisation.** Is the setting value sanitised before\n   rendering?\n   - `sanitize_html(setting.value)` or equivalent\n   - Content type set to `text/plain` instead of `text/html`\n   - Liquid auto-escape (no `| raw` filter)\n   - Allowlist of permitted HTML tags\n\n5. **Look for richtext settings.** Theme extension settings with\n   `\"type\": \"richtext\"` are designed to accept HTML — but if the app\n   renders them without sanitisation in a context where script execution\n   is possible, it's still a vulnerability.\n\n## What to report\n\nFor each setting rendered as HTML without sanitisation:\n\n```json\n{\n  \"file\": \"app/controllers/settings_controller.rb\",\n  \"line\": 20,\n  \"message\": \"Merchant-configurable header_text setting rendered as raw HTML\",\n  \"snippet\": \"render html: shop_setting.header_text\",\n  \"evidence\": [\n    {\n      \"file\": \"app/controllers/settings_controller.rb\",\n      \"line\": 20,\n      \"quote\": \"render html: shop_setting.header_text\"\n    },\n    {\n      \"file\": \"app/models/shop_setting.rb\",\n      \"line\": 5,\n      \"quote\": \"field :header_text, :text (merchant-configurable)\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The header_text setting is merchant-configurable and rendered as raw HTML without sanitisation. A merchant (or attacker who compromised the merchant account) can inject arbitrary HTML including script tags.\"\n}\n```\n\nDo not report:\n\n- Settings rendered as `text/plain` (no HTML parsing)\n- Settings that are developer-configured constants (not merchant-editable)\n- Settings with explicit HTML sanitisation (`sanitize_html`, allowlist)\n- Liquid `{{ setting }}` without `| raw` (auto-escaped)\n- Test files\n",
+  "---\nid: THEME_EXTENSION_XSS\nversion: 1\ntier: agentic\nseverity: critical\n---\n\nFind cases where theme app extensions render user-controlled data\nwithout escaping, creating XSS vulnerabilities in the merchant's\nstorefront.\n\nTheme app extensions render Liquid in the merchant's storefront. If\nthe Liquid renders user-controlled data (metafields, product data,\ncustomer input, URL parameters) without proper escaping, an attacker\ncan inject script that executes on the merchant's store — affecting\nevery visitor to that store.\n\nThis is distinct from `UNSAFE_INNERHTML` (which targets JavaScript\nDOM writes). Theme extension XSS happens in Liquid, server-side,\nthrough Shopify's rendering pipeline. The entry point is a Liquid\ntemplate, not a JavaScript file.\n\n## What to look for\n\n1. **Find all Liquid files in theme app extensions.** Search for:\n   - `*.liquid` files under `extensions/` or `theme-app-extension/`\n   - Liquid blocks, snippets, sections\n   - Theme extension entry points\n\n2. **Find `| raw` filter usage.** The `raw` filter bypasses Liquid's\n   auto-escaping:\n   - `{{ variable | raw }}` — renders unescaped HTML\n   - `{{ variable | raw }}` where variable is user-controlled — XSS\n   - Check whether the variable is proven trusted HTML (e.g. a constant\n     or app-generated content) or user-controlled\n\n3. **Trace Liquid data sources.** For each `{{ }}` output, determine\n   where the data comes from:\n   - `{{ product.metafield.custom.field }}` — merchant-writable, user-controlled\n   - `{{ customer.metafield.app.value }}` — customer-editable in some apps\n   - `{{ variant.metafield.custom.html }}` — could contain malicious HTML\n   - `{{ request.params.x }}` — URL parameter, user-controlled\n   - `{{ shop.metafield.app.config }}` — merchant-configurable\n   - `{{ block.settings.text }}` — theme settings, merchant-configurable\n   - `{{ app.metafield.namespace.key }}` — app metafield, could be\n     merchant-writable depending on permissions\n\n4. **Check Liquid rendering context.** Liquid auto-escapes `{{ }}`\n   output, but there are exceptions:\n   - `| raw` — bypasses escaping entirely\n   - `{% liquid %}` blocks with `echo` — auto-escaped\n   - `{% render %}` with `{{ }}` inside the rendered snippet — escaped,\n     but check the snippet's own output\n   - JSON responses with `{{ }}` — escaped for JSON, not for HTML context\n\n5. **Find JavaScript in theme extensions.** Theme extension assets\n   (`.js` files) that:\n   - Read from the DOM (URL params, metafield values rendered in hidden\n     elements) and write to innerHTML — overlaps with `UNSAFE_INNERHTML`\n   - Use `postMessage` with unvalidated origin — can receive XSS payloads\n     from other windows\n   - Read `window.Shopify` data that includes merchant-editable fields\n\n## What to report\n\nFor each Liquid template or JS file that renders user-controlled data\nwithout escaping:\n\n```json\n{\n  \"file\": \"extensions/theme-app-extension/blocks/widget.liquid\",\n  \"line\": 15,\n  \"message\": \"Metafield value rendered with | raw filter — XSS in storefront\",\n  \"snippet\": \"{{ product.metafield.custom.html | raw }}\",\n  \"evidence\": [\n    {\n      \"file\": \"extensions/.../blocks/widget.liquid\",\n      \"line\": 15,\n      \"quote\": \"{{ product.metafield.custom.html | raw }}\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The metafield value is merchant-writable (user-controlled) and rendered with the raw filter, bypassing Liquid's auto-escaping. An attacker who controls the metafield can inject script that executes on the merchant's storefront.\"\n}\n```\n\nDo not report:\n\n- `{{ variable }}` without `| raw` (auto-escaped by Liquid)\n- `{{ variable | raw }}` where the variable is a constant or app-generated\n  trusted HTML\n- `{{ variable | escape }}` or `{{ variable | escape_once }}` (escaped)\n- JavaScript `textContent` assignments (safe)\n- Test files\n",
+  "---\nid: UNAUTHENTICATED_ENDPOINT\nversion: 2\ntier: agentic\nseverity: high\n---\n\nFind controller actions or route handlers that process requests without\nverifying the caller's identity or authority.\n\nAn unauthenticated endpoint in a Shopify app is one where a request from\noutside the merchant's session — another app, a scraper, an attacker — can\nreach a handler that reads or modifies shop data. Authentication in Shopify\napps comes in several forms, and the right one depends on the entry point:\n\n- **Embedded app pages** use `authenticate.admin(request)` (Remix) or\n  `ShopifyApp::EnsureHasSession` (Rails). The session is validated by a\n  JWT or session cookie.\n- **Webhooks** are verified by HMAC signature\n  (`ShopifyApp::WebhookVerification`, `@shopify/webhook-processer`).\n- **App proxies** are verified by signature query parameters.\n- **Service-to-service** endpoints use bearer tokens or mTLS.\n\nA handler is unauthenticated if none of these apply AND the handler\naccesses shop-scoped data. A public endpoint that returns static content\nis not a finding.\n\n## What to look for\n\n1. **Find every route handler.** In Rails, these are controller actions\n   (methods in a controller class). In Remix/Express, these are loader\n   and action exports, or route handlers. In PHP, these are controller\n   methods or route closures.\n\n2. **For each handler, check whether authentication is applied.** Look for:\n   - A `before_action` / `beforeAction` / middleware that validates the\n     session (often inherited from a parent controller — follow the chain)\n   - An `authenticate.admin(request)` call in a Remix loader/action\n   - An HMAC verification for webhook/proxy endpoints\n   - A bearer token check for service endpoints\n\n3. **Follow inheritance.** A controller with no visible `before_action`\n   may inherit one from `ApplicationController` or a parent. Read the\n   parent class before flagging.\n\n4. **Check for `skip_idor_protection` or `protect_from_forgery` exceptions.**\n   These are explicit opt-outs — the author chose to skip a protection.\n   Determine whether the remaining auth (if any) is sufficient.\n\n5. **Check for the try/catch fallback pattern:**\n   ```js\n   try {\n     authenticate.admin(request);\n   } catch {\n     url.searchParams.get(\"shop\");\n   }\n   ```\n   This looks authenticated but falls back to user input on failure — the\n   catch block bypasses auth entirely. This is a real finding.\n\n## What to report\n\nFor each genuinely unauthenticated handler that accesses shop data:\n\n```json\n{\n  \"file\": \"app/controllers/...\",\n  \"line\": 42,\n  \"message\": \"Controller action processes shop data with no auth verification\",\n  \"snippet\": \"def export\\n  Order.all.to_csv\\nend\",\n  \"evidence\": [\n    { \"file\": \"path\", \"line\": 12, \"quote\": \"the line showing no auth\" },\n    {\n      \"file\": \"path\",\n      \"line\": 5,\n      \"quote\": \"class FooController < ApplicationController (no before_action in parent)\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"why this handler is reachable without authentication\"\n}\n```\n\nDo not report:\n\n- Public endpoints that return static content (health checks, app metadata)\n- Handlers protected by inherited `before_action` (verify the parent first)\n- Webhook/proxy handlers with HMAC verification\n- Test controllers or development-only routes\n\nEvery finding must cite the file and line where you determined auth is\nabsent. If you couldn't read the parent controller, say so — do not assume\nauth is missing.\n",
+  "---\nid: UNSAFE_INNERHTML\nversion: 3\ntier: agentic\nseverity: critical\n---\n\nFind cases where user-controlled data is written to the DOM without\nsanitisation, creating a cross-site scripting (XSS) vulnerability.\n\nXSS in a Shopify app is particularly dangerous because the app runs\ninside the admin iframe. A script injection can access the merchant's\nsession, make API calls on their behalf, or exfiltrate data.\n\n## What to look for\n\n1. **Find all DOM write calls.** Search for every pattern that parses\n   HTML, not just innerHTML:\n   - `element.innerHTML = ...`\n   - `element.outerHTML = ...`\n   - `element.insertAdjacentHTML(position, ...)`\n   - `document.write(...)`\n   - `document.writeln(...)`\n   - `eval(...)` — code injection, not HTML, but same attacker entry point\n   - `setTimeout(string, ...)` / `setInterval(string, ...)` — evals string\n   - `new Function(string)` — evals string\n\n2. **Find React/Vue dangerous rendering.** These frameworks auto-escape\n   string interpolation, but have explicit escape hatches:\n   - `dangerouslySetInnerHTML={{ __html: ... }}` — React\n   - `v-html=\"...\"` — Vue\n   - Any prop or attribute named `html` that receives raw HTML\n\n3. **Find Liquid unsafe rendering.** In theme app extensions:\n   - `{{ variable }}` — safe (auto-escaped)\n   - `{{ variable | raw }}` — unsafe (bypasses escaping)\n   - `{{ variable | escape_once }}` — partially safe\n\n4. **Trace the data source.** For each write, determine what's being\n   inserted. User-controlled sources include:\n   - URL parameters: `searchParams`, `URLSearchParams`, `params`\n   - Form input: `formData`, `request.json()`\n   - **Metafield values**: `product.metafield.value`,\n     `metafield.namespace.key`, `metafieldsSet` responses\n     — these are merchant-writable, so they are user-controlled even\n     though they look like app config\n   - GraphQL responses: product titles, customer names, review text\n   - API responses that include merchant-editable fields\n   - A literal string — not a finding\n   - A config constant — not user-controlled, not a finding\n\n5. **Check for sanitisation.** Is the data passed through:\n   - `DOMPurify.sanitize(...)` — but verify it handles event handler\n     attributes (onerror, onload, onfocus, onclick), not just tag removal\n   - `escapeHTML(...)` or a similar escaping function\n   - A textContent assignment instead (safe — textContent doesn't parse HTML)\n\n## XSS evasion patterns to check for\n\nWhen checking whether sanitisation is adequate, consider these evasion\ntechniques that bypass naive string-matching:\n\n- **Event handler attributes**: `<img src=x onerror=\"...\">` — a sanitizer\n  that strips `<script>` tags but leaves `onerror` attributes is bypassable\n- **Base64-encoded payloads**: `atob(\"...\")` decoded at runtime — evades\n  static string matching for known XSS strings\n- **Data URI payloads**: `<iframe src=\"data:text/html,...\">`\n- **SVG payloads**: `<svg onload=\"...\">` — some sanitizers miss SVG events\n\nIf the sanitizer is a custom function (not DOMPurify or a well-known\nlibrary), flag it — custom sanitizers are frequently bypassable.\n\n## What to report\n\nFor each DOM write where user-controlled data (including metafield values)\nreaches the DOM unsanitised:\n\n```json\n{\n  \"file\": \"extensions/.../widget.js\",\n  \"line\": 42,\n  \"message\": \"User-controlled metafield value rendered via innerHTML without sanitisation\",\n  \"snippet\": \"el.innerHTML = product.metafield.custom.value\",\n  \"evidence\": [\n    {\n      \"file\": \"extensions/.../widget.js\",\n      \"line\": 42,\n      \"quote\": \"el.innerHTML = product.metafield.custom.value\"\n    },\n    {\n      \"file\": \"extensions/.../widget.js\",\n      \"line\": 30,\n      \"quote\": \"const metafield = await admin.rest.get({ path: 'metafields' })\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The metafield value is merchant-writable (user-controlled) and is inserted into innerHTML without DOMPurify or equivalent sanitisation. An attacker who controls the metafield value can inject script tags that execute in the storefront.\"\n}\n```\n\nDo not report:\n\n- Literal HTML strings (`el.innerHTML = \"<b>Static</b>\"`)\n- `textContent` assignments (safe — no HTML parsing)\n- React JSX with string interpolation (auto-escaped)\n- `dangerouslySetInnerHTML` with static/constant content (still risky but\n  if the content is a constant string, there's no XSS vector from user input)\n- Sanitised inputs (`DOMPurify.sanitize(userInput)`) — unless the sanitizer\n  is custom and might miss event handler attributes\n- `eval()` or `new Function()` with literal strings (no user input)\n",
+  "---\nid: UNSCOPED_SHOP_CONFIG_WRITE\nversion: 1\ntier: agentic\nseverity: high\n---\n\nFind configuration writes where the target shop is determined by request\ninput rather than the authenticated session, allowing an attacker to\nmodify another shop's configuration.\n\nSome apps write per-shop configuration — metafields, app settings,\nwebhook subscriptions. The target shop must come from the authenticated\nsession, not from the request body or query string. If an attacker can\ncontrol the target shop, they can write to another merchant's config.\n\n## What to look for\n\n1. **Find configuration write calls.** Search for:\n   - GraphQL mutations: `metafieldsSet`, `metafieldUpdate`, `appUpdate`,\n     `webhookSubscriptionCreate`, `webhookSubscriptionUpdate`\n   - REST writes: `admin.rest.put`, `admin.rest.post`\n   - Rails: `.save`, `.update`, `.create` on config models\n   - Any write that takes a shop identifier as a parameter\n\n2. **Trace the shop identifier.** For each write, determine where the\n   target shop comes from:\n   - `params[:shop_id]`, `request.body.shop`, `url.searchParams.get('shop')`\n     — request input, attacker-controlled\n   - `session.shop`, `current_shop.shop_id`, `authenticate.admin(request)`\n     — session-derived, safe\n   - A variable — trace it back\n\n3. **Check for session verification.** Is `authenticate.admin(request)`\n   called in this handler? Is there a `before_action` that establishes\n   the session? If the shop comes from the session, it's safe.\n\n4. **Check the Remix pattern.** In Remix apps, the admin context comes\n   from `authenticate.admin(request)`, which returns `{ admin, session }`.\n   The shop is `session.shop`. If code instead reads `shop` from the\n   request body and passes it to `unauthenticated.admin(shop)`, that's\n   the vulnerability — `unauthenticated.admin` doesn't verify the caller.\n\n## What to report\n\n```json\n{\n  \"file\": \"app/routes/api.update-settings.ts\",\n  \"line\": 20,\n  \"message\": \"Configuration write targets shop from request body without session verification\",\n  \"snippet\": \"const shop = await request.json().then(d => d.shop)\",\n  \"evidence\": [\n    {\n      \"file\": \"path\",\n      \"line\": 20,\n      \"quote\": \"const shop = await request.json().then(d => d.shop)\"\n    },\n    {\n      \"file\": \"path\",\n      \"line\": 25,\n      \"quote\": \"await admin.rest.put({ path: 'metafields', shop })\"\n    },\n    {\n      \"file\": \"path\",\n      \"line\": 1,\n      \"quote\": \"no authenticate.admin(request) call found\"\n    }\n  ],\n  \"confidence\": \"high\",\n  \"reasoning\": \"The target shop comes from the request body and is passed to a configuration write. No session verification is present, so an attacker can write to any shop's config.\"\n}\n```\n\nDo not report:\n\n- Writes where the shop comes from `authenticate.admin(request)` session\n- Writes where the shop comes from an HMAC-verified webhook payload\n- Test handlers\n"
+];
diff --git a/packages/app/src/cli/services/app-doctor-engine/checks/index.ts b/packages/app/src/cli/services/app-doctor-engine/checks/index.ts
new file mode 100644
index 00000000000..27c88ebfad3
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/checks/index.ts
@@ -0,0 +1,349 @@
+import {EMBEDDED_CHECK_SOURCES} from './embedded.js'
+import {redactText} from '../rules/secret-rules.js'
+import {createHash} from 'node:crypto'
+import type {CheckExecution, FindingEvidence, Issue, Severity} from '../types.js'
+
+/**
+ * Semantic checks — the agentic review track.
+ *
+ * Some questions are facts and some are judgements. "Is this API version
+ * end-of-life" is a lookup: a static rule answers it exactly, every time.
+ * "Is this query scoped to one tenant" is not — answering it requires
+ * following inheritance, resolving a receiver back to its caller, and
+ * reading a schema. A line-oriented matcher cannot do that.
+ *
+ * So the agentic track ships a *prompt*, not a rule. The developer's agent
+ * — which already has repository access — runs the prompt, explores the
+ * code, and reports findings. app-doctor never calls a model: no API key,
+ * no network, five dependencies. It emits the question and ingests the
+ * answer.
+ *
+ * This is a parallel track, not a pipeline. The deterministic scan finds
+ * what it can (facts); the agentic review finds what the scan cannot
+ * (semantic judgements). Neither feeds the other.
+ */
+
+export interface Check {
+  id: string
+  version: number
+  tier: 'agentic'
+  severity: string
+  prompt: string
+  /** Hash of the prompt body. Recorded on every finding so a verdict is
+   * traceable to the exact wording that produced it. */
+  prompt_hash: string
+}
+
+const parseFrontmatter = (raw: string): {meta: Record<string, string>; body: string} => {
+  const match = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/.exec(raw)
+  if (!match) return {meta: {}, body: raw}
+  const [, frontmatter = '', prompt = ''] = match
+  const meta: Record<string, string> = {}
+  for (const line of frontmatter.split('\n')) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    meta[line.slice(0, idx).trim()] = line.slice(idx + 1).trim()
+  }
+  return {meta, body: prompt.trim()}
+}
+
+export const loadChecks = (): Map<string, Check> => {
+  const checks = new Map<string, Check>()
+
+  for (const source of EMBEDDED_CHECK_SOURCES) {
+    const {meta, body} = parseFrontmatter(source)
+    if (!meta.id) continue
+    checks.set(meta.id, {
+      id: meta.id,
+      version: Number(meta.version ?? 1),
+      tier: 'agentic',
+      severity: meta.severity ?? 'medium',
+      prompt: body,
+      prompt_hash: `sha256:${createHash('sha256').update(body).digest('hex')}`,
+    })
+  }
+  return checks
+}
+
+export interface ReviewPack {
+  doctor_version: string
+  generated_at: string
+  checks: Pick<Check, 'id' | 'version' | 'prompt_hash' | 'prompt' | 'severity'>[]
+  instructions: string
+}
+
+const INSTRUCTIONS = `Each check below is a prompt for you to run against this
+codebase. For each one, explore the repository, find real instances of what
+it describes, and report them with evidence.
+
+Write the results to a JSON file:
+
+  { "checks_executed": [ { "check_id": "...", "check_version": N, "prompt_hash": "sha256:..." } ],
+    "findings": [ { "check_id": "...", "check_version": N, ...fields... } ] }
+
+Then run: shopify app doctor scan --findings <that file>
+
+Rules:
+- Only report findings you verified by reading the code.
+- Every finding must cite at least one file and line.
+- Record every completed check in checks_executed, even when it found nothing.
+- Don't report things you couldn't confirm — uncertainty is not a finding.`
+
+/**
+ * Build the review pack — the prompts for the developer's agent.
+ * No candidates, no scan output. The agent explores independently.
+ */
+export const buildReviewPack = (doctorVersion: string): ReviewPack => ({
+  doctor_version: doctorVersion,
+  generated_at: new Date().toISOString(),
+  checks: [...loadChecks().values()].map((check) => ({
+    id: check.id,
+    version: check.version,
+    prompt_hash: check.prompt_hash,
+    prompt: check.prompt,
+    severity: check.severity,
+  })),
+  instructions: INSTRUCTIONS,
+})
+
+/**
+ * A finding reported by the developer's agent after running a check prompt.
+ */
+export interface AgentFinding {
+  check_id: string
+  check_version: number
+  prompt_hash: string
+  file: string
+  line: number
+  message: string
+  snippet?: string
+  evidence?: {file: string; line?: number; quote?: string}[]
+  confidence?: 'high' | 'medium' | 'low'
+  reasoning?: string
+}
+
+/**
+ * Convert an agent finding into an Issue for the trace.
+ * Agent findings are "agentic" confidence — advisory until confirmed, but
+ * carrying more weight than a heuristic guess because the agent read the code.
+ */
+const SEVERITY_POINTS: Record<string, number> = {
+  critical: -25,
+  high: -15,
+  medium: -10,
+  low: -5,
+}
+
+export const findingToIssue = (finding: AgentFinding, check: Check): Issue => ({
+  id: check.id,
+  severity: (check.severity as Severity) ?? 'medium',
+  points: SEVERITY_POINTS[check.severity] ?? -10,
+  title: check.id
+    .replace(/_/g, ' ')
+    .toLowerCase()
+    .replace(/\b\w/g, (character) => character.toUpperCase()),
+  message: redactText(finding.message),
+  location: {
+    file: redactText(finding.file.replace(/\\/g, '/')),
+    line: finding.line,
+  },
+  snippet: finding.snippet === undefined ? undefined : redactText(finding.snippet),
+  evidence: finding.evidence?.map(
+    (item): FindingEvidence => ({
+      location: {
+        file: redactText(item.file.replace(/\\/g, '/')),
+        ...(item.line === undefined ? {} : {line: item.line}),
+      },
+      ...(item.quote === undefined ? {} : {quote: redactText(item.quote)}),
+    }),
+  ),
+  fix: {
+    automated: false,
+    description: "See the agent's reasoning and evidence.",
+  },
+  confidence: 'agentic',
+  found_by: 'agent',
+  // check_version and prompt_hash are taken from the CHECK WE LOADED, never
+  // from the finding. The finding's copies are untrusted input; they are
+  // validated in mergeFindings and then discarded. Copying them through would
+  // let anyone editing findings.json claim any provenance they liked, which
+  // would defeat the point of recording provenance at all.
+  check_version: check.version,
+  prompt_hash: check.prompt_hash,
+  agent_confidence: finding.confidence,
+  agent_reasoning: finding.reasoning === undefined ? undefined : redactText(finding.reasoning),
+})
+
+/**
+ * A finding is only usable if it is grounded. An answer with no evidence is
+ * a claim, and claims are what this whole mechanism exists to avoid taking
+ * at face value.
+ */
+/** Caps on agent-supplied text, so a malformed findings.json cannot produce an
+ *  unbounded submission artifact. Generous enough for real findings. */
+const MAX_MESSAGE_LENGTH = 4_000
+const MAX_SNIPPET_LENGTH = 4_000
+const MAX_REASONING_LENGTH = 8_000
+const MAX_EVIDENCE = 50
+const MAX_QUOTE_LENGTH = 4_000
+const MAX_PATH_LENGTH = 1_024
+const MAX_FINDINGS = 1_000
+
+/**
+ * Reject paths that escape the app root or are absolute.
+ *
+ * `findings.json` is developer-controlled input that ends up verbatim in the
+ * trace submitted to Shopify. A path like `../../../etc/passwd` is never a
+ * legitimate finding location, and file-keyed lookups (file_hashes, staleness)
+ * assume project-relative paths.
+ */
+export const isSafeRelativePath = (path: string): boolean => {
+  if (!path) return false
+  // Reject absolute POSIX and Windows paths.
+  if (path.startsWith('/') || /^[a-zA-Z]:[\\/]/.test(path)) return false
+  if (path.includes('\0')) return false
+  // Normalise separators and reject any traversal segment.
+  const segments = path.replace(/\\/g, '/').split('/')
+  return !segments.includes('..')
+}
+
+export const validateFinding = (finding: AgentFinding): string | undefined => {
+  if (!finding || typeof finding !== 'object') return 'finding must be an object'
+  if (!finding.check_id) return 'missing check_id'
+  if (!finding.file) return 'missing file'
+  if (!finding.line) return 'missing line'
+  if (!finding.message) return 'missing message'
+  if (!finding.prompt_hash) return 'missing prompt_hash'
+  if (!finding.evidence || finding.evidence.length === 0) return 'finding requires at least one evidence citation'
+  if (finding.evidence.length > MAX_EVIDENCE) return `finding exceeds ${MAX_EVIDENCE} evidence citations`
+  if (finding.file.length > MAX_PATH_LENGTH) return `file path exceeds ${MAX_PATH_LENGTH} characters`
+  if (!isSafeRelativePath(finding.file))
+    return `unsafe file path (must be relative and inside the app): ${finding.file}`
+  if (!Number.isInteger(finding.line) || finding.line < 1) return `invalid line number: ${finding.line}`
+  if (finding.message.length > MAX_MESSAGE_LENGTH) return `message exceeds ${MAX_MESSAGE_LENGTH} characters`
+  if (finding.snippet && finding.snippet.length > MAX_SNIPPET_LENGTH)
+    return `snippet exceeds ${MAX_SNIPPET_LENGTH} characters`
+  if (finding.reasoning && finding.reasoning.length > MAX_REASONING_LENGTH)
+    return `reasoning exceeds ${MAX_REASONING_LENGTH} characters`
+  for (const evidence of finding.evidence) {
+    if (!isSafeRelativePath(evidence.file)) return `unsafe evidence file path: ${evidence.file}`
+    if (evidence.file.length > MAX_PATH_LENGTH) return `evidence file path exceeds ${MAX_PATH_LENGTH} characters`
+    if (evidence.line !== undefined && (!Number.isInteger(evidence.line) || evidence.line < 1))
+      return `invalid evidence line number: ${evidence.line}`
+    if (evidence.quote && evidence.quote.length > MAX_QUOTE_LENGTH)
+      return `evidence quote exceeds ${MAX_QUOTE_LENGTH} characters`
+  }
+  return undefined
+}
+
+/**
+ * Merge agent findings into a scan result's issues.
+ * Returns the count of accepted and rejected findings.
+ */
+export const mergeFindings = (
+  issues: Issue[],
+  findings: AgentFinding[],
+  options: {knownFiles?: ReadonlySet<string>} = {},
+): {accepted: number; rejected: string[]} => {
+  const checks = loadChecks()
+  const rejected: string[] = []
+  let accepted = 0
+
+  if (findings.length > MAX_FINDINGS) {
+    rejected.push(`findings file contains ${findings.length} findings, exceeding the limit of ${MAX_FINDINGS}`)
+    return {accepted: 0, rejected}
+  }
+
+  for (const finding of findings) {
+    const problem = validateFinding(finding)
+    if (problem) {
+      const id = finding && typeof finding === 'object' ? finding.check_id : '<unknown>'
+      rejected.push(`${id}: ${problem}`)
+      continue
+    }
+    if (options.knownFiles && !options.knownFiles.has(redactText(finding.file.replace(/\\/g, '/')))) {
+      rejected.push(`${finding.check_id}: finding file was not part of the scanned inputs: ${finding.file}`)
+      continue
+    }
+    if (options.knownFiles) {
+      const unknownEvidence = finding.evidence?.find(
+        (item) => !options.knownFiles!.has(redactText(item.file.replace(/\\/g, '/'))),
+      )
+      if (unknownEvidence) {
+        rejected.push(`${finding.check_id}: evidence file was not part of the scanned inputs: ${unknownEvidence.file}`)
+        continue
+      }
+    }
+    const check = checks.get(finding.check_id)
+    if (!check) {
+      rejected.push(`${finding.check_id}: unknown check`)
+      continue
+    }
+    if (finding.check_version !== check.version) {
+      rejected.push(
+        `${finding.check_id}: version mismatch (finding v${finding.check_version}, current v${check.version})`,
+      )
+      continue
+    }
+    // The prompt hash is the strongest provenance claim in the trace: it binds
+    // a verdict to the exact prompt wording that produced it. Validate it with
+    // the same rigour as the version rather than trusting the agent's copy.
+    if (finding.prompt_hash !== check.prompt_hash) {
+      rejected.push(
+        `${finding.check_id}: prompt_hash mismatch (finding ${finding.prompt_hash.slice(0, 12)}…, current ${check.prompt_hash.slice(0, 12)}…) — the finding was produced by a different prompt revision`,
+      )
+      continue
+    }
+    issues.push(findingToIssue(finding, check))
+    accepted++
+  }
+
+  return {accepted, rejected}
+}
+
+export interface AgentFindingsDocument {
+  findings: AgentFinding[]
+  /** Checks the agent actually completed, including those with zero findings. */
+  checks_executed?: {
+    check_id: string
+    check_version: number
+    prompt_hash: string
+  }[]
+}
+
+export function validateAgentChecksExecuted(document: AgentFindingsDocument): {
+  executions: CheckExecution[]
+  rejected: string[]
+} {
+  const checks = loadChecks()
+  const rejected: string[] = []
+  const seen = new Set<string>()
+  const executions: CheckExecution[] = []
+  if (document.checks_executed !== undefined && !Array.isArray(document.checks_executed))
+    return {executions, rejected: ['checks_executed must be an array']}
+  for (const claimed of document.checks_executed ?? []) {
+    const check = checks.get(claimed.check_id)
+    if (!check) {
+      rejected.push(`${claimed.check_id}: unknown executed check`)
+      continue
+    }
+    if (seen.has(claimed.check_id)) {
+      rejected.push(`${claimed.check_id}: duplicate executed check`)
+      continue
+    }
+    if (claimed.check_version !== check.version || claimed.prompt_hash !== check.prompt_hash) {
+      rejected.push(`${claimed.check_id}: executed-check provenance mismatch`)
+      continue
+    }
+    seen.add(claimed.check_id)
+    executions.push({
+      id: check.id,
+      version: check.version,
+      kind: 'check',
+      status: 'executed',
+      findings: document.findings.filter((finding) => finding.check_id === check.id).length,
+      prompt_hash: check.prompt_hash,
+    })
+  }
+  return {executions, rejected}
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/embed-checks.mjs b/packages/app/src/cli/services/app-doctor-engine/embed-checks.mjs
new file mode 100644
index 00000000000..8e60883b8a3
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/embed-checks.mjs
@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * Embeds the versioned semantic-check markdown so the bundled CLI does not
+ * depend on runtime assets. The markdown files remain the source of truth.
+ */
+import {readFileSync, readdirSync, writeFileSync} from 'node:fs'
+import {dirname, join} from 'node:path'
+import {fileURLToPath} from 'node:url'
+
+const engineRoot = dirname(fileURLToPath(import.meta.url))
+const checksDirectory = join(engineRoot, 'checks')
+const outputPath = join(checksDirectory, 'embedded.ts')
+const files = readdirSync(checksDirectory)
+  .filter((file) => file.endsWith('.md'))
+  .sort()
+const sources = files.map((file) => readFileSync(join(checksDirectory, file), 'utf8'))
+
+const output = `// AUTO-GENERATED by app-doctor-engine/embed-checks.mjs — do not edit.
+// Source of truth: adjacent checks/*.md files.
+
+// prettier-ignore
+export const EMBEDDED_CHECK_SOURCES: readonly string[] = ${JSON.stringify(sources, null, 2)};
+`
+
+writeFileSync(outputPath, output)
+console.log(`Embedded ${files.length} semantic checks in app-doctor-engine/checks/embedded.ts`)
diff --git a/packages/app/src/cli/services/app-doctor-engine/external/index.ts b/packages/app/src/cli/services/app-doctor-engine/external/index.ts
new file mode 100644
index 00000000000..1218c3e070b
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/external/index.ts
@@ -0,0 +1,109 @@
+import {isSafeRelativePath} from '../checks/index.js'
+import {redactIssue} from '../trace/index.js'
+import {redactText} from '../rules/secret-rules.js'
+import type {FindingEvidence, Issue, Location, Severity} from '../types.js'
+
+export interface ExternalFinding {
+  rule_id: string
+  rule_version: number
+  severity: Severity
+  title: string
+  message: string
+  location: Location
+  evidence?: FindingEvidence[]
+  snippet?: string
+  fix?: {description: string; guide?: string}
+}
+
+const MAX_FINDINGS = 1_000
+const MAX_EVIDENCE = 50
+const MAX_TEXT_LENGTH = 8_000
+const MAX_PATH_LENGTH = 1_024
+
+const severities = new Set<Severity>(['critical', 'high', 'medium', 'low'])
+
+export function validateExternalFinding(finding: ExternalFinding): string | undefined {
+  if (!finding || typeof finding !== 'object') return 'finding must be an object'
+  if (!finding.rule_id) return 'missing rule_id'
+  if (!Number.isInteger(finding.rule_version) || finding.rule_version < 1) return 'invalid rule_version'
+  if (!severities.has(finding.severity)) return 'invalid severity'
+  if (!finding.title || !finding.message) return 'title and message are required'
+  if (
+    finding.title.length > MAX_TEXT_LENGTH ||
+    finding.message.length > MAX_TEXT_LENGTH ||
+    (finding.snippet?.length ?? 0) > MAX_TEXT_LENGTH
+  )
+    return `text exceeds ${MAX_TEXT_LENGTH} characters`
+  if (finding.location.file.length > MAX_PATH_LENGTH) return `path exceeds ${MAX_PATH_LENGTH} characters`
+  if ((finding.evidence?.length ?? 0) > MAX_EVIDENCE) return `finding exceeds ${MAX_EVIDENCE} evidence citations`
+  if (!isSafeRelativePath(finding.location.file)) return 'unsafe finding location'
+  if (finding.location.line !== undefined && (!Number.isInteger(finding.location.line) || finding.location.line < 1))
+    return 'invalid finding line'
+  for (const evidence of finding.evidence ?? []) {
+    if (evidence.location.file.length > MAX_PATH_LENGTH) return `evidence path exceeds ${MAX_PATH_LENGTH} characters`
+    if ((evidence.quote?.length ?? 0) > MAX_TEXT_LENGTH) return `evidence quote exceeds ${MAX_TEXT_LENGTH} characters`
+    if (!isSafeRelativePath(evidence.location.file)) return 'unsafe evidence location'
+    if (
+      evidence.location.line !== undefined &&
+      (!Number.isInteger(evidence.location.line) || evidence.location.line < 1)
+    )
+      return 'invalid evidence line'
+  }
+  return undefined
+}
+
+export function mergeExternalFindings(
+  issues: Issue[],
+  findings: ExternalFinding[],
+  options: {knownFiles?: ReadonlySet<string>} = {},
+): {accepted: number; rejected: string[]} {
+  const rejected: string[] = []
+  let accepted = 0
+  if (findings.length > MAX_FINDINGS)
+    return {
+      accepted: 0,
+      rejected: [`external findings exceed the limit of ${MAX_FINDINGS}`],
+    }
+  for (const finding of findings) {
+    const problem = validateExternalFinding(finding)
+    if (problem) {
+      const id = finding && typeof finding === 'object' ? finding.rule_id : '<unknown>'
+      rejected.push(`${id}: ${problem}`)
+      continue
+    }
+    const normalize = (path: string) => redactText(path.replace(/\\/g, '/'))
+    if (options.knownFiles && !options.knownFiles.has(normalize(finding.location.file))) {
+      rejected.push(`${finding.rule_id}: finding file was not part of the scanned inputs`)
+      continue
+    }
+    const unknownEvidence = finding.evidence?.find(
+      (item) => options.knownFiles && !options.knownFiles.has(normalize(item.location.file)),
+    )
+    if (unknownEvidence) {
+      rejected.push(`${finding.rule_id}: evidence file was not part of the scanned inputs`)
+      continue
+    }
+    issues.push(
+      redactIssue({
+        id: finding.rule_id,
+        rule_version: finding.rule_version,
+        found_by: 'external',
+        severity: finding.severity,
+        points: 0,
+        title: finding.title,
+        message: finding.message,
+        location: finding.location,
+        evidence: finding.evidence,
+        snippet: finding.snippet,
+        fix: {
+          automated: false,
+          description: finding.fix?.description ?? 'Review the external finding.',
+          guide: finding.fix?.guide,
+        },
+        confidence: 'agentic',
+      }),
+    )
+    accepted++
+  }
+  return {accepted, rejected}
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/index.ts b/packages/app/src/cli/services/app-doctor-engine/index.ts
new file mode 100644
index 00000000000..fc12ba9bff1
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/index.ts
@@ -0,0 +1,47 @@
+export {scan, DETERMINISTIC_RULES} from './scanners/index.js'
+export {
+  buildReviewPack,
+  loadChecks,
+  mergeFindings,
+  validateFinding,
+  validateAgentChecksExecuted,
+} from './checks/index.js'
+export type {AgentFinding, AgentFindingsDocument, Check, ReviewPack} from './checks/index.js'
+export {getRegistry} from './registry/index.js'
+export type {RegistryEntry} from './registry/index.js'
+export {
+  compileTrace,
+  validateTrace,
+  validateSuppression,
+  assertCompatibleTrace,
+  isTraceSchemaVersionSupported,
+  canonicalJson,
+  findingFingerprint,
+  sha256,
+} from './trace/index.js'
+export type {CompileTraceOptions, TraceValidationResult} from './trace/index.js'
+export {mergeExternalFindings, validateExternalFinding} from './external/index.js'
+export type {ExternalFinding} from './external/index.js'
+export {formatConsole, formatIssue, formatJson, sortIssues} from './output/format.js'
+export {ENGINE_NAME, SUPPORTED_TRACE_SCHEMA_VERSIONS, TRACE_SCHEMA_VERSION} from './types.js'
+export {getEngineVersion} from './version.js'
+export type {
+  Capabilities,
+  CheckExecution,
+  Confidence,
+  FindingEvidence,
+  FindingSource,
+  Fix,
+  Grade,
+  Issue,
+  Location,
+  ScanMetadata,
+  ScanResult,
+  ScoreResult,
+  Severity,
+  SkippedFile,
+  Suppression,
+  SuppressionProvenance,
+  TraceFinding,
+  TraceV1,
+} from './types.js'
diff --git a/packages/app/src/cli/services/app-doctor-engine/output/format.ts b/packages/app/src/cli/services/app-doctor-engine/output/format.ts
new file mode 100644
index 00000000000..a3f85b01ac9
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/output/format.ts
@@ -0,0 +1,157 @@
+import {redactText} from '../rules/secret-rules.js'
+import {redactIssue} from '../trace/index.js'
+import type {Capabilities, Issue, ScanResult, Severity} from '../types.js'
+
+const SEVERITY_ORDER: Record<Severity, number> = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1,
+}
+
+const SEVERITY_SYMBOL: Record<Severity, string> = {
+  critical: '✖',
+  high: '⚠',
+  medium: '⚠',
+  low: 'ℹ',
+}
+
+const SEVERITY_LABEL: Record<Severity, string> = {
+  critical: 'Critical',
+  high: 'High',
+  medium: 'Medium',
+  low: 'Low',
+}
+
+export interface FormatConsoleOptions {
+  verbose?: boolean
+  elapsedMilliseconds?: number
+  /**
+   * Number of unresolved needs_review findings. When set, the grade is marked
+   * provisional — an unresolved app has not been cleared, and a bare "Excellent"
+   * would imply otherwise.
+   */
+  provisional?: number
+}
+
+export function formatConsole(result: ScanResult, options: FormatConsoleOptions = {}): string {
+  const lines: string[] = []
+  const issues = sortIssues(result.issues)
+  const elapsedSuffix =
+    options.elapsedMilliseconds === undefined ? '' : ` in ${formatElapsed(options.elapsedMilliseconds)}`
+
+  lines.push('')
+  lines.push(`✔ Scanned ${result.scan.files_scanned} files${elapsedSuffix}`)
+  // An unscanned file is not a clean file — never let incomplete coverage pass
+  // silently, or a reader will mistake "did not look" for "looked, found nothing".
+  const skipped = result.scan.files_skipped_count ?? 0
+  if (skipped > 0) {
+    const detail = result.scan.files_skipped ?? []
+    const tooLarge = detail.filter((file) => file.reason === 'too_large').length
+    const unreadable = detail.filter((file) => file.reason === 'unreadable').length
+    const parts: string[] = []
+    if (tooLarge > 0) parts.push(`${tooLarge} too large`)
+    if (unreadable > 0) parts.push(`${unreadable} unreadable`)
+    lines.push(
+      `⚠ ${skipped} file${skipped === 1 ? '' : 's'} NOT scanned (${parts.join(', ')}) — coverage is incomplete`,
+    )
+    for (const file of detail.slice(0, 5)) {
+      const size = file.size_bytes ? ` (${Math.round(file.size_bytes / 1024)} KB)` : ''
+      lines.push(`    ${redactText(file.path)}${size}`)
+    }
+    if (detail.length > 5) lines.push(`    …and ${detail.length - 5} more`)
+  }
+  lines.push('')
+  lines.push(`Shopify App Doctor — ${redactText(result.app.name)}`)
+  const provisionalSuffix =
+    options.provisional && options.provisional > 0 ? `  (provisional — ${options.provisional} unresolved)` : ''
+  lines.push(`Score: ${result.score.total} / 100 ${formatGrade(result.score.grade)}${provisionalSuffix}`)
+
+  if (issues.length === 0) {
+    lines.push('')
+    lines.push('✔ No security issues found')
+  } else {
+    lines.push('')
+    lines.push(`${issues.length} ${issues.length === 1 ? 'issue' : 'issues'}`)
+    lines.push(formatSeveritySummary(issues))
+    lines.push('')
+    for (const issue of issues) {
+      lines.push(formatIssue(issue, options.verbose === true))
+      lines.push('')
+    }
+  }
+
+  if (options.verbose) {
+    lines.push('Scan details')
+    lines.push(`  Capabilities: ${formatCapabilities(result.capabilities)}`)
+    lines.push(`  Rules run: ${result.scan.rules_run} | Skipped: ${result.scan.rules_skipped}`)
+    lines.push(`  Input hash: ${result.scan.input_hash}`)
+    lines.push(`  Result hash: ${result.scan.result_hash}`)
+    lines.push('')
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`
+}
+
+export function formatIssue(issueInput: Issue, verbose = false): string {
+  const issue = redactIssue(issueInput)
+  const location = issue.location.line ? `${issue.location.file}:${issue.location.line}` : issue.location.file
+  const lines = [`${SEVERITY_SYMBOL[issue.severity]} ${issue.title}`, `  ${issue.id}`, `  ${location}`]
+  if (verbose) {
+    lines.push(`  ${issue.message}`)
+    lines.push(`  Fix: ${issue.fix.description}`)
+    if (issue.fix.guide) lines.push(`  Docs: ${issue.fix.guide}`)
+    if (issue.snippet) lines.push(`  Code: ${issue.snippet}`)
+  }
+  return lines.join('\n')
+}
+
+export function formatJson(result: ScanResult): string {
+  return JSON.stringify(result, (_key, value) => (typeof value === 'string' ? redactText(value) : value), 2)
+}
+
+export function sortIssues(issues: Issue[]): Issue[] {
+  return [...issues].sort((left, right) => {
+    const severityDifference = SEVERITY_ORDER[right.severity] - SEVERITY_ORDER[left.severity]
+    if (severityDifference !== 0) return severityDifference
+    const fileDifference = left.location.file.localeCompare(right.location.file)
+    if (fileDifference !== 0) return fileDifference
+    return (left.location.line ?? 0) - (right.location.line ?? 0)
+  })
+}
+
+function formatSeveritySummary(issues: Issue[]): string {
+  const counts = new Map<Severity, number>()
+  for (const issue of issues) counts.set(issue.severity, (counts.get(issue.severity) ?? 0) + 1)
+  return (Object.keys(SEVERITY_ORDER) as Severity[])
+    .filter((severity) => (counts.get(severity) ?? 0) > 0)
+    .sort((left, right) => SEVERITY_ORDER[right] - SEVERITY_ORDER[left])
+    .map((severity) => `${SEVERITY_LABEL[severity]}: ${counts.get(severity)}`)
+    .join(', ')
+}
+
+function formatCapabilities(capabilities: Capabilities): string {
+  const active: string[] = []
+  if (capabilities.theme_app_extension) active.push('theme_app_extension')
+  if (capabilities.app_embed) active.push('app_embed')
+  if (capabilities.script_tags) active.push('script_tags')
+  if (capabilities.webhooks) active.push('webhooks')
+  if (capabilities.app_proxy) active.push('app_proxy')
+  if (capabilities.storefront_metafield_writes) active.push('storefront_metafields')
+  if (capabilities.has_backend) active.push('backend')
+  if (capabilities.checkout_extension) active.push('checkout_extension')
+  if (capabilities.declared_ip_allowlist) active.push('ip_allowlist')
+  return active.length > 0 ? active.join(', ') : 'none detected'
+}
+
+function formatGrade(grade: ScanResult['score']['grade']): string {
+  return grade
+    .replaceAll('_', ' ')
+    .toLowerCase()
+    .replace(/^./, (character) => character.toUpperCase())
+}
+
+function formatElapsed(elapsedMilliseconds: number): string {
+  if (elapsedMilliseconds < 1000) return `${Math.round(elapsedMilliseconds)}ms`
+  return `${(elapsedMilliseconds / 1000).toFixed(1)}s`
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/registry/index.ts b/packages/app/src/cli/services/app-doctor-engine/registry/index.ts
new file mode 100644
index 00000000000..ed192b7de87
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/registry/index.ts
@@ -0,0 +1,62 @@
+import {loadChecks} from '../checks/index.js'
+import {RULE_CATALOG, type RuleCatalogEntry} from '../rules/catalog.js'
+import {DETERMINISTIC_RULES} from '../scanners/index.js'
+
+export interface RegistryEntry {
+  id: string
+  version: number
+  kind: 'deterministic' | 'agent'
+  severity: RuleCatalogEntry['severity']
+  title: string
+  description: string
+  points: number
+  fix: string
+  guide?: string
+  requires?: RuleCatalogEntry['requires']
+  prompt_hash?: string
+}
+
+/** The one public registry used by docs, CLI listing, review packs, and traces. */
+export function getRegistry(): RegistryEntry[] {
+  const catalog = new Map(RULE_CATALOG.map((entry) => [entry.id, entry]))
+  const deterministic: RegistryEntry[] = DETERMINISTIC_RULES.map((rule) => {
+    const entry = catalog.get(rule.id)
+    if (!entry) throw new Error(`Deterministic rule ${rule.id} is missing from the rule catalog`)
+    return {
+      id: rule.id,
+      version: rule.version,
+      kind: 'deterministic',
+      severity: entry.severity,
+      title: entry.title,
+      description: entry.description,
+      points: entry.points,
+      fix: entry.fix,
+      ...(entry.guide ? {guide: entry.guide} : {}),
+      ...(entry.requires ? {requires: entry.requires} : {}),
+    }
+  })
+  const agent: RegistryEntry[] = [...loadChecks().values()].map((check) => {
+    const entry = catalog.get(check.id)
+    return {
+      id: check.id,
+      version: check.version,
+      kind: 'agent',
+      severity: check.severity as RegistryEntry['severity'],
+      title:
+        entry?.title ??
+        check.id
+          .replaceAll('_', ' ')
+          .toLowerCase()
+          .replace(/\b\w/g, (character) => character.toUpperCase()),
+      description: entry?.description ?? "Semantic security review performed by the developer's coding agent.",
+      points: entry?.points ?? 0,
+      fix: entry?.fix ?? 'Review the cited evidence and correct the security boundary.',
+      ...(entry?.guide ? {guide: entry.guide} : {}),
+      prompt_hash: check.prompt_hash,
+      ...(entry?.requires ? {requires: entry.requires} : {}),
+    }
+  })
+  return [...deterministic, ...agent].sort((left, right) =>
+    `${left.kind}|${left.id}`.localeCompare(`${right.kind}|${right.id}`),
+  )
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/additional-security-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/additional-security-rules.ts
new file mode 100644
index 00000000000..e5d101397d3
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/additional-security-rules.ts
@@ -0,0 +1,114 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: TOKEN_LEAKAGE (-20, high)
+ *
+ * Detects session tokens, access tokens, or API secrets being logged
+ * via console.log, logger, or similar output. Leaking tokens in logs
+ * is a common security incident — logs are often shipped to third-party
+ * observability tools.
+ */
+
+export function scanTokenLeakage(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  const tokenPatterns = [
+    /(?:access[_-]?token|session[_-]?token|api[_-]?secret|api[_-]?key|SHOPIFY_API_SECRET|SHOPIFY_ACCESS_TOKEN)\b/i,
+  ]
+
+  const sinkPatterns = [
+    /\bconsole\.(log|info|warn|error|debug)\s*\(/,
+    /\blogger\.(info|debug|warn|error|log)\s*\(/,
+    /\bconsole\.dir\s*\(/,
+  ]
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb', '.py'].includes(file.ext)) continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      const isSink = sinkPatterns.some((pattern) => pattern.test(line))
+      if (!isSink) continue
+
+      // Check if the log call includes token-like variable names
+      const hasTokenRef = tokenPatterns.some((pattern) => pattern.test(line))
+      if (!hasTokenRef) continue
+
+      // Skip if it's clearly a comment or a string that mentions tokens
+      // but doesn't actually log them
+      if (/^\s*\/\//.test(line) || /^\s*#/.test(line)) continue
+      if (/["'].*token.*["']/.test(line) && !/[\w.]+\s*[),]/.test(line)) continue
+
+      issues.push({
+        id: 'TOKEN_LEAKAGE',
+        severity: 'high',
+        points: -20,
+        title: 'Token or secret may be logged',
+        message: `This log statement references a token or secret. Logging credentials exposes them in log files and observability tools. Remove the token from the log call or redact it.`,
+        location: {file: file.path, line: i + 1},
+        snippet: line.trim().substring(0, 80),
+        fix: {
+          automated: false,
+          description:
+            'Remove the token/secret from the log statement. If debugging is needed, log a redacted version or a boolean flag.',
+        },
+      })
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Rule: OPEN_REDIRECT (-12, medium)
+ *
+ * Detects auth callback handlers that redirect to a URL taken from
+ * request parameters without validation. This is a classic OAuth
+ * vulnerability — an attacker can craft a URL that redirects the
+ * merchant to a phishing site after auth.
+ */
+
+export function scanOpenRedirect(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      // Pattern: redirect/searchParams.get("returnUrl") or redirect(req.query.redirect)
+      // without validation
+      const redirectFromParam =
+        /\b(?:redirect|res\.redirect|Response\.redirect)\s*\(\s*(?:.*searchParams\.get|.*query\.|.*params\.|.*\.url)/i.test(
+          line,
+        )
+      const hasValidation = /\b(?:if|validate|allowed|whitelist|allowlist|startsWith|includes|match)\b/i.test(
+        lines.slice(i, i + 5).join('\n'),
+      )
+
+      if (redirectFromParam && !hasValidation) {
+        issues.push({
+          id: 'OPEN_REDIRECT',
+          severity: 'medium',
+          points: -12,
+          title: 'Open redirect in auth callback',
+          message: `Redirect target is taken from request parameters without validation. An attacker can redirect users to a phishing site after authentication. Validate the redirect URL against an allowlist.`,
+          location: {file: file.path, line: i + 1},
+          snippet: line.trim().substring(0, 80),
+          fix: {
+            automated: false,
+            description:
+              'Validate the redirect URL against an allowlist of permitted domains, or use a relative path only.',
+            guide: 'https://shopify.dev/docs/apps/build/authentication-authorization',
+          },
+          confidence: 'needs_review',
+        })
+      }
+    }
+  }
+
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/catalog.ts b/packages/app/src/cli/services/app-doctor-engine/rules/catalog.ts
new file mode 100644
index 00000000000..ac146ad29c4
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/catalog.ts
@@ -0,0 +1,289 @@
+import type {Severity, Capabilities} from '../types.js'
+
+export interface RuleCatalogEntry {
+  id: string
+  title: string
+  severity: Severity
+  points: number
+  description: string
+  fix: string
+  guide?: string
+  requires?: keyof Capabilities
+  status?: 'active' | 'planned'
+}
+
+export const RULE_CATALOG: RuleCatalogEntry[] = [
+  {
+    id: 'DEPRECATED_SCRIPT_TAG_SCOPE',
+    title: 'Using deprecated write_script_tags scope',
+    severity: 'critical',
+    points: -30,
+    description: 'Detects the deprecated write_script_tags OAuth scope in shopify.app.toml.',
+    fix: 'Remove write_script_tags from scopes and migrate to app embeds.',
+    guide: 'https://shopify.dev/docs/apps/online-store/app-embeds',
+  },
+  {
+    id: 'SCOPE_OVER_REQUEST',
+    title: 'OAuth scope may be over-requested',
+    severity: 'high',
+    points: -12,
+    description: "Detects declared OAuth scopes that don't appear to be used by the app code.",
+    fix: 'Remove unused scopes or add the code path that needs them.',
+    guide: 'https://shopify.dev/docs/api/usage/access-scopes',
+  },
+  {
+    id: 'MISSING_SRI',
+    title: 'Missing subresource integrity on external script',
+    severity: 'high',
+    points: -15,
+    description: "Detects external script tags in Liquid or HTML that don't declare integrity metadata.",
+    fix: 'Add integrity and crossorigin attributes to the script tag.',
+    guide: 'https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity',
+    requires: 'theme_app_extension',
+  },
+  {
+    id: 'UNSAFE_INNERHTML',
+    title: 'Unsafe HTML assignment',
+    severity: 'critical',
+    points: -25,
+    description: 'Detects innerHTML, outerHTML, and insertAdjacentHTML receiving non-literal values.',
+    fix: 'Use textContent where possible or sanitize with DOMPurify before rendering.',
+    guide: 'https://shopify.dev/docs/apps/online-store/security#xss-prevention',
+    requires: 'theme_app_extension',
+  },
+  {
+    id: 'LIQUID_UNSAFE_RENDER',
+    title: 'Unsafe Liquid rendering with | raw filter',
+    severity: 'critical',
+    points: -25,
+    description: 'Detects Liquid output that renders unescaped values through the raw filter.',
+    fix: 'Replace | raw with | escape unless the value is proven trusted HTML.',
+    guide: 'https://shopify.dev/docs/api/liquid/filters/raw',
+    requires: 'theme_app_extension',
+  },
+  {
+    id: 'EXTERNAL_CDN_DEPENDENCY',
+    title: 'External CDN dependency',
+    severity: 'medium',
+    points: -7,
+    description: 'Detects extension code loading dependencies or fetches from external non-Shopify domains.',
+    fix: 'Bundle the dependency locally or self-host it behind a trusted boundary.',
+    requires: 'theme_app_extension',
+  },
+  {
+    id: 'INSECURE_WEBHOOK_URL',
+    title: 'Webhook URL is not HTTPS',
+    severity: 'high',
+    points: -12,
+    description: 'Detects webhook subscriptions configured with non-HTTPS absolute URLs.',
+    fix: 'Change the webhook URI to use HTTPS.',
+    guide: 'https://shopify.dev/docs/apps/webhooks',
+    requires: 'webhooks',
+  },
+  {
+    id: 'COMMITTED_SECRET',
+    title: 'Committed secret or environment file',
+    severity: 'critical',
+    points: -50,
+    description: 'Detects environment files and common API key/token patterns in source files.',
+    fix: 'Remove committed secrets, rotate exposed values, and store them in environment variables.',
+  },
+  {
+    id: 'OUTDATED_SHOPIFY_SDK',
+    title: 'Outdated Shopify SDK',
+    severity: 'medium',
+    points: -5,
+    description: 'Detects Shopify SDK packages below the expected current major version.',
+    fix: 'Upgrade the Shopify SDK dependency to the current supported major.',
+    guide: 'https://shopify.dev/docs/apps/tools/sdk',
+  },
+  {
+    id: 'KNOWN_CVE_IN_DEPENDENCY',
+    title: 'Known CVE in dependency',
+    severity: 'high',
+    points: -8,
+    description: 'Detects a small curated set of dependency versions with known CVEs.',
+    fix: 'Upgrade the dependency to a patched version.',
+  },
+  {
+    id: 'MISSING_IP_ALLOWLIST',
+    title: 'No IP address spaces declared in app config',
+    severity: 'high',
+    points: -10,
+    description: 'Detects apps with no IP allowlist declaration or an allowlist open to every address.',
+    fix: 'Declare only the server IP ranges that should access Shopify APIs.',
+    guide: 'https://shopify.dev/docs/apps/launch/security-review#ip-allowlisting',
+    status: 'planned',
+  },
+  {
+    id: 'EXPIRING_OFFLINE_TOKEN',
+    title: 'Expiring offline access tokens not enabled',
+    severity: 'high',
+    points: -20,
+    description: 'Detects apps that have not opted into expiring offline access tokens (Jan 1, 2026 deadline).',
+    fix: 'Enable future.expiringOfflineAccessTokens: true (Remix) or add user session repository (Rails).',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+  },
+  {
+    id: 'METAFIELD_OFFLINE_TOKEN',
+    title: 'Metafield write using offline token context',
+    severity: 'high',
+    points: -15,
+    description:
+      'Detects metafield writes (metafieldsSet) in offline-token contexts. Online tokens provide user attribution and expiry.',
+    fix: 'Use authenticate.admin(request) instead of unauthenticated.admin() for metafield writes.',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+  },
+  {
+    id: 'MISSING_EMBEDDED_CSP',
+    title: 'Embedded app missing frame-ancestors CSP directive',
+    severity: 'high',
+    points: -10,
+    description: 'Detects embedded apps that set document response headers but omit frame-ancestors.',
+    fix: 'Add frame-ancestors to CSP, restricted to the authenticated shop domain and admin.shopify.com.',
+    guide: 'https://shopify.dev/docs/apps/build/security/set-up-iframe-protection',
+  },
+  {
+    id: 'MISSING_COMPLIANCE_WEBHOOKS',
+    title: 'Missing mandatory GDPR compliance webhooks',
+    severity: 'high',
+    points: -15,
+    description:
+      'Detects apps missing mandatory compliance webhooks (shop/redact, customers/data_request, customers/redact).',
+    fix: 'Add the missing webhook subscriptions to shopify.app.toml.',
+    guide: 'https://shopify.dev/docs/apps/webhooks/configuration/mandatory-webhooks',
+  },
+  {
+    id: 'EOL_API_VERSION',
+    title: 'End-of-life API version',
+    severity: 'medium',
+    points: -10,
+    description: 'Detects apps pinned to API versions older than ~24 months from the latest release.',
+    fix: 'Update api_version in shopify.app.toml and the ApiVersion enum in shopify.server.ts.',
+    guide: 'https://shopify.dev/docs/api/usage/versioning',
+  },
+  {
+    id: 'WEAK_SHOP_VALIDATION',
+    title: 'Shop domain validation regex is not anchored',
+    severity: 'high',
+    points: -15,
+    description: 'Detects unanchored myshopify.com regexes that allow domain spoofing and token theft.',
+    fix: 'Anchor the regex with ^ and $ to prevent prefix/suffix attacks.',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/get-access-tokens/oauth',
+  },
+  {
+    id: 'APP_PROXY_LIQUID_INJECTION',
+    title: 'App proxy Liquid injection risk',
+    severity: 'critical',
+    points: -25,
+    description: 'Detects app proxy endpoints that interpolate request parameters into application/liquid responses.',
+    fix: "Don't interpolate user input into application/liquid responses. Use application/json or escape all input.",
+    guide: 'https://shopify.dev/docs/apps/online-store/app-proxies',
+  },
+  {
+    id: 'MISSING_TENANT_ISOLATION',
+    title: 'Database query may not be scoped by shop',
+    severity: 'high',
+    points: -20,
+    description: "Detects database queries in authenticated routes that don't reference the shop domain or session.",
+    fix: "Add the authenticated shop to the query's where clause.",
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+  },
+  {
+    id: 'TOKEN_LEAKAGE',
+    title: 'Token or secret may be logged',
+    severity: 'high',
+    points: -20,
+    description: 'Detects log statements that reference access tokens, session tokens, or API secrets.',
+    fix: 'Remove the token from the log statement or redact it.',
+  },
+  {
+    id: 'OPEN_REDIRECT',
+    title: 'Open redirect in auth callback',
+    severity: 'medium',
+    points: -12,
+    description: 'Detects redirect targets taken from request parameters without validation.',
+    fix: 'Validate the redirect URL against an allowlist of permitted domains.',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization',
+  },
+  {
+    id: 'UNAUTHENTICATED_ENDPOINT',
+    title: 'Route handler lacks recognized auth verification',
+    severity: 'high',
+    points: -15,
+    description:
+      'Detects backend routes with no recognized auth guard or catch-block fallback to request-controlled shop input.',
+    fix: 'Require Shopify session validation before accessing shop data.',
+    guide: 'https://shopify.dev/docs/apps/auth',
+    requires: 'has_backend',
+  },
+  {
+    id: 'REQUEST_CONTROLLED_ADMIN_CONTEXT',
+    title: 'Request input selects Admin API shop context',
+    severity: 'critical',
+    points: -30,
+    description:
+      "Detects request-derived shop values passed into unauthenticated.admin(...), allowing callers to select another shop's Admin API context.",
+    fix: 'Use the Admin API context returned by authenticate.admin(request). Never pass form, JSON, query, or route input into unauthenticated.admin(...).',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens',
+  },
+  {
+    id: 'RUNTIME_CONFIG_SCRIPT_EXECUTION',
+    title: 'Runtime config field is executed as script',
+    severity: 'critical',
+    points: -25,
+    description: 'Detects config fields named as executable script used in files that inject or evaluate scripts.',
+    fix: 'Ship storefront JavaScript as static versioned extension assets and treat runtime config as data only.',
+  },
+  {
+    id: 'DEPRECATED_SCRIPT_TAG_API',
+    title: 'Deprecated ScriptTag API expands storefront attack surface',
+    severity: 'high',
+    points: -12,
+    description: 'Detects ScriptTag creation or update calls in app code.',
+    fix: 'Migrate storefront UI to a theme app extension or analytics to a web pixel.',
+    guide: 'https://shopify.dev/docs/apps/build/online-store/theme-app-extensions',
+  },
+  {
+    id: 'APP_PROXY_UNVERIFIED_SIGNATURE',
+    title: 'App proxy request trusted without signature verification',
+    severity: 'high',
+    points: -15,
+    description: 'Detects app proxy parameters read without visible signature verification.',
+    fix: 'Verify app proxy signatures before trusting shop, customer, or path parameters.',
+    guide: 'https://shopify.dev/docs/apps/build/online-store/app-proxies/authenticate-app-proxies',
+    requires: 'app_proxy',
+  },
+  {
+    id: 'REQUEST_DERIVED_SHOP_SCOPE',
+    title: 'Query scoped by shop value taken from request input',
+    severity: 'high',
+    points: -15,
+    description:
+      'Detects queries whose shop scope comes from request params rather than the authenticated session. Presence of a shop key is not proof of scoping when its value is attacker-controlled.',
+    fix: 'Scope the query with the shop from the authenticated session, or verify the supplied shop against a signed session or HMAC first.',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+  },
+  {
+    id: 'UNSCOPED_SHOP_CONFIG_WRITE',
+    title: 'Config write trusts shop from request input',
+    severity: 'high',
+    points: -15,
+    description:
+      'Detects settings or metafield writes scoped by request-controlled shop input without visible auth verification.',
+    fix: 'Derive the target shop from an authenticated session or verified HMAC.',
+    guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+  },
+  {
+    id: 'STATIC_FRAME_ANCESTORS',
+    title: 'Embedded app frame-ancestors uses a wildcard',
+    severity: 'high',
+    points: -12,
+    description: 'Detects wildcard frame-ancestors CSP policies in Shopify app code.',
+    fix: 'Build frame-ancestors per request from the authenticated shop domain and admin.shopify.com.',
+    guide: 'https://shopify.dev/docs/apps/build/security/set-up-iframe-protection',
+  },
+]
+
+export const findRule = (ruleId: string): RuleCatalogEntry | undefined =>
+  RULE_CATALOG.find((rule) => rule.id.toLowerCase() === ruleId.toLowerCase())
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/compliance-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/compliance-rules.ts
new file mode 100644
index 00000000000..455b94c1088
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/compliance-rules.ts
@@ -0,0 +1,177 @@
+import {readFileSync} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import type {Issue} from '../types.js'
+import type {ScanContext, Rule, SourceFile} from './types.js'
+
+/**
+ * Rule: MISSING_COMPLIANCE_WEBHOOKS (-15, high)
+ *
+ * Every public Shopify app must implement three mandatory compliance webhooks:
+ *   - shop/redact        (GDPR right to erasure — delete shop data)
+ *   - customers/data_request (GDPR data portability)
+ *   - customers/redact   (GDPR right to erasure — delete customer data)
+ *
+ * These are App Store submission requirements. Missing them means the app
+ * will be rejected during review. The doctor should catch this before
+ * the developer submits.
+ *
+ * This rule checks the shopify.app.toml for declared webhook subscriptions
+ * and flags any of the three mandatory topics that are missing.
+ */
+
+const MANDATORY_TOPICS = ['shop/redact', 'customers/data_request', 'customers/redact']
+
+export const missingComplianceWebhooks: Rule = {
+  id: 'MISSING_COMPLIANCE_WEBHOOKS',
+  title: 'Missing mandatory GDPR compliance webhooks',
+  severity: 'high',
+  points: -15,
+  requires: 'webhooks',
+  check(ctx: ScanContext): Issue[] {
+    if (!ctx.appToml?.webhooks) return []
+
+    const declaredTopics = new Set(ctx.appToml.webhooks.flatMap((sub) => sub.topics))
+
+    const missing = MANDATORY_TOPICS.filter((t) => !declaredTopics.has(t))
+
+    if (missing.length === 0) return []
+
+    return [
+      {
+        id: this.id,
+        severity: this.severity,
+        points: this.points,
+        title: this.title,
+        message: `Missing mandatory compliance webhook${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}. These are required for all public apps (GDPR right to erasure and data portability). Add them to the [webhooks] section of shopify.app.toml.`,
+        location: {file: 'shopify.app.toml'},
+        fix: {
+          automated: false,
+          description: `Add the following webhook subscriptions to shopify.app.toml:\n${missing.map((t) => `  [[webhooks.subscriptions]]\n  topics = ["${t}"]\n  uri = "/webhooks/${t.replace('/', '_')}"`).join('\n')}`,
+          guide: 'https://shopify.dev/docs/apps/webhooks/configuration/mandatory-webhooks',
+        },
+      },
+    ]
+  },
+}
+
+/**
+ * Rule: EOL_API_VERSION (-10, medium)
+ *
+ * Shopify releases quarterly API versions. Each is stable for ~12 months,
+ * then deprecated. Versions older than ~24 months from the latest release
+ * are end-of-life or deprecation-imminent. Apps on EOL versions miss
+ * security fixes and will eventually break.
+ *
+ * This rule checks the api_version declared in shopify.app.toml and
+ * the ApiVersion enum used in shopify.server.ts (Remix apps).
+ */
+
+// Shopify API versions in reverse chronological order.
+// The latest is 2025-10 (October 2025). Versions older than
+// 24 months from the latest are considered EOL.
+const SUPPORTED_API_VERSIONS = [
+  '2025-10',
+  '2025-07',
+  '2025-04',
+  '2025-01',
+  '2024-10',
+  '2024-07',
+  '2024-04',
+  '2024-01',
+  '2023-10',
+  '2023-07',
+  '2023-04',
+  '2023-01',
+]
+
+// The cutoff: versions older than this are EOL.
+// 2023-10 is ~24 months before 2025-10. Anything older is flagged.
+const EOL_CUTOFF = '2023-10'
+
+// Map ApiVersion enum names to version strings.
+const API_VERSION_ENUM_MAP: Record<string, string> = {
+  October25: '2025-10',
+  July25: '2025-07',
+  April25: '2025-04',
+  January25: '2025-01',
+  October24: '2024-10',
+  July24: '2024-07',
+  April24: '2024-04',
+  January24: '2024-01',
+  October23: '2023-10',
+  July23: '2023-07',
+  April23: '2023-04',
+  January23: '2023-01',
+}
+
+function isEol(version: string): boolean {
+  const index = SUPPORTED_API_VERSIONS.indexOf(version)
+  // Unknown versions are definitely old or invalid.
+  if (index === -1) return true
+  const cutoffIndex = SUPPORTED_API_VERSIONS.indexOf(EOL_CUTOFF)
+  // Entries further down the list are older.
+  return index > cutoffIndex
+}
+
+export function scanEolApiVersion(sourceFiles: SourceFile[], appRoot: string): Issue[] {
+  const issues: Issue[] = []
+  const seen = new Set<string>()
+
+  // 1. Check shopify.app.toml for api_version
+  try {
+    const toml = readFileSync(joinPath(appRoot, 'shopify.app.toml')).toString()
+    const match = toml.match(/api_version\s*=\s*["']([^"']+)["']/)
+    if (match?.[1] && isEol(match[1])) {
+      issues.push({
+        id: 'EOL_API_VERSION',
+        severity: 'medium',
+        points: -10,
+        title: 'End-of-life API version',
+        message: `API version ${match[1]} is end-of-life or deprecation-imminent. Update to a current version (2024-10 or newer) to get security fixes and avoid breaking changes.`,
+        location: {file: 'shopify.app.toml'},
+        fix: {
+          automated: false,
+          description: `Update api_version in shopify.app.toml to a current version (e.g., "2025-10"). Also update the ApiVersion enum in shopify.server.ts if using Remix.`,
+          guide: 'https://shopify.dev/docs/api/usage/versioning',
+        },
+      })
+    }
+    // Missing or unreadable TOML files are handled by source-file discovery.
+    // eslint-disable-next-line no-catch-all/no-catch-all
+  } catch {
+    // Nothing else to do.
+  }
+
+  // 2. Check shopify.server.ts for ApiVersion enum (Remix apps)
+  for (const file of sourceFiles) {
+    if (!file.content) continue
+    if (!['shopify.server.ts', 'shopify.server.js'].some((filename) => file.path.endsWith(filename))) continue
+
+    const enumMatch = file.content.match(/ApiVersion\.(\w+)/g)
+    if (!enumMatch) continue
+
+    for (const match of enumMatch) {
+      const enumName = match.replace('ApiVersion.', '')
+      const version = API_VERSION_ENUM_MAP[enumName]
+      if (!version) continue
+      if (isEol(version) && !seen.has(file.path)) {
+        seen.add(file.path)
+        issues.push({
+          id: 'EOL_API_VERSION',
+          severity: 'medium',
+          points: -10,
+          title: 'End-of-life API version',
+          message: `ApiVersion.${enumName} (${version}) is end-of-life or deprecation-imminent. Update to a current version to get security fixes and avoid breaking changes.`,
+          location: {file: file.path},
+          fix: {
+            automated: false,
+            description: `Update ApiVersion.${enumName} to a current version (e.g., ApiVersion.October25) in ${file.path}.`,
+            guide: 'https://shopify.dev/docs/api/usage/versioning',
+          },
+        })
+      }
+    }
+  }
+
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/config-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/config-rules.ts
new file mode 100644
index 00000000000..66ba0960b3d
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/config-rules.ts
@@ -0,0 +1,267 @@
+import {readFileSync} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import type {Issue} from '../types.js'
+import type {Rule, ScanContext} from './types.js'
+
+// ---------------------------------------------------------------------------
+// Scope declaration sites
+//
+// Scopes are not only declared in shopify.app.toml. Server-side SDKs declare
+// them in their own config files. A deprecated or over-requested scope is
+// equally dangerous wherever it is declared, so every known site must be
+// checked.
+// ---------------------------------------------------------------------------
+
+export interface ScopeDeclarationSite {
+  label: string
+  /** Paths relative to the app root. */
+  files: string[]
+  /** Must capture the comma/space-separated scope list in group 1. */
+  pattern: RegExp
+}
+
+export const SCOPE_DECLARATION_SITES: ScopeDeclarationSite[] = [
+  {
+    label: 'app configuration',
+    files: ['shopify.app.toml'],
+    // TOML scopes are a quoted string. Commas or spaces can separate entries.
+    pattern: /^[ \t]*scopes[ \t]*=[ \t]*"([^"]*)"/m,
+  },
+  {
+    label: 'shopify_app initializer',
+    files: ['config/initializers/shopify_app.rb'],
+    // Ruby: config.scope = "read_products, write_script_tags"
+    // Anchored to line start so commented-out declarations do not match.
+    pattern: /^[ \t]*config\.scope[ \t]*=[ \t]*["']([^"']*)["']/m,
+  },
+]
+
+export interface ScopeDeclaration {
+  label: string
+  /** Path relative to the app root. */
+  file: string
+  scopes: string[]
+}
+
+/**
+ * Collect declared scopes from every known declaration site present in the app.
+ * Splitting on both commas and whitespace handles both valid TOML conventions.
+ */
+export function collectScopeDeclarations(appRoot: string): ScopeDeclaration[] {
+  const declarations: ScopeDeclaration[] = []
+
+  for (const site of SCOPE_DECLARATION_SITES) {
+    for (const file of site.files) {
+      let content: string
+      try {
+        content = readFileSync(joinPath(appRoot, file)).toString()
+        // A missing declaration site isn't an error.
+        // eslint-disable-next-line no-catch-all/no-catch-all
+      } catch {
+        continue
+      }
+      const match = content.match(site.pattern)
+      if (!match?.[1]) continue
+      const scopes = match[1]
+        .split(/[\s,]+/)
+        .map((scope) => scope.trim())
+        .filter(Boolean)
+      if (scopes.length > 0) {
+        declarations.push({label: site.label, file, scopes})
+      }
+    }
+  }
+
+  return declarations
+}
+
+/** Parse a scopes string (comma or space separated) into individual scope names. */
+export function parseScopes(scopes: string): string[] {
+  return scopes
+    .split(/[\s,]+/)
+    .map((scope) => scope.trim())
+    .filter(Boolean)
+}
+
+/** Rule 1: DEPRECATED_SCRIPT_TAG_SCOPE (-30, critical) */
+export const deprecatedScriptTagScope: Rule = {
+  id: 'DEPRECATED_SCRIPT_TAG_SCOPE',
+  title: 'Using deprecated write_script_tags scope',
+  severity: 'critical',
+  points: -30,
+  check(ctx: ScanContext): Issue[] {
+    const declarations = collectScopeDeclarations(ctx.appRoot)
+    const issues: Issue[] = []
+    const seen = new Set<string>()
+
+    for (const decl of declarations) {
+      for (const scope of decl.scopes) {
+        if (scope !== 'write_script_tags' && scope !== 'read_script_tags') continue
+        // Same scope declared in two places is one problem, not two.
+        if (seen.has(scope)) continue
+        seen.add(scope)
+
+        issues.push({
+          id: this.id,
+          severity: this.severity,
+          points: this.points,
+          title: this.title,
+          message: `Scope "${scope}" is deprecated (declared in ${decl.label}). Apps should use app embeds (theme app extensions) instead of the Script Tag API.`,
+          location: {file: decl.file},
+          fix: {
+            automated: false,
+            description: `Remove "${scope}" from scopes and migrate to app embeds`,
+            guide: 'https://shopify.dev/docs/apps/online-store/app-embeds',
+          },
+        })
+      }
+    }
+    return issues
+  },
+}
+
+/** Rule 2: SCOPE_OVER_REQUEST (-12, high) — heuristic: declared scopes not referenced in code */
+export const scopeOverRequest: Rule = {
+  id: 'SCOPE_OVER_REQUEST',
+  title: 'OAuth scope may be over-requested',
+  severity: 'high',
+  points: -12,
+  check(ctx: ScanContext): Issue[] {
+    const declarations = collectScopeDeclarations(ctx.appRoot)
+    if (declarations.length === 0) return []
+
+    // De-duplicate scopes across declaration sites.
+    const allScopes = [...new Set(declarations.flatMap((declaration) => declaration.scopes))]
+
+    // Combine all source file content for searching.
+    const searchableFiles = ctx.sourceFiles.filter((file) => (file.content ?? '').length > 0)
+    const allContent = searchableFiles.map((file) => file.content ?? '').join('\n')
+
+    // This rule infers "unused" from the absence of a reference in the code.
+    // With no code to search, that inference is vacuous — every declared scope
+    // would be reported as unused. Config-only zones (a shopify.app.toml with
+    // the implementation living elsewhere) hit this and produced one false
+    // positive per declared scope. Stay silent rather than guess.
+    if (searchableFiles.length === 0) return []
+
+    const issues: Issue[] = []
+    for (const scope of allScopes) {
+      // Skip scopes that are commonly used implicitly.
+      if (['read_products', 'write_products'].includes(scope)) continue
+
+      // Check if scope (or its root concept) appears in code.
+      const scopeRoot = scope.replace(/^(?:read|write)_/, '').replace(/s$/, '')
+      const searchTerms = [scope, scopeRoot]
+      const found = searchTerms.some((term) => new RegExp(term.replace(/_/g, '[_]?'), 'i').test(allContent))
+      if (!found) {
+        // Report against the first declaration site that contains this scope.
+        const decl = declarations.find((declaration) => declaration.scopes.includes(scope))
+        issues.push({
+          id: this.id,
+          severity: this.severity,
+          points: this.points,
+          title: this.title,
+          message: `Scope "${scope}" is declared but not referenced in the app code. It may be over-requested.`,
+          location: {file: decl?.file ?? 'shopify.app.toml'},
+          fix: {
+            automated: false,
+            description: `Remove "${scope}" from scopes if not needed, or add code that uses it`,
+            guide: 'https://shopify.dev/docs/api/usage/access-scopes',
+          },
+          confidence: 'needs_review',
+        })
+      }
+    }
+    return issues
+  },
+}
+
+/** Rule 7: INSECURE_WEBHOOK_URL (-12, high) */
+export const insecureWebhookUrl: Rule = {
+  id: 'INSECURE_WEBHOOK_URL',
+  title: 'Webhook URL is not HTTPS',
+  severity: 'high',
+  points: -12,
+  requires: 'webhooks',
+  check(ctx: ScanContext): Issue[] {
+    if (!ctx.appToml?.webhooks) return []
+
+    const issues: Issue[] = []
+    for (const sub of ctx.appToml.webhooks) {
+      // Relative URIs are fine (they resolve to the app URL)
+      if (sub.uri.startsWith('/')) continue
+      if (!sub.uri.startsWith('https://')) {
+        issues.push({
+          id: this.id,
+          severity: this.severity,
+          points: this.points,
+          title: this.title,
+          message: `Webhook URI "${sub.uri}" is not HTTPS. Webhook endpoints must use HTTPS.`,
+          location: {file: relativePath(ctx.appToml.path, ctx.appRoot)},
+          fix: {
+            automated: false,
+            description: 'Change the webhook URI to use https://',
+            guide: 'https://shopify.dev/docs/apps/webhooks',
+          },
+        })
+      }
+    }
+    return issues
+  },
+}
+
+/** Rule 11: MISSING_IP_ALLOWLIST (-10, high) */
+export const missingIpAllowlist: Rule = {
+  id: 'MISSING_IP_ALLOWLIST',
+  title: 'No IP address spaces declared in app config',
+  severity: 'high',
+  points: -10,
+  check(ctx: ScanContext): Issue[] {
+    if (!ctx.appToml) return []
+
+    const allowlist = ctx.appToml.ip_allowlist
+    if (!allowlist || allowlist.length === 0) {
+      return [
+        {
+          id: this.id,
+          severity: this.severity,
+          points: this.points,
+          title: this.title,
+          message:
+            'No IP address ranges are declared in shopify.app.toml. Declaring IP spaces improves security by restricting where API requests can originate.',
+          location: {file: relativePath(ctx.appToml.path, ctx.appRoot)},
+          fix: {
+            automated: false,
+            description: 'Add an [ip_allowlist] section to shopify.app.toml with your server IP ranges',
+            guide: 'https://shopify.dev/docs/apps/launch/security-review#ip-allowlisting',
+          },
+        },
+      ]
+    }
+
+    // Check for open allowlist
+    if (allowlist.includes('0.0.0.0/0') || allowlist.includes('::/0')) {
+      return [
+        {
+          id: this.id,
+          severity: this.severity,
+          points: this.points,
+          title: 'IP allowlist is open to all addresses',
+          message:
+            'The IP allowlist contains 0.0.0.0/0, which allows requests from any IP. Restrict to your server IP ranges.',
+          location: {file: relativePath(ctx.appToml.path, ctx.appRoot)},
+          fix: {
+            automated: false,
+            description: 'Remove 0.0.0.0/0 and add specific IP ranges',
+          },
+        },
+      ]
+    }
+
+    return []
+  },
+}
+
+function relativePath(fullPath: string, appRoot: string): string {
+  return fullPath.replace(`${appRoot}/`, '').replace(appRoot, '')
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/dependency-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/dependency-rules.ts
new file mode 100644
index 00000000000..4ab92f75764
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/dependency-rules.ts
@@ -0,0 +1,126 @@
+import type {Issue} from '../types.js'
+import type {ManifestFile} from './types.js'
+
+/** Rule 9: OUTDATED_SHOPIFY_SDK (-5, medium) */
+export function scanOutdatedShopifySdk(manifests: ManifestFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  const shopifyPackages: Record<string, string> = {
+    // Current major versions.
+    '@shopify/shopify-api': '12',
+    '@shopify/shopify-app-remix': '4',
+    '@shopify/app-bridge-react': '4',
+    '@shopify/shopify-app-express': '2',
+    '@shopify/shopify-app-session-storage-prisma': '8',
+  }
+
+  for (const manifest of manifests) {
+    if (manifest.type !== 'npm') continue
+    const deps = {...manifest.dependencies, ...manifest.devDependencies}
+
+    for (const [pkg, currentMajor] of Object.entries(shopifyPackages)) {
+      if (!(pkg in deps)) continue
+      const version = deps[pkg]
+      if (version === undefined) continue
+      const major = extractMajorVersion(version)
+      if (major === null) continue
+
+      if (major < Number(currentMajor)) {
+        issues.push({
+          id: 'OUTDATED_SHOPIFY_SDK',
+          severity: 'medium',
+          points: -5,
+          title: `Outdated Shopify SDK: ${pkg}`,
+          message: `${pkg}@${version} is behind the current major version (${currentMajor}.x). Update to get security patches and new features.`,
+          location: {file: manifest.path},
+          fix: {
+            automated: false,
+            description: `Update ${pkg} to the latest version`,
+            guide: 'https://shopify.dev/docs/apps/tools/sdk',
+          },
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+/** Rule 10: KNOWN_CVE_IN_DEPENDENCY (-8, high) */
+export function scanKnownCves(manifests: ManifestFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  // Known vulnerable versions (curated list for Phase 1)
+  // In production, this would shell out to `npm audit` or use a CVE database
+  const knownVulnerable: Record<string, Record<string, string>> = {
+    lodash: {
+      '4.17.15': 'CVE-2019-10744, CVE-2020-8203 (prototype pollution)',
+      '4.17.11': 'CVE-2019-10744',
+      '4.17.4': 'CVE-2018-3721',
+    },
+    minimatch: {
+      '3.0.4': 'CVE-2022-3517 (ReDoS)',
+      '3.0.1': 'CVE-2022-3517',
+    },
+    jquery: {
+      '3.4.0': 'CVE-2020-11022, CVE-2020-11023 (XSS)',
+      '3.3.1': 'CVE-2015-9251',
+      '2.2.4': 'CVE-2015-9251',
+    },
+    handlebars: {
+      '4.5.3': 'CVE-2019-19919 (template injection)',
+      '4.3.0': 'CVE-2019-19919',
+      '4.1.2': 'CVE-2021-23383',
+    },
+    validator: {
+      '13.6.0': 'CVE-2021-37624',
+    },
+    atob: {
+      '2.1.0': 'CVE-2021-44910',
+    },
+    marked: {
+      '0.8.0': 'CVE-2021-21330',
+      '1.2.7': 'CVE-2021-21330',
+    },
+  }
+
+  for (const manifest of manifests) {
+    if (manifest.type !== 'npm') continue
+    const deps = {...manifest.dependencies, ...manifest.devDependencies}
+
+    for (const [pkg, versionMap] of Object.entries(knownVulnerable)) {
+      if (!(pkg in deps)) continue
+      const version = deps[pkg]
+      if (version === undefined) continue
+      const exactVersion = extractExactVersion(version)
+      if (exactVersion && exactVersion in versionMap) {
+        issues.push({
+          id: 'KNOWN_CVE_IN_DEPENDENCY',
+          severity: 'high',
+          points: -8,
+          title: `Known CVE in ${pkg}@${exactVersion}`,
+          message: `${pkg}@${exactVersion} has known vulnerabilities: ${versionMap[exactVersion]}. Update to a patched version.`,
+          location: {file: manifest.path},
+          fix: {
+            automated: false,
+            description: `Update ${pkg} to the latest patched version`,
+          },
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+function extractMajorVersion(versionSpec: string): number | null {
+  // Handle ^1.0.0, ~2.3.0, >=3.0.0, 1.0.0, etc.
+  const match = versionSpec.match(/(\d+)/)
+  return match?.[1] === undefined ? null : Number(match[1])
+}
+
+function extractExactVersion(versionSpec: string): string | null {
+  // Handle exact versions: "4.17.15" or "4.17.15"
+  const match = versionSpec.match(/^[\^~>=]*((\d+)\.(\d+)\.(\d+))/)
+  return match?.[1] ?? null
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/endpoint-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/endpoint-rules.ts
new file mode 100644
index 00000000000..5940ca9bbe6
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/endpoint-rules.ts
@@ -0,0 +1,279 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/** Rule 12: UNAUTHENTICATED_ENDPOINT (-15, high) */
+export function scanUnauthenticatedEndpoints(sourceFiles: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of sourceFiles) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb', '.php', '.py'].includes(file.ext)) continue
+
+    const routes = findRoutes(file)
+    for (const route of routes) {
+      if (hasAuthPattern(file.content, route)) {
+        // Auth exists — but check for the try/catch fallback pattern.
+        const fallback = detectAuthFallbackToUserInput(file.content, route)
+        if (fallback) {
+          issues.push({
+            id: 'UNAUTHENTICATED_ENDPOINT',
+            severity: 'high',
+            points: -15,
+            title: 'Auth may be bypassed via catch-block fallback to user input',
+            message: `This route has authentication (${fallback.authPattern}), but the catch block at line ${fallback.catchLine} falls back to using user input (${fallback.userInputPattern}) for data access. If auth fails, an attacker can control the shop identity via query params or request body — an IDOR vulnerability. Derive shop identity from the authenticated session, never from user input.`,
+            location: {file: file.path, line: fallback.catchLine},
+            snippet: fallback.snippet,
+            fix: {
+              automated: false,
+              description:
+                'Remove the catch-block fallback. If public access is needed, use a separate unauthenticated endpoint with explicit, limited data access — never trust user-supplied shop params.',
+              guide: 'https://shopify.dev/docs/apps/auth/session-tokens',
+            },
+            confidence: 'needs_review',
+          })
+        }
+        continue
+      }
+
+      // No auth at all — flag as unauthenticated.
+      issues.push({
+        id: 'UNAUTHENTICATED_ENDPOINT',
+        severity: 'high',
+        points: -15,
+        title: 'Route handler with no recognized auth verification',
+        message: `Route handler at line ${route.line} does not appear to have authentication verification. Ensure Shopify session validation (authenticate.admin or equivalent) is present. This is a "needs review" finding — verify your auth pattern is recognized.`,
+        location: {file: file.path, line: route.line},
+        snippet: route.snippet,
+        fix: {
+          automated: false,
+          description:
+            'Add session validation middleware (e.g., authenticate.admin for Remix, verify_request for Express, before_action for Rails)',
+          guide: 'https://shopify.dev/docs/apps/auth',
+        },
+        confidence: 'needs_review',
+      })
+    }
+  }
+
+  return issues
+}
+
+interface RouteMatch {
+  line: number
+  snippet: string
+  /** The function/method body that handles this route */
+  handlerText: string
+}
+
+function findRoutes(file: SourceFile): RouteMatch[] {
+  const routes: RouteMatch[] = []
+  const content = file.content!
+  const lines = content.split('\n')
+
+  // Skip auth/login files — these are supposed to be unauthenticated
+  if (/auth[._-]?(login|callback|start|begin)/i.test(file.path)) return routes
+  // Skip index/homepage routes — public landing pages
+  if (file.path.includes('_index') || file.path.includes('home')) return routes
+  // Skip test/eval fixture routes — these are test infrastructure, not app endpoints
+  if (/\b(test|eval|verdict|fixture|mock)\b/i.test(file.path)) return routes
+  // Skip route config files — these declare routes but auth lives in controllers/middleware, not the route definition
+  if (/\b(routes\.rb|routes\.php|urls\.py|routes\.js|routes\.ts)\b/i.test(file.path)) return routes
+  // Skip files under lib/ — engine/service code, not direct app endpoints.
+  // Shopify apps put their controllers in app/controllers/. Code in lib/ is
+  // typically mounted inside a namespace (e.g. namespace :internal) whose
+  // auth lives at the Rails route level, not inside the Sinatra/Rails controller.
+  // Flagging these produces false positives we can't resolve from the file alone.
+  if (/\blib\//.test(file.path)) return routes
+  // Skip health/ping/status routes — these are infrastructure endpoints, not app endpoints
+  // Check both filename AND route path content
+  if (/\b(health|ping|status|ready|live)\b/i.test(file.path)) return routes
+  if (content && /['"]\/(?:health|ping|status|ready|live|services\/ping)['"]/.test(content)) return routes
+
+  if (file.ext === '.rb') {
+    for (const [i, line] of lines.entries()) {
+      if (/^\s*(?:get|post|put|delete|patch|match)\s+['"]/.test(line)) {
+        routes.push({
+          line: i + 1,
+          snippet: line.trim(),
+          handlerText: lines.slice(i, i + 10).join('\n'),
+        })
+      }
+    }
+  } else if (file.ext === '.php') {
+    for (const [i, line] of lines.entries()) {
+      if (/Route::(?:get|post|put|delete|patch)\s*\(/.test(line)) {
+        routes.push({
+          line: i + 1,
+          snippet: line.trim(),
+          handlerText: lines.slice(i, i + 20).join('\n'),
+        })
+      }
+    }
+  } else if (file.ext === '.py') {
+    for (const [i, line] of lines.entries()) {
+      if (/@(?:app|bp)\.route\s*\(/.test(line)) {
+        routes.push({
+          line: i + 1,
+          snippet: line.trim(),
+          handlerText: lines.slice(i, i + 20).join('\n'),
+        })
+      }
+    }
+  } else {
+    for (const [i, line] of lines.entries()) {
+      const expressMatch = line.match(/\b(?:app|router)\.(get|post|put|delete|patch)\s*\(\s*['"`]([^'"`]*)['"`]/)
+      if (expressMatch) {
+        routes.push({
+          line: i + 1,
+          snippet: line.trim(),
+          handlerText: lines.slice(i, i + 30).join('\n'),
+        })
+        continue
+      }
+
+      const remixMatch = line.match(/export\s+(?:async\s+)?(?:const|function)\s+(loader|action)\b/)
+      if (remixMatch) {
+        const endLine = Math.min(i + 50, lines.length)
+        routes.push({
+          line: i + 1,
+          snippet: line.trim(),
+          handlerText: lines.slice(i, endLine).join('\n'),
+        })
+      }
+    }
+  }
+
+  return routes
+}
+
+/**
+ * Check if the route handler has recognized auth patterns.
+ */
+function hasAuthPattern(content: string, route: RouteMatch): boolean {
+  const handlerText = route.handlerText
+
+  if (hasDelegatedAuthHelper(content, handlerText)) return true
+  if (/authenticate\.(admin|public|customer)\s*\(/.test(handlerText)) return true
+  if (/\bauthenticate\.admin\b/.test(handlerText)) return true
+  if (/\bawait\s+authenticate\b/.test(handlerText)) return true
+  if (/verifyRequest|verify_request|requireAuth|require_auth/i.test(handlerText)) return true
+  if (/shopify\.(auth|session)/i.test(handlerText)) return true
+  if (/before_action\s+:.*(?:verify|auth|shopify)/i.test(handlerText)) return true
+  if (/authenticate_shop!?|current_shopify_shop|current_shop/i.test(handlerText)) return true
+  if (/verify_shopify/i.test(handlerText)) return true
+  if (/middleware\s*\(\s*['"]auth/i.test(handlerText)) return true
+  if (/\$this->middleware\s*\(/i.test(handlerText)) return true
+  if (/@login_required|current_user/is.test(handlerText)) return true
+  if (/login_required/.test(handlerText)) return true
+  if (
+    /session\s*===?\s*null|!session|session\??\.user|isAuthenticated|verifyToken|verifyHmac|hmac\s*===?\s*/i.test(
+      handlerText,
+    )
+  )
+    return true
+  if (/from\s+['"][^'"]*shopify\.server['"]/.test(content) && /authenticate/.test(handlerText)) return true
+  if (/verifyWebhook|verify_webhook|validateWebhook|hmac\s*===?\s*computed/i.test(handlerText)) return true
+  // Remix/Express webhook verification patterns.
+  if (/authenticate\.webhook\s*\(/.test(handlerText)) return true
+  if (/createHmac|crypto\.createHmac/.test(handlerText)) return true
+  if (/timingSafeEqual|timing_safe_equal/.test(handlerText)) return true
+  if (/verifyHmacSignature|verify_hmac_signature/.test(handlerText)) return true
+
+  return false
+}
+
+function hasDelegatedAuthHelper(content: string, handlerText: string): boolean {
+  const helperCallPattern = /\b([A-Za-z_$][\w$]*)\s*\(/g
+  let helperCallMatch = helperCallPattern.exec(handlerText)
+  while (helperCallMatch !== null) {
+    const helperName = helperCallMatch[1]
+    if (helperName && !['json', 'redirect', 'Response', 'URL'].includes(helperName)) {
+      const escapedHelperName = helperName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+      const helperDefinitionPattern = new RegExp(
+        `(?:async\\s+function\\s+${escapedHelperName}\\b|(?:const|let|var)\\s+${escapedHelperName}\\s*=)[\\s\\S]{0,1200}authenticate\\.(?:admin|public|customer)\\s*\\(`,
+      )
+      if (helperDefinitionPattern.test(content)) return true
+    }
+    helperCallMatch = helperCallPattern.exec(handlerText)
+  }
+  return false
+}
+
+interface AuthFallback {
+  authPattern: string
+  catchLine: number
+  userInputPattern: string
+  snippet: string
+}
+
+/*
+ * Detect the try/catch fallback pattern:
+ *
+ *   try {
+ *     const { session } = await authenticate.admin(request);
+ *   } catch (error) {
+ *     const shop = url.searchParams.get("shop");  // user input trusted
+ *   }
+ *
+ * If auth fails, the attacker controls which shop's data gets returned.
+ */
+function detectAuthFallbackToUserInput(content: string, route: RouteMatch): AuthFallback | null {
+  const lines = content.split('\n')
+  const handlerLines = lines.slice(route.line - 1, route.line - 1 + 60)
+
+  const authMatch = handlerLines.join('\n').match(/authenticate\.(admin|public|customer)\s*\(/)
+  const authPattern = authMatch?.[1] === undefined ? 'authenticate' : `authenticate.${authMatch[1]}`
+
+  for (const [i, line] of handlerLines.entries()) {
+    if (/^\s*\}\s*catch\s*\(/.test(line) || /^\s*catch\s*\(/.test(line)) {
+      const catchLine = route.line + i
+
+      let braceDepth = 1
+      const catchBody: string[] = []
+      for (const bodyLine of handlerLines.slice(i + 1)) {
+        if (braceDepth <= 0) break
+        catchBody.push(bodyLine)
+        for (const ch of bodyLine) {
+          if (ch === '{') braceDepth++
+          if (ch === '}') braceDepth--
+        }
+      }
+
+      const catchText = catchBody.join('\n')
+
+      const userInputPatterns = [
+        {
+          pattern: /(?:url\.)?searchParams\.get\s*\(\s*["']shop["']/i,
+          label: 'searchParams.get("shop")',
+        },
+        {
+          pattern: /(?:url\.)?searchParams\.get\s*\(/i,
+          label: 'searchParams.get()',
+        },
+        {
+          pattern: /(?:req|request)\.body(?:\.shop|\.shopDomain|\.domain)?/i,
+          label: 'request.body',
+        },
+        {
+          pattern: /(?:req|request)\.query(?:\.shop|\.shopDomain)?/i,
+          label: 'request.query',
+        },
+        {pattern: /params\.shop/i, label: 'params.shop'},
+        {
+          pattern: /(?:request|req)\.headers\[?["']shop/i,
+          label: 'request.headers["shop"]',
+        },
+      ]
+
+      for (const {pattern, label} of userInputPatterns) {
+        if (pattern.test(catchText)) {
+          const inputLine = catchBody.find((candidate) => pattern.test(candidate))
+          const snippet = inputLine?.trim() ?? line.trim()
+          return {authPattern, catchLine, userInputPattern: label, snippet}
+        }
+      }
+    }
+  }
+
+  return null
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/js-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/js-rules.ts
new file mode 100644
index 00000000000..3a414fda583
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/js-rules.ts
@@ -0,0 +1,299 @@
+import {parse} from 'acorn'
+import {simple} from 'acorn-walk'
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+interface InspectableNode {
+  type: string
+  name?: string
+  value?: unknown
+  operator?: string
+  left?: unknown
+  right?: unknown
+  property?: InspectableNode
+  object?: InspectableNode
+  callee?: InspectableNode
+  arguments?: unknown[]
+  expressions?: unknown[]
+  loc?: {start?: {line?: number}}
+}
+
+function isInspectableNode(value: unknown): value is InspectableNode {
+  return value !== null && typeof value === 'object' && 'type' in value && typeof value.type === 'string'
+}
+
+/** Rule 4: UNSAFE_INNERHTML (-25, critical) */
+export function scanUnsafeInnerHTML(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+
+    let ast
+    try {
+      ast = parse(file.content, {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        locations: true,
+        allowReturnOutsideFunction: true,
+      })
+      // Unsupported syntax falls back to the conservative regex scanner.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch {
+      issues.push(...scanUnsafeInnerHTMLRegex(file))
+      continue
+    }
+
+    simple(ast, {
+      AssignmentExpression(node) {
+        const expression = node as InspectableNode
+        // Detect: element.innerHTML = <non-literal>
+        const left = expression.left as InspectableNode | undefined
+        if (
+          left?.type === 'MemberExpression' &&
+          (left.property?.name === 'innerHTML' || left.property?.value === 'innerHTML') &&
+          !isStringLiteral(expression.right)
+        ) {
+          issues.push(
+            makeInnerHtmlIssue(file, expression.loc?.start?.line, expression.left, assessConfidence(expression.right)),
+          )
+        }
+        // Detect: element.outerHTML = <non-literal>
+        if (
+          left?.type === 'MemberExpression' &&
+          (left.property?.name === 'outerHTML' || left.property?.value === 'outerHTML') &&
+          !isStringLiteral(expression.right)
+        ) {
+          issues.push(makeOuterHtmlIssue(file, expression.loc?.start?.line))
+        }
+      },
+      CallExpression(node) {
+        const expression = node as InspectableNode
+        // Detect: element.insertAdjacentHTML(position, <non-literal>)
+        const callee = expression.callee
+        if (
+          callee?.type === 'MemberExpression' &&
+          (callee.property?.name === 'insertAdjacentHTML' || callee.property?.value === 'insertAdjacentHTML')
+        ) {
+          const secondArg = expression.arguments?.[1]
+          if (secondArg && !isStringLiteral(secondArg)) {
+            issues.push(makeInsertAdjacentIssue(file, expression.loc?.start?.line))
+          }
+        }
+      },
+    })
+  }
+
+  return issues
+}
+
+function isStringLiteral(node: unknown): boolean {
+  if (!isInspectableNode(node)) return false
+  if (node.type === 'Literal' && typeof node.value === 'string') return true
+  if (node.type === 'TemplateLiteral' && node.expressions?.length === 0) return true
+  // String concatenation of only literals is safe
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    return isStringLiteral(node.left) && isStringLiteral(node.right)
+  }
+  return false
+}
+
+/**
+ * Determine confidence for an innerHTML/outerHTML assignment.
+ * If the RHS is a template literal whose expressions are all literals/numbers,
+ * it's probably not XSS — mark as needs_review.
+ * If the RHS contains request-controlled sources (searchParams, formData, request.body),
+ * it's definite.
+ * Member expressions on non-request objects (e.g. product.star_rating) are
+ * needs_review — they could be user-controlled but usually aren't HTML.
+ */
+function assessConfidence(node: unknown): 'definite' | 'needs_review' {
+  if (!isInspectableNode(node)) return 'definite'
+
+  // Check for request-controlled sources anywhere in the expression
+  if (containsRequestControlledData(node)) return 'definite'
+
+  // Template literal: check expressions
+  if (node.type === 'TemplateLiteral') {
+    const expressions = node.expressions ?? []
+    // An expression-free template contains only static text.
+    if (expressions.length === 0) return 'needs_review'
+    const allSafe = expressions.every((expression) => isLikelySafeExpression(expression))
+    return allSafe ? 'needs_review' : 'definite'
+  }
+
+  // Binary expression (string concat): check both sides
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    return isLikelySafeExpression(node.left) && isLikelySafeExpression(node.right) ? 'needs_review' : 'definite'
+  }
+
+  // Direct identifier or call expression — can't know if user-controlled
+  return 'needs_review'
+}
+
+/** Check if an expression tree contains request-controlled data sources. */
+function containsRequestControlledData(node: unknown): boolean {
+  if (!isInspectableNode(node)) return false
+  if (node.type === 'CallExpression') {
+    const callee = node.callee
+    // searchParams.get(), formData.get(), request.body, etc.
+    if (callee?.type === 'MemberExpression') {
+      const prop = callee.property?.name ?? callee.property?.value
+      if (prop === 'get' || prop === 'getBoolean' || prop === 'getFloat') {
+        const obj = callee.object
+        const objProp = obj?.property?.name ?? obj?.property?.value
+        if (objProp === 'searchParams' || objProp === 'query' || objProp === 'params') return true
+      }
+    }
+    // Check arguments recursively
+    for (const arg of node.arguments ?? []) {
+      if (containsRequestControlledData(arg)) return true
+    }
+  }
+  if (node.type === 'MemberExpression') {
+    const objProp = node.object?.property?.name ?? node.object?.property?.value
+    if (
+      node.object?.type === 'Identifier' &&
+      typeof node.object.name === 'string' &&
+      /^(request|req|event)$/.test(node.object.name)
+    )
+      return true
+    if (objProp === 'body' || objProp === 'query' || objProp === 'params') return true
+  }
+  // Recurse into binary expressions and template literals
+  if (node.type === 'BinaryExpression') {
+    return containsRequestControlledData(node.left) || containsRequestControlledData(node.right)
+  }
+  if (node.type === 'TemplateLiteral') {
+    return (node.expressions ?? []).some((expression) => containsRequestControlledData(expression))
+  }
+  return false
+}
+
+/**
+ * A "likely safe" expression is one that's probably not user-controlled HTML:
+ * - Literals (strings, numbers, booleans)
+ * - Member expressions on non-request objects (product.title, item.price)
+ * - Call expressions on literals (.repeat(), .toString())
+ * - Binary expressions combining safe expressions
+ */
+function isLikelySafeExpression(node: unknown): boolean {
+  if (!isInspectableNode(node)) return false
+  if (isLiteralOrNumeric(node)) return true
+  // Member expressions on non-request identifiers (product.star_rating)
+  if (node.type === 'MemberExpression' && !containsRequestControlledData(node)) return true
+  // Binary expressions of safe parts
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    return isLikelySafeExpression(node.left) && isLikelySafeExpression(node.right)
+  }
+  return false
+}
+
+function isLiteralOrNumeric(node: unknown): boolean {
+  if (!isInspectableNode(node)) return false
+  // Literal strings, numbers, and booleans are safe.
+  if (node.type === 'Literal') return true
+  if (node.type === 'TemplateLiteral' && (node.expressions ?? []).length === 0) return true
+  if (node.type === 'BinaryExpression' && node.operator === '+') {
+    return isLiteralOrNumeric(node.left) && isLiteralOrNumeric(node.right)
+  }
+  // Member expressions like '⭐'.repeat() are technically callable but the
+  // result of String.prototype.repeat on a literal is still a literal.
+  if (node.type === 'CallExpression') {
+    const callee = node.callee
+    if (callee?.type === 'MemberExpression') {
+      const prop = callee.property?.value ?? callee.property?.name
+      if (prop === 'repeat' && isLiteralOrNumeric(callee.object)) return true
+    }
+  }
+  return false
+}
+
+function makeInnerHtmlIssue(
+  file: SourceFile,
+  line: number | undefined,
+  left: unknown,
+  confidence: 'definite' | 'needs_review' = 'definite',
+): Issue {
+  return {
+    id: 'UNSAFE_INNERHTML',
+    severity: 'critical',
+    points: -25,
+    title: 'Unsafe innerHTML assignment',
+    message:
+      'innerHTML is assigned a non-literal value. This can lead to XSS if the value contains user-controlled data. Use textContent instead, or sanitize with DOMPurify.',
+    location: {file: file.path, line},
+    snippet: left ? `innerHTML = ...` : undefined,
+    fix: {
+      automated: false,
+      description: 'Replace innerHTML with textContent, or add DOMPurify.sanitize()',
+      guide: 'https://shopify.dev/docs/apps/online-store/security#xss-prevention',
+    },
+    confidence,
+  }
+}
+
+function makeOuterHtmlIssue(file: SourceFile, line: number | undefined): Issue {
+  return {
+    id: 'UNSAFE_INNERHTML',
+    severity: 'critical',
+    points: -25,
+    title: 'Unsafe outerHTML assignment',
+    message:
+      'outerHTML is assigned a non-literal value. This can lead to XSS. Use textContent or sanitize with DOMPurify.',
+    location: {file: file.path, line},
+    fix: {
+      automated: false,
+      description: 'Replace outerHTML with textContent, or add DOMPurify.sanitize()',
+    },
+  }
+}
+
+function makeInsertAdjacentIssue(file: SourceFile, line: number | undefined): Issue {
+  return {
+    id: 'UNSAFE_INNERHTML',
+    severity: 'critical',
+    points: -25,
+    title: 'Unsafe insertAdjacentHTML call',
+    message:
+      'insertAdjacentHTML is called with a non-literal value. This can lead to XSS. Use textContent or sanitize with DOMPurify.',
+    location: {file: file.path, line},
+    fix: {
+      automated: false,
+      description: 'Replace insertAdjacentHTML with textContent, or add DOMPurify.sanitize()',
+    },
+  }
+}
+
+/** Regex fallback when AST parsing fails */
+function scanUnsafeInnerHTMLRegex(file: SourceFile): Issue[] {
+  const issues: Issue[] = []
+  const lines = file.content!.split('\n')
+
+  for (const [i, line] of lines.entries()) {
+    // innerHTML = <not a string literal>
+    const innerMatch = line.match(/\.innerHTML\s*=\s*([^;"'`]+)/)
+    const innerValue = innerMatch?.[1]?.trim()
+    if (
+      innerValue !== undefined &&
+      !innerValue.startsWith("'") &&
+      !innerValue.startsWith('"') &&
+      !innerValue.startsWith('`')
+    ) {
+      issues.push(makeInnerHtmlIssue(file, i + 1, null))
+    }
+    // insertAdjacentHTML(..., <not a string literal>)
+    const insertMatch = line.match(/\.insertAdjacentHTML\s*\([^,]+,\s*([^)]+)/)
+    const insertedValue = insertMatch?.[1]?.trim()
+    if (
+      insertedValue !== undefined &&
+      !insertedValue.startsWith("'") &&
+      !insertedValue.startsWith('"') &&
+      !insertedValue.startsWith('`')
+    ) {
+      issues.push(makeInsertAdjacentIssue(file, i + 1))
+    }
+  }
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/liquid-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/liquid-rules.ts
new file mode 100644
index 00000000000..ed5cfbbe860
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/liquid-rules.ts
@@ -0,0 +1,202 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/** Rule 5: LIQUID_UNSAFE_RENDER (-25, critical) */
+export function scanLiquidUnsafeRender(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (file.ext !== '.liquid') continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      // Match {{ ... | raw }} — the raw filter outputs unescaped HTML
+      // Also catch {{ ... | raw | ... }} if raw is in the filter chain
+      const rawMatches = matchLiquidRaw(line, i, lines)
+      for (const match of rawMatches) {
+        // Check if the variable is a metafield or user-generated content
+        const isMetafield = /metafield|custom\.|description|content|body|review|comment/i.test(match.expression)
+
+        issues.push({
+          id: 'LIQUID_UNSAFE_RENDER',
+          severity: 'critical',
+          points: -25,
+          title: 'Unsafe Liquid rendering with | raw filter',
+          message: isMetafield
+            ? `The | raw filter renders unescaped HTML from "${match.expression}". Metafield or user-generated content rendered with raw is an XSS vulnerability. Use | escape instead.`
+            : `The | raw filter renders unescaped HTML from "${match.expression}". Use | escape to sanitize output.`,
+          location: {file: file.path, line: i + 1},
+          snippet: line.trim(),
+          fix: {
+            automated: false,
+            description: 'Replace | raw with | escape',
+            guide: 'https://shopify.dev/docs/api/liquid/filters/raw',
+          },
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+interface LiquidMatch {
+  expression: string
+  lineIndex: number
+}
+
+/*
+ * Match Liquid raw-filter patterns.
+ * Handles single-line and multi-line expressions.
+ */
+function matchLiquidRaw(line: string, lineIndex: number, _allLines: string[]): LiquidMatch[] {
+  const matches: LiquidMatch[] = []
+
+  // Single-line: {{ expression | raw }}
+  const singleLineRegex = /\{\{\{?\s*([^}|]+?)(?:\s*\|\s*raw)\s*\}?\}\}/g
+  let match
+  while ((match = singleLineRegex.exec(line)) !== null) {
+    const expression = match[1]
+    if (expression !== undefined) matches.push({expression: expression.trim(), lineIndex})
+  }
+
+  // Also match | raw anywhere in the output tag, even with other filters
+  // {{ expression | some_filter | raw }}
+  const chainRegex = /\{\{\{?\s*([^}]+?\|[^}]+?\|[^}]*?raw[^}]*?)\s*\}?\}\}/g
+  while ((match = chainRegex.exec(line)) !== null) {
+    // Extract the main variable (first part before any |)
+    const expression = match[1]
+    const variable = expression?.split('|')[0]
+    if (variable !== undefined) matches.push({expression: variable.trim(), lineIndex})
+  }
+
+  return matches
+}
+
+/** Rule 3: MISSING_SRI (-15, high) — detects external scripts without integrity. */
+export function scanMissingSRI(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (file.ext !== '.liquid' && file.ext !== '.html') continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      // Match <script src="https://...">
+      const scriptRegex = /<script\s+[^>]*src\s*=\s*["']([^"']+)["'][^>]*>/gi
+      let match
+      while ((match = scriptRegex.exec(line)) !== null) {
+        const src = match[1]
+        // Only flag external URLs (http/https), not Shopify asset URLs
+        if (src === undefined || !src.startsWith('http')) continue
+        if (isShopifyDomain(src)) continue
+
+        // Check if the tag has integrity attribute (may be on the same or next line)
+        const fullTag = getFullScriptTag(lines, i, match.index)
+        if (!fullTag.includes('integrity=')) {
+          issues.push({
+            id: 'MISSING_SRI',
+            severity: 'high',
+            points: -15,
+            title: 'Missing subresource integrity on external script',
+            message: `External script "${src}" has no integrity attribute. Add integrity="sha384-..." to prevent supply chain attacks.`,
+            location: {file: file.path, line: i + 1},
+            snippet: line.trim(),
+            fix: {
+              automated: false,
+              description: 'Add integrity and crossorigin attributes to the script tag',
+              guide: 'https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity',
+            },
+          })
+        }
+      }
+    }
+  }
+
+  return issues
+}
+
+/** Rule 6: EXTERNAL_CDN_DEPENDENCY (-7, medium) — external CDN references in extension assets */
+export function scanExternalCdn(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  const knownCdns = ['unpkg.com', 'cdn.jsdelivr.net', 'cdnjs.cloudflare.com', 'ajax.googleapis.com']
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (
+      file.ext !== '.liquid' &&
+      file.ext !== '.js' &&
+      file.ext !== '.ts' &&
+      file.ext !== '.jsx' &&
+      file.ext !== '.tsx'
+    )
+      continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      for (const cdn of knownCdns) {
+        if (line.includes(cdn)) {
+          // Skip if this line has an integrity attribute — the script is
+          // pinned, so the CDN supply-chain risk is mitigated.
+          const fullTag = getFullScriptTag(lines, i, line.indexOf(cdn))
+          if (fullTag.includes('integrity=')) continue
+
+          issues.push({
+            id: 'EXTERNAL_CDN_DEPENDENCY',
+            severity: 'medium',
+            points: -7,
+            title: 'External CDN dependency',
+            message: `Reference to ${cdn} detected. External CDN dependencies are a supply chain risk. Bundle the dependency or self-host it.`,
+            location: {file: file.path, line: i + 1},
+            snippet: line.trim(),
+            fix: {
+              automated: false,
+              description: 'Bundle the dependency locally or self-host it',
+            },
+          })
+        }
+      }
+
+      // Also flag fetch() to non-Shopify external domains
+      const fetchMatch = line.match(/fetch\s*\(\s*['"`](https?:\/\/[^'"`]+)['"`]/)
+      const url = fetchMatch?.[1]
+      if (url !== undefined) {
+        if (!isShopifyDomain(url)) {
+          issues.push({
+            id: 'EXTERNAL_CDN_DEPENDENCY',
+            severity: 'medium',
+            points: -7,
+            title: 'External fetch to non-Shopify domain',
+            message: `fetch() to external domain "${url}". Ensure this is necessary and the endpoint is trusted.`,
+            location: {file: file.path, line: i + 1},
+            snippet: line.trim(),
+            fix: {
+              automated: false,
+              description: 'Proxy through Shopify App Proxy or declare the domain in extension config',
+            },
+          })
+        }
+      }
+    }
+  }
+
+  return issues
+}
+
+function isShopifyDomain(url: string): boolean {
+  return /(?:^|\.)(shopify\.com|shopifycdn\.com|myshopify\.com|shopifycloud\.com|shop\.dev)(?:$|\/)/.test(url)
+}
+
+/** Get the full <script> tag, handling multi-line tags */
+function getFullScriptTag(lines: string[], startIndex: number, startOffset: number): string {
+  let tag = lines[startIndex]?.slice(startOffset) ?? ''
+  let lineIdx = startIndex
+  while (!tag.includes('>') && lineIdx < lines.length - 1) {
+    lineIdx++
+    tag += `\n${lines[lineIdx] ?? ''}`
+  }
+  return tag
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/proxy-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/proxy-rules.ts
new file mode 100644
index 00000000000..60348b777ae
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/proxy-rules.ts
@@ -0,0 +1,110 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: APP_PROXY_LIQUID_INJECTION (-25, critical)
+ *
+ * When an app proxy endpoint responds with content-type "application/liquid",
+ * Shopify renders the response body as Liquid on the merchant's storefront.
+ * If the response body includes user input (query params, form data, request
+ * body), this is server-side template injection — an attacker can inject
+ * Liquid tags that execute on the merchant's store.
+ *
+ * This is one of the most Shopify-specific vulnerabilities that exists.
+ * No generic scanner knows about app proxies or application/liquid.
+ *
+ * Detection:
+ * 1. Find files that set content_type to "application/liquid"
+ * 2. In the same file, check if request params are interpolated into the
+ *    response body (render text:, render inline:, res.send with params)
+ * 3. If both conditions are met → flag as definite
+ * 4. If application/liquid is used but no param interpolation is visible
+ *    → flag as needs_review (the endpoint exists, review manually)
+ */
+
+const RULE_ID = 'APP_PROXY_LIQUID_INJECTION'
+const POINTS = -25
+const SEVERITY: Issue['severity'] = 'critical'
+const TITLE = 'App proxy Liquid injection risk'
+
+export function scanAppProxyLiquidInjection(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb'].includes(file.ext)) continue
+
+    const content = file.content
+
+    // Check if this file uses application/liquid content type
+    const hasLiquidContentType = /application\/liquid/i.test(content)
+    if (!hasLiquidContentType) continue
+
+    // Check if request params are interpolated into response bodies
+    // Ruby: params[:xxx] in render text:, ERB templates
+    // JS/TS: req.query, req.params, request.url in res.send/render
+    const hasParamInterpolation =
+      // Ruby patterns
+      /params\[/.test(content) ||
+      /params\./.test(content) ||
+      // JS/TS patterns
+      /req\.query/.test(content) ||
+      /req\.params/.test(content) ||
+      /request\.url/.test(content) ||
+      /searchParams\.get/.test(content) ||
+      // Liquid variable interpolation in strings
+      /\{\{.*params/.test(content)
+
+    // Check if the response actually uses the params in a rendered body
+    // (not just reading them for logging or validation)
+    const rendersWithParams =
+      // Ruby: render text: "...#{params[:xxx]}..."
+      /render\s+(?:text:|inline:).*params\[/s.test(content) ||
+      // Ruby: ERB with params
+      /<%=.*params\[/s.test(content) ||
+      // JS: res.send(`...${req.query.xxx}...`)
+      /res\.(send|json|end)\s*\(.*req\.(query|params|body)/s.test(content) ||
+      // JS: response.body with params
+      /response\.body.*req\.(query|params)/s.test(content) ||
+      // Generic: any string interpolation containing params and render/send
+      /(render|send|write|body).*params/s.test(content)
+
+    if (rendersWithParams) {
+      issues.push({
+        id: RULE_ID,
+        severity: SEVERITY,
+        points: POINTS,
+        title: TITLE,
+        message: `App proxy endpoint responds with content-type "application/liquid" and interpolates request parameters into the response. Shopify will render this as Liquid on the merchant's storefront — an attacker can inject Liquid tags that execute on the store. Never interpolate user input into application/liquid responses.`,
+        location: {file: file.path},
+        fix: {
+          automated: false,
+          description:
+            "Don't interpolate request parameters into application/liquid responses. Use application/json for data responses, or escape all user input before rendering as Liquid.",
+          guide: 'https://shopify.dev/docs/apps/online-store/app-proxies',
+        },
+      })
+    } else if (hasParamInterpolation) {
+      // application/liquid + params read but not clearly rendered → needs_review
+      issues.push({
+        id: RULE_ID,
+        severity: SEVERITY,
+        points: POINTS,
+        title: TITLE,
+        message: `App proxy endpoint responds with content-type "application/liquid" and reads request parameters. Review manually to ensure no user input is interpolated into the Liquid response — this would be server-side template injection.`,
+        location: {file: file.path},
+        fix: {
+          automated: false,
+          description:
+            'Verify that request parameters are not interpolated into the application/liquid response body. Use "application/json" for data, or escape all user input.',
+          guide: 'https://shopify.dev/docs/apps/online-store/app-proxies',
+        },
+        confidence: 'needs_review',
+      })
+    }
+    // If application/liquid is used but no params at all → don't flag
+    // (the endpoint renders static Liquid, which is safe)
+  }
+
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/request-scope-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/request-scope-rules.ts
new file mode 100644
index 00000000000..9e0309bbdc1
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/request-scope-rules.ts
@@ -0,0 +1,179 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: REQUEST_DERIVED_SHOP_SCOPE (-15, high, needs_review)
+ *
+ * A query that IS scoped by shop, but whose shop value comes from request
+ * input rather than the authenticated session:
+ *
+ *     Token.where(shop_id: params[:shop_id]).delete_all
+ *     Token.find_by(shop_id: params[:shop_id], app: app_type)
+ *
+ * MISSING_TENANT_ISOLATION checks whether a shop key is *present*. That
+ * treats the presence of `shop_id:` as proof of scoping, so these queries
+ * pass silently — but an attacker controls the value, which makes the scope
+ * worthless. Presence of a tenant key is not the same as trustworthy
+ * provenance, and this rule covers the gap.
+ *
+ * Always `needs_review`: a compensating control is often present but not
+ * visible here. Flow, for example, guards these paths with an HMAC +
+ * timestamp check declared in a parent controller. Static analysis cannot
+ * follow that inheritance, so the finding is surfaced for a human or agent
+ * to confirm rather than scored.
+ *
+ * Queries against the Shop model itself are excluded. Looking a shop up by
+ * a request-supplied domain is the normal OAuth install path; the risk is
+ * using a request-supplied shop to read or mutate *other* models' rows.
+ */
+
+const RULE_ID = 'REQUEST_DERIVED_SHOP_SCOPE'
+const POINTS = -15
+const SEVERITY: Issue['severity'] = 'high'
+const TITLE = 'Query scoped by shop value taken from request input'
+
+/** Ruby finder methods that accept keyword conditions. */
+const RUBY_FINDERS = /\.(where|find_by!?|find_or_create_by!?|find_or_initialize_by|delete_by|destroy_by|exists\?)\s*\(/
+
+/** Keys that carry tenant identity. */
+const SHOP_KEY = /\b(shop_id|shopify_domain|shop_domain|shop)\s*:/
+
+/** Request-controlled sources in Rails. */
+const RUBY_REQUEST_SOURCE = /\b(?:request\.)?params\s*\[|\bparams\.fetch\s*\(/
+
+/** Request-controlled sources in JS/TS. */
+const JS_REQUEST_SOURCE = /\b(?:req|request)\.(?:query|body|params)\b|\bsearchParams\.get\s*\(|\bformData\.get\s*\(/
+
+/** Model names that are the tenant record itself, not tenant-owned data. */
+const SHOP_MODEL = /\b(?:::)?Shops?\s*\.\s*(?:where|find_by!?|find_or_create_by!?|exists\?)/
+
+/**
+ * Ruby locals are method-scoped, so request bindings must be too.
+ *
+ * A file-global map produces false positives: Flow assigns
+ * `shop_id = params[:shop_id]` in one method, and an unrelated method later
+ * takes `shop_id` as a *parameter*. Treating those as the same variable
+ * flagged a safe call site. Bindings are therefore collected per `def`, and
+ * a name in the method's own parameter list shadows any outer binding.
+ *
+ * Returns, for each line, the set of request-bound names visible at it.
+ */
+function collectRequestBoundLocalsByLine(lines: string[]): Set<string>[] {
+  const perLine: Set<string>[] = []
+  // Instance variables (@shop) survive across methods within a request, so
+  // they are tracked at file scope; plain locals reset at each `def`.
+  const instanceScope = new Set<string>()
+  let methodScope = new Set<string>()
+
+  for (const line of lines) {
+    const defMatch = /^\s*def\s+[\w.]+\s*\(?([^)]*)\)?/.exec(line)
+    const parameters = defMatch?.[1]
+    if (parameters !== undefined) {
+      methodScope = new Set<string>()
+      // Parameters shadow outer bindings and are not request-bound here.
+      for (const raw of parameters.split(',')) {
+        const name = raw
+          .trim()
+          .replace(/[:*&].*$/, '')
+          .replace(/\s*=.*$/, '')
+          .trim()
+        if (name) methodScope.delete(name)
+      }
+    }
+
+    const assignment = /^\s*(@?[a-z_][a-zA-Z0-9_]*)\s*(?:\|\|)?=\s*(.+)$/.exec(line)
+    if (assignment) {
+      const [, name, value] = assignment
+      if (name !== undefined && value !== undefined) {
+        const fromRequest = RUBY_REQUEST_SOURCE.test(value) || JS_REQUEST_SOURCE.test(value)
+        const target = name.startsWith('@') ? instanceScope : methodScope
+        if (fromRequest) target.add(name)
+        // Reassignment from a trusted value clears the taint.
+        else target.delete(name)
+      }
+    }
+
+    perLine.push(new Set([...instanceScope, ...methodScope]))
+  }
+
+  return perLine
+}
+
+export function scanRequestDerivedShopScope(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+  const seen = new Set<string>()
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.rb', '.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+
+    // Test fixtures legitimately construct queries from arbitrary input.
+    if (
+      /\b(test|spec|fixture|mock|__test)\b/i.test(file.path) ||
+      /_test\.rb$/i.test(file.path) ||
+      /\btests?\//.test(file.path)
+    ) {
+      continue
+    }
+
+    const content = file.content
+    const isHandler =
+      (/class\s+\w*Controller/.test(content) && file.ext === '.rb') ||
+      /export\s+(?:async\s+)?(?:const|function)\s+(?:loader|action)\b/.test(content) ||
+      /authenticate\.admin\s*\(/.test(content)
+    if (!isHandler) continue
+
+    const lines = content.split('\n')
+    const boundByLine = collectRequestBoundLocalsByLine(lines)
+
+    for (const [i, line] of lines.entries()) {
+      const trimmed = line.trim()
+      if (/^\s*(\/\/|#|\/\*|\*)/.test(trimmed)) continue
+      if (!RUBY_FINDERS.test(trimmed) && !/\.(findMany|findFirst|findUnique|findAll|findOne)\s*\(/.test(trimmed)) {
+        continue
+      }
+      if (!SHOP_KEY.test(trimmed)) continue
+      // Looking up the tenant record itself is the normal install path.
+      if (SHOP_MODEL.test(trimmed)) continue
+
+      // The shop key's value must itself come from request input.
+      const shopValue = /\b(?:shop_id|shopify_domain|shop_domain|shop)\s*:\s*([^,)\]}]+)/.exec(trimmed)
+      const valueExpression = shopValue?.[1]?.trim()
+      if (valueExpression === undefined) continue
+
+      const direct = RUBY_REQUEST_SOURCE.test(valueExpression) || JS_REQUEST_SOURCE.test(valueExpression)
+      const visible = boundByLine[i] ?? new Set<string>()
+      const viaLocal = [...visible].some((name) =>
+        new RegExp(`^${name.replace(/[@$]/g, '\\$&')}\\b`).test(valueExpression),
+      )
+      if (!direct && !viaLocal) continue
+
+      const key = `${file.path}:${i + 1}`
+      if (seen.has(key)) continue
+      seen.add(key)
+
+      issues.push({
+        id: RULE_ID,
+        severity: SEVERITY,
+        points: POINTS,
+        title: TITLE,
+        message:
+          `The shop scope on this query is taken from request input (${valueExpression}) rather than the ` +
+          `authenticated session. A caller can substitute another shop's identifier and reach that tenant's rows. ` +
+          `If a signature or session check guards this path, confirm it covers this action.`,
+        location: {file: file.path, line: i + 1},
+        snippet: trimmed.substring(0, 120),
+        fix: {
+          automated: false,
+          description:
+            'Scope the query with the shop from the authenticated session (current_shop / session.shop). ' +
+            'If the endpoint must accept a shop parameter, verify it against a signed session or HMAC first.',
+          guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+        },
+        confidence: 'needs_review',
+      })
+    }
+  }
+
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/secret-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/secret-rules.ts
new file mode 100644
index 00000000000..885e6d5761a
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/secret-rules.ts
@@ -0,0 +1,320 @@
+import {fileExistsSync, readFileSync} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import {captureOutputWithExitCode} from '@shopify/cli-kit/node/system'
+import type {SourceFile} from './types.js'
+import type {Issue} from '../types.js'
+
+/**
+ * Secret patterns. Each entry MUST place the sensitive material in capture
+ * group 1 (or make the whole match sensitive when `wholeMatch` is set), because
+ * redaction is derived from the pattern that fired rather than from a second,
+ * separately-maintained list of redaction regexes.
+ *
+ * Why this shape: a previous version kept `keyPatterns` and a `redactLine()`
+ * helper as independent lists. They drifted — an AWS pattern was added to the
+ * detector with no matching entry in the redactor, so detected AWS keys were
+ * printed verbatim into the console AND into the submitted trace. Deriving the
+ * redaction span from the match makes that class of bug unrepresentable: if a
+ * pattern can fire, its match is redacted.
+ */
+export interface SecretPattern {
+  regex: RegExp
+  name: string
+  /** When true the entire match is the secret; otherwise capture group 1 is. */
+  wholeMatch?: boolean
+}
+
+export const SECRET_PATTERNS: SecretPattern[] = [
+  // Shopify API key (32 hex chars)
+  {
+    regex: /(?:api[_-]?key|client[_-]?id|SHOPIFY_API_KEY)\s*[:=]\s*['"]([a-f0-9]{32})['"]/i,
+    name: 'Shopify API key',
+  },
+  // Shopify API secret (shpss_ prefix or 32 hex)
+  {
+    regex: /(?:api[_-]?secret|SHOPIFY_API_SECRET)\s*[:=]\s*['"](shpss_[a-f0-9]+|[a-f0-9]{32})['"]/i,
+    name: 'Shopify API secret',
+  },
+  // Shopify access token (shpat_ / shpca_ / shppa_)
+  {
+    regex: /(?:access[_-]?token|SHOPIFY_ACCESS_TOKEN)\s*[:=]\s*['"](shp(?:at|ca|pa)_[a-zA-Z0-9]+)['"]/i,
+    name: 'Shopify access token',
+  },
+  // Bare Shopify tokens, even without an assignment context
+  {
+    regex: /shp(?:at|ca|pa|ss)_[a-fA-F0-9]{16,}/,
+    name: 'Shopify token',
+    wholeMatch: true,
+  },
+  // Stripe keys
+  {
+    regex: /(?:sk|pk|rk)_(?:live|test)_[a-zA-Z0-9]{20,}/,
+    name: 'Stripe API key',
+    wholeMatch: true,
+  },
+  // AWS access key ID
+  {regex: /AKIA[0-9A-Z]{16}/, name: 'AWS access key', wholeMatch: true},
+  // AWS secret access key (40 char base64-ish, assignment context to limit noise)
+  {
+    regex: /aws[_-]?secret[_-]?access[_-]?key\s*[:=]\s*['"]([A-Za-z0-9/+=]{40})['"]/i,
+    name: 'AWS secret access key',
+  },
+  // GitHub tokens
+  {
+    regex: /gh[pousr]_[A-Za-z0-9]{36,}/,
+    name: 'GitHub token',
+    wholeMatch: true,
+  },
+  // Google API key
+  {regex: /AIza[0-9A-Za-z_-]{35}/, name: 'Google API key', wholeMatch: true},
+  // Slack token
+  {
+    regex: /xox[baprs]-[0-9A-Za-z-]{10,}/,
+    name: 'Slack token',
+    wholeMatch: true,
+  },
+  // Private key PEM blocks
+  {
+    regex: /-----BEGIN (?:RSA |EC |OPENSSH |PGP )?PRIVATE KEY-----/,
+    name: 'private key',
+    wholeMatch: true,
+  },
+]
+
+/**
+ * Redact a line using the pattern that matched it.
+ *
+ * The redacted span is taken from the match itself, so any pattern added to
+ * SECRET_PATTERNS is automatically covered. Never returns the raw secret.
+ */
+export function redactMatch(line: string, pattern: SecretPattern): string {
+  const match = pattern.regex.exec(line)
+  if (!match) return '[REDACTED]'
+
+  const secret = pattern.wholeMatch ? match[0] : match[1]
+  if (!secret) return '[REDACTED]'
+
+  // Keep a short prefix for identification (e.g. "AKIA…") but never enough to use.
+  const keep = Math.min(4, Math.floor(secret.length / 4))
+  const hint = keep > 0 ? secret.slice(0, keep) : ''
+  const replaced = line.split(secret).join(`${hint}[REDACTED:${secret.length}]`)
+
+  // Belt and braces: if the secret somehow survived, drop the line entirely.
+  return replaced.includes(secret) ? '[REDACTED LINE]' : replaced
+}
+
+/** Redact every known secret occurrence from arbitrary scanner or agent text. */
+export function redactText(text: string): string {
+  let redacted = text
+  for (const pattern of SECRET_PATTERNS) {
+    // Patterns deliberately have no global flag. Re-run until all occurrences
+    // are removed, with a guard against a future non-progressing pattern.
+    for (let count = 0; count < 100; count++) {
+      const match = pattern.regex.exec(redacted)
+      if (!match) break
+      const next = redactMatch(redacted, pattern)
+      if (next === redacted) return '[REDACTED TEXT]'
+      redacted = next
+    }
+    // Fail closed when hostile input contains more matches than the work cap.
+    if (pattern.regex.test(redacted)) return '[REDACTED TEXT]'
+  }
+  return redacted
+}
+
+/** Rule 8: COMMITTED_SECRET (-50, critical) */
+export async function scanCommittedSecrets(sourceFiles: SourceFile[], appRoot: string): Promise<Issue[]> {
+  const issues: Issue[] = []
+
+  // Check for .env files present in the project
+  const envPatterns = ['.env', '.env.local', '.env.production', '.env.development']
+  for (const envFile of envPatterns) {
+    const envPath = joinPath(appRoot, envFile)
+    if (fileExistsSync(envPath)) {
+      // Keep git probes sequential to avoid spawning competing processes for one repository.
+      // eslint-disable-next-line no-await-in-loop
+      const status = await gitStatusFor(appRoot, envFile)
+      // Check whether the file actually contains secret-like values.
+      // A .env with only HOST= is not a secret leak.
+      const content = readFileSync(envPath).toString()
+      const hasSecrets =
+        /(?:api[_-]?key|api[_-]?secret|access[_-]?token|secret[_-]?key|private[_-]?key|password|SHOPIFY_API_KEY|SHOPIFY_API_SECRET)\s*[:=]/i.test(
+          content,
+        )
+
+      if (hasSecrets) {
+        // Only a file that git confirms is BOTH untracked and ignored may be
+        // downgraded. Being listed in .gitignore proves nothing on its own:
+        // a file committed before it was ignored stays tracked forever, which
+        // is the single most common way secrets leak. Anything we cannot
+        // positively confirm as safe stays critical (fail closed).
+        const safe = status.tracked === false && status.ignored === true
+        let title = 'Environment file with secrets committed to repository'
+        let message = `${envFile} contains secret-like values and its git status could not be determined${status.reason ? ` (${status.reason})` : ''}. Treating as exposed. Rotate any exposed secrets and confirm the file is untracked.`
+        let fixDescription = `Add ${envFile} to .gitignore, confirm with 'git ls-files ${envFile}', and rotate secrets if it was ever committed`
+        if (safe) {
+          title = 'Environment file with secrets (untracked and gitignored)'
+          message = `${envFile} contains secret-like values. git confirms it is untracked and ignored, so it is not in the repository. Keep it that way.`
+          fixDescription = `No action required beyond keeping ${envFile} out of version control`
+        } else if (status.tracked === true) {
+          title = 'Environment file with secrets is tracked by git'
+          message = `${envFile} contains secret-like values and IS TRACKED BY GIT (confirmed via git ls-files), so the secrets are in the repository history${status.ignored ? ' — adding it to .gitignore after committing does not remove it' : ''}. Rotate every exposed secret and purge the file from history.`
+          fixDescription = `git rm --cached ${envFile}, add it to .gitignore, purge it from history (git filter-repo), and rotate every secret it contained`
+        }
+        issues.push({
+          id: 'COMMITTED_SECRET',
+          severity: safe ? 'medium' : 'critical',
+          points: safe ? -7 : -50,
+          title,
+          message,
+          location: {file: envFile},
+          detection_evidence: status.evidence,
+          fix: {
+            automated: false,
+            description: fixDescription,
+          },
+        })
+      } else {
+        // .env file exists but contains no secrets — low-priority advisory.
+        issues.push({
+          id: 'COMMITTED_SECRET',
+          severity: 'low',
+          points: -2,
+          title: 'Environment file present (no secrets detected)',
+          message: `${envFile} is present but does not appear to contain secret values. Verify it is in .gitignore to prevent future secrets from being committed.`,
+          location: {file: envFile},
+          fix: {
+            automated: false,
+            description: `Add ${envFile} to .gitignore as a precaution`,
+          },
+        })
+      }
+    }
+  }
+
+  // Check for .env.secrets and similar
+  const secretFiles = ['.env.secrets', '.env.keys', 'secrets.json', 'credentials.json']
+  for (const secretFile of secretFiles) {
+    const secretPath = joinPath(appRoot, secretFile)
+    if (!fileExistsSync(secretPath)) continue
+    // Keep git probes sequential to avoid spawning competing processes for one repository.
+    // eslint-disable-next-line no-await-in-loop
+    const status = await gitStatusFor(appRoot, secretFile)
+    // Fail closed: only skip when git positively confirms untracked + ignored.
+    if (!(status.tracked === false && status.ignored === true)) {
+      issues.push({
+        id: 'COMMITTED_SECRET',
+        severity: 'critical',
+        points: -50,
+        title: status.tracked === true ? 'Secret file is tracked by git' : 'Secret file in repository',
+        message:
+          status.tracked === true
+            ? `${secretFile} IS TRACKED BY GIT (confirmed via git ls-files), so its contents are in the repository history. Rotate every secret it contains and purge it from history.`
+            : `${secretFile} is present in the project and could not be confirmed as untracked-and-ignored${status.reason ? ` (${status.reason})` : ''}. Treating as exposed.`,
+        location: {file: secretFile},
+        detection_evidence: status.evidence,
+        fix: {
+          automated: false,
+          description:
+            status.tracked === true
+              ? `git rm --cached ${secretFile}, add it to .gitignore, purge from history, and rotate every secret`
+              : `Add ${secretFile} to .gitignore, confirm with 'git ls-files ${secretFile}', and rotate any exposed secrets`,
+        },
+      })
+    }
+  }
+
+  // Scan source files for hardcoded API key patterns
+  for (const file of sourceFiles) {
+    if (!file.content) continue
+    // Skip .env files (already checked above), node_modules, and test files
+    if (file.path.includes('node_modules')) continue
+    if (file.path.endsWith('.env') || file.path.includes('.env.')) continue
+    if (file.path.includes('.test.') || file.path.includes('.spec.')) continue
+    // Skip test fixture/config files — app-configs, test-utils, fixtures
+    if (/app[._-]?configs|test[._-]?utils|fixtures/i.test(file.path)) continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      for (const pattern of SECRET_PATTERNS) {
+        // Patterns are non-global so `.test()` has no lastIndex state to leak
+        // between iterations. Do not add the /g flag here.
+        if (!pattern.regex.test(line)) continue
+        issues.push({
+          id: 'COMMITTED_SECRET',
+          severity: 'critical',
+          points: -50,
+          title: `Hardcoded ${pattern.name} detected`,
+          message: `A ${pattern.name} pattern was found in source code. Never hardcode secrets — use environment variables.`,
+          location: {file: file.path, line: i + 1},
+          snippet: redactMatch(line, pattern),
+          fix: {
+            automated: false,
+            description: 'Move the secret to an environment variable and rotate it immediately',
+          },
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Ask git directly whether a file is tracked and whether it is ignored.
+ *
+ * Hand-parsing .gitignore cannot answer either question correctly:
+ *   - Presence in .gitignore does NOT imply the file is untracked. A file
+ *     committed before being ignored stays tracked, and its secrets stay in
+ *     history. That is the most common real-world leak, and the previous
+ *     hand-rolled check downgraded exactly that case from critical to medium.
+ *   - Real gitignore semantics include negation (!pattern), directory scoping,
+ *     nested .gitignore files, ** globs and precedence rules. A substring and
+ *     trailing-* check gets all of them wrong.
+ *
+ * `tracked`/`ignored` are tri-state: `undefined` means "could not determine"
+ * (no git, not a repo, git failed). Callers MUST treat undefined as unsafe.
+ */
+export interface GitFileStatus {
+  /** true = git tracks it, false = git confirms untracked, undefined = unknown */
+  tracked?: boolean
+  /** true = git confirms ignored, false = not ignored, undefined = unknown */
+  ignored?: boolean
+  /** Why the status is unknown, when it is. */
+  reason?: string
+  /** Commands run and their verdicts, for the trace. */
+  evidence?: string[]
+}
+
+export async function gitStatusFor(appRoot: string, file: string): Promise<GitFileStatus> {
+  const run = async (args: string[]): Promise<{ok: boolean; out: string}> => {
+    const result = await captureOutputWithExitCode('git', args, {cwd: appRoot})
+    return {ok: result.exitCode === 0, out: result.stdout.trim()}
+  }
+
+  // Is this even a git repo? If not, we cannot confirm anything.
+  const inRepo = await run(['rev-parse', '--is-inside-work-tree'])
+  if (!inRepo.ok || inRepo.out !== 'true') {
+    return {
+      tracked: undefined,
+      ignored: undefined,
+      reason: 'not a git repository, or git unavailable',
+      evidence: ['git rev-parse --is-inside-work-tree → not a work tree'],
+    }
+  }
+
+  const evidence: string[] = []
+
+  // Tracked? `git ls-files --error-unmatch` exits non-zero when untracked.
+  const ls = await run(['ls-files', '--error-unmatch', '--', file])
+  const tracked = ls.ok && ls.out.length > 0
+  evidence.push(`git ls-files --error-unmatch ${file} → ${tracked ? 'TRACKED' : 'untracked'}`)
+
+  // Ignored? `git check-ignore -q` exits 0 when the path is ignored. It applies
+  // full gitignore semantics including negation and nested ignore files.
+  const ci = await run(['check-ignore', '-q', '--', file])
+  const ignored = ci.ok
+  evidence.push(`git check-ignore -q ${file} → ${ignored ? 'ignored' : 'not ignored'}`)
+
+  return {tracked, ignored, evidence}
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/security-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/security-rules.ts
new file mode 100644
index 00000000000..749312d2c99
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/security-rules.ts
@@ -0,0 +1,140 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: METAFIELD_OFFLINE_TOKEN (-15, high)
+ *
+ * Metafield writes (metafieldsSet) should use online session tokens,
+ * not offline tokens. Online tokens are user-scoped and expire, which
+ * means the write is attributable to a specific user session. Offline
+ * tokens are shop-scoped and permanent — a metafield write with an
+ * offline token has no user attribution and no expiry.
+ *
+ * This rule detects metafieldsSet calls that appear in the context of
+ * unauthenticated.admin() — which uses offline tokens by definition.
+ */
+
+const RULE_ID = 'METAFIELD_OFFLINE_TOKEN'
+const POINTS = -15
+const SEVERITY: Issue['severity'] = 'high'
+const TITLE = 'Metafield write using offline token context'
+
+export function scanMetafieldOfflineToken(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+  const seen = new Set<string>()
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb'].includes(file.ext)) continue
+
+    const content = file.content
+
+    // JS/TS: unauthenticated.admin(...) + metafieldsSet in same file
+    if (['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) {
+      const hasUnauthAdmin = /unauthenticated\.admin\s*\(/.test(content)
+      const hasMetafieldWrite = /metafields?Set|metafields?\/.*(?:POST|PUT|create|update)/i.test(content)
+
+      if (hasUnauthAdmin && hasMetafieldWrite) {
+        const key = file.path
+        if (seen.has(key)) continue
+        seen.add(key)
+        issues.push({
+          id: RULE_ID,
+          severity: SEVERITY,
+          points: POINTS,
+          title: TITLE,
+          message: `metafieldsSet is called in a file that also uses unauthenticated.admin() — metafield writes should use online session tokens (authenticate.admin), not offline tokens (unauthenticated.admin).`,
+          location: {file: file.path},
+          fix: {
+            automated: false,
+            description:
+              'Use authenticate.admin(request) instead of unauthenticated.admin() for metafield writes. Online tokens provide user attribution and expiry.',
+            guide:
+              'https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+          },
+          confidence: 'needs_review',
+        })
+      }
+    }
+
+    // Ruby: ShopifyAPI::Context with is_embedded but using offline sessions
+    if (file.ext === '.rb') {
+      const hasMetafieldWrite = /metafield.*(?:create|update|save|set)/i.test(content)
+      const hasOfflineOnly = /shop_session_repository/.test(content) && !/user_session_repository/.test(content)
+
+      if (hasMetafieldWrite && hasOfflineOnly) {
+        const key = file.path
+        if (seen.has(key)) continue
+        seen.add(key)
+        issues.push({
+          id: RULE_ID,
+          severity: SEVERITY,
+          points: POINTS,
+          title: TITLE,
+          message: `Metafield write in a Rails app that uses offline-only sessions (config.shop_session_repository without config.user_session_repository). Metafield writes should use online tokens.`,
+          location: {file: file.path},
+          fix: {
+            automated: false,
+            description: 'Add config.user_session_repository to enable online (user) sessions for metafield writes.',
+            guide:
+              'https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+          },
+          confidence: 'needs_review',
+        })
+      }
+    }
+  }
+
+  return issues
+}
+
+/**
+ * Rule: MISSING_EMBEDDED_CSP (-10, high)
+ *
+ * Embedded Shopify apps must set a Content-Security-Policy frame-ancestors
+ * directive. Without it, any origin can iframe the app — a clickjacking risk.
+ * The existing STATIC_FRAME_ANCESTORS rule catches wildcards; this rule
+ * catches the *absence* of any frame-ancestors in an embedded app.
+ */
+
+const CSP_RULE_ID = 'MISSING_EMBEDDED_CSP'
+const CSP_POINTS = -10
+const CSP_SEVERITY: Issue['severity'] = 'high'
+const CSP_TITLE = 'Embedded app missing frame-ancestors CSP directive'
+
+export function scanMissingEmbeddedCsp(files: SourceFile[], isEmbedded: boolean): Issue[] {
+  // This check only applies to embedded apps.
+  if (!isEmbedded) return []
+
+  const issues: Issue[] = []
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+
+    // Look for document response header setup (where CSP would be set)
+    const hasResponseHeaders =
+      /addDocumentResponseHeaders|Content-Security-Policy|frame-ancestors|documentResponseHeaders/i.test(file.content)
+
+    // If this file sets up response headers but doesn't mention frame-ancestors
+    if (hasResponseHeaders && !/frame-ancestors/i.test(file.content)) {
+      issues.push({
+        id: CSP_RULE_ID,
+        severity: CSP_SEVERITY,
+        points: CSP_POINTS,
+        title: CSP_TITLE,
+        message: `This embedded app sets document response headers but does not include a frame-ancestors directive. Without frame-ancestors, any origin can iframe the app — a clickjacking risk.`,
+        location: {file: file.path},
+        fix: {
+          automated: false,
+          description:
+            "Add frame-ancestors to your CSP, restricted to the authenticated shop domain and admin.shopify.com. Use Shopify App Remix's addDocumentResponseHeaders for automatic handling.",
+          guide: 'https://shopify.dev/docs/apps/build/security/set-up-iframe-protection',
+        },
+        confidence: 'needs_review',
+      })
+    }
+  }
+
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/shopify-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/shopify-rules.ts
new file mode 100644
index 00000000000..a34a340ccad
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/shopify-rules.ts
@@ -0,0 +1,351 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+const IDENTIFIER_PATTERN_SOURCE = '[A-Za-z_$][\\w$]*'
+const SHOP_FIELD_PATTERN_SOURCE = 'shop(?:_?[iI]d|_?[dD]omain)?'
+
+const REQUEST_FORM_DATA_BINDING_PATTERN = new RegExp(
+  `(?:const|let|var)\\s+(${IDENTIFIER_PATTERN_SOURCE})\\s*=\\s*await\\s+(?:req|request)\\.formData\\s*\\(\\s*\\)`,
+  'g',
+)
+const REQUEST_MEMBER_SHOP_ASSIGNMENT_PATTERN = new RegExp(
+  `(?:const|let|var)\\s+(${IDENTIFIER_PATTERN_SOURCE})\\s*=\\s*(?:req|request)\\.(?:body|query|params)(?:\\.\\s*${SHOP_FIELD_PATTERN_SOURCE}|\\[\\s*["']${SHOP_FIELD_PATTERN_SOURCE}["']\\s*\\])`,
+  'g',
+)
+const REQUEST_JSON_SHOP_DESTRUCTURE_PATTERN = new RegExp(
+  `(?:const|let|var)\\s*\\{[^}]{0,200}\\b(${SHOP_FIELD_PATTERN_SOURCE})\\b[^}]{0,200}\\}\\s*=\\s*await\\s+(?:req|request)\\.json\\s*\\(\\s*\\)`,
+  'g',
+)
+const UNAUTHENTICATED_ADMIN_IDENTIFIER_ARGUMENT_PATTERN = new RegExp(
+  `\\bunauthenticated\\.admin\\s*\\(\\s*(${IDENTIFIER_PATTERN_SOURCE})\\s*\\)`,
+  'g',
+)
+const CONFIG_SCRIPT_FIELD_PATTERN =
+  /\b(?:external_?script|custom_?js|custom_?script|custom_?javascript|injected_?js|remote_?script)\b/i
+const SCRIPT_EXECUTION_SINK_PATTERN =
+  /\beval\s*\(|new\s+Function\s*\(|createElement\(\s*["']script["']\s*\)|\.insertAdjacentHTML\s*\(|document\.write(?:ln)?\s*\(|dangerouslySetInnerHTML|\.(?:inner|outer)HTML\s*=|\.srcdoc\s*=|\.src\s*=/
+const SCRIPT_SOURCE_VALIDATION_PATTERN =
+  /allow[_-]?list|ALLOWED_(?:SCRIPT|DOMAIN|HOST|SRC)|\bisAllowed\w*\s*\(|\bsanitize\w*\s*\(/i
+const SCRIPT_TAG_CREATION_PATTERN = [
+  /\bscriptTagCreate\b|\bscriptTagUpdate\b/,
+  /\bnew\s+[\w.]*\bScriptTag\s*\(/,
+  /\b(?:post|put)\b[^\n]{0,120}script_tags/i,
+]
+const APP_PROXY_PARAM_READ_PATTERN = /\blogged_in_customer_id\b|\bpath_prefix\b/
+const APP_PROXY_VERIFICATION_PATTERN =
+  /authenticate\.public\.appProxy|\b[A-Za-z]{0,40}(?:verif|valid|check|assert|authenticat)[A-Za-z]{0,40}(?:proxy|signature|hmac)[A-Za-z]{0,40}\s*\(|createHmac|timingSafeEqual|["']signature["']|\.signature\b/i
+const CONFIG_WRITE_PATTERN =
+  /metafieldsSet|metafields?\b[^\n]{0,80}(?:set|create|update|write)|\b(?:settings?|config(?:uration)?)\w*\b[^\n]{0,120}\.(?:update|upsert|save|create|updateOne|updateMany|findOneAndUpdate|set)\s*\(|\.(?:update|upsert|updateOne|findOneAndUpdate)\s*\(\s*\{[^}]{0,120}\bshop/i
+const SESSION_VERIFICATION_PATTERN =
+  /authenticate\.(?:admin|public|webhook|flow|fulfillmentService)|verifyRequest|validateAuthenticatedSession|session[_-]?token|getSessionToken|decodeSessionToken|jwt\.verify|\bverify(?:Jwt|Session|Hmac|Signature)\w*\s*\(|createHmac|timingSafeEqual/i
+const WILDCARD_FRAME_ANCESTORS_PATTERN = /frame-ancestors[^;"'`\n]*(?:\s\*(?:\s|;|["'`]|$)|\*\.myshopify\.com)/i
+const SHOPIFY_APP_CONTEXT_PATTERN = /@shopify\/shopify-app|@shopify\/shopify-api|myshopify\.com/
+const DYNAMIC_POLICY_PATTERN = /frame-ancestors[^;"'`\n]*(?:\$\{|["'`]\s*\+)/i
+const stripComments = (content: string): string => {
+  let result = ''
+  let index = 0
+  let quote: string | null = null
+  while (index < content.length) {
+    const character = content[index]
+    const nextCharacter = content[index + 1]
+    if (quote !== null) {
+      result += character
+      if (character === '\\') {
+        result += nextCharacter ?? ''
+        index += 2
+        continue
+      }
+      if (character === quote) quote = null
+      index += 1
+      continue
+    }
+    if (character === '"' || character === "'" || character === '`') {
+      quote = character
+      result += character
+      index += 1
+      continue
+    }
+    if (character === '/' && nextCharacter === '/') {
+      while (index < content.length && content[index] !== '\n') {
+        result += ' '
+        index += 1
+      }
+      continue
+    }
+    if (character === '/' && nextCharacter === '*') {
+      result += '  '
+      index += 2
+      while (index < content.length && !(content[index] === '*' && content[index + 1] === '/')) {
+        result += content[index] === '\n' ? '\n' : ' '
+        index += 1
+      }
+      if (index < content.length) {
+        result += '  '
+        index += 2
+      }
+      continue
+    }
+    result += character
+    index += 1
+  }
+  return result
+}
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const collectBindings = (content: string, pattern: RegExp): Set<string> => {
+  const bindings = new Set<string>()
+  pattern.lastIndex = 0
+  let match = pattern.exec(content)
+  while (match !== null) {
+    if (match[1]) bindings.add(match[1])
+    match = pattern.exec(content)
+  }
+  return bindings
+}
+
+const collectRequestFormDataBindings = (content: string): Set<string> =>
+  collectBindings(content, REQUEST_FORM_DATA_BINDING_PATTERN)
+
+const collectRequestControlledShopBindings = (content: string): Set<string> => {
+  const bindings = new Set<string>([
+    ...collectBindings(content, REQUEST_MEMBER_SHOP_ASSIGNMENT_PATTERN),
+    ...collectBindings(content, REQUEST_JSON_SHOP_DESTRUCTURE_PATTERN),
+  ])
+
+  for (const formDataBinding of collectRequestFormDataBindings(content)) {
+    const formDataShopAssignmentPattern = new RegExp(
+      `(?:const|let|var)\\s+(${IDENTIFIER_PATTERN_SOURCE})\\s*=\\s*${escapeRegExp(formDataBinding)}\\.get\\s*\\(\\s*["']${SHOP_FIELD_PATTERN_SOURCE}["']\\s*\\)`,
+      'g',
+    )
+    for (const binding of collectBindings(content, formDataShopAssignmentPattern)) bindings.add(binding)
+  }
+
+  return bindings
+}
+
+const lineAtIndex = (content: string, index: number): number => content.slice(0, index).split('\n').length
+
+const snippetAtIndex = (content: string, index: number): string =>
+  content.slice(index, content.indexOf('\n', index) === -1 ? undefined : content.indexOf('\n', index)).trim()
+
+const makeIssue = (input: {
+  id: string
+  severity: Issue['severity']
+  points: number
+  title: string
+  message: string
+  file: SourceFile
+  index: number
+  fix: string
+  guide?: string
+  confidence?: Issue['confidence']
+}): Issue => ({
+  id: input.id,
+  severity: input.severity,
+  points: input.points,
+  title: input.title,
+  message: input.message,
+  location: {
+    file: input.file.path,
+    line: lineAtIndex(input.file.content ?? '', input.index),
+  },
+  snippet: snippetAtIndex(input.file.content ?? '', input.index),
+  fix: {automated: false, description: input.fix, guide: input.guide},
+  confidence: input.confidence ?? 'definite',
+})
+
+export const scanRequestControlledAdminContext = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    const requestControlledShopBindings = collectRequestControlledShopBindings(content)
+    UNAUTHENTICATED_ADMIN_IDENTIFIER_ARGUMENT_PATTERN.lastIndex = 0
+    let match = UNAUTHENTICATED_ADMIN_IDENTIFIER_ARGUMENT_PATTERN.exec(content)
+    while (match !== null) {
+      if (match[1] && requestControlledShopBindings.has(match[1])) {
+        issues.push(
+          makeIssue({
+            id: 'REQUEST_CONTROLLED_ADMIN_CONTEXT',
+            severity: 'critical',
+            points: -30,
+            title: 'Request input selects Admin API shop context',
+            message:
+              "A request-controlled shop value is passed to unauthenticated.admin(...), so the caller can choose which shop's Admin API context this route uses.",
+            file,
+            index: match.index,
+            fix: 'Use the Admin API context returned by authenticate.admin(request). Never pass form, JSON, query, or route input into unauthenticated.admin(...).',
+            guide:
+              'https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens',
+            confidence: 'needs_review',
+          }),
+        )
+      }
+      match = UNAUTHENTICATED_ADMIN_IDENTIFIER_ARGUMENT_PATTERN.exec(content)
+    }
+
+    for (const formDataBinding of collectRequestFormDataBindings(content)) {
+      const directPattern = new RegExp(
+        `\\bunauthenticated\\.admin\\s*\\(\\s*${escapeRegExp(formDataBinding)}\\.get\\s*\\(\\s*["']${SHOP_FIELD_PATTERN_SOURCE}["']\\s*\\)\\s*\\)`,
+        'g',
+      )
+      let directMatch = directPattern.exec(content)
+      while (directMatch !== null) {
+        issues.push(
+          makeIssue({
+            id: 'REQUEST_CONTROLLED_ADMIN_CONTEXT',
+            severity: 'critical',
+            points: -30,
+            title: 'Request input selects Admin API shop context',
+            message:
+              "A request-controlled shop value is passed to unauthenticated.admin(...), so the caller can choose which shop's Admin API context this route uses.",
+            file,
+            index: directMatch.index,
+            fix: 'Use the Admin API context returned by authenticate.admin(request). Never pass form, JSON, query, or route input into unauthenticated.admin(...).',
+            guide:
+              'https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/online-access-tokens',
+            confidence: 'needs_review',
+          }),
+        )
+        directMatch = directPattern.exec(content)
+      }
+    }
+  }
+  return issues
+}
+
+export const scanRuntimeConfigScriptExecution = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    const match = CONFIG_SCRIPT_FIELD_PATTERN.exec(content)
+    if (!match || !SCRIPT_EXECUTION_SINK_PATTERN.test(content) || SCRIPT_SOURCE_VALIDATION_PATTERN.test(content))
+      continue
+    issues.push(
+      makeIssue({
+        id: 'RUNTIME_CONFIG_SCRIPT_EXECUTION',
+        severity: 'critical',
+        points: -25,
+        title: 'Runtime config field is executed as script',
+        message:
+          'A config field named as executable script appears in a file that also injects or evaluates scripts. Config-delivered script bypasses extension versioning and review.',
+        file,
+        index: match.index,
+        fix: 'Ship storefront JavaScript as static versioned extension assets. Treat runtime config as data only, never as executable code or script URLs.',
+        confidence: 'needs_review',
+      }),
+    )
+  }
+  return issues
+}
+
+export const scanDeprecatedScriptTagApi = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    for (const pattern of SCRIPT_TAG_CREATION_PATTERN) {
+      const match = pattern.exec(content)
+      if (!match) continue
+      issues.push(
+        makeIssue({
+          id: 'DEPRECATED_SCRIPT_TAG_API',
+          severity: 'high',
+          points: -12,
+          title: 'Deprecated ScriptTag API expands storefront attack surface',
+          message:
+            'This code uses the deprecated ScriptTag API. ScriptTags run remotely hosted, silently replaceable JavaScript in every storefront session, so a stolen API token or compromised backend can affect every installed shop at once.',
+          file,
+          index: match.index,
+          fix: 'Migrate storefront UI to a theme app extension or analytics to a web pixel instead of creating ScriptTags.',
+          guide: 'https://shopify.dev/docs/apps/build/online-store/theme-app-extensions',
+        }),
+      )
+      break
+    }
+  }
+  return issues
+}
+
+export const scanAppProxyUnverifiedSignature = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    const match = APP_PROXY_PARAM_READ_PATTERN.exec(content)
+    if (!match || !/\b(?:req|request)\b/.test(content) || APP_PROXY_VERIFICATION_PATTERN.test(content)) continue
+    issues.push(
+      makeIssue({
+        id: 'APP_PROXY_UNVERIFIED_SIGNATURE',
+        severity: 'high',
+        points: -15,
+        title: 'App proxy request trusted without signature verification',
+        message:
+          'App proxy parameters are read without an obvious signature verification step. Unsigned proxy parameters are attacker-controlled URL input.',
+        file,
+        index: match.index,
+        fix: 'Verify the app proxy signature before trusting shop, logged_in_customer_id, path_prefix, or other proxy parameters. With Shopify App Remix, use authenticate.public.appProxy(request).',
+        guide: 'https://shopify.dev/docs/apps/build/online-store/app-proxies/authenticate-app-proxies',
+        confidence: 'needs_review',
+      }),
+    )
+  }
+  return issues
+}
+
+export const scanUnscopedShopConfigWrite = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    const bindings = collectRequestControlledShopBindings(content)
+    if (bindings.size === 0 || !CONFIG_WRITE_PATTERN.test(content) || SESSION_VERIFICATION_PATTERN.test(content))
+      continue
+    const firstBinding = [...bindings][0]
+    const matchIndex = firstBinding ? content.indexOf(firstBinding) : 0
+    issues.push(
+      makeIssue({
+        id: 'UNSCOPED_SHOP_CONFIG_WRITE',
+        severity: 'high',
+        points: -15,
+        title: 'Config write trusts shop from request input',
+        message:
+          'The target shop comes from client-supplied request input and flows into a configuration write without visible session or signature verification.',
+        file,
+        index: Math.max(0, matchIndex),
+        fix: 'Derive the target shop from an authenticated session or verified HMAC, never from request body, query, params, or form data.',
+        guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+        confidence: 'needs_review',
+      }),
+    )
+  }
+  return issues
+}
+
+export const scanStaticFrameAncestors = (files: SourceFile[]): Issue[] => {
+  const issues: Issue[] = []
+  for (const file of files) {
+    if (!file.content || !['.js', '.ts', '.jsx', '.tsx'].includes(file.ext)) continue
+    const content = stripComments(file.content)
+    const match = WILDCARD_FRAME_ANCESTORS_PATTERN.exec(content)
+    if (!match || !SHOPIFY_APP_CONTEXT_PATTERN.test(content) || DYNAMIC_POLICY_PATTERN.test(content)) continue
+    issues.push(
+      makeIssue({
+        id: 'STATIC_FRAME_ANCESTORS',
+        severity: 'high',
+        points: -12,
+        title: 'Embedded app frame-ancestors uses a wildcard',
+        message:
+          'This Content-Security-Policy allows any origin or any myshopify.com shop to frame the app. Embedded apps should restrict frame-ancestors to the current shop and admin.shopify.com.',
+        file,
+        index: match.index,
+        fix: 'Build frame-ancestors per request from the authenticated shop domain and admin.shopify.com, or use Shopify App Remix response header helpers.',
+        guide: 'https://shopify.dev/docs/apps/build/security/set-up-iframe-protection',
+        confidence: 'needs_review',
+      }),
+    )
+  }
+  return issues
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/tenant-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/tenant-rules.ts
new file mode 100644
index 00000000000..8d0b1e525ae
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/tenant-rules.ts
@@ -0,0 +1,135 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: MISSING_TENANT_ISOLATION (-20, high, needs_review)
+ *
+ * The most common real vulnerability class in Shopify apps: database
+ * queries not scoped by shop. A Remix app doing
+ * `prisma.order.findMany({ where: { id } })` without `shop` in the
+ * where clause leaks data across tenants.
+ *
+ * This is inherently noisy — static analysis can't prove a query is
+ * unscoped without understanding the full data model. So this rule is
+ * always `needs_review` — it surfaces the pattern for human/agent review
+ * but does not affect the score.
+ *
+ * Detection:
+ * - Prisma: findMany/findFirst/findUnique with a where clause that
+ *   doesn't reference shop/session
+ * - Rails: Model.where(...) without shop_id or shop: in conditions
+ * - Sequelize: findAll/findOne with where that doesn't reference shop
+ *
+ * Only scans files in authenticated route handlers ( loaders/actions in
+ * Remix, controller actions in Rails) — public routes don't have a
+ * shop context to scope by.
+ */
+
+const RULE_ID = 'MISSING_TENANT_ISOLATION'
+const POINTS = -20
+const SEVERITY: Issue['severity'] = 'high'
+const TITLE = 'Database query may not be scoped by shop'
+
+export function scanMissingTenantIsolation(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+  const seen = new Set<string>()
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb'].includes(file.ext)) continue
+
+    // Skip test files — test fixtures contain DB queries that aren't
+    // real app code. Covers: *.test.*, *.spec.*, *_test.rb,
+    // test/*, tests/*, __tests__/*, etc.
+    if (
+      /\b(test|spec|fixture|mock|__test)\b/i.test(file.path) ||
+      /_test\.rb$/i.test(file.path) ||
+      /\btests?\//.test(file.path)
+    )
+      continue
+
+    const content = file.content
+
+    // Only scan files that look like route handlers / controllers
+    // (have authenticate or loader/action patterns)
+    const isRouteHandler =
+      /export\s+(?:async\s+)?(?:const|function)\s+(?:loader|action)\b/.test(content) ||
+      /authenticate\.admin\s*\(/.test(content) ||
+      (/class.*Controller/.test(content) && file.ext === '.rb')
+
+    if (!isRouteHandler) continue
+
+    // Skip internal controllers — same reasoning as lib/ skip:
+    // auth lives at the route level (namespace :internal), not in the controller.
+    if (/\binternal\//.test(file.path) || /\binternal_/.test(file.path)) continue
+
+    const lines = content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      const trimmed = line.trim()
+
+      // Skip comments
+      if (/^\s*(\/\/|#|\/\*|\*)/.test(trimmed)) continue
+
+      // --- Prisma patterns (JS/TS) ---
+      // findMany({ where: { id } }) — no shop in where
+      if (/\.(findMany|findFirst|findUnique|findUniqueOrThrow)\s*\(/.test(trimmed)) {
+        // Check next ~5 lines for the where clause (narrower window to avoid
+        // picking up unrelated shop mentions in surrounding code)
+        const context = lines.slice(i, i + 5).join('\n')
+        // If the where clause doesn't mention shop, session, or shopId → flag
+        if (/where\s*:/.test(context) && !/\bshop\b|shopId|shop_id|session\.shop|session\.domain/i.test(context)) {
+          const key = `${file.path}:${i + 1}`
+          if (seen.has(key)) continue
+          seen.add(key)
+          issues.push(makeIssue(file.path, i + 1, 'Prisma query without shop scope', trimmed))
+        }
+      }
+
+      // --- Rails patterns (Ruby) ---
+      // Model.where(...) without shop_id or shop: in conditions
+      if (file.ext === '.rb') {
+        // .where(condition) without shop_id
+        if (/\.where\s*\(/.test(trimmed) && !/shop_id|shop\b.*:|current_shop|shopify_domain/i.test(trimmed)) {
+          // Skip if it's a Shop model query itself
+          if (/Shop\.where|shop\.where/i.test(trimmed)) continue
+          const key = `${file.path}:${i + 1}`
+          if (seen.has(key)) continue
+          seen.add(key)
+          issues.push(makeIssue(file.path, i + 1, 'Rails query without shop scope', trimmed))
+        }
+      }
+
+      // --- Sequelize patterns (JS/TS) ---
+      if (/\.findAll\s*\(/.test(trimmed) || /\.findOne\s*\(/.test(trimmed)) {
+        const context = lines.slice(i, i + 10).join('\n')
+        if (/where\s*:/.test(context) && !/\bshop\b|shopId|shop_id|session\.(shop|domain)/i.test(context)) {
+          const key = `${file.path}:${i + 1}`
+          if (seen.has(key)) continue
+          seen.add(key)
+          issues.push(makeIssue(file.path, i + 1, 'Sequelize query without shop scope', trimmed))
+        }
+      }
+    }
+  }
+
+  return issues
+}
+
+function makeIssue(file: string, line: number, type: string, snippet: string): Issue {
+  return {
+    id: RULE_ID,
+    severity: SEVERITY,
+    points: POINTS,
+    title: TITLE,
+    message: `${type} in an authenticated route handler. The where clause does not reference the shop domain or session — this query may return data from other tenants. In a multi-tenant Shopify app, always scope database queries by the authenticated shop.`,
+    location: {file, line},
+    snippet: snippet.substring(0, 80),
+    fix: {
+      automated: false,
+      description:
+        "Add the authenticated shop to the query's where clause: where: { id, shop: session.shop } or where: { shop_id: current_shop.id }.",
+      guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/session-tokens',
+    },
+    confidence: 'needs_review',
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/token-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/token-rules.ts
new file mode 100644
index 00000000000..974c37bf655
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/token-rules.ts
@@ -0,0 +1,137 @@
+import {readFileSync} from '@shopify/cli-kit/node/fs'
+import {joinPath} from '@shopify/cli-kit/node/path'
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/**
+ * Rule: EXPIRING_OFFLINE_TOKEN (-20, high)
+ *
+ * Shopify is requiring apps to migrate from permanent offline access tokens
+ * to online tokens (which expire and must be refreshed). The deadline is
+ * January 1, 2026. As of August 2026, adoption was at ~40%.
+ *
+ * This rule detects apps that have not opted into the migration:
+ *
+ * - Remix/JS: `shopifyApp()` config without `expiringOfflineAccessTokens: true`
+ *   in the `future` flags, or explicit `isOnline: false`
+ * - Rails: `config.shop_session_repository` set but `config.user_session_repository`
+ *   NOT set (offline-only, no user-level online sessions)
+ * - Any app: `isOnline: false` in authentication setup
+ */
+
+const RULE_ID = 'EXPIRING_OFFLINE_TOKEN'
+const POINTS = -20
+const SEVERITY: Issue['severity'] = 'high'
+const TITLE = 'Expiring offline access tokens not enabled'
+
+export function scanExpiringOfflineTokens(sourceFiles: SourceFile[], appRoot: string): Issue[] {
+  const issues: Issue[] = []
+  // Deduplicate issues by file.
+  const seen = new Set<string>()
+
+  for (const file of sourceFiles) {
+    if (!file.content) continue
+
+    // --- Remix / JS / TS: shopifyApp() config ---
+    if (['.ts', '.tsx', '.js', '.jsx'].includes(file.ext)) {
+      // Check if this file sets up shopifyApp()
+      if (!/shopifyApp\s*\(/.test(file.content)) continue
+
+      // If they explicitly set expiringOfflineAccessTokens: true, they're compliant
+      if (/expiringOfflineAccessTokens\s*:\s*true/.test(file.content)) continue
+
+      // If they explicitly set isOnline: false, that's a clear violation
+      const isOnlineFalse = /isOnline\s*:\s*false/.test(file.content)
+
+      // If they have the future flag but it's false or not set to true
+      const hasFutureFlags = /future\s*:/.test(file.content)
+      const hasExpiringFlag = /expiringOfflineAccessTokens/.test(file.content)
+
+      if (isOnlineFalse) {
+        issues.push(
+          makeIssue(file.path, `Explicit isOnline: false in ${file.path} — app uses permanent offline tokens`),
+        )
+      } else if (hasFutureFlags && !hasExpiringFlag) {
+        issues.push(
+          makeIssue(
+            file.path,
+            `shopifyApp() config has future flags but does not enable expiringOfflineAccessTokens: true`,
+          ),
+        )
+      } else if (!hasFutureFlags) {
+        issues.push(
+          makeIssue(
+            file.path,
+            `shopifyApp() config does not set future.expiringOfflineAccessTokens: true — app may be using permanent offline tokens`,
+          ),
+        )
+      }
+    }
+
+    // --- Rails: shopify_app.rb initializer ---
+    if (file.ext === '.rb' && /shopify_app/i.test(file.path)) {
+      // Strip Ruby comments (lines starting with #) before checking
+      const activeLines = file.content
+        .split('\n')
+        .filter((line) => !/^\s*#/.test(line))
+        .join('\n')
+      const hasShopSession = /config\.shop_session_repository\s*=/.test(activeLines)
+      const hasUserSession = /config\.user_session_repository\s*=/.test(activeLines)
+
+      // Offline-only: has shop session but no user session
+      if (hasShopSession && !hasUserSession) {
+        issues.push(
+          makeIssue(
+            file.path,
+            `Rails app uses config.shop_session_repository without config.user_session_repository — offline tokens only, no online (user) sessions`,
+          ),
+        )
+      }
+    }
+  }
+
+  // Also check shopify.app.toml for access mode hints
+  try {
+    const tomlPath = joinPath(appRoot, 'shopify.app.toml')
+    const toml = readFileSync(tomlPath).toString()
+    // Some apps declare access_mode in the TOML
+    if (/access_mode\s*=\s*["']offline["']/i.test(toml)) {
+      issues.push(
+        makeIssue(
+          'shopify.app.toml',
+          'shopify.app.toml declares access_mode = "offline" — migrate to online tokens before Jan 1, 2026',
+        ),
+      )
+    }
+    // Missing or unreadable TOML files are handled by source-file discovery.
+    // eslint-disable-next-line no-catch-all/no-catch-all
+  } catch {
+    // Nothing else to do.
+  }
+
+  // Dedup by file
+  return issues.filter((issue) => {
+    const key = issue.location.file
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+
+  function makeIssue(file: string, message: string): Issue {
+    return {
+      id: RULE_ID,
+      severity: SEVERITY,
+      points: POINTS,
+      title: TITLE,
+      message,
+      location: {file},
+      fix: {
+        automated: false,
+        description:
+          'Enable expiring offline access tokens: set future.expiringOfflineAccessTokens: true in shopifyApp() config (Remix) or add config.user_session_repository (Rails). See https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+        guide:
+          'https://shopify.dev/docs/apps/build/authentication-authorization/access-token-types/online-access-tokens',
+      },
+    }
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/types.ts b/packages/app/src/cli/services/app-doctor-engine/rules/types.ts
new file mode 100644
index 00000000000..c056c0db126
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/types.ts
@@ -0,0 +1,89 @@
+import type {Issue, Capabilities, Severity} from '../types.js'
+
+/**
+ * A rule defines:
+ * - Which capability gates it (skip if not applicable)
+ * - How to check for the issue
+ * - How many points to deduct
+ */
+export interface Rule {
+  /** Stable identifier, e.g. "DEPRECATED_SCRIPT_TAG_SCOPE" */
+  id: string
+  /** Human-readable title */
+  title: string
+  /** Default severity */
+  severity: Severity
+  /** Points deducted when this rule fires */
+  points: number
+  /** Which capability must be true for this rule to run. undefined = always runs. */
+  requires?: keyof Capabilities
+  /** The check function */
+  check: (context: ScanContext) => Issue[]
+}
+
+/**
+ * Context passed to every rule's check function.
+ */
+export interface ScanContext {
+  /** Absolute path to the app root directory */
+  appRoot: string
+  /** Contents of shopify.app.toml (parsed), or null if not found */
+  appToml: AppTomlContent | null
+  /** All extension config files found */
+  extensions: ExtensionInfo[]
+  /** All source files found (JS, TS, Liquid, PHP, Ruby, Python) */
+  sourceFiles: SourceFile[]
+  /** Package manifest files found (package.json, Gemfile, composer.json) */
+  manifests: ManifestFile[]
+  /** Detected capabilities */
+  capabilities: Capabilities
+}
+
+export interface AppTomlContent {
+  /** Raw parsed TOML object */
+  raw: Record<string, unknown>
+  /** Path to the file */
+  path: string
+  /** The scopes string, if present */
+  scopes?: string
+  /** Redirect URLs */
+  redirect_urls?: string[]
+  /** Webhook subscriptions */
+  webhooks?: WebhookSubscription[]
+  /** IP allowlist entries, if declared */
+  ip_allowlist?: string[]
+}
+
+export interface WebhookSubscription {
+  topics: string[]
+  uri: string
+}
+
+export interface ExtensionInfo {
+  /** Path to shopify.extension.toml */
+  path: string
+  /** Extension type, e.g. "theme_app_extension" */
+  type: string
+  /** All files in the extension directory */
+  files: SourceFile[]
+}
+
+export interface SourceFile {
+  /** Project-relative path */
+  path: string
+  /** Absolute path */
+  absolutePath: string
+  /** File extension */
+  ext: string
+  /** File contents (read lazily where possible) */
+  content?: string
+}
+
+export interface ManifestFile {
+  path: string
+  absolutePath: string
+  type: 'npm' | 'ruby' | 'php'
+  /** Parsed dependencies, keyed by name with version specifications as values. */
+  dependencies: Record<string, string>
+  devDependencies?: Record<string, string>
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/rules/validation-rules.ts b/packages/app/src/cli/services/app-doctor-engine/rules/validation-rules.ts
new file mode 100644
index 00000000000..619d5a29092
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/rules/validation-rules.ts
@@ -0,0 +1,118 @@
+import type {Issue} from '../types.js'
+import type {SourceFile} from './types.js'
+
+/*
+ * Rule: WEAK_SHOP_VALIDATION (-15, high)
+ *
+ * During OAuth, apps validate the `shop` parameter to ensure it's a
+ * legitimate Shopify shop domain. A common vulnerability is using an
+ * unanchored regex like /\.myshopify\.com/ which matches
+ * "evil.com/x.myshopify.com" — allowing an attacker to redirect the
+ * OAuth token to a server they control.
+ *
+ * This rule detects regex patterns that:
+ * 1. Contain "myshopify.com" (not .io, not .dev — those are different domains)
+ * 2. Are used in a validation context (not just any URL reference)
+ * 3. Are NOT anchored (^ and $)
+ *
+ * To avoid false positives, we skip:
+ * - Comments (//, #, /*)
+ * - Lines that look like URLs in strings (http://...myshopify.com/...)
+ * - Template interpolation ({shop}.myshopify.com)
+ * - Import/export statements
+ */
+
+const RULE_ID = 'WEAK_SHOP_VALIDATION'
+const POINTS = -15
+const SEVERITY: Issue['severity'] = 'high'
+const TITLE = 'Shop domain validation regex is not anchored'
+
+export function scanWeakShopValidation(files: SourceFile[]): Issue[] {
+  const issues: Issue[] = []
+  const seen = new Set<string>()
+
+  for (const file of files) {
+    if (!file.content) continue
+    if (!['.js', '.ts', '.jsx', '.tsx', '.rb'].includes(file.ext)) continue
+
+    // Skip test files — test fixtures contain myshopify.com in assertions,
+    // not actual validation code. Covers: *.test.*, *.spec.*, *_test.rb,
+    // test/*, tests/*, __tests__/*, *.test.tsx, etc.
+    if (
+      /\b(test|spec|fixture|mock|__test)\b/i.test(file.path) ||
+      /_test\.rb$/i.test(file.path) ||
+      /\btests?\//.test(file.path)
+    )
+      continue
+
+    const lines = file.content.split('\n')
+    for (const [i, line] of lines.entries()) {
+      const trimmed = line.trim()
+
+      // Skip comments
+      if (/^\s*(\/\/|#|\/\*|\*)/.test(trimmed)) continue
+      // Skip import/export/require lines
+      if (/^\s*(import|export|require)\b/.test(trimmed)) continue
+      // Skip lines that are just URLs in strings (http/https references)
+      if (
+        /https?:\/\/[^/]*myshopify\.com/i.test(trimmed) &&
+        !/regex|RegExp|match|test\(|=~|valid|sanitize|check/i.test(trimmed)
+      )
+        continue
+      // Skip template interpolation like `{shop}.myshopify.com`
+      if (
+        /\{.*\}.*myshopify\.com/i.test(trimmed) &&
+        !/regex|RegExp|match|test\(|=~|valid|sanitize|check/i.test(trimmed)
+      )
+        continue
+
+      // Only flag lines that have BOTH myshopify.com AND a validation context
+      const hasValidationContext = /regex|RegExp|match|test\(|=~|valid|sanitize|check|verify|pattern/i.test(trimmed)
+      if (!hasValidationContext) continue
+
+      // Detect regex literals containing myshopify.com (not .io, not .dev)
+      const regexMatch = line.match(/\/([^/]*myshopify[^/]*com[^/]*)\//)
+      const regexPattern = regexMatch?.[1]
+      if (regexPattern !== undefined && !isAnchored(regexPattern)) {
+        const key = `${file.path}:${i + 1}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        issues.push(makeIssue(file.path, i + 1, regexPattern, trimmed))
+      }
+
+      // Detect new RegExp("...myshopify.com...") calls
+      const newRegExpMatch = line.match(/new\s+RegExp\s*\(\s*["'`](.*?myshopify\.com.*?)["'`]/)
+      const constructorPattern = newRegExpMatch?.[1]
+      if (constructorPattern !== undefined && !isAnchored(constructorPattern)) {
+        const key = `${file.path}:${i + 1}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        issues.push(makeIssue(file.path, i + 1, constructorPattern, trimmed))
+      }
+    }
+  }
+
+  return issues
+}
+
+function isAnchored(pattern: string): boolean {
+  return /^\^/.test(pattern) && /\$[^/]*$/.test(pattern)
+}
+
+function makeIssue(file: string, line: number, pattern: string, snippet: string): Issue {
+  return {
+    id: RULE_ID,
+    severity: SEVERITY,
+    points: POINTS,
+    title: TITLE,
+    message: `Shop domain validation regex /${pattern}/ is not anchored. An unanchored regex matching "myshopify.com" can be exploited: "evil.com/x.myshopify.com" would pass validation, allowing token theft. Anchor with ^ and $.`,
+    location: {file, line},
+    snippet: snippet.substring(0, 80),
+    fix: {
+      automated: false,
+      description:
+        'Anchor the regex: /^[a-zA-Z0-9][a-zA-Z0-9-]*\\.myshopify\\.com$/ — the ^ and $ prevent prefix/suffix attacks.',
+      guide: 'https://shopify.dev/docs/apps/build/authentication-authorization/get-access-tokens/oauth',
+    },
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/scanners/discover.ts b/packages/app/src/cli/services/app-doctor-engine/scanners/discover.ts
new file mode 100644
index 00000000000..3be2387b1ab
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/scanners/discover.ts
@@ -0,0 +1,356 @@
+import fg from 'fast-glob'
+import {parse as parseToml} from '@iarna/toml'
+import {fileExistsSync, fileSizeSync, readFileSync} from '@shopify/cli-kit/node/fs'
+import {cwd, dirname, extname, joinPath, relativePath} from '@shopify/cli-kit/node/path'
+import type {AppTomlContent, ExtensionInfo, SourceFile, ManifestFile, WebhookSubscription} from '../rules/types.js'
+
+/**
+ * Find the app root by walking up from CWD looking for shopify.app.toml.
+ * If a specific path is passed (--app), use that directly.
+ */
+export function findAppRoot(startPath?: string): string {
+  if (startPath && fileExistsSync(startPath)) {
+    // If they passed a TOML file, use its directory.
+    if (startPath.endsWith('.toml')) return dirname(startPath)
+    return startPath
+  }
+
+  let dir = cwd()
+  for (let index = 0; index < 20; index++) {
+    // Check for shopify.app.toml or shopify.app.*.toml.
+    const tomls = fg.sync('shopify.app*.toml', {cwd: dir, deep: 1, onlyFiles: true})
+    if (tomls.length > 0) {
+      return dir
+    }
+    const parent = joinPath(dir, '..')
+    if (parent === dir) break
+    dir = parent
+  }
+
+  // Fallback: use CWD even without TOML (file scan mode)
+  return cwd()
+}
+
+/**
+ * Find and parse all shopify.app.*.toml files in the app root.
+ */
+export function findAppTomls(appRoot: string): AppTomlContent[] {
+  const files = fg.sync('shopify.app*.toml', {cwd: appRoot, deep: 1, onlyFiles: true})
+
+  return files.map((file) => {
+    const path = joinPath(appRoot, file)
+    const raw = parseToml(readFileSync(path).toString()) as Record<string, unknown>
+    return parseAppToml(raw, path)
+  })
+}
+
+/**
+ * Load a specific shopify.app.toml file.
+ */
+export function loadAppToml(tomlPath: string): AppTomlContent | null {
+  if (!fileExistsSync(tomlPath)) return null
+  const raw = parseToml(readFileSync(tomlPath).toString()) as Record<string, unknown>
+  return parseAppToml(raw, tomlPath)
+}
+
+export function parseAppToml(raw: Record<string, unknown>, path: string): AppTomlContent {
+  const scopes = (raw.access_scopes as Record<string, unknown>)?.scopes as string | undefined
+  const auth = raw.auth as Record<string, unknown> | undefined
+  const redirectUrls = auth?.redirect_urls as string[] | undefined
+  const webhooksSection = raw.webhooks as Record<string, unknown> | undefined
+  const webhookSubs = (webhooksSection?.subscriptions as Record<string, unknown>[])?.map(
+    (sub): WebhookSubscription => ({
+      // Merge regular topics and compliance_topics into one array.
+      // Shopify allows either `topics = [...]` or `compliance_topics = [...]`
+      // for GDPR webhooks — both should count toward the mandatory check.
+      topics: [...((sub.topics as string[]) ?? []), ...((sub.compliance_topics as string[]) ?? [])],
+      uri: sub.uri as string,
+    }),
+  )
+
+  // Check for IP allowlist in various possible locations
+  const ipAllowlistRaw =
+    (raw.ip_allowlist as Record<string, unknown>) ??
+    ((raw.access as Record<string, unknown>)?.ip_allowlist as Record<string, unknown>) ??
+    ((raw.security as Record<string, unknown>)?.ip_allowlist as Record<string, unknown>) ??
+    undefined
+
+  // Handle both formats: [ip_allowlist] with addresses=[...] or ip_allowlist = ["..."]
+  let ipAllowlist: string[] | undefined
+  if (Array.isArray(ipAllowlistRaw)) {
+    ipAllowlist = ipAllowlistRaw as string[]
+  } else if (ipAllowlistRaw && Array.isArray(ipAllowlistRaw.addresses)) {
+    ipAllowlist = ipAllowlistRaw.addresses as string[]
+  }
+
+  return {
+    raw,
+    path,
+    scopes,
+    redirect_urls: redirectUrls,
+    webhooks: webhookSubs,
+    ip_allowlist: ipAllowlist,
+  }
+}
+
+/**
+ * Directories never worth scanning: build output, dependencies, and test
+ * fixture trees.
+ *
+ * Patterns are generic on purpose. Earlier versions hardcoded the names of
+ * this project's own fixture directories, which both leaked internal naming
+ * into a tool that ships to third-party developers and silently skipped any
+ * directory a developer happened to give the same name.
+ *
+ * Sub-apps (a nested directory with its own shopify.app.toml) are excluded
+ * separately by callers, since that requires reading the tree rather than
+ * matching a name.
+ */
+export const IGNORED_DIRECTORIES = [
+  'node_modules/**',
+  '.git/**',
+  'dist/**',
+  'build/**',
+  '**/fixtures/**',
+  '**/*-fixtures/**',
+  '**/__fixtures__/**',
+]
+
+/**
+ * Find all theme app extensions and their files.
+ */
+export function findExtensions(appRoot: string): ExtensionInfo[] {
+  const extensionTomls = fg.sync('**/shopify.extension.toml', {
+    followSymbolicLinks: false,
+    cwd: appRoot,
+    ignore: IGNORED_DIRECTORIES,
+    absolute: false,
+  })
+
+  // Filter out extensions that belong to sub-apps (have a shopify.app.toml in an ancestor)
+  const subAppTomls = new Set(
+    fg
+      .sync('**/shopify.app*.toml', {
+        followSymbolicLinks: false,
+        cwd: appRoot,
+        ignore: ['node_modules/**', '.git/**', 'dist/**', 'build/**'],
+        absolute: false,
+      })
+      .filter((path) => path !== 'shopify.app.toml' && !path.match(/^shopify\.app\.[^.]+\.toml$/))
+      .map((path) => path.replace(/shopify\.app[^/]*\.toml$/, '')),
+  )
+
+  const filtered = extensionTomls.filter((tomlPath) => {
+    // Skip if this extension is inside a sub-app directory
+    for (const subAppDir of subAppTomls) {
+      if (subAppDir && tomlPath.startsWith(`${subAppDir}/`)) return false
+    }
+    return true
+  })
+
+  return filtered.map((tomlPath) => {
+    const fullPath = joinPath(appRoot, tomlPath)
+    const raw = parseToml(readFileSync(fullPath).toString()) as Record<string, unknown>
+    const type = raw.type as string
+
+    const extDir = joinPath(appRoot, tomlPath, '..')
+    const files = findSourceFiles(extDir, appRoot)
+
+    return {
+      path: tomlPath,
+      type,
+      files,
+    }
+  })
+}
+
+/**
+ * Maximum file size we will read into memory for analysis.
+ *
+ * Files above this are recorded as skipped rather than silently dropped — see
+ * `getSkippedFiles`. Minified bundles routinely exceed it and are exactly
+ * where committed secrets hide, so "we did not look" must be visible in the
+ * trace instead of being indistinguishable from "we looked and found nothing".
+ */
+export const MAX_FILE_SIZE_BYTES = 500_000
+
+/** A file that was discovered but not analyzed, and why. */
+export interface SkippedFile {
+  path: string
+  reason: 'too_large' | 'unreadable'
+  size_bytes?: number
+  detail?: string
+}
+
+/**
+ * Files skipped during the most recent discovery pass.
+ *
+ * Module-level because discovery runs in several places and the scanner needs
+ * to surface the total in scan metadata. Reset at the start of each scan via
+ * `resetSkippedFiles()`.
+ */
+let skippedFiles: SkippedFile[] = []
+
+export function resetSkippedFiles(): void {
+  skippedFiles = []
+}
+
+export function getSkippedFiles(): SkippedFile[] {
+  return [...skippedFiles]
+}
+
+/**
+ * Find all source files in a directory (JS, TS, JSX, TSX, Liquid, PHP, Ruby, Python).
+ */
+export function findSourceFiles(dir: string, projectRoot = dir): SourceFile[] {
+  const extensions = ['.js', '.ts', '.jsx', '.tsx', '.liquid', '.php', '.rb', '.py']
+  const patterns = extensions.map((ext) => `**/*${ext}`)
+
+  const files = fg.sync(patterns, {
+    cwd: dir,
+    ignore: [...IGNORED_DIRECTORIES, '*.test.*', '*.spec.*'],
+    absolute: false,
+    // Do not traverse symlinks. Third-party app code is untrusted input; a
+    // symlink to / or to a large shared directory would take the scan outside
+    // the app root and inflate the run.
+    followSymbolicLinks: false,
+  })
+
+  return files.map((file) => {
+    const absolutePath = joinPath(dir, file)
+    const projectPath = relativePath(projectRoot, absolutePath).replace(/\\/g, '/')
+    const ext = extname(file)
+    let content: string | undefined
+    try {
+      const size = fileSizeSync(absolutePath)
+      if (size < MAX_FILE_SIZE_BYTES) {
+        content = readFileSync(absolutePath).toString()
+      } else {
+        // Record rather than silently drop: an unscanned file isn't a clean file.
+        skippedFiles.push({
+          path: projectPath,
+          reason: 'too_large',
+          size_bytes: size,
+        })
+      }
+      // Discovery records unreadable files for trace coverage.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      skippedFiles.push({
+        path: projectPath,
+        reason: 'unreadable',
+        detail: error instanceof Error ? error.message : String(error),
+      })
+    }
+    return {
+      path: projectPath,
+      absolutePath,
+      ext,
+      content,
+    }
+  })
+}
+
+/**
+ * Find all source files in the app root (backend routes, etc.)
+ */
+export function findAppSourceFiles(appRoot: string): SourceFile[] {
+  return findSourceFiles(appRoot)
+}
+
+/**
+ * Find package manifests (package.json, Gemfile, composer.json)
+ */
+export function findManifestPaths(appRoot: string): string[] {
+  const paths = fg.sync('**/package.json', {
+    followSymbolicLinks: false,
+    cwd: appRoot,
+    ignore: IGNORED_DIRECTORIES,
+    absolute: false,
+  })
+  for (const rootManifest of ['Gemfile', 'composer.json']) {
+    if (fileExistsSync(joinPath(appRoot, rootManifest))) paths.push(rootManifest)
+  }
+  return [...new Set(paths)].sort()
+}
+
+export function findManifests(appRoot: string, discoveredPaths = findManifestPaths(appRoot)): ManifestFile[] {
+  const manifests: ManifestFile[] = []
+
+  const pkgPaths = discoveredPaths.filter((path) => path.endsWith('package.json'))
+
+  for (const pkgPath of pkgPaths) {
+    try {
+      const fullPath = joinPath(appRoot, pkgPath)
+      const pkg = JSON.parse(readFileSync(fullPath).toString())
+      manifests.push({
+        path: pkgPath,
+        absolutePath: fullPath,
+        type: 'npm',
+        dependencies: pkg.dependencies ?? {},
+        devDependencies: pkg.devDependencies ?? {},
+      })
+      // Invalid manifests are recorded as unreadable for trace coverage.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      skippedFiles.push({
+        path: pkgPath,
+        reason: 'unreadable',
+        detail: `manifest could not be parsed: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+
+  // Gemfile
+  const gemfilePath = joinPath(appRoot, 'Gemfile')
+  if (discoveredPaths.includes('Gemfile')) {
+    try {
+      const content = readFileSync(gemfilePath).toString()
+      const dependencies: Record<string, string> = {}
+      for (const line of content.split('\n')) {
+        const match = line.match(/gem\s+['"]([^'"]+)['"](?:\s*,\s*['"]([^'"]+)['"])?/)
+        const dependencyName = match?.[1]
+        if (dependencyName !== undefined) dependencies[dependencyName] = match?.[2] ?? 'latest'
+      }
+      manifests.push({
+        path: 'Gemfile',
+        absolutePath: gemfilePath,
+        type: 'ruby',
+        dependencies,
+      })
+      // Invalid manifests are recorded as unreadable for trace coverage.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      skippedFiles.push({
+        path: 'Gemfile',
+        reason: 'unreadable',
+        detail: error instanceof Error ? error.message : String(error),
+      })
+    }
+  }
+
+  // composer.json
+  const composerPath = joinPath(appRoot, 'composer.json')
+  if (discoveredPaths.includes('composer.json')) {
+    try {
+      const composer = JSON.parse(readFileSync(composerPath).toString())
+      manifests.push({
+        path: 'composer.json',
+        absolutePath: composerPath,
+        type: 'php',
+        dependencies: composer.require ?? {},
+        devDependencies: composer['require-dev'] ?? {},
+      })
+      // Invalid manifests are recorded as unreadable for trace coverage.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch (error) {
+      skippedFiles.push({
+        path: 'composer.json',
+        reason: 'unreadable',
+        detail: `manifest could not be parsed: ${error instanceof Error ? error.message : String(error)}`,
+      })
+    }
+  }
+
+  return manifests
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/scanners/index.ts b/packages/app/src/cli/services/app-doctor-engine/scanners/index.ts
new file mode 100644
index 00000000000..5e50a15c111
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/scanners/index.ts
@@ -0,0 +1,315 @@
+import {
+  findAppRoot,
+  findAppTomls,
+  loadAppToml,
+  findExtensions,
+  findAppSourceFiles,
+  resetSkippedFiles,
+  getSkippedFiles,
+  findManifests,
+  findManifestPaths,
+} from './discover.js'
+import {detectCapabilities} from '../capabilities/detect.js'
+import {calculateScore, computeScanMetadata} from '../scorer/index.js'
+
+// Rules
+import {deprecatedScriptTagScope, scopeOverRequest, insecureWebhookUrl} from '../rules/config-rules.js'
+import {scanUnsafeInnerHTML} from '../rules/js-rules.js'
+import {scanLiquidUnsafeRender, scanMissingSRI, scanExternalCdn} from '../rules/liquid-rules.js'
+import {redactText, scanCommittedSecrets} from '../rules/secret-rules.js'
+import {scanOutdatedShopifySdk, scanKnownCves} from '../rules/dependency-rules.js'
+import {scanDeprecatedScriptTagApi} from '../rules/shopify-rules.js'
+import {missingComplianceWebhooks, scanEolApiVersion} from '../rules/compliance-rules.js'
+import {scanWeakShopValidation} from '../rules/validation-rules.js'
+import {scanAppProxyLiquidInjection} from '../rules/proxy-rules.js'
+import {scanExpiringOfflineTokens} from '../rules/token-rules.js'
+import {scanTokenLeakage} from '../rules/additional-security-rules.js'
+import {redactIssue} from '../trace/index.js'
+import {getEngineVersion} from '../version.js'
+import {readFileSync} from '@shopify/cli-kit/node/fs'
+import {basename, joinPath, relativePath} from '@shopify/cli-kit/node/path'
+import {captureOutputWithExitCode} from '@shopify/cli-kit/node/system'
+import {createHash} from 'node:crypto'
+import type {Rule, ScanContext} from '../rules/types.js'
+import type {CheckExecution, ScanResult, Issue} from '../types.js'
+
+const ALL_RULES: Rule[] = [deprecatedScriptTagScope, scopeOverRequest, insecureWebhookUrl, missingComplianceWebhooks]
+
+const SCANNER_RULES = [
+  {
+    id: 'UNSAFE_INNERHTML',
+    requires: 'theme_app_extension' as const,
+    run: scanUnsafeInnerHTML,
+  },
+  {
+    id: 'LIQUID_UNSAFE_RENDER',
+    requires: 'theme_app_extension' as const,
+    run: scanLiquidUnsafeRender,
+  },
+  {
+    id: 'MISSING_SRI',
+    requires: 'theme_app_extension' as const,
+    run: scanMissingSRI,
+  },
+  {
+    id: 'EXTERNAL_CDN_DEPENDENCY',
+    requires: 'theme_app_extension' as const,
+    run: scanExternalCdn,
+  },
+  {id: 'DEPRECATED_SCRIPT_TAG_API', run: scanDeprecatedScriptTagApi},
+]
+
+const DEPENDENCY_RULES = [
+  {id: 'OUTDATED_SHOPIFY_SDK', run: scanOutdatedShopifySdk},
+  {id: 'KNOWN_CVE_IN_DEPENDENCY', run: scanKnownCves},
+]
+
+const SECRET_RULES = [{id: 'COMMITTED_SECRET', run: scanCommittedSecrets}]
+
+/** Authoritative deterministic rule registry. All versions are trace-contract versions. */
+export const DETERMINISTIC_RULES = [
+  ...ALL_RULES.map((rule) => ({
+    id: rule.id,
+    version: 1,
+    requires: rule.requires,
+  })),
+  ...SCANNER_RULES.map((rule) => ({
+    id: rule.id,
+    version: 1,
+    requires: rule.requires,
+  })),
+  ...DEPENDENCY_RULES.map((rule) => ({id: rule.id, version: 1})),
+  ...SECRET_RULES.map((rule) => ({id: rule.id, version: 1})),
+  {id: 'EXPIRING_OFFLINE_TOKEN', version: 1},
+  {id: 'EOL_API_VERSION', version: 1},
+  {id: 'TOKEN_LEAKAGE', version: 1},
+  {id: 'WEAK_SHOP_VALIDATION', version: 1},
+  {id: 'APP_PROXY_LIQUID_INJECTION', version: 1},
+] as const
+
+async function gitProject(appRoot: string): Promise<ScanResult['project']> {
+  const run = async (args: string[]): Promise<string | null> => {
+    const result = await captureOutputWithExitCode('git', args, {cwd: appRoot})
+    return result.exitCode === 0 ? result.stdout.trim() : null
+  }
+  const commit = await run(['rev-parse', 'HEAD'])
+  if (!commit) return {commit: null, dirty: null}
+  const status = await run(['status', '--porcelain', '--untracked-files=normal'])
+  return {commit, dirty: status === null ? null : status.length > 0}
+}
+
+export async function scan(startPath?: string): Promise<ScanResult> {
+  const appRoot = findAppRoot(startPath)
+
+  // Clear per-run skip state before discovery so the trace reports only the
+  // files this scan declined to read.
+  resetSkippedFiles()
+
+  // Discover files
+  const appTomls = findAppTomls(appRoot)
+  const extensions = findExtensions(appRoot)
+  const sourceFiles = findAppSourceFiles(appRoot)
+  const manifestPaths = findManifestPaths(appRoot)
+  const manifests = findManifests(appRoot, manifestPaths)
+
+  // Use the first app TOML (or merge if multiple)
+  const appToml = startPath?.endsWith('.toml') ? loadAppToml(startPath) : (appTomls[0] ?? null)
+
+  // Detect capabilities
+  const capabilities = detectCapabilities(appToml, extensions, sourceFiles)
+
+  // Build scan context
+  const ctx: ScanContext = {
+    appRoot,
+    appToml,
+    extensions,
+    sourceFiles,
+    manifests,
+    capabilities,
+  }
+
+  let issues: Issue[] = []
+  let rulesRun = 0
+  let rulesSkipped = 0
+  const checksExecuted: CheckExecution[] = []
+  const record = (id: string, status: 'executed' | 'skipped', before: number, reason?: string): void => {
+    checksExecuted.push({
+      id,
+      version: 1,
+      kind: 'rule',
+      status,
+      findings: status === 'executed' ? issues.length - before : 0,
+      ...(reason ? {reason} : {}),
+    })
+  }
+
+  // Run config-based rules
+  for (const rule of ALL_RULES) {
+    if (rule.requires && !capabilities[rule.requires]) {
+      rulesSkipped++
+      record(rule.id, 'skipped', issues.length, `requires capability ${rule.requires}`)
+      continue
+    }
+    rulesRun++
+    const before = issues.length
+    issues.push(...rule.check(ctx))
+    record(rule.id, 'executed', before)
+  }
+
+  // Run scanner-based rules
+  for (const scanner of SCANNER_RULES) {
+    if (scanner.requires && !capabilities[scanner.requires]) {
+      rulesSkipped++
+      record(scanner.id, 'skipped', issues.length, `requires capability ${scanner.requires}`)
+      continue
+    }
+    rulesRun++
+    const before = issues.length
+
+    // Collect files to scan for this rule
+    let filesToScan = sourceFiles
+    if (scanner.requires === 'theme_app_extension') {
+      filesToScan = extensions.flatMap((extension) => extension.files)
+    }
+
+    issues.push(...scanner.run(filesToScan))
+    record(scanner.id, 'executed', before)
+  }
+
+  // Deduplicate: if MISSING_SRI already flagged a script tag on the same
+  // file+line, drop the EXTERNAL_CDN_DEPENDENCY finding for that line.
+  // Both rules fire on the same external <script> tag — one problem, one
+  // deduction. MISSING_SRI is the more specific and more severe finding.
+  const sriLines = new Set(
+    issues.filter((i) => i.id === 'MISSING_SRI').map((i) => `${i.location.file}:${i.location.line ?? 0}`),
+  )
+  issues = issues.filter((i) => {
+    if (i.id !== 'EXTERNAL_CDN_DEPENDENCY') return true
+    const key = `${i.location.file}:${i.location.line ?? 0}`
+    return !sriLines.has(key)
+  })
+
+  // Run dependency rules
+  for (const depRule of DEPENDENCY_RULES) {
+    rulesRun++
+    const before = issues.length
+    issues.push(...depRule.run(manifests))
+    record(depRule.id, 'executed', before)
+  }
+
+  // Run secret rules
+  for (const secretRule of SECRET_RULES) {
+    rulesRun++
+    const before = issues.length
+    // Rules run in registry order so trace execution metadata stays deterministic.
+    // eslint-disable-next-line no-await-in-loop
+    issues.push(...(await secretRule.run(sourceFiles, appRoot)))
+    record(secretRule.id, 'executed', before)
+  }
+
+  const runStandalone = (id: string, run: () => Issue[]): void => {
+    rulesRun++
+    const before = issues.length
+    issues.push(...run())
+    record(id, 'executed', before)
+  }
+  runStandalone('EXPIRING_OFFLINE_TOKEN', () => scanExpiringOfflineTokens(sourceFiles, appRoot))
+  runStandalone('EOL_API_VERSION', () => scanEolApiVersion(sourceFiles, appRoot))
+  runStandalone('TOKEN_LEAKAGE', () => scanTokenLeakage(sourceFiles))
+  runStandalone('WEAK_SHOP_VALIDATION', () => scanWeakShopValidation(sourceFiles))
+  runStandalone('APP_PROXY_LIQUID_INJECTION', () => scanAppProxyLiquidInjection(sourceFiles))
+
+  // Safety net: some rules have mixed definite/needs_review paths (e.g.
+  // UNSAFE_INNERHTML returns "definite" for request-controlled data but
+  // "needs_review" for ambiguous cases). Only definite findings enter the
+  // trace. Semantic questions are handled by the agentic review track
+  // (app-doctor review), not by the static scanner.
+  issues = issues.filter((i) => i.confidence !== 'needs_review').map(redactIssue)
+  // Recompute counts after filtering and deduplication.
+  for (const execution of checksExecuted)
+    execution.findings = issues.filter((issue) => issue.id === execution.id).length
+
+  // Calculate score
+  const score = calculateScore(issues, capabilities)
+
+  // Compute file hashes for integrity
+  const fileHashes = sourceFiles.map((file): string | undefined => {
+    if (file.content !== undefined) {
+      return createHash('sha256').update(file.content).digest('hex')
+    }
+    try {
+      return createHash('sha256').update(readFileSync(file.absolutePath)).digest('hex')
+      // Discovery already records this file as unreadable. Never invent a hash.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch {
+      return undefined
+    }
+  })
+
+  // Per-file map keyed by project-relative path, so a resolution can record
+  // which bytes it was made against and be invalidated when they change.
+  const fileHashMap: Record<string, string> = {}
+  sourceFiles.forEach((file, index) => {
+    const hash = fileHashes[index]
+    if (hash) fileHashMap[redactText(file.path)] = `sha256:${hash}`
+  })
+
+  // Config files aren't in sourceFiles but many findings point at them
+  // (scopes, API version, webhook URLs). Without their hashes those findings
+  // can't be staleness-checked — which is exactly where it matters, since
+  // editing scopes after attesting is the easy way to invalidate a claim.
+  const configPaths = [
+    ...appTomls.map((t) => t.path),
+    ...extensions.map((extension) => joinPath(appRoot, extension.path)),
+    ...manifestPaths.map((manifest) => joinPath(appRoot, manifest)),
+  ]
+  for (const absolute of configPaths) {
+    if (!absolute) continue
+    const projectRelativePath = redactText(relativePath(appRoot, absolute) || basename(absolute))
+    if (fileHashMap[projectRelativePath]) continue
+    try {
+      fileHashMap[projectRelativePath] = `sha256:${createHash('sha256').update(readFileSync(absolute)).digest('hex')}`
+      // Unreadable config files are omitted rather than assigned a bogus hash.
+      // eslint-disable-next-line no-catch-all/no-catch-all
+    } catch {
+      // Nothing else to do.
+    }
+  }
+
+  const safeSkippedFiles = [
+    ...new Map(
+      getSkippedFiles().map((file) => {
+        const safe = {
+          ...file,
+          path: redactText(file.path),
+          ...(file.detail ? {detail: redactText(file.detail)} : {}),
+        }
+        return [`${safe.path}|${safe.reason}`, safe] as const
+      }),
+    ).values(),
+  ]
+  const scanMeta = computeScanMetadata(
+    sourceFiles.filter((file) => file.content !== undefined).length,
+    rulesRun,
+    rulesSkipped,
+    issues,
+    score,
+    fileHashMap,
+    safeSkippedFiles,
+    checksExecuted,
+  )
+
+  return {
+    version: getEngineVersion(),
+    timestamp: new Date().toISOString(),
+    project: await gitProject(appRoot),
+    app: {
+      name: redactText(String(appToml?.raw.name ?? 'Unknown')),
+      type: 'public',
+    },
+    capabilities,
+    score,
+    scan: scanMeta,
+    issues,
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/scorer/index.ts b/packages/app/src/cli/services/app-doctor-engine/scorer/index.ts
new file mode 100644
index 00000000000..e48924cbe45
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/scorer/index.ts
@@ -0,0 +1,117 @@
+import {canonicalJson, sha256} from '../trace/index.js'
+import {getEngineVersion} from '../version.js'
+import type {CheckExecution, Issue, ScoreResult, Grade, ScanMetadata, Capabilities, SkippedFile} from '../types.js'
+
+const BASELINE = 70
+
+interface BonusRule {
+  id: string
+  points: number
+  test: (capabilities: Capabilities, issues: Issue[]) => boolean
+}
+
+// Bonus points for good security practices.
+// These let a well-configured app score above 85.
+const BONUS_RULES: BonusRule[] = [
+  {
+    id: 'BONUS_NO_SCRIPT_TAGS',
+    points: 5,
+    test: (caps) => !caps.script_tags,
+  },
+  {
+    id: 'BONUS_CURRENT_SDK',
+    points: 5,
+    test: (_caps, issues) => !issues.some((i) => i.id === 'OUTDATED_SHOPIFY_SDK'),
+  },
+  {
+    id: 'BONUS_NO_SECRETS',
+    points: 10,
+    test: (_caps, issues) => !issues.some((i) => i.id === 'COMMITTED_SECRET'),
+  },
+]
+
+export function calculateScore(issues: Issue[], capabilities: Capabilities): ScoreResult {
+  let total = BASELINE
+
+  // Apply deductions — only for definite findings.
+  // needs_review and agentic findings are advisory and do NOT affect the score.
+  for (const issue of issues) {
+    if (issue.confidence !== 'definite' && issue.confidence !== undefined) continue
+    total += issue.points
+  }
+
+  // Apply bonuses — only check definite findings for bonus eligibility.
+  // An advisory finding shouldn't withhold a bonus.
+  for (const bonus of BONUS_RULES) {
+    const definiteIssues = issues.filter((i) => i.confidence === 'definite' || i.confidence === undefined)
+    if (bonus.test(capabilities, definiteIssues)) {
+      total += bonus.points
+    }
+  }
+
+  total = Math.max(0, Math.min(100, total))
+
+  return {
+    total,
+    baseline: BASELINE,
+    grade: scoreToGrade(total),
+  }
+}
+
+function scoreToGrade(score: number): Grade {
+  if (score >= 90) return 'EXCELLENT'
+  if (score >= 75) return 'GOOD'
+  if (score >= 60) return 'NEEDS_WORK'
+  return 'CRITICAL'
+}
+
+export function computeResultHash(issues: Issue[], score: ScoreResult): string {
+  const canonicalIssues = issues
+    .map((issue) => ({
+      id: issue.id,
+      source: issue.found_by ?? 'static',
+      rule_version: issue.rule_version ?? (issue.found_by === 'agent' ? null : 1),
+      check_version: issue.check_version ?? null,
+      prompt_hash: issue.prompt_hash ?? null,
+      severity: issue.severity,
+      points: issue.points,
+      title: issue.title,
+      message: issue.message,
+      location: issue.location,
+      snippet: issue.snippet ?? null,
+      evidence: issue.evidence ?? [],
+      fix: issue.fix,
+    }))
+    .sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right)))
+  return sha256({issues: canonicalIssues, score})
+}
+
+export function computeScanMetadata(
+  filesScanned: number,
+  rulesRun: number,
+  rulesSkipped: number,
+  issues: Issue[],
+  score: ScoreResult,
+  fileHashMap?: Record<string, string>,
+  filesSkipped?: SkippedFile[],
+  checksExecuted?: CheckExecution[],
+): ScanMetadata {
+  const inputs = {
+    files: Object.entries(fileHashMap ?? {}).sort(([left], [right]) => left.localeCompare(right)),
+    skipped: [...(filesSkipped ?? [])].sort((left, right) => left.path.localeCompare(right.path)),
+  }
+  return {
+    timestamp: new Date().toISOString(),
+    doctor_version: getEngineVersion(),
+    files_scanned: filesScanned,
+    rules_run: rulesRun,
+    rules_skipped: rulesSkipped,
+    // Surfaced so a reviewer can tell "clean" apart from "never looked".
+    files_skipped_count: filesSkipped?.length ?? 0,
+    files_skipped: filesSkipped && filesSkipped.length > 0 ? filesSkipped : undefined,
+    input_hash: sha256(inputs),
+    result_hash: computeResultHash(issues, score),
+    file_hashes: fileHashMap,
+    checks_executed: checksExecuted,
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/checks.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/checks.test.ts
new file mode 100644
index 00000000000..238f5003418
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/checks.test.ts
@@ -0,0 +1,298 @@
+/* eslint-disable id-length -- concise fixture names keep provenance-focused assertions readable */
+import {
+  loadChecks,
+  buildReviewPack,
+  validateFinding,
+  findingToIssue,
+  mergeFindings,
+  validateAgentChecksExecuted,
+  type AgentFinding,
+} from '../checks/index.js'
+import {EMBEDDED_CHECK_SOURCES} from '../checks/embedded.js'
+import {describe, expect, test} from 'vitest'
+import {readFileSync, readdirSync} from 'node:fs'
+
+const EXPECTED_CHECK_IDS = [
+  'APP_PROXY_UNVERIFIED_SIGNATURE',
+  'CSRF_MISSING_PROTECTION',
+  'MISSING_AUTHORIZATION_CHECK',
+  'MISSING_EMBEDDED_CSP',
+  'MISSING_TENANT_ISOLATION',
+  'OPEN_REDIRECT',
+  'OVERBROAD_DATA_ACCESS',
+  'REQUEST_DERIVED_SHOP_SCOPE',
+  'SCOPE_OVER_REQUEST',
+  'SCRIPT_TAG_URL_INJECTION',
+  'SSRF_REQUEST_FORGERY',
+  'TEXT_SETTING_HTML_SMUGGLING',
+  'THEME_EXTENSION_XSS',
+  'UNAUTHENTICATED_ENDPOINT',
+  'UNSAFE_INNERHTML',
+  'UNSCOPED_SHOP_CONFIG_WRITE',
+]
+
+const validFinding: AgentFinding = {
+  check_id: 'MISSING_TENANT_ISOLATION',
+  check_version: 1,
+  prompt_hash: 'sha256:test-provenance',
+  file: 'app/controllers/orders_controller.rb',
+  line: 42,
+  message: 'Query not scoped to current shop',
+  snippet: 'Product.where(id: params[:id])',
+  evidence: [
+    {
+      file: 'app/controllers/orders_controller.rb',
+      line: 42,
+      quote: 'Product.where(id: params[:id])',
+    },
+  ],
+  confidence: 'high',
+  reasoning: 'No before_action scopes by shop_id',
+}
+
+describe('check loading', () => {
+  test('keeps the generated prompt sources in exact parity with markdown', () => {
+    const checksDir = new URL('../checks/', import.meta.url)
+    const markdownSources = readdirSync(checksDir)
+      .filter((file) => file.endsWith('.md'))
+      .sort()
+      .map((file) => readFileSync(new URL(file, checksDir), 'utf8'))
+
+    expect(EMBEDDED_CHECK_SOURCES).toEqual(markdownSources)
+  })
+
+  test('loads all versioned checks with frontmatter parsed', () => {
+    const checks = loadChecks()
+    expect([...checks.keys()]).toEqual(EXPECTED_CHECK_IDS)
+    expect(checks.size).toBe(16)
+    const tenant = checks.get('MISSING_TENANT_ISOLATION')
+    expect(tenant).toBeDefined()
+    expect(tenant!.version).toBeGreaterThanOrEqual(1)
+    expect(tenant!.severity).toBe('high')
+    expect(tenant!.prompt.length).toBeGreaterThan(200)
+    expect(tenant!.tier).toBe('agentic')
+  })
+
+  test('does not carry candidate_source — the agent explores independently', () => {
+    const checks = loadChecks()
+    const tenant = checks.get('MISSING_TENANT_ISOLATION')!
+    expect((tenant as unknown as Record<string, unknown>).candidate_source).toBeUndefined()
+  })
+
+  test('hashes the prompt so a finding is traceable to exact wording', () => {
+    const a = loadChecks().get('MISSING_TENANT_ISOLATION')!
+    const b = loadChecks().get('MISSING_TENANT_ISOLATION')!
+    expect(a.prompt_hash).toMatch(/^sha256:[0-9a-f]{64}$/)
+    expect(a.prompt_hash).toBe(b.prompt_hash)
+  })
+})
+
+describe('review pack', () => {
+  test('contains prompts, not candidates', () => {
+    const pack = buildReviewPack('0.1.0')
+    expect(pack.checks.map((check) => check.id)).toEqual(EXPECTED_CHECK_IDS)
+    expect(pack.checks).toHaveLength(16)
+    expect((pack as unknown as Record<string, unknown>).candidates).toBeUndefined()
+    const tenant = pack.checks.find((c) => c.id === 'MISSING_TENANT_ISOLATION')
+    expect(tenant).toBeDefined()
+    expect(tenant!.prompt.length).toBeGreaterThan(200)
+  })
+
+  test('instructions tell the agent to explore and find, not adjudicate', () => {
+    const pack = buildReviewPack('0.1.0')
+    expect(pack.instructions).toMatch(/explore|find/i)
+    expect(pack.instructions).toMatch(/findings/i)
+  })
+})
+
+describe('finding validation', () => {
+  test('rejects a finding with no evidence', () => {
+    const f = {...validFinding, evidence: []}
+    expect(validateFinding(f)).toMatch(/evidence/)
+  })
+
+  test('rejects a finding missing required fields', () => {
+    expect(validateFinding({...validFinding, file: ''})).toMatch(/file/)
+    expect(validateFinding({...validFinding, line: undefined as never})).toMatch(/line/)
+    expect(validateFinding({...validFinding, message: ''})).toMatch(/message/)
+  })
+
+  test('accepts a well-formed finding with evidence', () => {
+    expect(validateFinding(validFinding)).toBeUndefined()
+  })
+})
+
+describe('finding to issue', () => {
+  test('marks the issue as agentic with agent provenance', () => {
+    const checks = loadChecks()
+    const check = checks.get('MISSING_TENANT_ISOLATION')!
+    const issue = findingToIssue(
+      {
+        ...validFinding,
+        check_version: check.version,
+        prompt_hash: check.prompt_hash,
+      },
+      check,
+    )
+    expect(issue.confidence).toBe('agentic')
+    expect(issue.found_by).toBe('agent')
+    expect(issue.check_version).toBe(check.version)
+    expect(issue.prompt_hash).toBe(check.prompt_hash)
+    expect(issue.agent_confidence).toBe('high')
+    expect(issue.agent_reasoning).toBe(validFinding.reasoning)
+    expect(issue.fix.automated).toBe(false)
+    expect(issue.evidence).toEqual([
+      {
+        location: {file: 'app/controllers/orders_controller.rb', line: 42},
+        quote: 'Product.where(id: params[:id])',
+      },
+    ])
+  })
+})
+
+describe('merge findings', () => {
+  test('accepts findings that match a known check version', () => {
+    const checks = loadChecks()
+    const check = checks.get('MISSING_TENANT_ISOLATION')!
+    const f = {
+      ...validFinding,
+      check_version: check.version,
+      prompt_hash: check.prompt_hash,
+    }
+    const {accepted, rejected} = mergeFindings([], [f])
+    expect(accepted).toBe(1)
+    expect(rejected).toHaveLength(0)
+  })
+
+  test('rejects findings for an unknown check', () => {
+    const f = {...validFinding, check_id: 'NONEXISTENT'}
+    const {accepted, rejected} = mergeFindings([], [f])
+    expect(accepted).toBe(0)
+    expect(rejected[0]).toMatch(/unknown check/)
+  })
+
+  test('rejects a missing or mismatched prompt hash', () => {
+    const check = loadChecks().get('MISSING_TENANT_ISOLATION')!
+    expect(mergeFindings([], [{...validFinding, prompt_hash: ''}]).rejected[0]).toMatch(/prompt_hash/)
+    expect(
+      mergeFindings(
+        [],
+        [
+          {
+            ...validFinding,
+            check_version: check.version,
+            prompt_hash: 'sha256:wrong',
+          },
+        ],
+      ).rejected[0],
+    ).toMatch(/prompt_hash mismatch/)
+  })
+
+  test('rejects unsafe evidence paths and lines', () => {
+    expect(
+      validateFinding({
+        ...validFinding,
+        evidence: [{file: '../secret', line: 1}],
+      }),
+    ).toMatch(/unsafe evidence/)
+    expect(
+      validateFinding({
+        ...validFinding,
+        evidence: [{file: '/etc/passwd', line: 1}],
+      }),
+    ).toMatch(/unsafe evidence/)
+    expect(
+      validateFinding({
+        ...validFinding,
+        evidence: [{file: 'app/a.ts', line: 0}],
+      }),
+    ).toMatch(/evidence line/)
+  })
+
+  test('rejects findings with a version mismatch', () => {
+    const checks = loadChecks()
+    const check = checks.get('MISSING_TENANT_ISOLATION')!
+    const f = {
+      ...validFinding,
+      check_version: check.version + 999,
+      prompt_hash: check.prompt_hash,
+    }
+    const {accepted, rejected} = mergeFindings([], [f])
+    expect(accepted).toBe(0)
+    expect(rejected[0]).toMatch(/version mismatch/)
+  })
+
+  test('rejects findings outside the scanned input set', () => {
+    const check = loadChecks().get('MISSING_TENANT_ISOLATION')!
+    const finding = {
+      ...validFinding,
+      check_version: check.version,
+      prompt_hash: check.prompt_hash,
+    }
+    expect(mergeFindings([], [finding], {knownFiles: new Set(['other.ts'])}).rejected[0]).toMatch(
+      /not part of the scanned inputs/,
+    )
+    expect(
+      mergeFindings([], [{...finding, evidence: [{file: 'other.ts', line: 1}]}], {knownFiles: new Set([finding.file])})
+        .rejected[0],
+    ).toMatch(/evidence file/)
+  })
+
+  test('rejects submissions above the finding cap', () => {
+    expect(
+      mergeFindings(
+        [],
+        Array.from({length: 1_001}, () => validFinding),
+      ).rejected[0],
+    ).toMatch(/exceeding the limit/)
+  })
+
+  test('rejects findings with no evidence', () => {
+    const checks = loadChecks()
+    const check = checks.get('MISSING_TENANT_ISOLATION')!
+    const f = {
+      ...validFinding,
+      check_version: check.version,
+      prompt_hash: check.prompt_hash,
+      evidence: [],
+    }
+    const {accepted, rejected} = mergeFindings([], [f])
+    expect(accepted).toBe(0)
+    expect(rejected[0]).toMatch(/evidence/)
+  })
+})
+
+describe('executed check validation', () => {
+  test('records zero-finding checks and rejects duplicate or forged provenance', () => {
+    const check = loadChecks().get('MISSING_TENANT_ISOLATION')!
+    const valid = {
+      check_id: check.id,
+      check_version: check.version,
+      prompt_hash: check.prompt_hash,
+    }
+    const other = loadChecks().get('OPEN_REDIRECT')!
+    const result = validateAgentChecksExecuted({
+      findings: [],
+      checks_executed: [
+        valid,
+        valid,
+        {...valid, check_id: 'UNKNOWN'},
+        {
+          check_id: other.id,
+          check_version: other.version + 1,
+          prompt_hash: other.prompt_hash,
+        },
+      ],
+    })
+    expect(result.executions).toEqual([
+      expect.objectContaining({
+        id: check.id,
+        status: 'executed',
+        findings: 0,
+      }),
+    ])
+    expect(result.rejected.join(' ')).toMatch(/duplicate/)
+    expect(result.rejected.join(' ')).toMatch(/unknown/)
+    expect(result.rejected.join(' ')).toMatch(/provenance/)
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/interaction.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/interaction.test.ts
new file mode 100644
index 00000000000..dffb93c4493
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/interaction.test.ts
@@ -0,0 +1,83 @@
+import {formatConsole} from '../output/format.js'
+import {getRegistry} from '../registry/index.js'
+import {describe, expect, test} from 'vitest'
+import type {ScanResult} from '../types.js'
+
+const result: ScanResult = {
+  version: '0.1.0',
+  timestamp: '2026-08-24T00:00:00.000Z',
+  project: {commit: null, dirty: null},
+  app: {name: 'Example App', type: 'public'},
+  capabilities: {
+    theme_app_extension: false,
+    app_embed: false,
+    script_tags: false,
+    webhooks: false,
+    app_proxy: false,
+    storefront_metafield_writes: false,
+    has_backend: true,
+    declared_ip_allowlist: false,
+    checkout_extension: false,
+  },
+  score: {total: 40, baseline: 70, grade: 'CRITICAL'},
+  scan: {
+    timestamp: '2026-08-24T00:00:00.000Z',
+    doctor_version: '0.1.0',
+    files_scanned: 12,
+    rules_run: 18,
+    rules_skipped: 0,
+    files_skipped_count: 0,
+    input_hash: 'sha256:input',
+    result_hash: 'sha256:result',
+  },
+  issues: [
+    {
+      id: 'REQUEST_CONTROLLED_ADMIN_CONTEXT',
+      severity: 'critical',
+      points: -30,
+      title: 'Request input selects Admin API shop context',
+      message: 'A request-controlled shop value is passed to unauthenticated.admin(...).',
+      location: {file: 'app/routes/action.ts', line: 42},
+      fix: {
+        automated: false,
+        description: 'Use authenticate.admin(request).',
+      },
+    },
+    {
+      id: 'MISSING_IP_ALLOWLIST',
+      severity: 'high',
+      points: -10,
+      title: 'No IP address spaces declared in app config',
+      message: 'No IP ranges declared.',
+      location: {file: 'shopify.app.toml'},
+      fix: {automated: false, description: 'Declare IP ranges.'},
+    },
+  ],
+}
+
+describe('React Doctor-style interaction surface', () => {
+  test('renders a concise grouped report by default', () => {
+    const output = formatConsole(result, {elapsedMilliseconds: 125})
+
+    expect(output).toContain('✔ Scanned 12 files in 125ms')
+    expect(output).toContain('Shopify App Doctor — Example App')
+    expect(output).toContain('2 issues')
+    expect(output).toContain('Critical: 1, High: 1')
+    expect(output).toContain('REQUEST_CONTROLLED_ADMIN_CONTEXT')
+    expect(output).not.toContain('Fix: Use authenticate.admin(request).')
+  })
+
+  test('adds evidence and fix guidance in verbose mode', () => {
+    const output = formatConsole(result, {verbose: true})
+
+    expect(output).toContain('Fix: Use authenticate.admin(request).')
+    expect(output).toContain('Capabilities: backend')
+    expect(output).toContain('Rules run: 18 | Skipped: 0')
+  })
+
+  test('exposes the authoritative registry for list and explain commands', () => {
+    const registry = getRegistry()
+    expect(registry).toHaveLength(33)
+    expect(registry.find((entry) => entry.id === 'TOKEN_LEAKAGE')?.title).toBe('Token or secret may be logged')
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/metamorphic.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/metamorphic.test.ts
new file mode 100644
index 00000000000..e56869c3063
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/metamorphic.test.ts
@@ -0,0 +1,373 @@
+/* eslint-disable id-length, no-restricted-imports -- low-level scanner fixtures use Node paths and paired short aliases */
+import {scan} from '../index.js'
+import {scanRequestDerivedShopScope} from '../rules/request-scope-rules.js'
+import {scanMissingTenantIsolation} from '../rules/tenant-rules.js'
+import {scopeOverRequest} from '../rules/config-rules.js'
+import {findAppTomls, findExtensions, findManifests, findAppSourceFiles} from '../scanners/discover.js'
+import {detectCapabilities} from '../capabilities/detect.js'
+import {describe, expect, afterAll, test} from 'vitest'
+import {join, dirname} from 'node:path'
+import {tmpdir} from 'node:os'
+import {mkdtempSync, writeFileSync, rmSync, mkdirSync} from 'node:fs'
+import type {ScanContext} from '../rules/types.js'
+import type {Issue} from '../types.js'
+
+/**
+ * Metamorphic testing for scanner rules.
+ *
+ * Ground-truth fixtures only catch rules that miss a known vulnerability or
+ * fire on a known-clean app. They cannot catch a rule that gets the right
+ * answer for the wrong reason — which is how both false positives found so
+ * far got through:
+ *
+ *   mcp-app  inferred "scope unused" from an empty evidence corpus
+ *   Flow     inferred "value is request-tainted" from a name match across
+ *            two different method scopes
+ *
+ * Metamorphic relations test the *reasoning* instead of the answer. Each
+ * relation transforms an input in a way whose effect on the output is known
+ * a priori, then asserts it. A violation means the rule depends on something
+ * it shouldn't — no ground truth required, so these generalise to rules that
+ * don't exist yet.
+ */
+
+const tempDirs: string[] = []
+afterAll(() => {
+  for (const dir of tempDirs) rmSync(dir, {recursive: true, force: true})
+})
+
+const APP_TOML = `
+name = "mr-app"
+client_id = "abc123"
+application_url = "https://example.com"
+
+[access_scopes]
+scopes = "read_orders"
+
+[webhooks]
+api_version = "2025-01"
+`
+
+const makeApp = (files: Record<string, string>): string => {
+  const dir = mkdtempSync(join(tmpdir(), 'app-doctor-mr-'))
+  tempDirs.push(dir)
+  writeFileSync(join(dir, 'shopify.app.toml'), APP_TOML)
+  for (const [name, content] of Object.entries(files)) {
+    const full = join(dir, name)
+    mkdirSync(dirname(full), {recursive: true})
+    writeFileSync(full, content)
+  }
+  return dir
+}
+
+/** Findings reduced to rule + location, so line shifts are visible but noise isn't. */
+const fingerprint = (issues: Issue[]): string[] => issues.map((i) => `${i.id}@${i.location.file}`).sort()
+
+/** Findings reduced to rule id counts, ignoring position entirely. */
+const countByRule = (issues: Issue[]): Record<string, number> => {
+  const counts: Record<string, number> = {}
+  for (const i of issues) counts[i.id] = (counts[i.id] ?? 0) + 1
+  return counts
+}
+
+const scanFiles = async (files: Record<string, string>) => {
+  const dir = makeApp(files)
+  const staticResult = await scan(dir)
+  // Also run semantic rules directly — scan() filters them out of the trace,
+  // but metamorphic relations test the rules themselves, not the trace.
+  const sourceFiles = findAppSourceFiles(dir)
+  const semantic = [...scanRequestDerivedShopScope(sourceFiles), ...scanMissingTenantIsolation(sourceFiles)]
+  return [...staticResult.issues, ...semantic]
+}
+
+/** Run scopeOverRequest directly on a directory (scan() filters it out now). */
+const scopeOverRequestIssues = (dir: string) => {
+  const appTomls = findAppTomls(dir)
+  const extensions = findExtensions(dir)
+  const sourceFiles = findAppSourceFiles(dir)
+  const manifests = findManifests(dir)
+  const appToml = appTomls[0] ?? null
+  const capabilities = detectCapabilities(appToml, extensions, sourceFiles)
+  const ctx: ScanContext = {
+    appRoot: dir,
+    appToml,
+    extensions,
+    sourceFiles,
+    manifests,
+    capabilities,
+  }
+  return scopeOverRequest.check(ctx)
+}
+
+// ---------------------------------------------------------------------------
+// The Rails controller that exposed the scope bug, used as the primary probe.
+// ---------------------------------------------------------------------------
+
+const controller = (paramName: string) => `
+class TokensController < ApplicationController
+  def update_cookie
+    shop_id = params[:shop_id]
+    cookies.signed[:shop_id] = shop_id
+  end
+
+  def save_access_token(${paramName}, access_token)
+    row = Token.find_or_initialize_by(shop_id: ${paramName}, app: app_type)
+    row.save!
+  end
+end
+`
+
+describe('metamorphic: α-renaming invariance', () => {
+  /**
+   * Consistently renaming a variable cannot change whether code is
+   * vulnerable. If findings differ, the rule matched a name rather than a
+   * data flow.
+   *
+   * This is the relation that catches the Flow bug: with a file-global
+   * binding map, `save_access_token(shop_id, ...)` was flagged only because
+   * an unrelated method assigned a variable of the same name. Rename the
+   * parameter and the finding vanishes — proving the match was a name
+   * coincidence.
+   */
+  test('renaming a method parameter does not change findings', async () => {
+    const original = await scanFiles({
+      'app/controllers/tokens_controller.rb': controller('shop_id'),
+    })
+    const renamed = await scanFiles({
+      'app/controllers/tokens_controller.rb': controller('sid'),
+    })
+
+    expect(countByRule(renamed)).toEqual(countByRule(original))
+  })
+
+  test('renaming a genuinely tainted local does not change findings', async () => {
+    const base = (name: string) => `
+class TokensController < ApplicationController
+  def destroy
+    ${name} = params[:shop_id]
+    Token.where(shop_id: ${name}).delete_all
+  end
+end
+`
+    const a = await scanFiles({
+      'app/controllers/t_controller.rb': base('shop_id'),
+    })
+    const b = await scanFiles({
+      'app/controllers/t_controller.rb': base('target'),
+    })
+
+    expect(countByRule(b)).toEqual(countByRule(a))
+    // And the finding must actually be present — the relation is only
+    // meaningful if the rule fires at all.
+    expect(countByRule(a).REQUEST_DERIVED_SHOP_SCOPE).toBe(1)
+  })
+})
+
+describe('metamorphic: locality', () => {
+  /**
+   * Adding unrelated code must not change findings elsewhere. A rule that
+   * leaks state across scopes or across files violates this.
+   */
+  test('an unrelated method does not create findings in another method', async () => {
+    const withoutNeighbour = `
+class TokensController < ApplicationController
+  def save_access_token(shop_id, access_token)
+    row = Token.find_or_initialize_by(shop_id: shop_id, app: app_type)
+    row.save!
+  end
+end
+`
+    const withNeighbour = `
+class TokensController < ApplicationController
+  def unrelated
+    shop_id = params[:shop_id]
+    Rails.logger.info(shop_id)
+  end
+
+  def save_access_token(shop_id, access_token)
+    row = Token.find_or_initialize_by(shop_id: shop_id, app: app_type)
+    row.save!
+  end
+end
+`
+    const before = await scanFiles({
+      'app/controllers/a_controller.rb': withoutNeighbour,
+    })
+    const after = await scanFiles({
+      'app/controllers/a_controller.rb': withNeighbour,
+    })
+
+    expect(countByRule(after)).toEqual(countByRule(before))
+  })
+
+  test('a second unrelated file does not change findings in the first', async () => {
+    const target = `
+class TokensController < ApplicationController
+  def destroy
+    Token.where(shop_id: params[:shop_id]).delete_all
+  end
+end
+`
+    const alone = await scanFiles({
+      'app/controllers/a_controller.rb': target,
+    })
+    const withOther = await scanFiles({
+      'app/controllers/a_controller.rb': target,
+      'app/controllers/b_controller.rb': `
+class OtherController < ApplicationController
+  def index
+    render json: {}
+  end
+end
+`,
+    })
+
+    // Compare only findings located in the shared file. Config-level rules
+    // report against shopify.app.toml and legitimately see a wider corpus.
+    const inTarget = (issues: Issue[]) => issues.filter((i) => i.location.file.includes('a_controller'))
+    expect(countByRule(inTarget(withOther))).toEqual(countByRule(inTarget(alone)))
+  })
+})
+
+describe('metamorphic: position invariance', () => {
+  /** Shifting code down the file changes line numbers, never verdicts. */
+  test('leading padding does not change which rules fire', async () => {
+    const body = `
+class TokensController < ApplicationController
+  def destroy
+    Token.where(shop_id: params[:shop_id]).delete_all
+  end
+end
+`
+    const plain = await scanFiles({'app/controllers/a_controller.rb': body})
+    const padded = await scanFiles({
+      'app/controllers/a_controller.rb': `# frozen_string_literal: true\n#\n#\n#\n${body}`,
+    })
+
+    expect(countByRule(padded)).toEqual(countByRule(plain))
+    expect(fingerprint(padded)).toEqual(fingerprint(plain))
+  })
+})
+
+describe('metamorphic: comment neutrality', () => {
+  /**
+   * Commented-out code is not executable, so it cannot be vulnerable.
+   * A rule that fires on comments is pattern-matching text, not code.
+   */
+  test('commenting out the vulnerable line removes the finding', async () => {
+    const live = `
+class TokensController < ApplicationController
+  def destroy
+    Token.where(shop_id: params[:shop_id]).delete_all
+  end
+end
+`
+    const commented = `
+class TokensController < ApplicationController
+  def destroy
+    # Token.where(shop_id: params[:shop_id]).delete_all
+  end
+end
+`
+    const a = countByRule(await scanFiles({'app/controllers/a_controller.rb': live}))
+    const b = countByRule(await scanFiles({'app/controllers/a_controller.rb': commented}))
+
+    expect(a.REQUEST_DERIVED_SHOP_SCOPE).toBe(1)
+    expect(b.REQUEST_DERIVED_SHOP_SCOPE ?? 0).toBe(0)
+  })
+})
+
+describe('metamorphic: negative-inference safety', () => {
+  /**
+   * Rules that conclude something from ABSENCE must have an evidence corpus
+   * to be absent from. With zero source files, "X is never referenced" is
+   * vacuously true for every X — which is exactly how mcp-app produced 29
+   * false positives.
+   *
+   * Generalised: scanning a config-only app must not produce findings that
+   * depend on searching code.
+   */
+  test('a config-only app produces no absence-derived findings', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'app-doctor-mr-'))
+    tempDirs.push(dir)
+    writeFileSync(
+      join(dir, 'shopify.app.toml'),
+      `
+name = "config-only"
+client_id = "abc123"
+application_url = "https://example.com"
+
+[access_scopes]
+scopes = "read_orders,read_customers,read_analytics,read_reports"
+
+[webhooks]
+api_version = "2025-01"
+`,
+    )
+    const result = await scan(dir)
+
+    expect(result.scan.files_scanned).toBe(0)
+
+    // Any rule whose verdict is "not found in the code" must abstain here.
+    const absenceDerived = ['SCOPE_OVER_REQUEST', 'MISSING_COMPLIANCE_WEBHOOKS']
+    for (const ruleId of absenceDerived) {
+      const fired = result.issues.filter((i) => i.id === ruleId)
+      expect(fired, `${ruleId} fired with zero files scanned — it inferred absence from an empty corpus`).toHaveLength(
+        0,
+      )
+    }
+  })
+
+  test('adding code that uses a scope removes the over-request finding', async () => {
+    const toml = `
+name = "mr-app"
+client_id = "abc123"
+application_url = "https://example.com"
+
+[access_scopes]
+scopes = "read_orders,read_analytics"
+
+[webhooks]
+api_version = "2025-01"
+`
+    const dirA = mkdtempSync(join(tmpdir(), 'app-doctor-mr-'))
+    tempDirs.push(dirA)
+    writeFileSync(join(dirA, 'shopify.app.toml'), toml)
+    writeFileSync(join(dirA, 'server.js'), 'const a = 1;')
+    const before = countByRule(scopeOverRequestIssues(dirA))
+
+    const dirB = mkdtempSync(join(tmpdir(), 'app-doctor-mr-'))
+    tempDirs.push(dirB)
+    writeFileSync(join(dirB, 'shopify.app.toml'), toml)
+    writeFileSync(join(dirB, 'server.js'), 'const a = 1; // uses read_analytics reporting')
+    const after = countByRule(scopeOverRequestIssues(dirB))
+
+    // Referencing the scope must reduce, never increase, the finding count.
+    expect(after.SCOPE_OVER_REQUEST ?? 0).toBeLessThan(before.SCOPE_OVER_REQUEST ?? 0)
+  })
+})
+
+describe('metamorphic: duplication linearity', () => {
+  /**
+   * Two copies of the same vulnerable file contain two instances of the
+   * vulnerability — not one (deduped away) and not three (double-counted).
+   */
+  test('duplicating a vulnerable file doubles the findings', async () => {
+    const body = `
+class TokensController < ApplicationController
+  def destroy
+    Token.where(shop_id: params[:shop_id]).delete_all
+  end
+end
+`
+    const single = countByRule(await scanFiles({'app/controllers/a_controller.rb': body}))
+    const doubled = countByRule(
+      await scanFiles({
+        'app/controllers/a_controller.rb': body,
+        'app/controllers/b_controller.rb': body.replace('TokensController', 'TokensTwoController'),
+      }),
+    )
+
+    expect(doubled.REQUEST_DERIVED_SHOP_SCOPE).toBe((single.REQUEST_DERIVED_SHOP_SCOPE ?? 0) * 2)
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/registry.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/registry.test.ts
new file mode 100644
index 00000000000..a2032857c2d
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/registry.test.ts
@@ -0,0 +1,27 @@
+import {DETERMINISTIC_RULES, getRegistry, loadChecks} from '../index.js'
+import {RULE_CATALOG} from '../rules/catalog.js'
+import {describe, expect, test} from 'vitest'
+
+describe('authoritative registry', () => {
+  test('contains every executable deterministic rule and shipped agent check exactly once', () => {
+    const registry = getRegistry()
+    expect(
+      registry
+        .filter((entry) => entry.kind === 'deterministic')
+        .map((entry) => entry.id)
+        .sort(),
+    ).toEqual(DETERMINISTIC_RULES.map((entry) => entry.id).sort())
+    expect(
+      registry
+        .filter((entry) => entry.kind === 'agent')
+        .map((entry) => entry.id)
+        .sort(),
+    ).toEqual([...loadChecks().keys()].sort())
+    expect(new Set(registry.map((entry) => `${entry.kind}:${entry.id}`)).size).toBe(registry.length)
+  })
+
+  test('has catalog documentation for every deterministic rule', () => {
+    const catalogIds = new Set(RULE_CATALOG.map((entry) => entry.id))
+    expect(DETERMINISTIC_RULES.filter((entry) => !catalogIds.has(entry.id))).toEqual([])
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/request-scope.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/request-scope.test.ts
new file mode 100644
index 00000000000..c42042dafbb
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/request-scope.test.ts
@@ -0,0 +1,135 @@
+import {scanRequestDerivedShopScope} from '../rules/request-scope-rules.js'
+import {describe, expect, test} from 'vitest'
+import type {SourceFile} from '../rules/types.js'
+
+const rb = (content: string, path = 'app/controllers/things_controller.rb'): SourceFile => ({
+  path,
+  absolutePath: `/tmp/${path}`,
+  ext: '.rb',
+  content,
+})
+
+const run = (content: string, path?: string) => scanRequestDerivedShopScope([rb(content, path)])
+
+describe('REQUEST_DERIVED_SHOP_SCOPE', () => {
+  test('flags a query whose shop scope comes straight from params', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def destroy
+          Token.where(shop_id: params[:shop_id]).delete_all
+        end
+      end
+    `)
+    expect(issues).toHaveLength(1)
+    expect(issues[0]?.confidence).toBe('needs_review')
+    expect(issues[0]?.id).toBe('REQUEST_DERIVED_SHOP_SCOPE')
+  })
+
+  test('flags find_by with a request-supplied shop alongside other conditions', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def show
+          token = Token.find_by(shop_id: params[:shop_id], app: app_type)
+        end
+      end
+    `)
+    expect(issues).toHaveLength(1)
+  })
+
+  test('does not flag a query scoped by the authenticated session', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def index
+          Token.where(shop_id: current_shop.id).to_a
+        end
+      end
+    `)
+    expect(issues).toHaveLength(0)
+  })
+
+  test('does not flag looking up the tenant record itself during install', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def callback
+          @shop = Shop.find_by(shopify_domain: params[:shop])
+        end
+      end
+    `)
+    expect(issues).toHaveLength(0)
+  })
+
+  test('follows a request-bound local within the same method', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def destroy
+          shop_id = params[:shop_id]
+          Token.where(shop_id: shop_id).delete_all
+        end
+      end
+    `)
+    expect(issues).toHaveLength(1)
+  })
+
+  test('does not leak a binding into a method that shadows the name as a parameter', () => {
+    // Regression: Flow assigns shop_id = params[:shop_id] in update_cookie,
+    // and save_access_token later takes shop_id as its own parameter. A
+    // file-global binding map flagged the second, safe call site.
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def update_cookie
+          shop_id = params[:shop_id]
+          cookies.signed[:shop_id] = shop_id
+        end
+
+        def save_access_token(shop_id, access_token)
+          row = Token.find_or_initialize_by(shop_id: shop_id, app: app_type)
+          row.save!
+        end
+      end
+    `)
+    expect(issues).toHaveLength(0)
+  })
+
+  test('clears a binding when the local is reassigned from a trusted source', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def index
+          shop_id = params[:shop_id]
+          shop_id = current_shop.id
+          Token.where(shop_id: shop_id).to_a
+        end
+      end
+    `)
+    expect(issues).toHaveLength(0)
+  })
+
+  test('ignores non-controller files', () => {
+    const issues = run(`Token.where(shop_id: params[:shop_id]).delete_all`, 'app/models/token.rb')
+    expect(issues).toHaveLength(0)
+  })
+
+  test('ignores test files', () => {
+    const issues = run(
+      `
+      class ThingsControllerTest < ActionDispatch::IntegrationTest
+        def test_thing
+          Token.where(shop_id: params[:shop_id]).delete_all
+        end
+      end
+      `,
+      'test/controllers/things_controller_test.rb',
+    )
+    expect(issues).toHaveLength(0)
+  })
+
+  test('ignores commented-out code', () => {
+    const issues = run(`
+      class ThingsController < ApplicationController
+        def destroy
+          # Token.where(shop_id: params[:shop_id]).delete_all
+        end
+      end
+    `)
+    expect(issues).toHaveLength(0)
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/secret-safety.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/secret-safety.test.ts
new file mode 100644
index 00000000000..6985d375ac9
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/secret-safety.test.ts
@@ -0,0 +1,270 @@
+/* eslint-disable id-length, line-comment-position, no-restricted-imports -- security fixtures exercise raw git and filesystem behavior */
+import {scan} from '../scanners/index.js'
+import {SECRET_PATTERNS, redactMatch, gitStatusFor} from '../rules/secret-rules.js'
+import {describe, expect, test} from 'vitest'
+import {mkdtempSync, writeFileSync, mkdirSync, rmSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+import {execFileSync} from 'node:child_process'
+
+/**
+ * Regression tests for two defects found in review, both of which the existing
+ * suite and the eval gate passed cleanly:
+ *
+ *   1. The secret scanner printed detected AWS keys verbatim into the console
+ *      AND into app-doctor-trace.json — the artifact developers are told to
+ *      submit to Shopify. Detection patterns and redaction patterns were two
+ *      independent lists, and they drifted.
+ *
+ *   2. A .env that was committed and only afterwards added to .gitignore was
+ *      downgraded from critical to medium, because the rule inferred "not
+ *      committed" from the presence of a line in .gitignore. That is the most
+ *      common real-world secret leak, and the tool called it safe.
+ *
+ * The eval gate reported 100% precision throughout, because precision only
+ * asks "did we flag the fixture", never "did we handle the finding safely".
+ *
+ * ────────────────────────────────────────────────────────────────────────────
+ * NOTE ON TEST DATA
+ *
+ * Every credential-shaped value below is ASSEMBLED AT RUNTIME from fragments
+ * rather than written as a literal. All values are non-functional, but their
+ * *shape* is real by design — that is the whole point of the test — and a
+ * literal would be flagged by GitHub push protection and by any other secret
+ * scanner pointed at this repository. (The first version of this file was
+ * rejected by GitHub push protection for exactly that reason, which is a
+ * decent live demonstration of the bug being fixed here.)
+ *
+ * Keep it that way: never paste a literal credential-shaped string into this
+ * file, even a fake one.
+ * ────────────────────────────────────────────────────────────────────────────
+ */
+
+/** Assemble a credential-shaped probe value without writing a literal. */
+const compose = (prefix: string, body: string): string => `${prefix}${body}`
+
+const HEX32 = '0123456789abcdef'.repeat(2)
+const ALNUM = 'abcdefghijklmnopqrstuvwxyz0123456789'
+
+const PROBES = {
+  awsAccessKey: compose('AKIA', 'IOSFODNN7EXAMPLE'),
+  awsSecretKey: compose('wJalrXUtnFEMI', 'K7MDENGbPxRfiCYEXAMPLEKEY12'),
+  stripeLive: compose('sk_', `live_51H8xQ2eZvKYlo2C${ALNUM.slice(0, 24)}`),
+  shopifyToken: compose('shp', `at_${HEX32}`),
+  shopifySecret: compose('shp', `ss_${HEX32}`),
+  githubToken: compose('gh', `p_${ALNUM.repeat(2).slice(0, 36)}`),
+  googleKey: compose('AIza', `Sy${ALNUM.repeat(2).slice(0, 33)}`),
+  slackToken: compose('xox', `b-123456789012-${ALNUM.slice(0, 16)}`),
+  pemHeader: compose('-----BEGIN ', 'RSA PRIVATE KEY-----'),
+}
+
+const TOML = `name = "t"
+client_id = "abc123"
+application_url = "https://example.com"
+[access_scopes]
+scopes = "read_orders"
+[webhooks]
+api_version = "2025-01"
+`
+
+const makeApp = (files: Record<string, string>): string => {
+  const dir = mkdtempSync(join(tmpdir(), 'doctor-secret-'))
+  writeFileSync(join(dir, 'shopify.app.toml'), TOML)
+  for (const [path, content] of Object.entries(files)) {
+    const full = join(dir, path)
+    mkdirSync(join(full, '..'), {recursive: true})
+    writeFileSync(full, content)
+  }
+  return dir
+}
+
+const git = (dir: string, args: string[]) =>
+  execFileSync('git', args, {
+    cwd: dir,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 't',
+      GIT_AUTHOR_EMAIL: 't@t',
+      GIT_COMMITTER_NAME: 't',
+      GIT_COMMITTER_EMAIL: 't@t',
+    },
+  })
+
+describe('redaction never emits the secret it detected', () => {
+  const samples: [string, string][] = [
+    ['AWS access key', `const k = "${PROBES.awsAccessKey}";`],
+    ['Stripe API key', `const k = "${PROBES.stripeLive}";`],
+    ['Shopify token', `const k = "${PROBES.shopifyToken}";`],
+    ['GitHub token', `const k = "${PROBES.githubToken}";`],
+    ['Google API key', `const k = "${PROBES.googleKey}";`],
+    ['Slack token', `const k = "${PROBES.slackToken}";`],
+    ['Shopify API key', `const apiKey = "${HEX32}";`],
+  ]
+
+  for (const [label, line] of samples) {
+    test(`redacts ${label} in the snippet`, () => {
+      const matching = SECRET_PATTERNS.filter((p) => p.regex.test(line))
+      expect(matching.length, `no pattern detected ${label}`).toBeGreaterThan(0)
+
+      for (const pattern of matching) {
+        const match = pattern.regex.exec(line)!
+        const secret = pattern.wholeMatch ? match[0] : match[1]
+        const redacted = redactMatch(line, pattern)
+        expect(redacted, `${label} leaked via ${pattern.name}`).not.toContain(secret)
+        expect(redacted).toContain('REDACTED')
+      }
+    })
+  }
+
+  test('every detection pattern has working redaction — no drift between the two', () => {
+    // The original bug: a pattern existed in the detector with no counterpart
+    // in the redactor. Assert the property directly for every pattern rather
+    // than trusting that two hand-maintained lists stay in sync.
+    let exercised = 0
+    for (const pattern of SECRET_PATTERNS) {
+      const probe = probeFor(pattern.name)
+      if (!probe || !pattern.regex.test(probe)) continue
+      exercised++
+      const match = pattern.regex.exec(probe)!
+      const secret = pattern.wholeMatch ? match[0] : match[1]
+      expect(redactMatch(probe, pattern), `${pattern.name} has no effective redaction`).not.toContain(secret)
+    }
+    // Guard against the probe table silently falling out of date and making
+    // this test vacuous.
+    expect(exercised).toBeGreaterThanOrEqual(SECRET_PATTERNS.length - 1)
+  })
+
+  test('does not leak a detected secret into the trace written for submission', async () => {
+    const dir = makeApp({
+      'config.js': `const awsKey = "${PROBES.awsAccessKey}";\n`,
+    })
+    const result = await scan(dir)
+    const serialized = JSON.stringify(result)
+    expect(serialized).not.toContain(PROBES.awsAccessKey)
+    expect(serialized).toContain('REDACTED')
+    rmSync(dir, {recursive: true, force: true})
+  })
+})
+
+describe('git status drives severity, not .gitignore text', () => {
+  test('keeps a tracked .env CRITICAL even when it is listed in .gitignore', async () => {
+    // The classic leak: commit the file, then gitignore it and assume safety.
+    const dir = makeApp({})
+    git(dir, ['init', '-q', '.'])
+    writeFileSync(join(dir, '.env'), 'SHOPIFY_API_SECRET=placeholder-value-here\n')
+    git(dir, ['add', '-f', '.env'])
+    git(dir, ['commit', '-qm', 'oops'])
+    writeFileSync(join(dir, '.gitignore'), '.env\n')
+
+    expect(git(dir, ['ls-files', '.env']).trim()).toBe('.env') // still tracked
+
+    const result = await scan(dir)
+    const finding = result.issues.find((i) => i.id === 'COMMITTED_SECRET')
+    expect(finding).toBeDefined()
+    expect(finding!.severity).toBe('critical')
+    expect(finding!.points).toBe(-50)
+    expect(finding!.detection_evidence?.join(' ')).toContain('TRACKED')
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  test('downgrades only when git confirms the file is untracked AND ignored', async () => {
+    const dir = makeApp({})
+    git(dir, ['init', '-q', '.'])
+    writeFileSync(join(dir, '.gitignore'), '.env\n')
+    git(dir, ['add', '.gitignore'])
+    git(dir, ['commit', '-qm', 'init'])
+    writeFileSync(join(dir, '.env'), 'SHOPIFY_API_SECRET=placeholder-value-here\n')
+
+    const result = await scan(dir)
+    const finding = result.issues.find((i) => i.id === 'COMMITTED_SECRET')
+    expect(finding).toBeDefined()
+    expect(finding!.severity).toBe('medium')
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  test('fails closed when git cannot answer (no repository)', async () => {
+    // Unknown status must never be treated as safe.
+    const dir = makeApp({})
+    writeFileSync(join(dir, '.env'), 'SHOPIFY_API_SECRET=placeholder-value-here\n')
+    writeFileSync(join(dir, '.gitignore'), '.env\n')
+
+    const result = await scan(dir)
+    const finding = result.issues.find((i) => i.id === 'COMMITTED_SECRET')
+    expect(finding).toBeDefined()
+    expect(finding!.severity).toBe('critical')
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  test('reports tri-state status rather than a boolean guess', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'doctor-nogit-'))
+    const status = await gitStatusFor(dir, '.env')
+    // Outside a repo both answers are unknown — not `false`.
+    expect(status.tracked).toBeUndefined()
+    expect(status.ignored).toBeUndefined()
+    expect(status.reason).toBeTruthy()
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  test('honours gitignore negation, which hand-parsing got wrong', async () => {
+    // `.env*` ignored but `!.env.example` re-included. The old substring
+    // parser had no concept of negation.
+    const dir = makeApp({})
+    git(dir, ['init', '-q', '.'])
+    writeFileSync(join(dir, '.gitignore'), '.env*\n!.env.example\n')
+    writeFileSync(join(dir, '.env.example'), 'SHOPIFY_API_KEY=placeholder\n')
+
+    const status = await gitStatusFor(dir, '.env.example')
+    expect(status.ignored).toBe(false) // negated back in
+    rmSync(dir, {recursive: true, force: true})
+  })
+})
+
+describe('incomplete coverage is reported, not hidden', () => {
+  test('records oversized files as skipped instead of silently dropping them', async () => {
+    const dir = makeApp({'huge.js': `// pad\n${'x'.repeat(600_000)}\n`})
+    const result = await scan(dir)
+    expect(result.scan.files_skipped_count).toBeGreaterThan(0)
+    const skipped = result.scan.files_skipped ?? []
+    expect(skipped.some((f) => f.path.endsWith('huge.js') && f.reason === 'too_large')).toBe(true)
+    rmSync(dir, {recursive: true, force: true})
+  })
+
+  test('reports zero skipped files for a fully-scanned app', async () => {
+    const dir = makeApp({'small.js': 'const a = 1;\n'})
+    const result = await scan(dir)
+    expect(result.scan.files_skipped_count).toBe(0)
+    rmSync(dir, {recursive: true, force: true})
+  })
+})
+
+/** Probe strings with realistic shape, assembled at runtime. See note above. */
+function probeFor(name: string): string | undefined {
+  switch (name) {
+    case 'Shopify API key':
+      return `api_key = "${HEX32}"`
+    case 'Shopify API secret':
+      return `api_secret = "${PROBES.shopifySecret}"`
+    case 'Shopify access token':
+      return `access_token = "${PROBES.shopifyToken}"`
+    case 'Shopify token':
+      return `x = ${PROBES.shopifyToken}`
+    case 'Stripe API key':
+      return `x = ${PROBES.stripeLive}`
+    case 'AWS access key':
+      return `x = ${PROBES.awsAccessKey}`
+    case 'AWS secret access key':
+      return `aws_secret_access_key = "${PROBES.awsSecretKey}"`
+    case 'GitHub token':
+      return `x = ${PROBES.githubToken}`
+    case 'Google API key':
+      return `x = ${PROBES.googleKey}`
+    case 'Slack token':
+      return `x = ${PROBES.slackToken}`
+    case 'private key':
+      return PROBES.pemHeader
+    default:
+      return undefined
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/shopify-rules.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/shopify-rules.test.ts
new file mode 100644
index 00000000000..2a563113927
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/shopify-rules.test.ts
@@ -0,0 +1,167 @@
+import {scanUnauthenticatedEndpoints} from '../rules/endpoint-rules.js'
+import {
+  scanAppProxyUnverifiedSignature,
+  scanDeprecatedScriptTagApi,
+  scanRequestControlledAdminContext,
+  scanRuntimeConfigScriptExecution,
+  scanStaticFrameAncestors,
+  scanUnscopedShopConfigWrite,
+} from '../rules/shopify-rules.js'
+import {describe, expect, test} from 'vitest'
+/* eslint-disable @shopify/cli/no-inline-graphql -- inline source snippets are scanner test fixtures */
+import type {SourceFile} from '../rules/types.js'
+
+const sourceFile = (path: string, content: string): SourceFile => ({
+  path,
+  absolutePath: `/app/${path}`,
+  ext: path.slice(path.lastIndexOf('.')),
+  content,
+})
+
+describe('Shopify-specific security rules', () => {
+  test('flags request-controlled shop selection of unauthenticated Admin API context', () => {
+    const issues = scanRequestControlledAdminContext([
+      sourceFile(
+        'app/routes/app.combined_listings.$id/action.ts',
+        `export const action = async ({ request }) => {
+  const formData = await request.formData();
+  return getGraphqlClient(request, formData);
+};
+async function getGraphqlClient(request: Request, formData: FormData) {
+  const { admin } = await authenticate.admin(request);
+  const shop = formData.get("shop");
+  if (typeof shop === "string" && shop.length > 0) {
+    const { admin: requestedShopAdmin } = await unauthenticated.admin(shop);
+    return requestedShopAdmin.graphql;
+  }
+  return admin.graphql;
+}`,
+      ),
+    ])
+
+    expect(issues).toHaveLength(1)
+    expect(issues[0]?.id).toBe('REQUEST_CONTROLLED_ADMIN_CONTEXT')
+    expect(issues[0]?.location.line).toBe(9)
+  })
+
+  test('does not also report a route as unauthenticated when auth is delegated to a helper', () => {
+    const issues = scanUnauthenticatedEndpoints([
+      sourceFile(
+        'app/routes/app.combined_listings.$id/action.ts',
+        `export const action = async ({ request }) => {
+  const formData = await request.formData();
+  const graphql = await getGraphqlClient(request, formData);
+  return updateCombinedListing(graphql);
+};
+async function getGraphqlClient(request: Request, formData: FormData) {
+  const { admin } = await authenticate.admin(request);
+  return admin.graphql;
+}`,
+      ),
+    ])
+
+    expect(issues).toHaveLength(0)
+  })
+
+  test('stays silent when unauthenticated Admin API context uses a trusted job shop', () => {
+    const issues = scanRequestControlledAdminContext([
+      sourceFile(
+        'server/jobs/sync.ts',
+        `export const sync = async (job: SyncJob) => {
+  const { admin } = await unauthenticated.admin(job.shop);
+  return admin.graphql("mutation Sync { productUpdate { id } }");
+};`,
+      ),
+    ])
+
+    expect(issues).toHaveLength(0)
+  })
+
+  test('flags runtime config script execution', () => {
+    const issues = scanRuntimeConfigScriptExecution([
+      sourceFile(
+        'extensions/widget/assets/loader.ts',
+        `const config = await (await fetch("/apps/widget/config")).json();
+const script = document.createElement("script");
+script.src = config.external_script;
+document.head.appendChild(script);`,
+      ),
+    ])
+
+    expect(issues.map((issue) => issue.id)).toEqual(['RUNTIME_CONFIG_SCRIPT_EXECUTION'])
+  })
+
+  test('flags deprecated ScriptTag creation but not deletion', () => {
+    const created = scanDeprecatedScriptTagApi([
+      sourceFile(
+        'app/services/install.ts',
+        `await admin.graphql("mutation { scriptTagCreate(input: { src: $src }) { scriptTag { id } } }");`,
+      ),
+    ])
+    const deleted = scanDeprecatedScriptTagApi([
+      sourceFile(
+        'app/services/uninstall.ts',
+        `await admin.graphql("mutation { scriptTagDelete(id: $id) { deletedScriptTagId } }");`,
+      ),
+    ])
+
+    expect(created.map((issue) => issue.id)).toEqual(['DEPRECATED_SCRIPT_TAG_API'])
+    expect(deleted).toHaveLength(0)
+  })
+
+  test('flags app proxy params without signature verification', () => {
+    const unsafe = scanAppProxyUnverifiedSignature([
+      sourceFile(
+        'app/routes/proxy.wishlist.ts',
+        `export const loader = async ({ request }) => {
+  const url = new URL(request.url);
+  const customerId = url.searchParams.get("logged_in_customer_id");
+  return json(await loadWishlist(customerId));
+};`,
+      ),
+    ])
+    const safe = scanAppProxyUnverifiedSignature([
+      sourceFile(
+        'app/routes/proxy.wishlist.ts',
+        `export const loader = async ({ request }) => {
+  const { session } = await authenticate.public.appProxy(request);
+  const url = new URL(request.url);
+  const customerId = url.searchParams.get("logged_in_customer_id");
+  return json(await loadWishlist(session.shop, customerId));
+};`,
+      ),
+    ])
+
+    expect(unsafe.map((issue) => issue.id)).toEqual(['APP_PROXY_UNVERIFIED_SIGNATURE'])
+    expect(safe).toHaveLength(0)
+  })
+
+  test('flags unscoped config writes using request-controlled shops', () => {
+    const issues = scanUnscopedShopConfigWrite([
+      sourceFile(
+        'server/api/update-settings.ts',
+        `export const handler = async (req, res) => {
+  const shop = req.body.shop;
+  await widgetSettings.updateOne({ shop }, { $set: req.body.settings });
+  res.json({ ok: true });
+};`,
+      ),
+    ])
+
+    expect(issues.map((issue) => issue.id)).toEqual(['UNSCOPED_SHOP_CONFIG_WRITE'])
+  })
+
+  test('flags wildcard frame-ancestors in Shopify app code', () => {
+    const issues = scanStaticFrameAncestors([
+      sourceFile(
+        'server/headers.ts',
+        `import "@shopify/shopify-app-remix";
+res.setHeader("Content-Security-Policy", "frame-ancestors https://*.myshopify.com https://admin.shopify.com");`,
+      ),
+    ])
+
+    expect(issues.map((issue) => issue.id)).toEqual(['STATIC_FRAME_ANCESTORS'])
+  })
+})
+
+/* eslint-enable @shopify/cli/no-inline-graphql */
diff --git a/packages/app/src/cli/services/app-doctor-engine/tests/trace.test.ts b/packages/app/src/cli/services/app-doctor-engine/tests/trace.test.ts
new file mode 100644
index 00000000000..e6b2d750a3b
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/tests/trace.test.ts
@@ -0,0 +1,367 @@
+/* eslint-disable no-restricted-imports -- trace fixtures use Node temporary-directory primitives */
+import {computeResultHash} from '../scorer/index.js'
+import {
+  compileTrace,
+  formatConsole,
+  formatJson,
+  mergeExternalFindings,
+  scan,
+  sha256,
+  validateTrace,
+  validateExternalFinding,
+  validateSuppression,
+  type Issue,
+  type ScanResult,
+  type Suppression,
+} from '../index.js'
+import {afterEach, describe, expect, test} from 'vitest'
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+
+const dirs: string[] = []
+afterEach(() => dirs.splice(0).forEach((dir) => rmSync(dir, {recursive: true, force: true})))
+
+const result = (issues: Issue[] = []): ScanResult => ({
+  version: '0.1.0',
+  timestamp: '2026-08-28T00:00:00.000Z',
+  project: {commit: 'a'.repeat(40), dirty: false},
+  app: {name: 'trace-test', type: 'public'},
+  capabilities: {
+    theme_app_extension: false,
+    app_embed: false,
+    script_tags: false,
+    webhooks: false,
+    app_proxy: false,
+    storefront_metafield_writes: false,
+    has_backend: true,
+    declared_ip_allowlist: false,
+    checkout_extension: false,
+  },
+  score: {total: 70, baseline: 70, grade: 'NEEDS_WORK'},
+  scan: {
+    timestamp: '2026-08-28T00:00:00.000Z',
+    doctor_version: '0.1.0',
+    files_scanned: 1,
+    rules_run: 1,
+    rules_skipped: 0,
+    files_skipped_count: 0,
+    input_hash: `sha256:${'b'.repeat(64)}`,
+    result_hash: `sha256:${'c'.repeat(64)}`,
+    file_hashes: {'app/a.ts': `sha256:${'d'.repeat(64)}`},
+    checks_executed: [
+      {
+        id: 'TOKEN_LEAKAGE',
+        version: 1,
+        kind: 'rule',
+        status: 'executed',
+        findings: 0,
+      },
+    ],
+  },
+  issues,
+})
+
+const deterministicIssue = (): Issue => ({
+  id: 'TOKEN_LEAKAGE',
+  rule_version: 1,
+  found_by: 'static',
+  severity: 'high',
+  points: -20,
+  title: 'Token logged',
+  message: 'A token is logged',
+  location: {file: 'app/a.ts', line: 2},
+  evidence: [{location: {file: 'app/a.ts', line: 2}, quote: 'console.log(token)'}],
+  snippet: 'console.log(token)',
+  fix: {automated: false, description: 'Remove it'},
+})
+
+describe('trace v1', () => {
+  test('compiles and validates a portable v1 trace with zero-finding checks', () => {
+    const trace = compileTrace(result(), {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    expect(trace.schema_version).toBe(1)
+    expect(trace.engine.name).toBe('shopify-app-doctor')
+    expect(trace.project).toMatchObject({
+      commit: 'a'.repeat(40),
+      dirty: false,
+    })
+    expect(trace.checks_executed).toContainEqual(
+      expect.objectContaining({
+        id: 'TOKEN_LEAKAGE',
+        status: 'executed',
+        findings: 0,
+      }),
+    )
+    expect(trace.attestation).toMatchObject({signed: false})
+    expect(trace.attestation.digest).toMatch(/^sha256:[0-9a-f]{64}$/)
+    expect(validateTrace(trace)).toEqual({valid: true, errors: []})
+  })
+
+  test('rejects malformed required fields even when the outer digest is recomputed', () => {
+    const trace = compileTrace(result([deterministicIssue()]), {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    const malformed = structuredClone(trace) as unknown as Record<string, any>
+    malformed.generated_at = 'not-a-date'
+    malformed.engine.name = 'not-app-doctor'
+    malformed.project.input_hashes['/etc/passwd'] = `sha256:${'f'.repeat(64)}`
+    malformed.findings[0].rule_version = -1
+    malformed.findings[0].fingerprint = 'not-a-hash'
+    delete malformed.findings[0].title
+    delete malformed.findings[0].fix
+    delete malformed.coverage.files_scanned
+    const {attestation: _old, ...unsigned} = malformed
+    malformed.attestation = {digest: sha256(unsigned), signed: false}
+    const errors = validateTrace(malformed).errors.join(' ')
+    expect(errors).toMatch(/generated_at/)
+    expect(errors).toMatch(/engine/)
+    expect(errors).toMatch(/project/)
+    expect(errors).toMatch(/fingerprint/)
+    expect(errors).toMatch(/provenance/)
+    expect(errors).toMatch(/coverage/)
+    expect(
+      validateSuppression({
+        id: 'bad-actor',
+        finding_fingerprint: `sha256:${'a'.repeat(64)}`,
+        justification: 'test',
+        provenance: {
+          source: 'human',
+          actor: 42,
+          created_at: '2026-08-28T00:00:00.000Z',
+        },
+      }),
+    ).toMatch(/actor/)
+  })
+
+  test('never throws on cyclic or excessively deep unknown input', () => {
+    const cyclic: Record<string, unknown> = {}
+    cyclic.self = cyclic
+    expect(() => validateTrace(cyclic)).not.toThrow()
+    expect(validateTrace(cyclic).valid).toBe(false)
+    let deep: Record<string, unknown> = {}
+    const root = deep
+    for (let index = 0; index < 200; index++) {
+      deep.next = {}
+      deep = deep.next as Record<string, unknown>
+    }
+    expect(() => validateTrace(root)).not.toThrow()
+    expect(validateTrace(root).valid).toBe(false)
+  })
+
+  test('rejects unknown schemas, malformed provenance, and a changed digest', () => {
+    const trace = compileTrace(result([deterministicIssue()]), {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    expect(validateTrace({...trace, schema_version: 2}).errors).toContain('unsupported schema_version: 2')
+    const changed = structuredClone(trace)
+    const [changedFinding] = changed.findings
+    if (!changedFinding) throw new Error('Expected the trace to contain a finding')
+    changedFinding.message = 'edited'
+    expect(validateTrace(changed).errors).toContain('attestation digest mismatch')
+    const malformed = structuredClone(trace) as unknown as {
+      findings: Record<string, unknown>[]
+    }
+    const [malformedFinding] = malformed.findings
+    if (!malformedFinding) throw new Error('Expected the trace to contain a finding')
+    delete malformedFinding.rule_version
+    expect(validateTrace(malformed).errors.some((error) => error.includes('rule provenance'))).toBe(true)
+  })
+
+  test('recomputes the scan result hash over merged finding content', () => {
+    const scanResult = result()
+    const before = computeResultHash(scanResult.issues, scanResult.score)
+    scanResult.issues.push(deterministicIssue())
+    expect(computeResultHash(scanResult.issues, scanResult.score)).not.toBe(before)
+    const changed = deterministicIssue()
+    changed.evidence = [{location: changed.location, quote: 'different'}]
+    expect(computeResultHash([changed], scanResult.score)).not.toBe(
+      computeResultHash([deterministicIssue()], scanResult.score),
+    )
+  })
+
+  test('hashes full finding messages, locations, snippets, and evidence independent of ordering', () => {
+    const base = deterministicIssue()
+    const first = compileTrace(result([base]), {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    for (const changed of [
+      {...base, message: 'different'},
+      {...base, location: {...base.location, line: 3}},
+      {...base, snippet: 'different'},
+      {...base, evidence: [{location: base.location, quote: 'different'}]},
+    ]) {
+      expect(compileTrace(result([changed]), {generatedAt: first.generated_at}).attestation.digest).not.toBe(
+        first.attestation.digest,
+      )
+    }
+    const second = {...base, location: {file: 'app/b.ts', line: 1}}
+    expect(compileTrace(result([base, second]), {generatedAt: first.generated_at}).attestation.digest).toBe(
+      compileTrace(result([second, base]), {generatedAt: first.generated_at}).attestation.digest,
+    )
+  })
+
+  test('preserves justified suppression provenance and attaches it by fingerprint', () => {
+    const initial = compileTrace(result([deterministicIssue()]), {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    const [initialFinding] = initial.findings
+    if (!initialFinding) throw new Error('Expected the trace to contain a finding')
+    const suppression: Suppression = {
+      id: 'approved-risk',
+      finding_fingerprint: initialFinding.fingerprint,
+      justification: 'Accepted for the migration window',
+      provenance: {
+        source: 'human',
+        actor: 'security@example.com',
+        created_at: '2026-08-28T00:00:00.000Z',
+      },
+    }
+    const trace = compileTrace(result([deterministicIssue()]), {
+      suppressions: [suppression],
+      generatedAt: initial.generated_at,
+    })
+    expect(trace.findings[0]?.suppression?.id).toBe('approved-risk')
+    expect(trace.suppressions).toEqual([suppression])
+    expect(validateTrace(trace).valid).toBe(true)
+  })
+
+  test('rejects malformed, unsafe, and unbounded external findings', () => {
+    const valid = {
+      rule_id: 'VENDOR_RULE',
+      rule_version: 1,
+      severity: 'low' as const,
+      title: 'Vendor',
+      message: 'Review',
+      location: {file: 'app/a.ts', line: 1},
+    }
+    expect(validateExternalFinding({...valid, rule_id: ''})).toMatch(/rule_id/)
+    expect(validateExternalFinding({...valid, location: {file: '../secret'}})).toMatch(/unsafe/)
+    expect(
+      mergeExternalFindings([], [{...valid, location: {file: 'unknown.ts'}}], {knownFiles: new Set(['app/a.ts'])})
+        .rejected[0],
+    ).toMatch(/scanned inputs/)
+    expect(
+      mergeExternalFindings(
+        [],
+        Array.from({length: 1_001}, () => valid),
+      ).rejected[0],
+    ).toMatch(/limit/)
+  })
+
+  test('rejects suppressions that do not match a current finding', () => {
+    expect(() =>
+      compileTrace(result(), {
+        suppressions: [
+          {
+            id: 'stale',
+            finding_fingerprint: `sha256:${'e'.repeat(64)}`,
+            justification: 'Old exception',
+            provenance: {
+              source: 'human',
+              created_at: '2026-08-28T00:00:00.000Z',
+            },
+          },
+        ],
+      }),
+    ).toThrow(/did not match/)
+  })
+
+  test('accepts external findings with explicit source and rule provenance', () => {
+    const scanResult = result()
+    expect(
+      mergeExternalFindings(scanResult.issues, [
+        {
+          rule_id: 'VENDOR_RULE',
+          rule_version: 3,
+          severity: 'low',
+          title: 'Vendor finding',
+          message: 'Review',
+          location: {file: 'app/a.ts', line: 1},
+        },
+      ]).accepted,
+    ).toBe(1)
+    const trace = compileTrace(scanResult, {
+      generatedAt: '2026-08-28T00:00:00.000Z',
+    })
+    expect(trace.findings[0]).toMatchObject({
+      source: 'external',
+      rule_id: 'VENDOR_RULE',
+      rule_version: 3,
+    })
+    expect(validateTrace(trace).valid).toBe(true)
+  })
+
+  test('fails closed when text contains more secret matches than the work cap', () => {
+    const secrets = Array.from({length: 150}, (_, index) => `AKIA${index.toString(36).toUpperCase().padStart(16, 'A')}`)
+    const issue = deterministicIssue()
+    issue.message = secrets.join(' ')
+    const scanResult = result([issue])
+    const outputs = [
+      JSON.stringify(compileTrace(scanResult)),
+      formatConsole(scanResult, {verbose: true}),
+      formatJson(scanResult),
+    ]
+    for (const output of outputs) {
+      for (const secret of secrets) expect(output).not.toContain(secret)
+      expect(output).toContain('[REDACTED TEXT]')
+    }
+  })
+
+  test('redacts matched secrets from every finding output field', () => {
+    const secret = `shpat_${'a'.repeat(24)}`
+    const issue = deterministicIssue()
+    issue.title = `title ${secret}`
+    issue.message = `message ${secret}`
+    issue.snippet = `snippet ${secret}`
+    issue.evidence = [{location: issue.location, quote: `quote ${secret}`}]
+    issue.fix.description = `fix ${secret}`
+    issue.fix.guide = `https://example.com/${secret}`
+    const serialized = JSON.stringify(compileTrace(result([issue])))
+    expect(serialized).not.toContain(secret)
+    expect(serialized).toContain('[REDACTED:')
+
+    const scanResult = result([issue])
+    scanResult.app.name = `app ${secret}`
+    expect(formatConsole(scanResult, {verbose: true})).not.toContain(secret)
+    expect(formatJson(scanResult)).not.toContain(secret)
+  })
+})
+
+describe('strong scan input hashes', () => {
+  const app = (name: string): string => {
+    const dir = mkdtempSync(join(tmpdir(), 'app-doctor-trace-'))
+    dirs.push(dir)
+    writeFileSync(join(dir, 'shopify.app.toml'), `name = "${name}"\napplication_url = "https://example.com"\n`)
+    return dir
+  }
+
+  test('hashes valid and invalid manifests using project-relative paths', async () => {
+    const dir = app('manifests')
+    writeFileSync(join(dir, 'package.json'), '{"dependencies":{"react":"1.0.0"}}')
+    const valid = await scan(dir)
+    expect(valid.scan.file_hashes?.['package.json']).toMatch(/^sha256:[0-9a-f]{64}$/)
+    writeFileSync(join(dir, 'package.json'), '{invalid')
+    const invalid = await scan(dir)
+    expect(invalid.scan.file_hashes?.['package.json']).toMatch(/^sha256:[0-9a-f]{64}$/)
+    expect(invalid.scan.files_skipped).toContainEqual(
+      expect.objectContaining({path: 'package.json', reason: 'unreadable'}),
+    )
+    expect(compileTrace(invalid).coverage.complete).toBe(false)
+  })
+
+  test('includes config bytes and file paths', async () => {
+    const dir = app('first')
+    writeFileSync(join(dir, 'a.ts'), 'export const same = true;')
+    const before = await scan(dir)
+    writeFileSync(join(dir, 'shopify.app.toml'), 'name = "second"\napplication_url = "https://example.com"\n')
+    const configChanged = await scan(dir)
+    expect(configChanged.scan.input_hash).not.toBe(before.scan.input_hash)
+
+    rmSync(join(dir, 'a.ts'))
+    writeFileSync(join(dir, 'b.ts'), 'export const same = true;')
+    const pathChanged = await scan(dir)
+    expect(pathChanged.scan.input_hash).not.toBe(configChanged.scan.input_hash)
+  })
+})
diff --git a/packages/app/src/cli/services/app-doctor-engine/trace/index.ts b/packages/app/src/cli/services/app-doctor-engine/trace/index.ts
new file mode 100644
index 00000000000..b427e5252aa
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/trace/index.ts
@@ -0,0 +1,570 @@
+import {ENGINE_NAME, SUPPORTED_TRACE_SCHEMA_VERSIONS, TRACE_SCHEMA_VERSION} from '../types.js'
+import {loadChecks} from '../checks/index.js'
+import {redactText} from '../rules/secret-rules.js'
+import {createHash} from 'node:crypto'
+import type {
+  CheckExecution,
+  FindingEvidence,
+  Issue,
+  Location,
+  ScanResult,
+  Severity,
+  Suppression,
+  TraceFinding,
+  TraceV1,
+} from '../types.js'
+
+const SHA256 = /^sha256:[0-9a-f]{64}$/
+const SEVERITIES = new Set<Severity>(['critical', 'high', 'medium', 'low'])
+
+/** Stable JSON for hashes and fingerprints. Object keys are sorted recursively. */
+export function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (value !== null && typeof value === 'object') {
+    const object = value as Record<string, unknown>
+    return `{${Object.keys(object)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
+      .join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+export function sha256(value: unknown): string {
+  const input = typeof value === 'string' ? value : canonicalJson(value)
+  return `sha256:${createHash('sha256').update(input).digest('hex')}`
+}
+
+const safeLocation = (location: Location): Location => ({
+  file: redactText(location.file.replace(/\\/g, '/')),
+  ...(location.line === undefined ? {} : {line: location.line}),
+  ...(location.column === undefined ? {} : {column: location.column}),
+})
+
+const redactEvidence = (evidence: FindingEvidence[] | undefined): FindingEvidence[] =>
+  (evidence ?? []).map((item) => ({
+    location: safeLocation(item.location),
+    ...(item.quote === undefined ? {} : {quote: redactText(item.quote)}),
+  }))
+
+/** Central output boundary: all untrusted and scanner finding text is redacted here. */
+export function redactIssue(issue: Issue): Issue {
+  return {
+    ...issue,
+    id: redactText(issue.id),
+    title: redactText(issue.title),
+    message: redactText(issue.message),
+    location: safeLocation(issue.location),
+    ...(issue.snippet === undefined ? {} : {snippet: redactText(issue.snippet)}),
+    ...(issue.agent_reasoning === undefined ? {} : {agent_reasoning: redactText(issue.agent_reasoning)}),
+    ...(issue.detection_evidence === undefined ? {} : {detection_evidence: issue.detection_evidence.map(redactText)}),
+    ...(issue.evidence === undefined ? {} : {evidence: redactEvidence(issue.evidence)}),
+    fix: {
+      ...issue.fix,
+      description: redactText(issue.fix.description),
+      ...(issue.fix.guide ? {guide: redactText(issue.fix.guide)} : {}),
+    },
+  }
+}
+
+const findingFingerprintPayload = (finding: Omit<TraceFinding, 'fingerprint' | 'suppression' | 'suppressed'>) => ({
+  source: finding.source,
+  rule_id: finding.rule_id ?? null,
+  rule_version: finding.rule_version ?? null,
+  check_id: finding.check_id ?? null,
+  check_version: finding.check_version ?? null,
+  prompt_hash: finding.prompt_hash ?? null,
+  severity: finding.severity,
+  title: finding.title,
+  location: finding.location,
+  message: finding.message,
+  evidence: finding.evidence,
+  snippet: finding.snippet ?? null,
+  fix: finding.fix,
+})
+
+export function findingFingerprint(finding: Omit<TraceFinding, 'fingerprint' | 'suppression' | 'suppressed'>): string {
+  return sha256(findingFingerprintPayload(finding))
+}
+
+function issueFindingSource(issue: Issue): TraceFinding['source'] {
+  if (issue.found_by === 'agent') return 'agent'
+  if (issue.found_by === 'external') return 'external'
+  return 'deterministic'
+}
+
+function issueToFinding(issueInput: Issue): TraceFinding {
+  const issue = redactIssue(issueInput)
+  const source = issueFindingSource(issue)
+  const core: Omit<TraceFinding, 'fingerprint' | 'suppression' | 'suppressed'> = {
+    source,
+    ...(source === 'agent'
+      ? {
+          check_id: issue.id,
+          check_version: issue.check_version,
+          prompt_hash: issue.prompt_hash,
+        }
+      : {rule_id: issue.id, rule_version: issue.rule_version ?? 1}),
+    severity: issue.severity,
+    title: issue.title,
+    message: issue.message,
+    location: issue.location,
+    evidence: redactEvidence(issue.evidence),
+    ...(issue.snippet === undefined ? {} : {snippet: issue.snippet}),
+    fix: issue.fix,
+  }
+  return {fingerprint: findingFingerprint(core), ...core, suppressed: false}
+}
+
+export interface CompileTraceOptions {
+  engineVersion?: string
+  ruleset?: string
+  suppressions?: Suppression[]
+  agentChecksExecuted?: CheckExecution[]
+  externalChecksExecuted?: CheckExecution[]
+  generatedAt?: string
+}
+
+/** Compile a portable trace v1 from a deterministic scan and merged findings. */
+export function compileTrace(result: ScanResult, options: CompileTraceOptions = {}): TraceV1 {
+  const findings = result.issues
+    .map(issueToFinding)
+    .sort((left, right) =>
+      `${left.source}|${left.check_id ?? left.rule_id}|${left.location.file}|${left.location.line ?? 0}|${left.fingerprint}`.localeCompare(
+        `${right.source}|${right.check_id ?? right.rule_id}|${right.location.file}|${right.location.line ?? 0}|${right.fingerprint}`,
+      ),
+    )
+  const suppressionInputs = options.suppressions ?? []
+  const suppressionIds = new Set<string>()
+  const suppressionByFingerprint = new Map<string, Suppression>()
+  for (const suppression of suppressionInputs) {
+    const problem = validateSuppression(suppression)
+    if (problem) throw new Error(`Invalid suppression ${redactText(suppression.id || '<unknown>')}: ${problem}`)
+    if (suppressionIds.has(suppression.id)) throw new Error(`Duplicate suppression id: ${redactText(suppression.id)}`)
+    if (suppressionByFingerprint.has(suppression.finding_fingerprint))
+      throw new Error(`Multiple suppressions target finding ${suppression.finding_fingerprint}`)
+    suppressionIds.add(suppression.id)
+    suppressionByFingerprint.set(suppression.finding_fingerprint, suppression)
+  }
+  const usedSuppressions: Suppression[] = []
+  for (const finding of findings) {
+    const suppression = suppressionByFingerprint.get(finding.fingerprint)
+    if (!suppression) continue
+    const safe: Suppression = {
+      ...suppression,
+      id: redactText(suppression.id),
+      justification: redactText(suppression.justification),
+      provenance: {
+        ...suppression.provenance,
+        ...(suppression.provenance.actor ? {actor: redactText(suppression.provenance.actor)} : {}),
+      },
+    }
+    finding.suppressed = true
+    finding.suppression = {
+      id: safe.id,
+      justification: safe.justification,
+      provenance: safe.provenance,
+    }
+    usedSuppressions.push(safe)
+  }
+  if (usedSuppressions.length !== suppressionInputs.length) {
+    const findingFingerprints = new Set(findings.map((finding) => finding.fingerprint))
+    const unmatched = suppressionInputs
+      .filter((suppression) => !findingFingerprints.has(suppression.finding_fingerprint))
+      .map((suppression) => redactText(suppression.id))
+    throw new Error(`Suppressions did not match current findings: ${unmatched.join(', ')}`)
+  }
+
+  const deterministicExecutions = (result.scan.checks_executed ?? []).map((execution) => ({
+    ...execution,
+    findings: findings.filter((finding) => finding.source === 'deterministic' && finding.rule_id === execution.id)
+      .length,
+  }))
+  const checks = loadChecks()
+  const explicitAgent = new Map((options.agentChecksExecuted ?? []).map((execution) => [execution.id, execution]))
+  const agentExecutions: CheckExecution[] = [...checks.values()].map((check) => {
+    const explicit = explicitAgent.get(check.id)
+    const count = findings.filter((finding) => finding.source === 'agent' && finding.check_id === check.id).length
+    if (explicit) return {...explicit, findings: count}
+
+    return {
+      id: check.id,
+      version: check.version,
+      kind: 'check',
+      status: count > 0 ? 'executed' : 'skipped',
+      findings: count,
+      prompt_hash: check.prompt_hash,
+      ...(count > 0 ? {} : {reason: 'agent review not reported as executed'}),
+    }
+  })
+  const externalById = new Map((options.externalChecksExecuted ?? []).map((execution) => [execution.id, execution]))
+  for (const finding of findings.filter((item) => item.source === 'external')) {
+    if (!externalById.has(finding.rule_id!)) {
+      externalById.set(finding.rule_id!, {
+        id: finding.rule_id!,
+        version: finding.rule_version!,
+        kind: 'external',
+        status: 'executed',
+        findings: 0,
+      })
+    }
+  }
+  const externalExecutions = [...externalById.values()].map((execution) => ({
+    ...execution,
+    findings: findings.filter((finding) => finding.source === 'external' && finding.rule_id === execution.id).length,
+  }))
+  const checksExecuted = [...deterministicExecutions, ...agentExecutions, ...externalExecutions]
+    .map((execution) => ({
+      ...execution,
+      id: redactText(execution.id),
+      ...(execution.reason ? {reason: redactText(execution.reason)} : {}),
+    }))
+    .sort((left, right) => `${left.kind}|${left.id}`.localeCompare(`${right.kind}|${right.id}`))
+
+  const unsigned = {
+    schema_version: TRACE_SCHEMA_VERSION,
+    engine: {
+      name: ENGINE_NAME,
+      version: redactText(options.engineVersion ?? result.version),
+      ruleset: redactText(options.ruleset ?? `app-doctor-rules@${result.version}`),
+    },
+    generated_at: options.generatedAt ?? new Date().toISOString(),
+    project: {
+      commit: result.project.commit,
+      dirty: result.project.dirty,
+      input_hash: result.scan.input_hash,
+      input_hashes: Object.fromEntries(
+        Object.entries(result.scan.file_hashes ?? {}).map(([path, hash]) => [redactText(path), hash]),
+      ),
+    },
+    findings,
+    checks_executed: checksExecuted,
+    suppressions: usedSuppressions.sort((left, right) => left.id.localeCompare(right.id)),
+    coverage: {
+      files_scanned: result.scan.files_scanned,
+      files_skipped: (result.scan.files_skipped ?? []).map((file) => ({
+        ...file,
+        path: redactText(file.path),
+        ...(file.detail ? {detail: redactText(file.detail)} : {}),
+      })),
+      complete: result.scan.files_skipped_count === 0,
+    },
+  }
+  return {
+    ...unsigned,
+    attestation: {digest: sha256(unsigned), signed: false},
+  }
+}
+
+export function validateSuppression(value: unknown): string | undefined {
+  if (!isObject(value)) return 'must be an object'
+  if (typeof value.id !== 'string' || !value.id.trim()) return 'id is required'
+  if (typeof value.finding_fingerprint !== 'string' || !SHA256.test(value.finding_fingerprint))
+    return 'finding_fingerprint must be a SHA-256 digest'
+  if (typeof value.justification !== 'string' || !value.justification.trim()) return 'justification is required'
+  if (!isObject(value.provenance) || !['human', 'policy', 'external'].includes(String(value.provenance.source)))
+    return 'provenance source is invalid'
+  if (!(value.provenance.actor === undefined || typeof value.provenance.actor === 'string'))
+    return 'provenance actor must be a string'
+  if (typeof value.provenance.created_at !== 'string' || Number.isNaN(Date.parse(value.provenance.created_at)))
+    return 'provenance created_at must be an ISO date'
+  return undefined
+}
+
+export function isTraceSchemaVersionSupported(version: unknown): version is typeof TRACE_SCHEMA_VERSION {
+  return SUPPORTED_TRACE_SCHEMA_VERSIONS.includes(version as typeof TRACE_SCHEMA_VERSION)
+}
+
+export interface TraceValidationResult {
+  valid: boolean
+  errors: string[]
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+const validPath = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  value.length > 0 &&
+  value.length <= 1_024 &&
+  !value.includes('\0') &&
+  !value.startsWith('/') &&
+  !/^[a-zA-Z]:[\\/]/.test(value) &&
+  !value.split(/[\\/]/).includes('..')
+const validLocation = (value: unknown): boolean =>
+  isObject(value) &&
+  validPath(value.file) &&
+  (value.line === undefined || (Number.isInteger(value.line) && Number(value.line) > 0)) &&
+  (value.column === undefined || (Number.isInteger(value.column) && Number(value.column) > 0))
+
+const inspectUnknownValue = (root: unknown): {containsSecret: boolean; unsafe: boolean} => {
+  const stack: {value: unknown; depth: number}[] = [{value: root, depth: 0}]
+  const seen = new WeakSet<object>()
+  let containsSecret = false
+  let visited = 0
+  while (stack.length > 0) {
+    const {value, depth} = stack.pop()!
+    if (++visited > 50_000 || depth > 100) return {containsSecret, unsafe: true}
+    if (typeof value === 'string') {
+      if (redactText(value) !== value) containsSecret = true
+      continue
+    }
+    if (value === null || typeof value !== 'object') continue
+    if (seen.has(value)) continue
+    seen.add(value)
+    if (Array.isArray(value)) {
+      for (const item of value) stack.push({value: item, depth: depth + 1})
+    } else {
+      for (const [key, item] of Object.entries(value)) {
+        if (redactText(key) !== key) containsSecret = true
+        stack.push({value: item, depth: depth + 1})
+      }
+    }
+  }
+  return {containsSecret, unsafe: false}
+}
+
+/** Runtime contract validator for traces created by any producer, including outside Shopify CLI. */
+function validateTraceValue(value: unknown): TraceValidationResult {
+  const errors: string[] = []
+  if (!isObject(value)) return {valid: false, errors: ['trace must be an object']}
+  const inspection = inspectUnknownValue(value)
+  if (inspection.unsafe)
+    return {
+      valid: false,
+      errors: ['trace is cyclic or exceeds validation complexity limits'],
+    }
+  if (!isTraceSchemaVersionSupported(value.schema_version))
+    errors.push(`unsupported schema_version: ${String(value.schema_version)}`)
+  if (
+    !isObject(value.engine) ||
+    value.engine.name !== ENGINE_NAME ||
+    typeof value.engine.version !== 'string' ||
+    !value.engine.version.trim() ||
+    typeof value.engine.ruleset !== 'string' ||
+    !value.engine.ruleset.trim()
+  )
+    errors.push('engine name, version, and ruleset are required')
+  if (
+    !isObject(value.project) ||
+    !SHA256.test(String(value.project.input_hash)) ||
+    !isObject(value.project.input_hashes) ||
+    !Object.entries(value.project.input_hashes).every(([path, hash]) => validPath(path) && SHA256.test(String(hash))) ||
+    !(value.project.commit === null || (typeof value.project.commit === 'string' && value.project.commit.length > 0)) ||
+    !(value.project.dirty === null || typeof value.project.dirty === 'boolean')
+  )
+    errors.push('project commit, dirty state, input_hash, and input_hashes are required')
+  if (typeof value.generated_at !== 'string' || Number.isNaN(Date.parse(value.generated_at)))
+    errors.push('generated_at must be an ISO date')
+  if (Array.isArray(value.findings)) {
+    value.findings.forEach((finding, index) => {
+      if (!isObject(finding)) return errors.push(`findings[${index}] must be an object`)
+      if (!['deterministic', 'agent', 'external'].includes(String(finding.source)))
+        errors.push(`findings[${index}].source is invalid`)
+      if (!SEVERITIES.has(finding.severity as Severity)) errors.push(`findings[${index}].severity is invalid`)
+      if (!validLocation(finding.location)) errors.push(`findings[${index}].location is invalid`)
+      if (
+        typeof finding.title !== 'string' ||
+        !finding.title.trim() ||
+        typeof finding.message !== 'string' ||
+        !finding.message.trim() ||
+        !(finding.snippet === undefined || typeof finding.snippet === 'string') ||
+        typeof finding.fingerprint !== 'string' ||
+        !SHA256.test(finding.fingerprint) ||
+        typeof finding.suppressed !== 'boolean' ||
+        !isObject(finding.fix) ||
+        typeof finding.fix.automated !== 'boolean' ||
+        typeof finding.fix.description !== 'string' ||
+        !finding.fix.description.trim() ||
+        !(finding.fix.guide === undefined || typeof finding.fix.guide === 'string')
+      )
+        errors.push(`findings[${index}] title, message, fingerprint, fix, and suppression state are required`)
+      if (
+        finding.source === 'agent' &&
+        (typeof finding.check_id !== 'string' ||
+          !Number.isInteger(finding.check_version) ||
+          Number(finding.check_version) < 1 ||
+          typeof finding.prompt_hash !== 'string' ||
+          !SHA256.test(finding.prompt_hash))
+      )
+        errors.push(`findings[${index}] agent provenance is required`)
+      if (
+        finding.source !== 'agent' &&
+        (typeof finding.rule_id !== 'string' ||
+          !Number.isInteger(finding.rule_version) ||
+          Number(finding.rule_version) < 1)
+      )
+        errors.push(`findings[${index}] rule provenance is required`)
+      if (
+        !Array.isArray(finding.evidence) ||
+        finding.evidence.some(
+          (item) =>
+            !isObject(item) ||
+            !validLocation(item.location) ||
+            !(item.quote === undefined || typeof item.quote === 'string'),
+        )
+      )
+        errors.push(`findings[${index}].evidence is invalid`)
+      else if (
+        validLocation(finding.location) &&
+        typeof finding.message === 'string' &&
+        typeof finding.title === 'string' &&
+        isObject(finding.fix)
+      ) {
+        const core = {
+          source: finding.source as TraceFinding['source'],
+          ...(finding.source === 'agent'
+            ? {
+                check_id: finding.check_id as string,
+                check_version: finding.check_version as number,
+                prompt_hash: finding.prompt_hash as string,
+              }
+            : {
+                rule_id: finding.rule_id as string,
+                rule_version: finding.rule_version as number,
+              }),
+          severity: finding.severity as Severity,
+          title: finding.title,
+          message: finding.message,
+          location: finding.location as Location,
+          evidence: finding.evidence as unknown as FindingEvidence[],
+          ...(finding.snippet === undefined ? {} : {snippet: finding.snippet as string}),
+          fix: finding.fix as unknown as TraceFinding['fix'],
+        }
+        if (finding.fingerprint !== findingFingerprint(core)) errors.push(`findings[${index}].fingerprint mismatch`)
+      }
+    })
+  } else errors.push('findings must be an array')
+  if (Array.isArray(value.checks_executed)) {
+    value.checks_executed.forEach((execution, index) => {
+      if (
+        !isObject(execution) ||
+        typeof execution.id !== 'string' ||
+        !Number.isInteger(execution.version) ||
+        Number(execution.version) < 1 ||
+        !['rule', 'check', 'external'].includes(String(execution.kind)) ||
+        !['executed', 'skipped'].includes(String(execution.status)) ||
+        !Number.isInteger(execution.findings) ||
+        Number(execution.findings) < 0 ||
+        !(execution.reason === undefined || typeof execution.reason === 'string') ||
+        !(
+          execution.prompt_hash === undefined ||
+          (typeof execution.prompt_hash === 'string' && SHA256.test(execution.prompt_hash))
+        )
+      )
+        errors.push(`checks_executed[${index}] is invalid`)
+    })
+  } else errors.push('checks_executed must be an array')
+  if (Array.isArray(value.checks_executed) && Array.isArray(value.findings)) {
+    const executions: unknown[] = value.checks_executed
+    const traceFindings: unknown[] = value.findings
+    const executionKeys = new Set<string>()
+    executions.filter(isObject).forEach((execution, index) => {
+      const key = `${execution.kind}|${execution.id}`
+      if (executionKeys.has(key)) errors.push(`checks_executed[${index}] is duplicated`)
+      executionKeys.add(key)
+      let source: TraceFinding['source'] = 'external'
+      if (execution.kind === 'rule') source = 'deterministic'
+      else if (execution.kind === 'check') source = 'agent'
+      const actual = traceFindings.filter(
+        (finding) =>
+          isObject(finding) &&
+          finding.source === source &&
+          (source === 'agent' ? finding.check_id : finding.rule_id) === execution.id,
+      ).length
+      if (execution.findings !== actual) errors.push(`checks_executed[${index}].findings does not match findings`)
+      if (execution.status === 'skipped' && actual !== 0)
+        errors.push(`checks_executed[${index}] is skipped but has findings`)
+    })
+    traceFindings.filter(isObject).forEach((finding, index) => {
+      let kind = 'external'
+      if (finding.source === 'deterministic') kind = 'rule'
+      else if (finding.source === 'agent') kind = 'check'
+      const id = finding.source === 'agent' ? finding.check_id : finding.rule_id
+      const execution = executions.find(
+        (candidate) => isObject(candidate) && candidate.kind === kind && candidate.id === id,
+      )
+      if (!isObject(execution) || execution.status !== 'executed')
+        errors.push(`findings[${index}] has no executed check record`)
+    })
+  }
+  if (Array.isArray(value.suppressions)) {
+    value.suppressions.forEach((suppression, index) => {
+      if (validateSuppression(suppression)) errors.push(`suppressions[${index}] is invalid`)
+    })
+  } else errors.push('suppressions must be an array')
+  if (Array.isArray(value.findings) && Array.isArray(value.suppressions)) {
+    const findingFingerprints = new Set(value.findings.filter(isObject).map((finding) => finding.fingerprint))
+    const suppressionById = new Map(value.suppressions.filter(isObject).map((item) => [item.id, item]))
+    value.suppressions.filter(isObject).forEach((suppression, index) => {
+      if (!findingFingerprints.has(suppression.finding_fingerprint))
+        errors.push(`suppressions[${index}] targets an unknown finding`)
+    })
+    value.findings.filter(isObject).forEach((finding, index) => {
+      if (
+        finding.suppression !== undefined &&
+        (!isObject(finding.suppression) || !suppressionById.has(finding.suppression.id))
+      )
+        errors.push(`findings[${index}].suppression is not declared`)
+      else if (isObject(finding.suppression)) {
+        const declared = suppressionById.get(finding.suppression.id)
+        if (
+          isObject(declared) &&
+          (declared.finding_fingerprint !== finding.fingerprint ||
+            declared.justification !== finding.suppression.justification ||
+            canonicalJson(declared.provenance) !== canonicalJson(finding.suppression.provenance))
+        )
+          errors.push(`findings[${index}].suppression does not match its declaration`)
+      }
+      if ((finding.suppressed === true) !== (finding.suppression !== undefined))
+        errors.push(`findings[${index}].suppression state is inconsistent`)
+    })
+  }
+  if (
+    !isObject(value.coverage) ||
+    !Number.isInteger(value.coverage.files_scanned) ||
+    Number(value.coverage.files_scanned) < 0 ||
+    typeof value.coverage.complete !== 'boolean' ||
+    !Array.isArray(value.coverage.files_skipped) ||
+    value.coverage.files_skipped.some(
+      (file) =>
+        !isObject(file) ||
+        !validPath(file.path) ||
+        !['too_large', 'unreadable'].includes(String(file.reason)) ||
+        !(file.size_bytes === undefined || (Number.isInteger(file.size_bytes) && Number(file.size_bytes) >= 0)) ||
+        !(file.detail === undefined || typeof file.detail === 'string'),
+    ) ||
+    value.coverage.complete !== (value.coverage.files_skipped.length === 0)
+  )
+    errors.push('coverage is invalid')
+  if (inspection.containsSecret) errors.push('trace contains an unredacted matched secret')
+  if (
+    !isObject(value.attestation) ||
+    value.attestation.signed !== false ||
+    !SHA256.test(String(value.attestation.digest))
+  )
+    errors.push('attestation must contain a SHA-256 digest and signed:false')
+  else {
+    const {attestation: _attestation, ...unsigned} = value
+    const expected = sha256(unsigned)
+    if (value.attestation.digest !== expected) errors.push('attestation digest mismatch')
+  }
+  return {valid: errors.length === 0, errors}
+}
+
+export function validateTrace(value: unknown): TraceValidationResult {
+  try {
+    return validateTraceValue(value)
+    // The public validation boundary must fail closed for all malformed input.
+    // eslint-disable-next-line no-catch-all/no-catch-all
+  } catch (error) {
+    return {
+      valid: false,
+      errors: [`trace validation failed safely: ${error instanceof Error ? error.message : String(error)}`],
+    }
+  }
+}
+
+export function assertCompatibleTrace(value: unknown): asserts value is TraceV1 {
+  const validation = validateTrace(value)
+  if (!validation.valid) throw new Error(`Invalid App Doctor trace: ${validation.errors.join('; ')}`)
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/types.ts b/packages/app/src/cli/services/app-doctor-engine/types.ts
new file mode 100644
index 00000000000..33f59403029
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/types.ts
@@ -0,0 +1,240 @@
+/**
+ * A single security finding produced by a rule.
+ */
+export interface Issue {
+  /** Stable rule identifier, e.g. "DEPRECATED_SCRIPT_TAG_SCOPE" */
+  id: string
+  /** "critical" | "high" | "medium" | "low" */
+  severity: Severity
+  /** Points deducted from the baseline score */
+  points: number
+  /** Short human-readable headline */
+  title: string
+  /** Longer explanation of what was found */
+  message: string
+  /** Where the issue was found */
+  location: Location
+  /** Code snippet (optional) */
+  snippet?: string
+  /** How to fix it */
+  fix: Fix
+  /** Confidence level: "definite" affects the score; others are advisory */
+  confidence?: Confidence
+  /**
+   * Who found this issue. "static" = a deterministic rule; "agent" = an
+   * agentic check prompt. Agentic findings carry the check version and prompt
+   * hash so a verdict is traceable to the exact wording that produced it.
+   */
+  found_by?: 'static' | 'agent' | 'external'
+  /** Version of the deterministic rule or external producer rule. */
+  rule_version?: number
+  /** Redacted citations supporting an agent or external finding. */
+  evidence?: FindingEvidence[]
+  /** Which agentic check found this (agent findings only). */
+  check_version?: number
+  prompt_hash?: string
+  /** The agent's stated confidence in its own finding. */
+  agent_confidence?: 'high' | 'medium' | 'low'
+  /** The agent's reasoning for why this is a real issue. */
+  agent_reasoning?: string
+  /**
+   * How the rule established this finding — e.g. the git commands consulted
+   * and their verdicts. Lets a reviewer see WHY a severity was chosen rather
+   * than taking the rule's word for it, and makes fail-closed decisions
+   * ("could not determine, treated as exposed") visible in the trace.
+   */
+  detection_evidence?: string[]
+}
+
+export type Severity = 'critical' | 'high' | 'medium' | 'low'
+
+/**
+ * Confidence level for a finding.
+ * - "definite": a deterministic rule matched a provable pattern. Affects the score.
+ * - "needs_review": heuristic or context-dependent. Used internally by rules that
+ *   have mixed definite/needs_review paths. Filtered out of the trace by scan().
+ * - "agentic": found by an agent running a semantic check prompt. Advisory
+ *   until a human or Shopify confirms, but carries more weight than a
+ *   heuristic guess because the agent read the surrounding code.
+ * Defaults to "definite" when omitted for backward compatibility.
+ */
+export type Confidence = 'definite' | 'needs_review' | 'agentic'
+
+export interface Location {
+  /** Project-relative file path */
+  file: string
+  /** 1-indexed line number (optional for config-level checks) */
+  line?: number
+  /** 1-indexed column number */
+  column?: number
+}
+
+export interface Fix {
+  /** Can this be fixed automatically? */
+  automated: boolean
+  /** URL to documentation for manual fix */
+  guide?: string
+  /** Short text description of the fix */
+  description: string
+}
+
+/**
+ * What the app does — auto-detected to skip irrelevant checks.
+ */
+export interface Capabilities {
+  theme_app_extension: boolean
+  app_embed: boolean
+  script_tags: boolean
+  webhooks: boolean
+  app_proxy: boolean
+  storefront_metafield_writes: boolean
+  has_backend: boolean
+  declared_ip_allowlist: boolean
+  checkout_extension: boolean
+}
+
+/**
+ * The full scan result.
+ */
+export interface ScanResult {
+  version: string
+  timestamp: string
+  /** Best-effort local git identity. null means unavailable, never "clean". */
+  project: {
+    commit: string | null
+    dirty: boolean | null
+  }
+  app: {
+    name: string
+    type: string
+  }
+  capabilities: Capabilities
+  score: ScoreResult
+  scan: ScanMetadata
+  issues: Issue[]
+}
+
+export interface ScoreResult {
+  total: number
+  baseline: number
+  grade: Grade
+}
+
+export type Grade = 'EXCELLENT' | 'GOOD' | 'NEEDS_WORK' | 'CRITICAL'
+
+/**
+ * A file that was discovered but never analyzed. Recorded explicitly because
+ * an unscanned file is not a clean file, and a reviewer reading the trace must
+ * be able to tell the difference.
+ */
+export interface SkippedFile {
+  path: string
+  reason: 'too_large' | 'unreadable'
+  size_bytes?: number
+  detail?: string
+}
+
+export interface ScanMetadata {
+  timestamp: string
+  doctor_version: string
+  files_scanned: number
+  rules_run: number
+  rules_skipped: number
+  /** Files discovered but not analyzed. Non-zero means coverage is incomplete. */
+  files_skipped_count: number
+  /** Detail for each skipped file, present only when some were skipped. */
+  files_skipped?: SkippedFile[]
+  /** SHA-256 of concatenated file content hashes — lets platform verify what was scanned */
+  input_hash: string
+  /** SHA-256 of canonical issues+score JSON — lets platform verify output integrity */
+  result_hash: string
+  /** Per-file SHA-256, keyed by project-relative path. Enables staleness detection. */
+  file_hashes?: Record<string, string>
+  /** Deterministic checks attempted, including checks that found nothing. */
+  checks_executed?: CheckExecution[]
+}
+
+export const TRACE_SCHEMA_VERSION = 1 as const
+export const SUPPORTED_TRACE_SCHEMA_VERSIONS = [TRACE_SCHEMA_VERSION] as const
+export const ENGINE_NAME = 'shopify-app-doctor' as const
+
+export type FindingSource = 'deterministic' | 'agent' | 'external'
+
+export interface FindingEvidence {
+  location: Location
+  quote?: string
+}
+
+export interface CheckExecution {
+  id: string
+  version: number
+  kind: 'rule' | 'check' | 'external'
+  status: 'executed' | 'skipped'
+  findings: number
+  prompt_hash?: string
+  reason?: string
+}
+
+export interface SuppressionProvenance {
+  source: 'human' | 'policy' | 'external'
+  actor?: string
+  created_at: string
+}
+
+export interface Suppression {
+  id: string
+  finding_fingerprint: string
+  justification: string
+  provenance: SuppressionProvenance
+}
+
+export interface TraceFinding {
+  fingerprint: string
+  source: FindingSource
+  rule_id?: string
+  rule_version?: number
+  check_id?: string
+  check_version?: number
+  prompt_hash?: string
+  severity: Severity
+  title: string
+  message: string
+  location: Location
+  evidence: FindingEvidence[]
+  snippet?: string
+  fix: Fix
+  suppressed: boolean
+  suppression?: {
+    id: string
+    justification: string
+    provenance: SuppressionProvenance
+  }
+}
+
+export interface TraceV1 {
+  schema_version: typeof TRACE_SCHEMA_VERSION
+  engine: {
+    name: typeof ENGINE_NAME
+    version: string
+    ruleset: string
+  }
+  generated_at: string
+  project: {
+    commit: string | null
+    dirty: boolean | null
+    input_hash: string
+    input_hashes: Record<string, string>
+  }
+  findings: TraceFinding[]
+  checks_executed: CheckExecution[]
+  suppressions: Suppression[]
+  coverage: {
+    files_scanned: number
+    files_skipped: SkippedFile[]
+    complete: boolean
+  }
+  attestation: {
+    digest: string
+    signed: false
+  }
+}
diff --git a/packages/app/src/cli/services/app-doctor-engine/version.ts b/packages/app/src/cli/services/app-doctor-engine/version.ts
new file mode 100644
index 00000000000..f2f7060c930
--- /dev/null
+++ b/packages/app/src/cli/services/app-doctor-engine/version.ts
@@ -0,0 +1,5 @@
+import {CLI_KIT_VERSION} from '@shopify/cli-kit/common/version'
+
+export function getEngineVersion(): string {
+  return CLI_KIT_VERSION
+}
diff --git a/packages/app/src/cli/services/doctor.test.ts b/packages/app/src/cli/services/doctor.test.ts
new file mode 100644
index 00000000000..aed1da2b001
--- /dev/null
+++ b/packages/app/src/cli/services/doctor.test.ts
@@ -0,0 +1,146 @@
+import doctor, {appDoctorSkillInstructionsPrompt, formatDoctorOutput} from './doctor.js'
+import {describe, expect, test, vi} from 'vitest'
+import type {AppDoctorRunOptions, AppDoctorRunResult} from './app-doctor-api.js'
+
+const engineResult: AppDoctorRunResult = {
+  output: 'No security issues found.',
+  engine: {
+    name: 'shopify-app-doctor',
+    version: '1.2.3',
+    ruleset: '2026.08.28',
+  },
+  exitCode: 0,
+}
+
+function testDependencies(result: AppDoctorRunResult = engineResult) {
+  return {
+    runEngine: vi.fn(async (_options: AppDoctorRunOptions) => result),
+    canPrompt: vi.fn(() => false),
+    confirmShowSkillInstructions: vi.fn(async () => false),
+    output: vi.fn(),
+    setExitCode: vi.fn(),
+  }
+}
+
+function testOptions() {
+  return {
+    directory: '/tmp/unlinked-app',
+    json: false,
+    verbose: false,
+    blocking: 'none' as const,
+    yes: false,
+    skipSkill: false,
+  }
+}
+
+describe('doctor', () => {
+  test('forwards scan options to the in-tree engine and reports engine versions', async () => {
+    const dependencies = testDependencies()
+
+    await doctor({...testOptions(), verbose: true, blocking: 'high'}, dependencies)
+
+    expect(dependencies.runEngine).toHaveBeenCalledWith({
+      directory: '/tmp/unlinked-app',
+      format: 'human',
+      verbose: true,
+      blocking: 'high',
+      findingsPath: undefined,
+    })
+    expect(dependencies.output).toHaveBeenCalledWith(
+      'No security issues found.\n\nEngine: shopify-app-doctor 1.2.3\nRuleset: 2026.08.28',
+    )
+  })
+
+  test('preserves the JSON report and includes engine and ruleset versions', async () => {
+    const dependencies = testDependencies({
+      ...engineResult,
+      output: JSON.stringify({schema_version: 1, findings: []}),
+    })
+
+    await doctor({...testOptions(), json: true, yes: true}, dependencies)
+
+    expect(dependencies.runEngine).toHaveBeenCalledWith(expect.objectContaining({format: 'json'}))
+    expect(JSON.parse(dependencies.output.mock.calls[0]![0])).toEqual({
+      schema_version: 1,
+      findings: [],
+      engine: engineResult.engine,
+    })
+    expect(dependencies.canPrompt).not.toHaveBeenCalled()
+    expect(dependencies.confirmShowSkillInstructions).not.toHaveBeenCalled()
+    expect(dependencies.output).toHaveBeenCalledTimes(1)
+  })
+
+  test('does not offer skill instructions in CI or another non-interactive environment', async () => {
+    const dependencies = testDependencies()
+
+    await doctor(testOptions(), dependencies)
+
+    expect(dependencies.canPrompt).toHaveBeenCalledOnce()
+    expect(dependencies.confirmShowSkillInstructions).not.toHaveBeenCalled()
+    expect(dependencies.output).toHaveBeenCalledTimes(1)
+  })
+
+  test('offers to show skill setup instructions without claiming it will perform setup', async () => {
+    const dependencies = testDependencies()
+    dependencies.canPrompt.mockReturnValue(true)
+    dependencies.confirmShowSkillInstructions.mockResolvedValue(true)
+
+    await doctor(testOptions(), dependencies)
+
+    expect(appDoctorSkillInstructionsPrompt).toEqual({
+      message: 'Show setup instructions for the Shopify App Doctor skill?',
+      confirmationMessage: 'Yes, show instructions',
+      cancellationMessage: 'No, skip instructions',
+      defaultValue: false,
+    })
+    expect(dependencies.confirmShowSkillInstructions).toHaveBeenCalledOnce()
+    expect(dependencies.output).toHaveBeenCalledTimes(2)
+    expect(dependencies.output.mock.calls[1]![0]).toContain('Shopify App Doctor skill setup instructions')
+    expect(dependencies.output.mock.calls[1]![0]).toContain('engine 1.2.3 (ruleset 2026.08.28)')
+    expect(dependencies.output.mock.calls[1]![0]).toContain("Shopify CLI didn't install or change")
+  })
+
+  test('--yes shows instructions without prompting or claiming setup occurred, including in CI', async () => {
+    const dependencies = testDependencies()
+
+    await doctor({...testOptions(), yes: true}, dependencies)
+
+    expect(dependencies.canPrompt).not.toHaveBeenCalled()
+    expect(dependencies.confirmShowSkillInstructions).not.toHaveBeenCalled()
+    expect(dependencies.output).toHaveBeenCalledTimes(2)
+    expect(dependencies.output.mock.calls[1]![0]).toContain('instructions only')
+  })
+
+  test('--skip-skill never offers instructions', async () => {
+    const dependencies = testDependencies()
+    dependencies.canPrompt.mockReturnValue(true)
+
+    await doctor({...testOptions(), skipSkill: true}, dependencies)
+
+    expect(dependencies.canPrompt).not.toHaveBeenCalled()
+    expect(dependencies.confirmShowSkillInstructions).not.toHaveBeenCalled()
+    expect(dependencies.output).toHaveBeenCalledTimes(1)
+  })
+
+  test('uses the engine exit code for blocking findings', async () => {
+    const dependencies = testDependencies({...engineResult, exitCode: 1})
+
+    await doctor(testOptions(), dependencies)
+
+    expect(dependencies.setExitCode).toHaveBeenCalledWith(1)
+  })
+})
+
+describe('formatDoctorOutput', () => {
+  test('keeps existing JSON engine fields while applying authoritative version metadata', () => {
+    const output = formatDoctorOutput(
+      {
+        ...engineResult,
+        output: JSON.stringify({engine: {commit: 'abc123'}, findings: []}),
+      },
+      true,
+    )
+
+    expect(JSON.parse(output).engine).toEqual({...engineResult.engine, commit: 'abc123'})
+  })
+})
diff --git a/packages/app/src/cli/services/doctor.ts b/packages/app/src/cli/services/doctor.ts
new file mode 100644
index 00000000000..147366ac35d
--- /dev/null
+++ b/packages/app/src/cli/services/doctor.ts
@@ -0,0 +1,102 @@
+import {runAppDoctor} from './app-doctor-api.js'
+import {outputResult} from '@shopify/cli-kit/node/output'
+import {terminalSupportsPrompting} from '@shopify/cli-kit/node/system'
+import {renderConfirmationPrompt} from '@shopify/cli-kit/node/ui'
+import type {
+  AppDoctorBlockingLevel,
+  AppDoctorEngineMetadata,
+  AppDoctorRunOptions,
+  AppDoctorRunResult,
+} from './app-doctor-api.js'
+
+export interface DoctorOptions {
+  directory: string
+  json: boolean
+  verbose: boolean
+  blocking: AppDoctorBlockingLevel
+  yes: boolean
+  skipSkill: boolean
+  findingsPath?: string
+}
+
+interface DoctorDependencies {
+  runEngine(options: AppDoctorRunOptions): Promise<AppDoctorRunResult>
+  canPrompt(): boolean
+  confirmShowSkillInstructions(): Promise<boolean>
+  output(content: string): void
+  setExitCode(exitCode: number): void
+}
+
+export const appDoctorSkillInstructionsPrompt = {
+  message: 'Show setup instructions for the Shopify App Doctor skill?',
+  confirmationMessage: 'Yes, show instructions',
+  cancellationMessage: 'No, skip instructions',
+  defaultValue: false,
+} as const
+
+const defaultDependencies: DoctorDependencies = {
+  runEngine: runAppDoctor,
+  canPrompt: terminalSupportsPrompting,
+  confirmShowSkillInstructions: () => renderConfirmationPrompt(appDoctorSkillInstructionsPrompt),
+  output: outputResult,
+  setExitCode: (exitCode) => {
+    process.exitCode = exitCode
+  },
+}
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function formatDoctorOutput(result: AppDoctorRunResult, json: boolean): string {
+  if (!json) {
+    return `${result.output.trimEnd()}\n\nEngine: ${result.engine.name} ${result.engine.version}\nRuleset: ${result.engine.ruleset}`
+  }
+
+  const report: unknown = JSON.parse(result.output)
+  const reportWithEngine = isJsonObject(report)
+    ? {...report, engine: {...(isJsonObject(report.engine) ? report.engine : {}), ...result.engine}}
+    : {engine: result.engine, result: report}
+
+  return JSON.stringify(reportWithEngine, null, 2)
+}
+
+function skillSetupInstructions(engine: AppDoctorEngineMetadata): string {
+  return [
+    'Shopify App Doctor skill setup instructions',
+    '',
+    'Follow the Shopify AI Toolkit setup guide for your coding agent, then enable the shopify-app-doctor skill:',
+    'https://github.com/Shopify/Shopify-AI-Toolkit',
+    '',
+    `Use a skill compatible with App Doctor engine ${engine.version} (ruleset ${engine.ruleset}).`,
+    "These are instructions only; Shopify CLI didn't install or change your coding-agent configuration.",
+  ].join('\n')
+}
+
+async function shouldShowSkillInstructions(options: DoctorOptions, dependencies: DoctorDependencies): Promise<boolean> {
+  if (options.json || options.skipSkill) return false
+  if (options.yes) return true
+  if (!dependencies.canPrompt()) return false
+  return dependencies.confirmShowSkillInstructions()
+}
+
+export default async function doctor(
+  options: DoctorOptions,
+  dependencies: DoctorDependencies = defaultDependencies,
+): Promise<void> {
+  const result = await dependencies.runEngine({
+    directory: options.directory,
+    format: options.json ? 'json' : 'human',
+    verbose: options.verbose,
+    blocking: options.blocking,
+    findingsPath: options.findingsPath,
+  })
+
+  dependencies.output(formatDoctorOutput(result, options.json))
+
+  if (await shouldShowSkillInstructions(options, dependencies)) {
+    dependencies.output(skillSetupInstructions(result.engine))
+  }
+
+  if (result.exitCode !== 0) dependencies.setExitCode(result.exitCode)
+}
diff --git a/packages/cli/oclif.manifest.json b/packages/cli/oclif.manifest.json
index fa36d024fb8..9d34e3292c0 100644
--- a/packages/cli/oclif.manifest.json
+++ b/packages/cli/oclif.manifest.json
@@ -1303,6 +1303,98 @@
       "strict": true,
       "summary": "Cleans up the dev preview from the selected store."
     },
+    "app:doctor:scan": {
+      "aliases": [],
+      "args": {
+        "directory": {
+          "description": "The app directory to check. Defaults to the current directory.",
+          "name": "directory"
+        }
+      },
+      "description": "Runs Shopify App Doctor locally and creates its review pack and trace.\n\nPass `--findings` after completing the review pack to validate agent findings and compile them into the trace. In CI and other non-interactive environments, skill setup instructions aren't offered unless you pass `--yes`. JSON output never prompts or prints those instructions. Shopify CLI only shows instructions; it doesn't install or configure the skill.",
+      "flags": {
+        "no-color": {
+          "description": "Disable color output.",
+          "env": "SHOPIFY_FLAG_NO_COLOR",
+          "hidden": false,
+          "name": "no-color",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Increase the verbosity of the output. May include sensitive data.",
+          "env": "SHOPIFY_FLAG_VERBOSE",
+          "hidden": false,
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "json": {
+          "char": "j",
+          "description": "Output the result as JSON. Automatically disables color output.",
+          "env": "SHOPIFY_FLAG_JSON",
+          "hidden": false,
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "findings": {
+          "description": "Validate agent findings from a JSON file and compile them into the trace.",
+          "env": "SHOPIFY_FLAG_APP_DOCTOR_FINDINGS",
+          "name": "findings",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "blocking": {
+          "description": "The minimum finding severity that causes a non-zero exit code.",
+          "env": "SHOPIFY_FLAG_APP_DOCTOR_BLOCKING",
+          "name": "blocking",
+          "default": "none",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "critical",
+            "high",
+            "medium",
+            "low",
+            "none"
+          ],
+          "type": "option"
+        },
+        "yes": {
+          "description": "Show optional App Doctor skill setup instructions without prompting.",
+          "env": "SHOPIFY_FLAG_YES",
+          "exclusive": [
+            "skip-skill"
+          ],
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "skip-skill": {
+          "description": "Don't offer App Doctor skill setup instructions.",
+          "env": "SHOPIFY_FLAG_SKIP_SKILL",
+          "exclusive": [
+            "yes"
+          ],
+          "name": "skip-skill",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "app:doctor:scan",
+      "pluginAlias": "@shopify/cli",
+      "pluginName": "@shopify/cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Check an app for Shopify-specific security issues.",
+      "enableJsonFlag": false,
+      "descriptionWithMarkdown": "Runs Shopify App Doctor locally and creates its review pack and trace.\n\nPass `--findings` after completing the review pack to validate agent findings and compile them into the trace. In CI and other non-interactive environments, skill setup instructions aren't offered unless you pass `--yes`. JSON output never prompts or prints those instructions. Shopify CLI only shows instructions; it doesn't install or configure the skill.",
+      "customPluginName": "@shopify/app"
+    },
     "app:env:pull": {
       "aliases": [
       ],
diff --git a/packages/cli/src/app-doctor-registration.test.ts b/packages/cli/src/app-doctor-registration.test.ts
new file mode 100644
index 00000000000..6fb1f0bd075
--- /dev/null
+++ b/packages/cli/src/app-doctor-registration.test.ts
@@ -0,0 +1,9 @@
+import {COMMANDS} from './index.js'
+import {describe, expect, test} from 'vitest'
+
+describe('@shopify/cli command registration', () => {
+  test('exposes app:doctor:scan from @shopify/app', () => {
+    expect(COMMANDS['app:doctor:scan']).toBeDefined()
+    expect(COMMANDS['app:doctor:scan'].customPluginName).toBe('@shopify/app')
+  })
+})
diff --git a/packages/e2e/data/snapshots/commands.txt b/packages/e2e/data/snapshots/commands.txt
index 488d7481cb0..358b206fc43 100644
--- a/packages/e2e/data/snapshots/commands.txt
+++ b/packages/e2e/data/snapshots/commands.txt
@@ -12,6 +12,8 @@
 │  ├─ deploy
 │  ├─ dev
 │  │  └─ clean
+│  ├─ doctor
+│  │  └─ scan
 │  ├─ env
 │  │  ├─ pull
 │  │  └─ show
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 402a85d6031..b8bea202853 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -167,6 +167,9 @@ importers:
       '@graphql-typed-document-node/core':
         specifier: 3.2.0
         version: 3.2.0(graphql@16.14.2)
+      '@iarna/toml':
+        specifier: 2.2.5
+        version: 2.2.5
       '@luckycatfactory/esbuild-graphql-loader':
         specifier: 3.8.1
         version: 3.8.1(esbuild@0.28.1)(graphql-tag@2.12.7(graphql@16.14.2))(graphql@16.14.2)
@@ -191,6 +194,12 @@ importers:
       '@shopify/toml-patch':
         specifier: 0.3.0
         version: 0.3.0
+      acorn:
+        specifier: 8.17.0
+        version: 8.17.0
+      acorn-walk:
+        specifier: 8.3.5
+        version: 8.3.5
       chokidar:
         specifier: 3.6.0
         version: 3.6.0
@@ -200,6 +209,9 @@ importers:
       esbuild:
         specifier: 0.28.1
         version: 0.28.1
+      fast-glob:
+        specifier: 3.3.3
+        version: 3.3.3
       graphql-request:
         specifier: 6.1.0
         version: 6.1.0(graphql@16.14.2)
@@ -569,7 +581,7 @@ importers:
         version: 8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)
       '@vitest/eslint-plugin':
         specifier: 1.1.44
-        version: 1.1.44(@typescript-eslint/utils@8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7)(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)))
+        version: 1.1.44(@typescript-eslint/utils@8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7(vitest@4.1.10))(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)))
       eslint:
         specifier: ^9.0.0
         version: 9.39.5(jiti@2.6.1)
@@ -3759,6 +3771,7 @@ packages:
   '@shopify/polaris@12.27.0':
     resolution: {integrity: sha512-Y8yus6iEjcfW2ZtEJtlqxbWeDJqTX3S/MOLH4GWRvU5gFYJQhlaHaETs0+OimbhEpO95mXbY8qB+KnIJaVBHwA==, tarball: https://registry.npmjs.org/@shopify/polaris/-/polaris-12.27.0.tgz}
     engines: {node: ^16.17.0 || >=18.12.0}
+    deprecated: 'Polaris React is deprecated and no longer maintained. For building Shopify admin experiences, use Polaris web components: https://shopify.dev/docs/api/polaris — archived docs for this package: https://shopify.github.io/polaris-react-archive/'
     peerDependencies:
       react: ^18.0.0
       react-dom: ^18.0.0
@@ -4308,11 +4321,6 @@ packages:
     resolution: {integrity: sha512-HEHNfbars9v4pgpW6SO1KSPkfoS0xVOM/9UzkJltjlsHZmJasxg8aXkuZa7SMf8vKGIBhpUsPluQSqhJFCqebw==, tarball: https://registry.npmjs.org/acorn-walk/-/acorn-walk-8.3.5.tgz}
     engines: {node: '>=0.4.0'}
 
-  acorn@8.16.0:
-    resolution: {integrity: sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==, tarball: https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz}
-    engines: {node: '>=0.4.0'}
-    hasBin: true
-
   acorn@8.17.0:
     resolution: {integrity: sha512-xRQbDb9BnwDafYNn6Vwl839DYVjqXYb1XVGtWAZ1kcDc6iwAL4hg3B1dZlRiuENFeO2H53gFG3in621AdERVAg==, tarball: https://registry.npmjs.org/acorn/-/acorn-8.17.0.tgz}
     engines: {node: '>=0.4.0'}
@@ -5559,6 +5567,7 @@ packages:
   eslint@9.39.5:
     resolution: {integrity: sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==, tarball: https://registry.npmjs.org/eslint/-/eslint-9.39.5.tgz}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    deprecated: This version is no longer supported. Please see https://eslint.org/version-support for other options.
     hasBin: true
     peerDependencies:
       jiti: '*'
@@ -13081,17 +13090,17 @@ snapshots:
       magicast: 0.3.5
       test-exclude: 7.0.2
       tinyrainbow: 2.0.0
-      vitest: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7)(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0))
+      vitest: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7(vitest@4.1.10))(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0))
     transitivePeerDependencies:
       - supports-color
 
-  '@vitest/eslint-plugin@1.1.44(@typescript-eslint/utils@8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7)(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)))':
+  '@vitest/eslint-plugin@1.1.44(@typescript-eslint/utils@8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7(vitest@4.1.10))(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)))':
     dependencies:
       '@typescript-eslint/utils': 8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)
       eslint: 9.39.5(jiti@2.6.1)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7)(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0))
+      vitest: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7(vitest@4.1.10))(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0))
 
   '@vitest/eslint-plugin@1.1.44(@typescript-eslint/utils@8.56.1(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3))(eslint@9.39.5(jiti@2.6.1))(typescript@5.9.3)(vitest@4.1.10)':
     dependencies:
@@ -13191,8 +13200,6 @@ snapshots:
     dependencies:
       acorn: 8.17.0
 
-  acorn@8.16.0: {}
-
   acorn@8.17.0: {}
 
   address@2.0.3: {}
@@ -17798,7 +17805,7 @@ snapshots:
       '@tsconfig/node14': 1.0.3
       '@tsconfig/node16': 1.0.4
       '@types/node': 22.20.1
-      acorn: 8.16.0
+      acorn: 8.17.0
       acorn-walk: 8.3.5
       arg: 4.1.3
       create-require: 1.1.1
@@ -18104,7 +18111,7 @@ snapshots:
     transitivePeerDependencies:
       - msw
 
-  vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7)(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)):
+  vitest@4.1.10(@opentelemetry/api@1.9.1)(@types/node@26.1.1)(@vitest/coverage-istanbul@3.2.7(vitest@4.1.10))(jsdom@28.1.0)(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0)):
     dependencies:
       '@vitest/expect': 4.1.10
       '@vitest/mocker': 4.1.10(msw@2.15.0(@types/node@26.1.1)(typescript@5.9.3))(vite@6.4.3(@types/node@26.1.1)(jiti@2.6.1)(sass@1.100.0)(tsx@4.23.1)(yaml@2.9.0))