@purveyors/cli 0.33.2 → 0.35.0

package/dist/lib/manifest.js

@@ -84,13 +84,39 @@ 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',
         source: 'coffee_sales row',
         usedBy: ['sales update/delete'],
     },
+    {
+        name: 'reference_profile_id',
+        source: 'owner-scoped Studio reference profile',
+        usedBy: [
+            'reference-profile get',
+            'reference-profile chart',
+            'reference-profile preview/save',
+            'reference-profile export',
+            'reference-profile compare profile:<uuid>',
+        ],
+    },
+    {
+        name: 'reference_revision_id',
+        source: 'immutable revision belonging to a reference profile',
+        usedBy: [
+            'reference-profile chart',
+            'reference-profile preview/save',
+            'reference-profile export',
+            'reference-profile compare revision:<uuid>',
+        ],
+    },
 ];
 const commandGroups = [
     {
@@ -102,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' },
                 ],
@@ -111,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',
@@ -118,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',
@@ -135,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>' },
@@ -149,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 },
@@ -183,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',
                 ],
             },
@@ -190,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',
@@ -217,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: [
@@ -235,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' },
@@ -277,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>' },
@@ -307,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' },
@@ -325,6 +394,7 @@ const commandGroups = [
                 name: 'supplier-detail',
                 summary: 'Show aggregate detail for a supplier query',
                 auth: 'viewer',
+                sdkMethods: ['catalog.supplierDetail'],
                 arguments: [
                     {
                         name: 'supplier',
@@ -349,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' },
@@ -376,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',
@@ -422,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>' },
@@ -445,6 +518,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get a single inventory item',
                 auth: 'member',
+                sdkMethods: ['inventory.list'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -460,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>' },
@@ -469,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',
@@ -490,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',
@@ -518,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>' },
@@ -542,6 +637,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get a single roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.get'],
                 arguments: [
                     {
                         name: 'roast_id',
@@ -553,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>' },
@@ -564,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' },
                 ],
             },
@@ -571,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',
@@ -591,6 +724,7 @@ const commandGroups = [
                 name: 'delete',
                 summary: 'Delete a roast profile',
                 auth: 'member',
+                sdkMethods: ['roasts.delete'],
                 arguments: [
                     {
                         name: 'roast_id',
@@ -606,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 },
@@ -620,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>' },
@@ -650,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>' },
@@ -668,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>' },
@@ -689,6 +828,7 @@ const commandGroups = [
                 name: 'update',
                 summary: 'Update a sale record',
                 auth: 'member',
+                sdkMethods: ['sales.update'],
                 arguments: [
                     {
                         name: 'sale_id',
@@ -709,6 +849,7 @@ const commandGroups = [
                 name: 'delete',
                 summary: 'Delete a sale record',
                 auth: 'member',
+                sdkMethods: ['sales.delete'],
                 arguments: [
                     {
                         name: 'sale_id',
@@ -731,6 +872,7 @@ const commandGroups = [
                 name: 'get',
                 summary: 'Get tasting notes for a coffee',
                 auth: 'member',
+                sdkMethods: ['tasting.get'],
                 arguments: [
                     {
                         name: 'catalog_id',
@@ -746,6 +888,7 @@ const commandGroups = [
                 name: 'rate',
                 summary: 'Rate a coffee bean with cupping scores',
                 auth: 'member',
+                sdkMethods: ['tasting.rate'],
                 arguments: [
                     {
                         name: 'inventory_id',
@@ -861,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' },
                     {
@@ -901,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>' },
@@ -921,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>' },
@@ -939,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>' },
@@ -976,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',
@@ -986,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.',
@@ -996,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',
@@ -1011,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',
@@ -1039,6 +1281,234 @@ const commandGroups = [
             },
         ],
     },
+    {
+        name: 'reference-profile',
+        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.',
+                    'Requires a member credential and Studio access; entitlement is enforced by Parchment.',
+                ],
+                examples: ['purvey reference-profile list --pretty'],
+            },
+            {
+                name: 'get',
+                summary: 'Get one reference profile and its current revision',
+                auth: 'member',
+                sdkMethods: ['referenceProfiles.get'],
+                arguments: [
+                    {
+                        name: 'reference_profile_id',
+                        cliToken: 'profile-id',
+                        description: 'owner-scoped reference profile UUID',
+                        required: true,
+                        idType: 'reference_profile_id',
+                    },
+                ],
+                notes: ['Use data.currentRevision.id for chart, preview, and save.'],
+                examples: ['purvey reference-profile get 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty'],
+            },
+            {
+                name: 'chart',
+                summary: 'Get the typed Artisan chart for a reference revision',
+                auth: 'member',
+                sdkMethods: ['referenceProfiles.chart'],
+                arguments: [
+                    {
+                        name: 'reference_profile_id',
+                        cliToken: 'profile-id',
+                        description: 'owner-scoped reference profile UUID',
+                        required: true,
+                        idType: 'reference_profile_id',
+                    },
+                    {
+                        name: 'reference_revision_id',
+                        cliToken: 'revision-id',
+                        description: 'immutable revision UUID belonging to the profile',
+                        required: true,
+                        idType: 'reference_revision_id',
+                    },
+                ],
+                notes: [
+                    'Backed by GET /v1/reference-profiles/{id}/revisions/{revisionId}/chart via @purveyors/sdk.',
+                ],
+                examples: [
+                    'purvey reference-profile chart 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --pretty',
+                ],
+            },
+            {
+                name: 'import',
+                summary: 'Upload an Artisan file as a private Studio reference profile',
+                auth: 'member',
+                sdkMethods: ['referenceProfiles.import'],
+                arguments: [
+                    {
+                        name: 'file',
+                        description: 'Path to an Artisan .alog or importer-supported JSON file',
+                        required: true,
+                    },
+                ],
+                options: [
+                    { flags: '--title <text>' },
+                    { flags: '--notes <text>' },
+                    { flags: '--idempotency-key <key>', description: 'Stable key for safe retries' },
+                ],
+                notes: [
+                    'Backed by POST /v1/reference-profiles/imports via @purveyors/sdk; parsing and private retention are server-owned.',
+                    'A new idempotency key is generated when omitted; reuse an explicit key to replay the same upload.',
+                    'Import creates a reference profile, not executed roast history.',
+                ],
+                examples: [
+                    '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',
+                        cliToken: 'profile-id',
+                        description: 'owner-scoped reference profile UUID',
+                        required: true,
+                        idType: 'reference_profile_id',
+                    },
+                    {
+                        name: 'reference_revision_id',
+                        cliToken: 'revision-id',
+                        description: 'immutable parent revision UUID',
+                        required: true,
+                        idType: 'reference_revision_id',
+                    },
+                ],
+                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, 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.',
+                ],
+                examples: [
+                    'purvey reference-profile preview 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty',
+                ],
+            },
+            {
+                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',
+                        cliToken: 'profile-id',
+                        description: 'owner-scoped reference profile UUID',
+                        required: true,
+                        idType: 'reference_profile_id',
+                    },
+                    {
+                        name: 'reference_revision_id',
+                        cliToken: 'revision-id',
+                        description: 'immutable parent revision UUID',
+                        required: true,
+                        idType: 'reference_revision_id',
+                    },
+                ],
+                options: [
+                    { flags: '--request <file>', requiredInFlagMode: true },
+                    { flags: '--idempotency-key <key>', description: 'Stable key for safe retries' },
+                ],
+                notes: [
+                    'Backed by POST /v1/reference-profiles/{id}/revisions/{revisionId}/generated via @purveyors/sdk.',
+                    'A new idempotency key is generated when omitted; reuse an explicit key to replay the same save.',
+                    'Generated references are plans and never create executed roast history.',
+                ],
+                examples: [
+                    'purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty',
+                ],
+            },
+            {
+                name: 'export',
+                summary: 'Download a saved generated reference as an unsigned Artisan .alog plan',
+                auth: 'member',
+                sdkMethods: ['referenceProfiles.exportGenerated'],
+                arguments: [
+                    {
+                        name: 'reference_profile_id',
+                        cliToken: 'profile-id',
+                        description: 'saved generated reference profile UUID',
+                        required: true,
+                        idType: 'reference_profile_id',
+                    },
+                    {
+                        name: 'reference_revision_id',
+                        cliToken: 'revision-id',
+                        description: 'saved generated revision UUID',
+                        required: true,
+                        idType: 'reference_revision_id',
+                    },
+                ],
+                options: [
+                    { flags: '--output <file>', requiredInFlagMode: true },
+                    { flags: '--force', description: 'Overwrite the destination file if it exists' },
+                ],
+                notes: [
+                    'Backed by GET /v1/reference-profiles/{id}/revisions/{revisionId}/export via @purveyors/sdk.',
+                    'Only a saved generated revision can be exported; output is a local file plus a JSON receipt.',
+                    'The CLI does not claim verified Artisan 4.2 playback compatibility.',
+                ],
+                examples: [
+                    'purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog',
+                ],
+            },
+        ],
+    },
 ];
 const workflows = [
     {
@@ -1063,6 +1533,16 @@ const workflows = [
             'purvey roast import ~/artisan/ethiopia.alog --coffee-id 7 --pretty',
         ],
     },
+    {
+        title: 'Plan and export an Artisan reference',
+        commands: [
+            'purvey reference-profile import ~/artisan/ethiopia.alog --title "Ethiopia baseline"',
+            'purvey reference-profile get 5ea1af6f-234c-43a9-9bf8-5678dd24f854 --pretty',
+            'purvey reference-profile preview 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --pretty',
+            'purvey reference-profile save 5ea1af6f-234c-43a9-9bf8-5678dd24f854 8d2c41e0-7b9a-4f3e-a6d1-2c9e5f07b3a4 --request changes.json --idempotency-key 3f6c2a1b-8e4d-4b7a-9c05-7e1f2d3a4b5c',
+            'purvey reference-profile export 0b7e9f52-3c61-4d8a-9e24-6f1a8c3d5b90 c43a1d7e-95b2-4e06-8f7c-1d2b3a4e5f68 --output ~/artisan/next-batch.alog',
+        ],
+    },
     {
         title: 'Watch a folder for new roasts',
         commands: [
@@ -1092,7 +1572,7 @@ const errorPatterns = [
         title: 'Wrong ID type',
         exitCodes: [EXIT_CODES.INVALID_ARGUMENT, EXIT_CODES.NOT_FOUND],
         guidance: [
-            'Verify whether the command wants catalog_id, inventory_id, roast_id, or sale_id.',
+            'Verify whether the command wants catalog_id, inventory_id, roast_id, sale_id, reference_profile_id, or reference_revision_id.',
             'See the ID MAP section.',
         ],
     },
@@ -1272,7 +1752,7 @@ function renderIdMap(ids) {
     for (const id of ids) {
         lines.push(`${id.name.padEnd(14, ' ')} ${id.source}; used by: ${id.usedBy.join(', ')}`);
     }
-    lines.push('', 'Common ID mistake: tasting get takes catalog_id; tasting rate takes inventory_id.');
+    lines.push('', 'Common ID mistakes: tasting get takes catalog_id; tasting rate takes inventory_id; reference-profile commands use profile and revision UUIDs, not roast IDs.');
     return lines;
 }
 function renderOptions(options = [], indent = '    ') {
@@ -1298,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));
         }