From 0b7ec75a7554062a6f0cdcf74c5e25fe9e4153c2 Mon Sep 17 00:00:00 2001
From: Arber Xhindoli <14798762+arberx@users.noreply.github.com>
Date: Sun, 29 Mar 2026 23:07:05 -0500
Subject: [PATCH] feat: add snapshot report command

---
 package.json                                  |   2 +-
 packages/api-routes/src/index.ts              |   7 +
 packages/api-routes/src/openapi.ts            |  28 +
 packages/api-routes/src/snapshot.ts           |  41 +
 packages/api-routes/test/snapshot.test.ts     | 152 ++++
 packages/canonry/package.json                 |  16 +-
 packages/canonry/src/cli-commands.ts          |   2 +
 packages/canonry/src/cli-commands/snapshot.ts |  46 +
 packages/canonry/src/cli.ts                   |   4 +
 packages/canonry/src/client.ts                |  10 +
 packages/canonry/src/commands/snapshot.ts     | 109 +++
 packages/canonry/src/server.ts                |   5 +
 packages/canonry/src/snapshot-format.ts       |   5 +
 packages/canonry/src/snapshot-pdf.ts          | 377 ++++++++
 packages/canonry/src/snapshot-service.ts      | 853 ++++++++++++++++++
 .../canonry/test/snapshot-command.test.ts     | 210 +++++
 .../canonry/test/snapshot-service.test.ts     | 210 +++++
 packages/contracts/src/index.ts               |   1 +
 packages/contracts/src/snapshot.ts            | 113 +++
 pnpm-lock.yaml                                |  48 +-
 .../canonry-setup/references/canonry-cli.md   |   6 +
 21 files changed, 2230 insertions(+), 15 deletions(-)
 create mode 100644 packages/api-routes/src/snapshot.ts
 create mode 100644 packages/api-routes/test/snapshot.test.ts
 create mode 100644 packages/canonry/src/cli-commands/snapshot.ts
 create mode 100644 packages/canonry/src/commands/snapshot.ts
 create mode 100644 packages/canonry/src/snapshot-format.ts
 create mode 100644 packages/canonry/src/snapshot-pdf.ts
 create mode 100644 packages/canonry/src/snapshot-service.ts
 create mode 100644 packages/canonry/test/snapshot-command.test.ts
 create mode 100644 packages/canonry/test/snapshot-service.test.ts
 create mode 100644 packages/contracts/src/snapshot.ts

diff --git a/package.json b/package.json
index a231b0b..734edf3 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "canonry",
   "private": true,
-  "version": "1.28.2",
+  "version": "1.29.0",
   "type": "module",
   "packageManager": "pnpm@10.28.2",
   "scripts": {
diff --git a/packages/api-routes/src/index.ts b/packages/api-routes/src/index.ts
index 7e2177a..0dc8c42 100644
--- a/packages/api-routes/src/index.ts
+++ b/packages/api-routes/src/index.ts
@@ -17,6 +17,8 @@ import { openApiRoutes } from './openapi.js'
 import type { OpenApiInfo } from './openapi.js'
 import { settingsRoutes } from './settings.js'
 import type { SettingsRoutesOptions, ProviderSummaryEntry, ProviderAdapterInfo } from './settings.js'
+import { snapshotRoutes } from './snapshot.js'
+import type { SnapshotRoutesOptions } from './snapshot.js'
 import { telemetryRoutes } from './telemetry.js'
 import type { TelemetryRoutesOptions } from './telemetry.js'
 import { scheduleRoutes } from './schedules.js'
@@ -63,6 +65,8 @@ export interface ApiRoutesOptions {
   onScheduleUpdated?: (action: 'upsert' | 'delete', projectId: string) => void
   /** Callback when a project is deleted */
   onProjectDeleted?: (projectId: string) => void
+  /** Callback to generate a one-shot AI perception snapshot */
+  onSnapshotRequested?: SnapshotRoutesOptions['onSnapshotRequested']
   /** Callback to generate keyword suggestions using an LLM provider */
   onGenerateKeywords?: KeywordRoutesOptions['onGenerateKeywords']
   /** Telemetry status/toggle callbacks */
@@ -185,6 +189,9 @@ export async function apiRoutes(app: FastifyInstance, opts: ApiRoutesOptions) {
       bing: opts.bingSettingsSummary,
       onBingUpdate: opts.onBingSettingsUpdate,
     } satisfies SettingsRoutesOptions)
+    await api.register(snapshotRoutes, {
+      onSnapshotRequested: opts.onSnapshotRequested,
+    } satisfies SnapshotRoutesOptions)
     await api.register(scheduleRoutes, {
       onScheduleUpdated: opts.onScheduleUpdated,
       validProviderNames: opts.providerAdapters?.map(a => a.name),
diff --git a/packages/api-routes/src/openapi.ts b/packages/api-routes/src/openapi.ts
index 4e7a0f1..bcbadd4 100644
--- a/packages/api-routes/src/openapi.ts
+++ b/packages/api-routes/src/openapi.ts
@@ -736,6 +736,34 @@ const routeCatalog: OpenApiOperation[] = [
       501: { description: 'Google settings updates are not supported.' },
     },
   },
+  {
+    method: 'post',
+    path: '/api/v1/snapshot',
+    summary: 'Generate a one-shot AI perception snapshot',
+    tags: ['snapshot'],
+    requestBody: {
+      required: true,
+      content: {
+        'application/json': {
+          schema: {
+            type: 'object',
+            required: ['companyName', 'domain'],
+            properties: {
+              companyName: stringSchema,
+              domain: stringSchema,
+              phrases: stringArraySchema,
+              competitors: stringArraySchema,
+            },
+          },
+        },
+      },
+    },
+    responses: {
+      200: { description: 'Snapshot report returned.' },
+      400: { description: 'Invalid snapshot input.' },
+      501: { description: 'Snapshot reporting is not supported.' },
+    },
+  },
   {
     method: 'put',
     path: '/api/v1/settings/bing',
diff --git a/packages/api-routes/src/snapshot.ts b/packages/api-routes/src/snapshot.ts
new file mode 100644
index 0000000..700b752
--- /dev/null
+++ b/packages/api-routes/src/snapshot.ts
@@ -0,0 +1,41 @@
+import type { FastifyInstance } from 'fastify'
+import { notImplemented, snapshotRequestSchema, validationError, type SnapshotReportDto, type SnapshotRequestDto } from '@ainyc/canonry-contracts'
+
+export interface SnapshotRoutesOptions {
+  onSnapshotRequested?: (input: SnapshotRequestDto) => Promise<SnapshotReportDto>
+}
+
+export async function snapshotRoutes(app: FastifyInstance, opts: SnapshotRoutesOptions) {
+  app.post<{
+    Body: SnapshotRequestDto
+  }>('/snapshot', async (request, reply) => {
+    const parsed = snapshotRequestSchema.safeParse(request.body)
+    if (!parsed.success) {
+      const err = validationError('Invalid snapshot payload', {
+        issues: parsed.error.issues.map(issue => ({
+          path: issue.path.join('.'),
+          message: issue.message,
+        })),
+      })
+      return reply.status(err.statusCode).send(err.toJSON())
+    }
+
+    if (!opts.onSnapshotRequested) {
+      const err = notImplemented('Snapshot reporting is not supported in this deployment')
+      return reply.status(err.statusCode).send(err.toJSON())
+    }
+
+    try {
+      const report = await opts.onSnapshotRequested(parsed.data)
+      return reply.send(report)
+    } catch (err) {
+      request.log.error({ err }, 'Snapshot report generation failed')
+      return reply.status(500).send({
+        error: {
+          code: 'INTERNAL_ERROR',
+          message: err instanceof Error ? err.message : 'Failed to generate snapshot report',
+        },
+      })
+    }
+  })
+}
diff --git a/packages/api-routes/test/snapshot.test.ts b/packages/api-routes/test/snapshot.test.ts
new file mode 100644
index 0000000..65ec5dd
--- /dev/null
+++ b/packages/api-routes/test/snapshot.test.ts
@@ -0,0 +1,152 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import Fastify from 'fastify'
+import { createClient, migrate } from '@ainyc/canonry-db'
+import { apiRoutes } from '../src/index.js'
+import type { ApiRoutesOptions } from '../src/index.js'
+
+function buildApp(opts: Partial<Omit<ApiRoutesOptions, 'db'>> = {}) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'api-routes-snapshot-'))
+  const db = createClient(path.join(tmpDir, 'test.db'))
+  migrate(db)
+
+  const app = Fastify()
+  app.register(apiRoutes, { db, skipAuth: true, ...opts })
+  return { app, tmpDir }
+}
+
+const SNAPSHOT_FIXTURE = {
+  companyName: 'Acme Corp',
+  domain: 'acme.example.com',
+  homepageUrl: 'https://acme.example.com',
+  generatedAt: '2026-03-29T12:00:00.000Z',
+  phrases: ['best enterprise widget provider'],
+  competitors: ['widgetco.com'],
+  profile: {
+    industry: 'Manufacturing',
+    summary: 'Acme Corp sells enterprise widget manufacturing services.',
+    services: ['Widget manufacturing'],
+    categoryTerms: ['enterprise widgets'],
+  },
+  audit: {
+    url: 'https://acme.example.com',
+    finalUrl: 'https://acme.example.com',
+    auditedAt: '2026-03-29T12:00:00.000Z',
+    overallScore: 58,
+    overallGrade: 'D+',
+    summary: 'Overall grade D+ with weak schema completeness.',
+    factors: [],
+  },
+  queryResults: [
+    {
+      phrase: 'best enterprise widget provider',
+      providerResults: [
+        {
+          provider: 'openai',
+          displayName: 'OpenAI',
+          model: 'gpt-5.4',
+          mentioned: false,
+          cited: false,
+          describedAccurately: 'not-mentioned',
+          accuracyNotes: null,
+          incorrectClaims: [],
+          recommendedCompetitors: ['widgetco.com'],
+          citedDomains: ['widgetco.com'],
+          groundingSources: [],
+          searchQueries: ['best enterprise widget provider'],
+          answerText: 'WidgetCo is a strong option.',
+          error: null,
+        },
+      ],
+    },
+  ],
+  summary: {
+    totalQueries: 1,
+    totalProviders: 1,
+    totalComparisons: 1,
+    mentionCount: 0,
+    citationCount: 0,
+    topCompetitors: [{ name: 'widgetco.com', count: 1 }],
+    visibilityGap: 'Acme Corp was not mentioned in any provider responses.',
+    whatThisMeans: ['Competitors are winning category queries.'],
+    recommendedActions: ['Improve schema completeness.'],
+  },
+}
+
+describe('snapshot routes', () => {
+  let app: ReturnType<typeof Fastify>
+  let tmpDir: string
+
+  beforeAll(async () => {
+    const ctx = buildApp({
+      onSnapshotRequested: async () => SNAPSHOT_FIXTURE,
+    })
+    app = ctx.app
+    tmpDir = ctx.tmpDir
+    await app.ready()
+  })
+
+  afterAll(async () => {
+    await app.close()
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('POST /api/v1/snapshot returns a structured report', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/snapshot',
+      payload: {
+        companyName: 'Acme Corp',
+        domain: 'acme.example.com',
+      },
+    })
+
+    expect(res.statusCode).toBe(200)
+    const body = res.json() as typeof SNAPSHOT_FIXTURE
+    expect(body.companyName).toBe('Acme Corp')
+    expect(body.audit.overallScore).toBe(58)
+    expect(body.queryResults[0]?.providerResults[0]?.recommendedCompetitors).toEqual(['widgetco.com'])
+  })
+
+  it('POST /api/v1/snapshot validates the payload', async () => {
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/v1/snapshot',
+      payload: {
+        companyName: '',
+        domain: '',
+      },
+    })
+
+    expect(res.statusCode).toBe(400)
+    const body = res.json() as {
+      error: {
+        code: string
+        details: { issues: Array<{ path: string }> }
+      }
+    }
+    expect(body.error.code).toBe('VALIDATION_ERROR')
+    expect(body.error.details.issues.map(issue => issue.path)).toEqual(['companyName', 'domain'])
+  })
+
+  it('POST /api/v1/snapshot returns 501 when the server has no snapshot implementation', async () => {
+    const ctx = buildApp()
+    await ctx.app.ready()
+
+    const res = await ctx.app.inject({
+      method: 'POST',
+      url: '/api/v1/snapshot',
+      payload: {
+        companyName: 'Acme Corp',
+        domain: 'acme.example.com',
+      },
+    })
+
+    expect(res.statusCode).toBe(501)
+
+    await ctx.app.close()
+    fs.rmSync(ctx.tmpDir, { recursive: true, force: true })
+  })
+})
diff --git a/packages/canonry/package.json b/packages/canonry/package.json
index 881bb4d..256362f 100644
--- a/packages/canonry/package.json
+++ b/packages/canonry/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ainyc/canonry",
-  "version": "1.28.2",
+  "version": "1.29.0",
   "type": "module",
   "description": "The ultimate open-source AEO monitoring tool - track how answer engines cite your domain",
   "license": "FSL-1.1-ALv2",
