wealthbox-cli 2.2.0__tar.gz → 2.3.0__tar.gz

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `wealthbox-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.1] - 2026-05-13
+
+Bug-fix release. `wbox self upgrade` was silently no-op'ing for users who
+installed `wbox` via `uv tool install` or `pipx`: it computed the install root
+from `sys.executable` (the venv's `python.exe`) and tried to swap the
+console-script shim there, but `~/.local/bin/wbox.exe` (or pipx's equivalent)
+is a separate copy uv/pipx made — replacing the venv-side shim never changed
+what `PATH` resolved.
+
+### Fixed
+- `wbox self upgrade` now detects the install kind (`bundle` / `uv-tool` /
+  `pipx` / `pip`) up front. Non-bundle installs exit `1` with the correct
+  follow-up command (`uv tool upgrade wealthbox-cli`, `pipx upgrade
+  wealthbox-cli`, or `pip install --upgrade wealthbox-cli`) instead of
+  scheduling a swap that would never take effect on `PATH`.
+
 ## [2.2.0] - 2026-05-13
 
 Small feature + correctness release. Disambiguates the two IDs returned by

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wealthbox-cli
-Version: 2.2.0
+Version: 2.3.0
 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/
@@ -60,6 +60,13 @@ The installer:
 2. Installs the AI agent skill into [Claude Code](https://claude.ai/download) (and Codex, if you have it).
 3. 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.
 
+Re-running is idempotent: it keeps your stored token, refreshes the skill template, and leaves PATH alone if already correct. To install just the binary without the AI agent skill, on Windows download install.ps1 and run with `-SkipSkills`:
+
+```powershell
+iwr https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 -OutFile install.ps1
+.\install.ps1 -SkipSkills
+```
+
 That's it. Open Claude Code and try one of the prompts below.
 
 ------------------------------------------------------------------------
@@ -107,6 +114,19 @@ You stay in control: the agent shows you what it's about to do before it does it
 
 The installer drops a single prebuilt `wbox` binary onto your PATH (`~/.local/bin/wbox` on Mac/Linux, `%LOCALAPPDATA%\Programs\wbox\wbox.exe` on Windows), then registers the AI agent skill with Claude Code (and Codex, if it's installed). Firm data lives at `~/.config/wbox/firm/` (Mac/Linux) or `%APPDATA%\wbox\firm\` (Windows) and survives reinstalls and upgrades. Run `wbox doctor` to see your install status anytime, and `wbox skills upgrade` to pull the latest skill template.
 
+### Upgrading
+
+The upgrade command depends on how you installed:
+
+| If you installed via... | Upgrade with |
+|---|---|
+| `install.sh` / `install.ps1` (the one-line installer above) | `wbox self upgrade` |
+| `pip install wealthbox-cli` | `pip install --upgrade wealthbox-cli` |
+| `pipx install wealthbox-cli` | `pipx upgrade wealthbox-cli` |
+| `uv tool install wealthbox-cli` | `uv tool upgrade wealthbox-cli` |
+
+`wbox self upgrade` only swaps the standalone bundle the one-line installer puts in place; on pip/pipx/uv installs it refuses with the correct follow-up command rather than half-replacing a venv-managed shim.
+
 ------------------------------------------------------------------------
 
 ## For developers and power users
@@ -178,6 +198,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md) for the archit
 <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.
+- **`wbox self upgrade` says "run `uv tool upgrade …`" (or pipx / pip)** — expected. `wbox self upgrade` only swaps the standalone bundle the one-line installer drops in place. If you installed via pip / pipx / uv, follow the command the gate prints. See [Upgrading](#upgrading).
 - **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.

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/README.md

@@ -20,6 +20,13 @@ The installer:
 2. Installs the AI agent skill into [Claude Code](https://claude.ai/download) (and Codex, if you have it).
 3. 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.
 
+Re-running is idempotent: it keeps your stored token, refreshes the skill template, and leaves PATH alone if already correct. To install just the binary without the AI agent skill, on Windows download install.ps1 and run with `-SkipSkills`:
+
+```powershell
+iwr https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 -OutFile install.ps1
+.\install.ps1 -SkipSkills
+```
+
 That's it. Open Claude Code and try one of the prompts below.
 
 ------------------------------------------------------------------------
@@ -67,6 +74,19 @@ You stay in control: the agent shows you what it's about to do before it does it
 
 The installer drops a single prebuilt `wbox` binary onto your PATH (`~/.local/bin/wbox` on Mac/Linux, `%LOCALAPPDATA%\Programs\wbox\wbox.exe` on Windows), then registers the AI agent skill with Claude Code (and Codex, if it's installed). Firm data lives at `~/.config/wbox/firm/` (Mac/Linux) or `%APPDATA%\wbox\firm\` (Windows) and survives reinstalls and upgrades. Run `wbox doctor` to see your install status anytime, and `wbox skills upgrade` to pull the latest skill template.
 
+### Upgrading
+
+The upgrade command depends on how you installed:
+
+| If you installed via... | Upgrade with |
+|---|---|
+| `install.sh` / `install.ps1` (the one-line installer above) | `wbox self upgrade` |
+| `pip install wealthbox-cli` | `pip install --upgrade wealthbox-cli` |
+| `pipx install wealthbox-cli` | `pipx upgrade wealthbox-cli` |
+| `uv tool install wealthbox-cli` | `uv tool upgrade wealthbox-cli` |
+
+`wbox self upgrade` only swaps the standalone bundle the one-line installer puts in place; on pip/pipx/uv installs it refuses with the correct follow-up command rather than half-replacing a venv-managed shim.
+
 ------------------------------------------------------------------------
 
 ## For developers and power users
@@ -138,6 +158,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) and [CLAUDE.md](CLAUDE.md) for the archit
 <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.
+- **`wbox self upgrade` says "run `uv tool upgrade …`" (or pipx / pip)** — expected. `wbox self upgrade` only swaps the standalone bundle the one-line installer drops in place. If you installed via pip / pipx / uv, follow the command the gate prints. See [Upgrading](#upgrading).
 - **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.

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/docs/getting-started.md

@@ -8,20 +8,26 @@ This guide walks you through installing **wealthbox-cli** and configuring it to
 
 ### One-line installer (no Python required)
 
-If you don't have Python installed, the bootstrap script handles everything: it installs [uv](https://github.com/astral-sh/uv) (which provisions Python automatically), installs `wbox`, prompts for your API token, and offers to install the AI agent skill.
+If you don't have Python installed, the bootstrap script handles everything: it downloads a prebuilt `wbox`, places it on your PATH, prompts for your API token, and offers to install the AI agent skill.
 
 === "macOS / Linux"
 
+    Installs [uv](https://github.com/astral-sh/uv) (which provisions Python automatically) and uses it to put `wbox` on your PATH.
+
     ```bash
     curl -LsSf https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.sh | bash
     ```
 
 === "Windows (PowerShell)"
 
+    Downloads a standalone PyInstaller-bundled `wbox.exe` (no Python, no uv) to `%LOCALAPPDATA%\Programs\wbox\`. Pass `-SkipSkills` (via `iwr -OutFile install.ps1; .\install.ps1 -SkipSkills`) to skip the AI agent skill.
+
     ```powershell
     irm https://raw.githubusercontent.com/massive-value/wealthbox-cli/main/scripts/install.ps1 | iex
     ```
 
+Either install supports `wbox self upgrade` for future updates. If you instead install via pip / pipx / uv tool (below), use the corresponding package-manager upgrade command — `wbox self upgrade` will refuse with the right pointer.
+
 ### From PyPI (recommended for Python users)
 
 ```bash

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wealthbox-cli"
-version = "2.2.0"
+version = "2.3.0"
 description = "CLI and client library for the Wealthbox CRM API"
 readme = "README.md"
 requires-python = ">=3.11"

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/cli/_util.py

