@purveyors/cli 0.8.3 → 0.9.0

package/README.md

@@ -1,12 +1,10 @@
-# purvey — The Purveyors CLI
+# purvey
 
-> Coffee intelligence from your terminal.
+Coffee intelligence from your terminal.
 
-`purvey` is the official command-line interface for [purveyors.io](https://purveyors.io). It gives coffee professionals direct terminal access to the Purveyors platform: search green coffee availability, track pricing tiers, monitor inventory, record roasts, log sales, and capture tasting notes — all from your terminal or scripts.
+`purvey` is the official CLI for [purveyors.io](https://purveyors.io). It gives coffee professionals and AI agents direct access to the Purveyors platform from the terminal: catalog search, inventory tracking, roast logging, sales records, tasting notes, and Artisan `.alog` import.
 
-**Designed for both humans and AI agents.** Run `purvey context` for instant agent onboarding.
-
----
+Run `purvey context` for the dense agent reference.
 
 ## Installation
 
@@ -14,284 +12,378 @@
 npm install -g @purveyors/cli
 ```
 
-Requires **Node.js >= 20**.
+Requirements:
+
+- Node.js 20 or newer
 
-Verify:
+Verify the install:
 
 ```bash
 purvey --version
 ```
 
----
-
 ## Quick Start
 
 ```bash
 # 1. Authenticate
 purvey auth login
 
-# 2. Confirm your session
+# 2. Confirm the session
 purvey auth status
 
-# 3. Search the catalog (no login required)
+# 3. Search the catalog
 purvey catalog search --origin "Ethiopia" --stocked --pretty
 
-# 4. Check your inventory
+# 4. Check inventory
 purvey inventory list --stocked --pretty
 
 # 5. Import a roast from Artisan
 purvey roast import ~/artisan/my-roast.alog --coffee-id 7 --pretty
 ```
 
----
-
 ## Authentication
 
-`purvey` authenticates via Google OAuth, using the same account as your purveyors.io web session.
+`purvey` uses Google OAuth through purveyors.io.
 
-### Browser Login (interactive)
+Interactive login:
 
 ```bash
 purvey auth login
 ```
 
-Opens your default browser. Complete Google sign-in, then return to the terminal. Credentials are stored at `~/.config/purvey/credentials.json` (owner-readable only, mode 0600).
-
-### Headless Login (agents, CI, servers)
+Headless login for agents, CI, and remote machines:
 
 ```bash
 purvey auth login --headless
 ```
 
-No browser required. The CLI prints a Google OAuth URL — open it in any browser, sign in, then copy the full callback URL and paste it back at the prompt.
-
-### Status
+Status:
 
 ```bash
 purvey auth status
+purvey auth status --json
 purvey auth status --pretty
 ```
 
-```
-✔ Logged in as you@example.com
-ℹ Role: member
-ℹ Token expires: 2026-04-01T08:00:00.000Z
-```
-
-### Token Refresh
-
-Tokens refresh automatically. No need to re-login between sessions.
-
-### Logout
+Logout:
 
 ```bash
 purvey auth logout
 ```
 
-Clears stored credentials from disk.
+Credentials are stored at `~/.config/purvey/credentials.json`.
 
----
+### Auth roles
 
-## Output Formats
+`catalog` commands require an authenticated viewer session. Sign in before using:
 
-All `purvey` commands default to **compact JSON** — one line, no colors, machine-readable. This makes `purvey` pipeable into `jq`, `csvkit`, or any script.
+- `purvey catalog search`
+- `purvey catalog get <id>`
+- `purvey catalog stats`
+- `purvey catalog similar <id>`
 
-### Compact JSON (default)
+`inventory`, `roast`, `sales`, and `tasting` commands require a member role.
 
-```bash
-purvey auth status
-# → {"authenticated":true,"email":"you@example.com","role":"member","tokenExpires":"..."}
-```
+## Output and Scripting
+
+Most commands write compact JSON to stdout by default.
+Use `--json` if you want to request that mode explicitly.
 
-### Pretty JSON (`--pretty`)
+Pretty JSON:
 
 ```bash
-purvey catalog search --origin "Ethiopia" --pretty
-# → indented, colorized JSON
+purvey inventory list --pretty
 ```
 
-### CSV (`--csv`)
+CSV output for array results:
 
 ```bash
 purvey inventory list --csv > inventory.csv
-purvey catalog search --stocked --csv | head -5
+purvey sales list --csv > sales.csv
 ```
 
-### Piping with jq
+Pipe JSON into `jq`:
 
 ```bash
 purvey inventory list | jq '.[].id'
-purvey catalog search --origin "Colombia" | jq '.[].cost_lb'
-purvey auth status | jq -r '.email'
+purvey roast list --limit 5 | jq '.[].roast_id'
+purvey auth status 2>/dev/null | jq -r '.email'
 ```
 
-User feedback messages (spinners, success/error) go to **stderr** only — stdout is always clean data, safe to pipe.
+Operational messages go to stderr, so stdout stays script-friendly.
 
----
+### Output caveats worth knowing
+
+- `purvey auth status` prints human-readable output in an interactive terminal unless you pass `--json`, `--pretty`, or `--csv`. When piped or redirected, it emits JSON.
+- `--json` is an explicit alias for the default compact JSON mode, and it forces JSON even in an interactive terminal.
 
 ## Command Reference
 
-### Authentication
+### auth
 
-| Command                        | Description                                   |
-| ------------------------------ | --------------------------------------------- |
-| `purvey auth login`            | Log in via Google OAuth (browser)             |
-| `purvey auth login --headless` | Log in without a browser (paste callback URL) |
-| `purvey auth status`           | Show current authentication state and role    |
-| `purvey auth logout`           | Clear stored credentials                      |
+- `purvey auth login`
+- `purvey auth login --headless`
+- `purvey auth status`
+- `purvey auth logout`
 
-### Catalog (no authentication required)
+### catalog
 
-| Command                   | Description                                         |
-| ------------------------- | --------------------------------------------------- |
-| `purvey catalog search`   | Search coffees by origin, process, price, or flavor |
-| `purvey catalog get <id>` | Get details for a specific coffee by catalog ID     |
-| `purvey catalog stats`    | Aggregate statistics for the full catalog           |
+- `purvey catalog search`
+- `purvey catalog get <id>`
+- `purvey catalog stats`
+- `purvey catalog similar <id>`
 
-**catalog search options:**
+`catalog search` filters:
 
+- `--origin <text>` -- filter by origin (country, continent, or region)
+- `--process <method>` -- filter by processing method (e.g. natural, washed)
+- `--price-min <n>` -- minimum price per lb (USD)
+- `--price-max <n>` -- maximum price per lb (USD)
+- `--flavor <keywords>` -- flavor keywords, comma-separated
+- `--name <text>` -- filter by coffee name (partial match, case-insensitive)
+- `--supplier <name>` -- filter by supplier/source name (partial match, case-insensitive)
+- `--ids <n,n,...>` -- fetch specific catalog IDs (comma-separated, ignores limit)
+- `--stocked` -- only show currently stocked coffees
+- `--sort <price|price-desc|name|origin|newest>` -- sort results
+- `--offset <n>` -- skip N results for pagination
+- `--limit <n>` -- maximum results to return (default: 10)
+
+`catalog similar <id>` options:
+
+- `--threshold <0-1>` -- minimum similarity score (default: 0.70)
+- `--limit <n>` -- max results (default: 10)
+- `--stocked-only` -- only show currently stocked beans
+
+Examples:
+
+```bash
+purvey catalog search --origin "Ethiopia" --pretty
+purvey catalog search --supplier "Royal Coffee" --stocked --pretty
+purvey catalog search --ids "1182,1183,1200"
+purvey catalog search --stocked --sort price --offset 10 --limit 10
+purvey catalog similar 1182 --threshold 0.85 --stocked-only --pretty
+purvey catalog similar 1182 --json | jq '.[0]'
 ```
---origin <text>      country or region (e.g. "Ethiopia", "Colombia")
---process <method>   natural, washed, honey
---price-min <n>      min USD/lb
---price-max <n>      max USD/lb
---flavor <keywords>  comma-separated (e.g. "blueberry,citrus")
---stocked            only currently stocked coffees
---limit <n>          max results (default: 10)
-```
 
-### Inventory (member role required)
+### inventory
+
+- `purvey inventory list`
+- `purvey inventory get <id>`
+- `purvey inventory add`
+- `purvey inventory update <id>`
+- `purvey inventory delete <id>`
 
-| Command                        | Description                      |
-| ------------------------------ | -------------------------------- |
-| `purvey inventory list`        | List your green coffee inventory |
-| `purvey inventory get <id>`    | Get a single inventory item      |
-| `purvey inventory add`         | Add a bean to your inventory     |
-| `purvey inventory update <id>` | Update an inventory item         |
-| `purvey inventory delete <id>` | Delete an inventory item         |
+`inventory list` options:
 
-**inventory add** — required flags: `--catalog-id`, `--qty`
+- `--stocked` -- only show currently stocked beans
+- `--limit <n>` -- maximum results (default: 20)
+
+`inventory add` flags:
+
+- `--catalog-id <id>` -- [REQUIRED] coffee_catalog.catalog_id
+- `--qty <lbs>` -- [REQUIRED] quantity in pounds
+- `--cost <dollars>` -- bean cost in dollars
+- `--tax-ship <dollars>` -- tax and shipping cost in dollars
+- `--notes <text>` -- notes for this inventory item
+- `--purchase-date <YYYY-MM-DD>` -- purchase date (defaults to today)
+- `--form` -- interactive form mode
+
+`inventory update <id>` flags:
+
+- `--qty <lbs>` -- updated quantity in pounds
+- `--cost <dollars>` -- updated bean cost
+- `--tax-ship <dollars>` -- updated tax/shipping cost
+- `--notes <text>` -- updated notes
+- `--stocked <true|false>` -- mark as stocked or not
+
+Examples:
 
 ```bash
+purvey inventory list --stocked --pretty
 purvey inventory add --catalog-id 128 --qty 10 --cost 8.50
-purvey inventory add --form    # interactive wizard
+purvey inventory add --catalog-id 42 --qty 5 --cost 6.25 --tax-ship 4.00
+purvey inventory update 7 --stocked false
+purvey inventory delete 7 --yes
 ```
 
-### Roast Profiles (member role required)
+### roast
+
+- `purvey roast list`
+- `purvey roast get <id>`
+- `purvey roast create`
+- `purvey roast update <id>`
+- `purvey roast delete <id>`
+- `purvey roast import [file]`
+- `purvey roast watch [directory]`
+
+`roast list` filters:
+
+- `--coffee-id <id>` -- filter by inventory item ID (green_coffee_inv.id)
+- `--roast-id <id>` -- filter by exact roast profile ID
+- `--batch-name <text>` -- filter by batch name (partial match, case-insensitive)
+- `--date-start <YYYY-MM-DD>` -- only show roasts on or after this date
+- `--date-end <YYYY-MM-DD>` -- only show roasts on or before this date
+- `--stocked` -- only show roasts for currently stocked beans
+- `--catalog-id <id>` -- filter by coffee_catalog ID
+- `--limit <n>` -- maximum results (default: 20)
+
+`roast get <id>` options:
+
+- `--include-temps` -- include temperature curve data
+- `--include-events` -- include roast event markers
+
+`roast create` flags:
 
-| Command                      | Description                           |
-| ---------------------------- | ------------------------------------- |
-| `purvey roast list`          | List your roast profiles              |
-| `purvey roast get <id>`      | Get a single roast profile            |
-| `purvey roast create`        | Create a new roast profile            |
-| `purvey roast update <id>`   | Update a roast profile                |
-| `purvey roast delete <id>`   | Delete a roast profile                |
-| `purvey roast import [file]` | Import an Artisan .alog roast file    |
-| `purvey roast watch [dir]`   | Watch a directory for new .alog files |
+- `--coffee-id <id>` -- [REQUIRED] green_coffee_inv ID
+- `--batch-name <name>` -- batch name (defaults to coffee name + today's date)
+- `--oz-in <oz>` -- green weight in ounces
+- `--oz-out <oz>` -- roasted weight in ounces
+- `--roast-date <YYYY-MM-DD>` -- roast date (defaults to today)
+- `--notes <text>` -- roast notes
+- `--form` -- interactive form mode
 
-**roast import** — required: `<file>`, `--coffee-id`
+`roast update <id>` fields:
+
+- `--notes <text>` -- updated roast notes
+- `--oz-out <oz>` -- updated roasted weight (triggers weight loss recalculation)
+- `--batch-name <name>` -- updated batch name
+- `--targets <text>` -- updated roast targets
+
+`roast import [file]` flags:
+
+- `--coffee-id <id>` -- [REQUIRED] green_coffee_inv ID
+- `--batch-name <name>` -- batch name (auto-generated if omitted)
+- `--oz-in <oz>` -- green weight (extracted from .alog if present, overridden here)
+- `--roast-notes <text>` -- additional roast notes
+- `--form` -- interactive form mode
+
+`roast watch [directory]` options:
+
+- `--coffee-id <id>` -- [REQUIRED unless --auto-match] inventory ID for all imports
+- `--batch-prefix <name>` -- batch name prefix for auto-named batches
+- `--prompt-each` -- prompt for bean selection on each new file
+- `--auto-match` -- auto-match beans per file (mutually exclusive with --coffee-id)
+- `--resume` -- resume a previous watch session
+- `--form` -- interactive setup wizard
+
+Examples:
 
 ```bash
+purvey roast list --catalog-id 128 --pretty
+purvey roast list --batch-name "Ethiopia Guji" --pretty
+purvey roast list --date-start 2026-03-01 --date-end 2026-03-31
+purvey roast create --coffee-id 7 --batch-name "Ethiopia Guji Light" --oz-in 16
+purvey roast update 123 --targets "Aim for FC at 390F, 18% dev"
 purvey roast import ~/artisan/ethiopia.alog --coffee-id 7
-purvey roast import --form    # interactive wizard
+purvey roast watch ~/artisan/ --auto-match
 ```
 
-**roast watch** — required: `<directory>`, `--coffee-id` (or `--auto-match`)
+### sales
 
-```bash
-purvey roast watch ~/artisan/ --coffee-id 7
-purvey roast watch ~/artisan/ --auto-match    # AI matches beans per file
-purvey roast watch --resume                  # continue previous session
-```
+- `purvey sales list`
+- `purvey sales record`
+- `purvey sales update <id>`
+- `purvey sales delete <id>`
+
+`sales record` flags:
 
-### Sales (member role required)
+- `--roast-id <id>` -- [REQUIRED] roast_data.roast_id
+- `--oz <amount>` -- [REQUIRED] ounces sold
+- `--price <dollars>` -- [REQUIRED] total sale price in dollars
+- `--buyer <name>` -- buyer name or identifier
+- `--sell-date <YYYY-MM-DD>` -- sale date (defaults to today)
+- `--form` -- interactive form mode
 
-| Command                    | Description             |
-| -------------------------- | ----------------------- |
-| `purvey sales list`        | List your sales records |
-| `purvey sales record`      | Record a new sale       |
-| `purvey sales update <id>` | Update a sale record    |
-| `purvey sales delete <id>` | Delete a sale record    |
+`sales update <id>` flags:
 
-**sales record** — required flags: `--roast-id`, `--oz`, `--price`
+- `--oz <amount>` -- updated ounces sold
+- `--price <dollars>` -- updated sale price
+- `--buyer <name>` -- updated buyer name
+- `--sell-date <YYYY-MM-DD>` -- updated sale date
+
+Examples:
 
 ```bash
-purvey sales record --roast-id 123 --oz 12 --price 22.00
-purvey sales record --form    # interactive wizard
+purvey sales record --roast-id 123 --oz 12 --price 22.00 --buyer "Jane Smith"
+purvey sales list --pretty
+purvey sales update 5 --price 24.00
+purvey sales delete 5 --yes
 ```
 
-### Tasting Notes (member role required)
+### tasting
 
-| Command                              | Description                            |
-| ------------------------------------ | -------------------------------------- |
-| `purvey tasting get <catalog-id>`    | Get tasting notes for a catalog coffee |
-| `purvey tasting rate [inventory-id]` | Rate a coffee with cupping scores      |
+- `purvey tasting get <bean-id>`
+- `purvey tasting rate [bean-id]`
 
-**tasting rate** — required (flag mode): `<inventory-id>` + all five score flags
+`purvey tasting get <bean-id>` options:
+
+- `--filter <user|supplier|both>` -- which notes to show (default: both)
+
+`purvey tasting rate [bean-id]` options:
+
+- `--aroma <1-5>` -- [REQUIRED in flag mode]
+- `--body <1-5>` -- [REQUIRED in flag mode]
+- `--acidity <1-5>` -- [REQUIRED in flag mode]
+- `--sweetness <1-5>` -- [REQUIRED in flag mode]
+- `--aftertaste <1-5>` -- [REQUIRED in flag mode]
+- `--brew-method <method>` -- brew method used (e.g. pour_over, espresso)
+- `--notes <text>` -- additional tasting notes
+- `--form` -- interactive form mode
+
+Examples:
 
 ```bash
+purvey tasting get 128 --filter both --pretty
 purvey tasting rate 7 --aroma 4 --body 3 --acidity 5 --sweetness 4 --aftertaste 4
-purvey tasting rate --form    # interactive wizard
+purvey tasting rate 42 --aroma 3 --body 3 --acidity 3 --sweetness 3 --aftertaste 3 --notes "Underextracted"
 ```
 
-### Configuration
+### config
 
-| Command                           | Description                  |
-| --------------------------------- | ---------------------------- |
-| `purvey config list`              | Show all config values       |
-| `purvey config get <key>`         | Get a single config value    |
-| `purvey config set <key> <value>` | Set a config value           |
-| `purvey config reset`             | Reset all config to defaults |
+- `purvey config list`
+- `purvey config get <key>`
+- `purvey config set <key> <value>`
+- `purvey config reset`
 
-**Supported config keys:**
+Current config key:
 
-| Key         | Values           | Description                                                                          |
-| ----------- | ---------------- | ------------------------------------------------------------------------------------ |
-| `form-mode` | `true` / `false` | When true, write commands auto-enter interactive wizard if required args are missing |
+- `form-mode`: when set to `true`, write commands enter interactive mode when required args are missing
+
+Examples:
 
 ```bash
 purvey config set form-mode true
 purvey config get form-mode
-purvey config list
 ```
 
----
+### context
+
+- `purvey context`
+
+Use this when an agent needs a compact, source-aware CLI reference.
 
 ## Common Workflows
 
-### Buy green coffee, roast it, record a sale
+### Buy coffee, roast it, rate it, and record a sale
 
 ```bash
-# Find a coffee
 purvey catalog search --origin "Ethiopia" --process "natural" --stocked --pretty
-
-# Add to inventory (catalog-id from search results)
 purvey inventory add --catalog-id 128 --qty 10 --cost 8.50
-
-# Get your inventory id
 purvey inventory list --stocked --pretty
-
-# Import a roast from Artisan (inventory id = 7)
 purvey roast import ~/artisan/guji-light.alog --coffee-id 7 --pretty
-
-# Rate the coffee after brewing
 purvey tasting rate 7 --aroma 5 --body 3 --acidity 5 --sweetness 4 --aftertaste 4
-
-# Record a sale (roast_id from import output)
 purvey sales record --roast-id 123 --oz 12 --price 22.00 --buyer "Jane Smith"
 ```
 
-### Continuous watch mode for Artisan
+### Continuous Artisan watch mode
 
 ```bash
-# Watch a directory — auto-imports every new .alog file
-purvey roast watch ~/Library/Application\ Support/Artisan-Scope/artisan/ --coffee-id 7
-
-# Resume a watch session after restart
+purvey roast watch ~/artisan/ --coffee-id 7
+purvey roast watch ~/artisan/ --auto-match
 purvey roast watch --resume
 ```
 
-### Export data for spreadsheets
+### Export records for spreadsheets
 
 ```bash
 purvey inventory list --csv > inventory.csv
@@ -299,66 +391,45 @@ purvey roast list --csv > roasts.csv
 purvey sales list --csv > sales.csv
 ```
 
----
-
-## Environment Variables
+## ID Reference
 
-| Variable                      | Description                                     |
-| ----------------------------- | ----------------------------------------------- |
-| `PURVEYORS_SUPABASE_URL`      | Override the Supabase project URL (dev/staging) |
-| `PURVEYORS_SUPABASE_ANON_KEY` | Override the Supabase anon key                  |
-| `PURVEY_DEBUG`                | Set to any value to enable verbose error output |
+Use the right ID for the right command.
 
----
+- `catalog_id`: coffee_catalog rows; used by `catalog get`, `inventory add --catalog-id`, `tasting get`, `roast list --catalog-id`
+- `inventory id`: green_coffee_inv rows; used by `inventory get/update/delete`, `roast --coffee-id`, `tasting rate`, `roast list --coffee-id`
+- `roast_id`: roast_data rows; used by `roast get/delete`, `sales --roast-id`, `roast list --roast-id`
+- `sale id`: coffee_sales rows; used by `sales update/delete`
 
-## For AI Agents
+## Environment Variables
 
-`purvey` is built with AI agents in mind. Every command has structured JSON output, clear error messages, and an `--headless` auth flow.
+- `PURVEYORS_SUPABASE_URL`: override the Supabase project URL
+- `PURVEYORS_SUPABASE_ANON_KEY`: override the Supabase anon key
+- `PURVEYORS_BASE_URL`: override the Purveyors web base URL
+- `PURVEY_DEBUG`: enable verbose error output
 
-### Agent Onboarding
+## For AI Agents
 
-Run this once to get complete CLI knowledge:
+Start here:
 
 ```bash
 purvey context
 ```
 
-This outputs a comprehensive, token-efficient reference covering all commands, required vs optional flags, data model relationships, common workflows, and error recovery. Designed for agents to read once and use every command correctly.
-
-### Agent Auth Flow
+Recommended flow:
 
 ```bash
 purvey auth login --headless
-# → prints OAuth URL
-# → user opens URL, signs in, pastes callback URL back
-# Token auto-refreshes; no further auth action needed.
-```
-
-### Agent Usage Pattern
-
-```bash
-# Check auth before any write operations
-purvey auth status
-
-# Always use JSON output (default) for scripting
-purvey catalog search --origin "Ethiopia" | jq '.[0].catalog_id'
-purvey inventory list | jq '.[] | select(.stocked == true) | .id'
-
-# Use --yes to skip confirmation prompts in automated flows
-purvey inventory delete 7 --yes
-purvey sales delete 5 --yes
+purvey auth status 2>/dev/null | jq .
+purvey inventory list | jq '.[].id'
 ```
 
-### ID Types (avoid confusion)
+The CLI is designed to be agent-friendly:
 
-| ID             | Table              | Used with                                                          |
-| -------------- | ------------------ | ------------------------------------------------------------------ |
-| `catalog_id`   | `coffee_catalog`   | `catalog get`, `inventory add --catalog-id`, `tasting get`         |
-| `inventory_id` | `green_coffee_inv` | `inventory get/update/delete`, `roast --coffee-id`, `tasting rate` |
-| `roast_id`     | `roast_data`       | `roast get/delete`, `sales --roast-id`                             |
-| `sale_id`      | `coffee_sales`     | `sales update/delete`                                              |
-
----
+- stable command names
+- structured output on stdout
+- headless auth flow
+- copy-pasteable examples
+- a dedicated `context` command for onboarding
 
 ## Development
 
@@ -366,71 +437,22 @@ purvey sales delete 5 --yes
 git clone https://github.com/reedwhetstone/purveyors-cli
 cd purveyors-cli
 pnpm install
+npm run build
+npm run check
+npm run lint
+npm test
 ```
 
-Create a `.env` file:
-
-```
-PURVEYORS_SUPABASE_URL=https://your-project.supabase.co
-PURVEYORS_SUPABASE_ANON_KEY=your-anon-key
-```
-
-Run locally:
-
-```bash
-pnpm dev -- auth status
-pnpm dev -- catalog search --origin Ethiopia --pretty
-pnpm dev -- --help
-```
-
-Build:
-
-```bash
-pnpm build
-```
-
-Lint + type check + test:
-
-```bash
-pnpm lint
-pnpm check
-pnpm test
-```
-
-### Architecture
-
-```
-src/
-  index.ts           Entry point — registers all subcommands
-  commands/          One file per command group
-    auth.ts          OAuth login/status/logout
-    catalog.ts       Public coffee catalog search
-    config.ts        CLI configuration
-    context.ts       Agent onboarding reference
-    inventory.ts     Green coffee inventory management
-    roast.ts         Roast profiles + Artisan .alog import
-    sales.ts         Sales recording
-    tasting.ts       Cupping notes and scoring
-  lib/               Business logic (no Commander dependencies)
-    supabase.ts      Auth client + session management
-    catalog.ts       Catalog query functions
-    inventory.ts     Inventory CRUD
-    roast.ts         Roast profile CRUD + import pipeline
-    sales.ts         Sales CRUD
-    tasting.ts       Tasting notes + cupping score logic
-    artisan/         Artisan .alog parser
-    interactive/     Interactive form prompts + watch mode
-    output.ts        JSON/CSV output formatting
-    errors.ts        Error handling + withErrorHandling wrapper
-    config.ts        Local config read/write
-```
-
-See [AGENTS.md](./AGENTS.md) for the full contributor guide including code conventions and PR requirements.
+Key files:
 
----
+- `src/index.ts`: top-level CLI registration and global options
+- `src/commands/`: command definitions and help text
+- `src/lib/`: business logic and Supabase integration
+- `src/commands/context.ts`: dense agent reference
+- `AGENTS.md`: contributor guide
 
 ## License
 
 Sustainable Use License. See [LICENSE.md](./LICENSE.md).
 
-Copyright © 2026 Reed Whetstone / purveyors.io
+Copyright 2026 Reed Whetstone / purveyors.io