@@ -42,31 +42,33 @@
     "lint": "eslint src/ test/"
   },
   "dependencies": {
+    "@ainyc/aeo-audit": "1.3.2",
     "@anthropic-ai/sdk": "^0.78.0",
     "@fastify/static": "^8.1.0",
     "@google/genai": "^1.46.0",
     "better-sqlite3": "^12.6.2",
+    "chrome-remote-interface": "^0.33.2",
     "drizzle-orm": "^0.45.1",
     "fastify": "^5.4.0",
     "node-cron": "^4.2.1",
     "openai": "^6.0.0",
+    "pdf-lib": "^1.17.1",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.7.1",
-    "zod": "^4.1.12",
-    "chrome-remote-interface": "^0.33.2"
+    "zod": "^4.1.12"
   },
   "devDependencies": {
     "@ainyc/canonry-api-routes": "workspace:*",
     "@ainyc/canonry-config": "workspace:*",
     "@ainyc/canonry-contracts": "workspace:*",
     "@ainyc/canonry-db": "workspace:*",
-    "@ainyc/canonry-provider-claude": "workspace:*",
-    "@ainyc/canonry-provider-gemini": "workspace:*",
-    "@ainyc/canonry-provider-cdp": "workspace:*",
-    "@ainyc/canonry-provider-local": "workspace:*",
     "@ainyc/canonry-integration-bing": "workspace:*",
     "@ainyc/canonry-integration-google": "workspace:*",
     "@ainyc/canonry-integration-wordpress": "workspace:*",
+    "@ainyc/canonry-provider-cdp": "workspace:*",
+    "@ainyc/canonry-provider-claude": "workspace:*",
+    "@ainyc/canonry-provider-gemini": "workspace:*",
+    "@ainyc/canonry-provider-local": "workspace:*",
     "@ainyc/canonry-provider-openai": "workspace:*",
     "@ainyc/canonry-provider-perplexity": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
diff --git a/packages/canonry/src/cli-commands.ts b/packages/canonry/src/cli-commands.ts
index a9cef47..c34541c 100644
--- a/packages/canonry/src/cli-commands.ts
+++ b/packages/canonry/src/cli-commands.ts
@@ -11,6 +11,7 @@ import { PROJECT_CLI_COMMANDS } from './cli-commands/project.js'
 import { RUN_CLI_COMMANDS } from './cli-commands/run.js'
 import { SCHEDULE_CLI_COMMANDS } from './cli-commands/schedule.js'
 import { SETTINGS_CLI_COMMANDS } from './cli-commands/settings.js'
+import { SNAPSHOT_CLI_COMMANDS } from './cli-commands/snapshot.js'
 import { SYSTEM_CLI_COMMANDS } from './cli-commands/system.js'
 import { WORDPRESS_CLI_COMMANDS } from './cli-commands/wordpress.js'
 
@@ -20,6 +21,7 @@ export const REGISTERED_CLI_COMMANDS: readonly CliCommandSpec[] = [
   ...KEYWORD_CLI_COMMANDS,
   ...COMPETITOR_CLI_COMMANDS,
   ...SETTINGS_CLI_COMMANDS,
+  ...SNAPSHOT_CLI_COMMANDS,
   ...RUN_CLI_COMMANDS,
   ...OPERATOR_CLI_COMMANDS,
   ...SCHEDULE_CLI_COMMANDS,
diff --git a/packages/canonry/src/cli-commands/snapshot.ts b/packages/canonry/src/cli-commands/snapshot.ts
new file mode 100644
index 0000000..5471dcf
--- /dev/null
+++ b/packages/canonry/src/cli-commands/snapshot.ts
@@ -0,0 +1,46 @@
+import { createSnapshotReport } from '../commands/snapshot.js'
+import type { CliCommandSpec } from '../cli-dispatch.js'
+import { getString, requirePositional, requireStringOption, stringOption } from '../cli-command-helpers.js'
+
+function parseCsvOption(value: string | undefined): string[] | undefined {
+  if (!value) return undefined
+  const parts = value
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean)
+  return parts.length > 0 ? [...new Set(parts)] : undefined
+}
+
+export const SNAPSHOT_CLI_COMMANDS: readonly CliCommandSpec[] = [
+  {
+    path: ['snapshot'],
+    usage: 'canonry snapshot <company-name> --domain <domain> [--phrases "a,b"] [--competitors "x,y"] [--pdf <path>] [--format table|json]',
+    options: {
+      domain: stringOption(),
+      phrases: stringOption(),
+      competitors: stringOption(),
+      pdf: stringOption(),
+    },
+    run: async (input) => {
+      const usage = 'canonry snapshot <company-name> --domain <domain> [--phrases "a,b"] [--competitors "x,y"] [--pdf <path>] [--format table|json]'
+      const companyName = requirePositional(input, 0, {
+        command: 'snapshot',
+        usage,
+        message: 'company name is required',
+      })
+      const domain = requireStringOption(input, 'domain', {
+        command: 'snapshot',
+        usage,
+        message: '--domain is required',
+      })
+
+      await createSnapshotReport(companyName, {
+        domain,
+        phrases: parseCsvOption(getString(input.values, 'phrases')),
+        competitors: parseCsvOption(getString(input.values, 'competitors')),
+        pdf: getString(input.values, 'pdf'),
+        format: input.format,
+      })
+    },
+  },
+]
diff --git a/packages/canonry/src/cli.ts b/packages/canonry/src/cli.ts
index 40fdd7d..c8b5d9c 100644
--- a/packages/canonry/src/cli.ts
+++ b/packages/canonry/src/cli.ts
@@ -31,6 +31,7 @@ Usage:
   canonry keyword generate <project>  Auto-generate key phrases (--provider, --count, --save)
   canonry competitor add <project> <domain>  Add competitors
   canonry competitor list <project>   List competitors
+  canonry snapshot <company> --domain <domain>  One-shot AI perception report
   canonry run <project>               Trigger a run (all providers)
   canonry run <project> --provider <name>  Trigger a run for a specific provider
   canonry run <project> --location <label> Run with a specific location
@@ -132,6 +133,9 @@ Options:
   --language <lang>    Language code (default: en)
   --provider <name>    Provider to use (gemini, openai, claude, perplexity, local, cdp:chatgpt, or cdp for all CDP targets)
   --format <fmt>       Output format: text (default) or json
+  --phrases <list>     Comma-separated category queries (snapshot)
+  --competitors <list> Comma-separated competitor hints (snapshot)
+  --pdf <path>         Write a PDF snapshot report to a file
   --location <label>   Run with a specific configured location
   --all-locations      Run for every configured location
   --no-location        Explicitly skip location context
diff --git a/packages/canonry/src/client.ts b/packages/canonry/src/client.ts
index d8cf4e5..ebc81c9 100644
--- a/packages/canonry/src/client.ts
+++ b/packages/canonry/src/client.ts
@@ -1,5 +1,6 @@
 import { loadConfig } from './config.js'
 import type {
+  SnapshotReportDto,
   WordpressAuditIssueDto,
   WordpressAuditPageDto,
   WordpressDiffDto,
@@ -212,6 +213,15 @@ export class ApiClient {
     return this.request<object>('GET', '/settings')
   }
 
+  async createSnapshot(body: {
+    companyName: string
+    domain: string
+    phrases?: string[]
+    competitors?: string[]
+  }): Promise<SnapshotReportDto> {
+    return this.request<SnapshotReportDto>('POST', '/snapshot', body)
+  }
+
   async updateProvider(name: string, body: { apiKey?: string; baseUrl?: string; model?: string; quota?: { maxConcurrency?: number; maxRequestsPerMinute?: number; maxRequestsPerDay?: number } }): Promise<object> {
     return this.request<object>('PUT', `/settings/providers/${encodeURIComponent(name)}`, body)
   }
diff --git a/packages/canonry/src/commands/snapshot.ts b/packages/canonry/src/commands/snapshot.ts
new file mode 100644
index 0000000..11964fb
--- /dev/null
+++ b/packages/canonry/src/commands/snapshot.ts
@@ -0,0 +1,109 @@
+import type { SnapshotProviderResultDto, SnapshotReportDto } from '@ainyc/canonry-contracts'
+import { createApiClient } from '../client.js'
+import { writeSnapshotPdf } from '../snapshot-pdf.js'
+
+function getClient() {
+  return createApiClient()
+}
+
+export async function createSnapshotReport(
+  companyName: string,
+  opts: {
+    domain: string
+    phrases?: string[]
+    competitors?: string[]
+    pdf?: string
+    format?: string
+  },
+): Promise<void> {
+  const client = getClient()
+  const report = await client.createSnapshot({
+    companyName,
+    domain: opts.domain,
+    ...(opts.phrases && opts.phrases.length > 0 ? { phrases: opts.phrases } : {}),
+    ...(opts.competitors && opts.competitors.length > 0 ? { competitors: opts.competitors } : {}),
+  })
+
+  let savedPdfPath: string | undefined
+  if (opts.pdf) {
+    savedPdfPath = await writeSnapshotPdf(report, opts.pdf)
+  }
+
+  if (opts.format === 'json') {
+    console.log(JSON.stringify(report, null, 2))
+    if (savedPdfPath) {
+      process.stderr.write(`Saved PDF: ${savedPdfPath}\n`)
+    }
+    return
+  }
+
+  console.log(formatSnapshotText(report))
+  if (savedPdfPath) {
+    console.log(`\nPDF saved: ${savedPdfPath}`)
+  }
+}
+
+export function formatSnapshotText(report: SnapshotReportDto): string {
+  const lines: string[] = []
+  lines.push(`Snapshot: ${report.companyName} (${report.domain})`)
+  lines.push(`AEO audit: ${report.audit.overallScore}/100 (${report.audit.overallGrade})`)
+  lines.push(report.summary.visibilityGap)
+  lines.push('')
+
+  if (report.summary.topCompetitors.length > 0) {
+    lines.push(
+      `Top competitors AI recommended instead: ${report.summary.topCompetitors.map(entry => `${entry.name} (${entry.count})`).join(', ')}`,
+    )
+    lines.push('')
+  }
+
+  if (report.summary.whatThisMeans.length > 0) {
+    lines.push('What this means:')
+    for (const item of report.summary.whatThisMeans) {
+      lines.push(`  - ${item}`)
+    }
+    lines.push('')
+  }
+
+  const providerWidth = Math.max(
+    8,
+    ...report.queryResults.flatMap(query => query.providerResults.map(result => result.displayName.length)),
+  )
+
+  for (const query of report.queryResults) {
+    lines.push(`"${query.phrase}"`)
+    for (const result of query.providerResults) {
+      lines.push(`  ${result.displayName.padEnd(providerWidth)}  ${formatProviderLine(result)}`)
+    }
+    lines.push('')
+  }
+
+  if (report.summary.recommendedActions.length > 0) {
+    lines.push('Recommended actions:')
+    for (const action of report.summary.recommendedActions) {
+      lines.push(`  - ${action}`)
+    }
+  }
+
+  return lines.join('\n').trimEnd()
+}
+
+function formatProviderLine(result: SnapshotProviderResultDto): string {
+  if (result.error) {
+    return `ERROR: ${result.error}`
+  }
+
+  const bits: string[] = []
+  bits.push(result.mentioned ? 'YES mentioned' : 'NO mention')
+  if (result.cited) bits.push('cited')
+  if (result.describedAccurately !== 'not-mentioned') {
+    bits.push(`accuracy=${result.describedAccurately}`)
+  }
+  if (result.recommendedCompetitors.length > 0) {
+    bits.push(`recommended instead: ${result.recommendedCompetitors.join(', ')}`)
+  }
+  if (result.incorrectClaims.length > 0) {
+    bits.push(`incorrect: ${result.incorrectClaims.join('; ')}`)
+  }
+  return bits.join(' | ')
+}
diff --git a/packages/canonry/src/server.ts b/packages/canonry/src/server.ts
index 5b95d9f..6b5edc1 100644
--- a/packages/canonry/src/server.ts
+++ b/packages/canonry/src/server.ts
@@ -47,6 +47,7 @@ import { executeInspectSitemap } from './gsc-inspect-sitemap.js'
 import { ProviderRegistry } from './provider-registry.js'
 import { Scheduler } from './scheduler.js'
 import { Notifier } from './notifier.js'
+import { SnapshotService } from './snapshot-service.js'
 import { fetchSiteText } from './site-fetch.js'
 import { createLogger } from './logger.js'
 
@@ -234,6 +235,7 @@ export async function createServer(opts: {
   jobRunner.recoverStaleRuns()
   const notifier = new Notifier(opts.db, serverUrl)
   jobRunner.onRunCompleted = (runId, projectId) => notifier.onRunCompleted(runId, projectId)
+  const snapshotService = new SnapshotService(registry)
 
   const scheduler = new Scheduler(opts.db, {
     onRunCreated: (runId, projectId, providers) => {
@@ -896,6 +898,9 @@ export async function createServer(opts: {
       const raw = await provider.adapter.generateText(prompt, provider.config)
       return parseKeywordResponse(raw, count)
     },
+    onSnapshotRequested: async (input) => {
+      return snapshotService.createReport(input)
+    },
   })
 
   // Try to serve static SPA assets
diff --git a/packages/canonry/src/snapshot-format.ts b/packages/canonry/src/snapshot-format.ts
new file mode 100644
index 0000000..746318d
--- /dev/null
+++ b/packages/canonry/src/snapshot-format.ts
@@ -0,0 +1,5 @@
+import type { SnapshotAuditFactorDto } from '@ainyc/canonry-contracts'
+
+export function formatAuditFactorScore(factor: Pick<SnapshotAuditFactorDto, 'score' | 'weight'>): string {
+  return `${factor.score}/100 (${factor.weight}% weight)`
+}
diff --git a/packages/canonry/src/snapshot-pdf.ts b/packages/canonry/src/snapshot-pdf.ts
new file mode 100644
index 0000000..a5c0d6d
--- /dev/null
+++ b/packages/canonry/src/snapshot-pdf.ts
@@ -0,0 +1,377 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { PDFDocument, StandardFonts, rgb, type PDFFont, type PDFPage } from 'pdf-lib'
+import type { SnapshotReportDto } from '@ainyc/canonry-contracts'
+import { formatAuditFactorScore } from './snapshot-format.js'
+
+const PAGE_WIDTH = 612
+const PAGE_HEIGHT = 792
+const MARGIN = 48
+const BRAND = rgb(0.58, 0, 0)
+const INK = rgb(0.1, 0.1, 0.1)
+const MUTED = rgb(0.38, 0.38, 0.38)
+const LINE = rgb(0.82, 0.8, 0.76)
+const PASS = rgb(0.18, 0.49, 0.31)
+const CAUTION = rgb(0.72, 0.45, 0.2)
+const FAIL = rgb(0.7, 0.15, 0.15)
+
+class PdfWriter {
+  private readonly usableWidth = PAGE_WIDTH - (MARGIN * 2)
+  private page!: PDFPage
+  private y = 0
+
+  constructor(
+    private readonly doc: PDFDocument,
+    private readonly regular: PDFFont,
+    private readonly bold: PDFFont,
+  ) {
+    this.addPage()
+  }
+
+  addPage() {
+    this.page = this.doc.addPage([PAGE_WIDTH, PAGE_HEIGHT])
+    this.y = PAGE_HEIGHT - MARGIN
+  }
+
+  ensureSpace(height: number) {
+    if (this.y - height < MARGIN) {
+      this.addPage()
+    }
+  }
+
+  heading(text: string, size = 18) {
+    this.ensureSpace(size + 12)
+    this.page.drawText(text, {
+      x: MARGIN,
+      y: this.y,
+      size,
+      font: this.bold,
+      color: BRAND,
+    })
+    this.y -= size + 8
+  }
+
+  subheading(text: string, size = 12) {
+    this.ensureSpace(size + 8)
+    this.page.drawText(text, {
+      x: MARGIN,
+      y: this.y,
+      size,
+      font: this.bold,
+      color: INK,
+    })
+    this.y -= size + 6
+  }
+
+  paragraph(text: string, opts?: { size?: number; color?: ReturnType<typeof rgb>; lineHeight?: number }) {
+    const size = opts?.size ?? 10
+    const color = opts?.color ?? INK
+    const lineHeight = opts?.lineHeight ?? size + 4
+    const lines = wrapText(this.regular, text, size, this.usableWidth)
+    this.ensureSpace((lines.length * lineHeight) + 4)
+    for (const line of lines) {
+      this.page.drawText(line, {
+        x: MARGIN,
+        y: this.y,
+        size,
+        font: this.regular,
+        color,
+      })
+      this.y -= lineHeight
+    }
+    this.y -= 2
+  }
+
+  bullet(text: string) {
+    const lines = wrapText(this.regular, text, 10, this.usableWidth - 14)
+    this.ensureSpace((lines.length * 14) + 2)
+    this.page.drawText('-', {
+      x: MARGIN,
+      y: this.y,
+      size: 10,
+      font: this.bold,
+      color: BRAND,
+    })
+    let first = true
+    for (const line of lines) {
+      this.page.drawText(line, {
+        x: MARGIN + 14,
+        y: this.y,
+        size: 10,
+        font: this.regular,
+        color: INK,
+      })
+      this.y -= 14
+      if (first) first = false
+    }
+    this.y -= 2
+  }
+
+  rule() {
+    this.ensureSpace(8)
+    this.page.drawLine({
+      start: { x: MARGIN, y: this.y },
+      end: { x: PAGE_WIDTH - MARGIN, y: this.y },
+      thickness: 1,
+      color: LINE,
+    })
+    this.y -= 10
+  }
+
+  keyValue(label: string, value: string) {
+    const size = 10
+    const labelWidth = this.bold.widthOfTextAtSize(`${label}: `, size)
+    this.ensureSpace(16)
+    this.page.drawText(`${label}:`, {
+      x: MARGIN,
+      y: this.y,
+      size,
+      font: this.bold,
+      color: INK,
+    })
+    const lines = wrapText(this.regular, value, size, this.usableWidth - labelWidth - 4)
+    let currentY = this.y
+    for (const line of lines) {
+      this.page.drawText(line, {
+        x: MARGIN + labelWidth + 4,
+        y: currentY,
+        size,
+        font: this.regular,
+        color: INK,
+      })
+      currentY -= 14
+    }
+    this.y = currentY - 2
+  }
+
+  table(headers: string[], rows: string[][], widths?: number[]) {
+    const columnWidths = widths ?? headers.map(() => this.usableWidth / headers.length)
+    const headerHeight = 20
+    this.ensureSpace(headerHeight + 10)
+
+    let x = MARGIN
+    for (let i = 0; i < headers.length; i++) {
+      const width = columnWidths[i]!
+      this.page.drawRectangle({
+        x,
+        y: this.y - headerHeight + 4,
+        width,
+        height: headerHeight,
+        color: BRAND,
+      })
+      const lines = wrapText(this.bold, headers[i]!, 9, width - 8)
+      let lineY = this.y - 10
+      for (const line of lines) {
+        this.page.drawText(line, {
+          x: x + 4,
+          y: lineY,
+          size: 9,
+          font: this.bold,
+          color: rgb(1, 0.98, 0.93),
+        })
+        lineY -= 10
+      }
+      x += width
+    }
+    this.y -= headerHeight + 4
+
+    for (const row of rows) {
+      const lineCounts = row.map((cell, index) => wrapText(this.regular, cell, 9, columnWidths[index]! - 8).length)
+      const rowHeight = Math.max(18, Math.max(...lineCounts) * 11 + 6)
+      this.ensureSpace(rowHeight + 4)
+
+      let cellX = MARGIN
+      for (let i = 0; i < row.length; i++) {
+        const width = columnWidths[i]!
+        this.page.drawRectangle({
+          x: cellX,
+          y: this.y - rowHeight + 4,
+          width,
+          height: rowHeight,
+          borderColor: LINE,
+          borderWidth: 0.5,
+        })
+        const lines = wrapText(this.regular, row[i]!, 9, width - 8)
+        let lineY = this.y - 10
+        for (const line of lines) {
+          this.page.drawText(line, {
+            x: cellX + 4,
+            y: lineY,
+            size: 9,
+            font: this.regular,
+            color: INK,
+          })
+          lineY -= 11
+        }
+        cellX += width
+      }
+      this.y -= rowHeight + 2
+    }
+
+    this.y -= 4
+  }
+}
+
+export async function writeSnapshotPdf(report: SnapshotReportDto, outputPath: string): Promise<string> {
+  const doc = await PDFDocument.create()
+  doc.setTitle(`${report.companyName} AI Perception Snapshot`)
+  doc.setAuthor('Canonry')
+  doc.setSubject('AEO snapshot report')
+  doc.setProducer('Canonry')
+  doc.setCreator('Canonry')
+
+  const regular = await doc.embedFont(StandardFonts.Helvetica)
+  const bold = await doc.embedFont(StandardFonts.HelveticaBold)
+  const pdf = new PdfWriter(doc, regular, bold)
+
+  renderCover(pdf, report)
+  renderSummary(pdf, report)
+  renderAudit(pdf, report)
+  renderCompetitors(pdf, report)
+  renderQueries(pdf, report)
+
+  const bytes = await doc.save()
+  const resolvedPath = path.resolve(outputPath)
+  fs.mkdirSync(path.dirname(resolvedPath), { recursive: true })
+  fs.writeFileSync(resolvedPath, bytes)
+  return resolvedPath
+}
+
+function renderCover(pdf: PdfWriter, report: SnapshotReportDto) {
+  pdf.heading('AI Perception Snapshot', 24)
+  pdf.paragraph(report.companyName, { size: 15, color: INK, lineHeight: 18 })
+  pdf.paragraph(report.domain, { size: 11, color: MUTED, lineHeight: 14 })
+  pdf.rule()
+  pdf.keyValue('Generated', new Date(report.generatedAt).toLocaleString('en-US', {
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+  }))
+  pdf.keyValue('AEO Audit', `${report.audit.overallScore}/100 (${report.audit.overallGrade})`)
+  pdf.keyValue('Visibility Gap', report.summary.visibilityGap)
+  pdf.paragraph(report.profile.summary, { size: 11, color: INK, lineHeight: 16 })
+  pdf.rule()
+}
+
+function renderSummary(pdf: PdfWriter, report: SnapshotReportDto) {
+  pdf.heading('What This Means')
+  for (const line of report.summary.whatThisMeans) {
+    pdf.bullet(line)
+  }
+  pdf.subheading('Recommended Actions')
+  for (const action of report.summary.recommendedActions) {
+    pdf.bullet(action)
+  }
+  pdf.rule()
+}
+
+function renderAudit(pdf: PdfWriter, report: SnapshotReportDto) {
+  pdf.heading('Audit Snapshot')
+  pdf.paragraph(report.audit.summary, { size: 10, color: MUTED, lineHeight: 14 })
+
+  const factorRows = [...report.audit.factors]
+    .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
+    .slice(0, 5)
+    .map(factor => [
+      factor.name,
+      formatAuditFactorScore(factor),
+      factor.status,
+    ])
+
+  if (factorRows.length > 0) {
+    pdf.table(['Weakest factor', 'Score / Weight', 'Status'], factorRows, [270, 120, 126])
+  }
+  pdf.rule()
+}
+
+function renderCompetitors(pdf: PdfWriter, report: SnapshotReportDto) {
+  pdf.heading('Recommended Instead')
+  if (report.summary.topCompetitors.length === 0) {
+    pdf.paragraph('No clear competitor cluster was extracted from the responses.', {
+      size: 10,
+      color: MUTED,
+    })
+    pdf.rule()
+    return
+  }
+
+  pdf.table(
+    ['Competitor', 'Mentions'],
+    report.summary.topCompetitors.map(entry => [entry.name, String(entry.count)]),
+    [420, 96],
+  )
+  pdf.rule()
+}
+
+function renderQueries(pdf: PdfWriter, report: SnapshotReportDto) {
+  pdf.heading('Provider Comparison')
+  for (const query of report.queryResults) {
+    pdf.subheading(query.phrase, 11)
+    for (const result of query.providerResults) {
+      const status = result.error
+        ? 'error'
+        : result.mentioned
+          ? result.cited ? 'mentioned and cited' : 'mentioned'
+          : 'not mentioned'
+      const accuracy = result.describedAccurately === 'not-mentioned'
+        ? ''
+        : `; accuracy: ${result.describedAccurately}`
+      const competitors = result.recommendedCompetitors.length > 0
+        ? `; recommended instead: ${result.recommendedCompetitors.join(', ')}`
+        : ''
+      const line = `${result.displayName}: ${status}${accuracy}${competitors}`
+      pdf.bullet(line)
+      if (result.error) {
+        pdf.paragraph(`Error: ${result.error}`, { size: 9, color: FAIL, lineHeight: 12 })
+      } else if (result.accuracyNotes) {
+        const color = result.describedAccurately === 'yes'
+          ? PASS
+          : result.describedAccurately === 'no'
+            ? FAIL
+            : CAUTION
+        pdf.paragraph(result.accuracyNotes, { size: 9, color, lineHeight: 12 })
+      }
+    }
+    pdf.rule()
+  }
+}
+
+function wrapText(font: PDFFont, text: string, size: number, maxWidth: number): string[] {
+  const normalized = text.replace(/\s+/g, ' ').trim()
+  if (!normalized) return ['']
+
+  const words = normalized.split(' ')
+  const lines: string[] = []
+  let current = ''
+
+  for (const word of words) {
+    const next = current ? `${current} ${word}` : word
+    if (font.widthOfTextAtSize(next, size) <= maxWidth) {
+      current = next
+      continue
+    }
+
+    if (current) {
+      lines.push(current)
+      current = word
+      continue
+    }
+
+    let chunk = ''
+    for (const char of word) {
+      const candidate = `${chunk}${char}`
+      if (font.widthOfTextAtSize(candidate, size) <= maxWidth) {
+        chunk = candidate
+      } else {
+        if (chunk) lines.push(chunk)
+        chunk = char
+      }
+    }
+    current = chunk
+  }
+
+  if (current) lines.push(current)
+  return lines
+}
diff --git a/packages/canonry/src/snapshot-service.ts b/packages/canonry/src/snapshot-service.ts
new file mode 100644
index 0000000..e4a5c8e
--- /dev/null
+++ b/packages/canonry/src/snapshot-service.ts
@@ -0,0 +1,853 @@
+import { runAeoAudit } from '@ainyc/aeo-audit'
+import type {
+  GroundingSource,
+  SnapshotAccuracy,
+  SnapshotAuditDto,
+  SnapshotProfileDto,
+  SnapshotProviderResultDto,
+  SnapshotQueryResultDto,
+  SnapshotReportDto,
+  SnapshotRequestDto,
+} from '@ainyc/canonry-contracts'
+import type { ProviderName } from '@ainyc/canonry-contracts'
+import { fetchSiteText } from './site-fetch.js'
+import type { RegisteredProvider, ProviderRegistry } from './provider-registry.js'
+import { createLogger } from './logger.js'
+import { formatAuditFactorScore } from './snapshot-format.js'
+
+const log = createLogger('Snapshot')
+
+const ANALYSIS_PROVIDER_PRIORITY = ['openai', 'claude', 'gemini', 'perplexity', 'local'] as const
+const SNAPSHOT_QUERY_COUNT = 6
+class ProviderExecutionGate {
+  private readonly window: number[] = []
+  private readonly waiters: Array<() => void> = []
+  private rateLimitChain = Promise.resolve()
+  private inFlight = 0
+
+  constructor(
+    private readonly maxConcurrency: number,
+    private readonly maxPerMinute: number,
+  ) {}
+
+  async run<T>(task: () => Promise<T>): Promise<T> {
+    await this.acquire()
+    try {
+      await this.waitForRateLimit()
+      return await task()
+    } finally {
+      this.release()
+    }
+  }
+
+  private async acquire(): Promise<void> {
+    if (this.inFlight < Math.max(1, this.maxConcurrency)) {
+      this.inFlight++
+      return
+    }
+
+    await new Promise<void>((resolve) => {
+      this.waiters.push(resolve)
+    })
+    this.inFlight++
+  }
+
+  private release(): void {
+    this.inFlight = Math.max(0, this.inFlight - 1)
+    const next = this.waiters.shift()
+    next?.()
+  }
+
+  private async waitForRateLimit(): Promise<void> {
+    let releaseChain: (() => void) | undefined
+    const previousChain = this.rateLimitChain
+    this.rateLimitChain = new Promise<void>((resolve) => {
+      releaseChain = resolve
+    })
+
+    await previousChain
+    try {
+      const now = Date.now()
+      const windowStart = now - 60_000
+      while (this.window.length > 0 && this.window[0]! < windowStart) {
+        this.window.shift()
+      }
+
+      if (this.window.length >= this.maxPerMinute) {
+        const oldestInWindow = this.window[0]!
+        const waitMs = oldestInWindow + 60_000 - now + 50
+        await new Promise(resolve => setTimeout(resolve, waitMs))
+        const nowAfterWait = Date.now()
+        const newWindowStart = nowAfterWait - 60_000
+        while (this.window.length > 0 && this.window[0]! < newWindowStart) {
+          this.window.shift()
+        }
+      }
+
+      this.window.push(Date.now())
+    } finally {
+      releaseChain?.()
+    }
+  }
+}
+
+type GeneratedSnapshotProfile = SnapshotProfileDto & {
+  phrases: string[]
+}
+
+type ResponseAssessment = {
+  phrase: string
+  provider: string
+  mentioned?: boolean
+  describedAccurately?: SnapshotAccuracy
+  accuracyNotes?: string | null
+  incorrectClaims?: string[]
+  recommendedCompetitors?: string[]
+}
+
+type BatchAssessment = {
+  assessments: ResponseAssessment[]
+  whatThisMeans: string[]
+  recommendedActions: string[]
+}
+
+type AeoAuditReport = Awaited<ReturnType<typeof runAeoAudit>>
+type AeoAuditFactor = AeoAuditReport['factors'][number]
+
+export class SnapshotService {
+  constructor(private readonly registry: ProviderRegistry) {}
+
+  async createReport(input: SnapshotRequestDto): Promise<SnapshotReportDto> {
+    const companyName = input.companyName.trim()
+    const domain = normalizeDomain(input.domain)
+    const manualPhrases = normalizeStringList(input.phrases ?? [])
+    const manualCompetitors = normalizeStringList(input.competitors ?? [])
+    const providers = this.registry.getAll()
+    if (providers.length === 0) {
+      throw new Error('No providers configured. Add at least one provider API key before running canonry snapshot.')
+    }
+
+    const analysisProvider = pickAnalysisProvider(this.registry.getApiProviders())
+    const homepageUrl = `https://${extractHostname(domain)}`
+
+    const [siteText, audit] = await Promise.all([
+      fetchSiteText(domain),
+      this.runAudit(homepageUrl),
+    ])
+
+    if (manualPhrases.length === 0 && !siteText) {
+      throw new Error(
+        `Could not analyze https://${extractHostname(domain)}. ` +
+        'Try again with a reachable homepage or pass manual category queries via --phrases.',
+      )
+    }
+
+    const profile = await this.buildProfile({
+      companyName,
+      domain,
+      siteText,
+      audit,
+      manualPhrases,
+      analysisProvider,
+    })
+
+    const queryResults = await this.runSnapshotQueries({
+      companyName,
+      domain,
+      phrases: profile.phrases,
+      providers,
+      manualCompetitors,
+    })
+
+    const batchAssessment = await this.analyzeResponses({
+      companyName,
+      domain,
+      profile,
+      audit,
+      queryResults,
+      manualCompetitors,
+      analysisProvider,
+    })
+
+    const enrichedResults = applyBatchAssessment(queryResults, batchAssessment)
+    const summary = buildSnapshotSummary(companyName, profile.phrases, providers, enrichedResults, audit, batchAssessment)
+    const reportCompetitors = uniqueStrings([
+      ...manualCompetitors,
+      ...summary.topCompetitors.map(entry => entry.name),
+    ])
+
+    return {
+      companyName,
+      domain,
+      homepageUrl,
+      generatedAt: new Date().toISOString(),
+      phrases: profile.phrases,
+      competitors: reportCompetitors,
+      profile: {
+        industry: profile.industry,
+        summary: profile.summary,
+        services: profile.services,
+        categoryTerms: profile.categoryTerms,
+      },
+      audit,
+      queryResults: enrichedResults,
+      summary,
+    }
+  }
+
+  private async runAudit(homepageUrl: string): Promise<SnapshotAuditDto> {
+    try {
+      const report = await runAeoAudit(homepageUrl)
+      return mapAuditReport(report)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      log.warn('audit.failed', { homepageUrl, error: message })
+      return {
+        url: homepageUrl,
+        finalUrl: homepageUrl,
+        auditedAt: new Date().toISOString(),
+        overallScore: 0,
+        overallGrade: 'N/A',
+        summary: `Technical audit unavailable: ${message}`,
+        factors: [],
+      }
+    }
+  }
+
+  private async buildProfile(ctx: {
+    companyName: string
+    domain: string
+    siteText: string
+    audit: SnapshotAuditDto
+    manualPhrases: string[]
+    analysisProvider?: RegisteredProvider
+  }): Promise<GeneratedSnapshotProfile> {
+    if (ctx.analysisProvider && ctx.siteText) {
+      const prompt = buildProfilePrompt(ctx)
+      try {
+        const raw = await ctx.analysisProvider.adapter.generateText(prompt, ctx.analysisProvider.config)
+        const parsed = parseJsonObject<{
+          industry?: string
+          summary?: string
+          services?: string[]
+          categoryTerms?: string[]
+          phrases?: string[]
+        }>(raw)
+        const parsedPhrases = ctx.manualPhrases.length > 0
+          ? ctx.manualPhrases
+          : normalizeStringList(parsed.phrases ?? []).slice(0, SNAPSHOT_QUERY_COUNT)
+
+        if (ctx.manualPhrases.length === 0 && parsedPhrases.length === 0) {
+          throw new Error('no phrases returned')
+        }
+
+        return {
+          industry: parsed.industry?.trim() || 'Unknown',
+          summary: parsed.summary?.trim() || ctx.audit.summary,
+          services: uniqueStrings(parsed.services ?? []).slice(0, 6),
+          categoryTerms: uniqueStrings(parsed.categoryTerms ?? []).slice(0, 8),
+          phrases: parsedPhrases,
+        }
+      } catch (err) {
+        log.warn('profile.generation-failed', {
+          domain: ctx.domain,
+          provider: ctx.analysisProvider.adapter.name,
+          error: err instanceof Error ? err.message : String(err),
+        })
+      }
+    }
+
+    if (ctx.manualPhrases.length === 0) {
+      throw new Error(
+        'Automatic category-query generation requires a configured API provider. ' +
+        'Add OpenAI, Claude, Gemini, Perplexity, or Local, or pass --phrases manually.',
+      )
+    }
+
+    return {
+      industry: 'Unknown',
+      summary: ctx.audit.summary,
+      services: [],
+      categoryTerms: [],
+      phrases: ctx.manualPhrases,
+    }
+  }
+
+  private async runSnapshotQueries(ctx: {
+    companyName: string
+    domain: string
+    phrases: string[]
+    providers: RegisteredProvider[]
+    manualCompetitors: string[]
+  }): Promise<SnapshotQueryResultDto[]> {
+    const gates = new Map<ProviderName, ProviderExecutionGate>()
+    for (const provider of ctx.providers) {
+      gates.set(
+        provider.adapter.name,
+        new ProviderExecutionGate(
+          provider.config.quotaPolicy.maxConcurrency,
+          provider.config.quotaPolicy.maxRequestsPerMinute,
+        ),
+      )
+    }
+
+    const competitorDomains = ctx.manualCompetitors.filter(isDomainLike)
+
+    return Promise.all(ctx.phrases.map(async (phrase) => ({
+      phrase,
+      providerResults: await Promise.all(ctx.providers.map(async (provider) => {
+        const gate = gates.get(provider.adapter.name)!
+        return gate.run(async () => {
+          try {
+            const raw = await provider.adapter.executeTrackedQuery(
+              {
+                keyword: phrase,
+                canonicalDomains: [ctx.domain],
+                competitorDomains,
+              },
+              provider.config,
+            )
+            const normalized = provider.adapter.normalizeResult(raw)
+            const preliminaryCompetitors = extractCompetitorsFromResponse({
+              answerText: normalized.answerText,
+              citedDomains: normalized.citedDomains,
+              manualCompetitors: ctx.manualCompetitors,
+              targetDomain: ctx.domain,
+            })
+
+            return {
+              provider: provider.adapter.name,
+              displayName: provider.adapter.displayName,
+              model: raw.model,
+              mentioned: mentionsTargetCompany(normalized.answerText, ctx.companyName, ctx.domain),
+              cited: citesTargetDomain(normalized.citedDomains, normalized.groundingSources, ctx.domain),
+              describedAccurately: 'unknown' as const,
+              accuracyNotes: null,
+              incorrectClaims: [],
+              recommendedCompetitors: preliminaryCompetitors,
+              citedDomains: uniqueStrings(normalized.citedDomains),
+              groundingSources: normalized.groundingSources,
+              searchQueries: uniqueStrings(normalized.searchQueries),
+              answerText: normalized.answerText,
+              error: null,
+            } satisfies SnapshotProviderResultDto
+          } catch (err) {
+            return {
+              provider: provider.adapter.name,
+              displayName: provider.adapter.displayName,
+              model: provider.config.model ?? provider.adapter.modelRegistry.defaultModel,
+              mentioned: false,
+              cited: false,
+              describedAccurately: 'unknown' as const,
+              accuracyNotes: null,
+              incorrectClaims: [],
+              recommendedCompetitors: [],
+              citedDomains: [],
+              groundingSources: [],
+              searchQueries: [],
+              answerText: '',
+              error: err instanceof Error ? err.message : String(err),
+            } satisfies SnapshotProviderResultDto
+          }
+        })
+      })),
+    })))
+  }
+
+  private async analyzeResponses(ctx: {
+    companyName: string
+    domain: string
+    profile: GeneratedSnapshotProfile
+    audit: SnapshotAuditDto
+    queryResults: SnapshotQueryResultDto[]
+    manualCompetitors: string[]
+    analysisProvider?: RegisteredProvider
+  }): Promise<BatchAssessment> {
+    if (!ctx.analysisProvider) {
+      return buildFallbackBatchAssessment(ctx.companyName, ctx.audit)
+    }
+
+    const responses = ctx.queryResults.flatMap(query =>
+      query.providerResults
+        .filter(result => !result.error)
+        .map(result => ({
+          phrase: query.phrase,
+          provider: result.provider,
+          displayName: result.displayName,
+          heuristicMentioned: result.mentioned,
+          heuristicCited: result.cited,
+          heuristicCompetitors: result.recommendedCompetitors,
+          citedDomains: result.citedDomains,
+          groundingSources: result.groundingSources.map(source => source.uri),
+          answerText: clipText(result.answerText, 420),
+        })),
+    )
+
+    if (responses.length === 0) {
+      return buildFallbackBatchAssessment(ctx.companyName, ctx.audit)
+    }
+
+    try {
+      const prompt = buildBatchAnalysisPrompt({
+        companyName: ctx.companyName,
+        domain: ctx.domain,
+        profile: ctx.profile,
+        audit: ctx.audit,
+        responses,
+        manualCompetitors: ctx.manualCompetitors,
+      })
+      const raw = await ctx.analysisProvider.adapter.generateText(prompt, ctx.analysisProvider.config)
+      const parsed = parseJsonObject<{
+        assessments?: Array<{
+          phrase?: string
+          provider?: string
+          mentioned?: boolean
+          describedAccurately?: SnapshotAccuracy
+          accuracyNotes?: string | null
+          incorrectClaims?: string[]
+          recommendedCompetitors?: string[]
+        }>
+        whatThisMeans?: string[]
+        recommendedActions?: string[]
+      }>(raw)
+
+      return {
+        assessments: (parsed.assessments ?? [])
+          .filter(assessment => assessment.phrase && assessment.provider)
+          .map(assessment => {
+            const hasReviewedCompetitors = assessment.recommendedCompetitors !== undefined
+            return {
+              phrase: assessment.phrase!,
+              provider: assessment.provider!,
+              mentioned: assessment.mentioned,
+              describedAccurately: assessment.describedAccurately,
+              accuracyNotes: assessment.accuracyNotes ?? null,
+              incorrectClaims: uniqueStrings(assessment.incorrectClaims ?? []).slice(0, 5),
+              ...(hasReviewedCompetitors
+                ? {
+                    recommendedCompetitors: uniqueStrings(assessment.recommendedCompetitors ?? []).slice(0, 6),
+                  }
+                : {}),
+            }
+          }),
+        whatThisMeans: uniqueStrings(parsed.whatThisMeans ?? []).slice(0, 4),
+        recommendedActions: uniqueStrings(parsed.recommendedActions ?? []).slice(0, 4),
+      }
+    } catch (err) {
+      log.warn('response.analysis-failed', {
+        provider: ctx.analysisProvider.adapter.name,
+        error: err instanceof Error ? err.message : String(err),
+      })
+      return buildFallbackBatchAssessment(ctx.companyName, ctx.audit)
+    }
+  }
+}
+
+function pickAnalysisProvider(providers: RegisteredProvider[]): RegisteredProvider | undefined {
+  return [...providers].sort((a, b) => {
+    const aIndex = ANALYSIS_PROVIDER_PRIORITY.indexOf(a.adapter.name as typeof ANALYSIS_PROVIDER_PRIORITY[number])
+    const bIndex = ANALYSIS_PROVIDER_PRIORITY.indexOf(b.adapter.name as typeof ANALYSIS_PROVIDER_PRIORITY[number])
+    return (aIndex === -1 ? Number.MAX_SAFE_INTEGER : aIndex) - (bIndex === -1 ? Number.MAX_SAFE_INTEGER : bIndex)
+  })[0]
+}
+
+function buildProfilePrompt(ctx: {
+  companyName: string
+  domain: string
+  siteText: string
+  audit: SnapshotAuditDto
+  manualPhrases: string[]
+  analysisProvider?: RegisteredProvider
+}): string {
+  const instructions = [
+    'You are an AEO and SEO expert building a sales snapshot for an uninformed corporate prospect.',
+    'Use ONLY the homepage text below. Do not browse or invent facts.',
+    'Infer the company category, summarize what it sells, and generate non-branded category queries buyers would ask an AI assistant.',
+    'Never produce brand queries like "what does Acme do?"',
+    `Return strict JSON with keys: industry, summary, services, categoryTerms, phrases.`,
+    `phrases must contain exactly ${SNAPSHOT_QUERY_COUNT} buyer-style category/recommendation queries unless manual phrases are provided.`,
+  ]
+
+  if (ctx.manualPhrases.length > 0) {
+    instructions.push('Manual phrases were already supplied. Echo them back unchanged in the "phrases" array.')
+  }
+
+  return [
+    ...instructions,
+    '',
+    `Company: ${ctx.companyName}`,
+    `Domain: ${ctx.domain}`,
+    `Existing audit summary: ${ctx.audit.summary}`,
+    '',
+    'Homepage text:',
+    ctx.siteText,
+  ].join('\n')
+}
+
+function buildBatchAnalysisPrompt(ctx: {
+  companyName: string
+  domain: string
+  profile: GeneratedSnapshotProfile
+  audit: SnapshotAuditDto
+  responses: Array<{
+    phrase: string
+    provider: string
+    displayName: string
+    heuristicMentioned: boolean
+    heuristicCited: boolean
+    heuristicCompetitors: string[]
+    citedDomains: string[]
+    groundingSources: string[]
+    answerText: string
+  }>
+  manualCompetitors: string[]
+}): string {
+  return [
+    'You are reviewing AI answer-engine responses for a sales-facing AEO snapshot report.',
+    'Use ONLY the provided facts and responses. Do not invent companies or claims.',
+    'Return strict JSON with keys: assessments, whatThisMeans, recommendedActions.',
+    'Each assessment must include: phrase, provider, mentioned, describedAccurately, accuracyNotes, incorrectClaims, recommendedCompetitors.',
+    'describedAccurately must be one of: yes, no, unknown, not-mentioned.',
+    'recommendedCompetitors should list actual competitor brands or domains named in the answer, not generic directories unless that is the only thing recommended.',
+    '',
+    `Target company: ${ctx.companyName}`,
+    `Target domain: ${ctx.domain}`,
+    `Industry: ${ctx.profile.industry}`,
+    `Summary: ${ctx.profile.summary}`,
+    `Services: ${ctx.profile.services.join(', ') || 'unknown'}`,
+    `Category terms: ${ctx.profile.categoryTerms.join(', ') || 'unknown'}`,
+    `Manual competitor hints: ${ctx.manualCompetitors.join(', ') || 'none'}`,
+    `Technical audit: ${ctx.audit.overallScore}/100 (${ctx.audit.overallGrade}) — ${ctx.audit.summary}`,
+    '',
+    'Responses JSON:',
+    JSON.stringify(ctx.responses, null, 2),
+  ].join('\n')
+}
+
+function buildFallbackBatchAssessment(companyName: string, audit: SnapshotAuditDto): BatchAssessment {
+  return {
+    assessments: [],
+    whatThisMeans: [
+      `${companyName} needs category-level visibility, not just branded comprehension.`,
+      `The technical baseline is ${audit.overallScore}/100 (${audit.overallGrade}), so weak site signals may be making AI systems prefer better-structured alternatives.`,
+    ],
+    recommendedActions: buildFallbackRecommendedActions(audit),
+  }
+}
+
+function applyBatchAssessment(
+  queryResults: SnapshotQueryResultDto[],
+  batchAssessment: BatchAssessment,
+): SnapshotQueryResultDto[] {
+  const assessmentMap = new Map<string, ResponseAssessment>()
+  for (const assessment of batchAssessment.assessments) {
+    assessmentMap.set(`${assessment.phrase}::${assessment.provider}`, assessment)
+  }
+
+  return queryResults.map(query => ({
+    phrase: query.phrase,
+    providerResults: query.providerResults.map(result => {
+      const assessment = assessmentMap.get(`${query.phrase}::${result.provider}`)
+      if (!assessment) {
+        return {
+          ...result,
+          describedAccurately: result.mentioned ? 'unknown' : 'not-mentioned',
+        }
+      }
+
+      const reviewedCompetitors = assessment.recommendedCompetitors
+      const recommendedCompetitors = reviewedCompetitors !== undefined
+        ? uniqueStrings(reviewedCompetitors)
+        : result.recommendedCompetitors
+
+      return {
+        ...result,
+        mentioned: result.mentioned || assessment.mentioned === true,
+        describedAccurately: assessment.describedAccurately
+          ?? (result.mentioned ? 'unknown' : 'not-mentioned'),
+        accuracyNotes: assessment.accuracyNotes ?? result.accuracyNotes ?? null,
+        incorrectClaims: uniqueStrings([
+          ...result.incorrectClaims,
+          ...(assessment.incorrectClaims ?? []),
+        ]),
+        recommendedCompetitors,
+      }
+    }),
+  }))
+}
+
+function buildSnapshotSummary(
+  companyName: string,
+  phrases: string[],
+  providers: RegisteredProvider[],
+  queryResults: SnapshotQueryResultDto[],
+  audit: SnapshotAuditDto,
+  batchAssessment: BatchAssessment,
+) {
+  const allResults = queryResults.flatMap(query => query.providerResults)
+  const successfulResults = allResults.filter(result => !result.error)
+  const failedComparisons = allResults.length - successfulResults.length
+  const mentionCount = successfulResults.filter(result => result.mentioned).length
+  const citationCount = successfulResults.filter(result => result.cited).length
+  const totalComparisons = successfulResults.length
+  const competitorCounts = new Map<string, number>()
+
+  for (const result of successfulResults) {
+    for (const competitor of result.recommendedCompetitors) {
+      competitorCounts.set(competitor, (competitorCounts.get(competitor) ?? 0) + 1)
+    }
+  }
+
+  const topCompetitors = [...competitorCounts.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, 10)
+    .map(([name, count]) => ({ name, count }))
+
+  const defaultMeaning = totalComparisons > 0
+    ? `${companyName} was mentioned in ${mentionCount}/${totalComparisons} successful provider-query response${totalComparisons === 1 ? '' : 's'} across ${phrases.length} category queries.`
+    : `No successful provider responses were returned across ${phrases.length} category queries.`
+  const failureNote = failedComparisons > 0
+    ? [
+        `${failedComparisons} provider response${failedComparisons === 1 ? '' : 's'} failed and ${failedComparisons === 1 ? 'was' : 'were'} excluded from visibility totals.`,
+      ]
+    : []
+  const whatThisMeans = batchAssessment.whatThisMeans.length > 0
+    ? batchAssessment.whatThisMeans
+    : [
+        defaultMeaning,
+      ]
+  const combinedWhatThisMeans = uniqueStrings([...whatThisMeans, ...failureNote]).slice(0, 5)
+
+  const recommendedActions = batchAssessment.recommendedActions.length > 0
+    ? batchAssessment.recommendedActions
+    : buildFallbackRecommendedActions(audit)
+
+  return {
+    totalQueries: phrases.length,
+    totalProviders: providers.length,
+    totalComparisons,
+    mentionCount,
+    citationCount,
+    topCompetitors,
+    visibilityGap: buildVisibilityGap(
+      companyName,
+      phrases.length,
+      providers.length,
+      totalComparisons,
+      mentionCount,
+      citationCount,
+      failedComparisons,
+    ),
+    whatThisMeans: combinedWhatThisMeans,
+    recommendedActions,
+  }
+}
+
+function buildVisibilityGap(
+  companyName: string,
+  queryCount: number,
+  providerCount: number,
+  totalComparisons: number,
+  mentionCount: number,
+  citationCount: number,
+  failedComparisons: number,
+): string {
+  const successfulLabel = `${totalComparisons} successful provider response${totalComparisons === 1 ? '' : 's'}`
+  const failureSuffix = failedComparisons > 0
+    ? ` ${failedComparisons} provider response${failedComparisons === 1 ? '' : 's'} failed.`
+    : ''
+  if (totalComparisons === 0) {
+    return `No providers returned successful answers across ${queryCount} category queries and ${providerCount} providers.${failureSuffix}`.trim()
+  }
+  if (mentionCount === 0) {
+    return `${companyName} was not mentioned in any of the ${successfulLabel} across ${queryCount} category queries and ${providerCount} providers.${failureSuffix}`.trim()
+  }
+  if (citationCount === 0) {
+    return `${companyName} was mentioned in ${mentionCount}/${totalComparisons} successful provider response${totalComparisons === 1 ? '' : 's'}, but never linked or cited directly.${failureSuffix}`.trim()
+  }
+  return `${companyName} was mentioned in ${mentionCount}/${totalComparisons} successful provider response${totalComparisons === 1 ? '' : 's'} and cited in ${citationCount}/${totalComparisons}.${failureSuffix}`.trim()
+}
+
+function buildFallbackRecommendedActions(audit: SnapshotAuditDto): string[] {
+  const weakestFactors = [...audit.factors]
+    .sort((a, b) => a.score - b.score || a.name.localeCompare(b.name))
+    .slice(0, 3)
+    .map(factor => `Improve ${factor.name.toLowerCase()}: ${formatAuditFactorScore(factor)}`)
+
+  const defaults = [
+    'Publish category pages that explicitly describe the services AI should recommend you for.',
+    'Add machine-readable trust signals such as schema, FAQs, and llms.txt support.',
+    'Build comparison and proof content that makes the category fit unmistakable.',
+  ]
+
+  return uniqueStrings([...weakestFactors, ...defaults]).slice(0, 4)
+}
+
+function mentionsTargetCompany(answerText: string, companyName: string, domain: string): boolean {
+  const haystack = normalizeText(answerText)
+  if (!haystack) return false
+
+  const fullName = normalizeText(companyName)
+  if (fullName && haystack.includes(fullName)) {
+    return true
+  }
+
+  const targetTokens = uniqueStrings([
+    ...extractDistinctiveTokens(companyName),
+    ...extractDistinctiveTokens(extractHostname(domain).split('.')[0] ?? ''),
+  ])
+
+  if (targetTokens.length === 0) return false
+  let matches = 0
+  for (const token of targetTokens) {
+    if (new RegExp(`\\b${escapeRegExp(token)}\\b`, 'i').test(answerText)) {
+      matches++
+    }
+  }
+
+  return matches >= Math.min(2, targetTokens.length) || matches >= 1 && targetTokens.length === 1
+}
+
+function citesTargetDomain(citedDomains: string[], groundingSources: GroundingSource[], targetDomain: string): boolean {
+  const normalizedTarget = extractHostname(targetDomain)
+  for (const domain of citedDomains) {
+    if (domainMatches(domain, normalizedTarget)) {
+      return true
+    }
+  }
+  for (const source of groundingSources) {
+    if (source.uri && source.uri.toLowerCase().includes(normalizedTarget.toLowerCase())) {
+      return true
+    }
+    if (source.title && source.title.toLowerCase().includes(normalizedTarget.toLowerCase())) {
+      return true
+    }
+  }
+  return false
+}
+
+function extractCompetitorsFromResponse(ctx: {
+  answerText: string
+  citedDomains: string[]
+  manualCompetitors: string[]
+  targetDomain: string
+}): string[] {
+  const competitors = new Set<string>()
+  const lowerAnswer = ctx.answerText.toLowerCase()
+  const targetDomain = extractHostname(ctx.targetDomain)
+
+  for (const hint of ctx.manualCompetitors) {
+    if (isDomainLike(hint)) {
+      const normalizedHint = normalizeDomain(hint)
+      if (domainMatches(normalizedHint, targetDomain)) continue
+      if (
+        ctx.citedDomains.some(domain => domainMatches(domain, normalizedHint))
+        || lowerAnswer.includes(normalizedHint.toLowerCase())
+      ) {
+        competitors.add(normalizedHint)
+      }
+      continue
+    }
+    if (hint.length >= 3 && lowerAnswer.includes(hint.toLowerCase())) {
+      competitors.add(hint)
+    }
+  }
+
+  return [...competitors].slice(0, 6)
+}
+
+function mapAuditReport(report: AeoAuditReport): SnapshotAuditDto {
+  return {
+    url: report.url,
+    finalUrl: report.finalUrl,
+    auditedAt: report.auditedAt,
+    overallScore: report.overallScore,
+    overallGrade: report.overallGrade,
+    summary: report.summary,
+    factors: report.factors.map(mapAuditFactor),
+  }
+}
+
+function mapAuditFactor(factor: AeoAuditFactor) {
+  return {
+    id: factor.id,
+    name: factor.name,
+    weight: factor.weight,
+    score: factor.score,
+    grade: factor.grade,
+    status: factor.status,
+    findings: factor.findings.map(finding => ({
+      type: finding.type,
+      message: finding.message,
+    })),
+    recommendations: factor.recommendations,
+  }
+}
+
+function parseJsonObject<T>(input: string): T {
+  const fenced = input.match(/```(?:json)?\s*([\s\S]*?)```/i)
+  const candidate = fenced?.[1] ?? input
+  const start = candidate.indexOf('{')
+  const end = candidate.lastIndexOf('}')
+  const json = start >= 0 && end >= start ? candidate.slice(start, end + 1) : candidate
+  return JSON.parse(json) as T
+}
+
+function normalizeText(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim()
+}
+
+function normalizeStringList(values: string[]): string[] {
+  const items = values.flatMap(value => value.split(','))
+  return uniqueStrings(
+    items
+      .map(value => value.trim())
+      .filter(Boolean),
+  )
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map(value => value.trim()).filter(Boolean))]
+}
+
+function normalizeDomain(value: string): string {
+  const trimmed = value.trim()
+  if (!trimmed) return trimmed
+  try {
+    const url = trimmed.includes('://') ? new URL(trimmed) : new URL(`https://${trimmed}`)
+    return url.hostname.replace(/^www\./, '').toLowerCase()
+  } catch {
+    return trimmed.replace(/^https?:\/\//, '').replace(/\/.*$/, '').replace(/^www\./, '').toLowerCase()
+  }
+}
+
+function extractHostname(value: string): string {
+  return normalizeDomain(value)
+}
+
+function domainMatches(candidate: string, target: string): boolean {
+  const normalizedCandidate = normalizeDomain(candidate)
+  const normalizedTarget = normalizeDomain(target)
+  return normalizedCandidate === normalizedTarget || normalizedCandidate.endsWith(`.${normalizedTarget}`)
+}
+
+function extractDistinctiveTokens(value: string): string[] {
+  return normalizeText(value)
+    .split(' ')
+    .filter(token => token.length >= 4)
+    .filter(token => !['llc', 'inc', 'corp', 'company', 'group', 'services', 'solutions', 'agency'].includes(token))
+}
+
+function isDomainLike(value: string): boolean {
+  const normalized = normalizeDomain(value)
+  return normalized.includes('.') && !normalized.includes(' ')
+}
+
+function clipText(value: string, length: number): string {
+  if (value.length <= length) return value
+  return `${value.slice(0, length - 3)}...`
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
diff --git a/packages/canonry/test/snapshot-command.test.ts b/packages/canonry/test/snapshot-command.test.ts
new file mode 100644
index 0000000..85fb403
--- /dev/null
+++ b/packages/canonry/test/snapshot-command.test.ts
@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import Fastify from 'fastify'
+import { createClient, migrate } from '@ainyc/canonry-db'
+import { apiRoutes } from '@ainyc/canonry-api-routes'
+import { invokeCli } from './cli-test-utils.js'
+import { formatSnapshotText } from '../src/commands/snapshot.js'
+import { writeSnapshotPdf } from '../src/snapshot-pdf.js'
+
+const SNAPSHOT_FIXTURE = {
+  companyName: 'Acme Corp',
+  domain: 'acme.example.com',
+  homepageUrl: 'https://acme.example.com',
+  generatedAt: '2026-03-29T12:00:00.000Z',
+  phrases: ['best enterprise widget provider', 'who offers enterprise widget support'],
+  competitors: ['widgetco.com', 'superwidgets.com'],
+  profile: {
+    industry: 'Manufacturing',
+    summary: 'Acme Corp sells enterprise widget manufacturing and support services.',
+    services: ['Widget manufacturing', 'Widget support'],
+    categoryTerms: ['enterprise widgets', 'widget support'],
+  },
+  audit: {
+    url: 'https://acme.example.com',
+    finalUrl: 'https://acme.example.com',
+    auditedAt: '2026-03-29T12:00:00.000Z',
+    overallScore: 58,
+    overallGrade: 'D+',
+    summary: 'Overall grade D+ with weak schema completeness.',
+    factors: [
+      {
+        id: 'schema-completeness',
+        name: 'Schema Completeness',
+        weight: 8,
+        score: 2,
+        grade: 'F',
+        status: 'fail',
+        findings: [{ type: 'missing', message: 'No Organization schema detected.' }],
+        recommendations: ['Add Organization and Service schema.'],
+      },
+    ],
+  },
+  queryResults: [
+    {
+      phrase: 'best enterprise widget provider',
+      providerResults: [
+        {
+          provider: 'openai',
+          displayName: 'OpenAI',
+          model: 'gpt-5.4',
+          mentioned: false,
+          cited: false,
+          describedAccurately: 'not-mentioned',
+          accuracyNotes: null,
+          incorrectClaims: [],
+          recommendedCompetitors: ['widgetco.com'],
+          citedDomains: ['widgetco.com'],
+          groundingSources: [],
+          searchQueries: ['best enterprise widget provider'],
+          answerText: 'WidgetCo is a strong option.',
+          error: null,
+        },
+      ],
+    },
+    {
+      phrase: 'who offers enterprise widget support',
+      providerResults: [
+        {
+          provider: 'claude',
+          displayName: 'Claude',
+          model: 'claude-sonnet-4-6',
+          mentioned: true,
+          cited: true,
+          describedAccurately: 'yes',
+          accuracyNotes: 'Acme appears with an accurate service description.',
+          incorrectClaims: [],
+          recommendedCompetitors: ['superwidgets.com'],
+          citedDomains: ['acme.example.com', 'superwidgets.com'],
+          groundingSources: [],
+          searchQueries: ['who offers enterprise widget support'],
+          answerText: 'Acme Corp provides enterprise widget support.',
+          error: null,
+        },
+      ],
+    },
+  ],
+  summary: {
+    totalQueries: 2,
+    totalProviders: 1,
+    totalComparisons: 2,
+    mentionCount: 1,
+    citationCount: 1,
+    topCompetitors: [
+      { name: 'widgetco.com', count: 1 },
+      { name: 'superwidgets.com', count: 1 },
+    ],
+    visibilityGap: 'Acme Corp was mentioned in 1/2 provider responses and cited in 1/2.',
+    whatThisMeans: ['Category visibility is inconsistent and competitors still win broad prompts.'],
+    recommendedActions: ['Add Organization and Service schema.'],
+  },
+}
+
+describe('snapshot command', () => {
+  let tmpDir: string
+  let app: ReturnType<typeof Fastify>
+  let originalConfigDir: string | undefined
+  let originalTelemetryDisabled: string | undefined
+  let originalCi: string | undefined
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `canonry-snapshot-${crypto.randomUUID()}`)
+    fs.mkdirSync(tmpDir, { recursive: true })
+
+    originalConfigDir = process.env.CANONRY_CONFIG_DIR
+    originalTelemetryDisabled = process.env.CANONRY_TELEMETRY_DISABLED
+    originalCi = process.env.CI
+    process.env.CANONRY_CONFIG_DIR = tmpDir
+    process.env.CANONRY_TELEMETRY_DISABLED = '1'
+    process.env.CI = '1'
+
+    const dbPath = path.join(tmpDir, 'test.db')
+    const db = createClient(dbPath)
+    migrate(db)
+
+    app = Fastify()
+    app.register(apiRoutes, {
+      db,
+      skipAuth: true,
+      onSnapshotRequested: async () => SNAPSHOT_FIXTURE,
+    })
+    await app.listen({ host: '127.0.0.1', port: 0 })
+
+    const address = app.server.address()
+    const port = typeof address === 'object' && address ? address.port : 0
+    fs.writeFileSync(
+      path.join(tmpDir, 'config.yaml'),
+      JSON.stringify({
+        apiUrl: `http://127.0.0.1:${port}`,
+        database: dbPath,
+        apiKey: 'cnry_test',
+        providers: {},
+      }),
+      'utf-8',
+    )
+  })
+
+  afterEach(async () => {
+    await app.close()
+    if (originalConfigDir === undefined) delete process.env.CANONRY_CONFIG_DIR
+    else process.env.CANONRY_CONFIG_DIR = originalConfigDir
+    if (originalTelemetryDisabled === undefined) delete process.env.CANONRY_TELEMETRY_DISABLED
+    else process.env.CANONRY_TELEMETRY_DISABLED = originalTelemetryDisabled
+    if (originalCi === undefined) delete process.env.CI
+    else process.env.CI = originalCi
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('prints snapshot JSON via the CLI', async () => {
+    const result = await invokeCli([
+      'snapshot',
+      'Acme Corp',
+      '--domain',
+      'acme.example.com',
+      '--format',
+      'json',
+    ])
+
+    expect(result.exitCode).toBe(undefined)
+    expect(result.stderr).toBe('')
+    const parsed = JSON.parse(result.stdout) as typeof SNAPSHOT_FIXTURE
+    expect(parsed.audit.overallScore).toBe(58)
+    expect(parsed.summary.topCompetitors[0]?.name).toBe('widgetco.com')
+  })
+
+  it('creates a PDF report when --pdf is provided', async () => {
+    const pdfPath = path.join(tmpDir, 'acme-snapshot.pdf')
+    const result = await invokeCli([
+      'snapshot',
+      'Acme Corp',
+      '--domain',
+      'acme.example.com',
+      '--pdf',
+      pdfPath,
+    ])
+
+    expect(result.exitCode).toBe(undefined)
+    expect(fs.existsSync(pdfPath)).toBe(true)
+    expect(fs.readFileSync(pdfPath).subarray(0, 5).toString('utf-8')).toBe('%PDF-')
+    expect(result.stdout).toContain('PDF saved:')
+  })
+
+  it('formats text output with visibility and competitor details', () => {
+    const text = formatSnapshotText(SNAPSHOT_FIXTURE)
+    expect(text).toContain('AEO audit: 58/100 (D+)')
+    expect(text).toContain('Top competitors AI recommended instead: widgetco.com (1), superwidgets.com (1)')
+    expect(text).toContain('OpenAI')
+    expect(text).toContain('recommended instead: widgetco.com')
+  })
+
+  it('writes a standalone PDF report', async () => {
+    const pdfPath = path.join(tmpDir, 'standalone.pdf')
+    const savedPath = await writeSnapshotPdf(SNAPSHOT_FIXTURE, pdfPath)
+
+    expect(savedPath).toBe(pdfPath)
+    expect(fs.readFileSync(savedPath).subarray(0, 5).toString('utf-8')).toBe('%PDF-')
+  })
+})
diff --git a/packages/canonry/test/snapshot-service.test.ts b/packages/canonry/test/snapshot-service.test.ts
new file mode 100644
index 0000000..2ef8b1f
--- /dev/null
+++ b/packages/canonry/test/snapshot-service.test.ts
@@ -0,0 +1,210 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import type {
+  GroundingSource,
+  NormalizedQueryResult,
+  ProviderAdapter,
+  ProviderConfig,
+  ProviderHealthcheckResult,
+  RawQueryResult,
+  TrackedQueryInput,
+} from '@ainyc/canonry-contracts'
+import { ProviderRegistry } from '../src/provider-registry.js'
+import { SnapshotService } from '../src/snapshot-service.js'
+import { formatAuditFactorScore } from '../src/snapshot-format.js'
+
+const { fetchSiteTextMock, runAeoAuditMock } = vi.hoisted(() => ({
+  fetchSiteTextMock: vi.fn(),
+  runAeoAuditMock: vi.fn(),
+}))
+
+vi.mock('../src/site-fetch.js', () => ({
+  fetchSiteText: fetchSiteTextMock,
+}))
+
+vi.mock('@ainyc/aeo-audit', () => ({
+  runAeoAudit: runAeoAuditMock,
+}))
+
+type TestProviderOptions = {
+  name: string
+  displayName: string
+  executeResult?: RawQueryResult
+  executeError?: Error
+  generatedText?: string[]
+}
+
+function makeConfig(name: string): ProviderConfig {
+  return {
+    provider: name,
+    apiKey: 'test-key',
+    quotaPolicy: {
+      maxConcurrency: 1,
+      maxRequestsPerMinute: 60,
+      maxRequestsPerDay: 500,
+    },
+  }
+}
+
+function healthcheck(name: string): ProviderHealthcheckResult {
+  return {
+    ok: true,
+    provider: name,
+    message: 'ok',
+  }
+}
+
+function normalizeRawResult(name: string, raw: RawQueryResult): NormalizedQueryResult {
+  const body = raw.rawResponse as {
+    answerText?: string
+    citedDomains?: string[]
+    groundingSources?: GroundingSource[]
+  }
+
+  return {
+    provider: name,
+    answerText: body.answerText ?? '',
+    citedDomains: body.citedDomains ?? [],
+    groundingSources: body.groundingSources ?? raw.groundingSources,
+    searchQueries: raw.searchQueries,
+  }
+}
+
+function makeAdapter(opts: TestProviderOptions): ProviderAdapter {
+  const generatedText = [...(opts.generatedText ?? [])]
+
+  return {
+    name: opts.name,
+    displayName: opts.displayName,
+    mode: 'api',
+    modelRegistry: {
+      defaultModel: `${opts.name}-model`,
+      validationPattern: /./,
+      validationHint: 'any model',
+      knownModels: [{ id: `${opts.name}-model`, displayName: `${opts.displayName} Model`, tier: 'standard' }],
+    },
+    validateConfig: () => healthcheck(opts.name),
+    healthcheck: async () => healthcheck(opts.name),
+    executeTrackedQuery: async (_input: TrackedQueryInput) => {
+      if (opts.executeError) throw opts.executeError
+      if (!opts.executeResult) throw new Error(`No execute result configured for ${opts.name}`)
+      return opts.executeResult
+    },
+    normalizeResult: (raw) => normalizeRawResult(opts.name, raw),
+    generateText: async () => {
+      const next = generatedText.shift()
+      if (next === undefined) throw new Error(`Unexpected generateText call for ${opts.name}`)
+      return next
+    },
+  }
+}
+
+function makeRawQueryResult(name: string, response: {
+  answerText: string
+  citedDomains?: string[]
+  groundingSources?: GroundingSource[]
+  searchQueries?: string[]
+}): RawQueryResult {
+  return {
+    provider: name,
+    model: `${name}-model`,
+    rawResponse: {
+      answerText: response.answerText,
+      citedDomains: response.citedDomains ?? [],
+      groundingSources: response.groundingSources ?? [],
+    },
+    groundingSources: response.groundingSources ?? [],
+    searchQueries: response.searchQueries ?? ['best widget vendor'],
+  }
+}
+
+describe('SnapshotService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    fetchSiteTextMock.mockResolvedValue('Acme Corp builds enterprise widgets and provides support.')
+    runAeoAuditMock.mockResolvedValue({
+      url: 'https://acme.example.com',
+      finalUrl: 'https://acme.example.com',
+      auditedAt: '2026-03-29T12:00:00.000Z',
+      overallScore: 58,
+      overallGrade: 'D+',
+      summary: 'Overall grade D+ with weak schema completeness.',
+      factors: [
+        {
+          id: 'schema-completeness',
+          name: 'Schema Completeness',
+          weight: 8,
+          score: 2,
+          grade: 'F',
+          status: 'fail',
+          findings: [],
+          recommendations: ['Add Organization and Service schema.'],
+        },
+      ],
+    })
+  })
+
+  it('excludes provider failures from visibility totals and trusts reviewed competitor lists', async () => {
+    const registry = new ProviderRegistry()
+    registry.register(makeAdapter({
+      name: 'openai',
+      displayName: 'OpenAI',
+      executeResult: makeRawQueryResult('openai', {
+        answerText: 'Industry sources compare widget vendors and cite nytimes.com.',
+        citedDomains: ['nytimes.com'],
+        groundingSources: [{ uri: 'https://nytimes.com/review/widgets', title: 'Widget review' }],
+      }),
+      generatedText: [
+        JSON.stringify({
+          industry: 'Manufacturing',
+          summary: 'Acme sells enterprise widget services.',
+          services: ['Widget manufacturing'],
+          categoryTerms: ['enterprise widgets'],
+          phrases: ['best enterprise widget vendor'],
+        }),
+        JSON.stringify({
+          assessments: [
+            {
+              phrase: 'best enterprise widget vendor',
+              provider: 'openai',
+              mentioned: false,
+              describedAccurately: 'not-mentioned',
+              accuracyNotes: null,
+              incorrectClaims: [],
+              recommendedCompetitors: [],
+            },
+          ],
+          whatThisMeans: [],
+          recommendedActions: [],
+        }),
+      ],
+    }), makeConfig('openai'))
+    registry.register(makeAdapter({
+      name: 'claude',
+      displayName: 'Claude',
+      executeError: new Error('rate limited'),
+    }), makeConfig('claude'))
+
+    const service = new SnapshotService(registry)
+    const report = await service.createReport({
+      companyName: 'Acme Corp',
+      domain: 'acme.example.com',
+    })
+
+    expect(report.summary.totalComparisons).toBe(1)
+    expect(report.summary.mentionCount).toBe(0)
+    expect(report.summary.visibilityGap).toContain('1 successful provider response')
+    expect(report.summary.visibilityGap).toContain('1 provider response failed')
+    expect(report.summary.whatThisMeans).toContain(
+      '1 provider response failed and was excluded from visibility totals.',
+    )
+    expect(report.queryResults[0]?.providerResults[0]?.recommendedCompetitors).toEqual([])
+    expect(report.summary.topCompetitors).toEqual([])
+    expect(report.summary.recommendedActions).toContain(
+      'Improve schema completeness: 2/100 (8% weight)',
+    )
+  })
+
+  it('formats audit factor scores with a 100-point denominator and explicit weight', () => {
+    expect(formatAuditFactorScore({ score: 2, weight: 8 })).toBe('2/100 (8% weight)')
+  })
+})
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index 37069ef..3e2d144 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -8,6 +8,7 @@ export * from './notification.js'
 export * from './project.js'
 export * from './provider.js'
 export * from './run.js'
+export * from './snapshot.js'
 export * from './schedule.js'
 export * from './analytics.js'
 export * from './source-categories.js'
diff --git a/packages/contracts/src/snapshot.ts b/packages/contracts/src/snapshot.ts
new file mode 100644
index 0000000..4c291e7
--- /dev/null
+++ b/packages/contracts/src/snapshot.ts
@@ -0,0 +1,113 @@
+import { z } from 'zod'
+import { groundingSourceSchema } from './run.js'
+
+export const snapshotAccuracySchema = z.enum(['yes', 'no', 'unknown', 'not-mentioned'])
+export type SnapshotAccuracy = z.infer<typeof snapshotAccuracySchema>
+
+export const snapshotRequestSchema = z.object({
+  companyName: z.string().min(1),
+  domain: z.string().min(1),
+  phrases: z.array(z.string().min(1)).optional().default([]),
+  competitors: z.array(z.string().min(1)).optional().default([]),
+})
+
+export type SnapshotRequestDto = z.infer<typeof snapshotRequestSchema>
+
+export const snapshotCompetitorEntrySchema = z.object({
+  name: z.string(),
+  count: z.number().int().nonnegative(),
+})
+
+export type SnapshotCompetitorEntryDto = z.infer<typeof snapshotCompetitorEntrySchema>
+
+export const snapshotAuditFactorSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  weight: z.number(),
+  score: z.number(),
+  grade: z.string(),
+  status: z.enum(['pass', 'partial', 'fail']),
+  findings: z.array(z.object({
+    type: z.string(),
+    message: z.string(),
+  })).default([]),
+  recommendations: z.array(z.string()).default([]),
+})
+
+export type SnapshotAuditFactorDto = z.infer<typeof snapshotAuditFactorSchema>
+
+export const snapshotAuditSchema = z.object({
+  url: z.string(),
+  finalUrl: z.string(),
+  auditedAt: z.string(),
+  overallScore: z.number(),
+  overallGrade: z.string(),
+  summary: z.string(),
+  factors: z.array(snapshotAuditFactorSchema).default([]),
+})
+
+export type SnapshotAuditDto = z.infer<typeof snapshotAuditSchema>
+
+export const snapshotProfileSchema = z.object({
+  industry: z.string(),
+  summary: z.string(),
+  services: z.array(z.string()).default([]),
+  categoryTerms: z.array(z.string()).default([]),
+})
+
+export type SnapshotProfileDto = z.infer<typeof snapshotProfileSchema>
+
+export const snapshotProviderResultSchema = z.object({
+  provider: z.string(),
+  displayName: z.string(),
+  model: z.string().nullable().optional(),
+  mentioned: z.boolean(),
+  cited: z.boolean(),
+  describedAccurately: snapshotAccuracySchema,
+  accuracyNotes: z.string().nullable().optional(),
+  incorrectClaims: z.array(z.string()).default([]),
+  recommendedCompetitors: z.array(z.string()).default([]),
+  citedDomains: z.array(z.string()).default([]),
+  groundingSources: z.array(groundingSourceSchema).default([]),
+  searchQueries: z.array(z.string()).default([]),
+  answerText: z.string(),
+  error: z.string().nullable().optional(),
+})
+
+export type SnapshotProviderResultDto = z.infer<typeof snapshotProviderResultSchema>
+
+export const snapshotQueryResultSchema = z.object({
+  phrase: z.string(),
+  providerResults: z.array(snapshotProviderResultSchema).default([]),
+})
+
+export type SnapshotQueryResultDto = z.infer<typeof snapshotQueryResultSchema>
+
+export const snapshotSummarySchema = z.object({
+  totalQueries: z.number().int().nonnegative(),
+  totalProviders: z.number().int().nonnegative(),
+  totalComparisons: z.number().int().nonnegative(),
+  mentionCount: z.number().int().nonnegative(),
+  citationCount: z.number().int().nonnegative(),
+  topCompetitors: z.array(snapshotCompetitorEntrySchema).default([]),
+  visibilityGap: z.string(),
+  whatThisMeans: z.array(z.string()).default([]),
+  recommendedActions: z.array(z.string()).default([]),
+})
+
+export type SnapshotSummaryDto = z.infer<typeof snapshotSummarySchema>
+
+export const snapshotReportSchema = z.object({
+  companyName: z.string(),
+  domain: z.string(),
+  homepageUrl: z.string(),
+  generatedAt: z.string(),
+  phrases: z.array(z.string()).default([]),
+  competitors: z.array(z.string()).default([]),
+  profile: snapshotProfileSchema,
+  audit: snapshotAuditSchema,
+  queryResults: z.array(snapshotQueryResultSchema).default([]),
+  summary: snapshotSummarySchema,
+})
+
+export type SnapshotReportDto = z.infer<typeof snapshotReportSchema>
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ce500d2..d64dbf4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -178,6 +178,9 @@ importers:
 
   packages/canonry:
     dependencies:
