wealthbox-cli 1.4.0__tar.gz → 1.5.1__tar.gz

{wealthbox_cli-1.4.0 → wealthbox_cli-1.5.1}/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wealthbox-crm",
   "description": "Wealthbox CRM agent skill — drive contacts, tasks, notes, events, and households via natural language. Bundles SKILL.md, references, and firm-bootstrap workflow. Requires the `wbox` CLI (auto-install instructions in SKILL.md).",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "author": "Kadin Bullock",
   "homepage": "https://github.com/massive-value/wealthbox-cli",
   "repository": "https://github.com/massive-value/wealthbox-cli",

wealthbox_cli-1.5.1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: wealthbox-cli
+Version: 1.5.1
+Summary: CLI and client library for the Wealthbox CRM API
+Project-URL: Homepage, https://github.com/massive-value/wealthbox-cli
+Project-URL: Documentation, https://massive-value.github.io/wealthbox-cli/
+Project-URL: Repository, https://github.com/massive-value/wealthbox-cli
+Project-URL: Issues, https://github.com/massive-value/wealthbox-cli/issues
+Project-URL: Changelog, https://github.com/massive-value/wealthbox-cli/blob/main/CHANGELOG.md
+Author: Kadin Bullock
+License: Apache-2.0
+License-File: LICENSE
+Keywords: api,cli,client-management,command-line,contacts,crm,financial-advisor,fintech,wealth-management,wealthbox
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.0
+Requires-Dist: python-dotenv<2.0,>=1.0
+Requires-Dist: tabulate<1.0,>=0.9
+Requires-Dist: typer<1.0,>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Wealthbox CLI
+
+**Run your Wealthbox CRM through Claude or ChatGPT.** Tell your AI agent *"add a contact for Jane Doe, send her our welcome packet, and put a follow-up on my calendar for next Tuesday"* — and it just happens. No coding, no Python, no terminal commands to memorize.
+
+[![PyPI](https://img.shields.io/pypi/v/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/) [![Downloads](https://img.shields.io/pypi/dm/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/) [![CI](https://img.shields.io/github/actions/workflow/status/massive-value/wealthbox-cli/ci.yml?label=CI)](https://github.com/massive-value/wealthbox-cli/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+> Unofficial, community-built. Not affiliated with or endorsed by Wealthbox.
+
+------------------------------------------------------------------------
+
+## Install (60 seconds, no Python required)
+
+| Platform | Paste this into your terminal |
+|---|---|
+| **Mac / Linux** | `curl -LsSf https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.sh \| bash` |
+| **Windows** (PowerShell) | `irm https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 \| iex` |
+
+The installer:
+1. Sets up the tools it needs (Python, etc. — handled automatically).
+2. Asks for your **Wealthbox API token**. *Where to find it:* in Wealthbox, click your initials in the top right → **Settings** → **API Access** → **Create Access Token**. Paste the token when prompted.
+3. Installs the AI agent skill into [Claude Code](https://claude.ai/download) (and Codex, if you have it).
+
+That's it. Open Claude Code and try one of the prompts below.
+
+------------------------------------------------------------------------
+
+## Try this in Claude Code
+
+```
+"Show me my contacts created this week."
+
+"Add Jane Doe as a new prospect — she came in as a referral from Bob Smith."
+
+"Pull up the Smith household, add a task for me to call them on Monday."
+
+"Find notes from my meeting with the Joneses last month and summarize the action items."
+
+"Schedule an annual review with Mary Chen for the second Tuesday of next month."
+```
+
+The first time you ask the agent to do something, it'll walk you through a short Q&A about your firm's conventions (default contact types, naming patterns, common workflows). After that, it just works.
+
+If you're new to Claude Code itself, [download it here](https://claude.ai/download) — it's free for personal use.
+
+------------------------------------------------------------------------
+
+## What it covers
+
+Full read/write access for **contacts** (people, households, organizations, trusts), **tasks**, **events**, **notes**, **opportunities**, **projects**, and **workflows**. Read access for users, activity, and your firm's category lookups.
+
+Anything you can do in Wealthbox manually, the agent can do for you — usually in one sentence.
+
+------------------------------------------------------------------------
+
+## How it works
+
+Your AI agent uses a small command-line tool called `wbox` to talk to the [Wealthbox CRM API](https://dev.wealthbox.com). The skill that ships with this repo teaches the agent two things:
+
+1. **Your firm's conventions** — the agent walks you through a one-time Q&A on first use ("what's your default contact type for new prospects? what's your household naming convention?"), then remembers your answers. Stored locally on your machine, never sent to a server.
+2. **The right command for each request** — translating "add Jane as a prospect" into the correct API call, handling required fields, validating dropdowns against your firm's actual categories.
+
+You stay in control: the agent shows you what it's about to do before it does it.
+
+------------------------------------------------------------------------
+
+## Already a Claude Code user?
+
+You can install the skill directly from the plugin marketplace inside Claude Code:
+
+```
+/plugin marketplace add massive-value/wealthbox-cli
+/plugin install wealthbox-crm@massive-value
+```
+
+The plugin auto-updates daily. Firm data lives at `~/.config/wbox/firm/` (Mac/Linux) or `%APPDATA%\wbox\firm\` (Windows) and survives plugin updates. Run `wbox doctor` to see your install status anytime.
+
+------------------------------------------------------------------------
+
+## For developers and power users
+
+<details>
+<summary><b>Direct CLI use, scripting, automation</b></summary>
+
+```bash
+pip install wealthbox-cli
+wbox config set-token
+
+# List contacts as a table
+wbox contacts list --format table
+
+# Create a contact
+wbox contacts add person --first-name Jane --last-name Doe --contact-type Client
+
+# Export tasks to CSV
+wbox tasks list --format csv > tasks.csv
+
+# Add a meeting note linked to a contact
+wbox notes add "Discussed retirement plan" --contact 12345
+```
+
+Full command reference: [CLI Reference](https://massive-value.github.io/wealthbox-cli/cli-reference/). Output formats: `json` (default), `table`, `csv`, `tsv`. Date format: ISO 8601 (`2026-05-01T10:00:00-07:00`). See [Getting Started](https://massive-value.github.io/wealthbox-cli/getting-started/) for pipx, env-var auth, and project-scoped installs.
+</details>
+
+<details>
+<summary><b>Manage skill installs (legacy / Codex / project scope)</b></summary>
+
+```bash
+wbox skills install        # interactive picker — Claude Code, Codex, project scope
+wbox skills bootstrap      # populate firm data from your Wealthbox account
+wbox skills refresh        # re-fetch generated firm data (categories, users, custom fields)
+wbox skills upgrade        # update the bundled SKILL.md / references in every install
+wbox skills firm-path      # print the canonical firm data directory
+wbox skills uninstall      # remove the skill template (firm data is preserved)
+wbox doctor                # comprehensive health check
+```
+
+The marketplace plugin path (above) is recommended for Claude Code. The legacy `wbox skills install` path remains for Codex users (until OpenAI's marketplace lands), project-scoped installs, or air-gapped setups without the `claude` CLI.
+</details>
+
+<details>
+<summary><b>Architecture and contributing</b></summary>
+
+```
+src/wealthbox_tools/
+    cli/        # Typer commands
+    client/     # Async HTTP client built from mixins
+    models/     # Pydantic v2 input validation
+```
+
+Built with [Typer](https://typer.tiangolo.com/), [httpx](https://www.python-httpx.org/), and [Pydantic v2](https://docs.pydantic.dev/).
+
+```bash
+git clone https://github.com/massive-value/wealthbox-cli
+cd wealthbox-cli
+python -m venv .venv
+# Activate: source .venv/bin/activate (Mac/Linux) | .venv\Scripts\Activate.ps1 (Windows)
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md) for the architecture guide and conventions.
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+- **401 Unauthorized** — token expired or wrong. Run `wbox config show` to see the masked token, `wbox config set-token` to update.
+- **Windows: "execution policy" error during install** — the installer offers to fix this for you. If you skipped it, run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` and re-run the installer.
+- **Linux: command not found after install** — open a new terminal, or run `source ~/.local/bin/env` in your current shell.
+- **Date format errors** — Wealthbox needs ISO 8601: `"2026-05-01T10:00:00-07:00"` for datetimes, `"YYYY-MM-DD"` for date-only fields.
+- **Writes succeed but nothing changes** — some category-constrained fields silently no-op on bad values. Check valid values with `wbox categories <type>`.
+
+For anything else, open an issue at [github.com/massive-value/wealthbox-cli/issues](https://github.com/massive-value/wealthbox-cli/issues).
+</details>
+
+------------------------------------------------------------------------
+
+## Links
+
+[Documentation](https://massive-value.github.io/wealthbox-cli/) · [Changelog](https://massive-value.github.io/wealthbox-cli/changelog/) · [PyPI](https://pypi.org/project/wealthbox-cli/) · [Wealthbox CRM](https://www.wealthbox.com/) · [Wealthbox API](https://dev.wealthbox.com)
+
+## Disclaimer
+
+This is an **unofficial, community-built** tool. It is not affiliated with, endorsed by, or supported by Wealthbox or its parent company. "Wealthbox" is a trademark of its respective owner. Use of this tool is subject to the [Wealthbox API Terms of Service](https://dev.wealthbox.com).
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

wealthbox_cli-1.5.1/README.md

@@ -0,0 +1,168 @@
+# Wealthbox CLI
+
+**Run your Wealthbox CRM through Claude or ChatGPT.** Tell your AI agent *"add a contact for Jane Doe, send her our welcome packet, and put a follow-up on my calendar for next Tuesday"* — and it just happens. No coding, no Python, no terminal commands to memorize.
+
+[![PyPI](https://img.shields.io/pypi/v/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/) [![Downloads](https://img.shields.io/pypi/dm/wealthbox-cli)](https://pypi.org/project/wealthbox-cli/) [![CI](https://img.shields.io/github/actions/workflow/status/massive-value/wealthbox-cli/ci.yml?label=CI)](https://github.com/massive-value/wealthbox-cli/actions/workflows/ci.yml) [![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+
+> Unofficial, community-built. Not affiliated with or endorsed by Wealthbox.
+
+------------------------------------------------------------------------
+
+## Install (60 seconds, no Python required)
+
+| Platform | Paste this into your terminal |
+|---|---|
+| **Mac / Linux** | `curl -LsSf https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.sh \| bash` |
+| **Windows** (PowerShell) | `irm https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 \| iex` |
+
+The installer:
+1. Sets up the tools it needs (Python, etc. — handled automatically).
+2. Asks for your **Wealthbox API token**. *Where to find it:* in Wealthbox, click your initials in the top right → **Settings** → **API Access** → **Create Access Token**. Paste the token when prompted.
+3. Installs the AI agent skill into [Claude Code](https://claude.ai/download) (and Codex, if you have it).
+
+That's it. Open Claude Code and try one of the prompts below.
+
+------------------------------------------------------------------------
+
+## Try this in Claude Code
+
+```
+"Show me my contacts created this week."
+
+"Add Jane Doe as a new prospect — she came in as a referral from Bob Smith."
+
+"Pull up the Smith household, add a task for me to call them on Monday."
+
+"Find notes from my meeting with the Joneses last month and summarize the action items."
+
+"Schedule an annual review with Mary Chen for the second Tuesday of next month."
+```
+
+The first time you ask the agent to do something, it'll walk you through a short Q&A about your firm's conventions (default contact types, naming patterns, common workflows). After that, it just works.
+
+If you're new to Claude Code itself, [download it here](https://claude.ai/download) — it's free for personal use.
+
+------------------------------------------------------------------------
+
+## What it covers
+
+Full read/write access for **contacts** (people, households, organizations, trusts), **tasks**, **events**, **notes**, **opportunities**, **projects**, and **workflows**. Read access for users, activity, and your firm's category lookups.
+
+Anything you can do in Wealthbox manually, the agent can do for you — usually in one sentence.
+
+------------------------------------------------------------------------
+
+## How it works
+
+Your AI agent uses a small command-line tool called `wbox` to talk to the [Wealthbox CRM API](https://dev.wealthbox.com). The skill that ships with this repo teaches the agent two things:
+
+1. **Your firm's conventions** — the agent walks you through a one-time Q&A on first use ("what's your default contact type for new prospects? what's your household naming convention?"), then remembers your answers. Stored locally on your machine, never sent to a server.
+2. **The right command for each request** — translating "add Jane as a prospect" into the correct API call, handling required fields, validating dropdowns against your firm's actual categories.
+
+You stay in control: the agent shows you what it's about to do before it does it.
+
+------------------------------------------------------------------------
+
+## Already a Claude Code user?
+
+You can install the skill directly from the plugin marketplace inside Claude Code:
+
+```
+/plugin marketplace add massive-value/wealthbox-cli
+/plugin install wealthbox-crm@massive-value
+```
+
+The plugin auto-updates daily. Firm data lives at `~/.config/wbox/firm/` (Mac/Linux) or `%APPDATA%\wbox\firm\` (Windows) and survives plugin updates. Run `wbox doctor` to see your install status anytime.
+
+------------------------------------------------------------------------
+
+## For developers and power users
+
+<details>
+<summary><b>Direct CLI use, scripting, automation</b></summary>
+
+```bash
+pip install wealthbox-cli
+wbox config set-token
+
+# List contacts as a table
+wbox contacts list --format table
+
+# Create a contact
+wbox contacts add person --first-name Jane --last-name Doe --contact-type Client
+
+# Export tasks to CSV
+wbox tasks list --format csv > tasks.csv
+
+# Add a meeting note linked to a contact
+wbox notes add "Discussed retirement plan" --contact 12345
+```
+
+Full command reference: [CLI Reference](https://massive-value.github.io/wealthbox-cli/cli-reference/). Output formats: `json` (default), `table`, `csv`, `tsv`. Date format: ISO 8601 (`2026-05-01T10:00:00-07:00`). See [Getting Started](https://massive-value.github.io/wealthbox-cli/getting-started/) for pipx, env-var auth, and project-scoped installs.
+</details>
+
+<details>
+<summary><b>Manage skill installs (legacy / Codex / project scope)</b></summary>
+
+```bash
+wbox skills install        # interactive picker — Claude Code, Codex, project scope
+wbox skills bootstrap      # populate firm data from your Wealthbox account
+wbox skills refresh        # re-fetch generated firm data (categories, users, custom fields)
+wbox skills upgrade        # update the bundled SKILL.md / references in every install
+wbox skills firm-path      # print the canonical firm data directory
+wbox skills uninstall      # remove the skill template (firm data is preserved)
+wbox doctor                # comprehensive health check
+```
+
+The marketplace plugin path (above) is recommended for Claude Code. The legacy `wbox skills install` path remains for Codex users (until OpenAI's marketplace lands), project-scoped installs, or air-gapped setups without the `claude` CLI.
+</details>
+
+<details>
+<summary><b>Architecture and contributing</b></summary>
+
+```
+src/wealthbox_tools/
+    cli/        # Typer commands
+    client/     # Async HTTP client built from mixins
+    models/     # Pydantic v2 input validation
+```
+
+Built with [Typer](https://typer.tiangolo.com/), [httpx](https://www.python-httpx.org/), and [Pydantic v2](https://docs.pydantic.dev/).
+
+```bash
+git clone https://github.com/massive-value/wealthbox-cli
+cd wealthbox-cli
+python -m venv .venv
+# Activate: source .venv/bin/activate (Mac/Linux) | .venv\Scripts\Activate.ps1 (Windows)
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md) for the architecture guide and conventions.
+</details>
+
+<details>
+<summary><b>Troubleshooting</b></summary>
+
+- **401 Unauthorized** — token expired or wrong. Run `wbox config show` to see the masked token, `wbox config set-token` to update.
+- **Windows: "execution policy" error during install** — the installer offers to fix this for you. If you skipped it, run `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` and re-run the installer.
+- **Linux: command not found after install** — open a new terminal, or run `source ~/.local/bin/env` in your current shell.
+- **Date format errors** — Wealthbox needs ISO 8601: `"2026-05-01T10:00:00-07:00"` for datetimes, `"YYYY-MM-DD"` for date-only fields.
+- **Writes succeed but nothing changes** — some category-constrained fields silently no-op on bad values. Check valid values with `wbox categories <type>`.
+
+For anything else, open an issue at [github.com/massive-value/wealthbox-cli/issues](https://github.com/massive-value/wealthbox-cli/issues).
+</details>
+
+------------------------------------------------------------------------
+
+## Links
+
+[Documentation](https://massive-value.github.io/wealthbox-cli/) · [Changelog](https://massive-value.github.io/wealthbox-cli/changelog/) · [PyPI](https://pypi.org/project/wealthbox-cli/) · [Wealthbox CRM](https://www.wealthbox.com/) · [Wealthbox API](https://dev.wealthbox.com)
+
+## Disclaimer
+
+This is an **unofficial, community-built** tool. It is not affiliated with, endorsed by, or supported by Wealthbox or its parent company. "Wealthbox" is a trademark of its respective owner. Use of this tool is subject to the [Wealthbox API Terms of Service](https://dev.wealthbox.com).
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

{wealthbox_cli-1.4.0/src/wealthbox_tools/skills → wealthbox_cli-1.5.1/codex-skill}/wealthbox-crm/SKILL.md

@@ -82,7 +82,7 @@ Verify with: `wbox me`
 | List/get/add/update events | events | `wbox events {list\|get\|add\|update\|delete} ...` |
 | Opportunities | opportunities | `wbox opportunities {list\|get\|add\|update\|delete} ...` |
 | Projects | projects | `wbox projects {list\|get\|add\|update} ...` |
-| Workflows | workflows | `wbox workflows {list\|get\|add\|complete-step\|revert-step} ...` |
+| Workflows | workflows | `wbox workflows {list\|get\|next\|add\|complete-step\|revert-step} ...` |
 | Household members | households | `wbox households {add-member\|remove-member} ...` |
 | Categories/tags | lookups | `wbox categories ...` or `wbox <resource> categories` |
 | Users | lookups | `wbox users list` |
@@ -111,6 +111,10 @@ When `<firm>/workflows.md` defines named workflows (e.g., "onboarding", "meeting
 - Default to `--format json` for single records, `--format table` for lists
 - If the user asks to "show" or "display", use `--format table`
 - If the user is piping or scripting, use `--format json`
+- **Token efficiency:** for any read where the html duplicates aren't needed
+  (almost always), pass `--brief` (or set `WBOX_BRIEF=1`). It strips every
+  `*_html` field recursively from the JSON output. Wealthbox returns html
+  3-5x larger than the plain text counterpart.
 
 ## Common Recipes
 

{wealthbox_cli-1.4.0/plugins/wealthbox-crm/skills → wealthbox_cli-1.5.1/codex-skill}/wealthbox-crm/references/contacts.md

@@ -36,7 +36,7 @@ wbox contacts <ID>
 wbox contacts get <ID>
 ```
 
-Returns full contact record including comments (use `--no-comments` to omit).
+Returns the full contact record. Contacts do not carry comments in Wealthbox — to read comments, fetch the related task, note, event, opportunity, project, or workflow with its `get` command (those default to including comments and accept `--no-comments` to suppress).
 
 ## Create Contact
 
@@ -69,6 +69,7 @@ wbox contacts add person [OPTIONS]
 | `--email-type` | STR | Work, Personal, etc. |
 | `--phone` | STR | Phone number |
 | `--phone-type` | STR | Work, Mobile, etc. |
+| `--tags` | STR | Comma-separated tag names (e.g. "VIP,Q1-Outreach"). New tags are auto-created. |
 | `--more-fields` | JSON | Additional fields as JSON object |
 | `--format` | json\|table\|csv\|tsv | Output format |
 
@@ -76,7 +77,7 @@ wbox contacts add person [OPTIONS]
 ```bash
 wbox contacts add household --name <NAME> [OPTIONS]
 ```
-`--name` is required. Supports: `--contact-type`, `--contact-source`, `--active/--inactive`, `--assigned-to`, `--email`, `--email-type`, `--more-fields`, `--format`.
+`--name` is required. Supports: `--contact-type`, `--contact-source`, `--active/--inactive`, `--assigned-to`, `--email`, `--email-type`, `--tags`, `--more-fields`, `--format`.
 
 ### Organization
 ```bash
@@ -110,6 +111,7 @@ Only pass the fields you want to change:
 | `--contact-source` | STR | Source |
 | `--active` / `--inactive` | flag | Active status |
 | `--assigned-to` | INT | Reassign to user ID |
+| `--tags` | STR | Comma-separated tag names. Replaces all tags — include existing ones to keep. |
 | `--json` | STR | Full JSON for nested/complex fields |
 | `--format` | json\|table\|csv\|tsv | Output format |
 

{wealthbox_cli-1.4.0/src/wealthbox_tools/skills → wealthbox_cli-1.5.1/codex-skill}/wealthbox-crm/references/tasks.md

@@ -44,7 +44,7 @@ wbox tasks add <NAME> [OPTIONS]
 |------|------|-------------|
 | `<NAME>` | positional | Task name (required) |
 | `--due-date` | STR | Due date (XOR with --frame) |
-| `--frame` | today\|tomorrow\|this-week\|next-week\|this-month\|next-month\|... | Relative due date (XOR with --due-date) |
+| `--frame` | today\|tomorrow\|this-week\|next-week\|future\|specific | Relative due date (XOR with --due-date). Both kebab-case (`next-week`) and snake_case (`next_week`) are accepted. |
 | `--priority` | Low\|Medium\|High | Priority level |
 | `--category` | STR | Task category by name or ID (e.g. "Follow-up"). See `wbox categories task-categories`. |
 | `--description` | STR | Task description |
@@ -57,6 +57,8 @@ wbox tasks add <NAME> [OPTIONS]
 
 **Note:** `--due-date` and `--frame` are mutually exclusive. Use `--frame` for relative dates.
 
+**Note (Wealthbox quirk):** `--frame next_week` resolves on the API side to the Monday of the calendar week *after* today. **If today is Sunday, `next_week` is tomorrow** (Monday) — only one day away, not seven. Wealthbox treats Sunday as the last day of the current week. If precise control matters (e.g. an advisor said "next week" expecting 7+ days out), use `--due-date YYYY-MM-DDTHH:MM:SS-07:00` with an explicit date instead of `--frame`.
+
 ## Update Task
 
 ```bash
@@ -67,7 +69,7 @@ wbox tasks update <ID> [OPTIONS]
 |------|------|-------------|
 | `--name` | STR | Rename |
 | `--due-date` | STR | Change due date |
-| `--frame` | STR | Change relative due date |
+| `--frame` | STR | Change relative due date. Accepts kebab-case (`next-week`) or snake_case (`next_week`); see Note above re: Sunday boundary. |
 | `--priority` | Low\|Medium\|High | Change priority |
 | `--category` | STR | Task category by name or ID. See `wbox categories task-categories`. |
 | `--assigned-to` | INT | Reassign |

wealthbox_cli-1.5.1/codex-skill/wealthbox-crm/references/workflows.md

@@ -0,0 +1,145 @@
+# Workflows
+
+Template-based process tracking. Created from templates, progressed by completing/reverting steps.
+
+## List Workflows
+
+```bash
+wbox workflows list [OPTIONS]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--resource-id` | INT | Filter by linked resource ID |
+| `--resource-type` | Contact\|Project | Type of linked resource |
+| `--status` | active\|completed\|scheduled | Filter by status |
+| `--updated-since` | ISO datetime | Modified after |
+| `--updated-before` | ISO datetime | Modified before |
+| `--page` | INT | Page number |
+| `--per-page` | INT | Results per page |
+| `--verbose`, `-v` | flag | Show all fields |
+| `--format` | json\|table\|csv\|tsv | Output format |
+
+## Get Workflow
+
+```bash
+wbox workflows <ID>
+wbox workflows get <ID>
+```
+
+Supports `--no-comments`, `--verbose`, `--format`. Default output omits the
+redundant `workflow_template` block (fetch separately via `templates list`);
+pass `--verbose` to include it.
+
+## Next Step
+
+```bash
+wbox workflows next <ID>
+```
+
+Returns the active step (or `{"completed": true, "completed_at": ...}` if the
+workflow is done). Cheaper than parsing the full `get` response when you only
+need to know "what's next."
+
+## Create Workflow
+
+```bash
+wbox workflows add [OPTIONS]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--template` | INT | Workflow template ID (required) |
+| `--label` | STR | Label/name for this instance |
+| `--contact` | INT | Link to contact |
+| `--project` | INT | Link to project |
+| `--opportunity` | INT | Link to opportunity |
+| `--visible-to` | STR | Visibility |
+| `--starts-at` | STR | Start date |
+| `--more-fields` | JSON | Additional fields |
+| `--format` | json\|table\|csv\|tsv | Output format |
+
+**Note:** Use `wbox workflows templates list` to find available template IDs.
+
+## Complete Step
+
+```bash
+wbox workflows complete-step <WORKFLOW_ID> <STEP_ID> [OPTIONS]
+```
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--outcome-id` | INT | Outcome selection |
+| `--due-date` | STR | For restarting a step |
+| `--due-date-set` | flag | Whether restarted step has due date |
+| `--no-advance-hint` | flag | Skip the post-complete workflow fetch + stderr summary |
+| `--format` | json\|table\|csv\|tsv | Output format |
+
+After a successful complete-step, the CLI fetches the workflow and prints a
+one-line summary to **stderr** describing the new active step (or that the
+workflow completed). Stdout stays the raw API response. Wealthbox's complete-step
+response itself does not say which outcome was selected, so this hint is the
+fastest way to confirm branching took effect.
+
+## Revert Step
+
+```bash
+wbox workflows revert-step <WORKFLOW_ID> <STEP_ID> [OPTIONS]
+```
+
+## List Templates
+
+```bash
+wbox workflows templates list [OPTIONS]
+```
+
+Same filter flags as workflow list.
+
+## Examples
+
+```bash
+# List available templates
+wbox workflows templates list --format table
+
+# Start onboarding workflow for a contact
+wbox workflows add --template 123 --contact 67890 --label "Smith Onboarding"
+
+# Complete a workflow step
+wbox workflows complete-step 111 222
+
+# Just tell me what's next
+wbox workflows next 111
+```
+
+## Quirks (verified against the live API)
+
+- **`completed_at` — not `active_step` — is the truth signal.** When a workflow
+  completes, Wealthbox does not clear the `active_step` field — it keeps
+  pointing at the final completed step. To detect completion, check that
+  `completed_at` is non-empty. `wbox workflows next` already handles this.
+- **`due_date` is materialized at step *activation*, not workflow creation.**
+  Steps further down the chain return `due_date: ""` until they become the
+  active step. Empty string ≠ "no due date scheduled" — it just means "not yet
+  reached."
+- **Empty strings, not nulls, for unset datetimes.** `completed_at: ""`,
+  `due_date: ""`. If you ever add a Pydantic output model with
+  `datetime | None`, you must coerce empty strings to None.
+- **`complete-step` response doesn't surface the selected outcome.** It returns
+  the step with *all* of its possible outcomes attached, identical shape to the
+  pre-completion read. To verify branching worked, re-fetch the workflow and
+  inspect the new `active_step` (or just rely on the CLI's stderr advance hint).
+- **Skipped steps stay `pending`.** When an outcome jumps over intermediate
+  steps, those steps are NOT marked skipped or completed — they have empty
+  `completed_at` and `due_date`, indistinguishable from steps that simply
+  haven't been reached. Outcome-driven workflows can revisit earlier steps, so
+  "later step is completed" doesn't reliably imply "earlier step was skipped."
+- **`revert-step` preserves `due_date`.** Reverting only clears `completed_at`
+  and `completer_id`; the previously materialized `due_date` is kept.
+- **Workflows attach to either the household or any member.** When looking up a
+  client's workflows, check both the household contact and each member contact —
+  Wealthbox does not roll member workflows up to the household.
+- **Instance `name` is lower-cased relative to template `name`.** Template
+  "Auto Trade Enrollment" becomes instance "Auto trade enrollment". Cosmetic.
+- **`workflow_template` is included on every workflow list/get response.** It's
+  the full template (every step + html descriptions). The CLI strips it from
+  default output to save tokens; pass `--verbose` to include it.

{wealthbox_cli-1.4.0 → wealthbox_cli-1.5.1}/plugins/wealthbox-crm/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "wealthbox-crm",
   "description": "Wealthbox CRM agent skill — drive contacts, tasks, notes, events, and households via natural language. Bundles SKILL.md, references, and firm-bootstrap workflow. Requires the `wbox` CLI (auto-install instructions in SKILL.md).",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "author": {
     "name": "Kadin Bullock"
   },

{wealthbox_cli-1.4.0 → wealthbox_cli-1.5.1}/plugins/wealthbox-crm/skills/wealthbox-crm/SKILL.md

@@ -82,7 +82,7 @@ Verify with: `wbox me`
 | List/get/add/update events | events | `wbox events {list\|get\|add\|update\|delete} ...` |
 | Opportunities | opportunities | `wbox opportunities {list\|get\|add\|update\|delete} ...` |
 | Projects | projects | `wbox projects {list\|get\|add\|update} ...` |
-| Workflows | workflows | `wbox workflows {list\|get\|add\|complete-step\|revert-step} ...` |
+| Workflows | workflows | `wbox workflows {list\|get\|next\|add\|complete-step\|revert-step} ...` |
 | Household members | households | `wbox households {add-member\|remove-member} ...` |
 | Categories/tags | lookups | `wbox categories ...` or `wbox <resource> categories` |
 | Users | lookups | `wbox users list` |
@@ -111,6 +111,10 @@ When `<firm>/workflows.md` defines named workflows (e.g., "onboarding", "meeting
 - Default to `--format json` for single records, `--format table` for lists
 - If the user asks to "show" or "display", use `--format table`
 - If the user is piping or scripting, use `--format json`
+- **Token efficiency:** for any read where the html duplicates aren't needed
+  (almost always), pass `--brief` (or set `WBOX_BRIEF=1`). It strips every
+  `*_html` field recursively from the JSON output. Wealthbox returns html
+  3-5x larger than the plain text counterpart.
 
 ## Common Recipes