jaz-clio 5.60.2 → 5.61.0

package/README.md

@@ -82,6 +82,8 @@ that ends up in a journal.
 
 > **No install at all?** Claude.ai, ChatGPT, Cowork, and Microsoft Copilot Studio can use Jaz through the hosted connector. Add `https://mcp.jaz.ai/mcp` as a custom connector and sign in with OAuth, no key. The local setup below is for terminal use, scripting, and editors that run MCP servers as local processes.
 
+Run `clio auth login` once on this computer before enabling local MCP.
+
 **Claude Code**
 
 ```bash
@@ -95,14 +97,13 @@ claude mcp add jaz -- npx jaz-clio mcp
   "mcpServers": {
     "jaz": {
       "command": "npx",
-      "args": ["-y", "jaz-clio", "mcp"],
-      "env": { "JAZ_API_KEY": "jk-your-api-key" }
+      "args": ["-y", "jaz-clio", "mcp"]
     }
   }
 }
 ```
 
-Several companies at once: comma-separate the keys, or use a personal access token.
+OAuth can reach the organizations granted at sign-in; name the organization on each call. Optional key-based access also supports comma-separated keys or a personal access token.
 
 ```json
 { "env": { "JAZ_API_KEY": "jk-org1-key,jk-org2-key" } }
@@ -137,18 +138,18 @@ A close is not one conversation. Month-end runs many steps over several days, an
 
 Also `/jk-keys`, `/jk-policy`, `/jk-teach`, `/jk-save`, `/jk-help`. **`/jaz-*` runs a single workflow; `/jk-*` runs your practice.**
 
-Each company lives under `~/Documents/Jaz Kit/orgs/<company>/`, holding its close config, its policies, and its own API key in a gitignored `.env`. A Jaz key is scoped to one company, so the folder you open is the company you work on: nothing to switch, and no way to post to the wrong books once a folder's key checks out.
+Each company lives under `~/Documents/Jaz Kit/orgs/<company>/`, holding its close config, policies, and organization ID. OAuth credentials stay outside the kit. Pin that ID on every CLI or MCP call and verify it before working. Existing per-company API keys remain optional.
 
 Everything is drafted first, every record carries a link into Jaz for you to review, and an interrupted close resumes exactly where it stopped. Multi-company work needs this CLI, which you already have. Full guide in the [repository README](https://github.com/teamtinvio/jaz-ai#jaz-kit--run-your-practice).
 
 ## Auth
 
 ```bash
-clio auth add <api-key>   # from Settings → API keys in Jaz
+clio auth login           # Sign in to Jaz in your browser
 clio auth whoami          # verify
 ```
 
-Or set `JAZ_API_KEY` in your environment for scripts and CI. For several companies from the CLI, register each with `clio auth add` and pass `--org <label>` per command, or let Jaz Kit keep one key per company folder for you. Every command takes `--json` for structured output.
+Pin an OAuth organization with `--org oauth:<resourceId>`. For optional API-key access, set `JAZ_API_KEY` or register a key using `clio auth add` and pass `--org <label>`. Every command takes `--json` for structured output.
 
 ## Semantic help-center search (optional)
 
@@ -165,3 +166,11 @@ Runs on your machine. Calls go to the Jaz API over HTTPS. No telemetry, no data
 ## License
 
 [MIT](LICENSE)
+
+## OAuth sign-in (default)
+
+Run `clio auth login` to open Jaz sign-in. CLI and local MCP share the session and refresh tokens automatically. Add `--no-browser` to open the printed link yourself on the same computer. Agents can use `--json`; the sign-in link is printed to stderr, and stdout contains only the result and organization choices.
+
+Use `clio auth organizations --json` to list accessible organizations, `clio auth select <resourceId>` to select one, and `--org oauth:<resourceId>` on every organization-scoped command to pin it. `clio auth logout` removes the local session without deleting API-key profiles; revoke its grant in Jaz to remove remote access.
+
+API-key profiles, `--api-key`, `JAZ_API_KEY`, and PATs remain supported. Use `--org oauth:<resourceId>` for OAuth or `--org <label>` for a saved key profile; either overrides an inherited `JAZ_API_KEY`. Without `--org`, the environment key still takes precedence. Do not combine `--api-key` with `--org`. Do not share OAuth storage or commit it to a workspace.

package/assets/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-api
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill whenever you call, debug, or review code that touches the Jaz
   REST API. Covers field names, response shapes, 159 production gotchas, error
@@ -10,16 +10,16 @@ description: >-
   schedulers, subscriptions, attachments, claim settings, and Jaz Magic extraction. Also use
   when building API clients, seeding test data, or adding new endpoint support.
 license: MIT
-compatibility: Requires Jaz API key (x-jk-api-key header). Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
+compatibility: Uses Jaz OAuth by default; organization API keys remain supported. Works with Claude Code, Google Antigravity, OpenAI Codex, GitHub Copilot, Cursor, and any agent that reads markdown.
 ---
 
 # Jaz API Skill
 
 You are working with the **Jaz REST API** — the accounting platform backend. Also fully compatible with Juan Accounting (same API, same endpoints).
 
-## Pick the right invocation path first
+Prefer the configured OAuth connection. Local CLI/MCP shares `clio auth login`; hosted MCP uses its host's sign-in. Select the organization explicitly. For a direct integration, follow the repository's OAuth sign-in reference; the API-key header examples below describe the optional key-based route. Never copy a host's tokens into another application.
 
-Before touching this skill's HTTP details, check what's actually available:
+## Pick the right invocation path first
 
 - **Running inside an MCP host (Claude Desktop, Cowork)**: use the MCP tools (`execute_tool` with `create_invoice`, `list_bills`, etc.). Do not write direct HTTP. The MCP server handles auth, retries, and field shape for you.
 - **Running Claude Code with the `jaz-clio` CLI**: use the CLI commands (`clio invoices list --json`, etc.). Same code path, structured output.

package/assets/skills/api/references/endpoints.md

@@ -9,7 +9,8 @@
 
 ```
 Base URL: https://api.getjaz.com