+      '@ainyc/aeo-audit':
+        specifier: 1.3.2
+        version: 1.3.2
       '@anthropic-ai/sdk':
         specifier: ^0.78.0
         version: 0.78.0(zod@4.3.6)
@@ -205,6 +208,9 @@ importers:
       openai:
         specifier: ^6.0.0
         version: 6.27.0(ws@8.20.0)(zod@4.3.6)
+      pdf-lib:
+        specifier: ^1.17.1
+        version: 1.17.1
       pino-pretty:
         specifier: ^13.1.3
         version: 13.1.3
@@ -980,6 +986,12 @@ packages:
     resolution: {integrity: sha512-9I2Zn6+NJLfaGoz9jN3lpwDgAYvfGeNYdbAIjJOqzs4Tpc+VU3Jqq4IofSUBKajiDS8k9fZIg18/z13mpk1bsA==}
     engines: {node: '>=8'}
 
+  '@pdf-lib/standard-fonts@1.0.0':
+    resolution: {integrity: sha512-hU30BK9IUN/su0Mn9VdlVKsWBS6GyhVfqjwl1FjZN4TxP6cCw0jP2w7V3Hf5uX7M0AZJ16vey9yE0ny7Sa59ZA==}
+
+  '@pdf-lib/upng@1.0.1':
+    resolution: {integrity: sha512-dQK2FUMQtowVP00mtIksrlZhdFXQZPC+taih1q4CvPZ5vqdxR/LKBaFg0oAfzd1GlHZXXSPdQfzQnt+ViGvEIQ==}
+
   '@pinojs/redact@0.4.0':
     resolution: {integrity: sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==}
 
