@slothmoney/agent-cli 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## Unreleased
 
+## 0.9.1 - 2026-08-15
+
+- Clarify how personal and joint category assignments appear in transaction
+  results and how assignment scope affects uncategorised filters.
+- Document complete category and line-item assignments, including the
+  category-specific `Other` fallback when no more specific line item fits.
+- Extend command-help and clean-installed package checks for the categorisation
+  workflow.
+
 ## 0.9.0 - 2026-08-12
 
 - Manage owned manual balance and manual transaction accounts through partial

package/README.md

@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.9.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.9.1 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -115,6 +115,34 @@ sloth-agent goals update --help
 sloth-agent ask-partner --help
 ```
 
+### How transaction categorisation is represented
+
+Personal and joint category assignments are separate. A personal assignment
+uses the transaction's top-level `categoryId`, `lineItemId`, and
+`categorySplits`. A joint-budget assignment uses the corresponding fields under
+`jointBudgetContribution`.
+
+A transaction can have no personal category while its joint-budget contribution
+already has a category and line item. To assess a transaction's categorisation,
+inspect both locations. An included joint contribution with a category and line
+item is already categorised for the joint budget. For example:
+
+```json
+{
+  "categoryId": null,
+  "lineItemId": null,
+  "jointBudgetContribution": {
+    "included": true,
+    "categoryId": "groceries",
+    "lineItemId": "joint-groceries"
+  }
+}
+```
+
+This transaction is uncategorised personally but categorised as Groceries for
+the joint budget. The `--uncategorized` filter applies to the selected
+assignment scope; personal is used when `--assignment-scope` is omitted.
+
 ### Categorise a transaction end to end
 
 1. Read categories and available budget line items:
@@ -127,23 +155,43 @@ A category is the broader parent. A line item is a child within one category.
 Line-item names such as `Other` may repeat, so preserve the full choice as
 `(scope, categoryId, lineItemId)`. Use the personal or joint line-item map that
 matches the transaction scope. For example, `Bills → Other` and `Subscriptions
-→ Other` are different choices.
+→ Other` are different choices. Choose the most specific suitable line item;
+if none fits, use that category's `Other` line item. Historical assignments
+without a line item should not be treated as a recommendation to omit one.
 
 2. Read uncategorised transactions:
 
 ```bash
-sloth-agent transactions --uncategorized --limit 50
+sloth-agent transactions \
+  --assignment-scope personal \
+  --uncategorized \
+  --limit 50
 ```
 
-3. Copy the exact `transactionRef` for the transaction and a `categoryId` from
-   the earlier outputs into `assignments.json`:
+To read uncategorised joint-budget contributions instead:
+
+```bash
+sloth-agent transactions \
+  --assignment-scope joint \
+  --uncategorized \
+  --limit 50
+```
+
+The remaining example continues with a personal assignment. For a joint
+assignment, set `"assignmentScope": "joint"` in the assignment payload and use
+`--assignment-scope joint` when checking the result.
+
+3. Copy the exact `transactionRef`, `categoryId`, and `lineItemId` from the
+   earlier outputs into `assignments.json`:
 
 ```json
 {
   "assignments": [
     {
       "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",
-      "categoryId": "PASTE_A_CATEGORY_ID_HERE"
+      "assignmentScope": "personal",
+      "categoryId": "PASTE_A_CATEGORY_ID_HERE",
+      "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"
     }
   ]
 }
@@ -172,17 +220,19 @@ This step requires a token created with **Allow changes**.
 
 Inspect every item in the returned `succeeded` and `failed` arrays.
 
-6. Check the result. Successful assignments update the category and optional
-   budget line item on the original transaction. See the result in **Sloth
-   Money → Transactions**, or re-run the original transaction query without
-   `--uncategorized` and inspect its category fields:
+6. Check the result in the same assignment scope that you changed. Successful
+   assignments update the category and optional budget line item on the
+   original transaction. See the result in **Sloth Money → Transactions**, or
+   re-run the original transaction query without `--uncategorized` and inspect
+   both the personal and joint category fields:
 
 ```bash