-Auth Header: x-jk-api-key: <key>
+Auth: OAuth through the configured CLI/MCP connection by default.
+Optional API-key header: x-jk-api-key: <key>
 Content-Type: application/json
 ```
 

package/assets/skills/api/references/field-map.md

@@ -80,7 +80,7 @@ These aliases are applied by middleware on POST/PUT endpoints. The alias is only
 
 | What You'd Guess | Actual API Field | Notes |
 |------------------|-------------------|-------|
-| `apiKey` header | `x-jk-api-key` | Custom header (not Authorization: Bearer) |
+| `apiKey` header | `x-jk-api-key` | API-key route only; OAuth uses Authorization: Bearer |
 | `org.id` | `data[0].resourceId` | Org endpoint returns a LIST |
 | `org.baseCurrency` | `data[0].currency` | Not `baseCurrency` |
 | `org.country` | `data[0].country` | ISO 2-letter code. NOT `countryCode` — that name is a deprecated alias, is optional, and may be absent from the response |

package/assets/skills/api/references/full-api-surface.md

@@ -20,7 +20,7 @@
 | `x-jk-api-key` | Standard API key | `jk-` prefix + 48 hex chars |
 | `x-magic-api-key` | Magic/AI endpoints | Separate key |
 
-**Use `x-jk-api-key` for all API access.**
+**Prefer OAuth through the configured CLI/MCP connection.** Direct applications use Jaz's authorization-code flow with PKCE and send the granted token as `Authorization: Bearer <access-token>`. Choose the intended organization during consent. The `x-jk-api-key` header remains supported for optional organization-key access.
 
 ---
 

package/assets/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-cli
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill when running Clio CLI commands, building shell scripts with
   Clio, debugging auth issues, understanding --json output, paginating results,
@@ -41,19 +41,26 @@ You are working with **Clio** (`jaz-clio`) — the CLI for the Jaz accounting pl
 
 Use **jaz-cli** when running commands. Use **jaz-api** when debugging API errors or understanding field mappings.
 
+## OAuth sign-in (default)
+
+Run `clio auth login` on the user's intended machine and guide browser sign-in. With `--json`, stdout returns organization choices and verification status; the sign-in URL goes to stderr. If there is one organization, it is selected automatically. Otherwise show the choices and run `clio auth select <resourceId> --json`. Use `--org oauth:<resourceId>` on each scoped CLI command. Local MCP shares the session and refreshes tokens automatically; hosted MCP uses its host's OAuth session. `auth organizations --json` refreshes accessible organizations. `auth logout` removes only local OAuth credentials.
+
+Never put tokens in chat or workspace files. Keep the login process alive until the callback completes. Browser callbacks must reach the computer running Jaz; use the user's persistent environment or hosted OAuth when an isolated sandbox cannot receive them. The key-profile commands below remain optional. Use `--org oauth:<resourceId>` for OAuth or `--org <label>` for a saved key profile, even when `JAZ_API_KEY` is inherited.
+
 ## Auth Precedence
 
-Resolution stops at the first match. Higher priority wins silently.
+Explicit `--org` wins over inherited credentials. Do not combine `--api-key` and `--org`. If both `JAZ_API_KEY` and `JAZ_ORG` are set, select explicitly with `--org` or remove one environment override.
 
 | Priority | Source | How to set |
 |----------|--------|------------|
 | 1 | `--api-key <key>` | Per-command flag |
-| 2 | `JAZ_API_KEY` env | `export JAZ_API_KEY=jk-...` |
-| 3 | `--org <label>` flag | Per-command profile lookup |
+| 2 | `--org <selector>` flag | Saved key profile or `oauth:<resourceId>` |
+| 3 | `JAZ_API_KEY` env | `export JAZ_API_KEY=jk-...` |
 | 4 | `JAZ_ORG` env | `export JAZ_ORG=acme-sg` (pinned session) |
-| 5 | Active profile | `clio auth switch <label>` (stored in `~/.config/jaz-clio/credentials.json`) |
+| 5 | Preferred OAuth session | `clio auth login` / `clio auth select <resourceId>` |
+| 6 | Active API-key profile | `clio auth switch <label>` (stored in `~/.config/jaz-clio/credentials.json`) |
 
-**Critical gotcha**: If `JAZ_API_KEY` is set in your shell, it overrides `--org` and the active profile. Run `unset JAZ_API_KEY` before switching tenants with `clio auth switch`.
+**Key access**: Use `--org <label>` to select a saved API-key profile. Without `--org`, `JAZ_API_KEY` remains the default when set. An unknown explicit selection fails without falling back to the environment key.
 
 Auth subcommands:
 ```