@@ -2802,6 +2814,9 @@ packages:
   package-json-from-dist@1.0.1:
     resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
 
+  pako@1.0.11:
+    resolution: {integrity: sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==}
+
   parent-module@1.0.1:
     resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
     engines: {node: '>=6'}
@@ -2833,6 +2848,9 @@ packages:
   pathe@2.0.3:
     resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==}
 
+  pdf-lib@1.17.1:
+    resolution: {integrity: sha512-V/mpyJAoTsN4cnP31vc0wfNA1+p20evqqnap0KLoRUN0Yk/p3wN52DOEsL4oBFcLdb76hlpKPtzJIgo67j/XLw==}
+
   picocolors@1.1.1:
     resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
 
@@ -3236,6 +3254,9 @@ packages:
   ts-interface-checker@0.1.13:
     resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==}
 
+  tslib@1.14.1:
+    resolution: {integrity: sha512-Xni35NKzjgMrwevysHTCArtLDpPvye8zV/0E4EyYn43P7/7qvQwPh9BGkHewbMulVntbigmcT7rdX3BNo9wRJg==}
+
   tslib@2.8.1:
     resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
 
@@ -3291,10 +3312,6 @@ packages:
   undici-types@7.16.0:
     resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
 
-  undici@7.24.2:
-    resolution: {integrity: sha512-P9J1HWYV/ajFr8uCqk5QixwiRKmB1wOamgS0e+o2Z4A44Ej2+thFVRLG/eA7qprx88XXhnV5Bl8LHXTURpzB3Q==}
-    engines: {node: '>=20.18.1'}
-
   undici@7.24.4:
     resolution: {integrity: sha512-BM/JzwwaRXxrLdElV2Uo6cTLEjhSb3WXboncJamZ15NgUURmvlXvxa6xkwIOILIjPNo9i8ku136ZvWV0Uly8+w==}
     engines: {node: '>=20.18.1'}
