wealthbox-cli 1.1.1__tar.gz → 1.1.2__tar.gz

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wealthbox-cli
-Version: 1.1.1
+Version: 1.1.2
 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/
@@ -166,9 +166,12 @@ This updates the generated half of the skill's firm files; hand-edited policy is
 wbox skills list             # show where the skill is installed + last bootstrap time
 wbox skills doctor           # diagnose install state + token
 wbox skills sync             # copy firm/ from one install to others (Claude Code <-> Codex)
+wbox skills upgrade          # refresh template files (SKILL.md, references/, ...) preserving firm/
 wbox skills uninstall        # remove the skill
 ```
 
+When the CLI ships a newer template (improved SKILL.md, new reference docs, etc.), `wbox skills upgrade` re-copies the bundled template into every installed platform without touching your firm-specific data in `firm/`. Each install records the template's CLI version in `_meta.json`, so the agent can detect drift and prompt you to upgrade when needed.
+
 `wbox skills sync` is useful if you maintain firm conventions in one platform's install (e.g., your Claude Code user scope) and want the same `firm/` files mirrored to Codex or to a project-scoped `.claude/skills/` folder. The command runs as a wizard by default; pass `--source`, `--target`, and `--yes` for non-interactive use.
 
 ### Works with other agents too

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/README.md

@@ -125,9 +125,12 @@ This updates the generated half of the skill's firm files; hand-edited policy is
 wbox skills list             # show where the skill is installed + last bootstrap time
 wbox skills doctor           # diagnose install state + token
 wbox skills sync             # copy firm/ from one install to others (Claude Code <-> Codex)
+wbox skills upgrade          # refresh template files (SKILL.md, references/, ...) preserving firm/
 wbox skills uninstall        # remove the skill
 ```
 
+When the CLI ships a newer template (improved SKILL.md, new reference docs, etc.), `wbox skills upgrade` re-copies the bundled template into every installed platform without touching your firm-specific data in `firm/`. Each install records the template's CLI version in `_meta.json`, so the agent can detect drift and prompt you to upgrade when needed.
+
 `wbox skills sync` is useful if you maintain firm conventions in one platform's install (e.g., your Claude Code user scope) and want the same `firm/` files mirrored to Codex or to a project-scoped `.claude/skills/` folder. The command runs as a wizard by default; pass `--source`, `--target`, and `--yes` for non-interactive use.
 
 ### Works with other agents too

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/pyproject.toml

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

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/src/wealthbox_tools/cli/_skill_bootstrap.py