@@ -451,6 +451,80 @@ async def resolve_category_id(
     raise typer.BadParameter(f"No {label} configured in this workspace.")
 
 
+def _match_contact_role(roles: list[dict[str, Any]], token: str) -> dict[str, Any]:
+    """Find a contact role by numeric id or case-insensitive name."""
+    if token.isdigit():
+        rid = int(token)
+        for r in roles:
+            if int(r.get("id", 0)) == rid:
+                return r
+        raise typer.BadParameter(f"No contact role with id {rid} in this workspace.")
+    target = token.casefold()
+    for r in roles:
+        if str(r.get("name", "")).casefold() == target:
+            return r
+    available = sorted(str(r["name"]) for r in roles if r.get("name"))
+    raise typer.BadParameter(
+        f"Unknown contact role '{token}'. Available: {', '.join(available) or '(none configured)'}"
+    )
+
+
+def _role_option_user(option: dict[str, Any]) -> dict[str, Any]:
+    return option.get("assigned_to") or {}
+
+
+def _match_role_option(role: dict[str, Any], token: str) -> int:
+    """Resolve a user (numeric id, exact name, or unique substring) to a role-option id."""
+    options = role.get("available_options", []) or []
+    role_name = role.get("name", "role")
+    if token.isdigit():
+        uid = int(token)
+        for opt in options:
+            if int(_role_option_user(opt).get("id", 0)) == uid:
+                return int(opt["id"])
+        raise typer.BadParameter(f"No user with id {uid} is available for role '{role_name}'.")
+    target = token.casefold()
+    exact = [o for o in options if str(_role_option_user(o).get("name", "")).casefold() == target]
+    matches = exact or [
+        o for o in options if target in str(_role_option_user(o).get("name", "")).casefold()
+    ]
+    if len(matches) == 1:
+        return int(matches[0]["id"])
+    if not matches:
+        names = sorted(str(_role_option_user(o).get("name", "")) for o in options)
+        raise typer.BadParameter(
+            f"No user matching '{token}' for role '{role_name}'. Available: {', '.join(names)}"
+        )
+    cand = sorted(str(_role_option_user(o).get("name", "")) for o in matches)
+    raise typer.BadParameter(
+        f"'{token}' is ambiguous for role '{role_name}': matches {', '.join(cand)}. Be more specific."
+    )
+
+
+async def resolve_contact_roles(client: WealthboxClient, specs: list[str]) -> list[dict[str, int]]:
+    """Resolve ``Role:User`` specs to ``[{"id": role_id, "value": option_id}]`` entries.
+
+    Role may be a contact-role name (case-insensitive) or numeric id. User may be a
+    user name (case-insensitive; exact preferred, else unique substring) or numeric
+    user id. Both are resolved against ``wbox contacts categories contact-roles`` —
+    the option id (``available_options[].id``), not the user id, is the value the
+    Wealthbox API stores.
+    """
+    data = await client.list_all_categories(CategoryType.CONTACT_ROLES)
+    roles = data.get("contact_roles", []) or []
+    resolved: list[dict[str, int]] = []
+    for spec in specs:
+        role_token, sep, user_token = spec.partition(":")
+        role_token, user_token = role_token.strip(), user_token.strip()
+        if not sep or not role_token or not user_token:
+            raise typer.BadParameter(
+                f"--advisor-role expects 'Role:User' (e.g. 'Associate Advisor:Greg Hyde'); got '{spec}'."
+            )
+        role = _match_contact_role(roles, role_token)
+        resolved.append({"id": int(role["id"]), "value": _match_role_option(role, user_token)})
+    return resolved
+
+
 def parse_more_fields(more_fields: str, reserved: set[str]) -> dict[str, Any]:
     """Parse --more-fields JSON and validate against reserved keys.
 

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/cli/contacts.py

@@ -25,9 +25,16 @@ from ._util import (
     make_resource_app,
     output_result,
     parse_more_fields,
+    resolve_contact_roles,
     run_client,
 )
 
+_ADVISOR_ROLE_HELP = (
+    "Assign a contact role as 'Role:User' (repeatable), e.g. "
+    "'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. "
+    "Resolved via: wbox contacts categories contact-roles"
+)
+
 app = make_resource_app(help="Manage Wealthbox contacts.")
 
 _DEFAULT_FIELDS = ["id", "name", "type", "contact_type", "assigned_to", "status"]
@@ -180,6 +187,23 @@ def _build_contact_entry(value: str | None, kind: str | None) -> list[dict[str,
     return [entry]
 
 
+def _finish_create(
+    payload: dict[str, Any], advisor_role: list[str] | None, token: str | None, fmt: OutputFormat
+) -> None:
+    """Resolve any --advisor-role specs in-session, build the model, create, and print."""
+    if advisor_role and "contact_roles" in payload:
+        raise typer.BadParameter(
+            "Set contact roles via --advisor-role OR contact_roles in --more-fields, not both."
+        )
+
+    async def _do(client: Any) -> Any:
+        if advisor_role:
+            payload["contact_roles"] = await resolve_contact_roles(client, advisor_role)
+        return await client.create_contact(ContactCreateInput(**payload))
+
+    output_result(run_client(token, _do), fmt)
+
+
 def _create_named_contact(
     record_type: RecordType,
     reserved: set[str],
@@ -194,6 +218,7 @@ def _create_named_contact(
     phone_type: str | None,
     tags: str | None,
     more_fields: str | None,
+    advisor_role: list[str] | None,
     token: str | None,
     fmt: OutputFormat,
 ) -> None:
@@ -216,8 +241,7 @@ def _create_named_contact(
         payload["tags"] = tag_list
     if more_fields:
         payload.update(parse_more_fields(more_fields, reserved))
-    input_model = ContactCreateInput(**payload)
-    output_result(run_client(token, lambda c: c.create_contact(input_model)), fmt)
+    _finish_create(payload, advisor_role, token, fmt)
 
 
 @add_app.command("person", help="Create a Person contact.")
@@ -253,6 +277,7 @@ def add_person(
     more_fields: str | None = typer.Option(
         None, "--more-fields", help="Extra fields as JSON object (merged with flags; cannot override explicit flags)"
     ),
+    advisor_role: list[str] | None = typer.Option(None, "--advisor-role", help=_ADVISOR_ROLE_HELP),
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
     fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
 ) -> None:
@@ -286,8 +311,7 @@ def add_person(
         payload["tags"] = tag_list
     if more_fields:
         payload.update(parse_more_fields(more_fields, _PERSON_RESERVED))
-    input_model = ContactCreateInput(**payload)
-    output_result(run_client(token, lambda c: c.create_contact(input_model)), fmt)
+    _finish_create(payload, advisor_role, token, fmt)
 
 
 @add_app.command("household", help="Create a Household contact.")
@@ -308,6 +332,7 @@ def add_household(
     more_fields: str | None = typer.Option(
         None, "--more-fields", help="Extra fields as JSON object (merged with flags; cannot override explicit flags)"
     ),
+    advisor_role: list[str] | None = typer.Option(None, "--advisor-role", help=_ADVISOR_ROLE_HELP),
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
     fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
 ) -> None:
@@ -327,8 +352,7 @@ def add_household(
         payload["tags"] = tag_list
     if more_fields:
         payload.update(parse_more_fields(more_fields, _HOUSEHOLD_RESERVED))
-    input_model = ContactCreateInput(**payload)
-    output_result(run_client(token, lambda c: c.create_contact(input_model)), fmt)
+    _finish_create(payload, advisor_role, token, fmt)
 
 
 @add_app.command("org", help="Create an Organization contact.")
@@ -353,12 +377,13 @@ def add_org(
     more_fields: str | None = typer.Option(
         None, "--more-fields", help="Extra fields as JSON object (merged with flags; cannot override explicit flags)"
     ),
+    advisor_role: list[str] | None = typer.Option(None, "--advisor-role", help=_ADVISOR_ROLE_HELP),
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
     fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
 ) -> None:
     _create_named_contact(
         RecordType.ORGANIZATION, _ORG_TRUST_RESERVED, name, contact_type, contact_source,
-        active, assigned_to, email, email_type, phone, phone_type, tags, more_fields, token, fmt,
+        active, assigned_to, email, email_type, phone, phone_type, tags, more_fields, advisor_role, token, fmt,
     )
 
 
@@ -384,12 +409,13 @@ def add_trust(
     more_fields: str | None = typer.Option(
         None, "--more-fields", help="Extra fields as JSON object (merged with flags; cannot override explicit flags)"
     ),
+    advisor_role: list[str] | None = typer.Option(None, "--advisor-role", help=_ADVISOR_ROLE_HELP),
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
     fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
 ) -> None:
     _create_named_contact(
         RecordType.TRUST, _ORG_TRUST_RESERVED, name, contact_type, contact_source,
-        active, assigned_to, email, email_type, phone, phone_type, tags, more_fields, token, fmt,
+        active, assigned_to, email, email_type, phone, phone_type, tags, more_fields, advisor_role, token, fmt,
     )
 
 
@@ -420,13 +446,19 @@ def update_contact(
             "include existing tags you wish to keep. New tags are auto-created."
         ),
     ),
+    advisor_role: list[str] | None = typer.Option(None, "--advisor-role", help=_ADVISOR_ROLE_HELP),
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
     fmt: OutputFormat = typer.Option(OutputFormat.JSON, "--format"),
 ) -> None:
+    if advisor_role and json_data is not None:
+        raise typer.BadParameter(
+            "Set contact roles via --advisor-role OR contact_roles in --json, not both."
+        )
+
     if json_data is not None:
-        input_model = ContactUpdateInput(**json.loads(json_data))
+        payload: dict[str, Any] = json.loads(json_data)
     else:
-        payload: dict[str, Any] = {k: v for k, v in {
+        payload = {k: v for k, v in {
             "first_name": first_name,
             "middle_name": middle_name,
             "last_name": last_name,
@@ -441,9 +473,13 @@ def update_contact(
         tag_list = _parse_tags(tags)
         if tag_list is not None:
             payload["tags"] = tag_list
-        input_model = ContactUpdateInput(**payload)
 
-    output_result(run_client(token, lambda c: c.update_contact(contact_id, input_model)), fmt)
+    async def _do(client: Any) -> Any:
+        if advisor_role:
+            payload["contact_roles"] = await resolve_contact_roles(client, advisor_role)
+        return await client.update_contact(contact_id, ContactUpdateInput(**payload))
+
+    output_result(run_client(token, _do), fmt)
 
 
 @app.command("delete", help="Delete an existing contact.")

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/cli/self_cmd.py

@@ -37,8 +37,29 @@ def _default_install_root() -> Path:
     return Path(sys.executable).resolve().parent
 
 
+_NON_BUNDLE_UPGRADE_HINTS = {
+    "uv-tool": "uv tool upgrade wealthbox-cli",
+    "pipx": "pipx upgrade wealthbox-cli",
+    "pip": "pip install --upgrade wealthbox-cli",
+}
+
+
 @app.command("upgrade", help="Upgrade the `wbox` CLI to the latest GitHub release.")
 def upgrade_cmd() -> None:
+    kind = self_upgrade._install_kind()
+    if kind != "bundle":
+        # The frozen-bundle swap would either silently no-op (uv copies the
+        # shim to ~/.local/bin so replacing the venv-side shim doesn't change
+        # what PATH resolves) or wedge the venv. Refuse before downloading.
+        hint = _NON_BUNDLE_UPGRADE_HINTS.get(kind, _NON_BUNDLE_UPGRADE_HINTS["pip"])
+        typer.echo(
+            "wbox self upgrade only swaps the standalone binary from "
+            "install.ps1.",
+            err=True,
+        )
+        typer.echo(f"This wbox was installed via {kind} — run: {hint}", err=True)
+        raise typer.Exit(code=1)
+
     candidate = self_upgrade.check()
     if candidate is None:
         typer.echo("Already on the latest version.")

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/models/common.py

@@ -105,8 +105,16 @@ class StreetAddress(WealthboxModel):
 
 
 class ContactRoleAssignment(WealthboxModel):
-    id: int | None = Field(default=None, ge=1)
-    type: str | None = None
+    """A contact-role assignment on a contact's write payload.
+
+    ``id`` is the contact-role id (e.g. "Associate Advisor") and ``value`` is
+    the *role-option* id that maps to a specific user — NOT the user's id.
+    Resolve both from ``wbox contacts categories contact-roles``, whose
+    ``available_options[].id`` is the value to use here.
+    """
+
+    id: int = Field(ge=1, description="Contact-role id (from contacts categories contact-roles)")
+    value: int = Field(ge=1, description="Role-option id mapping to a user (available_options[].id)")
 
 
 class LinkedToRef(WealthboxModel):

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/self_upgrade.py

@@ -51,6 +51,7 @@ __all__ = [
     "check_release_staleness",
     "apply",
     "_cleanup_stale_backups",
+    "_install_kind",
 ]
 
 _RELEASES_LATEST_URL = (
@@ -139,6 +140,35 @@ def _running_version() -> str:
     return __version__
 
 
+def _install_kind() -> str:
+    """Classify how the running ``wbox`` was installed.
+
+    The :func:`apply` swap is only correct for the standalone PyInstaller
+    bundle that ``install.ps1`` ships. Under uv / pipx / pip the install is
+    a tiny console-script shim around a venv; replacing it with a frozen
+    binary would either silently no-op (PATH points at a copy uv made
+    elsewhere, e.g. ``~/.local/bin/wbox.exe``) or wedge the venv on the
+    next ``uv tool sync``. The gate in :mod:`cli.self_cmd` consults this
+    classifier to refuse with a clear "use <installer> instead" message.
+
+    Returns one of:
+
+    - ``"bundle"`` — frozen PyInstaller EXE (``sys.frozen`` is set).
+    - ``"uv-tool"`` — ``sys.executable`` lives under a ``uv/tools/`` venv.
+    - ``"pipx"`` — ``sys.executable`` lives under a ``pipx/`` venv.
+    - ``"pip"`` — anything else (ordinary pip/venv install).
+    """
+    if getattr(sys, "frozen", False):
+        return "bundle"
+    parts = [p.lower() for p in Path(sys.executable).resolve().parts]
+    for i in range(len(parts) - 1):
+        if parts[i] == "uv" and parts[i + 1] == "tools":
+            return "uv-tool"
+    if "pipx" in parts:
+        return "pipx"
+    return "pip"
+
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/skills/wealthbox-crm/SKILL.md

@@ -195,3 +195,5 @@ The single-quoted heredoc (`<<'EOF'`) is the recommended default — it disables
 - **Relative due dates:** tasks accept `--frame today|tomorrow|this-week|next-week|this-month|next-month` instead of `--due-date` (mutually exclusive)
 - **Activity pagination:** uses `--cursor`, not `--page`
 - **Don't infer flag names:** read `references/<resource>.md` before invoking — flags like `--name` (not `--search`), `--frame` (not `--due-in`) are easy to guess wrong
+- **Advisor / contact roles:** assign them with `wbox contacts add|update ... --advisor-role "Role:User"` (e.g. `"Associate Advisor:Greg Hyde"`). This covers a firm's "Second Advisor" / Partner assignments. See `references/contacts.md` → "Contact Roles".
+- **Before falling back to raw API, exhaust the CLI:** if a firm-required field has no obvious flag, check `references/<resource>.md`, run `wbox <resource> --help` / `wbox <resource> <sub> --help`, and look for a `wbox <resource> categories <type>` lookup that supplies the needed ids. Reach for raw `curl`/API only after these come up empty — and if they do, that's a CLI gap worth filing as an issue.

wealthbox_cli-2.3.0/src/wealthbox_tools/skills/wealthbox-crm/firm-examples/contacts.md

@@ -0,0 +1,34 @@
+# firm/contacts.md — Example
+
+This is an illustrative template. Replace every value below with your firm's
+real conventions. Valid category values (contact types, sources, roles, etc.)
+come from your workspace — list them with `wbox contacts categories <type>`.
+
+## Required Fields
+- contact-type: one of your workspace's contact types (`wbox contacts categories contact-types`)
+- contact-source: one of your workspace's sources (`wbox contacts categories contact-sources`)
+
+## Defaults
+- assigned-to: <your default user id> (`wbox me user-id`)
+- active: true
+
+## Advisor / Contact Roles
+- If your firm assigns advisors via contact roles (e.g. "Associate Advisor",
+  "Partner"), set them with `--advisor-role "Role:User"` on add/update.
+- List the configured roles and their assignable users with
+  `wbox contacts categories contact-roles`.
+- Example: a prospect's primary advisor is `--assigned-to`, and the second
+  advisor is `--advisor-role "Associate Advisor:<user>"`.
+
+## Person Contacts
+- Always collect: email, phone, birth-date
+- Preferred email-type: Personal
+- Preferred phone-type: Mobile
+
+## Household Contacts
+- Always create a household when onboarding a married couple
+- Naming convention: e.g. "{Last}, {Head First} & {Spouse First}"
+- Add members one at a time (sequential) — see references/households.md
+
+## Organization / Trust Contacts
+- Require EIN in --more-fields for Trusts

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/skills/wealthbox-crm/references/contacts.md

@@ -70,6 +70,7 @@ wbox contacts add person [OPTIONS]
 | `--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. |
+| `--advisor-role` | STR | Assign a contact role (repeatable): `"Role:User"`, e.g. `"Associate Advisor:Greg Hyde"`. See "Contact Roles" below. |
 | `--more-fields` | JSON | Additional fields as JSON object |
 | `--format` | json\|table\|csv\|tsv | Output format |
 
@@ -77,7 +78,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`, `--tags`, `--more-fields`, `--format`.
+`--name` is required. Supports: `--contact-type`, `--contact-source`, `--active/--inactive`, `--assigned-to`, `--email`, `--email-type`, `--tags`, `--advisor-role`, `--more-fields`, `--format`.
 
 ### Organization
 ```bash
@@ -112,6 +113,7 @@ Only pass the fields you want to change:
 | `--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. |
+| `--advisor-role` | STR | Assign a contact role (repeatable): `"Role:User"`. See "Contact Roles" below. Mutually exclusive with a `contact_roles` block in `--json`. |
 | `--json` | STR | Full JSON for nested/complex fields |
 | `--format` | json\|table\|csv\|tsv | Output format |
 
@@ -136,6 +138,51 @@ wbox contacts categories website-types
 wbox contacts categories contact-roles
 ```
 
+## Contact Roles (advisor assignments)
+
+Contact roles attach a user to a contact in a named role — e.g. **Associate
+Advisor** ("Second Advisor") or **Partner**. This is how firm advisor
+assignments are stored; they are *separate* from `--assigned-to` (the primary
+owner).
+
+**Use the `--advisor-role` flag** (repeatable) on `add person|household|org|trust`
+and on `update`:
+
+```bash
+wbox contacts add person --first-name Mark --last-name Leone \
+  --advisor-role "Associate Advisor:Greg Hyde" \
+  --advisor-role "Partner:Jane Smith"
+
+wbox contacts update 12345 --advisor-role "Associate Advisor:Greg Hyde"
+```
+
+The spec is `Role:User`. The role is matched by name (case-insensitive) or
+numeric id; the user by name (exact, else unique substring) or numeric user id.
+The flag resolves both against `wbox contacts categories contact-roles` for you.
+
+**The underlying write shape** (if you ever build it by hand via `--more-fields`
+or `--json`) is `{"id": <role_id>, "value": <option_id>}`:
+
+```bash
+wbox contacts update 12345 --json '{"contact_roles": [{"id": 1338, "value": 4226}]}'
+```
+
+⚠️ `value` is the **role-option id**, NOT the user id. Each role exposes
+`available_options[].id`, one per assignable user — that option id is the value.
+Look it up with `wbox contacts categories contact-roles`:
+
+```jsonc
+{ "id": 1338, "name": "Associate Advisor",
+  "available_options": [
+    { "id": 4226, "assigned_to": { "id": 154372, "name": "Greg Hyde" } }
+  ] }
+// → to set Greg as Associate Advisor: {"id": 1338, "value": 4226}
+```
+
+Notes: roles can only be added/updated, not removed, via the API. You only need
+to include the roles you're changing. `--advisor-role` and a `contact_roles`
+block in `--more-fields`/`--json` are mutually exclusive.
+
 ## Generated Flag Reference
 
 The following section is auto-generated from the Typer command tree by
@@ -150,6 +197,7 @@ Create a Household contact.
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--active` / `--inactive` | `BOOLEAN` | `-` | Set contact status to Active or Inactive |
+| `--advisor-role` | `TEXT` | `-` | Assign a contact role as 'Role:User' (repeatable), e.g. 'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. Resolved via: wbox contacts categories contact-roles |
 | `--assigned-to` | `INTEGER` | `-` | Assign to a user by ID |
 | `--contact-source` | `TEXT` | `-` |  |
 | `--contact-type` | `TEXT` | `-` | e.g. Client, Prospect |
@@ -174,6 +222,7 @@ Create an Organization contact.
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--active` / `--inactive` | `BOOLEAN` | `-` | Set contact status to Active or Inactive |
+| `--advisor-role` | `TEXT` | `-` | Assign a contact role as 'Role:User' (repeatable), e.g. 'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. Resolved via: wbox contacts categories contact-roles |
 | `--assigned-to` | `INTEGER` | `-` | Assign to a user by ID |
 | `--contact-source` | `TEXT` | `-` |  |
 | `--contact-type` | `TEXT` | `-` | e.g. Client, Prospect |
@@ -200,6 +249,7 @@ Create a Person contact.
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--active` / `--inactive` | `BOOLEAN` | `-` | Set contact status to Active or Inactive |
+| `--advisor-role` | `TEXT` | `-` | Assign a contact role as 'Role:User' (repeatable), e.g. 'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. Resolved via: wbox contacts categories contact-roles |
 | `--anniversary` | `TEXT` | `-` | Format: YYYY-MM-DD |
 | `--assigned-to` | `INTEGER` | `-` | Assign to a user by ID |
 | `--birth-date` | `TEXT` | `-` | Format: YYYY-MM-DD |
@@ -254,6 +304,7 @@ Create a Trust contact.
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--active` / `--inactive` | `BOOLEAN` | `-` | Set contact status to Active or Inactive |
+| `--advisor-role` | `TEXT` | `-` | Assign a contact role as 'Role:User' (repeatable), e.g. 'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. Resolved via: wbox contacts categories contact-roles |
 | `--assigned-to` | `INTEGER` | `-` | Assign to a user by ID |
 | `--contact-source` | `TEXT` | `-` |  |
 | `--contact-type` | `TEXT` | `-` | e.g. Client, Prospect |
@@ -479,6 +530,7 @@ Update an existing contact. Pass only the fields you want to change.
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
 | `--active` / `--inactive` | `BOOLEAN` | `-` | Set contact status to Active or Inactive |
+| `--advisor-role` | `TEXT` | `-` | Assign a contact role as 'Role:User' (repeatable), e.g. 'Associate Advisor:Greg Hyde'. User may be a name or numeric user id. Resolved via: wbox contacts categories contact-roles |
 | `--assigned-to` | `INTEGER` | `-` | Reassign to a user by ID |
 | `--company-name` | `TEXT` | `-` |  |
 | `--contact-source` | `TEXT` | `-` |  |
@@ -512,7 +564,12 @@ wbox contacts add person --first-name Jane --last-name Doe --contact-type Client
 # Update job title
 wbox contacts update 12345 --job-title "CFO"
 
-# Create a household and add members (two-step)
+# Create a prospect with primary owner + advisor role in one call
+wbox contacts add person --first-name Jane --last-name Doe \
+  --contact-type Prospect --assigned-to 154372 \
+  --advisor-role "Associate Advisor:Greg Hyde"
+
+# Create a household and add members (two-step — add members SEQUENTIALLY)
 wbox contacts add household --name "The Smith Family"
 # note the returned ID, then:
 wbox households add-member <HOUSEHOLD_ID> <MEMBER_ID> --title Head

{wealthbox_cli-2.2.0 → wealthbox_cli-2.3.0}/src/wealthbox_tools/skills/wealthbox-crm/references/households.md

@@ -2,6 +2,11 @@
 
 Manage membership of household contacts. Household contacts are created via `wbox contacts add household`.
 
+> ⚠️ **Add members one at a time, sequentially.** Each `add-member` call
+> rewrites the household's member list, so concurrent/parallel calls race and
+> the last write clobbers the earlier ones. Run them in series and wait for
+> each to return before issuing the next.
+
 ## Add Member
 
 ```bash

wealthbox_cli-2.2.0/src/wealthbox_tools/skills/wealthbox-crm/firm-examples/contacts.md

@@ -1,21 +0,0 @@
-# firm/contacts.md — Example
-
-## Required Fields
-- contact-type: always one of: Client, Prospect, Center of Influence, Vendor
-- contact-source: always one of: Referral, Website, Event, Cold Call
-
-## Defaults
-- assigned-to: 12345
-- active: true
-
-## Person Contacts
-- Always collect: email, phone, birth-date
-- Preferred email-type: Personal
-- Preferred phone-type: Mobile
-
-## Household Contacts
-- Always create a household when onboarding a married couple
-- Naming convention: "The {LastName} Family"
-
-## Organization / Trust Contacts
-- Require EIN in more-fields for Trusts