@@ -3989,6 +4006,14 @@ snapshots:
 
   '@lukeed/ms@2.0.2': {}
 
+  '@pdf-lib/standard-fonts@1.0.0':
+    dependencies:
+      pako: 1.0.11
+
+  '@pdf-lib/upng@1.0.1':
+    dependencies:
+      pako: 1.0.11
+
   '@pinojs/redact@0.4.0': {}
 
   '@protobufjs/aspromise@1.1.2': {}
@@ -4753,7 +4778,7 @@ snapshots:
       parse5: 7.3.0
       parse5-htmlparser2-tree-adapter: 7.1.0
       parse5-parser-stream: 7.1.2
-      undici: 7.24.2
+      undici: 7.24.4
       whatwg-mimetype: 4.0.0
 
   chokidar@4.0.3:
@@ -5684,6 +5709,8 @@ snapshots:
 
   package-json-from-dist@1.0.1: {}
 
+  pako@1.0.11: {}
+
   parent-module@1.0.1:
     dependencies:
       callsites: 3.1.0
@@ -5716,6 +5743,13 @@ snapshots:
 
   pathe@2.0.3: {}
 
+  pdf-lib@1.17.1:
+    dependencies:
+      '@pdf-lib/standard-fonts': 1.0.0
+      '@pdf-lib/upng': 1.0.1
+      pako: 1.0.11
+      tslib: 1.14.1
+
   picocolors@1.1.1: {}
 
   picomatch@4.0.3: {}
