@slothmoney/agent-cli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,22 @@
 # Changelog
 
-## Unreleased
+## 0.10.0 - 2026-08-15
+
+- Require every goal create to specify a positive target amount and Keep or
+  Spend type, matching the breaking Agent Goals API v1 contract.
+- Expose `goalType` and nullable `spentAt`, allow active goal type changes, and
+  remove obsolete `isAchieved` and target-amount clearing assumptions.
+- Add preview-by-default `goals mark-spent` and `goals restore` actions that
+  send the canonical `isSpent` lifecycle update only with `--apply`.
+
+## 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
 

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.10.0 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -112,9 +112,39 @@ sloth-agent transactions --help
 sloth-agent assign --help
 sloth-agent goals create --help
 sloth-agent goals update --help
+sloth-agent goals mark-spent --help
+sloth-agent goals restore --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 +157,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 +222,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
 
@@ -363,45 +415,64 @@ Goal writes are previews unless `--apply` is present:
 sloth-agent goals create \
   --name "Emergency fund" \
   --target-amount 12000 \
-  --target-month 2027-06
+  --type keep
 
 sloth-agent goals create \
-  --name "Emergency fund" \
-  --target-amount 12000 \
+  --name "Wedding" \
+  --target-amount 22000 \
   --target-month 2027-06 \
+  --type spend \
   --apply
 ```
 
-Use the `id` from list or create output to update or delete goals:
+Every goal is either Keep or Spend. A Keep goal continues reserving its funded
+money. A Spend goal reserves money until you explicitly mark it spent. Goal
+list, create, and update output includes lowercase `goalType` and nullable
+`spentAt`; `spentAt` is an ISO timestamp only after a Spend goal is marked
+spent.
+
+Use the `id` from list or create output to update a goal, change its type, or
+move it in the priority order:
 
 ```bash
 sloth-agent goals update \
   --goal-id goal-id \
-  --clear-target-amount \
   --target-month 2027-12 \
-  --achieved=false \
+  --type spend \
   --apply
 
 sloth-agent goals update \
   --goal-id house-goal-id \
   --priority 2 \
   --apply
