bkper 4.12.14 → 4.12.16

package/README.md

@@ -1,4 +1,3 @@
-[bkper.yaml reference]: #bkperyaml-reference
 [Developer Docs]: https://bkper.com/docs
 [App Template]: https://github.com/bkper/bkper-app-template
 [Pi]: https://pi.dev/
@@ -76,8 +75,6 @@ bkper transaction create -b <bookId> --description "Office supplies 123.78"
 ```
 
 > Run `bkper --help` or `bkper <command> --help` for built-in documentation on any command.
->
-> To build and deploy Bkper Apps, see [App Management](#app-management).
 
 ### Access Token
 
@@ -93,6 +90,8 @@ curl -s -H "Authorization: Bearer $TOKEN" \
   https://api.bkper.app/v5/books | jq '.items[].name'
 ```
 
+---
+
 ## Interactive Mode (powered by Pi)
 
 Run `bkper agent` to start the embedded Bkper Agent TUI. Running `bkper` with no arguments shows CLI help.
@@ -134,794 +133,35 @@ https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#cli-referenc
 
 Pi-specific extensions are loaded from Pi extension folders (for example `.pi/extensions` and `~/.pi/agent/extensions`).
 
-<!-- Suggested showcase media: add a short terminal GIF here (bkper agent -> "Bkper Agent ready." -> one prompt). -->
-
 ---
 
 ## Data Management
 
-**Interact with books, accounts, transactions, and balances.**
-
-All data commands that operate within a book use `-b, --book <bookId>` to specify the book context.
-
-### Books
-
-Create and manage financial books with locale-specific settings.
+Manage books, accounts, transactions, and balances.
 
 ```bash
-# List all books
 bkper book list
-
-# Get book details
-bkper book get abc123
-
-# Create a book with Brazilian settings
-bkper book create --name "My Company" --fraction-digits 2 \
-  --date-pattern "dd/MM/yyyy" --decimal-separator COMMA \
-  --time-zone "America/Sao_Paulo"
-
-# Create a book with custom properties
-bkper book create --name "Project X" -p "code=PX001" -p "department=Engineering"
-
-# Update a book
-bkper book update abc123 --lock-date 2024-12-31
-```
-
-<details>
-<summary>Command reference</summary>
-
--   `book list` - List all books
-    -   `-q, --query <query>` - Search query
--   `book get <bookId>` - Get a book's details
--   `book create` - Create a new book
-    -   `--name <name>` - Book name (required)
-    -   `--fraction-digits <digits>` - Number of decimal places (`0`-`8`)
-    -   `--date-pattern <pattern>` - Date format pattern (`dd/MM/yyyy`, `MM/dd/yyyy`, or `yyyy/MM/dd`)
-    -   `--decimal-separator <separator>` - Decimal separator (`DOT` or `COMMA`)
-    -   `--time-zone <timezone>` - IANA time zone (e.g. `America/New_York`, `UTC`)
-    -   `--period <period>` - Period (`MONTH`, `QUARTER`, or `YEAR`)
-    -   `-p, --property <key=value>` - Set a property (repeatable)
--   `book update <bookId>` - Update a book
-    -   `--name <name>` - Book name
-    -   `--fraction-digits <digits>` - Number of decimal places (`0`-`8`)
-    -   `--date-pattern <pattern>` - Date format pattern (`dd/MM/yyyy`, `MM/dd/yyyy`, or `yyyy/MM/dd`)
-    -   `--decimal-separator <separator>` - Decimal separator (`DOT` or `COMMA`)
-    -   `--time-zone <timezone>` - IANA time zone identifier (e.g. `America/New_York`, `Europe/London`, `UTC`)
-    -   `--lock-date <date>` - Lock date in ISO format (`yyyy-MM-dd`, e.g. `2024-01-31`)
-    -   `--closing-date <date>` - Closing date in ISO format (`yyyy-MM-dd`)
-    -   `--period <period>` - Period (`MONTH`, `QUARTER`, or `YEAR`)
-    -   `-p, --property <key=value>` - Set a property (repeatable, e.g. `-p code=1010 -p branch=NYC`; empty value deletes the property)
-
-</details>
-
-### Accounts
-
-Manage your chart of accounts within a book.
-
-```bash
-# List all accounts
-bkper account list -b abc123
-
-# Get an account by name
-bkper account get "Bank Account" -b abc123
-
-# Create an asset account
-bkper account create -b abc123 --name "Bank Account" --type ASSET --groups "Current Assets"
-
-# Update an account
-bkper account update "Bank Account" -b abc123 --type LIABILITY
-
-# Archive an account
-bkper account update "Old Account" -b abc123 --archived true
-
-# Delete an account
-bkper account delete "Old Account" -b abc123
-```
-
-<details>
-<summary>Command reference</summary>
-
--   `account list -b <bookId>` - List accounts in a book
--   `account get <nameOrId> -b <bookId>` - Get an account
--   `account create -b <bookId>` - Create a new account
-    -   `--name <name>` - Account name (required)
-    -   `--type <type>` - Account type (`ASSET`, `LIABILITY`, `INCOMING`, `OUTGOING`)
-    -   `--description <description>` - Account description
-    -   `--groups <groups>` - Comma-separated group names
-    -   `-p, --property <key=value>` - Set a property (repeatable)
--   `account update <nameOrId> -b <bookId>` - Update an account
-    -   `--name <name>` - Account name
-    -   `--type <type>` - Account type (`ASSET`, `LIABILITY`, `INCOMING`, `OUTGOING`)
-    -   `--archived <true|false>` - Archive status
-    -   `-p, --property <key=value>` - Set a property (repeatable, merges with existing)
--   `account delete <nameOrId> -b <bookId>` - Delete an account
-
-</details>
-
-### Groups
-
-Organize accounts into hierarchical groups for structured reporting.
-
-```bash
-# List all groups (shows hierarchy)
-bkper group list -b abc123
-
-# Create a group
-bkper group create -b abc123 --name "Current Assets"
-
-# Create a child group
-bkper group create -b abc123 --name "Cash" --parent "Current Assets"
-
-# Update a group
-bkper group update "Cash" -b abc123 --hidden true
-
-# Delete a group
-bkper group delete "Cash" -b abc123
+bkper account list -b <bookId>
+bkper transaction list -b <bookId> -q 'on:2025' --format csv
+bkper balance list -b <bookId> -q 'on:2025-12-31' --format csv
 ```
 
