@purveyors/cli 0.33.3 → 0.35.0

package/dist/lib/manifest.js

@@ -84,7 +84,12 @@ const idTypes = [
     {
         name: 'roast_id',
         source: 'roast_data row',
-        usedBy: ['roast get/delete', 'roast list --roast-id', 'sales record --roast-id'],
+        usedBy: [
+            'roast get/chart/delete',
+            'roast list --roast-id',
+            'sales record --roast-id',
+            'reference-profile compare roast:<roast-id>',
+        ],
     },
     {
         name: 'sale_id',
@@ -99,6 +104,7 @@ const idTypes = [
             'reference-profile chart',
             'reference-profile preview/save',
             'reference-profile export',
+            'reference-profile compare profile:<uuid>',
         ],
     },
     {
@@ -108,6 +114,7 @@ const idTypes = [
             'reference-profile chart',
             'reference-profile preview/save',
             'reference-profile export',
+            'reference-profile compare revision:<uuid>',
         ],
     },
 ];
@@ -121,6 +128,7 @@ const commandGroups = [
                 name: 'login',
                 summary: 'Log in to purveyors.io',
                 auth: 'none',
+                sdkMethods: ['cliAuth.create', 'cliAuth.exchange'],
                 options: [
                     { flags: '--headless', description: 'Print approval URL without opening a browser' },
                 ],
@@ -130,6 +138,7 @@ const commandGroups = [
                 name: 'status',
                 summary: 'Show current login status and role',
                 auth: 'none',
+                sdkMethods: ['me'],
                 options: [{ flags: '--pretty' }, { flags: '--csv' }],
                 examples: [
                     'purvey auth status',
@@ -137,6 +146,21 @@ const commandGroups = [
                     'purvey auth status --json',
                 ],
             },
+            {
+                name: 'whoami',
+                summary: 'Show the canonical identity, plan, scopes, and capabilities for the active credential',
+                auth: 'none',
+                sdkMethods: ['me'],
+                notes: [
+                    'Prints the GET /v1/me response unchanged, including capabilities.profileStudio.',
+                    'Uses PARCHMENT_API_KEY or PURVEYORS_API_KEY when set, otherwise the stored login key.',
+                    'Without a credential it prints the anonymous principal (authenticated: false).',
+                ],
+                examples: [
+                    'purvey auth whoami --pretty',
+                    "purvey auth whoami | jq '.capabilities.profileStudio'",
+                ],
+            },
             {
                 name: 'logout',
                 summary: 'Clear stored credentials',
@@ -154,6 +178,7 @@ const commandGroups = [
                 name: 'search',
                 summary: 'Search coffees by origin, process, price, and catalog metadata; structured process filters require member access',
                 auth: 'viewer',
+                sdkMethods: ['catalog.list'],
                 options: [
                     { flags: '--origin <origin>' },
                     { flags: '--process <method>' },
@@ -168,6 +193,18 @@ const commandGroups = [
                     { flags: '--ids <n,n,...>' },
                     { flags: '--variety <text>' },
                     { flags: '--stocked-days <n>' },
+                    {
+                        flags: '--supplier <name>',
+                        description: 'Canonical /v1/catalog supplier filter (partial source-name match)',
+                    },
+                    {
+                        flags: '--drying-method <method>',
+                        description: 'Canonical /v1/catalog dryingMethod filter; Parchment owns matching',
+                    },
+                    {
+                        flags: '--flavor <keywords>',
+                        description: 'Comma-separated canonical /v1/catalog flavorKeywords; a row matches any keyword',
+                    },
                     { flags: '--stocked' },
                     { flags: '--sort <field>' },
                     { flags: '--offset <n>', defaultValue: 0 },
@@ -202,6 +239,7 @@ const commandGroups = [
                     'purvey catalog search --process-additive "hops" --processing-confidence-min 0.8 --pretty',
                     'purvey catalog search --variety "gesha" --stocked --pretty',
                     'purvey catalog search --stocked-days 30 --pretty',
+                    'purvey catalog search --supplier "Royal" --flavor "blueberry,jasmine" --stocked --pretty',
                     'purvey catalog search --origin "Ethiopia" --include-proof --json',
                 ],
             },
@@ -209,6 +247,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get details for a specific coffee by ID',
                 auth: 'viewer',
+                sdkMethods: ['catalog.list'],
                 arguments: [
                     {
                         name: 'catalog_id',
@@ -236,17 +275,19 @@ const commandGroups = [
                 name: 'stats',
                 summary: 'Aggregate statistics for the catalog',
                 auth: 'viewer',
+                sdkMethods: ['catalog.stats'],
                 examples: ['purvey catalog stats --pretty'],
             },
             {
                 name: 'facets',
-                summary: 'List distinct catalog facet values with counts',
+                summary: 'List counted catalog facet values for filter discovery',
                 auth: 'viewer',
+                sdkMethods: ['catalog.facets'],
                 arguments: [
                     {
                         name: 'field',
-                        description: 'facet field: supplier, country, processing_base_method, fermentation_type, drying_method, grade, wholesale',
-                        required: true,
+                        description: 'optional facet field: supplier, country, processing_base_method, fermentation_type, drying_method, grade, wholesale',
+                        required: false,
                     },
                 ],
                 options: [
@@ -254,24 +295,30 @@ const commandGroups = [
                         flags: '--all',
                         description: 'Use all visible catalog rows instead of the default stocked-only scope.',
                     },
-                    { flags: '--limit <n>', defaultValue: 60 },
                 ],
                 notes: [
-                    'Counts values from catalog rows visible to the current client.',
+                    'Without a field, prints the canonical /v1/catalog/facets envelope (values, facets, meta) unchanged.',
+                    "With a field, prints { field, facet, data, meta }: that facet's counted values and Parchment's meta.",
+                    'Counts are computed by Parchment; counts for multi-valued dimensions can overlap, so do not sum them.',
                     'Defaults to currently stocked catalog rows; use --all for all visible rows.',
-                    'Output metadata reports stocked_only/scope, rows_examined, and truncation for deterministic agent use.',
                 ],
                 examples: [
                     'purvey catalog facets supplier --pretty',
-                    'purvey catalog facets country --limit 25 --json',
+                    'purvey catalog facets country --all --json',
+                    'purvey catalog facets --pretty',
                 ],
             },
             {
                 name: 'rank',
                 summary: 'Rank catalog candidates by deterministic objective',
                 auth: 'viewer',
+                sdkMethods: ['catalog.rank'],
                 options: [
                     { flags: '--objective <objective>', defaultValue: 'premium' },
+                    {
+                        flags: '--supplier <name>',
+                        description: 'Canonical /v1/catalog/rank supplier filter',
+                    },
                     { flags: '--country <country>' },
                     { flags: '--process <method>' },
                     { flags: '--stocked' },
@@ -296,12 +343,14 @@ const commandGroups = [
                 examples: [
                     'purvey catalog rank --objective premium --stocked --pretty',
                     'purvey catalog rank --objective value --country Ethiopia --price-max 12 --json',
+                    'purvey catalog rank --objective premium --supplier "Royal Coffee" --limit 5 --json',
                 ],
             },
             {
                 name: 'rank-premium',
                 summary: 'Rank premium catalog candidates by Purveyor Score',
                 auth: 'viewer',
+                sdkMethods: ['catalog.rankPremium'],
                 options: [
                     { flags: '--origin <origin>' },
                     { flags: '--process <method>' },
@@ -326,6 +375,7 @@ const commandGroups = [
                 name: 'supplier-list',
                 summary: 'List supplier aggregates from catalog rows',
                 auth: 'viewer',
+                sdkMethods: ['catalog.suppliers'],
                 options: [
                     { flags: '--country <country>' },
                     { flags: '--stocked' },
@@ -344,6 +394,7 @@ const commandGroups = [
                 name: 'supplier-detail',
                 summary: 'Show aggregate detail for a supplier query',
                 auth: 'viewer',
+                sdkMethods: ['catalog.supplierDetail'],
                 arguments: [
                     {
                         name: 'supplier',
@@ -368,6 +419,7 @@ const commandGroups = [
                 name: 'supplier-rank',
                 summary: 'Rank suppliers by average Purveyor Score and stocked coverage',
                 auth: 'viewer',
+                sdkMethods: ['catalog.supplierRank'],
                 options: [
                     { flags: '--country <country>' },
                     { flags: '--stocked' },
@@ -395,6 +447,7 @@ const commandGroups = [
                 name: 'similar',
                 summary: 'Fetch beta canonical /v1/catalog/{id}/similar groups for likely same-lot candidates and similar recommendations',
                 auth: 'member',
+                sdkMethods: ['catalog.similar'],
                 arguments: [
                     {
                         name: 'catalog_id',
@@ -441,6 +494,7 @@ const commandGroups = [
                 name: 'list',
                 summary: 'List your green coffee inventory with catalog details',
                 auth: 'member',
+                sdkMethods: ['inventory.list'],
                 options: [
                     { flags: '--stocked' },
                     { flags: '--catalog-id <id>' },
@@ -464,6 +518,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get a single inventory item',
                 auth: 'member',
+                sdkMethods: ['inventory.list'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -479,8 +534,17 @@ const commandGroups = [
                 name: 'add',
                 summary: 'Add a bean to your inventory',
                 auth: 'member',
+                sdkMethods: ['inventory.create'],
+                confirmedActionEquivalents: ['add_bean_to_inventory'],
                 options: [
-                    { flags: '--catalog-id <id>', requiredInFlagMode: true },
+                    {
+                        flags: '--catalog-id <id>',
+                        description: 'Catalog lot to add; exactly one of --catalog-id or --manual-name',
+                    },
+                    {
+                        flags: '--manual-name <name>',
+                        description: 'Coffee name for a lot that is not in the catalog',
+                    },
                     { flags: '--qty <lbs>', requiredInFlagMode: true },
                     { flags: '--cost <dollars>' },
                     { flags: '--tax-ship <dollars>' },
@@ -488,12 +552,21 @@ const commandGroups = [
                     { flags: '--purchase-date <YYYY-MM-DD>' },
                     { flags: '--form' },
                 ],
-                examples: ['purvey inventory add --catalog-id 128 --qty 10 --cost 8.50 --pretty'],
+                notes: [
+                    'Flag mode requires --qty and exactly one of --catalog-id or --manual-name.',
+                    '--manual-name creates a manual coffee record when Parchment has manual inventory writes enabled.',
+                ],
+                examples: [
+                    'purvey inventory add --catalog-id 128 --qty 10 --cost 8.50 --pretty',
+                    'purvey inventory add --manual-name "Farm-gate Ethiopia lot 7" --qty 12 --cost 96 --pretty',
+                ],
             },
             {
                 name: 'update',
                 summary: 'Update an inventory item',
                 auth: 'member',
+                sdkMethods: ['inventory.update'],
+                confirmedActionEquivalents: ['update_bean'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -509,12 +582,14 @@ const commandGroups = [
                     { flags: '--tax-ship <dollars>' },
                     { flags: '--notes <text>' },
                     { flags: '--stocked <true|false>' },
+                    { flags: '--rank <n>', description: 'Owner-assigned integer rank for this lot' },
                 ],
             },
             {
                 name: 'delete',
                 summary: 'Delete an inventory item',
                 auth: 'member',
+                sdkMethods: ['inventory.delete'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -537,6 +612,7 @@ const commandGroups = [
                 name: 'list',
                 summary: 'List your roast profiles, sorted by date',
                 auth: 'member',
+                sdkMethods: ['roasts.list'],
                 options: [
                     { flags: '--coffee-id <id>' },
                     { flags: '--roast-id <id>' },
@@ -561,6 +637,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get a single roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.get'],
                 arguments: [
                     {
                         name: 'roast_id',
@@ -572,10 +649,43 @@ const commandGroups = [
                 ],
                 options: [{ flags: '--include-temps' }, { flags: '--include-events' }],
             },
+            {
+                name: 'chart',
+                summary: 'Fetch the sampled chart model for one roast (series, events, revision)',
+                auth: 'member',
+                sdkMethods: ['roasts.chartData'],
+                arguments: [
+                    {
+                        name: 'roast_id',
+                        cliToken: 'id',
+                        description: 'roast_data.roast_id',
+                        required: true,
+                        idType: 'roast_id',
+                    },
+                ],
+                options: [
+                    {
+                        flags: '--target-points <n>',
+                        description: 'Approximate samples per series, 50-1000; Parchment defaults to 400',
+                        minimum: 50,
+                        maximum: 1000,
+                    },
+                ],
+                notes: [
+                    "Returns Parchment's canonical chart-data envelope unchanged: sampled series, events, and metadata.",
+                    'data.metadata.revision identifies the immutable chart revision used by reference-profile compare.',
+                ],
+                examples: [
+                    'purvey roast chart 123 --pretty',
+                    "purvey roast chart 123 --target-points 120 | jq '.data.metadata.revision'",
+                ],
+            },
             {
                 name: 'create',
                 summary: 'Create a new roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.create'],
+                confirmedActionEquivalents: ['create_roast_session'],
                 options: [
                     { flags: '--coffee-id <id>', requiredInFlagMode: true },
                     { flags: '--batch-name <name>' },
@@ -583,6 +693,8 @@ const commandGroups = [
                     { flags: '--oz-out <oz>' },
                     { flags: '--roast-date <YYYY-MM-DD>' },
                     { flags: '--notes <text>' },
+                    { flags: '--targets <text>' },
+                    { flags: '--roaster-type <text>' },
                     { flags: '--form' },
                 ],
             },
@@ -590,6 +702,8 @@ const commandGroups = [
                 name: 'update',
                 summary: 'Update a roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.update'],
+                confirmedActionEquivalents: ['update_roast_notes'],
                 arguments: [
                     {
                         name: 'roast_id',
@@ -610,6 +724,7 @@ const commandGroups = [
                 name: 'delete',
                 summary: 'Delete a roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.delete'],
                 arguments: [
                     {
                         name: 'roast_id',
@@ -625,6 +740,7 @@ const commandGroups = [
                 name: 'import',
                 summary: 'Import an Artisan .alog roast file',
                 auth: 'member',
+                sdkMethods: ['roasts.import'],
                 arguments: [{ name: 'file', description: 'Path to Artisan .alog file', required: false }],
                 options: [
                     { flags: '--coffee-id <id>', requiredInFlagMode: true },
@@ -639,6 +755,7 @@ const commandGroups = [
                 name: 'watch',
                 summary: 'Watch a directory for new Artisan .alog files',
                 auth: 'member',
+                sdkMethods: ['roasts.import', 'inventory.list', 'roasts.classify'],
                 arguments: [{ name: 'directory', description: 'Directory to watch', required: false }],
                 options: [
                     { flags: '--coffee-id <inventory_id>' },
@@ -669,6 +786,7 @@ const commandGroups = [
                 name: 'list',
                 summary: 'List your sales, sorted by sell date',
                 auth: 'member',
+                sdkMethods: ['sales.list'],
                 options: [
                     { flags: '--coffee-id <id>' },
                     { flags: '--date-start <YYYY-MM-DD>' },
@@ -687,6 +805,8 @@ const commandGroups = [
                 name: 'record',
                 summary: 'Record a new sale',
                 auth: 'member',
+                sdkMethods: ['sales.create', 'roasts.list', 'roasts.get'],
+                confirmedActionEquivalents: ['record_sale'],
                 options: [
                     { flags: '--roast-id <id>' },
                     { flags: '--coffee-id <id>' },
@@ -708,6 +828,7 @@ const commandGroups = [
                 name: 'update',
                 summary: 'Update a sale record',
                 auth: 'member',
+                sdkMethods: ['sales.update'],
                 arguments: [
                     {
                         name: 'sale_id',
@@ -728,6 +849,7 @@ const commandGroups = [
                 name: 'delete',
                 summary: 'Delete a sale record',
                 auth: 'member',
+                sdkMethods: ['sales.delete'],
                 arguments: [
                     {
                         name: 'sale_id',
@@ -750,6 +872,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get tasting notes for a coffee',
                 auth: 'member',
+                sdkMethods: ['tasting.get'],
                 arguments: [
                     {
                         name: 'catalog_id',
@@ -765,6 +888,7 @@ const commandGroups = [
                 name: 'rate',
                 summary: 'Rate a coffee bean with cupping scores',
                 auth: 'member',
+                sdkMethods: ['tasting.rate'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -880,13 +1004,14 @@ const commandGroups = [
     },
     {
         name: 'market',
-        summary: 'Market Index decision surface: value signals, movement stats, and metadata trends via the canonical API',
+        summary: 'Market Index decision surface: value signals, movement stats, metadata trends, overview, and evidence via the canonical API',
         auth: 'mixed',
         subcommands: [
             {
                 name: 'signals',
                 summary: 'Actionable market value signals; unfiltered summary is a public teaser',
                 auth: 'none',
+                sdkMethods: ['market.signals'],
                 options: [
                     { flags: '--summary' },
                     {
@@ -920,6 +1045,7 @@ const commandGroups = [
                 name: 'stats',
                 summary: 'Price movement-significance stats; unfiltered retail slice is public',
                 auth: 'none',
+                sdkMethods: ['priceIndex.stats'],
                 options: [
                     { flags: '--origin <origin>' },
                     { flags: '--process <method>' },
@@ -940,6 +1066,7 @@ const commandGroups = [
                 name: 'metadata',
                 summary: 'Metadata-trend index; process/retail/month slice is public',
                 auth: 'none',
+                sdkMethods: ['market.metadataIndex'],
                 options: [
                     { flags: '--dimension <process|disclosure|score>' },
                     { flags: '--origin <origin>' },
@@ -958,16 +1085,40 @@ const commandGroups = [
                     'purvey market metadata --dimension score --origin "Ethiopia" --grain month --json',
                 ],
             },
+            {
+                name: 'overview',
+                summary: 'Aggregate-only green-coffee market overview over the public catalog',
+                auth: 'viewer',
+                sdkMethods: ['market.overview'],
+                notes: [
+                    'Backed by the canonical API GET /v1/market/overview via @purveyors/sdk.',
+                    'The API rejects anonymous requests; any signed-in session or API key with catalog read access receives the same public evidence.',
+                    'Emits the API response verbatim: daily change, coverage, movement, process distribution, and origin price distributions.',
+                ],
+                examples: ['purvey market overview --pretty'],
+            },
+            {
+                name: 'evidence',
+                summary: 'Named arrivals, delistings, comparable lots, and supplier health and price ranges',
+                auth: 'member',
+                sdkMethods: ['market.evidence'],
+                notes: [
+                    'Backed by the canonical API GET /v1/market/evidence via @purveyors/sdk.',
+                    'Requires Parchment Intelligence plus catalog read access, enforced server-side (401/403 on denial).',
+                ],
+                examples: ['purvey market evidence --json'],
+            },
         ],
     },
     {
         name: 'price-index',
-        summary: 'Parchment Price Index aggregate snapshots; requires price-index (PPI) access',
-        auth: 'member',
+        summary: 'Parchment Price Index snapshots, matched 30-day comparisons, and chart history via the canonical API',
+        auth: 'mixed',
         command: {
             name: 'price-index',
             summary: 'Fetch Parchment Price Index aggregate snapshots from the canonical API',
             auth: 'member',
+            sdkMethods: ['priceIndex.list'],
             options: [
                 { flags: '--origin <origin>' },
                 { flags: '--process <method>' },
@@ -995,6 +1146,75 @@ const commandGroups = [
                 'purvey price-index --from 2026-01-01 --to 2026-06-30 --pretty',
             ],
         },
+        subcommands: [
+            {
+                name: 'comparisons',
+                summary: 'Available exact 30-day matched price comparisons with significance',
+                auth: 'member',
+                sdkMethods: ['priceIndex.comparisons'],
+                options: [{ flags: '--wholesale <true|false|all>' }],
+                notes: [
+                    'Backed by the canonical API GET /v1/price-index/comparisons via @purveyors/sdk.',
+                    'Requires Parchment Intelligence access, enforced server-side.',
+                    'The API discovers origins with an exact 30-day matched comparison; an empty comparisons list means none qualify.',
+                    'Each comparison carries significance verbatim; classification (quiet|normal|notable|exceptional) is null until eight baseline windows exist, meaning not enough history, never quiet.',
+                ],
+                examples: [
+                    'purvey price-index comparisons --pretty',
+                    'purvey price-index comparisons --wholesale all --json',
+                ],
+            },
+            {
+                name: 'comparison',
+                summary: 'Matched-listing price comparison for one origin between two exact dates',
+                auth: 'member',
+                sdkMethods: ['priceIndex.comparison'],
+                options: [
+                    { flags: '--origin <origin>', notes: ['required'] },
+                    { flags: '--from <date>', notes: ['required; ISO date YYYY-MM-DD'] },
+                    { flags: '--to <date>', notes: ['required; ISO date within 365 days of --from'] },
+                    { flags: '--wholesale <true|false>' },
+                ],
+                notes: [
+                    'Backed by the canonical API GET /v1/price-index/comparison via @purveyors/sdk.',
+                    'Requires Parchment Intelligence access, enforced server-side.',
+                    'status insufficient_fresh_coverage returns a null changePercent, never zero.',
+                ],
+                examples: [
+                    'purvey price-index comparison --origin "Ethiopia" --from 2026-08-31 --to 2026-09-30 --pretty',
+                ],
+            },
+            {
+                name: 'history',
+                summary: 'Tier-one price-index chart history; windows up to 90 days are public',
+                auth: 'none',
+                sdkMethods: ['priceIndex.history'],
+                options: [
+                    {
+                        flags: '--window-days <n>',
+                        description: `Trailing window in days, ${CLI_NUMERIC_BOUNDS.priceIndexHistoryWindowDays.minimum}-${CLI_NUMERIC_BOUNDS.priceIndexHistoryWindowDays.maximum}`,
+                        minimum: CLI_NUMERIC_BOUNDS.priceIndexHistoryWindowDays.minimum,
+                        maximum: CLI_NUMERIC_BOUNDS.priceIndexHistoryWindowDays.maximum,
+                    },
+                    { flags: '--page <n>' },
+                    {
+                        flags: '--limit <n>',
+                        description: `Results per page, ${CLI_NUMERIC_BOUNDS.priceIndexHistoryLimit.minimum}-${CLI_NUMERIC_BOUNDS.priceIndexHistoryLimit.maximum}`,
+                        minimum: CLI_NUMERIC_BOUNDS.priceIndexHistoryLimit.minimum,
+                        maximum: CLI_NUMERIC_BOUNDS.priceIndexHistoryLimit.maximum,
+                    },
+                    { flags: '--order <asc|desc>' },
+                ],
+                notes: [
+                    'Backed by the canonical API GET /v1/price-index/history via @purveyors/sdk.',
+                    'Windows up to 90 days (the default) run without credentials; 91-365 days require Parchment Intelligence access, enforced server-side.',
+                ],
+                examples: [
+                    'purvey price-index history --pretty',
+                    'purvey price-index history --window-days 365 --limit 500 --json',
+                ],
+            },
+        ],
     },
     {
         name: 'procurement',
@@ -1005,6 +1225,7 @@ const commandGroups = [
                 name: 'list',
                 summary: 'List your saved sourcing briefs',
                 auth: 'member',
+                sdkMethods: ['procurement.briefs.list'],
                 notes: [
                     'Backed by the canonical API GET /v1/procurement/briefs via @purveyors/sdk.',
                     'Brief creation is a write handled by the Phase 2 write build-out (PADR-0016), not this read surface.',
@@ -1015,6 +1236,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get a single saved sourcing brief by id',
                 auth: 'member',
+                sdkMethods: ['procurement.briefs.get'],
                 arguments: [
                     {
                         name: 'brief_id',
@@ -1030,6 +1252,7 @@ const commandGroups = [
                 name: 'matches',
                 summary: 'Run a saved brief against the catalog and page through matches',
                 auth: 'member',
+                sdkMethods: ['procurement.briefs.matches'],
                 arguments: [
                     {
                         name: 'brief_id',
@@ -1060,13 +1283,14 @@ const commandGroups = [
     },
     {
         name: 'reference-profile',
-        summary: 'Preview, save, and export Studio reference plans through the canonical API',
+        summary: 'Compare, preview, save, and export Studio reference plans through the canonical API',
         auth: 'member',
         subcommands: [
             {
                 name: 'list',
                 summary: 'List your Studio reference profiles',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.list'],
                 options: [{ flags: '--include-archived' }],
                 notes: [
                     'Backed by GET /v1/reference-profiles via @purveyors/sdk.',
@@ -1078,6 +1302,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get one reference profile and its current revision',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.get'],
                 arguments: [
                     {
                         name: 'reference_profile_id',
@@ -1094,6 +1319,7 @@ const commandGroups = [
                 name: 'chart',
                 summary: 'Get the typed Artisan chart for a reference revision',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.chart'],
                 arguments: [
                     {
                         name: 'reference_profile_id',
@@ -1121,6 +1347,7 @@ const commandGroups = [
                 name: 'import',
                 summary: 'Upload an Artisan file as a private Studio reference profile',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.import'],
                 arguments: [
                     {
                         name: 'file',
@@ -1142,10 +1369,48 @@ const commandGroups = [
                     'purvey reference-profile import ~/artisan/ethiopia.alog --title "Ethiopia baseline"',
                 ],
             },
+            {
+                name: 'compare',
+                summary: 'Compare two immutable roast or reference revisions with measured deltas',
+                auth: 'member',
+                sdkMethods: ['referenceProfiles.compare', 'referenceProfiles.get', 'roasts.chartData'],
+                arguments: [
+                    {
+                        name: 'left',
+                        description: 'selector: revision:<uuid>, profile:<uuid>, roast:<roast-id>, or roast:<roast-id>@<chart-revision>',
+                        required: true,
+                    },
+                    {
+                        name: 'right',
+                        description: 'selector: revision:<uuid>, profile:<uuid>, roast:<roast-id>, or roast:<roast-id>@<chart-revision>',
+                        required: true,
+                    },
+                ],
+                options: [
+                    { flags: '--unit <F|C>', defaultValue: 'F' },
+                    {
+                        flags: '--target-points <n>',
+                        description: 'Samples per aligned series, 50-1000',
+                        defaultValue: 400,
+                        minimum: 50,
+                        maximum: 1000,
+                    },
+                ],
+                notes: [
+                    'Backed by POST /v1/profile-comparisons via @purveyors/sdk; output is the canonical comparison envelope.',
+                    'profile:<uuid> resolves the profile currentRevisionId; roast:<roast-id> resolves data.metadata.revision from roast chart data.',
+                    'Parchment aligns both sides at charge; a reference profile is never executed roast history.',
+                ],
+                examples: [
+                    'purvey reference-profile compare roast:123 profile:5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty',
+                    'purvey reference-profile compare roast:123 roast:124 --unit C --json',
+                ],
+            },
             {
                 name: 'preview',
                 summary: 'Preview bounded temperature adjustments without saving',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.preview'],
                 arguments: [
                     {
                         name: 'reference_profile_id',
@@ -1165,7 +1430,7 @@ const commandGroups = [
                 options: [{ flags: '--request <file>', requiredInFlagMode: true }],
                 notes: [
                     'Backed by POST /v1/reference-profiles/{id}/revisions/{revisionId}/preview via @purveyors/sdk.',
-                    'Request JSON contains title, optional notes, and changes.temperatureAdjustments; each adjustment has kind, startMilliseconds, endMilliseconds, and delta.',
+                    'Request JSON contains title, optional notes, optional userGoal (600 chars), modelRecommendation (800), and userEdits (800) provenance, and changes.temperatureAdjustments; each adjustment has kind, startMilliseconds, endMilliseconds, and delta.',
                     'At most 12 adjustments are accepted; intervals must be ordered and each nonzero delta is bounded to -20 through 20.',
                     'Parchment recalculates from the immutable parent; preview never persists or changes the source.',
                 ],
@@ -1177,6 +1442,8 @@ const commandGroups = [
                 name: 'save',
                 summary: 'Save changes as a new immutable generated reference plan',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.generate'],
+                confirmedActionEquivalents: ['create_generated_reference'],
                 arguments: [
                     {
                         name: 'reference_profile_id',
@@ -1210,6 +1477,7 @@ const commandGroups = [
                 name: 'export',
                 summary: 'Download a saved generated reference as an unsigned Artisan .alog plan',
                 auth: 'member',
+                sdkMethods: ['referenceProfiles.exportGenerated'],
                 arguments: [
                     {
                         name: 'reference_profile_id',
@@ -1510,10 +1778,10 @@ function renderCommandGroups(groups) {
     for (const group of groups) {
         if (group.command) {
             lines.push(...renderCommandEntry(group.command, '', group.name));
-            lines.push('');
-            continue;
         }
-        lines.push(group.name);
+        else {
+            lines.push(group.name);
+        }
         for (const subcommand of group.subcommands ?? []) {
             lines.push(...renderCommandEntry(subcommand));
         }