@@ -332,7 +339,7 @@ Multiple contacts match "Acme":
 Be more specific, or use the full billingName.
 
 # Auth not configured
-No API key configured. Run `clio auth add <key>`, set JAZ_API_KEY, or pass --api-key.
+No Jaz authentication configured. Run `clio auth login`, or use optional API-key access.
 
 # API validation error (422)
 API error 422: lineItems[0].accountResourceId is required when saveAsDraft is false
@@ -394,7 +401,7 @@ See `references/common-workflows.md` for end-to-end multi-command patterns.
 2. **Line-item accounts don't fuzzy-resolve.** Use UUID or exact name.
 3. **Cash entries finalize immediately.** Unlike invoices which default to draft.
 4. **--offset is page number (0-indexed), not row count.**
-5. **JAZ_API_KEY env overrides --org.** Unset to use profiles.
+5. **Explicit organization selection wins.** `--org` uses the selected OAuth organization or saved key profile even when `JAZ_API_KEY` is set.
 
 See [references/agent-gotchas.md](./references/agent-gotchas.md) for the full list of 19 critical gotchas. See [references/output-shapes.md](./references/output-shapes.md) for `--json` output structures. See [references/error-recovery.md](./references/error-recovery.md) for 30+ error patterns with fixes.
 

package/assets/skills/cli/references/agent-gotchas.md

@@ -15,7 +15,7 @@
 
 5. **--all caps at 1,000 rows by default** (lowered from 10,000 in 2026-04). For large orgs, pass `--max-rows 50000` explicitly. The CLI auto-paginates with concurrent requests and **stops fetching once `--max-rows` is reached** (early-stop, not slice-after — the previous behavior would pull every page and discard the excess, causing minute-long hangs on busy sandboxes).
 
-6. **JAZ_API_KEY env var overrides --org and active profile.** If set, all commands use that key regardless of `--org` or `clio auth switch`. Run `unset JAZ_API_KEY` to restore profile-based auth. Run `echo $JAZ_API_KEY` to check.
+6. **Explicit --org wins over JAZ_API_KEY.** Use `--org oauth:<resourceId>` for OAuth or `--org <label>` for a saved key profile. Without `--org`, the environment key remains the default. Never print its value.
 
 7. **--json output goes to stdout; errors go to stderr.** Piping `clio invoices list --json | jq .` works cleanly. Resolution feedback ("Contact: Acme Corp (abc1234...)") is on stderr and won't corrupt JSON. Always parse stdout only.
 

package/assets/skills/cli/references/common-workflows.md

