bkper 4.12.21 → 4.12.23

package/lib/docs/app-management.md

@@ -7,6 +7,58 @@ Build, deploy, and manage Bkper apps using the `bkper` CLI.
 
 ---
 
+## Verification Workflow
+
+When scaffolding, developing, or deploying an app, verify each step before proceeding. This prevents broken deployments and silent failures.
+
+### 1. Init
+```bash
+bkper app init my-app
+```
+Verify:
+- `packages/web/client/`, `packages/web/server/`, `packages/events/`, and `packages/shared/` exist
+- `bkper.yaml` has `id`, `name`, `description`, and `developers`
+- `package.json` scripts include `dev` and `build`
+
+### 2. Develop
+```bash
+npm run dev
+```
+Verify:
+- Web server responds: `curl http://localhost:8787` (or the port you configured)
+- Client dev server is reachable if running separately
+- Events tunnel URL is printed in terminal and registered in Bkper (check `webhookUrlDev` in app settings)
+- If any handler fails to start, fix before writing code
+
+### 3. Build
+```bash
+npm run build
+```
+Verify:
+- `dist/web/server/` contains the web worker bundle
+- `dist/events/` contains the events handler bundle
+- No build errors in terminal output
+
+### 4. Sync & Deploy
+```bash
+bkper app sync && bkper app deploy
+```
+Verify:
+- `bkper app status` shows the deployed version
+- URLs in `bkper.yaml` match the deployed domain (`https://{appId}.bkper.app`)
+
+### 5. Validate
+```bash
+bkper app install <appId> -b <bookId>
+```
+Verify:
+- Menu appears in the book's "More" menu (if configured)
+- Trigger a subscribed event in the book
+- Check the Bkper activity stream for the handler response
+- If the handler writes back to the book, confirm loop prevention is in place (check `event.agent.id`)
+
+---
+
 ## Development Workflow
 
 ```bash
@@ -54,13 +106,13 @@ bkper app uninstall my-app -b abc123
 
 ```bash
 # Store a secret (prompts for value)
-bkper app secrets put API_KEY
+bkper app secrets put EXTERNAL_SERVICE_TOKEN
 
 # List all secrets
 bkper app secrets list
 
 # Delete a secret
-bkper app secrets delete API_KEY
+bkper app secrets delete EXTERNAL_SERVICE_TOKEN
 ```
 
 ---

package/lib/docs/index.md

@@ -4,6 +4,7 @@ Reference docs for Bkper tasks. Load only the specific doc(s) relevant to the ta
 
 - **data-management.md** — CLI reference for managing financial data: books, accounts, groups, transactions, per-account balance queries, query operators (on:, after:, before:, account:, group:), output formats (table/json/csv), batch operations via stdin/piping, collections.
 - **app-management.md** — CLI reference for building and deploying Bkper apps: dev/build/deploy workflow, app install/uninstall, secrets management, bkper.yaml configuration reference (identity, branding, events, menu integration, deployment).
+- **app-building.md** — Full app-building reference: architecture (packages, client/server/events), development loop, event handlers, deployment patterns, the Bkper Platform, and self-hosted alternatives. Includes authentication patterns for web clients (`@bkper/web-auth`), event handlers (`bkper-oauth-token` headers), and local development. Load this for scaffolding apps, understanding app structure, or debugging the dev/build/deploy lifecycle.
 - **financial-statements.md** — Step-by-step workflow for aggregate financial reports (balance sheet, P&L): root group discovery, query patterns, date semantics (before: vs after:+before:), common mistakes to avoid.
 - **bkper-js.md** — bkper-js Node.js/browser SDK: Bkper, Book, Account, Transaction, Group, Balance classes, all methods, getBalancesReport, OAuth configuration, library setup.
 - **bkper-api-types.md** — Bkper REST API TypeScript interfaces: Book, Account, Transaction, Group, Balance, Collection — field names and types used by the API and bkper-js.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.12.21",
+    "version": "4.12.23",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"
@@ -27,7 +27,8 @@
     "scripts": {
         "clean": "rm -rf ./lib & rm -rf ./node_modules & wait",
         "sync:docs": "bun ./scripts/sync-docs.ts",
-        "prebuild": "bun install && bun sync:docs",
+        "generate:skill": "bun ./scripts/generate-skill.ts",
+        "prebuild": "bun install && bun sync:docs && bun generate:skill",
         "build": "run-s build:clean build:compile build:copy-docs",
         "build:clean": "gts clean && rimraf temp",
         "build:compile": "tsc",
@@ -50,7 +51,7 @@
         "upgrade:api": "bun update @bkper/bkper-api-types --latest && bun update bkper-js --latest"
     },
     "dependencies": {
-        "@mariozechner/pi-coding-agent": "0.69.0",
+        "@mariozechner/pi-coding-agent": "0.70.5",
         "bkper-js": "^2.32.2",
         "commander": "^13.1.0",
         "dotenv": "^8.2.0",