@@ -86,11 +86,11 @@ def render_users_md(users: list[dict[str, Any]]) -> str:
 FIRM_README = """# firm/ — Firm Customizations
 
 This folder holds everything the agent needs to know about your firm's
-Wealthbox conventions.
+Wealthbox conventions. Install metadata lives in `../_meta.json` (skill
+root), not here.
 
 ## Generated files (overwritten by `wbox skills refresh`)
 
-- `_meta.json` — refresh timestamps, firm identity, CLI version
 - `categories.md` — every category type + valid values
 - `custom-fields.md` — custom fields per document type + valid values
 - `users.md` — user id → name → email
@@ -139,22 +139,52 @@ def write_stubs(firm_dir: Path) -> list[str]:
     return written
 
 
-def write_meta_json(
-    firm_dir: Path,
+def meta_path(skill_dir: Path) -> Path:
+    """Location of _meta.json relative to a skill install root."""
+    return skill_dir / "_meta.json"
+
+
+def read_meta(skill_dir: Path) -> dict[str, Any]:
+    """Read _meta.json. Returns {} if missing or unreadable."""
+    p = meta_path(skill_dir)
+    if not p.exists():
+        return {}
+    try:
+        loaded = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+
+
+def write_meta(skill_dir: Path, data: dict[str, Any]) -> None:
+    meta_path(skill_dir).write_text(
+        json.dumps(data, indent=2) + "\n", encoding="utf-8"
+    )
+
+
+def update_template_meta(skill_dir: Path, *, cli_version: str) -> None:
+    """Set the template section of _meta.json. Preserves any existing firm section."""
+    meta = read_meta(skill_dir)
+    meta["template"] = {"cli_version": cli_version}
+    write_meta(skill_dir, meta)
+
+
+def update_firm_meta(
+    skill_dir: Path,
     *,
-    generated_files: list[str],
-    firm_identity: dict[str, Any],
+    identity: dict[str, Any],
     cli_version: str,
+    generated_files: list[str],
 ) -> None:
+    """Set the firm section of _meta.json. Preserves any existing template section."""
     now = datetime.now(timezone.utc).isoformat()
-    meta = {
-        "firm": firm_identity,
+    meta = read_meta(skill_dir)
+    meta["firm"] = {
+        "identity": identity,
         "cli_version": cli_version,
         "files": {name: now for name in generated_files},
     }
-    (firm_dir / "_meta.json").write_text(
-        json.dumps(meta, indent=2) + "\n", encoding="utf-8"
-    )
+    write_meta(skill_dir, meta)
 
 
 # --------------------------------------------------------------------------- #
@@ -230,11 +260,11 @@ def bootstrap_skill_dir(
     (firm_dir / "users.md").write_text(render_users_md(users), encoding="utf-8")
 
     generated = ["categories.md", "custom-fields.md", "users.md"]
-    write_meta_json(
-        firm_dir,
-        generated_files=generated,
-        firm_identity=firm_identity,
+    update_firm_meta(
+        skill_dir,
+        identity=firm_identity,
         cli_version=_pkg_version("wealthbox-cli"),
+        generated_files=generated,
     )
 
     wrote_stubs = 0

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/src/wealthbox_tools/cli/_skill_platforms.py

@@ -69,10 +69,36 @@ def install_skill(platform: Platform, src: Path, *, force: bool) -> None:
         _safe_rmtree(platform, dest)
     dest.parent.mkdir(parents=True, exist_ok=True)
     shutil.copytree(src, dest)
-    if platform.skill_filename != "SKILL.md":
-        skill_md = dest / "SKILL.md"
-        if skill_md.exists():
-            skill_md.rename(dest / platform.skill_filename)
+    _rename_skill_md(platform, dest)
+
+
+def upgrade_skill(platform: Platform, src: Path) -> None:
+    """Re-copy the bundled template over an existing install.
+
+    Preserves the user's `firm/` directory and root `_meta.json` (the
+    bundled template ships neither). Refreshes SKILL.md, references/,
+    firm-examples/, and bootstrap.md.
+    """
+    dest = skill_dir(platform)
+    if not dest.is_dir() or not (dest / platform.skill_filename).is_file():
+        raise SkillInstallError(
+            f"Cannot upgrade: nothing installed at {dest}"
+        )
+    shutil.copytree(src, dest, dirs_exist_ok=True)
+    _rename_skill_md(platform, dest)
+
+
+def _rename_skill_md(platform: Platform, dest: Path) -> None:
+    """Rename SKILL.md → platform.skill_filename if needed (e.g. AGENTS.md for codex)."""
+    if platform.skill_filename == "SKILL.md":
+        return
+    skill_md = dest / "SKILL.md"
+    target = dest / platform.skill_filename
+    if not skill_md.exists():
+        return
+    if target.exists():
+        target.unlink()
+    skill_md.rename(target)
 
 
 def uninstall_skill(platform: Platform) -> None:

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/src/wealthbox_tools/cli/skills.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
-import json
 import shutil
 from datetime import datetime, timezone
+from importlib.metadata import version as _pkg_version
 from importlib.resources import as_file, files
 from pathlib import Path
 
 import typer
 
+from ._skill_bootstrap import read_meta, update_template_meta
 from ._skill_platforms import (
     Platform,
     SkillInstallError,
@@ -16,6 +17,7 @@ from ._skill_platforms import (
     is_installed,
     skill_dir,
     uninstall_skill,
+    upgrade_skill,
 )
 
 app = typer.Typer(
@@ -27,31 +29,31 @@ app = typer.Typer(
 
 @app.command("list", help="Show where the skill is installed per platform.")
 def list_platforms() -> None:
-    header = ("platform", "path", "status", "last-bootstrap")
-    rows: list[tuple[str, str, str, str]] = []
+    header = ("platform", "path", "status", "template-version", "last-bootstrap")
+    rows: list[tuple[str, str, str, str, str]] = []
     for p in detect_platforms():
         dest = skill_dir(p)
         installed = is_installed(p)
-        meta_file = dest / "firm" / "_meta.json"
+        template_version = "-"
         last_bootstrap = "-"
-        if meta_file.exists():
-            try:
-                meta = json.loads(meta_file.read_text())
-                files = meta.get("files", {})
-                if files:
-                    last_bootstrap = max(files.values())
-            except (json.JSONDecodeError, OSError):
-                last_bootstrap = "(unreadable)"
+        if installed:
+            meta = read_meta(dest)
+            template_version = meta.get("template", {}).get("cli_version", "-")
+            firm_section = meta.get("firm") or {}
+            firm_files = firm_section.get("files") or {}
+            if firm_files:
+                last_bootstrap = max(firm_files.values())
         rows.append((
             p.id,
             str(dest),
             "installed" if installed else "not installed",
+            template_version,
             last_bootstrap,
         ))
 
     widths = [
         max(len(r[i]) for r in ([header] + rows))
-        for i in range(4)
+        for i in range(len(header))
     ]
     fmt = "  ".join(f"{{:<{w}}}" for w in widths)
     typer.echo(fmt.format(*header))
@@ -113,6 +115,7 @@ def install_cmd(
             except SkillInstallError as e:
                 typer.echo(f"Error installing to {target.id}: {e}", err=True)
                 raise typer.Exit(code=1) from e
+            update_template_meta(skill_dir(target), cli_version=_pkg_version("wealthbox-cli"))
             typer.echo(f"OK installed to {skill_dir(target)}")
 
     if not no_bootstrap:
@@ -192,26 +195,65 @@ def refresh_cmd(
         raise typer.Exit(code=2)
 
     for t in targets:
-        meta_path = skill_dir(t) / "firm" / "_meta.json"
-        if meta_path.exists():
+        meta = read_meta(skill_dir(t))
+        firm_files = (meta.get("firm") or {}).get("files") or {}
+        if firm_files:
             try:
-                meta = json.loads(meta_path.read_text())
-                ts_values = list(meta.get("files", {}).values())
-                if ts_values:
-                    oldest = min(datetime.fromisoformat(ts) for ts in ts_values)
-                    age_days = (datetime.now(timezone.utc) - oldest).days
-                    if age_days > staleness_days:
-                        typer.echo(
-                            f"! {t.id}: generated files were {age_days} days stale - refreshing now",
-                            err=True,
-                        )
-            except (json.JSONDecodeError, OSError, ValueError):
+                oldest = min(datetime.fromisoformat(ts) for ts in firm_files.values())
+                age_days = (datetime.now(timezone.utc) - oldest).days
+                if age_days > staleness_days:
+                    typer.echo(
+                        f"! {t.id}: generated files were {age_days} days stale - refreshing now",
+                        err=True,
+                    )
+            except ValueError:
                 pass
 
         bootstrap_skill_dir(skill_dir(t), token=token, generated_only=True)
         typer.echo(f"OK refreshed {t.id}")
 
 
+@app.command(
+    "upgrade",
+    help="Refresh template files (SKILL.md, references/, firm-examples/, bootstrap.md) "
+         "in every installed platform. Preserves firm/ and _meta.json firm section.",
+)
+def upgrade_cmd(
+    platforms_flag: list[str] = typer.Option(
+        [], "--platform", "-p",
+        help="Platform id. Default: every installed platform.",
+    ),
+) -> None:
+    if platforms_flag:
+        targets = _resolve_platforms(platforms_flag)
+        for t in targets:
+            if not is_installed(t):
+                typer.echo(f"Error: {t.id!r} is not installed.", err=True)
+                raise typer.Exit(code=2)
+    else:
+        targets = [p for p in detect_platforms() if is_installed(p)]
+
+    if not targets:
+        typer.echo(
+            "No installed platforms found. Run 'wbox skills install' first.",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    current = _pkg_version("wealthbox-cli")
+
+    with as_file(files("wealthbox_tools").joinpath("skills/wealthbox-crm")) as src:
+        for t in targets:
+            existing = (read_meta(skill_dir(t)).get("template") or {}).get("cli_version", "-")
+            try:
+                upgrade_skill(t, Path(src))
+            except SkillInstallError as e:
+                typer.echo(f"Error upgrading {t.id}: {e}", err=True)
+                raise typer.Exit(code=1) from e
+            update_template_meta(skill_dir(t), cli_version=current)
+            typer.echo(f"OK upgraded {t.id}: {existing} -> {current}")
+
+
 @app.command("doctor", help="Diagnose install state and token.")
 def doctor_cmd(
     token: str | None = typer.Option(None, envvar="WEALTHBOX_TOKEN", hidden=True),
@@ -220,13 +262,19 @@ def doctor_cmd(
 
     from ._util import run_client
 
+    current = _pkg_version("wealthbox-cli")
     typer.echo("# Skill install state")
     for p in detect_platforms():
         status = "installed" if is_installed(p) else "not installed"
-        meta_path = skill_dir(p) / "firm" / "_meta.json"
-        bootstrapped = "bootstrapped" if meta_path.exists() else "not bootstrapped"
+        meta = read_meta(skill_dir(p)) if is_installed(p) else {}
+        bootstrapped = "bootstrapped" if meta.get("firm") else "not bootstrapped"
+        template_v = (meta.get("template") or {}).get("cli_version", "-")
+        upgrade_hint = ""
+        if template_v not in ("-", current):
+            upgrade_hint = f"  [upgrade available: {template_v} -> {current}]"
         typer.echo(
-            f"  {p.id:<22} {status:<16} {bootstrapped:<18} {skill_dir(p)}"
+            f"  {p.id:<22} {status:<16} {bootstrapped:<18} "
+            f"template={template_v:<10} {skill_dir(p)}{upgrade_hint}"
         )
 
     typer.echo("\n# Token")

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/src/wealthbox_tools/skills/wealthbox-crm/SKILL.md

@@ -8,14 +8,34 @@ description: Use when the user wants to interact with Wealthbox CRM — creating
 Execute Wealthbox CRM operations via the `wbox` CLI. Supports contacts, tasks, notes, events,
 opportunities, projects, workflows, households, and read-only lookups (categories, users, activity, me).
 
-## First Run (self-delete after completion)
+## First Run
 
-If `firm/_meta.json` does not exist in this skill's directory, this is the
-first invocation on this machine. Before handling the user's request:
+If `_meta.json` in this skill's directory does **not** contain a `firm`
+section, the firm has not been onboarded yet on this machine. Before
+handling the user's request:
 
 1. Read `bootstrap.md` in this skill's directory.
 2. Follow it end-to-end.
-3. When done, this section and `bootstrap.md` will have been deleted.
+3. The bootstrap will populate `_meta.json.firm` so this check passes
+   on subsequent runs.
+
+## Staleness Check
+
+`_meta.json.template.cli_version` records which `wbox` version installed
+the template files. Compare it to the running CLI version:
+
+```bash
+wbox --version
+```
+
+If the template version is older, suggest the user run:
+
+```bash
+wbox skills upgrade
+```
+
+This refreshes SKILL.md, references/, firm-examples/, and bootstrap.md
+across every installed platform while preserving `firm/`.
 
 ## Prerequisites
 

{wealthbox_cli-1.1.1 → wealthbox_cli-1.1.2}/src/wealthbox_tools/skills/wealthbox-crm/bootstrap.md

@@ -1,8 +1,7 @@
 # First-Run Bootstrap
 
-You were told to read this because `firm/_meta.json` does not exist in the skill
-directory. Follow every step below. When you finish, delete this file and trim
-the `## First Run` section out of `SKILL.md`.
+You were told to read this because `_meta.json` in the skill root does not
+contain a `firm` section. Follow every step below.
 
 ## Step 1 — Fetch API-derived firm data
 
@@ -17,12 +16,13 @@ It populates these files per installed platform:
 - `firm/categories.md` — every category type + valid values
 - `firm/custom-fields.md` — custom fields per document type + valid values
 - `firm/users.md` — user id → name → email
-- `firm/_meta.json` — refresh timestamps + firm identity
+- `_meta.json` (skill root) — adds the `firm` section: identity, refresh
+  timestamps, and the CLI version that ran the bootstrap
 - Stub files: `firm/contacts.md`, `firm/tasks.md`, `firm/notes.md`,
   `firm/events.md`, `firm/opportunities.md`, `firm/projects.md`,
   `firm/workflows.md` — one-line TODOs you will fill in next.
 
-Verify `firm/_meta.json` now exists before continuing.
+Verify the `firm` section now exists in `_meta.json` before continuing.
 
 ## Step 2 — Gather firm policy (per-resource)
 
@@ -90,16 +90,11 @@ Ask the advisor: "Is there any firm convention, custom process, or preference
 I haven't asked about that I should follow?" Append freeform answers to
 `firm/workflows.md` under a `## Other Conventions` heading.
 
-## Step 4 — Self-trim
-
-Now that all firm files are filled in:
-
-1. Delete `bootstrap.md` (this file).
-2. Open `SKILL.md`. Find the `## First Run (self-delete after completion)`
-   section. Delete that heading and everything under it through (but not
-   including) the next `## ` heading.
-
-## Step 5 — Confirm and continue
+## Step 4 — Confirm and continue
 
 Tell the advisor: "First-run setup complete — `firm/` populated for <firm
 name>." Then return to the user's original request.
+
+You don't need to delete this file or trim `SKILL.md`. The first-run check
+keys on `_meta.json.firm`, which now exists, so the bootstrap path will be
+skipped on every subsequent invocation automatically.