-### Book setup guidance (important)
-
-When setting up a full Book or starter chart of accounts, prefer a hierarchical group structure by default.
-
-Create top-level groups first, then child groups with `--parent`, then accounts with `--groups`.
-
-Verify the resulting group hierarchy and account memberships before reporting success.
-
-Avoid using the same name for a Group and an Account in the same Book.
-
-<details>
-<summary>Command reference</summary>
-
--   `group list -b <bookId>` - List groups in a book
--   `group get <nameOrId> -b <bookId>` - Get a group
--   `group create -b <bookId>` - Create a new group
-    -   `--name <name>` - Group name (required)
-    -   `--parent <parent>` - Parent group name or ID
-    -   `--hidden` - Hide the group
-    -   `-p, --property <key=value>` - Set a property (repeatable)
--   `group update <nameOrId> -b <bookId>` - Update a group
-    -   `--name <name>` - Group name
-    -   `--hidden <true|false>` - Hide status
-    -   `-p, --property <key=value>` - Set a property (repeatable, merges with existing)
--   `group delete <nameOrId> -b <bookId>` - Delete a group
-
-</details>
-
-### Transactions
-
-Record, query, and manage financial transactions.
-
-```bash
-# Create a draft transaction
-bkper transaction create -b abc123 --description "Office supplies"
-
-# Create a complete transaction
-bkper transaction create -b abc123 --date 2025-01-15 --amount 100.50 \
-  --from "Bank Account" --to "Office Supplies" --description "Printer paper"
-
-# List transactions for a full year (on:YYYY)
-bkper transaction list -b abc123 -q 'on:2025'
-
-# List transactions for a month (on:YYYY-MM)
-bkper transaction list -b abc123 -q 'on:2025-01'
-
-# List with custom properties included
-bkper transaction list -b abc123 -q 'account:Sales' -p
-
-# Update a transaction
-bkper transaction update tx_456 -b abc123 --amount 120.00 --description "Printer paper (corrected)"
-
-# Post a draft transaction
-bkper transaction post tx_456 -b abc123
-
-# Check (reconcile) a transaction
-bkper transaction check tx_456 -b abc123
-
-# Trash a transaction
-bkper transaction trash tx_456 -b abc123
-
-# Merge two duplicate transactions
-bkper transaction merge tx_123 tx_456 -b abc123
-```
-
-<details>
-<summary>Command reference</summary>
-
--   `transaction list -b <bookId> -q <query>` - List transactions matching a query (auto-paginates through all results)
-    -   `-p, --properties` - Include custom properties in the output
--   `transaction create -b <bookId>` - Create a transaction
-    -   `--date <date>` - Transaction date
-    -   `--amount <amount>` - Transaction amount
-    -   `--description <description>` - Transaction description
-    -   `--from <from>` - Credit account (source)
-    -   `--to <to>` - Debit account (destination)
-    -   `--url <url>` - URL (repeatable)
-    -   `--remote-id <remoteId>` - Remote ID (repeatable)
-    -   `-p, --property <key=value>` - Set a property (repeatable, empty value deletes)
--   `transaction update [transactionId] -b <bookId>` - Update a transaction (or batch update via stdin)
-    -   `--date <date>` - Transaction date
-    -   `--amount <amount>` - Transaction amount
-    -   `--description <description>` - Transaction description
-    -   `--from <from>` - Credit account (source)
-    -   `--to <to>` - Debit account (destination)
-    -   `--url <url>` - URL (repeatable, replaces all)
-    -   `--update-checked` - Also update checked transactions
-    -   `-p, --property <key=value>` - Set a property (repeatable, empty value deletes)
--   `transaction post <id> -b <bookId>` - Post a draft transaction
--   `transaction check <id> -b <bookId>` - Check a transaction
--   `transaction trash <id> -b <bookId>` - Trash a transaction
--   `transaction merge <id1> <id2> -b <bookId>` - Merge two transactions
-
-</details>
-
-### Balances
-
-Query account balances and group totals.
-
-```bash
-# List balances for a specific date (point-in-time)
-bkper balance list -b abc123 -q 'on:2025-12-31'
-
-# Monthly balance evolution of one account during 2025
-bkper balance list -b abc123 -q "account:'<accountName>' after:2025-01-01 before:2026-01-01 by:m" --expanded 2
-```
-
-<details>
-<summary>Command reference</summary>
-
--   `balance list -b <bookId> -q <query>` - List balances
-    -   `--expanded <level>` - Expand groups to specified depth (`0`+)
-
-</details>
-
-### Query semantics (transactions and balances)
-
-Use the same query language across Bkper web app, CLI, and Google Sheets integrations.
-
--   `on:` supports different granularities:
-    -   `on:2025` → full year
-    -   `on:2025-01` → full month
-    -   `on:2025-01-31` → specific day
--   `after:` is **inclusive** and `before:` is **exclusive**.
-    -   Full year 2025: `after:2025-01-01 before:2026-01-01`
--   In shell commands, wrap queries with Bkper date variables (`$d`, `$m`, `$y`) in single quotes to avoid shell expansion.
-    -   Example: `bkper transaction list -b abc123 -q 'after:$m-3 before:$m+1'`
-    -   If the query already needs single quotes inside (for example, `account:'Brex Cash'`), keep double quotes and escape `$`: `-q "account:'Brex Cash' after:\$m-3 before:\$m+1"`
--   For point-in-time statements (typically permanent accounts `ASSET`/`LIABILITY`), prefer `on:` or `before:`.
--   For activity statements over a period (typically non-permanent accounts `INCOMING`/`OUTGOING`), prefer `after:` + `before:`.
--   For statement-level analysis, prefer filtering by the report root group. Root names vary by book.
-
-```bash
-# Balance Sheet snapshot (point-in-time)
-bkper balance list -b abc123 -q "group:'<balanceSheetRootGroup>' before:2026-01-01"
-
-# P&L activity over 2025
-bkper balance list -b abc123 -q "group:'<profitAndLossRootGroup>' after:2025-01-01 before:2026-01-01"
-```
-
-### Collections
-
-Organize books into collections.
-
-```bash
-# Create a collection
-bkper collection create --name "My Collection"
-
-# Add books to a collection
-bkper collection add-book col_789 -b abc123 -b def456
-
-# List all collections
-bkper collection list
-
-# Remove a book from a collection
-bkper collection remove-book col_789 -b abc123
-
-# Delete a collection
-bkper collection delete col_789
-```
-
-<details>
-<summary>Command reference</summary>
-
--   `collection list` - List all collections
--   `collection get <collectionId>` - Get a collection
--   `collection create` - Create a new collection
-    -   `--name <name>` - Collection name (required)
--   `collection update <collectionId>` - Update a collection
-    -   `--name <name>` - Collection name
--   `collection delete <collectionId>` - Delete a collection
--   `collection add-book <collectionId>` - Add books to a collection
-    -   `-b, --book <bookId>` - Book ID (repeatable)
--   `collection remove-book <collectionId>` - Remove books from a collection
-    -   `-b, --book <bookId>` - Book ID (repeatable)
-
-</details>
+→ [Full Data Management reference](https://github.com/bkper/bkper-cli/blob/main/docs/data-management.md)
 
-### Output Format
-
-All commands support three output formats via the `--format` global flag:
-
-| Format | Flag                       | Best for                                    |
-| ------ | -------------------------- | ------------------------------------------- |
-| Table  | `--format table` (default) | Human reading in the terminal               |
-| JSON   | `--format json`            | Programmatic access, single-item detail     |
-| CSV    | `--format csv`             | LLM consumption, spreadsheets, list reports |
-
-```bash
-# Table output (default)
-bkper account list -b abc123
-
-# JSON output
-bkper account list -b abc123 --format json
-
-# CSV output -- raw data, no truncation, RFC 4180
-bkper account list -b abc123 --format csv
-```
-
-**CSV output details:**
-
--   **RFC 4180 compliant** -- proper quoting, CRLF line endings, no truncation
--   **All metadata included** -- IDs, properties, hidden properties, URLs, and timestamps are enabled
--   **Raw values** -- dates stay in ISO format, numbers are unformatted (no locale formatting)
--   **Single-item commands** (e.g. `account get`, `transaction create`) fall back to JSON since CSV adds no value for non-tabular data
-
-**LLM-first output guidance (important):**
-
-When command output will be loaded into an LLM context (chat, prompt, memory, or agent reasoning), prefer:
-
--   **`--format csv` for list commands** (`balance list`, `transaction list`, `account list`, etc.).
--   **`--format json` for single-item commands** (`get`, `create`, `update`) and CLI-to-CLI pipelines.
-
-CSV is significantly more token-efficient than JSON for tabular data, and for wide balance outputs it can reduce token usage by up to **95%**.
-
-**Quick rule:**
-
--   **LLM consumption of lists/reports** → CSV
--   **Programmatic processing / pipelines** → JSON
--   **Human terminal reading** → Table
-
-### Batch Operations & Piping
-
-Write commands (`account create`, `transaction create`) accept JSON data piped via stdin for batch operations. The `transaction update` command also accepts stdin for batch updates. The input format follows the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts) exactly -- a single JSON object or an array of objects.
-
-```bash
-# Create transactions
-echo '[{
-  "date": "2025-01-15",
-  "amount": "100.50",
-  "creditAccount": {"name": "Bank Account"},
-  "debitAccount": {"name": "Office Supplies"},
-  "description": "Printer paper",
-  "properties": {"invoice": "INV-001"}
-}]' | bkper transaction create -b abc123
-
-# Create accounts
-echo '[{"name":"Cash","type":"ASSET"},{"name":"Revenue","type":"INCOMING"}]' | \
-  bkper account create -b abc123
-
-# Pipe from a script
-python export_bank.py | bkper transaction create -b abc123
-```
-
-The input follows the exact `bkper.Transaction` or `bkper.Account` type from the [Bkper API Types](https://raw.githubusercontent.com/bkper/bkper-api-types/refs/heads/master/index.d.ts). Custom properties go inside the `properties` object.
-
-Groups are created explicitly with `bkper group create --name` and optional `--parent` so hierarchy stays deterministic during setup.
-
-The `--property` CLI flag can override or delete properties from the stdin payload:
-
-```bash
-echo '[{"name":"Cash","type":"ASSET"}]' | \
-  bkper account create -b abc123 -p "region=LATAM"
-```
-
-**Batch output:** results are output as a flat JSON array, matching the same format as list commands:
-
-```bash
-bkper account create -b abc123 < accounts.json
-# Output: [{"id":"acc-abc","name":"Cash",...}, {"id":"acc-def","name":"Revenue",...}]
-```
-
-**Piping between commands:**
-
-For resources that support stdin creation, JSON output can be piped directly into create or update commands:
-
-```bash
-# Copy all accounts from one book to another
-bkper account list -b $BOOK_A --format json | bkper account create -b $BOOK_B
-
-# Copy transactions matching a query
-bkper transaction list -b $BOOK_A -q 'after:2025-01-01' --format json | \
-  bkper transaction create -b $BOOK_B
-
-# Clone accounts, then transactions
-bkper account list -b $SOURCE --format json | bkper account create -b $DEST
-bkper transaction list -b $SOURCE -q 'after:2025-01-01' --format json | \
-  bkper transaction create -b $DEST
-
-# Batch update: list transactions, modify, and pipe back to update
-bkper transaction list -b $BOOK -q 'after:2025-01-01' --format json | \
-  jq '[.[] | .description = "Updated: " + .description]' | \
-  bkper transaction update -b $BOOK
-
-# Batch update: add a property to all matching transactions
-bkper transaction list -b $BOOK -q 'account:Expenses' --format json | \
-  bkper transaction update -b $BOOK -p "reviewed=true"
-
-# Batch update checked transactions
-bkper transaction list -b $BOOK -q 'is:checked after:2025-01-01' --format json | \
-  bkper transaction update -b $BOOK --update-checked -p "migrated=true"
-```
-
-<details>
-<summary>Writable fields reference</summary>
-
-Only the fields below are meaningful when creating or updating resources via stdin. For batch updates, items must include an `id` field. Other read-only fields (`createdAt`, `updatedAt`, etc.) are ignored.
-
-**Transaction** (`bkper.Transaction`)
-
-| Field           | Type                               | Notes                                         |
-| --------------- | ---------------------------------- | --------------------------------------------- |
-| `id`            | `string`                           | Required for batch updates, ignored on create |
-| `date`          | `string`                           | ISO format `yyyy-MM-dd`                       |
-| `amount`        | `string`                           | Decimal format `####.##` (string, not number) |
-| `creditAccount` | `{"name":"..."}` or `{"id":"..."}` | Reference to an existing account              |
-| `debitAccount`  | `{"name":"..."}` or `{"id":"..."}` | Reference to an existing account              |
-| `description`   | `string`                           | Free-text description                         |
-| `urls`          | `string[]`                         | Attached URLs (e.g. receipts)                 |
-| `remoteIds`     | `string[]`                         | External IDs to prevent duplicates            |
-| `properties`    | `{"key": "value", ...}`            | Custom key/value properties                   |
-
-**Account** (`bkper.Account`)
-
-| Field        | Type                    | Notes                                              |
-| ------------ | ----------------------- | -------------------------------------------------- |
-| `name`       | `string`                | Account name (required)                            |
-| `type`       | `string`                | `ASSET`, `LIABILITY`, `INCOMING`, or `OUTGOING`    |
-| `credit`     | `boolean`               | Credit nature (`true`) or debit (`false`)          |
-| `archived`   | `boolean`               | Archive the account on creation                    |
-| `permanent`  | `boolean`               | Permanent accounts (e.g. bank accounts, customers) |
-| `groups`     | `[{"name":"..."}, ...]` | Groups to assign by name or id                     |
-| `properties` | `{"key": "value", ...}` | Custom key/value properties                        |
-
-</details>
 
 ---
 
 ## App Management
 
-**Build, deploy, and manage Bkper apps.**
-
-### Development Workflow
+Build, deploy, and manage Bkper apps.
 
 ```bash
-# Scaffold a new app from the template
 bkper app init my-app
-
-# Start the worker runtime (Miniflare + tunnel + file watching)
-# In your project, use "npm run dev" to run both Vite and workers concurrently
 bkper app dev
-
-# Build worker bundles (web server + events handler)
-# In your project, use "npm run build" to build both client (Vite) and workers
-bkper app build
-
-# Sync configuration and deploy to production
 bkper app sync && bkper app deploy
-
-# Deploy to development environment
-bkper app deploy --preview
-
-# Deploy only the events handler
-bkper app deploy --events
-
-# Check deployment status
-bkper app status
 ```
 
-> **Note:** `bkper app dev` runs the worker runtime only — Miniflare, file watching, and the Cloudflare tunnel. The Vite client dev server is configured in the project's `vite.config.ts` and run separately. The project template composes both via `npm run dev` using `concurrently`.
-
-### Install Apps on Books
-
-```bash
-# Install an app on a book
-bkper app install my-app -b abc123
-
-# Uninstall an app from a book
-bkper app uninstall my-app -b abc123
-```
-
-### Secrets
-
-```bash
-# Store a secret (prompts for value)
-bkper app secrets put API_KEY
-
-# List all secrets
-bkper app secrets list
-
-# Delete a secret
-bkper app secrets delete API_KEY
-```
-
-### Configuration
-
-Apps are configured via a `bkper.yaml` file in the project root. See the complete **[bkper.yaml reference]** below.
-
-<details>
-<summary>bkper.yaml reference</summary>
-
-```yaml
-# =============================================================================
-# bkper.yaml Reference
-# =============================================================================
-# This file documents all available configuration options for Bkper Apps.
-# Copy the fields you need to your app's bkper.yaml file.
-#
-# For a minimal working template, see:
-# https://github.com/bkper/bkper-app-template
-# =============================================================================
-
-# -----------------------------------------------------------------------------
-# APP IDENTITY
-# -----------------------------------------------------------------------------
-# The app id is permanent and cannot be changed after creation.
-# Use lowercase letters, numbers, and hyphens only.
-id: my-app
-
-# Display name shown in the Bkper UI
-name: My App
-
-# Brief description of what the app does
-description: A Bkper app that does something useful
-
-# -----------------------------------------------------------------------------
-# BRANDING
-# -----------------------------------------------------------------------------
-# App logo for light mode (SVG recommended, PNG/JPG supported)
-logoUrl: https://example.com/logo.svg
-
-# App logo for dark mode (required for proper theming)
-logoUrlDark: https://example.com/logo-dark.svg
-
-# App website or documentation URL
-website: https://example.com
-
-# -----------------------------------------------------------------------------
-# OWNERSHIP
-# -----------------------------------------------------------------------------
-# Developer/company name
-ownerName: Your Name
-
-# Owner's logo/avatar URL
-ownerLogoUrl: https://example.com/owner-logo.png
-
-# Owner's website
-ownerWebsite: https://yoursite.com
-
-# Source code repository URL
-repoUrl: https://github.com/you/my-app
-
-# Whether the repository is private
-repoPrivate: true
-
-# Mark as deprecated (hides from app listings, existing installs continue working)
-deprecated: false
-
-# -----------------------------------------------------------------------------
-# ACCESS CONTROL
-# -----------------------------------------------------------------------------
-# Who can update the app configuration and deploy new versions.
-# Comma-separated list of Bkper usernames (not emails).
-# Supports domain wildcards for registered custom domains: *@yourdomain.com
-developers: victor, aldo, *@bkper.com
-
-# Who can install and use the app.
-# Same format as developers. Leave empty for public apps.
-users: maria, *@acme.com
-
-# -----------------------------------------------------------------------------
-# MENU INTEGRATION (optional)
-# -----------------------------------------------------------------------------
-# When configured, adds a menu item to Bkper's "More" menu.
-# Clicking opens a popup with the specified URL.
-
-# Production menu URL (supports variable substitution)
-menuUrl: https://${id}.bkper.app?bookId=${book.id}
-
-# Development menu URL (used when developer runs the app)
-menuUrlDev: http://localhost:8787?bookId=${book.id}
-
-# Custom menu text (defaults to app name if not specified)
-menuText: Open My App
-
-# Popup dimensions in pixels
-menuPopupWidth: 500
-menuPopupHeight: 300
-
-# -----------------------------------------------------------------------------
-# Menu URL Variables
-# -----------------------------------------------------------------------------
-# The following variables can be used in menuUrl and menuUrlDev:
-#
-# ${book.id}                - Current book ID
-# ${book.properties.xxx}    - Book property value (replace xxx with property key)
-# ${account.id}             - Selected account ID (in account context)
-# ${account.properties.xxx} - Account property value
-# ${group.id}               - Selected group ID (in group context)
-# ${group.properties.xxx}   - Group property value
-# ${transactions.ids}       - Comma-separated selected transaction IDs
-# ${transactions.query}     - Current search query
-# -----------------------------------------------------------------------------
-
-# -----------------------------------------------------------------------------
-# EVENT HANDLING (optional)
-# -----------------------------------------------------------------------------
-# When configured, Bkper calls your webhook URL when subscribed events occur.
-
-# Production webhook URL
-webhookUrl: https://${id}.bkper.app/events
-
-# Development webhook URL (auto-updated by bkper app dev)
-webhookUrlDev: https://<random>.trycloudflare.com/events
-
-# API version for event payloads
-apiVersion: v5
-
-# Events to subscribe to (remove events you don't need)
-events:
-    # Transaction
-    - TRANSACTION_CREATED
-    - TRANSACTION_POSTED
-    - TRANSACTION_CHECKED
-    - TRANSACTION_UNCHECKED
-    - TRANSACTION_UPDATED
-    - TRANSACTION_DELETED
-    - TRANSACTION_RESTORED
-    # Account
-    - ACCOUNT_CREATED
-    - ACCOUNT_UPDATED
-    - ACCOUNT_DELETED
-    # Group
-    - GROUP_CREATED
-    - GROUP_UPDATED
-    - GROUP_DELETED
-    # File
-    - FILE_CREATED
-    - FILE_UPDATED
-    # Query
-    - QUERY_CREATED
-    - QUERY_UPDATED
-    - QUERY_DELETED
-    # Comment
-    - COMMENT_CREATED
-    - COMMENT_DELETED
-    # Collaborator
-    - COLLABORATOR_ADDED
-    - COLLABORATOR_UPDATED
-    - COLLABORATOR_REMOVED
-    # Integration
-    - INTEGRATION_CREATED
-    - INTEGRATION_UPDATED
-    - INTEGRATION_DELETED
-    # Book
-    - BOOK_CREATED
-    - BOOK_UPDATED
-    - BOOK_DELETED
-    - BOOK_AUDITED
-
-# -----------------------------------------------------------------------------
-# FILE PATTERNS (optional)
-# -----------------------------------------------------------------------------
-# For file processing apps. When a file matching these patterns is uploaded,
-# a FILE_CREATED event is triggered with the file content.
-filePatterns:
-    - '*.ofx'
-    - '*.csv'
-
-# -----------------------------------------------------------------------------
-# PROPERTIES SCHEMA (optional)
-# -----------------------------------------------------------------------------
-# Defines autocomplete suggestions for custom properties in the Bkper UI.
-# Helps users discover and use the correct property keys/values for your app.
-propertiesSchema:
-    book:
-        keys:
-            - my_app_enabled
-            - my_app_config
-        values:
-            - 'true'
-            - 'false'
-    group:
-        keys:
-            - my_app_category
-        values:
-            - category_a
-            - category_b
-    account:
-        keys:
-            - my_app_sync_id
-    transaction:
-        keys:
-            - my_app_reference
-
-# -----------------------------------------------------------------------------
-# DEPLOYMENT CONFIGURATION (optional)
-# -----------------------------------------------------------------------------
-# For apps deployed to Bkper's Workers for Platforms infrastructure.
-deployment:
-    # Web handler (serves UI and API)
-    web:
-        bundle: packages/web/server/dist
-        # assets: packages/web/client/dist  # Static assets (when supported)
-
-    # Events handler (processes webhooks)
-    events:
-        bundle: packages/events/dist
-
-    # Platform services available to your app (one per type, auto-provisioned)
-    # See: https://developers.cloudflare.com/kv/
-    services:
-        - KV # Key-value storage
-```
-
-</details>
-
-**Environment variables:**
-
--   `BKPER_API_KEY` -- Optional. If not set, uses the Bkper API proxy with a managed API key. Set it for direct API access with your own quotas. Follow [these steps](https://bkper.com/docs/#rest-api-enabling) to enable.
-
-<details>
-<summary>Command reference</summary>
-
-#### Authentication
-
--   `auth login` - Authenticate with Bkper, storing credentials locally
--   `auth logout` - Revoke the stored refresh token and clear local credentials
--   `auth token` - Print the current OAuth access token to stdout (requires prior login)
-
-#### Agent
-
--   `agent` - Start the interactive Bkper Agent
--   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
-
-#### App Lifecycle
-
--   `app init <name>` - Scaffold a new app from the template
--   `app list` - List all apps you have access to
--   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration (URLs, description) to Bkper API
--   `app build` - Build worker bundles for deployment
--   `app deploy` - Deploy built artifacts to Cloudflare Workers for Platforms
-    -   `-p, --preview` - Deploy to preview environment
-    -   `--events` - Deploy events handler instead of web handler
--   `app status` - Show deployment status
--   `app undeploy` - Remove app from platform
-    -   `-p, --preview` - Remove from preview environment
-    -   `--events` - Remove events handler instead of web handler
-    -   `--delete-data` - Permanently delete all associated data (requires confirmation)
-    -   `--force` - Skip confirmation prompts (use with `--delete-data` for automation)
--   `app dev` - Start the worker runtime for local development
-    -   `--sp, --server-port <port>` - Server simulation port (default: `8787`)
-    -   `--ep, --events-port <port>` - Events handler port (default: `8791`)
-    -   `-w, --web` - Run only the web handler
-    -   `-e, --events` - Run only the events handler
-
-> **Note:** `sync` and `deploy` are independent operations. Use `sync` to update your app's URLs in Bkper (required for webhooks and menu integration). Use `deploy` to push code to Cloudflare. For a typical deployment workflow, run both: `bkper app sync && bkper app deploy`
-
-#### App Installation
-
--   `app install <appId> -b <bookId>` - Install an app on a book
--   `app uninstall <appId> -b <bookId>` - Uninstall an app from a book
-
-#### Secrets Management
-
--   `app secrets put <name>` - Store a secret
-    -   `-p, --preview` - Set in preview environment
--   `app secrets list` - List all secrets
-    -   `-p, --preview` - List from preview environment
--   `app secrets delete <name>` - Delete a secret
-    -   `-p, --preview` - Delete from preview environment
-
-</details>
+→ [Full App Management reference](https://github.com/bkper/bkper-cli/blob/main/docs/app-management.md)
 
 ---