-sloth-agent transactions --limit 50
+sloth-agent transactions --assignment-scope personal --limit 50
 ```
 
 The transaction should also disappear from the matching `--uncategorized`
-query. Assignments do not create a separate list.
+query. Confirm that an existing assignment in the other scope was not changed.
+Assignments do not create a separate list.
 
 ### Other workflows
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, validateAssignmentPayload, validateBudgetUpdatePayload, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.9.0';
+export const CLI_VERSION = '0.9.1';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -185,6 +185,8 @@ export function categoriesHelpText() {
         '  Line-item names such as "Other" may repeat. Preserve the full choice as',
         '  (scope, categoryId, lineItemId), using the personal or joint line-item',
         '  map matching the transaction scope.',
+        '  Choose the most specific suitable line item. If none fits, use that',
+        '  category\'s "Other" line item.',
         '',
         'Examples:',
         '  sloth-agent categories',
@@ -463,7 +465,8 @@ export function transactionsHelpText() {
         '  sloth-agent transactions [options]',
         '',
         'Options:',
-        '  --uncategorized[=true|false]  Optional. Filter by state; with no value, use true.',
+        '  --uncategorized[=true|false]  Optional. Filter the selected assignment scope by state;',
+        '                                  with no value, use true.',
         '  --limit N                     Optional. Integer from 1 to 200; omit for API default.',
         '  --start-date YYYY-MM-DD        Optional. Include transactions on or after this date.',
         '  --end-date YYYY-MM-DD          Optional. Include transactions on or before this date.',
@@ -472,6 +475,7 @@ export function transactionsHelpText() {
         '  --category-id ID               Optional. Filter by category ID.',
         '  --line-item-id ID              Optional. Filter primary or split assignments by line-item ID.',
         '  --assignment-scope SCOPE        Optional. Filter assignments by personal or joint.',
+        '                                  Personal is used when omitted.',
         '  --cursor CURSOR                Optional. Continue from a previous nextCursor.',
         '  --base-url URL                 Optional. Override the API origin.',
         '  -h, --help                     Show this help.',
@@ -487,6 +491,10 @@ export function transactionsHelpText() {
         'Output:',
         '  JSON containing transactions, nextCursor, and structured refresh status.',
         '  Refresh failures do not hide readable cached transactions.',
+        '  Personal assignments use the top-level categoryId, lineItemId, and categorySplits.',
+        '  Joint assignments appear under jointBudgetContribution.',
+        '  A transaction can be uncategorised personally while its joint-budget contribution',
+        '  is already categorised. To assess its categorisation, inspect both locations.',
         '  Use nextCursor with --cursor',
         '  to request the next page. A null nextCursor means there are no more pages.',
         '',
@@ -529,29 +537,34 @@ export function assignHelpText() {
         '  categories output. The example values below are placeholders.',
         '  Set categoryId to null to clear an assignment.',
         '  lineItemId is optional and accepts a non-empty string or null.',
+        '  When the category has line items, choose the most specific suitable line item.',
+        '  If none fits, use that category\'s Other line item from the matching scope.',
         '  categorySplits is optional and accepts a non-empty array or null.',
         '  Each split requires categoryId and a positive integer amountPence;',
         '  a split lineItemId is optional.',
         '  incomeSubtype is optional and accepts "pay", "interest", or null.',
         '  assignmentScope is optional and accepts "personal" or "joint".',
+        '  Personal is used when assignmentScope is omitted.',
         '',
         'Workflow:',
         '  sloth-agent categories',
-        '  sloth-agent transactions --uncategorized --limit 50',
+        '  sloth-agent transactions --assignment-scope personal --uncategorized --limit 50',
         '  sloth-agent assign --input assignments.json          Preview only',
         '  sloth-agent assign --input assignments.json --apply  Write assignments',
-        '  sloth-agent transactions --limit 50                  Read back the result',
+        '  sloth-agent transactions --assignment-scope personal --limit 50  Read back',
         '',
         'Example:',
         '  {',
         '    "assignments": [',
         '      {',
         '        "transactionRef": "PASTE_THE_EXACT_TRANSACTION_REF_HERE",',
-        '        "categoryId": "PASTE_A_CATEGORY_ID_HERE"',
+        '        "assignmentScope": "personal",',
+        '        "categoryId": "PASTE_A_CATEGORY_ID_HERE",',
+        '        "lineItemId": "PASTE_A_LINE_ITEM_ID_HERE"',
         '      }',
         '    ]',
         '  }',
-        '  These are placeholders. Replace both values with exact IDs from CLI output.',
+        '  These are placeholders. Replace all three values with exact IDs from CLI output.',
         '',
         'Output:',
         '  Preview mode returns dryRun, endpoint, and the validated payload.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slothmoney/agent-cli",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Command-line access to the Sloth Money Agent API.",
   "type": "module",
   "bin": {