brewsorted-cli 0.8.4__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,471 @@
1
+ # BrewSorted CLI reference
2
+
3
+ ## Product feedback
4
+
5
+ `brewsorted product-feedback submit --input -` reads a JSON object containing
6
+ only `message` from stdin; `--input @path` reads a file. Keep text out of command
7
+ arguments. The limit is 10,000 Unicode characters and accepted text is preserved.
8
+ Only explicit User instruction authorizes submission. It sends one private
9
+ report and returns `report_id` and `status: received`, without a browser link,
10
+ tracking or guaranteed reply. It is distinct from `suggestion-feedback`.
11
+ No report lookup exists. `feedback_delivery_uncertain` means storage may have
12
+ succeeded; another submission requires new explicit intent accepting a possible
13
+ duplicate. `feedback_rate_limited` includes `retry_after` seconds; never schedule
14
+ a retry automatically. Follow the skill's Product feedback consent rules.
15
+
16
+ ## Coffee commands and Connection setup
17
+
18
+ The CLI emits one JSON document. Configure its exact API origin and optional
19
+ browser origin outside the conversation, then establish a protected local OAuth
20
+ Connection:
21
+
22
+ ```bash
23
+ export BREWSORTED_API_URL=https://coffee.example
24
+ export BREWSORTED_WEB_URL=https://coffee.example
25
+ install -d -m 0700 "$HOME/.local/state/brewsorted"
26
+ export BREWSORTED_STATE_FILE="$HOME/.local/state/brewsorted/auth.json"
27
+ brewsorted login --device
28
+ brewsorted status
29
+ brewsorted context
30
+ ```
31
+
32
+ If the agent VM requires an HTTP proxy, use its standard `HTTPS_PROXY`
33
+ environment variable (for example, `http://proxy.example:8080`) for the HTTPS
34
+ service. `HTTP_PROXY`, fallback `ALL_PROXY`, destination bypass `NO_PROXY`, and
35
+ lowercase equivalents are supported. A global
36
+ `brewsorted --proxy http://proxy.example:8080 login --device` overrides all
37
+ proxy and bypass environment settings. Keep the same environment or explicit
38
+ option for later commands; proxy configuration also covers signing keys,
39
+ refresh and logout and is not stored in the Connection. Keep proxy credentials
40
+ in the protected environment outside chat. TLS verification stays enabled;
41
+ use the VM's trusted CA bundle through `SSL_CERT_FILE`/`SSL_CERT_DIR` when needed.
42
+
43
+ Keep the device-login process alive and relay only its exact verification URL
44
+ and short code. The intended User authorizes in their own browser. Never ask for
45
+ SSH access, a password, tokens, or recovery links. `status` is anonymous service
46
+ health; `context` is the authenticated check and refreshes an expired access
47
+ token from the protected binding when needed. Disposable CRUD with exact
48
+ Qualified IDs is separate write/read-back evidence.
49
+
50
+ Never request, display, paste, or echo an access token in chat or a command argument.
51
+ The CLI stores its protected Connection outside chat, sends access tokens only as
52
+ Bearer credentials to the exact configured HTTPS origin, and does not follow
53
+ redirects. HTTP API origins are accepted only on loopback for development. The
54
+ web URL is independent and is the origin a person can open in a browser. When
55
+ configured, item and list results include a `web_url`; brew comparisons include
56
+ `left_web_url` and `right_web_url`. Return those exact links for records you
57
+ mention. When those fields are absent, do not construct a substitute.
58
+
59
+ Every User-owned record uses the complete Qualified ID returned by the API,
60
+ such as `alex/41`. Never pass a bare number or combine the current Username with
61
+ a remembered number. Collections and name searches are already relative to the
62
+ authenticated User.
63
+
64
+ ## Operational boundary
65
+
66
+ For coffee-journal work, use only the documented CLI commands in this reference
67
+ and `brewsorted --help` or resource help. Source code, application schemas,
68
+ migrations, direct database access, undocumented HTTP requests, and application
69
+ changes are outside the operational capability surface. A separately authorized
70
+ repository-development task is not journal operation and may use its own tools.
71
+
72
+ If no documented CLI operation can produce the requested outcome, stop before
73
+ writing and report the requested outcome, current supported behavior, observed
74
+ limitation, user impact, desired capability, and known affected record IDs or
75
+ emitted links (`unknown` when none were identified). State the needed outcome
76
+ without prescribing its implementation. Do not substitute another
77
+ classification, fabricate a placeholder or duplicate, promise the missing
78
+ feature, or rewrite history. Any later reconciliation starts from identified
79
+ records and fresh user authorization.
80
+
81
+ First distinguish a capability gap from an incomplete lookup. `context` is
82
+ bounded. Search the relevant catalog and use its documented get operation when
83
+ needed. When the user genuinely requested a new Brew method, Drink type,
84
+ Equipment item, or other creatable catalog entity, check for duplicates and use
85
+ the supported create command.
86
+
87
+ ## Health and lookup
88
+
89
+ `status` and `context` may include a version-only `client_update` advisory.
90
+ `brewsorted updates` checks the configured service anonymously and reports
91
+ `current_version`, `recommended_version`, and `update_available`; null means
92
+ unknown. It does not install anything. After completing a coffee request, use
93
+ `brewsorted updates --claim-reminder` for a known advisory and append a reminder
94
+ only if `reminder_due` is true. Claims share a rolling 24-hour cooldown across
95
+ sessions and release versions using the same configured state file. The
96
+ timestamp lives in a separate mode-0600 `.update-reminder` file beside it;
97
+ unavailable metadata or unsafe/unwritable state suppresses unsolicited advice.
98
+ An explicit update question uses the plain command without claiming a reminder.
99
+
100
+ ```bash
101
+ brewsorted status
102
+ brewsorted context
103
+ brewsorted roasteries list --q "Square Mile"
104
+ brewsorted coffees list --q "Red Brick"
105
+ brewsorted coffees get alex/3
106
+ brewsorted bags list --coffee-id alex/3 --active
107
+ brewsorted bags get alex/21
108
+ brewsorted equipment list --q "Comandante" --type grinder
109
+ brewsorted equipment get alex/7
110
+ brewsorted equipment list --q "V60" --type brewer
111
+ brewsorted equipment list --tag travel
112
+ brewsorted equipment-types list
113
+ brewsorted brew-methods list --q "Pour-over"
114
+ brewsorted brew-methods get alex/2
115
+ brewsorted drink-types list --q "Flat white"
116
+ brewsorted drink-types get alex/5
117
+ brewsorted water-profiles list --q "Third Wave Water"
118
+ brewsorted water-profiles get alex/6
119
+ brewsorted recipes list --q "Weekday V60"
120
+ brewsorted recipes get alex/7
121
+ brewsorted brews list --bag-id alex/21
122
+ brewsorted brews get alex/41
123
+ brewsorted brew-ratings list --brew-id alex/41
124
+ brewsorted brew-ratings get alex/12
125
+ brewsorted suggestion-strategies list
126
+ brewsorted suggestions list --brew-id alex/41
127
+ brewsorted suggestions get alex/9
128
+ ```
129
+
130
+ Use `brewsorted context` to bootload a new agent session with up to ten distinct
131
+ recently used Equipment items, five Brew methods, Drink types, and active
132
+ Recipes, and the ten latest enriched Brews. Use its canonical `equipment` array; `devices` and
133
+ `grinders` are deprecated read projections for older clients. It is one bounded
134
+ API read and returns empty arrays for collections with no eligible records. When web links are
135
+ configured, each nested item has its own `web_url`.
136
+
137
+ ## Identity preflight
138
+
139
+ Reuse a fresh `context` result within the session. Do not run it before every
140
+ write, and use `status` only for health. Resolve every identity the pending
141
+ mutation references: Coffee, physical Bag, Equipment, Brew method, Drink type,
142
+ Water profile, Recipe, or target Brew/Tasting. Search/get outside bounded context
143
+ when necessary. Coffee and Bag are separate identities; after resolving Coffee,
144
+ use `bags list --coffee-id ID --active` and ask when multiple physical Bags are
145
+ plausible. Rating resources have no author identity.
146
+
147
+ Names are not IDs. One clear result from a broadened catalog search may resolve
148
+ a distorted spoken name, such as searching for the distinctive `C40` token when
149
+ speech transcription mangles `Comandante`. Ask when multiple plausible matches
150
+ remain. Also ask before writing an ambiguous number or unit or a suspicious
151
+ transcription outlier. Do not silently normalize it; once clarified, an unusual
152
+ valid value is allowed. Show a concise proposed-record preview when that helps
153
+ resolve identity or classification, but do not demand another confirmation for
154
+ an unambiguous action the user already authorized. Recipe apply retains its
155
+ required preview and confirmation.
156
+
157
+ ## Mutation verification
158
+
159
+ Send the smallest supported mutation once. For every successful non-delete
160
+ mutation, take the returned `id`, run the resource's documented `get ID`, and
161
+ compare important supplied fields and relationships against the saved item.
162
+ This applies to catalog records, Brews, ratings, Bag adjustments, and images.
163
+ After `recipes apply`, run `brews get RETURNED_ID` and compare the confirmed
164
+ draft, overrides, and `source_recipe_id`; do not apply again.
165
+
166
+ If the write returned success but the exact-record read fails, say that the
167
+ write succeeded, give its ID or emitted `web_url`, and label verification as
168
+ failed. If read-back succeeds with a discrepancy, report the mismatch without
169
+ issuing a corrective write.
170
+
171
+ For a transport or protocol failure with an uncertain mutation outcome, use
172
+ documented list/search reads and the supplied relationships, values, and time to
173
+ look for the result. Zero or multiple plausible matches leave the outcome
174
+ uncertain; do not choose the latest item or retry. If exactly one candidate
175
+ matches, read that candidate by ID and compare it before reporting success. Use
176
+ the resource's documented retrieval command when `get` is unavailable.
177
+
178
+ ## Semantic payloads
179
+
180
+ Classify each supplied value before constructing a command: a user-stated fact,
181
+ a transparent calculation, a hypothesis, or unresolved input. Prefer measured
182
+ facts. Disclose arithmetic when it matters, but do not write derived response
183
+ fields back as inputs. Expected flavor, brewing advice, and agent hypotheses are
184
+ not observed Brew or Tasting data.
185
+
186
+ Direct Brew create uses the Brew method's `ratio_basis`: input water by default,
187
+ or beverage yield for explicitly configured methods. Use measured dose and the
188
+ corresponding liquid quantity, without a redundant `--ratio`:
189
+
190
+ ```bash
191
+ brewsorted brews create --coffee-bag-id alex/21 --dose-g 15 --water-g 240
192
+ ```
193
+
194
+ When the supplied target is a ratio, omit `--water-g`:
195
+
196
+ ```bash
197
+ brewsorted brews create --coffee-bag-id alex/21 --dose-g 15 --ratio 16
198
+ ```
199
+
200
+ For a beverage-yield method, direct ratio input declares actual yield instead of
201
+ water. Yield is extracted coffee before milk or dilution. Both water and yield
202
+ may be recorded, but the method selects the ratio basis. Do not infer that basis
203
+ from method names or Drink type. Legacy `method_params.yield_g` does not count as
204
+ the required canonical measurement.
205
+
206
+ ```bash
207
+ brewsorted brew-methods create --name "Espresso" --ratio-basis beverage_yield
208
+ brewsorted brews create --coffee-bag-id alex/21 --brew-method-id alex/9 \
209
+ --dose-g 18 --beverage-weight-g 36
210
+ ```
211
+
212
+ If the required measurement was not recorded, obtain explicit permission before
213
+ using `--acknowledge-missing-ratio-measurement`. The returned ratio is null and
214
+ `warnings` explains the missing measurement. Never invent water or yield. An
215
+ unrelated edit preserves the acknowledgement; supplying the quantity clears it.
216
+ Clearing a measured quantity or changing to a basis with a missing measurement
217
+ requires renewed acknowledgement.
218
+
219
+ A Brew PATCH may omit both and preserves unspecified values:
220
+
221
+ ```bash
222
+ brewsorted brews update alex/41 --notes "Fast drawdown"
223
+ ```
224
+
225
+ Recipe create may have zero or one liquid target. Preview/apply merge omissions,
226
+ explicit values, and nulls under the Recipe override contract. A preview draft
227
+ can contain stored `water_g` plus derived `ratio`, while a read can also contain
228
+ read-only fields; neither response is a valid write payload. Build each create,
229
+ PATCH, preview, or apply request from the fields that operation accepts.
230
+
231
+ Put actual execution observations such as flow in Brew `notes`. Put tasted
232
+ sensory observations in `brew-ratings`; notes and diagnostics require no overall
233
+ score. Keep expected flavors and hypotheses out of Tasting records, and do not
234
+ add an author field. Extraction dose, water/yield, and beverage weight exclude
235
+ milk and dilution. Leave bloom, agitation, filter, beverage weight, Water
236
+ profile, TDS, and extraction yield unset unless the user actually supplied them.
237
+
238
+ Never substitute another Coffee, physical Bag, Equipment item, Brew method, or
239
+ Drink type. An optional classification can remain unset when that is meaningful
240
+ and disclosed. Required identity must be resolved; if the documented CLI cannot
241
+ do so, use the capability-gap workflow. Equipment does not imply method or
242
+ finished drink. A genuinely new user-requested catalog entry may still be
243
+ created after a duplicate search.
244
+
245
+ Keep a marketed Coffee product name intact and send supported attributes
246
+ separately, for example:
247
+
248
+ ```bash
249
+ brewsorted coffees create --roastery-id alex/1 --name "Worka Sakaro" \
250
+ --origin-country Ethiopia --producer-farm Worka \
251
+ --varietal Heirloom --process natural
252
+ ```
253
+
254
+ Use only supported Coffee fields and update existing catalog IDs in place. The
255
+ user-supplied/confirmed URL and image policy still applies.
256
+
257
+ ## Create records
258
+
259
+ ```bash
260
+ brewsorted images upload /path/to/logo.png
261
+ brewsorted roasteries create --name "Square Mile" --country UK \
262
+ --website "https://shop.squaremilecoffee.com" \
263
+ --image-id "d9428888-122b-41e1-b85c-61cd3cbb3210"
264
+ brewsorted coffees create --roastery-id alex/1 --name "Red Brick" --process washed \
265
+ --product-url "https://shop.squaremilecoffee.com/red-brick" \
266
+ --image-id "d9428888-122b-41e1-b85c-61cd3cbb3210"
267
+ brewsorted bags create --coffee-id alex/1 --roast-date 2026-08-28 --weight-g 250
268
+ brewsorted equipment create --name "Comandante C40" --type grinder \
269
+ --grinder-kind hand --burr-type conical --setting-scale stepped \
270
+ --scale-description "Clicks from zero" --scale-minimum 0 \
271
+ --scale-maximum 60 --scale-step 1 --scale-direction higher_is_coarser \
272
+ --tag filter --image-id UUID
273
+ brewsorted equipment create --name "Hario V60" --type brewer \
274
+ --brewer-kind pour-over --image-id UUID
275
+ brewsorted water-profiles update alex/1 --image-id UUID
276
+ brewsorted drink-types update alex/1 --image-id UUID
277
+ brewsorted brew-methods create --name "Cold drip" \
278
+ --description "Slow percolation through a coffee bed"
279
+ brewsorted brew-methods update alex/1 --image-id UUID
280
+ brewsorted brews create --coffee-bag-id alex/1 --brewer-id alex/2 --grinder-id alex/1 \
281
+ --brew-method-id alex/1 --grind-setting 22 --dose-g 15 --ratio 16 \
282
+ --water-temp-c 94 --total-time-s 2:30
283
+ brewsorted recipes create --name "Weekday V60" --brewer-id alex/2 \
284
+ --grinder-id alex/1 --grind-setting 22 --dose-g 15 --ratio 16 \
285
+ --instructions "Bloom, then pour in two stages"
286
+ ```
287
+
288
+ Use either typed flags or `--input -` for stdin JSON or `--input @path` for a
289
+ JSON file. Do not combine them.
290
+
291
+ Roastery `--website` and Coffee `--product-url` accept absolute HTTP(S) URLs
292
+ without credentials. Pass through only values the user supplied or confirmed.
293
+ Managed images accept JPEG, PNG, or WebP files. Upload first, then pass the
294
+ returned UUID through `--image-id` for a Roastery, Coffee, Equipment item,
295
+ Water profile, Drink type, or Brew method; clear an attachment with JSON null
296
+ in an update. Brew methods support create, list, get, update, and delete; create
297
+ requires a unique nonblank name, while description and image are optional.
298
+ Resolve a requested method with `brew-methods list --q` and use its ID. Equipment
299
+ never selects a method, and a custom method does not imply Suggestion support.
300
+ `images get USERNAME/UUID`
301
+ inspects metadata and `images delete USERNAME/UUID` soft-deletes an image only when none
302
+ of those catalog records references it.
303
+
304
+ Equipment types are fixed: `brewer`, `grinder`, `kettle`, `scale`, `server`,
305
+ `filter`, and `other`. Names are not unique. When a lookup has multiple plausible
306
+ matches, present each candidate's ID, type, and tags and ask the person to choose.
307
+ Primary Brew flags require the matching type. Repeat
308
+ `--additional-equipment-id` to preserve extra ordering, but never repeat an ID or
309
+ select one ID in both a primary slot and extras.
310
+
311
+ `--grind-setting` is a JSON number and requires `--grinder-id`. Read the chosen
312
+ Equipment first and apply only its recorded scale bounds and increment. Step alignment starts
313
+ at the scale minimum when present and at zero otherwise. Missing
314
+ scale values remain unknown: do not invent units, bounds, a step, direction, or
315
+ cross-grinder conversion. Brew reads may contain exact
316
+ `legacy_grind_setting`; if `grind_setting` is null, describe that legacy text as
317
+ unresolved rather than interpreting it.
318
+
319
+ ## Read, update, and delete
320
+
321
+ ```bash
322
+ brewsorted coffees get alex/1
323
+ brewsorted coffees update alex/1 --notes "Best after day 10"
324
+ brewsorted coffees delete alex/1
325
+ brewsorted brews history --coffee-id alex/1
326
+ brewsorted brews latest --coffee-id alex/1
327
+ brewsorted brews compare alex/10 alex/11
328
+ brewsorted recipes get alex/7
329
+ brewsorted recipes update alex/7 --water-temp-c 92
330
+ brewsorted recipes delete alex/7
331
+ ```
332
+
333
+ ## Preview and apply Recipes
334
+
335
+ ```bash
336
+ brewsorted recipes preview alex/7 --coffee-bag-id alex/4
337
+ brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --grind-setting 22
338
+ brewsorted recipes apply alex/7 --coffee-bag-id alex/4 --grind-setting 22
339
+ ```
340
+
341
+ Preview first with the intended overrides. It performs no write and returns the
342
+ resolved `draft`, every ordered `issue`, and `can_create`. Do not invent values
343
+ for missing fields or inactive references. Present the draft and issues, then
344
+ apply only after `can_create` is true and the person confirms it. Use the same
345
+ overrides for apply. Recipe names are not unique, so resolve ambiguous list
346
+ matches by ID. Applying creates one ordinary Brew with copied instructions and
347
+ source identity; the Recipe itself is never evidence that brewing occurred.
348
+
349
+ Recipe defaults populate the Brew's quantities without duplicate input. Beverage
350
+ yield Recipes can use `--target-beverage-weight-g` or a ratio; that target is
351
+ distinct from actual `--beverage-weight-g` in preview/application overrides.
352
+ For explicit scaling use `--scale-from dose` or `--scale-from liquid`, supplying
353
+ only the anchor quantity, not the side being calculated. Editing quantities
354
+ without scaling preserves the other value. The target ratio stays fixed.
355
+
356
+ ```bash
357
+ brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --dose-g 20 --scale-from dose
358
+ brewsorted recipes preview alex/7 --coffee-bag-id alex/4 --beverage-weight-g 40 \
359
+ --allow-ratio-override
360
+ ```
361
+
362
+ Actual ratio deviations within 5% inclusive need no flag; larger deviations
363
+ require the User's explicit permission for `--allow-ratio-override`. This records
364
+ actual values, never edits the Recipe. For a deliberately unrecorded quantity,
365
+ clear its inherited default through `--input` with explicit null and add the
366
+ missing-measurement acknowledgement. Ratio-free Recipes remain usable. A stale
367
+ Recipe target basis must be explicitly replaced or cleared, not bypassed with
368
+ the deviation flag. Show preview warnings as well as blocking issues, then apply
369
+ the same confirmed overrides once.
370
+
371
+ ## Ratings
372
+
373
+ ```bash
374
+ brewsorted brew-ratings create --brew-id alex/11 --notes "Sweeter after cooling"
375
+ brewsorted brew-ratings update alex/12 --overall 8
376
+ brewsorted brew-ratings list --brew-id alex/11
377
+ brewsorted coffee-ratings create --coffee-id alex/1 --overall 5 --would-rebuy
378
+ brewsorted coffee-ratings list --coffee-id alex/1
379
+ ```
380
+
381
+ A brew tasting needs at least one observation: an overall score, diagnostic
382
+ field, or nonblank notes. Overall is optional and must never be inferred. Use
383
+ JSON input with `"overall": null` to clear a score while retaining another
384
+ observation. Coffee-product ratings still require `--overall`.
385
+
386
+ ## Grounded Suggestions, Attempts, and Feedback
387
+
388
+ ```bash
389
+ brewsorted suggestion-strategies list
390
+ brewsorted suggestions create --brew-id alex/41
391
+ brewsorted suggestions create --brew-id alex/41 \
392
+ --strategy-id rules.filter-dial-in.v1
393
+ brewsorted suggestions list --brew-id alex/41 --outcome proposed \
394
+ --strategy-id rules.filter-dial-in.v1
395
+ brewsorted suggestions get alex/9
396
+ brewsorted suggestion-attempts create --suggestion-id alex/9 --brew-id alex/44
397
+ brewsorted suggestion-attempts get alex/3
398
+ brewsorted suggestion-feedback create --attempt-id alex/3 --outcome unclear \
399
+ --notes "Needs another cup"
400
+ brewsorted suggestion-feedback list --attempt-id alex/3
401
+ brewsorted suggestion-feedback get alex/7
402
+ ```
403
+
404
+ Suggestion create accepts the optional body through `--input -` or
405
+ `--input @path` while retaining the required target `--brew-id`. Attempt create
406
+ retains `--suggestion-id`; its body may supply `brew_id` through a typed flag or
407
+ JSON input. Feedback create retains `--attempt-id`; its body may supply
408
+ `outcome` and optional nonblank `notes` through typed flags or JSON input.
409
+
410
+ The default strategy is deterministic and local. Repeat the API's frozen facts,
411
+ analysis runs, inference, proposed change, uncertainty, Knowledge card/source
412
+ snapshots, and insufficiency exactly enough to keep those categories distinct.
413
+ An insufficient result contains no fallback change. A missing score is not zero
414
+ and is never a reason to invent a diagnosis.
415
+
416
+ Before Attempt creation, read the later Brew and obtain explicit confirmation
417
+ that its different recorded grind setting tried the proposed direction. The API
418
+ captures numeric or exact legacy setting and Grinder scale context; neither the
419
+ CLI nor agent calculates a next setting. Before Feedback creation, obtain an
420
+ explicit `yes`, `no`, or `unclear`; append corrections as new Feedback rather
421
+ than interpreting a Tasting or score.
422
+
423
+ Configured Suggestion create/get/list output includes `web_url` with the stable
424
+ `/suggestions/{id}` route. Attempt and Feedback output includes
425
+ `suggestion_web_url` for that parent chain. Return only those emitted links.
426
+
427
+ ## Bag inventory adjustments
428
+
429
+ ```bash
430
+ brewsorted bag-adjustments create --bag-id alex/1 --change-g -18 \
431
+ --reason untracked_use --notes "Made coffee without logging a Brew"
432
+ brewsorted bag-adjustments create --bag-id alex/1 --remaining-weight-g 72 \
433
+ --reason correction --notes "Scale reading"
434
+ brewsorted bag-adjustments create --bag-id alex/1 --finish \
435
+ --reason finished_early --notes "Discarded the remainder"
436
+ brewsorted bag-adjustments list --bag-id alex/1
437
+ brewsorted bag-adjustments get alex/3
438
+ ```
439
+
440
+ Use exactly one create mode. `--change-g` is signed: negative removes beans and
441
+ positive adds them. Prefer `--remaining-weight-g` when the user states what is
442
+ actually left. `--finish` reconciles to zero and dates the Bag; use it only for
443
+ an explicit finish request. Reasons are `correction`, `untracked_use`,
444
+ `spillage`, `finished_early`, or `other`. Adjustments are immutable and never a
445
+ substitute for changing an actually incorrect Brew dose.
446
+
447
+ ## Exit codes
448
+
449
+ - `0`: success
450
+ - `2`: usage or local input error
451
+ - `3`: backend connection error
452
+ - `4`: API client error
453
+ - `5`: API server error
454
+
455
+ On failure, parse the problem document from stderr. A connection failure means
456
+ the local service may need `brewsorted-api serve --db ./coffee.db --port 8765`.
457
+ For `401`, report that authentication failed without asking for the token. For
458
+ `403`, report that the configured credential or User state cannot perform the
459
+ operation. Treat `404` as absent or inaccessible without probing foreign
460
+ existence. Treat `422 invalid_reference` as an invalid reference, re-resolve it
461
+ from authenticated collections, and never echo foreign-record detail.
462
+
463
+ ## Finished drinks
464
+
465
+ Look up explicit drink names with `brewsorted drink-types list --q "Latte"`.
466
+ Create a custom type with `brewsorted drink-types create --name "Iced latte"`;
467
+ the catalog also supports get, update, and delete using standard resource forms.
468
+ Pass the returned ID as `--drink-type-id` to Brew create/update/list/history.
469
+ Clear an assignment with update JSON (`{"drink_type_id": null}`) through `--input`.
470
+ Drink type identifies what was served; Brew measurements describe extraction and
471
+ Tastings describe that finished drink. Unspecified types remain unclassified.