@@ -209,7 +209,8 @@ clio ledger-find-fix apply -- "<previewId>"
 Manage multiple organizations from one machine.
 
 ```bash
-# Add multiple org keys
+# Prefer OAuth: clio auth login, then pin --org oauth:<resourceId> per call.
+# Optional alternative: add multiple org keys
 clio auth add jk-sg-key-here --as acme-sg
 clio auth add jk-ph-key-here --as acme-ph
 clio auth add jk-us-key-here --as acme-us

package/assets/skills/cli/references/error-recovery.md

@@ -9,12 +9,12 @@
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `No API key configured` | No auth source found in resolution chain | `clio auth add jk-xxx` or `export JAZ_API_KEY=jk-xxx` |
+| `No API key configured` | No auth source found in resolution chain | `clio auth login`; optional API-key access uses `clio auth add` |
 | `Invalid API key` | Key doesn't start with `jk-` or is malformed | Verify key format: must be `jk-` prefix + UUID |
-| `Unauthorized (401)` | Key expired, revoked, or wrong org | Run `clio auth whoami` to check; re-add key with `clio auth add` |
+| `Unauthorized (401)` | Session/key expired, revoked, or wrong org | Run `clio auth whoami` to check; reconnect OAuth with `clio auth login`, or repair the chosen API-key profile |
 | `--api-key and --org cannot be used together` | Conflicting auth flags | Use one or the other, not both |
 | `Profile 'xyz' not found` | `--org xyz` references non-existent profile | Run `clio auth list` to see available profiles |
-| `JAZ_API_KEY overrides --org` | Env var takes precedence silently | `unset JAZ_API_KEY` before using `--org` or `clio auth switch` |
+| `JAZ_API_KEY and JAZ_ORG are both set` | Two inherited authentication choices | Select explicitly with `--org oauth:<resourceId>` or `--org <label>`, or remove one environment override |
 
 ---
 
@@ -92,7 +92,7 @@
 ```bash
 clio auth whoami          # Check current auth source
 clio auth list            # See all saved profiles
-echo $JAZ_API_KEY         # Check for env override
+test -n "${JAZ_API_KEY:-}" && printf "JAZ_API_KEY is set\n" # Never print its value
 echo $JAZ_ORG             # Check for pinned org
 ```
 

package/assets/skills/conversion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-conversion
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill when migrating accounting data into Jaz — importing from Xero,
   QuickBooks, Sage, MYOB, or Excel exports. Covers the full conversion pipeline:

package/assets/skills/jaz-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-kit
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill when an accountant, bookkeeper, or owner is running real books
   in Jaz across one or more organizations from the terminal — setting up a
@@ -30,7 +30,7 @@ Jaz Kit gives each organization a folder: what the organization is, how it likes
   _shared/policies/ skills/      firm-wide, applies to every organization
   orgs/<slug>/
     ORG.md                       the close config + session journal
-    .env                         JAZ_API_KEY — this company's key (gitignored)
+    .env                         optional API-key access only (gitignored)
     policies/ rules/ skills/     how this organization works
     scripts/  work/              automations · scratch (swept on exit, after asking)
     closes/<period>/
@@ -38,7 +38,7 @@ Jaz Kit gives each organization a folder: what the organization is, how it likes
       workpapers/                permanent audit file
 ```
 
-The company's key lives in its own folder. A `jk-` key is org-scoped — it reaches exactly one company's books — so the folder you open decides which ledger you touch; there is no profile to switch and no `--org` to get wrong. The `.env` is gitignored and its value is never printed. (On a default Mac, `~/Documents` syncs to iCloud, so the key syncs too — bounded and revocable, and set `JAZ_KIT_HOME` outside `~/Documents` to avoid it. See `references/workspace.md`.)
+ORG.md's `organization_id` identifies the company's ledger. Use OAuth by default: sign in with `clio auth login`, then pin every command with `--org oauth:<organization_id>`. CLI and local MCP share the local sign-in; tokens stay outside the kit. Hosted MCP uses its own OAuth connection and the same explicit organization ID. Verify that each connection returns that ID before work. Existing per-company `.env` API keys remain an optional route; see `references/workspace.md`.
 
 ## Operations
 

package/assets/skills/jaz-kit/references/flows.md