@@ -6111,6 +6145,8 @@ snapshots:
 
   ts-interface-checker@0.1.13: {}
 
+  tslib@1.14.1: {}
+
   tslib@2.8.1: {}
 
   tsup@8.5.1(jiti@2.6.1)(postcss@8.5.8)(tsx@4.21.0)(typescript@5.9.3)(yaml@2.8.2):
@@ -6175,8 +6211,6 @@ snapshots:
 
   undici-types@7.16.0: {}
 
-  undici@7.24.2: {}
-
   undici@7.24.4: {}
 
   update-browserslist-db@1.2.3(browserslist@4.28.1):
diff --git a/skills/canonry-setup/references/canonry-cli.md b/skills/canonry-setup/references/canonry-cli.md
index ffebeeb..16af395 100644
--- a/skills/canonry-setup/references/canonry-cli.md
+++ b/skills/canonry-setup/references/canonry-cli.md
@@ -44,6 +44,10 @@ canonry project remove-location <name> <label>
 ## Sweeps
 
 ```bash
+canonry snapshot "Acme Corp" --domain acme.example.com      # one-shot sales snapshot
+canonry snapshot "Acme Corp" --domain acme.example.com --pdf ./acme.pdf
+canonry snapshot "Acme Corp" --domain acme.example.com --format json
+
 canonry run <project>                             # sweep all configured providers
 canonry run <project> --provider gemini           # single provider only
 canonry run <project> --wait                      # block until complete
@@ -60,6 +64,8 @@ Run statuses: `queued` → `running` → `completed` / `failed` / `partial`
 
 `partial` = some providers failed (usually rate limits) — successful snapshots are still saved.
 
+`snapshot` does not create a project or write to the DB. It generates category queries, runs providers, and produces a report for prospecting.
+
 ## Citation Data
 
 ```bash