financy 0.3.0 → 0.4.0

package/README.md

@@ -36,7 +36,7 @@ The CLI talks to your Open-Finance data through the Financy API, which is a **pa
 feature**. To use it you must:
 
 1. **Register for a Financy account** at [open-finance.ai](https://open-finance.ai).
-2. **Subscribe to a paid plan** (Starter or Pro) — the data API is **not** available
+2. **Subscribe to any paid plan** (Starter, Pro, or Ultra) — the data API is **not** available
    on the free plan (every data command returns exit code `4`).
 3. Copy your `clientId`, `clientSecret`, and `userId` from the Financy app →
    **Settings → API**.
@@ -80,6 +80,11 @@ financy transactions list|get <id>   Transactions with --from/--to/--account/--t
 financy categories                   The category taxonomy (English + Hebrew)
 financy providers list|branches      Reference data: banks and branches
 financy refresh                      Trigger an on-demand refresh of all connections (20 credits)
+financy integrations list|get <id>   Connected business systems (invoicing: Invoice4U)
+financy receivables                  Who owes you what: open and overdue invoices, aged per customer
+financy documents list|get           Invoices, receipts and credit notes in a business system
+financy customers list|get           Customers in a business system
+financy proposals list|get|create    Document drafts — issued only after you approve them in Financy
 financy config                       Show resolved endpoints + credential sources (secret masked)
 financy skills list|install          Agent skills bundled with the CLI
 financy mcp                          Run the embedded MCP server (stdio)
@@ -95,6 +100,155 @@ Every command takes `--json` for a stable machine-readable envelope
 `--all` (auto-paginate). Exit codes: `0` ok · `1` unexpected · `2` usage · `3` auth
 · `4` plan · `5` credits · `6` not-found · `7` api.
 
+## Connect bit (digital wallet) and ask about it
+
+bit can now be connected to Financy as a **digital wallet** (ארנק דיגיטלי). The
+connection runs over regulated Open Banking and is **read-only**: Financy reads the
+wallet account, its balance, and its transactions. It cannot send or request
+payments, and there is no savings data.
+
+### 1. Connect bit — from your phone
+
+bit approves Open Banking consents **only inside its mobile app**, so start the
+connection on the phone that has bit installed:
+
+1. Open the Financy app at [financy.open-finance.ai](https://financy.open-finance.ai)
+   in your phone's browser.
+2. **Connect account** → the **ארנקים** (wallets) tab → **bit**.
+3. Approve the consent in the bit app when it opens, then return to Financy.
+
+Starting from a desktop browser will not work — the approval step has to land in
+the bit app.
+
+### 2. Ask about it from the CLI
+
+bit is a connection like any bank or card, with provider id `bit`. There are no
+wallet-specific commands; filter by its connection id:
+
+```sh
+financy connections list          # bit appears with PROVIDER "bit" — copy its ID
+financy status                    # is the bit data current?
+financy accounts list --connection <bit-connection-id>     # the wallet and its balance
+financy transactions list --connection <bit-connection-id> --from 2026-09-01 --all
+financy transactions list --connection <bit-connection-id> --from 2026-09-01 --all --json
+```
+
+Leave out `--connection` and you get every source at once — bit next to your banks
+(e.g. Bank Hapoalim, provider `hapoalim`) and cards (e.g. Isracard, provider
+`isracard`):
+
+```sh
+financy accounts list                                  # bit, bank, and card balances together
+financy transactions list --from 2026-09-01 --all      # this month, every source
+financy providers list                                 # resolve any PROVIDER value to its name
+```
+
+### 3. Ask about it from Claude or ChatGPT
+
+Through the MCP server the same data is available as tools: `list_connections`
+and `get_status` to find bit and check freshness, `list_accounts` and
+`list_transactions` (both take a `connection` argument, and `list_transactions`
+takes `from`/`to`) to read it, and `list_providers` to resolve provider ids.
+
+- **Claude Code**, with the local server: `claude mcp add financy -- npx financy mcp`
+  (see [MCP server](#mcp-server-for-ai-agents)).
+- **Claude or ChatGPT**, with no CLI: add the hosted Financy connector,
+  `https://mcp.open-finance.ai/mcp`, as a custom connector and sign in with your
+  Financy account.
+
+Then ask in plain language. The assistant pulls bit, bank, and card transactions
+and combines them. Questions like "who hasn't paid yet" work by comparing this
+period's incoming bit transfers with earlier ones — give the assistant the list of
+who you expect to pay if you have one.
+
+### Prompts for business owners
+
+| Prompt | In English |
+|---|---|
+| «מי עוד לא שילם לי החודש?» | Who hasn't paid me yet this month? |
+| «מי שילם לי פעמיים בטעות?» | Who paid me twice by mistake? |
+| «כמה עשיתי היום?» | How much did I take in today? |
+| «מי מהלקוחות הקבועים נעלם לי?» | Which regular customers have stopped paying? |
+| «כמה כסף שוכב לי בביט ולא עבר לבנק?» | How much is sitting in bit and hasn't moved to the bank? |
+| «איזה יום בשבוע הכי רווחי לי?» | Which day of the week brings in the most? |
+| «כמה נכנס החודש מכל החשבונות — ביט והבנק ביחד?» | How much came in this month across all accounts — bit and the bank together? |
+| «תן לי רשימה של כל מי ששילם לי בביט השבוע, עם סכום ותאריך» | List everyone who paid me on bit this week, with amount and date. |
+| «מה התשלום הממוצע בביט החודש לעומת החודש שעבר?» | What's the average bit payment this month versus last month? |
+| «תבנה לי דאשבורד שאני פותח כל בוקר: הכנסות מביט ומהבנק, הוצאות בישראכרט, ומי עוד לא שילם» | Build me a dashboard I open every morning: income from bit and the bank, Isracard spending, and who still hasn't paid. |
+
+## Invoices (Invoice4U)
+
+Connect your invoicing system to Financy and the CLI reads it next to your bank
+data: who owes you what, every invoice and receipt, your customers — and it can
+**draft** documents for you to approve. Invoice4U is supported today; it needs a
+paid plan (Starter and above), and a free account gets exit `4` with the code
+`UPGRADE_REQUIRED`.
+
+Connect Invoice4U in the Financy app, on the **Connections** page; the CLI reads
+connections, it does not create them. Then:
+
+```sh
+financy integrations list                     # copy the integration ID (intg_…)
+financy receivables                           # open and overdue totals, per customer
+financy receivables --detailed --json         # …with each customer's open invoices
+financy documents list <integrationId> --status open --from 2026-09-01
+financy documents list <integrationId> --receivable-only --all --json
+financy documents get <integrationId> <documentId>
+financy customers list <integrationId> --search "סטודיו"
+```
+
+```
+$ financy receivables
+Receivables as of 2026-10-11
+  ILS: ₪2,340.00 open, ₪2,340.00 overdue across 1 documents
+
+CUSTOMER   OPEN       OVERDUE    DOCS  MAX DAYS LATE  CUSTOMER ID
+סטודיו גל  ₪2,340.00  ₪2,340.00  1     10             icus_…
+```
+
+Tables show amounts in shekels; under `--json` every amount is an integer in minor
+units (`…Minor`, agorot for ILS) exactly as the API returns it, and record lists
+carry a `freshness` object saying how recent the synced data is. Record lists page
+with `--limit`, `--cursor` and `--all`; `proposals list` takes only `--limit` (max 50).
+
+### Drafting a document
+
+`financy proposals create` sends a draft request and creates a **draft** — nothing
+is issued. The document is created in Invoice4U only after you open the returned
+approval link and approve it in Financy:
+
+```sh
+cat > draft.json <<'JSON'
+{
+  "action": "create_tax_invoice",
+  "items": [{
+    "counterpartyId": "icus_…",
+    "lines": [{ "description": "עיצוב לוגו", "quantity": 1, "unitPriceMinor": 234000 }],
+    "pricesIncludeVat": true
+  }]
+}
+JSON
+financy proposals create <integrationId> --file draft.json
+financy proposals get <proposalId>            # status: pending_approval → completed
+```
+
+`action` is one of `create_tax_invoice`, `create_invoice_receipt`, `create_receipt`,
+`create_credit_note` or `create_customer`. Each request carries an `Idempotency-Key`
+(a fresh UUID unless you pass `--idempotency-key`), so retrying with the same key
+returns the first draft instead of a second one. The CLI cannot approve or cancel a
+draft — that is always your step in Financy.
+
+Integration errors keep the API's code (`UPGRADE_REQUIRED`, `NOT_FOUND`,
+`VALIDATION_FAILED`, `PROPOSAL_INVALID`, `RATE_LIMITED`, …) and exit by class: `4`
+plan or permission, `6` not found, `2` invalid request, `1` conflict or expired
+cursor, `7` rate-limited or unavailable. Under `--json` the error also carries
+`retryable`, `userActionRequired` and, where the API gives one, an `action`.
+`INSUFFICIENT_SCOPE` means the token predates the key's integration access: the CLI
+mints a fresh one and retries once, and if that is refused too, the key has no
+integration access yet (Starter or above; rotate the key in Financy → Settings → API).
+The integrations API lives at `https://api.open-finance.ai/integrations`; override it
+with `FINANCY_INTEGRATIONS_URL` (it otherwise follows `FINANCY_API_URL`'s host).
+
 ## Agent skills
 
 Skills ship inside this package, so they can never drift from the CLI version they
@@ -130,6 +284,16 @@ an unconfigured server returns a structured `NOT_CONFIGURED` error from every to
 `refresh_connections` costs 20 credits — its tool description tells agents to
 confirm with the user first.
 
+The local server also serves the invoicing tools — `list_integrations`,
+`get_integration`, `get_receivables`, `list_invoicing_documents`,
+`get_invoicing_document`, `list_invoicing_customers`, `get_invoicing_customer`,
+`list_proposals`, `get_proposal`, and the draft tools `draft_invoice`,
+`draft_invoice_receipt`, `draft_receipt` and `draft_credit_note`. A draft tool only
+creates a draft: its description tells the agent to show the user the approval link,
+and nothing is issued until the user approves it in Financy. These tools are not in
+the importable `TOOLS` table, because hosts that import it (such as the hosted
+Financy connector) serve their own invoicing tools under the same names.
+
 ## Updating
 
 ```sh

package/dist/bin.js

@@ -4,13 +4,23 @@ import {
   EXIT,
   STALE_THRESHOLD_DAYS,
   VERSION,
+  createDraft,
   fetchAccount,
   fetchAccounts,
   fetchBranches,
   fetchCategories,
   fetchConnection,
   fetchConnections,
+  fetchIntegration,
+  fetchIntegrations,
+  fetchInvoicingCustomer,
+  fetchInvoicingCustomers,
+  fetchInvoicingDocument,
+  fetchInvoicingDocuments,
+  fetchProposal,
+  fetchProposals,
   fetchProviders,
+  fetchReceivables,
   fetchRefresh,
   fetchStatus,
   fetchTransaction,
@@ -23,7 +33,7 @@ import {
   resolveEndpoints,
   sanitizeCredential,
   writeCredentialsFile
-} from "./chunk-VE5WZRGU.js";
+} from "./chunk-LZSZIBYL.js";
 
 // src/run.ts
 import { Command, CommanderError } from "commander";
@@ -99,7 +109,7 @@ function renderTable(items, now) {
 
 // src/commands/setup.ts
 import { join } from "path";
-var CREDENTIALS_GUIDE = "financy needs your Financy API credentials: clientId, clientSecret, and userId.\nFind them in the Financy app \u2192 Settings \u2192 API.\nThis requires a registered Financy account on a paid plan (Starter or Pro) \u2014\nthe data API is not available on the free plan. Sign up at https://open-finance.ai\n\n";
+var CREDENTIALS_GUIDE = "financy needs your Financy API credentials: clientId, clientSecret, and userId.\nFind them in the Financy app \u2192 Settings \u2192 API.\nThis requires a registered Financy account on a paid plan (Starter, Pro, or Ultra) \u2014\nthe data API is not available on the free plan. Sign up at https://open-finance.ai\n\n";
 async function setupCommand(ctx) {
   if (!ctx.noInput) ctx.out(CREDENTIALS_GUIDE);
   const credentials = ctx.noInput ? credentialsFromEnv(ctx.env) : await credentialsFromPrompts(ctx.prompt);
@@ -177,6 +187,7 @@ async function configCommand(ctx) {
           authTokenUrl: endpoints.authTokenUrl,
           apiBaseUrl: endpoints.apiBaseUrl,
           chatBaseUrl: endpoints.chatBaseUrl,
+          integrationsBaseUrl: endpoints.integrationsBaseUrl,
           clientId: clientId.value ? maskId(clientId.value) : null,
           clientIdSource: clientId.source,
           clientSecretSet: clientSecret.source !== "unset",
@@ -201,6 +212,7 @@ async function configCommand(ctx) {
     `  auth url       ${endpoints.authTokenUrl}`,
     `  api url        ${endpoints.apiBaseUrl}`,
     `  chat url       ${endpoints.chatBaseUrl}`,
+    `  integrations   ${endpoints.integrationsBaseUrl}`,
     "",
     `  clientId       ${maskId(clientId.value)}  (${clientId.source})`,
     `  clientSecret   ${clientSecret.value ? `\u2022\u2022\u2022\u2022\u2022\u2022\u2022\u2022 (set, ${clientSecret.value.length} chars)` : "(unset)"}  (${clientSecret.source})`,
@@ -285,7 +297,12 @@ function renderList(ctx, envelope, columns) {
   if (ctx.json) {
     ctx.out(
       JSON.stringify(
-        { data: envelope.data, count: envelope.count, nextPage: envelope.nextPage },
+        {
+          data: envelope.data,
+          count: envelope.count,
+          nextPage: envelope.nextPage,
+          ...envelope.freshness === void 0 ? {} : { freshness: envelope.freshness }
+        },
         null,
         2
       )
@@ -297,7 +314,16 @@ function renderList(ctx, envelope, columns) {
 }
 function renderGet(ctx, envelope) {
   if (ctx.json) {
-    ctx.out(JSON.stringify({ data: envelope.data }, null, 2));
+    ctx.out(
+      JSON.stringify(
+        {
+          data: envelope.data,
+          ...envelope.freshness === void 0 ? {} : { freshness: envelope.freshness }
+        },
+        null,
+        2
+      )
+    );
   } else {
     ctx.out(JSON.stringify(envelope.data, null, 2) + "\n");
   }
@@ -414,9 +440,192 @@ function registerReadCommands(program, base, setExit) {
   });
 }
 
+// src/commands/integration-commands.ts
+import { readFile } from "fs/promises";
+import { randomUUID } from "crypto";
+var SYMBOLS = { ILS: "\u20AA", USD: "$", EUR: "\u20AC", GBP: "\xA3" };
+var money = (minor, currency = "ILS") => {
+  if (typeof minor !== "number" || !Number.isFinite(minor)) return "\u2014";
+  const code = typeof currency === "string" ? currency : "ILS";
+  const symbol = SYMBOLS[code] ?? `${code} `;
+  const major = Math.abs(minor) / 100;
+  return (minor < 0 ? "-" : "") + symbol + major.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+};
+var INTEGRATION_COLUMNS = [
+  { header: "ID", value: (i) => i.id },
+  { header: "SYSTEM", value: (i) => dash(i.connectorName) },
+  { header: "LABEL", value: (i) => dash(i.label) },
+  { header: "AUTH", value: (i) => dash(i.auth?.state) },
+  { header: "SYNC", value: (i) => dash(i.sync?.documents?.state) },
+  { header: "SYNCED AT", value: (i) => dash(i.sync?.documents?.lastSuccessAt) }
+];
+var DOCUMENT_COLUMNS = [
+  { header: "ISSUED", value: (d) => dash(d.issueDate) },
+  { header: "TYPE", value: (d) => dash(d.type) },
+  { header: "NUMBER", value: (d) => dash(d.number) },
+  { header: "CUSTOMER", value: (d) => dash(d.counterparty?.name) },
+  { header: "GROSS", value: (d) => money(d.amounts?.grossMinor, d.currency) },
+  { header: "OWED", value: (d) => money(d.receivable?.remainingMinor, d.currency) },
+  { header: "STATUS", value: (d) => dash(d.status) },
+  { header: "ID", value: (d) => d.id }
+];
+function newestFirst(a, b) {
+  const byDate = (b.issueDate ?? "").localeCompare(a.issueDate ?? "");
+  if (byDate !== 0) return byDate;
+  return (b.number ?? "").localeCompare(a.number ?? "", "en", { numeric: true });
+}
+var CUSTOMER_COLUMNS = [
+  { header: "ID", value: (c) => c.id },
+  { header: "NAME", value: (c) => dash(c.name) },
+  { header: "TAX ID", value: (c) => dash(c.businessTaxId) },
+  { header: "ACTIVE", value: (c) => c.active === false ? "no" : "yes" }
+];
+var PROPOSAL_COLUMNS = [
+  { header: "ID", value: (p) => p.id },
+  { header: "ACTION", value: (p) => dash(p.action) },
+  { header: "STATUS", value: (p) => dash(p.status) },
+  { header: "ITEMS", value: (p) => dash(p.totals?.count ?? p.items?.length) },
+  { header: "TOTAL", value: (p) => money(p.totals?.grossMinor, p.totals?.currency) },
+  { header: "CREATED", value: (p) => dash(p.createdAt) },
+  { header: "EXPIRES", value: (p) => dash(p.expiresAt) }
+];
+var RECEIVABLE_COLUMNS = [
+  { header: "CUSTOMER", value: (c) => dash(c.counterparty?.name) },
+  { header: "OPEN", value: (c) => money(c.openMinor, c.currency) },
+  { header: "OVERDUE", value: (c) => money(c.overdueMinor, c.currency) },
+  { header: "DOCS", value: (c) => dash(c.documentCount) },
+  { header: "MAX DAYS LATE", value: (c) => dash(c.maxDaysPastDue) },
+  { header: "CUSTOMER ID", value: (c) => dash(c.counterparty?.id) }
+];
+function renderReceivables(r) {
+  const lines = [`Receivables as of ${dash(r.asOf)}`];
+  for (const c of r.byCurrency ?? []) {
+    lines.push(
+      `  ${dash(c.currency)}: ${money(c.totals?.openMinor, c.currency)} open, ${money(c.totals?.overdueMinor, c.currency)} overdue across ${dash(c.totals?.documentCount)} documents`
+    );
+  }
+  if ((r.byCurrency ?? []).length === 0) lines.push("  Nothing is owed.");
+  let out = lines.join("\n") + "\n";
+  const customers = r.customers ?? [];
+  if (customers.length > 0) out += "\n" + renderTable2(customers, RECEIVABLE_COLUMNS);
+  const shown = r.truncated?.customersShown;
+  const total = r.truncated?.customersTotal;
+  if (typeof shown === "number" && typeof total === "number" && shown < total) {
+    out += `
+Showing ${shown} of ${total} customers \u2014 raise --customer-limit to see more.
+`;
+  }
+  for (const i of r.integrations ?? []) {
+    if (i.ready === "pending") {
+      out += `Note: ${dash(i.integrationId)} is still running its first sync \u2014 totals are incomplete.
+`;
+    } else if (i.stale) {
+      out += `Note: ${dash(i.integrationId)} data is stale (last synced ${dash(i.dataAsOf)}).
+`;
+    }
+  }
+  return out;
+}
+function renderDraft(p, replayed) {
+  const count = p.totals?.count ?? p.items?.length;
+  return [
+    `Draft ${p.id} created${replayed ? " (replayed \u2014 the same draft as the first request)" : ""} \u2014 status ${dash(p.status)}.`,
+    `  ${dash(p.action)} \xB7 ${dash(count)} item${count === 1 ? "" : "s"} \xB7 ${money(p.totals?.grossMinor, p.totals?.currency)}`,
+    "",
+    `  Approve it in Financy: ${dash(p.approvalUrl)}`,
+    `  Nothing is issued until you approve it there. The draft expires ${dash(p.expiresAt)}.`
+  ].join("\n") + "\n";
+}
+async function readDraftFile(path) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    throw new CliError(
+      EXIT.USAGE,
+      "DRAFT_FILE_UNREADABLE",
+      `could not read ${path}: ${error.code ?? String(error)}`
+    );
+  }
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch (error) {
+    throw new CliError(EXIT.USAGE, "INVALID_DRAFT", `${path} is not valid JSON (${error.message})`);
+  }
+}
+function registerIntegrationCommands(program, base, setExit) {
+  const ctx = { json: base.json, out: base.out };
+  const integrations = program.command("integrations").description("Connected business systems (invoicing: Invoice4U)");
+  integrations.command("list").option("--json", "machine-readable output").action(async () => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderList(ctx, await fetchIntegrations(config, base.now), INTEGRATION_COLUMNS));
+  });
+  integrations.command("get <integrationId>").option("--json", "machine-readable output").action(async (id) => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderGet(ctx, await fetchIntegration(config, base.now, id)));
+  });
+  program.command("receivables").description("Who owes you what: open and overdue invoices, aged per customer").option("--integration <ids>", "limit to these integration ids (comma-separated)").option("--as-of <date>", "age receivables against this date (YYYY-MM-DD, default today)").option("--detailed", "also list each customer's open documents").option("--customer-limit <n>", "how many customers to return (max 200)").option("--include-proforma", "count open proforma invoices too").option("--json", "machine-readable output").action(
+    async (opts) => {
+      const config = await loadOrThrow(base.env);
+      const envelope = await fetchReceivables(config, base.now, {
+        integrations: opts.integration ? [opts.integration] : void 0,
+        asOf: opts.asOf,
+        detailed: opts.detailed,
+        customerLimit: opts.customerLimit,
+        includeProforma: opts.includeProforma
+      });
+      base.out(base.json ? JSON.stringify(envelope, null, 2) : renderReceivables(envelope.data));
+      setExit(EXIT.OK);
+    }
+  );
+  const documents = program.command("documents").description("Invoices, receipts and credit notes in a connected business system");
+  documents.command("list <integrationId>").option("--status <status>", "open|partially_paid|paid|partially_credited|credited|cancelled|closed|unknown").option("--type <type>", "invoice|receipt|invoice_receipt|credit_note|proforma|quote|order|delivery_note|other").option("--customer <customerId>", "filter to one customer (icus_\u2026 from customers list)").option("--from <date>", "issued on or after (YYYY-MM-DD)").option("--to <date>", "issued on or before (YYYY-MM-DD)").option("--receivable-only", "only documents that are still owed money").option("--number <number>", "the document number").option("--limit <n>", "page size (max 200)").option("--cursor <token>", "resume from a nextPage cursor").option("--all", "auto-paginate to the end").option("--json", "machine-readable output").action(async (integrationId, opts) => {
+    const config = await loadOrThrow(base.env);
+    const envelope = await fetchInvoicingDocuments(config, base.now, integrationId, opts);
+    const rows = base.json ? envelope : { ...envelope, data: [...envelope.data].sort(newestFirst) };
+    setExit(renderList(ctx, rows, DOCUMENT_COLUMNS));
+  });
+  documents.command("get <integrationId> <documentId>").option("--json", "machine-readable output").action(async (integrationId, documentId) => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderGet(ctx, await fetchInvoicingDocument(config, base.now, integrationId, documentId)));
+  });
+  const customers = program.command("customers").description("Customers in a connected business system");
+  customers.command("list <integrationId>").option("--search <text>", "part of the customer name").option("--limit <n>", "page size (max 200)").option("--cursor <token>", "resume from a nextPage cursor").option("--all", "auto-paginate to the end").option("--json", "machine-readable output").action(async (integrationId, opts) => {
+    const config = await loadOrThrow(base.env);
+    const envelope = await fetchInvoicingCustomers(config, base.now, integrationId, opts);
+    setExit(renderList(ctx, envelope, CUSTOMER_COLUMNS));
+  });
+  customers.command("get <integrationId> <customerId>").option("--json", "machine-readable output").action(async (integrationId, customerId) => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderGet(ctx, await fetchInvoicingCustomer(config, base.now, integrationId, customerId)));
+  });
+  const proposals = program.command("proposals").description("Document drafts \u2014 issued only after you approve them in Financy");
+  proposals.command("list").option("--integration <id>", "filter to one integration").option("--status <status>", "pending_approval|approved|executing|completed|partially_failed|failed|expired|cancelled").option("--reference <ref>", "filter by the clientReference you sent").option("--limit <n>", "how many (max 50; this list has no cursor)").option("--json", "machine-readable output").action(async (opts) => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderList(ctx, await fetchProposals(config, base.now, opts), PROPOSAL_COLUMNS));
+  });
+  proposals.command("get <proposalId>").option("--json", "machine-readable output").action(async (id) => {
+    const config = await loadOrThrow(base.env);
+    setExit(renderGet(ctx, await fetchProposal(config, base.now, id)));
+  });
+  proposals.command("create <integrationId>").description("Create a document DRAFT from a JSON file; it is issued only after you approve it in Financy").requiredOption("--file <path>", 'the draft request JSON: {"action": "...", "items": [...]}').option("--idempotency-key <key>", "reuse a key to make a retry return the first draft (default: a new UUID)").option("--json", "machine-readable output").action(async (integrationId, opts) => {
+    const config = await loadOrThrow(base.env);
+    const body = await readDraftFile(opts.file);
+    const envelope = await createDraft(
+      config,
+      base.now,
+      integrationId,
+      body,
+      opts.idempotencyKey ?? randomUUID()
+    );
+    base.out(base.json ? JSON.stringify(envelope, null, 2) : renderDraft(envelope.data, envelope.replayed));
+    setExit(EXIT.OK);
+  });
+}
+
 // src/commands/skills.ts
 import { existsSync } from "fs";
-import { cp, readFile, readdir, stat } from "fs/promises";
+import { cp, readFile as readFile2, readdir, stat } from "fs/promises";
 import { dirname, join as join2 } from "path";
 import { fileURLToPath } from "url";
 var INSTALL_SUBPATH = join2(".claude", "skills");
@@ -462,7 +671,7 @@ async function listSkills(skillsRoot) {
   for (const name of entries) {
     const file = join2(skillsRoot, name, "SKILL.md");
     try {
-      const front = parseFrontmatter(await readFile(file, "utf8"));
+      const front = parseFrontmatter(await readFile2(file, "utf8"));
       skills.push({ name: front.name ?? name, description: front.description ?? "" });
     } catch {
     }
@@ -740,7 +949,7 @@ async function run(argv, io = {}) {
     exitCode = await configCommand({ env, json, out });
   });
   program.command("mcp").description("Run the embedded MCP server (stdio) exposing the CLI as agent tools").action(async () => {
-    const { startMcpServer } = await import("./server-RM4BAVES.js");
+    const { startMcpServer } = await import("./server-WGN36UXM.js");
     await startMcpServer(env);
   });
   const skills = program.command("skills").description("Agent skills bundled with financy (Claude Code and other agents)");
@@ -773,6 +982,9 @@ async function run(argv, io = {}) {
   registerReadCommands(program, { env, now, json, out }, (code) => {
     exitCode = code;
   });
+  registerIntegrationCommands(program, { env, now, json, out }, (code) => {
+    exitCode = code;
+  });
   if (argv.length === 0) {
     program.outputHelp();
     return EXIT.OK;