jaz-clio 5.4.40 → 5.5.0

package/README.md

@@ -19,7 +19,7 @@ Requires **Node.js 18+** ([nodejs.org](https://nodejs.org)). Also fully compatib
 
 - [Three Ways In](#three-ways-in) — CLI, MCP, Skills
 - [CLI](#cli) — 55 command groups
-- [MCP Server](#mcp-server) — 274 tools for AI agents
+- [MCP Server](#mcp-server) — 284 tools for AI agents
 - [Skills](#skills) — Teach any AI the Jaz API
 - [Setup](#setup) — Auth, multi-org, automation
 
@@ -54,7 +54,7 @@ clio practice create-engagement acme-pte-ltd --type monthly-close --period 2026-
 
 ## MCP Server
 
-275 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
+284 CLI tools, available to any AI agent that speaks MCP. Runs locally — no cloud, no ports. Includes the v5.2.0 `practice_*` tools (init, onboard_client, list_clients, load_client, create_engagement, load_engagement) so an agent in Claude Desktop or Claude Code can scaffold and load client workspaces conversationally.
 
 **Claude Code:**
 ```bash

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.4.40
+version: 5.5.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 141 production gotchas, error
@@ -447,6 +447,32 @@ Bills, invoices, and credit notes share identical mandatory field specs. Adding
 
 141. **`bulk_upsert_chart_of_accounts` — sync bulk-upsert with PARTIAL_SUCCESS** — wraps `POST /api/v1/chart-of-accounts/bulk-upsert` (max 500 per call). Returns synchronously (no jobId polling): `{ resourceIds: string[], failedRows: ImportedRowError[], failedCount: number }` per rule 136. Each successful row contributes one `resourceId`; each failure surfaces a `failedRows[]` entry with `rowIndex` (1-based per the API), `columnName`, `columnValue`, `errorCode`, `errorMessage`. **Dedup is by NAME, not code** — collisions emit `ORGANIZATION_CHART_OF_ACCOUNT_DUPLICATED` per row (other rows in the batch still succeed). Provide `resourceId` per account to update; omit to create. Accepts the classic 12 + 9 IFRS 18 `accountType` values per rule 140 (variants normalized client-side). For one-off creates with auto-dedup-on-name (returns existing if found), use `create_account` instead. CLI counterpart: `clio accounts bulk-upsert --input <file.json>`.
 
+142. **`capsuleRecipe` payload is mutually exclusive with `capsuleResourceId`** on trigger mutations (create/update of invoice, bill, journal, cash_in, cash_out). Use `capsuleRecipe` to CREATE a new capsule via the recipe engine; use `capsuleResourceId` to ATTACH a base-trx to an existing capsule. Sending both returns 422 (`excluded_with` validator).
+
+143. **Capsule recipe publish is best-effort post-commit.** On success the trigger-mutation response carries `capsuleRecipeJob: { jobResourceId, capsuleResourceId, subscriptionFBPath, totalRecords, idempotentHit, recipeKey }` (verified live 2026-05-27). **Note `jobResourceId` (NOT `resourceId`)** on the trigger-mutation payload — this is the polling key. If the base-trx commits but the recipe publish fails, `capsuleRecipeJob` is null and the base-trx is still saved. Recovery: poll `search_background_jobs` filtered by **`baseTransactionResourceId`** — NOT `capsuleResourceId` (the capsule may not exist yet if the recipe never started). The standalone `resume_capsule_recipe(capsuleResourceId)` response IS the full `CapsuleRecipeJob` shape with `resourceId` (distinct from the inline trigger-mutation payload).
+
+144. **`recipeName` IS enum-constrained at the API layer** (verified live 2026-05-27): closed enum `LOAN_AMORTIZATION | ACCRUAL_REVERSAL | PREPAID_AMORTIZATION | DEFERRED_REVENUE | IFRS16_LEASE` on `POST /capsule-recipes/preview` and on `capsuleRecipe.recipeName` payloads on trigger mutations. Send a string not in the set → 422 validation_error. Don't hard-code the 5 values in motherboard descriptions — discover via `list_capsule_recipes` (the source of truth) and pass the discovered name through.
+
+145. **Pseudo-SQL `truncated:true` does NOT mean "you hit the cap"** — it means "more rows matched than were returned in this preview". Inspect `rowCount` vs preview cap (100) or your LIMIT to interpret. If you need every row, switch to `export_pseudo_sql`.
+
+146. **Pseudo-SQL export `downloadUrl` is S3 pre-signed with ~15min expiry** (`X-Amz-Expires=900`). Fetch immediately; don't store the URL. If a fetch returns 403 (expired), call `get_pseudo_sql_export(jobId)` again for a fresh URL.
+
+147. **Cashflow report** (`download_export(exportType='cashflow')`) returns the org's CASHFLOW template (IAS 7). If no template configured, returns 404 `template_not_found`. Configure via Jaz settings before invoking.
+
+148. **`resume_capsule_recipe` after `terminalReason=BLOCKED_AFTER_3_RESUME_ATTEMPTS` is unavailable.** Only path forward is `rollback_capsule_recipe(capsuleResourceId)` or manual cleanup via Jaz admin. Resume is NOT idempotent — each call counts toward the 3-attempt limit.
+
+149. **`rollback_capsule_recipe` returning `status=PARTIAL_ROLLBACK`** with `blockedAtomResourceIds[]` is safe to retry (rollback is idempotent on already-deleted atoms). Persistent partial-rollback typically indicates an atom is referenced downstream; escalate to ops if retry doesn't resolve.
+
+150. **`preview_capsule_recipe` and trigger mutations return 422 `RECIPE_INVALID_BASE_TRANSACTION_TYPE`** if `baseTransactionType` is not in the recipe's `allowedBaseTransactionTypes` (see descriptor at `get_capsule_recipe`). Example: PREPAID_AMORTIZATION only allows PURCHASE; supplying SALE returns 422.
+
+151. **Sending BOTH `capsuleRecipe` AND `capsuleResourceId`** on the same trigger mutation returns 422 (`excluded_with` validator — same lock as Rule 142). Pick one based on intent.
+
+152. **`saveAsDraft: true` + `capsuleRecipe` payload** — recipe is stashed in the draft's `pending_capsule_recipe` JSONB column and fires on draft activation (not on draft create). The base-trx commits as DRAFT immediately; the recipe job is created later when the draft is activated via `convert_drafts_to_active`.
+
+153. **Pseudo-SQL `Idempotency-Key` dedup is server-side primary key** — same key + DIFFERENT query body returns the prior job's result (the server does NOT cross-check the new query body). For agent reliability, `run_pseudo_sql_and_download` auto-keys from `sha256(query).slice(0,16)` so dedup is query-tied automatically. If you call `export_pseudo_sql` directly with a manual key, treat it as a per-intent token — don't reuse across different queries.
+
+154. **`rollback_capsule_recipe` on a non-recipe capsule** (a capsule created by the legacy `create_capsule` tool or imported, not by the recipe engine) returns 422 `RECIPE_ROLLBACK_JOB_NOT_FOUND` ("No CAPSULE_RECIPE job found for capsule X in organization Y — nothing to roll back"). Rollback only works on capsules whose lifecycle was managed by the recipe engine. For legacy capsules, use `delete_capsule` instead.
+
 ## Supporting Files
 
 For detailed reference, read these files in this skill directory:

package/assets/skills/api/help-center-mirror/get-started.md

@@ -319,29 +319,58 @@ Source: https://help.jaz.ai/en/articles/11710444-billing-account-setup
   - Optionally, add emails to CC for the billing email.
 - Once setup is done, inside each billing accounts you can:
   - Recharge your account
-  - Setup auto-charge and add payment methods
+  - Setup auto recharge and add payment methods
   - View transaction history
   - Edit billing account details
   - Make the billing account inactive
 
-**Q6. How do I recharge my billing accounts?**
+**Q6. How does billing work in Jaz?**
 
-- To recharge your account, you can manually top up or turn on the **auto charge function**.**Q7. How do saved payment methods work?**
+- Billing depends on whether you've set a Preferred Billing Date or not. Here's the flow for each:
+  - **Preferred Billing Date is set**
+    - All subscription charges are consolidated into one billing on your Preferred Billing Date each month.
+    - If you subscribe mid-cycle, your first charge is prorated, covering only the days from your subscription date up to your next billing date.
+      - The prorated amount is calculated as: (Monthly plan amount ÷ days in the subscription month) × days remaining until billing date.
+      - For example, if your billing date is the 30th and you subscribe on the 22nd, your first invoice covers 8 days at the daily rate. From the 30th onward, you are billed the full recurring amount each month.
+    - All charges are consolidated on the billing date and the consolidated invoice is sent to your billing email the following day.
+  - **Preferred Billing Date is not set**
+    - Your billing date is the start date of each organization's subscription.
+    - If your billing account pays for multiple organizations with different start dates, each organization is billed separately on its own start date.
+    - Invoices are sent the day after each organization's subscription start date.
+  - If your billing account has insufficient funds on the billing date, your organizations will be automatically downgraded. See [Re-instating your Org's Subscription](https://help.jaz.ai/en/articles/13368779-re-instating-your-org-s-subscription) to recover within 28 days.
+
+**Q7. How do I edit my billing account?**
+
+- Go to Settings → Billing Account → Hover over a billing account → Click the 3-dot icon → Edit.
+
+**Q8. How do I recharge my billing accounts?**
+
+- To recharge your account, you can manually top up or turn on the **Auto recharge function**.
+- When auto charge is enabled, your account is automatically recharged before the billing date using your saved payment methods. The auto-charge covers the amount needed to settle your upcoming or overdue bill.
+
+**Q9. How do saved payment methods work?**
 
 - Saved methods enable secure, fast, and automatic recharges. You can save cards and select wallets. If one payment method fails, the system will automatically try the other saved methods.
 
-**Q8. How do I set up auto-charge and add payment methods?**
+**Q10. How do I set up auto recharge and add payment methods?**
 
-- Add new payment methods. Having at least two is recommended for reliability.
-- Enable the Auto Charge toggle to activate automatic payments.
+- Add new payment methods. Having at least two is recommended. If the primary method fails, the system will automatically attempt the next saved method.
+- Enable the auto recharge toggle to activate automatic payments before your billing date.
 
-**Q9. Can I give others access to my billing account?**
+**Q11. Can I give others access to my billing account?**
 
-- Yes. You can add users through the **Delegate Whitelist**. Go to**Billing Account** > hover over the **account** > click the**three-dot icon** > **Edit** >**Delegate Whitelist** > **Add Emails**
+- Yes. You can add users through the **Delegate Whitelist**. Go to**Billing Account** → hover over the **account** → click the**three-dot icon** → **Edit** →**Delegate Whitelist** → **Add Emails**
 - Whitelisted users can use your account as a billing method in organizations where you both have billing permissions. They cannot view or manage the account.
-- **Note:** Only whitelist trusted users. Jaz is not liable for any unauthorized charges made by delegates.**Q10. I’ve set up my Billing Account, what’s next?**
+- **Note:** Only whitelist trusted users. Jaz is not liable for any unauthorized charges made by delegates.**Q12. What happens when I make my billing account inactive?**
+
+- You won’t be able to pay for Jaz plans, or use auto recharge.
+- If the billing account is actively paying for subscriptions, those organizations will be downgraded after the current billing cycle ends.
+- Downgraded organizations can be reinstated within 28 days. See [Re-instating your Org's Subscription](https://help.jaz.ai/en/articles/13368779-re-instating-your-org-s-subscription).
+- Note: Billing accounts cannot be deleted.
+
+**Q13. I’ve set up my Billing Account, what’s next?**
 
-- Head over to **[Plans & Add-ons](https://help.jaz.ai/en/articles/11710415-choosing-plans-addons)**to customize the right plan for your organization.
+- Head over to [Plans & Add-ons](https://help.jaz.ai/en/articles/11710415-choosing-plans-add-ons) to customize the right plan for your organization.
 
 ---