bkper 5.4.1 → 5.5.1

package/lib/docs/cli/app-usage.md

@@ -0,0 +1,87 @@
+# App Usage
+
+Use the Apps installed in a Book, or available to install, to do work on it, instead of rebuilding what an App already does.
+
+Apps are part of how a Book works. They react to its Events, read their settings from Custom Properties, act on the Book as their own users, and may offer an interface in the Book or an API. An App's own route keeps results consistent with what it does on its own, and it is the Book's established, auditable way to do that work.
+
+All commands run as the signed-in user; Apps and Bkper enforce the user's Book permissions.
+
+---
+
+## Explore the Book's Apps
+
+```bash
+# Apps installed in a book
+bkper app list -b abc123
+
+# One App in full, including its readme
+bkper app get exchange-bot
+```
+
+For each App, read:
+
+-   `description` and, for a closer look, the readme from `app get` — what it does and how people use it.
+-   `propertiesSchema` — the property keys it reads on the Book, Accounts, Groups, and Transactions.
+-   `events` — the Book changes it reacts to.
+-   `menuText` — its interface, opened from the Book's menu.
+
+Match the `propertiesSchema` keys against the properties of the Book and its Accounts, Groups, and Transactions (`bkper book get`, `bkper account list`, `bkper group list`) to see which Apps are set up in this Book and how. Bot responses on events (`bkper event list -b <bookId>`) show what Apps have done.
+
+## Find an App to install
+
+When no installed App fits the task, look in the catalog:
+
+```bash
+# Apps you can install, most used first
+bkper app list
+
+# Read one App's readme before proposing it
+bkper app get <appId>
+
+# Install it (a change to the Book)
+bkper app install <appId> -b <bookId>
+```
+
+Read the readme for the setup an App needs after installation, usually properties on the Book, Accounts, or Groups.
+
+## Call an App's API
+
+```bash
+# The App's OpenAPI spec: operations, parameters, and schemas
+bkper app api spec inventory-bot
+
+# Read
+bkper app api request exchange-bot "/api/v1/books/abc123/exchange-rates?date=2026-08-05"
+
+# Send JSON data (POST unless -X says otherwise)
+bkper app api request inventory-bot /api/v1/books/abc123/accounts/def456/calculate -d '{"date":"2026-08-31"}'
+
+# Larger bodies via stdin
+cat body.json | bkper app api request merge-duplicates /api/v1/analyze
+```
+
+-   Read the spec before calling. Use paths exactly as written there, filling path parameters with IDs obtained from Bkper.
+-   Decide from each operation's summary, description, and schemas what it reads and what it changes in the Book. The HTTP method is a hint: GET usually only reads. When it is unclear whether an operation changes the Book, treat it as a change.
+-   Not every App has an API. `app api spec` then reports `<appId> does not publish an OpenAPI spec`. Such Apps work through Book events, and through their interface when they have one (`menuText`).
+-   A failed request exits with code 1 and `Error requesting app API: <status> <message>`, using the App's own error message.
+
+---
+
+<details>
+<summary>Command reference</summary>
+
+-   `app list` - List apps you have access to; readmes are omitted
+    -   `-b, --book <bookId>` - List the apps installed in this book instead
+-   `app get <appId>` - Get an app, including its readme
+-   `app install <appId> -b <bookId>` - Install an app on a book
+-   `app uninstall <appId> -b <bookId>` - Uninstall an app from a book
+-   `app api spec <appId>` - Print the app's OpenAPI spec (`/openapi.json`)
+    -   `-p, --preview` - Use the preview environment
+-   `app api request <appId> <path>` - Send a request to the app's API (`/api/...` paths only), as the signed-in user, and print the response body
+    -   `-X, --method <method>` - HTTP method (default: `GET`, or `POST` when data is sent)
+    -   `-d, --data <json>` - JSON request body; without it, a body piped via stdin is sent
+    -   `-p, --preview` - Use the preview environment
+
+Requests go to `https://{appId}.bkper.app`, or `https://{appId}-preview.bkper.app` with `--preview`. Redirects are not followed. JSON responses print compact when piped and pretty in a terminal; other responses print as they are.
+
+</details>

package/lib/docs/core/core-concepts.md

@@ -65,7 +65,7 @@ Groups inherit the nature of the accounts they contain:
 
 ## Books
 
-A **Book** is a self-contained ledger — the complete scope of an entity, whether an individual, a project, or a business. Every Account, Transaction, and Group lives within a Book, and every Book balances to zero. Books can track any countable resource using the same from-to model.
+A **Book** is a self-contained ledger — the complete scope of an entity, whether an individual, a project, or a business. Every Account, Transaction, and Group lives within a Book, and every Book balances to zero. Books can track any countable resource using the same from-to model. Their amounts are plain quantities of one unit — money, stocks, inventory — whose meaning comes from the people using them, not the ledger. Track each unit in its own Book.
 
 The sum of all credits and debits recorded in a Book always tallies to zero — nothing is created or destroyed, only transferred. For more complex entities, multiple Books can be organized into a Collection.
 