+```
+
+Marking spent and restoring are also previews by default:
+
+```bash
+sloth-agent goals mark-spent --goal-id goal-id
+sloth-agent goals mark-spent --goal-id goal-id --apply
+
+sloth-agent goals restore --goal-id goal-id
+sloth-agent goals restore --goal-id goal-id --apply
 
 sloth-agent goals delete --goal-id goal-id --apply
 ```
 
-Updates are partial. Use `--clear-target-amount` or `--clear-target-month` to
-remove an optional value. Marking a goal achieved removes its forecast
-assignment. Deleting a goal also removes its forecast assignments and drift
-history. Goal sharing remains app-managed. Change an active shared goal's
-pot-tracked target amount in the Sloth Budget app, where account balances can
-be reallocated across goals in priority order. Goal list output includes a
+Updates are partial. Use `--clear-target-month` to remove the optional month.
+A Keep goal cannot be marked spent. A spent goal must be restored before its
+type can change; the API returns these lifecycle conflicts without hiding the
+required recovery action. Restoring clears `spentAt` and returns the goal to
+allocation at its saved priority. Deleting a goal also removes its forecast
+assignments and drift history.
+
+Goal sharing remains app-managed. Change an active shared goal's pot-tracked
+target amount in the Sloth Budget app, where account balances can be
+reallocated across goals in priority order. Goal list output includes a
 one-based `priority`; `1` is highest. Moving one goal automatically shifts the
-goals between its old and new positions. The
-priority option must be used on its own, and the write persists immediately.
-Forecast assignments and shared pot
-progress are browser-owned derived state and refresh when the owner next opens
-the Forecast screen.
+goals between its old and new positions. The priority option must be used on
+its own. Forecast assignments and shared pot progress are browser-owned
+derived state and refresh when the owner next opens the Forecast screen.
 
 Read uncategorised contributions to the joint budget:
 

package/dist/args.js

@@ -1,5 +1,6 @@
 import { UsageError } from './errors.js';
 import { CATEGORY_TYPES, ICON_KEYS, } from './category-metadata.js';
+import { isGoalType, } from './goal-metadata.js';
 const PRODUCTION_BASE_URL = 'https://budget.slothmoney.app';
 const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 function readOptionValue(args, index, name) {
@@ -74,11 +75,11 @@ function parseGoalPriority(value) {
     }
     return priority;
 }
-function parseExplicitBoolean(value, name) {
-    if (value !== 'true' && value !== 'false') {
-        throw new UsageError(`${name} must be true or false`);
+function parseGoalType(value) {
+    if (!isGoalType(value)) {
+        throw new UsageError('--type must be keep or spend');
     }
-    return value === 'true';
+    return value;
 }
 function parseGoalName(value) {
     const name = value.trim();
@@ -500,6 +501,7 @@ function parseGoals(args, baseUrl) {
         let name;
         let targetAmount;
         let targetMonthKey;
+        let goalType;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
             const argument = args[index];
@@ -514,7 +516,8 @@ function parseGoals(args, baseUrl) {
                 : [argument, undefined];
             if (option !== '--name'
                 && option !== '--target-amount'
-                && option !== '--target-month') {
+                && option !== '--target-month'
+                && option !== '--type') {
                 throw new UsageError(`Unknown goals create option: ${argument}`);
             }
             const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
@@ -526,17 +529,27 @@ function parseGoals(args, baseUrl) {
             else if (option === '--target-amount') {
                 targetAmount = setOnce(targetAmount, parseGoalAmount(value, option), option);
             }
-            else {
+            else if (option === '--target-month') {
                 targetMonthKey = setOnce(targetMonthKey, parseGoalMonthKey(value, option), option);
             }
+            else {
+                goalType = setOnce(goalType, parseGoalType(value), option);
+            }
         }
         if (!name)
             throw new UsageError('goals create requires --name <name>');
+        if (targetAmount === undefined) {
+            throw new UsageError('goals create requires --target-amount <amount>');
+        }
+        if (goalType === undefined) {
+            throw new UsageError('goals create requires --type <keep|spend>');
+        }
         return withBaseUrl({
             command: 'goals-create',
             name,
-            ...(targetAmount === undefined ? {} : { targetAmount }),
+            targetAmount,
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
+            goalType,
             apply,
         }, baseUrl);
     }
@@ -545,7 +558,7 @@ function parseGoals(args, baseUrl) {
         let name;
         let targetAmount;
         let targetMonthKey;
-        let isAchieved;
+        let goalType;
         let priority;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
@@ -556,13 +569,6 @@ function parseGoals(args, baseUrl) {
                 apply = true;
                 continue;
             }
-            if (argument === '--clear-target-amount') {
-                if (targetAmount !== undefined) {
-                    throw new UsageError('--target-amount and --clear-target-amount are mutually exclusive');
-                }
-                targetAmount = null;
-                continue;
-            }
             if (argument === '--clear-target-month') {
                 if (targetMonthKey !== undefined) {
                     throw new UsageError('--target-month and --clear-target-month are mutually exclusive');
@@ -577,7 +583,7 @@ function parseGoals(args, baseUrl) {
                 && option !== '--name'
                 && option !== '--target-amount'
                 && option !== '--target-month'
-                && option !== '--achieved'
+                && option !== '--type'
                 && option !== '--priority') {
                 throw new UsageError(`Unknown goals update option: ${argument}`);
             }
@@ -591,10 +597,7 @@ function parseGoals(args, baseUrl) {
                 name = setOnce(name, parseGoalName(value), option);
             }
             else if (option === '--target-amount') {
-                if (targetAmount !== undefined) {
-                    throw new UsageError('--target-amount and --clear-target-amount are mutually exclusive');
-                }
-                targetAmount = parseGoalAmount(value, option);
+                targetAmount = setOnce(targetAmount, parseGoalAmount(value, option), option);
             }
             else if (option === '--target-month') {
                 if (targetMonthKey !== undefined) {
@@ -606,7 +609,7 @@ function parseGoals(args, baseUrl) {
                 priority = setOnce(priority, parseGoalPriority(value), option);
             }
             else {
-                isAchieved = setOnce(isAchieved, parseExplicitBoolean(value, option), option);
+                goalType = setOnce(goalType, parseGoalType(value), option);
             }
         }
         if (!goalId)
@@ -614,7 +617,7 @@ function parseGoals(args, baseUrl) {
         if (name === undefined
             && targetAmount === undefined
             && targetMonthKey === undefined
-            && isAchieved === undefined
+            && goalType === undefined
             && priority === undefined) {
             throw new UsageError('goals update requires at least one field to update');
         }
@@ -622,7 +625,7 @@ function parseGoals(args, baseUrl) {
             && (name !== undefined
                 || targetAmount !== undefined
                 || targetMonthKey !== undefined
-                || isAchieved !== undefined)) {
+                || goalType !== undefined)) {
             throw new UsageError('--priority must be used on its own');
         }
         return withBaseUrl({
@@ -631,12 +634,14 @@ function parseGoals(args, baseUrl) {
             ...(name === undefined ? {} : { name }),
             ...(targetAmount === undefined ? {} : { targetAmount }),
             ...(targetMonthKey === undefined ? {} : { targetMonthKey }),
-            ...(isAchieved === undefined ? {} : { isAchieved }),
+            ...(goalType === undefined ? {} : { goalType }),
             ...(priority === undefined ? {} : { priority }),
             apply,
         }, baseUrl);
     }
-    if (subcommand === 'delete') {
+    if (subcommand === 'mark-spent'
+        || subcommand === 'restore'
+        || subcommand === 'delete') {
         let goalId;
         let apply = false;
         for (let index = 0; index < args.length; index += 1) {
@@ -651,17 +656,22 @@ function parseGoals(args, baseUrl) {
                 ? argument.split(/=(.*)/s, 2)
                 : [argument, undefined];
             if (option !== '--goal-id') {
-                throw new UsageError(`Unknown goals delete option: ${argument}`);
+                throw new UsageError(`Unknown goals ${subcommand} option: ${argument}`);
             }
             const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
             if (inlineValue === undefined)
                 index += 1;
             goalId = setOnce(goalId, parseGoalId(value), option);
         }
-        if (!goalId)
-            throw new UsageError('goals delete requires --goal-id <id>');
+        if (!goalId) {
+            throw new UsageError(`goals ${subcommand} requires --goal-id <id>`);
+        }
         return withBaseUrl({
-            command: 'goals-delete',
+            command: subcommand === 'mark-spent'
+                ? 'goals-mark-spent'
+                : subcommand === 'restore'
+                    ? 'goals-restore'
+                    : 'goals-delete',
             goalId,
             apply,
         }, baseUrl);
@@ -699,6 +709,10 @@ function helpTopic(argv) {
             return 'goals-create';
         if (subcommand === 'update')
             return 'goals-update';
+        if (subcommand === 'mark-spent')
+            return 'goals-mark-spent';
+        if (subcommand === 'restore')
+            return 'goals-restore';
         if (subcommand === 'delete')
             return 'goals-delete';
         return 'goals';

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.10.0';
 const REQUEST_TIMEOUT_MS = 60_000;
 const API_ORIGIN_HELP_LINES = [
     '',
@@ -43,9 +43,11 @@ export function usageText() {
         '    [--cursor CURSOR] [--base-url URL]',
         '  sloth-agent assign --input assignments.json [--apply] [--base-url URL]',
         '  sloth-agent goals [list] [--base-url URL]',
-        '  sloth-agent goals create --name NAME [--target-amount AMOUNT]',
-        '    [--target-month YYYY-MM] [--apply] [--base-url URL]',
+        '  sloth-agent goals create --name NAME --target-amount AMOUNT',
+        '    --type keep|spend [--target-month YYYY-MM] [--apply] [--base-url URL]',
         '  sloth-agent goals update --goal-id ID [fields] [--apply] [--base-url URL]',
+        '  sloth-agent goals mark-spent --goal-id ID [--apply] [--base-url URL]',
+        '  sloth-agent goals restore --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent goals delete --goal-id ID [--apply] [--base-url URL]',
         '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
         '',
@@ -185,6 +187,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 +467,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 +477,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 +493,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 +539,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.',
@@ -565,12 +580,14 @@ export function goalsHelpText() {
     return [
         'Sloth Agent CLI — goals',
         '',
-        'List, create, update, or delete your savings goals.',
+        'List, create, update, mark spent, restore, or delete your savings goals.',
         '',
         'Commands:',
         '  sloth-agent goals list      List goals; "sloth-agent goals" is equivalent.',
         '  sloth-agent goals create    Preview or create a goal.',
         '  sloth-agent goals update    Preview or update selected goal fields.',
+        '  sloth-agent goals mark-spent Preview or mark a Spend goal spent.',
+        '  sloth-agent goals restore   Preview or restore a spent goal.',
         '  sloth-agent goals delete    Preview or permanently delete a goal.',
         '',
         'Help:',
@@ -598,7 +615,8 @@ export function goalsListHelpText() {
         '',
         'Output:',
         '  JSON containing currency and goals. Each goal contains id, name, priority,',
-        '  targetAmount, targetMonthKey, isAchieved, and sharedWithPartner.',
+        '  targetAmount, targetMonthKey, goalType, nullable spentAt, and',
+        '  sharedWithPartner.',
     ].join('\n');
 }
 export function goalsCreateHelpText() {
@@ -608,11 +626,12 @@ export function goalsCreateHelpText() {
         'Preview or create a goal.',
         '',
         'Usage:',
-        '  sloth-agent goals create --name NAME [options]',
+        '  sloth-agent goals create --name NAME --target-amount AMOUNT --type keep|spend [options]',
         '',
         'Options:',
         '  --name NAME                 Required. Goal name, 1 to 200 characters.',
-        '  --target-amount AMOUNT      Optional. Positive major-unit amount with up to 2 decimals.',
+        '  --target-amount AMOUNT      Required. Positive major-unit amount with up to 2 decimals.',
+        '  --type keep|spend           Required. Keep reserves funded money; Spend is spent later.',
         '  --target-month YYYY-MM      Optional. Target calendar month.',
         '  --apply                     Optional. Create the goal in Sloth Money.',
         '  --base-url URL              Optional. Override the API origin.',
@@ -625,8 +644,8 @@ export function goalsCreateHelpText() {
         '  New goals are private to the owner and appended to the existing goal order.',
         '',
         'Example:',
-        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000',
-        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --apply',
+        '  sloth-agent goals create --name "Emergency fund" --target-amount 12000 --type keep',
+        '  sloth-agent goals create --name "Wedding" --target-amount 22000 --type spend --target-month 2027-06 --apply',
         '',
         'Output:',
         '  Preview mode returns dryRun, method, endpoint, and payload.',
@@ -646,10 +665,9 @@ export function goalsUpdateHelpText() {
         '  --goal-id ID                 Required. Goal ID from goals list or create output.',
         '  --name NAME                  Optional. Replacement name, 1 to 200 characters.',
         '  --target-amount AMOUNT       Optional. Positive amount with up to 2 decimals.',
-        '  --clear-target-amount        Optional. Remove the target amount.',
         '  --target-month YYYY-MM       Optional. Replace the target month.',
         '  --clear-target-month         Optional. Remove the target month.',
-        '  --achieved=true|false        Optional. Mark the goal achieved or active.',
+        '  --type keep|spend            Optional. Change how funded money is treated.',
         '  --priority POSITION          Optional. Positive whole-number position; 1 is highest.',
         '  --apply                      Optional. Write the partial update.',
         '  --base-url URL               Optional. Override the API origin.',
@@ -663,9 +681,8 @@ export function goalsUpdateHelpText() {
         '  Moving a goal shifts the intervening goals automatically.',
         '  Forecast assignments and shared progress refresh when the owner next opens',
         '  the Forecast screen.',
-        '  Set and clear options for the same field are mutually exclusive.',
-        '  Marking a goal achieved removes its forecast assignment.',
-        '  Marking it active again does not restore the previous assignment.',
+        '  Set and clear target-month options are mutually exclusive.',
+        '  Restore a spent goal before changing its type.',
         '  Change active shared pot target amounts in the Sloth Budget app, where',
         '  account balances can be reconciled across goals in priority order.',
         '  Sharing remains app-managed. Updates to an already shared goal remain visible',
@@ -676,6 +693,7 @@ export function goalsUpdateHelpText() {
         '  Applying requires a write-enabled token created with Allow changes.',
         '',
         'Example:',
+        '  sloth-agent goals update --goal-id wedding --type spend --apply',
         '  sloth-agent goals update --goal-id goal-3 --priority 2 --apply',
         '',
         'Output:',
@@ -683,6 +701,63 @@ export function goalsUpdateHelpText() {
         '  Apply mode returns the complete persisted goal and currency.',
     ].join('\n');
 }
+export function goalsMarkSpentHelpText() {
+    return [
+        'Sloth Agent CLI — goals mark-spent',
+        '',
+        'Preview or mark a Spend goal spent.',
+        '',
+        'Usage:',
+        '  sloth-agent goals mark-spent --goal-id ID [--apply] [--base-url URL]',
+        '',
+        'Options:',
+        '  --goal-id ID   Required. Spend goal ID from goals list or create output.',
+        '  --apply        Optional. Mark the goal spent in Sloth Money.',
+        '  --base-url URL Optional. Override the API origin.',
+        '  -h, --help     Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Safety and lifecycle:',
+        '  Without --apply, the command previews PATCH {"isSpent":true} and does not write.',
+        '  Keep goals cannot be marked spent. Change an active goal to Spend first.',
+        '  A spent goal is excluded from future goal allocation until restored.',
+        '',
+        'Example:',
+        '  sloth-agent goals mark-spent --goal-id wedding --apply',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, endpoint, and payload.',
+        '  Apply mode returns the complete persisted goal and currency.',
+    ].join('\n');
+}
+export function goalsRestoreHelpText() {
+    return [
+        'Sloth Agent CLI — goals restore',
+        '',
+        'Preview or restore a spent Spend goal.',
+        '',
+        'Usage:',
+        '  sloth-agent goals restore --goal-id ID [--apply] [--base-url URL]',
+        '',
+        'Options:',
+        '  --goal-id ID   Required. Spent goal ID from goals list output.',
+        '  --apply        Optional. Restore the goal in Sloth Money.',
+        '  --base-url URL Optional. Override the API origin.',
+        '  -h, --help     Show this help.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Safety and lifecycle:',
+        '  Without --apply, the command previews PATCH {"isSpent":false} and does not write.',
+        '  Restoring clears spentAt and returns the goal to allocation at its saved priority.',
+        '',
+        'Example:',
+        '  sloth-agent goals restore --goal-id wedding --apply',
+        '',
+        'Output:',
+        '  Preview mode returns dryRun, method, endpoint, and payload.',
+        '  Apply mode returns the complete persisted goal and currency.',
+    ].join('\n');
+}
 export function goalsDeleteHelpText() {
     return [
         'Sloth Agent CLI — goals delete',
@@ -761,6 +836,8 @@ export function commandHelpText(topic) {
         'goals-list': goalsListHelpText,
         'goals-create': goalsCreateHelpText,
         'goals-update': goalsUpdateHelpText,
+        'goals-mark-spent': goalsMarkSpentHelpText,
+        'goals-restore': goalsRestoreHelpText,
         'goals-delete': goalsDeleteHelpText,
         'ask-partner': askPartnerHelpText,
     };
@@ -1143,12 +1220,11 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             const endpoint = `${baseUrl}/api/agent/v1/goals`;
             const payload = {
                 name: parsed.name,
-                ...(parsed.targetAmount === undefined
-                    ? {}
-                    : { targetAmount: parsed.targetAmount }),
+                targetAmount: parsed.targetAmount,
                 ...(parsed.targetMonthKey === undefined
                     ? {}
                     : { targetMonthKey: parsed.targetMonthKey }),
+                goalType: parsed.goalType,
             };
             if (!parsed.apply) {
                 writeJson(writeStdout, {
@@ -1172,23 +1248,27 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
-        if (parsed.command === 'goals-update') {
+        if (parsed.command === 'goals-update'
+            || parsed.command === 'goals-mark-spent'
+            || parsed.command === 'goals-restore') {
             const endpoint = `${baseUrl}/api/agent/v1/goals/${encodeURIComponent(parsed.goalId)}`;
-            const payload = {
-                ...(parsed.name === undefined ? {} : { name: parsed.name }),
-                ...(parsed.targetAmount === undefined
-                    ? {}
-                    : { targetAmount: parsed.targetAmount }),
-                ...(parsed.targetMonthKey === undefined
-                    ? {}
-                    : { targetMonthKey: parsed.targetMonthKey }),
-                ...(parsed.isAchieved === undefined
-                    ? {}
-                    : { isAchieved: parsed.isAchieved }),
-                ...(parsed.priority === undefined
-                    ? {}
-                    : { priority: parsed.priority }),
-            };
+            const payload = parsed.command === 'goals-update'
+                ? {
+                    ...(parsed.name === undefined ? {} : { name: parsed.name }),
+                    ...(parsed.targetAmount === undefined
+                        ? {}
+                        : { targetAmount: parsed.targetAmount }),
+                    ...(parsed.targetMonthKey === undefined
+                        ? {}
+                        : { targetMonthKey: parsed.targetMonthKey }),
+                    ...(parsed.goalType === undefined
+                        ? {}
+                        : { goalType: parsed.goalType }),
+                    ...(parsed.priority === undefined
+                        ? {}
+                        : { priority: parsed.priority }),
+                }
+                : { isSpent: parsed.command === 'goals-mark-spent' };
             if (!parsed.apply) {
                 writeJson(writeStdout, {
                     dryRun: true,
@@ -1207,8 +1287,8 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
                 body: JSON.stringify(payload),
                 signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
             });
-            const data = parseApiResponse('goals-update', await parseHttpResponse(response, token));
-            writeJson(writeStdout, parsed.priority === undefined
+            const data = parseApiResponse(parsed.command, await parseHttpResponse(response, token));
+            writeJson(writeStdout, parsed.command !== 'goals-update' || parsed.priority === undefined
                 ? data
                 : withUpdatedGoalPriority(data, parsed.priority));
             return 0;

package/dist/contracts.js

@@ -1,5 +1,6 @@
 import { ApiError, UsageError, } from './errors.js';
 import { CATEGORY_TYPES, ICON_KEYS } from './category-metadata.js';
+import { isGoalType } from './goal-metadata.js';
 function isObject(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
@@ -297,7 +298,8 @@ function isGoal(value) {
             'name',
             'targetAmount',
             'targetMonthKey',
-            'isAchieved',
+            'goalType',
+            'spentAt',
             'sharedWithPartner',
         ])
         && typeof value.id === 'string'
@@ -309,7 +311,10 @@ function isGoal(value) {
         && (value.targetMonthKey === null
             || (typeof value.targetMonthKey === 'string'
                 && /^\d{4}-(0[1-9]|1[0-2])$/.test(value.targetMonthKey)))
-        && typeof value.isAchieved === 'boolean'
+        && isGoalType(value.goalType)
+        && (value.goalType === 'spend'
+            ? value.spentAt === null || isIsoDateTime(value.spentAt)
+            : value.spentAt === null)
         && typeof value.sharedWithPartner === 'boolean');
 }
 function isCurrency(value) {

package/dist/goal-metadata.js

@@ -0,0 +1,4 @@
+export const GOAL_TYPES = ['keep', 'spend'];
+export function isGoalType(value) {
+    return typeof value === 'string' && GOAL_TYPES.includes(value);
+}

package/package.json

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