@slothmoney/agent-cli 0.20.0 → 0.21.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.21.1 - 2026-08-29
+
+- Clarify in portfolio, current budget status, and transaction help that a
+  completed eligible refresh updates the configured Budget balance audit.
+- Explain that a same-day cached read reuses fresh bank data without adding
+  another audit checkpoint.
+
+## 0.21.0 - 2026-08-28
+
+- Add `scenarios` commands to list, create, update, activate, and delete the
+  month-anchored choices used by Goal forecasts.
+- Preview every scenario change against Sloth's canonical planner with zero
+  writes; `--apply` remains the explicit write boundary.
+- Create the common No/Yes choice directly, support recurring and one-off
+  account contributions, and return the recalculated Goal roadmap.
+
 ## 0.20.0 - 2026-08-27
 
 - Add `portfolio` views for personal, partner-shared, and combined household

package/README.md

@@ -1,6 +1,6 @@
 # Sloth Agent CLI
 
-Use your own agent to inspect personal and household accounts, investments, and budgets, manage goals, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
+Use your own agent to inspect personal and household accounts, investments, and budgets, manage goals and forecast scenarios, move assigned budget money, update planned amounts, categorise transactions, and configure payment notifications through the
 [Sloth Money Agent API](https://slothmoney.app/developers/).
 
 ## Install
@@ -15,7 +15,7 @@ sloth-agent --version
 For a one-off pinned run:
 
 ```bash
-npm exec --yes --package=@slothmoney/agent-cli@0.17.0 -- sloth-agent --help
+npm exec --yes --package=@slothmoney/agent-cli@0.21.1 -- sloth-agent --help
 ```
 
 ## Authenticate
@@ -25,9 +25,9 @@ Create a personal access token in Sloth Money under
 where the CLI runs.
 
 New tokens are view-only. That is enough for `auth status`, `accounts`, `investments`, `portfolio`,
-`budget`, `categories`, `transactions`, and `goals` list. Enable **Allow changes** when
+`budget`, `categories`, `transactions`, `goals`, and `scenarios` list. Enable **Allow changes** when
 creating the token only if the CLI must apply assignments, manage categories
-or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals. Token
+or line items, move assigned budget money, update planned budgets, manage accounts, ask a partner for an explanation, or manage goals and scenarios. Token
 permissions cannot be changed later - revoke and reissue the token instead.
 
 ### Local computer
@@ -122,6 +122,9 @@ sloth-agent goals create --help
 sloth-agent goals update --help
 sloth-agent goals mark-spent --help
 sloth-agent goals restore --help
+sloth-agent scenarios create --help
+sloth-agent scenarios update --help
+sloth-agent scenarios activate --help
 sloth-agent ask-partner --help
 ```
 
@@ -446,6 +449,10 @@ nonnegative `moneyInPence` and `moneyOutPence` plus their difference as
 custom categories are normal rows. A transaction with no category at all is
 reported separately under `activity.uncategorized`.
 
+A completed current-period refresh updates the Budget balance audit for any
+configured backing accounts. A same-day cached read does not add another audit
+checkpoint.
+
 `budget` contains assigned, spent, and available category amounts when a
 trustworthy period plan exists. It is `null` when it does not; activity still
 returns. The response includes only the period budget currency and silently
@@ -645,6 +652,9 @@ planning only. It does not change account ownership, transaction access, Goal
 funding, or who can move money. Totals use the viewer's budget currency and
 exclude other native currencies without converting them.
 
+A completed balance refresh updates the Budget balance audit for any configured
+backing accounts. A same-day cached read does not add another audit checkpoint.
+
 Archive an owned manual account. The account disappears from active Sloth
 surfaces, but its underlying records are retained. Repeating an applied removal
 is safe and returns `changed: false`.
@@ -748,6 +758,52 @@ one-based `priority`; `1` is highest. Moving one goal automatically shifts the
 goals between its old and new positions. Sloth recalculates the active-scenario
 roadmap before every applied Goal mutation and returns the updated forecast.
 
+List the scenarios that supply assumptions to that roadmap:
+
+```bash
+sloth-agent scenarios
+```
+
+Create a monthly contribution choice. Preview is the default and performs zero
+writes; add `--apply` after reviewing the returned scenario and recalculated
+Goals:
+
+```bash
+sloth-agent scenarios create \
+  --month 2026-09 \
+  --name "Deposit £100 into the shopping pot each month?" \
+  --account-ref sloth_account_v1_... \
+  --recurring-amount 100
+```
+
+Creation adds No and Yes options and activates Yes. The recurring contribution
+continues until a later active scenario changes it. A one-off amount applies
+only in the scenario month. Scenarios alter the forecast; they do not move
+money.
+
+Use stable IDs from `scenarios` output to edit or select an option:
+
+```bash
+sloth-agent scenarios update \
+  --month 2026-09 \
+  --option-id yes \
+  --account-ref sloth_account_v1_... \
+  --recurring-amount 125 \
+  --apply
+
+sloth-agent scenarios activate \
+  --month 2026-09 \
+  --option-id no \
+  --apply
+
+sloth-agent scenarios delete --month 2026-09 --apply
+```
+
+For recurring contributions, `--recurring-amount 0` explicitly stops the
+earlier amount. `--clear-recurring` removes this month's override, so the
+earlier recurring amount continues. Contribution updates use the active option
+when `--option-id` is omitted.
+
 Read uncategorised contributions to the joint budget:
 
 ```bash
@@ -770,6 +826,10 @@ a structured `refresh` object:
 }
 ```
 
+A completed refresh also updates the Budget balance audit for any configured
+backing accounts. A same-day cached read reuses the existing data and does not
+add another audit checkpoint.
+
 Re-run the transaction query later to observe the completed refresh. A partial
 account failure remains eligible for an automatic retry.
 

package/dist/args.js

@@ -67,6 +67,16 @@ function parsePositiveDecimalAmount(value, name) {
     }
     return amount;
 }
+function parseNonNegativeDecimalAmount(value, name) {
+    if (!/^\d+(?:\.\d{1,2})?$/.test(value)) {
+        throw new UsageError(`${name} must be zero or a positive amount with at most two decimal places`);
+    }
+    const amount = Number(value);
+    if (!Number.isFinite(amount) || amount < 0) {
+        throw new UsageError(`${name} must be zero or a positive amount with at most two decimal places`);
+    }
+    return amount;
+}
 function parsePositiveAmountPence(value, name) {
     validatePositiveDecimalAmount(value, name);
     const [wholePounds, fractionalPounds = ''] = value.split('.');
@@ -864,6 +874,226 @@ function parseGoals(args, baseUrl) {
     }
     throw new UsageError(`Unknown goals command: ${subcommand}`);
 }
+function parseScenarioText(value, option, maxLength = 60) {
+    const text = value.trim();
+    if (text.length > maxLength) {
+        throw new UsageError(`${option} must be at most ${maxLength} characters`);
+    }
+    return text;
+}
+function parseScenarios(args, baseUrl) {
+    const subcommand = args.shift();
+    if (subcommand === undefined || subcommand === 'list') {
+        if (args.length > 0) {
+            throw new UsageError(`Unknown scenarios list option: ${args[0]}`);
+        }
+        return withBaseUrl({ command: 'scenarios-list' }, baseUrl);
+    }
+    if (subcommand === 'create') {
+        let monthKey;
+        let name;
+        let accountRef;
+        let recurringAmount;
+        let oneOffAmount;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month'
+                && option !== '--name'
+                && option !== '--account-ref'
+                && option !== '--recurring-amount'
+                && option !== '--one-off-amount') {
+                throw new UsageError(`Unknown scenarios create option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else if (option === '--name') {
+                name = setOnce(name, parseScenarioText(value, option), option);
+            }
+            else if (option === '--account-ref') {
+                accountRef = setOnce(accountRef, parseAccountRef(value), option);
+            }
+            else if (option === '--recurring-amount') {
+                recurringAmount = setOnce(recurringAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+            else {
+                oneOffAmount = setOnce(oneOffAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError('scenarios create requires --month <YYYY-MM>');
+        if (!name)
+            throw new UsageError('scenarios create requires --name <name>');
+        if (!accountRef)
+            throw new UsageError('scenarios create requires --account-ref <accountRef>');
+        if (recurringAmount === undefined && oneOffAmount === undefined) {
+            throw new UsageError('scenarios create requires --recurring-amount or --one-off-amount');
+        }
+        if ((recurringAmount ?? 0) === 0 && (oneOffAmount ?? 0) === 0) {
+            throw new UsageError('scenarios create requires at least one positive contribution');
+        }
+        return withBaseUrl({
+            command: 'scenarios-create',
+            monthKey,
+            name,
+            accountRef,
+            ...(recurringAmount === undefined ? {} : { recurringAmount }),
+            ...(oneOffAmount === undefined
+                ? recurringAmount === undefined ? {} : { oneOffAmount: 0 }
+                : { oneOffAmount }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'update') {
+        let monthKey;
+        let name;
+        let optionId;
+        let optionLabel;
+        let accountRef;
+        let recurringAmount;
+        let oneOffAmount;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            if (argument === '--clear-recurring') {
+                if (recurringAmount !== undefined) {
+                    throw new UsageError('--recurring-amount and --clear-recurring are mutually exclusive');
+                }
+                recurringAmount = null;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month'
+                && option !== '--name'
+                && option !== '--option-id'
+                && option !== '--option-label'
+                && option !== '--account-ref'
+                && option !== '--recurring-amount'
+                && option !== '--one-off-amount') {
+                throw new UsageError(`Unknown scenarios update option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else if (option === '--name') {
+                name = setOnce(name, parseScenarioText(value, option), option);
+            }
+            else if (option === '--option-id') {
+                optionId = setOnce(optionId, parseScenarioText(value, option, 200), option);
+            }
+            else if (option === '--option-label') {
+                optionLabel = setOnce(optionLabel, parseScenarioText(value, option), option);
+            }
+            else if (option === '--account-ref') {
+                accountRef = setOnce(accountRef, parseAccountRef(value), option);
+            }
+            else if (option === '--recurring-amount') {
+                if (recurringAmount !== undefined) {
+                    throw new UsageError('--recurring-amount and --clear-recurring are mutually exclusive');
+                }
+                recurringAmount = parseNonNegativeDecimalAmount(value, option);
+            }
+            else {
+                oneOffAmount = setOnce(oneOffAmount, parseNonNegativeDecimalAmount(value, option), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError('scenarios update requires --month <YYYY-MM>');
+        if (optionLabel !== undefined && optionId === undefined) {
+            throw new UsageError('--option-label requires --option-id');
+        }
+        if ((recurringAmount !== undefined || oneOffAmount !== undefined) && !accountRef) {
+            throw new UsageError('scenario contribution changes require --account-ref');
+        }
+        if (accountRef !== undefined
+            && recurringAmount === undefined
+            && oneOffAmount === undefined) {
+            throw new UsageError('--account-ref requires a contribution change');
+        }
+        if (name === undefined
+            && optionLabel === undefined
+            && accountRef === undefined
+            && recurringAmount === undefined
+            && oneOffAmount === undefined) {
+            throw new UsageError('scenarios update requires at least one field to update');
+        }
+        return withBaseUrl({
+            command: 'scenarios-update',
+            monthKey,
+            ...(name === undefined ? {} : { name }),
+            ...(optionId === undefined ? {} : { optionId }),
+            ...(optionLabel === undefined ? {} : { optionLabel }),
+            ...(accountRef === undefined ? {} : { accountRef }),
+            ...(recurringAmount === undefined ? {} : { recurringAmount }),
+            ...(oneOffAmount === undefined ? {} : { oneOffAmount }),
+            apply,
+        }, baseUrl);
+    }
+    if (subcommand === 'activate' || subcommand === 'delete') {
+        let monthKey;
+        let optionId;
+        let apply = false;
+        for (let index = 0; index < args.length; index += 1) {
+            const argument = args[index];
+            if (argument === '--apply') {
+                if (apply)
+                    throw new UsageError('--apply may only be provided once');
+                apply = true;
+                continue;
+            }
+            const [option, inlineValue] = argument.includes('=')
+                ? argument.split(/=(.*)/s, 2)
+                : [argument, undefined];
+            if (option !== '--month' && !(subcommand === 'activate' && option === '--option-id')) {
+                throw new UsageError(`Unknown scenarios ${subcommand} option: ${argument}`);
+            }
+            const value = requireNonEmpty(inlineValue ?? readOptionValue(args, index, option), option);
+            if (inlineValue === undefined)
+                index += 1;
+            if (option === '--month') {
+                monthKey = setOnce(monthKey, parseGoalMonthKey(value, option), option);
+            }
+            else {
+                optionId = setOnce(optionId, parseScenarioText(value, option, 200), option);
+            }
+        }
+        if (!monthKey)
+            throw new UsageError(`scenarios ${subcommand} requires --month <YYYY-MM>`);
+        if (subcommand === 'activate') {
+            if (!optionId)
+                throw new UsageError('scenarios activate requires --option-id <id>');
+            return withBaseUrl({
+                command: 'scenarios-activate', monthKey, optionId, apply,
+            }, baseUrl);
+        }
+        return withBaseUrl({ command: 'scenarios-delete', monthKey, apply }, baseUrl);
+    }
+    throw new UsageError(`Unknown scenarios command: ${subcommand}`);
+}
 function parseRules(args, baseUrl) {
     const subcommand = args.shift();
     if (subcommand === undefined || subcommand === 'list') {
@@ -945,6 +1175,19 @@ function helpTopic(argv) {
             return 'goals-delete';
         return 'goals';
     }
+    if (command === 'scenarios') {
+        if (subcommand === 'list')
+            return 'scenarios-list';
+        if (subcommand === 'create')
+            return 'scenarios-create';
+        if (subcommand === 'update')
+            return 'scenarios-update';
+        if (subcommand === 'activate')
+            return 'scenarios-activate';
+        if (subcommand === 'delete')
+            return 'scenarios-delete';
+        return 'scenarios';
+    }
     if (command === 'rules') {
         if (subcommand === 'get')
             return 'rules-get';
@@ -1021,6 +1264,9 @@ export function parseArgs(argv) {
     if (command === 'goals') {
         return parseGoals(args, baseUrl);
     }
+    if (command === 'scenarios') {
+        return parseScenarios(args, baseUrl);
+    }
     if (command === 'rules') {
         return parseRules(args, baseUrl);
     }

package/dist/cli.js

@@ -6,7 +6,7 @@ import { ICON_KEYS } from './category-metadata.js';
 import { parseApiResponse, parseAssignmentOperationResponse, toLegacyAssignmentResponse, validateAssignmentPayload, validateBudgetMovementResponse, validateBudgetUpdatePayload, validateNotificationRulePayload, validateReceiptConfirmation, } from './contracts.js';
 import { createSystemCredentialStore, secureStorageUnavailableError, } from './credential-store.js';
 import { ApiError, CliError, ConfigError, UsageError, } from './errors.js';
-export const CLI_VERSION = '0.20.0';
+export const CLI_VERSION = '0.21.1';
 const REQUEST_TIMEOUT_MS = 60_000;
 const MAX_CONTRACT_PDF_BYTES = 6_000_000;
 const API_ORIGIN_HELP_LINES = [
@@ -68,6 +68,12 @@ export function usageText() {
         '  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 scenarios [list] [--base-url URL]',
+        '  sloth-agent scenarios create --month YYYY-MM --name NAME --account-ref REF',
+        '    [--recurring-amount AMOUNT] [--one-off-amount AMOUNT] [--apply]',
+        '  sloth-agent scenarios update --month YYYY-MM [fields] [--apply]',
+        '  sloth-agent scenarios activate --month YYYY-MM --option-id ID [--apply]',
+        '  sloth-agent scenarios delete --month YYYY-MM [--apply]',
         '  sloth-agent ask-partner --transaction-ref REF [--base-url URL]',
         '',
         'Help:',
@@ -463,6 +469,8 @@ export function portfolioHelpText() {
         '',
         'Access:',
         '  This read-only command waits up to 45 seconds for eligible linked balances to refresh.',
+        '  A completed refresh updates the Budget balance audit for configured backing accounts.',
+        '  A same-day cached read does not add another audit checkpoint.',
         '  Partner shows only balances or holdings your partner explicitly shared.',
         '  Household combines your accounts with those shared balances and deduplicates joint accounts.',
         '  Shared data supports planning only. It does not assign partner accounts to Goals or change ownership.',
@@ -527,6 +535,8 @@ export function budgetStatusHelpText() {
         'Access and freshness:',
         '  This command is read-only, requires agent:read, and never changes the budget.',
         '  Current periods use the normal transaction refresh policy; historical periods are cache-only.',
+        '  A completed refresh updates the Budget balance audit for configured backing accounts.',
+        '  A same-day cached read does not add another audit checkpoint.',
         '  A historical response returns refresh as null.',
         '',
         'Output:',
@@ -648,6 +658,8 @@ export function transactionsHelpText() {
         '  --end-date must not be before --start-date.',
         '  The first transaction read each UTC day may refresh linked bank data.',
         '  Refresh remotely persists booked transactions and account balances.',
+        '  A completed refresh updates the Budget balance audit for configured backing accounts.',
+        '  A same-day cached read does not add another audit checkpoint.',
         '  The command waits up to 45 seconds, then returns cached data if refresh continues.',
         '',
         'Output:',
@@ -958,6 +970,192 @@ export function goalsDeleteHelpText() {
         '  Apply mode returns deleted and deletedGoalId.',
     ].join('\n');
 }
+export function scenariosHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios',
+        '',
+        'Manage the month-anchored choices used by the Goal forecast.',
+        'Each scenario contains options. Its active option controls the forecast calculation.',
+        '',
+        'Commands:',
+        '  sloth-agent scenarios list       List scenarios and their options.',
+        '  sloth-agent scenarios create     Create a No/Yes scenario.',
+        '  sloth-agent scenarios update     Change a scenario or option.',
+        '  sloth-agent scenarios activate   Make an option active.',
+        '  sloth-agent scenarios delete     Remove a scenario.',
+        '',
+        'Help:',
+        '  Run sloth-agent scenarios <command> --help for command-specific details.',
+        ...API_ORIGIN_HELP_LINES,
+    ].join('\n');
+}
+export function scenariosListHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios list',
+        '',
+        'List each scenario, its active option, and account contributions.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios [list] [--base-url URL] [-h]',
+        '',
+        'Options:',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Behavior:',
+        'This command is read-only and requires agent:read.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with currency, forecastBasis, and scenarios. Each scenario contains',
+        '  activeOptionId and options with isActive and account contributions.',
+    ].join('\n');
+}
+export function scenariosCreateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios create',
+        '',
+        'Create a month-anchored choice and recalculate the Goal roadmap.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios create --month YYYY-MM --name NAME --account-ref REF',
+        '    [--recurring-amount AMOUNT] [--one-off-amount AMOUNT] [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM              Month when this scenario begins.',
+        '  --name NAME                  Question shown for the scenario, up to 60 characters.',
+        '  --account-ref REF            Exact accountRef from sloth-agent accounts.',
+        '',
+        'Contribution: provide at least one:',
+        '  --recurring-amount AMOUNT    Optional monthly contribution in the budget currency.',
+        '  --one-off-amount AMOUNT      Optional contribution for this month.',
+        '  AMOUNT accepts zero or a positive decimal with at most two decimal places.',
+        '  At least one supplied amount must be positive.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the scenario; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Provide at least one positive contribution. A recurring contribution continues',
+        'until a later active scenario changes it. Creation adds No and Yes options and',
+        'activates Yes. It records a forecast assumption and does not move money.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth authenticates, calculates the result, and performs zero writes.',
+        '  With --apply, Sloth saves the scenario using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the proposed or saved scenario, and',
+        '  recalculated Goals. Preview and apply use the same output contract.',
+        '',
+        'Example:',
+        '  sloth-agent scenarios create --month 2026-09 \\',
+        '    --name "Deposit £100 into the shopping pot each month?" \\',
+        '    --account-ref PASTE_THE_EXACT_ACCOUNT_REF_HERE --recurring-amount 100',
+    ].join('\n');
+}
+export function scenariosUpdateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios update',
+        '',
+        'Change a scenario, one option, or an account contribution.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios update --month YYYY-MM [fields] [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM                 Scenario month.',
+        '',
+        'Fields:',
+        '  --name NAME                     Rename the scenario, up to 60 characters.',
+        '  --option-id ID                  Select an option ID, up to 200 characters.',
+        '  --option-label LABEL            Rename it, up to 60 characters; requires --option-id.',
+        '  --account-ref REF               Account for contribution changes.',
+        '  --recurring-amount AMOUNT       Set a monthly contribution; cannot be used',
+        '                                  with --clear-recurring.',
+        '  --clear-recurring               Inherit the earlier recurring amount.',
+        '  --one-off-amount AMOUNT         Set this month\'s one-off contribution.',
+        '  Amounts accept zero or a positive decimal with at most two decimal places.',
+        '  Contribution fields require --account-ref, and --account-ref requires one',
+        '  of those fields. Provide at least one field that changes the scenario.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the change; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Contribution changes use the active option when --option-id is omitted.',
+        'For recurring contributions, zero explicitly stops the earlier recurring amount.',
+        '--clear-recurring removes this override so the earlier recurring amount continues.',
+        '',
+        'Write behavior:',
+        '  Without --apply, Sloth authenticates, calculates the result, and performs zero writes.',
+        '  With --apply, Sloth saves the change using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the proposed or saved scenario, and',
+        '  recalculated Goals. Preview and apply use the same output contract.',
+    ].join('\n');
+}
+export function scenariosActivateHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios activate',
+        '',
+        'Select the option that controls the forecast and recalculates Goals.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios activate --month YYYY-MM --option-id ID [--apply]',
+        '    [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM   Scenario month.',
+        '  --option-id ID    Exact option ID from scenarios list, up to 200 characters.',
+        '',
+        'Options:',
+        '  --apply          Optional. Save the active option; otherwise preview it.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Write behavior:',
+        'Without --apply, Sloth calculates the result and performs zero writes.',
+        'With --apply, Sloth saves the active option using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, the selected scenario, and recalculated Goals.',
+    ].join('\n');
+}
+export function scenariosDeleteHelpText() {
+    return [
+        'Sloth Agent CLI - scenarios delete',
+        '',
+        'Remove one scenario. Sloth recalculates Goals without it.',
+        '',
+        'Usage:',
+        '  sloth-agent scenarios delete --month YYYY-MM [--apply] [--base-url URL] [-h]',
+        '',
+        'Required:',
+        '  --month YYYY-MM   Scenario month.',
+        '',
+        'Options:',
+        '  --apply          Optional. Remove the scenario; otherwise preview deletion.',
+        '  --base-url URL   Optional. Override the API origin.',
+        '  -h, --help       Show this help.',
+        '',
+        'Write behavior:',
+        'Without --apply, Sloth calculates the result and performs zero writes.',
+        'With --apply, Sloth removes the scenario using a write-enabled token with Allow changes.',
+        ...API_ORIGIN_HELP_LINES,
+        '',
+        'Output:',
+        '  JSON with changed, forecastBasis, deletedMonthKey, and recalculated Goals.',
+    ].join('\n');
+}
 export function askPartnerHelpText() {
     return [
         'Sloth Agent CLI — ask-partner',
@@ -1234,6 +1432,12 @@ export function commandHelpText(topic) {
         'goals-mark-spent': goalsMarkSpentHelpText,
         'goals-restore': goalsRestoreHelpText,
         'goals-delete': goalsDeleteHelpText,
+        scenarios: scenariosHelpText,
+        'scenarios-list': scenariosListHelpText,
+        'scenarios-create': scenariosCreateHelpText,
+        'scenarios-update': scenariosUpdateHelpText,
+        'scenarios-activate': scenariosActivateHelpText,
+        'scenarios-delete': scenariosDeleteHelpText,
         'ask-partner': askPartnerHelpText,
     };
     return helpByTopic[topic]();
@@ -1556,6 +1760,77 @@ function hasFailures(value) {
         return false;
     return Array.isArray(value.failed) && value.failed.length > 0;
 }
+function scenarioRequestDescriptor(parsed, baseUrl) {
+    const previewEndpoint = `${baseUrl}/api/agent/v1/scenarios/preview`;
+    switch (parsed.command) {
+        case 'scenarios-create': {
+            const scenario = {
+                monthKey: parsed.monthKey,
+                name: parsed.name,
+                accountRef: parsed.accountRef,
+                ...(parsed.recurringAmount === undefined
+                    ? {}
+                    : { recurringAmount: parsed.recurringAmount }),
+                ...(parsed.oneOffAmount === undefined
+                    ? {}
+                    : { oneOffAmount: parsed.oneOffAmount }),
+            };
+            return parsed.apply
+                ? { endpoint: `${baseUrl}/api/agent/v1/scenarios`, method: 'POST', body: scenario }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'create', scenario },
+                };
+        }
+        case 'scenarios-update': {
+            const updates = {
+                ...(parsed.name === undefined ? {} : { name: parsed.name }),
+                ...(parsed.optionId === undefined ? {} : { optionId: parsed.optionId }),
+                ...(parsed.optionLabel === undefined ? {} : { optionLabel: parsed.optionLabel }),
+                ...(parsed.accountRef === undefined ? {} : { accountRef: parsed.accountRef }),
+                ...(parsed.recurringAmount === undefined
+                    ? {}
+                    : { recurringAmount: parsed.recurringAmount }),
+                ...(parsed.oneOffAmount === undefined ? {} : { oneOffAmount: parsed.oneOffAmount }),
+            };
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}`,
+                    method: 'PATCH',
+                    body: updates,
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'update', monthKey: parsed.monthKey, updates },
+                };
+        }
+        case 'scenarios-activate':
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}/activate`,
+                    method: 'POST',
+                    body: { optionId: parsed.optionId },
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'activate', monthKey: parsed.monthKey, optionId: parsed.optionId },
+                };
+        case 'scenarios-delete':
+            return parsed.apply
+                ? {
+                    endpoint: `${baseUrl}/api/agent/v1/scenarios/${encodeURIComponent(parsed.monthKey)}`,
+                    method: 'DELETE',
+                }
+                : {
+                    endpoint: previewEndpoint,
+                    method: 'POST',
+                    body: { action: 'delete', monthKey: parsed.monthKey },
+                };
+    }
+}
 export async function runCli(argv = process.argv.slice(2), options = {}) {
     const environment = options.env ?? process.env;
     const fetchImplementation = options.fetch ?? globalThis.fetch;
@@ -2001,6 +2276,31 @@ export async function runCli(argv = process.argv.slice(2), options = {}) {
             writeJson(writeStdout, data);
             return 0;
         }
+        if (parsed.command === 'scenarios-list') {
+            const response = await fetchImplementation(`${baseUrl}/api/agent/v1/scenarios`, {
+                method: 'GET',
+                headers,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('scenarios-list', await parseHttpResponse(response, token)));
+            return 0;
+        }
+        if (parsed.command === 'scenarios-create'
+            || parsed.command === 'scenarios-update'
+            || parsed.command === 'scenarios-activate'
+            || parsed.command === 'scenarios-delete') {
+            const request = scenarioRequestDescriptor(parsed, baseUrl);
+            const response = await fetchImplementation(request.endpoint, {
+                method: request.method,
+                headers: request.body === undefined
+                    ? headers
+                    : { ...headers, 'Content-Type': 'application/json' },
+                ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            writeJson(writeStdout, parseApiResponse('scenarios-mutation', await parseHttpResponse(response, token)));
+            return 0;
+        }
         if (parsed.command === 'assign') {
             const payload = assignmentPayload;
             const data = await applyAssignments(fetchImplementation, sleep, baseUrl, token, payload);

package/dist/contracts.js

@@ -1054,6 +1054,101 @@ function isGoalDeleteResponse(value) {
         && typeof value.deletedGoalId === 'string'
         && value.deletedGoalId.trim().length > 0);
 }
+function isScenarioAmount(value) {
+    return typeof value === 'number'
+        && Number.isFinite(value)
+        && value >= 0
+        && Math.abs(value * 100 - Math.round(value * 100)) < Number.EPSILON * 100;
+}
+function isScenarioContribution(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'accountRef',
+            'accountLabel',
+            'accountType',
+            'recurringAmount',
+            'oneOffAmount',
+        ])
+        && isAccountRef(value.accountRef)
+        && typeof value.accountLabel === 'string'
+        && value.accountLabel.trim().length > 0
+        && (value.accountType === 'current'
+            || value.accountType === 'savings'
+            || value.accountType === 'investments')
+        && (value.recurringAmount === null
+            || isScenarioAmount(value.recurringAmount))
+        && isScenarioAmount(value.oneOffAmount);
+}
+function isScenarioOption(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['id', 'label', 'isActive', 'contributions'])
+        && typeof value.id === 'string'
+        && value.id.trim().length > 0
+        && value.id === value.id.trim()
+        && value.id.length <= 200
+        && typeof value.label === 'string'
+        && value.label.trim().length > 0
+        && value.label === value.label.trim()
+        && value.label.length <= 60
+        && typeof value.isActive === 'boolean'
+        && Array.isArray(value.contributions)
+        && value.contributions.every(isScenarioContribution);
+}
+function hasConsistentScenarioOptions(options, activeOptionId) {
+    const parsedOptions = options.filter(isObject);
+    if (parsedOptions.length !== options.length)
+        return false;
+    const optionIds = parsedOptions.map(option => String(option.id));
+    const activeOptions = parsedOptions.filter(option => option.isActive === true);
+    return new Set(optionIds).size === optionIds.length
+        && activeOptions.length === 1
+        && activeOptions[0]?.id === activeOptionId;
+}
+function isScenario(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['monthKey', 'name', 'activeOptionId', 'options'])
+        && isMonthKeyOrNull(value.monthKey)
+        && value.monthKey !== null
+        && (value.name === null
+            || (typeof value.name === 'string'
+                && value.name.trim().length > 0
+                && value.name === value.name.trim()
+                && value.name.length <= 60))
+        && typeof value.activeOptionId === 'string'
+        && value.activeOptionId.trim().length > 0
+        && value.activeOptionId === value.activeOptionId.trim()
+        && value.activeOptionId.length <= 200
+        && Array.isArray(value.options)
+        && value.options.length > 0
+        && value.options.every(isScenarioOption)
+        && hasConsistentScenarioOptions(value.options, value.activeOptionId);
+}
+function isScenariosResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, ['currency', 'forecastBasis', 'scenarios'])
+        && isCurrency(value.currency)
+        && isForecastBasis(value.forecastBasis)
+        && Array.isArray(value.scenarios)
+        && value.scenarios.every(isScenario);
+}
+function isScenarioMutationResponse(value) {
+    return isObject(value)
+        && hasOnlyFields(value, [
+            'currency',
+            'changed',
+            'forecastBasis',
+            'scenario',
+            'deletedMonthKey',
+            'goals',
+        ])
+        && isCurrency(value.currency)
+        && typeof value.changed === 'boolean'
+        && isForecastBasis(value.forecastBasis)
+        && (value.scenario === null || isScenario(value.scenario))
+        && isMonthKeyOrNull(value.deletedMonthKey)
+        && Array.isArray(value.goals)
+        && value.goals.every(isGoal);
+}
 function isReceiptConfirmation(value) {
     try {
         validateReceiptConfirmation(value);
@@ -1150,11 +1245,15 @@ export function parseApiResponse(command, value) {
                                                                                             ? isPartnerResponse(value)
                                                                                             : command === 'goals-list'
                                                                                                 ? isGoalsResponse(value)
-                                                                                                : command === 'goals-preview'
-                                                                                                    ? isGoalPreviewResponse(value)
-                                                                                                    : command === 'goals-delete'
-                                                                                                        ? isGoalDeleteResponse(value)
-                                                                                                        : isGoalMutationResponse(value);
+                                                                                                : command === 'scenarios-list'
+                                                                                                    ? isScenariosResponse(value)
+                                                                                                    : command === 'scenarios-mutation'
+                                                                                                        ? isScenarioMutationResponse(value)
+                                                                                                        : command === 'goals-preview'
+                                                                                                            ? isGoalPreviewResponse(value)
+                                                                                                            : command === 'goals-delete'
+                                                                                                                ? isGoalDeleteResponse(value)
+                                                                                                                : isGoalMutationResponse(value);
     if (!valid) {
         const label = command === 'assign' ? 'assignment' : command;
         throw new ApiError(`Invalid ${label} response from the Agent API`);

package/package.json

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