@@ -143,10 +143,16 @@ Unlike Account structures, Hashtags can be added or removed as needs evolve, mak
 
 **Collections** group related Books for organization and consolidated views. Each Book remains self-contained and balanced — Collections simply provide navigation and structure across multiple Books. You might track resources in multiple currencies, or organize branch offices in one collection.
 
-Collections can also serve as references for automations (Bots or Apps) that work on all Books in the collection.
+Collections can also serve as references for Apps that work on all Books in the collection.
 
 ## Events
 
-Every action in a Book — such as posting a transaction, editing an account, or attaching a file — generates an **Event**. Events record _who_ (a user) or _what_ (a bot, an automation) performed the action and _when_, forming a complete audit trail essential for collaboration and trust.
+Every action in a Book — such as posting a transaction, editing an account, or attaching a file — generates an **Event**. Events record _who_ (a user) or _what_ (an App or an automation) performed the action and _when_, forming a complete audit trail essential for collaboration and trust.
 
-Events are also the foundation of Bkper's automation model. Bots and Agents listen for specific event types and react automatically — for example, calculating taxes when a transaction is posted or converting currencies when one is checked.
+Events are also the foundation of Bkper's automation model. Apps listen for specific event types and react automatically — for example, calculating taxes when a transaction is posted or converting currencies when one is checked.
+
+## Apps
+
+**Apps** extend what Books can do. An App is installed in a Book and works through the same building blocks described above: it can react to the Book's Events, take its settings from Custom Properties, and act on the Book like any user — every change it makes is recorded as an Event of its own.
+
+Some Apps also offer an interface inside the Book, or an API for work started on demand. A Book's installed Apps are part of how that Book works, and more can be installed from the App directory.

package/lib/docs/index.md

@@ -5,10 +5,13 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 For Bkper app implementation, refactoring, or code review, always read `apps/quality.md` alongside the task-specific references. After implementation, review the changed code against the guidelines before considering the work complete.
 
 - `cli/data-management.md` — CLI reference for managing financial data and files: books, accounts, groups, files, transactions, events and bot responses (bot errors, replay, delete), per-account balance queries, query operators (on:, after:, before:, account:, group:), JSON output shapes and jq reshaping, human-review Bkper UI links, batch operations via stdin/piping, collections.
+- `cli/app-usage.md` — Using Bkper apps to do work on a Book instead of rebuilding what they do: list a Book's installed apps and the app catalog, read descriptions, readmes, and property schemas, match them to the Book's properties, read an app's OpenAPI spec and call its API as the user, install apps.
 - `cli/app-management.md` — CLI reference for building and deploying Bkper apps: init/git clone/credential helpers, dev/build/deploy workflow, app install/uninstall, secrets management, app logs, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
 - `apps/overview.md` — Platform evaluation and capability overview: use when comparing managed Bkper hosting with self-managed infrastructure or clarifying platform responsibilities; use the task-specific app references for implementation.
 - `apps/ai.md` — Bkper AI in apps, scripts, and tools: ask the Jev decision model with TypeSafe's SDK or language models with AI SDK Open Responses, authenticate through app `/api/*` routes or a Bkper token outside the platform, handle errors, and keep Book writes under deterministic application control.
-- `ai/decision-models.md` — Automating recurring judgments in code, such as categorizing bank lines, matching duplicates, or flagging entries, with Bkper AI decision models: writing questions and state, reading calibrated answers, and acting only above thresholds while routing uncertain cases to a person.
+- `ai/decision-models.md` — Designing software around decision models: when to use one, the three kinds of question, a step-by-step workflow from facts to thresholds and human review, and a worked bank-line example. The request, answers, errors, and caching are in `api/ai-gateway.md`.
+- `api/ai-gateway.md` — Bkper AI Gateway API guide: call Bkper AI language and decision models from your own client, script, or server — authentication, model IDs, requests, decision request rules and answer guarantees, streaming, errors, caching, and links to each operation's page.
+- `api/managed-agent.md` — Bkper Managed Agent API guide: build apps, chat bots, and scripts on the agent behind Bkper Agent — sessions, instructions, inputs and idempotency, Book context, streams, files, a Slack bot example, limits, errors, and links to each operation's page.
 - `apps/first-app.md` — First-app walkthrough: scaffold, install, run locally, trigger an event, customize the listing, establish shared source, check, and deploy.
 - `apps/architecture.md` — App and template architecture: npm workspace structure, Lit/Vite client, Hono Worker, typed `/api/*` contracts, authentication, `/events`, static assets, and supported app shapes.
 - `apps/quality.md` — Cross-cutting quality guidance for Bkper apps: UI consistency, immediate first rendering, typed API contracts, cohesive low-coupling modules, separation of business behavior from connectors and storage, security, and final implementation review. Load for app implementation, refactoring, or review tasks.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "5.4.1",
+    "version": "5.5.1",
     "description": "Official Bkper CLI for accounting data, automation, apps, and AI agents",
     "bin": {
         "bkper": "lib/cli.js"