@@ -6,11 +6,7 @@ Schemas live in `workspace.md` (KIT.md, ORG.md, `.env`) and `close-state.md` (CL
 
 ## Ground rules for every flow
 
-1. **One organization per session — the key decides which.** Each workspace's `.env` holds that company's own `jk-` key, and a `jk-` key is org-scoped: one key, one company's books. So the folder you open determines which ledger you touch — there is no active profile to switch, no label, no `--org` to get wrong. Load the key in the same command as each `clio` call:
-   ```
-   set -a; . "orgs/<slug>/.env"; set +a; clio <command> --json
-   ```
-   `set -a; . file; set +a` sources `JAZ_API_KEY` for that one command without echoing it — the value never reaches the transcript or `ps`. Never pass `--org`, never `clio auth switch`, and never carry a `JAZ_API_KEY` exported from another shell into a Jaz Kit session.
+1. **One organization per session — ORG.md decides which.** Use its `organization_id` on every call. OAuth CLI: `clio <command> --org oauth:<organization_id> --json`. Hosted MCP: pass the same ID explicitly. Never rely on the shared active organization. For the optional API-key route only, source the folder's `.env` in the same command and omit `--org`; verify the key resolves to the recorded ID.
 2. **Draft first.** `saveAsDraft` defaults to `false` in the API — omitting it posts live. Every write in a Jaz Kit flow sets `saveAsDraft: true` (or `--plan` then a non-finalized run for `clio ct`) unless the org's `rules/` explicitly relaxes that transaction type. Finalization happens in the review flow, never as a side effect.
 3. **Never print a key.** The key lives in the workspace `.env`, which the user pastes into — never chat, never a message, never an error. Source the file; do not read the key value into your own output. `jk-` strings are redacted on sight.
 4. **Judgment gets recorded.** When the user accepts a variance, carries a residual, or overrides a default, call `jot` at that moment. Mechanical steps never jot.
@@ -31,7 +27,7 @@ Idempotent. No kit → create it. Kit exists → this is the add-a-company flow.
 - *clients* → say "the client", "the engagement"
 - *both* → default to client vocabulary, treat own entities as clients
 
-**3. Create the skeleton and KIT.md** from `templates.md`. The keys live inside the kit (step 5), so git hygiene matters — write `.gitignore` **before** `git init` so a key can never be staged:
+**3. Create the skeleton and KIT.md** from `templates.md`. Write `.gitignore` **before** `git init`, including for optional API-key access:
 ```
 .env
 *.env
@@ -41,27 +37,20 @@ work/
 ```
 Offer git (default yes).
 
-**4. Check the CLI.** Multi-company work runs through the `clio` CLI. If `clio` is missing, say so and offer `npm i -g jaz-clio`; a single company can still work through the plugin's MCP key alone, but the workspace-key model below needs the CLI. If commands misbehave, `clio update` (the CLI self-notifies about new versions — do not hand-roll a version comparison).
+**4. Check the tools.** Reuse the authenticated hosted MCP or local CLI. Install local tooling only if the chosen workflow needs it. Skills do not require an API key.
 
-**5. Connect the company — its key lives in its folder.** A `jk-` key is org-scoped: one key *is* one company's books, so the key in the folder is all the identity the workspace needs.
-   1. Guide key creation in the Jaz UI (**Settings → API keys**).
-   2. Write a staging `.env` (`<root>/.new-org.env`) containing the single line `JAZ_API_KEY=` and tell the user the exact path to paste their key after the `=`. **Never take the key through chat** — it goes straight into the file.
-   3. Validate and identify the company in one call, sourcing the file so the value never surfaces:
-      ```
-      set -a; . "<root>/.new-org.env"; set +a; clio org info --json
-      ```
-      This returns the name, `resourceId`, currency, country, and financial year end — the key was valid if this succeeds, and it names the company so you never ask the user to retype it. A `401` means the pasted key is wrong or already revoked; send them back to step 5.1.
+**5. Connect the company.** Prefer OAuth. Reuse a verified connection or start `clio auth login --json` for local tooling; let the user complete browser sign-in. List accessible organizations and use the only organization automatically, or present a choice. Read the selected organization with `clio org info --org oauth:<organization_id> --json` or the corresponding hosted MCP tool. Record its resource ID; never store tokens in the workspace. Existing API-key workspaces can retain their connection using the optional procedure in `workspace.md`.
 
 **6. Auto-profile.** Two small calls answer almost everything:
 ```
-set -a; . "<root>/.new-org.env"; set +a; clio reports generate ledger-highlights --json
+clio reports generate ledger-highlights --org oauth:<organization_id> --json
 ```
 (Identity already came from step 5.3's `clio org info`.)
 Highlights (`get_ledger_highlights` on MCP) returns what the organization actually *uses*, not what exists: `hasCrossCurrencyActivity` and `activeCurrencyCodes` settle `multi_currency`; `transactionCountByType` shows which modules are live (a `FIXED_ASSET` count means the register is in use); `distinctAccountCount` and `activeAccountResourceIds` name the accounts in play; first/last transaction dates bound the periods worth closing.
 
 That matters because *existing* and *used* diverge hard: one real organization had 1,027 accounts of which 144 were active, and 226 bank accounts. Never transcribe the ledger into ORG.md — read highlights, then ask which of the active accounts they reconcile in a close.
 
-**Never run a bare `clio context --json`** — unscoped it preloads every reference entity (1.5 MB on that same org). If you need reference detail, scope it: `... clio context -w chart_of_accounts --json` (sourcing the same `.env`).
+**Never run a bare `clio context --json`** — unscoped it preloads every reference entity (1.5 MB on that same org). If you need reference detail, scope it: `... clio context -w chart_of_accounts --json` (passing the same explicit organization selector).
 
 Present the filled ORG.md and ask the user to confirm or correct. Never present a guess as a fact — mark anything inferred as *proposed*.
 
@@ -71,9 +60,7 @@ Present the filled ORG.md and ask the user to confirm or correct. Never present
 
 **If the directory already exists for THIS organization** (its `organization_id` matches), this is a re-onboard, not a new one. Never rewrite ORG.md and never reinstall the starter rules — that would destroy hand-edited materiality, accrual definitions, decisions, and the journal. Show a field-by-field diff of what auto-profiling found against what is on file, apply only what the user accepts, and leave everything else untouched.
 
-**9. Write the workspace**: create `orgs/<slug>/` with ORG.md, the empty folders `policies/ rules/ skills/ scripts/ work/ closes/`, and the starter rules from `templates.md` (draft-first, locked-period, review threshold). Then **move the staging key into place**: `mv <root>/.new-org.env orgs/<slug>/.env`. That file holds the real `JAZ_API_KEY` and is gitignored by step 3.
-
-**iCloud note.** If the kit root resolves under an iCloud-synced path (the default `~/Documents/Jaz Kit` does on most Macs), say so plainly once: the `.env` key will sync to the user's iCloud and their other devices. That is usually an acceptable trade — a `jk-` key is scoped to this one company and revocable in the Jaz UI in seconds — but if they would rather keep keys off the cloud, they can set `JAZ_KIT_HOME` to a path outside `~/Documents` and re-run setup. Their call; make it once, do not nag.
+**9. Write the workspace**: create `orgs/<slug>/` with ORG.md, the empty folders `policies/ rules/ skills/ scripts/ work/ closes/`, and the starter rules from `templates.md` (draft-first, locked-period, review threshold). Record the verified `organization_id` in ORG.md. OAuth requires no `.env` file. For optional key-based access, keep the company key in the ignored `.env` as described in `workspace.md`.
 
 **10. Close the loop.** Show the folder path and the single next step: `/jk-open <slug>`.
 
@@ -89,13 +76,9 @@ Triggers: "open <org>", "switch to <org>", "work on <client>", "let's do <org>'s
 
 **4. Load context**: ORG.md, then `policies/` and `rules/`, then `skills/` — org files first, `_shared/` second, and **org-level wins on conflict**. Do not re-read files already in context.
 
-**5. Load the company's key and verify it live.** Confirm `orgs/<slug>/.env` exists and holds a `JAZ_API_KEY` line; if it doesn't, the workspace was never fully set up — route to `/jk-keys`. Then, sourcing the key so the value never surfaces:
-```
-set -a; . "orgs/<slug>/.env"; set +a; clio org info --json
-```
-Compare the returned `resourceId` against ORG.md. Same identifier, different name → the company was renamed; flag it and offer to update ORG.md. Identifier mismatch → **the wrong key is in this folder** (someone pasted company B's key into company A's `.env`); stop, do not write, send them to `/jk-keys`. `401`/`403` → the key was revoked or access removed; `/jk-keys` and stop. This live check is why the key belonging to the folder matters — a session physically cannot write to the wrong company once its own key verifies.
+**5. Verify the company live.** Read `organization_id` from ORG.md, then run `clio org info --org oauth:<organization_id> --json` or use the hosted MCP organization read with that ID. For an existing API-key workspace, use its `.env` loading procedure instead. Compare `resourceId` to ORG.md and stop on mismatch. A changed name with the same ID is a rename; offer to update the context. On denied or revoked access, guide reauthentication before continuing.
 
-**6. Cross-check the tool plane.** If MCP tools are available, call `get_organization` and compare its identifier to what step 5 returned. A mismatch means the plugin's own `JAZ_API_KEY` (from connector settings) points at a different company than this folder's key — **stop**, tell the user to clear that setting, and do not write. The MCP plane can't be pointed per-folder; when it disagrees with the workspace key, the workspace key is the intended one.
+**6. Cross-check every tool connection used.** Pass the intended organization explicitly to MCP and compare the returned ID. Stop on a mismatch. A separately configured key-based MCP server may need reconfiguration; never assume it follows the CLI selection.
 
 **7. Report state, then wait**: open close and its phase, next filing deadline computed from ORG.md, count of items awaiting review, last session's closing note. Offer the obvious next action; do not start it unasked.
 
@@ -168,6 +151,8 @@ Across every `orgs/*/`: organization, last closed period, any open close and its
 
 Triggers: "add a key", "rotate the key", "my key stopped working".
 
+This flow is only for optional API-key access. For OAuth, use `clio auth login` to reconnect and verify the organization; no key file is needed.
+
 The key is the line `JAZ_API_KEY=jk-...` in `orgs/<slug>/.env`. Everything here is editing that one file. **Never display a key value, and never take one through chat — the user pastes into the file.**
 
 - **Check**: source it and make a live call. `set -a; . "orgs/<slug>/.env"; set +a; clio org info --json` — success means the key is valid and names the company; `401` means it is wrong or revoked.

package/assets/skills/jaz-kit/references/templates.md

@@ -182,7 +182,7 @@ Create the file empty apart from its heading. **Do not seed it with suggestions*
 
 ## orgs/<slug>/.env
 
-One line, the company's own org-scoped key. Created during setup as a staging file the user pastes into, then moved into the folder. Gitignored. Never echoed.
+Optional API-key access only. OAuth workspaces use the organization ID in ORG.md and need no `.env`. When the user chooses API-key access, store one company key privately in this gitignored file. Never echo it.
 
 ```
 JAZ_API_KEY=<paste this company's Jaz API key here>

package/assets/skills/jaz-kit/references/workspace.md

@@ -89,40 +89,28 @@ The next deadline is `filing_periods` + `filing_offset`. Past due with nothing r
 
 Estimation methods for accruals must match what the jobs skill's month-end playbook expects — see its accruals step for the list.
 
-## .env — the company's key
+## Authentication
 
-Each company's folder holds its own key:
+OAuth is the default. Store only `organization_id` in ORG.md. Run `clio auth login` on the machine running Jaz, then use `clio <command> --org oauth:<organization_id> --json` for every organization-scoped call. Never rely on the shared active organization. Refresh tokens stay in Jaz's private local configuration, outside the kit. Hosted MCP uses its own OAuth session; always pass the same organization ID and verify it.
 
-```
-JAZ_API_KEY=jk-<this company's key>
-```
-
-That is a real secret, gitignored by `.env` / `*.env` / `.env.*` (write `.gitignore` before `git init`). Nothing else belongs in this file — no other config, no second key.
-
-## Auth model
+Before opening a company, run `clio org info --org oauth:<organization_id> --json` and compare `resourceId` with ORG.md. Refuse a mismatch. Reauthenticate when access expires or is revoked; never silently switch to an API key. If CLI is unavailable, the same identity check can use hosted MCP.
 
-A `jk-` key is **org-scoped**: it grants access to exactly one company's books. So the key that sits in `orgs/acme/.env` *is* Acme's identity — there is no separate profile, label, or active-org to keep in sync, and nothing to switch. Open a folder, its key is the org.
+### Optional .env API key
 
-**Loading the key.** The CLI reads `JAZ_API_KEY` from the environment (it does not itself read `.env` files), so every `clio` call in a session sources the folder's file in the same command:
+Existing key-based workspaces remain supported. Keep their single `JAZ_API_KEY=jk-...` in a gitignored `.env`. Never read or print the value. For this route only, source the folder's `.env` in the same command as each CLI call, without `--org`:
 
 ```
 set -a; . "orgs/<slug>/.env"; set +a; clio <command> --json
 ```
 
-`set -a; . file; set +a` is the safe form — never `export $(… | xargs)`, whose `xargs` subprocess exposes the key in `ps` argv and word-splits the value. Never run the loader under `set -x`, and never echo the variable. Because each command sources exactly one folder's key and passes no `--org`, there is no ambient state to leak between sessions.
-
-**Two guards still apply** (they protect against habit and misconfiguration): the CLI refuses `--org` when `JAZ_API_KEY` is set — Jaz Kit never passes `--org`, so this only fires if something slips — and it refuses comma-separated keys. Neither is part of the normal path; both are backstops.
-
-**The one cross-check worth doing.** The plugin's MCP server has its own `JAZ_API_KEY` from connector settings, which may point at a different company than the folder you opened. The MCP plane can't be re-pointed per folder, so at open the flow compares `get_organization` (MCP) against `clio org info` (the folder's key) and stops on a mismatch. Otherwise the two models coexist cleanly: MCP for a single-company user with no CLI, the folder key for everyone running several.
-
-**iCloud.** The default root `~/Documents/Jaz Kit` syncs on most Macs, so the `.env` keys ride to the user's iCloud and their other devices. That is a real exposure and worth saying once at setup — but a bounded one: a `jk-` key reaches one company's books and is revocable in the Jaz UI in seconds. A user who would rather keep keys off the cloud sets `JAZ_KIT_HOME` to a path outside `~/Documents`. Git is separately handled by the ignore rules above.
+Do not mix key overrides with OAuth organization selectors. Keep `.env`, `*.env`, and `.env.*` ignored. When migrating an existing folder to OAuth, verify access to its recorded organization first, stop loading its `.env`, and preserve the old key until the user chooses to remove it. Keys placed in a cloud-synced folder will sync with it; OAuth tokens must never be placed in the kit.
 
 ## Sharing a kit across a team
 
 The kit is a git repository (offered at setup; `.env` / `*.env` / `work/` ignored). To share:
 
 1. Push to a **private** repository. The `.env` keys stay behind — they are gitignored, so nothing sensitive travels.
-2. Each colleague clones it and pastes their **own** key into each `orgs/<slug>/.env`. Keys are per-machine; only the ORG.md context and policies are shared.
+2. Each colleague clones it and signs in to Jaz themselves. Share organization context and policies, never OAuth sessions. Colleagues choosing API-key access configure their own ignored `.env` files.
 3. Pull before starting, push after finishing.
 
 Coordinate who works which company. Two people closing the same period simultaneously will conflict in CLOSE.md, and worse, may both finalize the same drafts. Git surfaces the file conflict; nothing prevents the double-finalize, so agree who owns a client before starting.

package/assets/skills/jaz-pseudo-sql/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-pseudo-sql
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill when answering ad-hoc data questions that aren't covered by
   download_export (canonical reports — anomaly, audit, aging, P&L, BS, GL,

package/assets/skills/jobs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-jobs
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill for recurring accounting workflows — month/quarter/year-end
   close, bank reconciliation, GST/VAT filing, payment runs, credit control,

package/assets/skills/transaction-recipes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jaz-recipes
-version: 5.60.2
+version: 5.61.0
 description: >-
   Use this skill when modeling complex multi-step accounting transactions —
   anything that spans multiple periods, involves changing amounts, or requires

package/assets/templates/platform-rules/jaz-agent-rules.md

@@ -1,8 +1,6 @@
 # Jaz — Agent Operating Rules
 
-How any AI agent (Claude / GPT / Gemini / Copilot / Cursor) should use the Jaz accounting stack in this workspace. Drop this file into the path your platform expects and your agent picks it up automatically.
-
-Source of truth lives in the installed skills (`.claude/skills/jaz-*/SKILL.md` or `.agents/skills/jaz-*/SKILL.md`). This file is a 30-second bias prompt — load the skill for the deep contract.
+Jaz accounting guidance for this workspace. Load the installed Jaz skills for detailed workflows and API contracts.
 
 ## Discovery
 
@@ -43,7 +41,9 @@ Exception: `fx-reval` is verification-only — Jaz auto-handles period-end IAS 2
 
 ## Safety
 
-- Never echo `JAZ_API_KEY` or `jk-*` strings to the user or into generated code.
+Prefer OAuth (`clio auth login` locally); API keys are optional.
+
+- Never echo OAuth tokens, `JAZ_API_KEY`, or `jk-*` strings to the user or into generated code.
 - Never invent enum values (UPPER_SNAKE_CASE only — match exactly).
 - Errors come back structured (`code`, `message`, `failedRows[]`, `errorDetails[]`). Read them — don't guess at what went wrong.