bkper 4.11.3 → 4.12.0

package/README.md

@@ -5,7 +5,7 @@
 
 A unified **interface for [Bkper](https://bkper.com)**. Use `bkper` in two complementary modes:
 
--   **Interactive mode** — run `bkper` with no arguments to open the agent TUI
+-   **Interactive mode** — run `bkper agent` to open the Bkper Agent TUI
 -   **Command mode** — run `bkper <command>` for explicit CLI workflows, scripts, and automation
 
 With one tool, you can build and deploy Bkper apps, and manage financial data -- books, accounts, transactions, and balances.
@@ -45,10 +45,15 @@ bkper auth login
 ### Start using bkper
 
 ```bash
-# Interactive mode (agent TUI)
+# Show CLI help
 bkper
 ```
 
+```bash
+# Interactive mode (agent TUI)
+bkper agent
+```
+
 ```bash
 # Command mode (explicit command)
 bkper book list
@@ -79,7 +84,7 @@ curl -s -H "Authorization: Bearer $TOKEN" \
 
 ## Interactive Mode (powered by Pi)
 
-When you run `bkper` with no arguments in an interactive terminal, bkper starts the embedded agent TUI.
+Run `bkper agent` to start the embedded Bkper Agent TUI. Running `bkper` with no arguments shows CLI help.
 
 Bkper's agent mode is intentionally a **thin wrapper** around [Pi][Pi]:
 
@@ -95,25 +100,30 @@ On each agent startup, bkper performs a background CLI auto-update check (same b
 Use Pi CLI features directly through bkper:
 
 ```bash
-bkper agent -- <pi-args>
+bkper agent <pi-args>
 ```
 
+If no Pi arguments are provided, `bkper agent` starts the interactive Bkper Agent experience.
+If Pi arguments are provided, everything after `bkper agent` is passed through to Pi.
+
 Examples:
 
 ```bash
-bkper agent -- -p "Summarize this repository"
-bkper agent -- --model openai/gpt-4o -c
-bkper agent -- install <pi-package-source>
+bkper agent -p "Summarize this repository"
+bkper agent --model openai/gpt-4o -c
+bkper agent install <pi-package-source>
+bkper agent --help
 ```
 
-`bkper agent` keeps Bkper defaults (including Bkper system prompt) unless you explicitly pass `--system-prompt`.
+`bkper agent` keeps Bkper defaults (including the Bkper system prompt) unless you explicitly pass `--system-prompt`.
+Use `bkper help agent` for the Bkper CLI command help, and `bkper agent --help` for Pi help.
 
 For all available passthrough flags and commands, see the Pi CLI reference:
 https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#cli-reference
 
 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 -> "Bkper Agent ready." -> one prompt). -->
+<!-- Suggested showcase media: add a short terminal GIF here (bkper agent -> "Bkper Agent ready." -> one prompt). -->
 
 ---
 
@@ -855,9 +865,10 @@ deployment:
 -   `auth logout` - Remove stored credentials
 -   `auth token` - Print the current OAuth access token to stdout
 
-#### Agent Bridge (Pi passthrough)
+#### Agent
 
--   `agent -- <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
+-   `agent` - Start the interactive Bkper Agent
+-   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
 
 #### App Lifecycle
 
@@ -917,7 +928,8 @@ Bkper.setConfig({
 
 Releases are published by GitHub Actions (Trusted Publisher with OIDC), not from local machines.
 
--   Merge a PR into `main` with one release label: `release:patch`, `release:minor`, or `release:major`
--   On each `main` push, the delivery workflow checks the merged PR associated with that commit, computes the next version from the latest release tag, publishes to npm, and pushes the new tag
+-   Add one release label to a PR targeting `main`: `release:patch`, `release:minor`, or `release:major`
+-   Before merge, the PR version bump workflow updates `package.json` on the PR branch to the next version derived from the latest release tag
+-   On each `main` push, the delivery workflow checks the merged PR label, verifies `package.json` already contains the expected next version, publishes to npm, and pushes the new tag
 -   Without a release label, publish is skipped
 -   Dependabot Pi update PRs are automatically labeled `release:patch` and set to GitHub native auto-merge when repo auto-merge and required checks are enabled

package/lib/agent/cli-dispatch.d.ts

@@ -1,6 +1,2 @@
-export interface CliDispatchEnvironment {
-    stdinIsTTY: boolean;
-    stdoutIsTTY: boolean;
-}
-export declare function shouldStartAgentMode(argv: string[], environment?: CliDispatchEnvironment): boolean;
+export declare function shouldRunAgentCommand(argv: string[]): boolean;
 //# sourceMappingURL=cli-dispatch.d.ts.map

package/lib/agent/cli-dispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-dispatch.d.ts","sourceRoot":"","sources":["../../src/agent/cli-dispatch.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,sBAAsB;IACnC,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAChC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,GAAE,sBAGZ,GACF,OAAO,CAET"}
+{"version":3,"file":"cli-dispatch.d.ts","sourceRoot":"","sources":["../../src/agent/cli-dispatch.ts"],"names":[],"mappings":"AAAA,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAE7D"}

package/lib/agent/cli-dispatch.js

@@ -1,7 +1,4 @@
-export function shouldStartAgentMode(argv, environment = {
-    stdinIsTTY: process.stdin.isTTY === true,
-    stdoutIsTTY: process.stdout.isTTY === true,
-}) {
-    return argv.length === 2 && environment.stdinIsTTY && environment.stdoutIsTTY;
+export function shouldRunAgentCommand(argv) {
+    return argv[2] === 'agent';
 }
 //# sourceMappingURL=cli-dispatch.js.map

package/lib/agent/cli-dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-dispatch.js","sourceRoot":"","sources":["../../src/agent/cli-dispatch.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,oBAAoB,CAChC,IAAc,EACd,cAAsC;IAClC,UAAU,EAAE,OAAO,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI;IACxC,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;CAC7C;IAED,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,WAAW,CAAC,UAAU,IAAI,WAAW,CAAC,WAAW,CAAC;AAClF,CAAC"}
+{"version":3,"file":"cli-dispatch.js","sourceRoot":"","sources":["../../src/agent/cli-dispatch.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,qBAAqB,CAAC,IAAc;IAChD,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;AAC/B,CAAC"}

package/lib/cli.js

@@ -19,15 +19,20 @@ import { registerTransactionCommands } from './commands/transactions/register.js
 import { registerBalanceCommands } from './commands/balances/register.js';
 import { registerCollectionCommands } from './commands/collections/register.js';
 import { registerUpgradeCommand } from './commands/upgrade.js';
-import { registerAgentCommands } from './commands/agent-command.js';
+import { registerAgentCommands, runAgentCommand } from './commands/agent-command.js';
+import { shouldRunAgentCommand } from './agent/cli-dispatch.js';
 import { VERSION, autoUpgrade } from './upgrade/index.js';
-import { shouldStartAgentMode } from './agent/cli-dispatch.js';
-import { runAgentMode } from './agent/run-agent-mode.js';
 function main() {
     return __awaiter(this, void 0, void 0, function* () {
-        if (shouldStartAgentMode(process.argv)) {
-            yield runAgentMode();
-            return;
+        if (shouldRunAgentCommand(process.argv)) {
+            try {
+                yield runAgentCommand(process.argv.slice(3));
+                return;
+            }
+            catch (err) {
+                console.error('Error running agent command:', err);
+                process.exit(1);
+            }
         }
         // Version
         program.version(VERSION, '-v, --version');

package/lib/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;AAEA,OAAO,eAAe,CAAC,CAAC,sDAAsD;AAE9E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,SAAe,IAAI;;QACf,IAAI,oBAAoB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,YAAY,EAAE,CAAC;YACrB,OAAO;QACX,CAAC;QAED,UAAU;QACV,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAE1C,+BAA+B;QAC/B,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,oCAAoC,EAAE,OAAO,CAAC,CAAC;QACnF,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,0CAA0C,CAAC,CAAC;QAErE,gBAAgB;QAChB,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE9B,oBAAoB;QACpB,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACjC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC/B,2BAA2B,CAAC,OAAO,CAAC,CAAC;QACrC,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;QAEpC,uBAAuB;QACvB,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAE/B,kBAAkB;QAClB,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAEhC,4EAA4E;QAC5E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,CAAC;YACxC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;CAAA;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IACf,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";;;;;;;;;;AAEA,OAAO,eAAe,CAAC,CAAC,sDAAsD;AAE9E,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AACrF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1D,SAAe,IAAI;;QACf,IAAI,qBAAqB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC;gBACD,MAAM,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC7C,OAAO;YACX,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;gBACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACpB,CAAC;QACL,CAAC;QAED,UAAU;QACV,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAE1C,+BAA+B;QAC/B,OAAO,CAAC,MAAM,CAAC,mBAAmB,EAAE,oCAAoC,EAAE,OAAO,CAAC,CAAC;QACnF,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,0CAA0C,CAAC,CAAC;QAErE,gBAAgB;QAChB,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAE9B,oBAAoB;QACpB,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC7B,oBAAoB,CAAC,OAAO,CAAC,CAAC;QAC9B,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACjC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAC/B,2BAA2B,CAAC,OAAO,CAAC,CAAC;QACrC,uBAAuB,CAAC,OAAO,CAAC,CAAC;QACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;QAEpC,uBAAuB;QACvB,qBAAqB,CAAC,OAAO,CAAC,CAAC;QAE/B,kBAAkB;QAClB,sBAAsB,CAAC,OAAO,CAAC,CAAC;QAEhC,4EAA4E;QAC5E,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,wBAAwB,EAAE,CAAC;YACxC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAClC,CAAC;QAED,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;CAAA;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE;IACf,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AACpB,CAAC,CAAC,CAAC"}

package/lib/commands/agent-command.d.ts

@@ -1,6 +1,8 @@
 import type { Command } from 'commander';
 export interface AgentCommandDependencies {
     runPi: (args: string[]) => Promise<void>;
+    runInteractiveMode: () => Promise<void>;
 }
-export declare function registerAgentCommands(program: Command, dependencies?: AgentCommandDependencies): void;
+export declare function runAgentCommand(piArgs: string[], dependencies?: AgentCommandDependencies): Promise<void>;
+export declare function registerAgentCommands(program: Command): void;
 //# sourceMappingURL=agent-command.d.ts.map

package/lib/commands/agent-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-command.d.ts","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIzC,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAoBD,wBAAgB,qBAAqB,CACjC,OAAO,EAAE,OAAO,EAChB,YAAY,GAAE,wBAAsD,GACrE,IAAI,CAeN"}
+{"version":3,"file":"agent-command.d.ts","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,kBAAkB,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAqBD,wBAAsB,eAAe,CACjC,MAAM,EAAE,MAAM,EAAE,EAChB,YAAY,GAAE,wBAAsD,GACrE,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAM5D"}

package/lib/commands/agent-command.js

@@ -8,10 +8,12 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { main as runPiMain } from '@mariozechner/pi-coding-agent';
+import { runAgentMode } from '../agent/run-agent-mode.js';
 import { getBkperAgentSystemPrompt } from '../agent/system-prompt.js';
 function createDefaultDependencies() {
     return {
         runPi: (args) => runPiMain(args),
+        runInteractiveMode: () => runAgentMode(),
     };
 }
 function hasSystemPromptArg(args) {
@@ -23,21 +25,21 @@ function buildPiArgs(args) {
     }
     return ['--system-prompt', getBkperAgentSystemPrompt(), ...args];
 }
-export function registerAgentCommands(program, dependencies = createDefaultDependencies()) {
+export function runAgentCommand(piArgs_1) {
+    return __awaiter(this, arguments, void 0, function* (piArgs, dependencies = createDefaultDependencies()) {
+        if (piArgs.length === 0) {
+            yield dependencies.runInteractiveMode();
+            return;
+        }
+        const args = buildPiArgs(piArgs);
+        yield dependencies.runPi(args);
+    });
+}
+export function registerAgentCommands(program) {
     program
         .command('agent [piArgs...]')
-        .description('Run Pi CLI with Bkper defaults (passthrough)')
+        .description('Start Bkper Agent or run Pi CLI with Bkper defaults')
         .allowUnknownOption(true)
-        .allowExcessArguments(true)
-        .action((...args_1) => __awaiter(this, [...args_1], void 0, function* (piArgs = []) {
-        try {
-            const args = buildPiArgs(piArgs);
-            yield dependencies.runPi(args);
-        }
-        catch (err) {
-            console.error('Error running agent command:', err);
-            process.exit(1);
-        }
-    }));
+        .allowExcessArguments(true);
 }
 //# sourceMappingURL=agent-command.js.map

package/lib/commands/agent-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-command.js","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAMtE,SAAS,yBAAyB;IAC9B,OAAO;QACH,KAAK,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;KAC7C,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,iBAAiB,IAAI,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IAC/B,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,iBAAiB,EAAE,yBAAyB,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,qBAAqB,CACjC,OAAgB,EAChB,eAAyC,yBAAyB,EAAE;IAEpE,OAAO;SACF,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,8CAA8C,CAAC;SAC3D,kBAAkB,CAAC,IAAI,CAAC;SACxB,oBAAoB,CAAC,IAAI,CAAC;SAC1B,MAAM,CAAC,YAA8B,EAAE,iDAAzB,SAAmB,EAAE;QAChC,IAAI,CAAC;YACD,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;YACjC,MAAM,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACX,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,CAAC;IACL,CAAC,CAAA,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"agent-command.js","sourceRoot":"","sources":["../../src/commands/agent-command.ts"],"names":[],"mappings":";;;;;;;;;AACA,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAOtE,SAAS,yBAAyB;IAC9B,OAAO;QACH,KAAK,EAAE,CAAC,IAAc,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;QAC1C,kBAAkB,EAAE,GAAG,EAAE,CAAC,YAAY,EAAE;KAC3C,CAAC;AACN,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAc;IACtC,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,iBAAiB,IAAI,GAAG,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,WAAW,CAAC,IAAc;IAC/B,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,OAAO,CAAC,iBAAiB,EAAE,yBAAyB,EAAE,EAAE,GAAG,IAAI,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAgB,eAAe;yDACjC,MAAgB,EAChB,eAAyC,yBAAyB,EAAE;QAEpE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,YAAY,CAAC,kBAAkB,EAAE,CAAC;YACxC,OAAO;QACX,CAAC;QAED,MAAM,IAAI,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QACjC,MAAM,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;CAAA;AAED,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IAClD,OAAO;SACF,OAAO,CAAC,mBAAmB,CAAC;SAC5B,WAAW,CAAC,qDAAqD,CAAC;SAClE,kBAAkB,CAAC,IAAI,CAAC;SACxB,oBAAoB,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC"}

package/lib/docs/cli-reference.md

@@ -5,7 +5,7 @@
 
 A unified **interface for [Bkper](https://bkper.com)**. Use `bkper` in two complementary modes:
 
--   **Interactive mode** — run `bkper` with no arguments to open the agent TUI
+-   **Interactive mode** — run `bkper agent` to open the Bkper Agent TUI
 -   **Command mode** — run `bkper <command>` for explicit CLI workflows, scripts, and automation
 
 With one tool, you can build and deploy Bkper apps, and manage financial data -- books, accounts, transactions, and balances.
@@ -45,10 +45,15 @@ bkper auth login
 ### Start using bkper
 
 ```bash
-# Interactive mode (agent TUI)
+# Show CLI help
 bkper
 ```
 
+```bash
+# Interactive mode (agent TUI)
+bkper agent
+```
+
 ```bash
 # Command mode (explicit command)
 bkper book list
@@ -79,7 +84,7 @@ curl -s -H "Authorization: Bearer $TOKEN" \
 
 ## Interactive Mode (powered by Pi)
 
-When you run `bkper` with no arguments in an interactive terminal, bkper starts the embedded agent TUI.
+Run `bkper agent` to start the embedded Bkper Agent TUI. Running `bkper` with no arguments shows CLI help.
 
 Bkper's agent mode is intentionally a **thin wrapper** around [Pi][Pi]:
 
@@ -95,25 +100,30 @@ On each agent startup, bkper performs a background CLI auto-update check (same b
 Use Pi CLI features directly through bkper:
 
 ```bash
-bkper agent -- <pi-args>
+bkper agent <pi-args>
 ```
 
+If no Pi arguments are provided, `bkper agent` starts the interactive Bkper Agent experience.
+If Pi arguments are provided, everything after `bkper agent` is passed through to Pi.
+
 Examples:
 
 ```bash
-bkper agent -- -p "Summarize this repository"
-bkper agent -- --model openai/gpt-4o -c
-bkper agent -- install <pi-package-source>
+bkper agent -p "Summarize this repository"
+bkper agent --model openai/gpt-4o -c
+bkper agent install <pi-package-source>
+bkper agent --help
 ```
 
-`bkper agent` keeps Bkper defaults (including Bkper system prompt) unless you explicitly pass `--system-prompt`.
+`bkper agent` keeps Bkper defaults (including the Bkper system prompt) unless you explicitly pass `--system-prompt`.
+Use `bkper help agent` for the Bkper CLI command help, and `bkper agent --help` for Pi help.
 
 For all available passthrough flags and commands, see the Pi CLI reference:
 https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent#cli-reference
 
 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 -> "Bkper Agent ready." -> one prompt). -->
+<!-- Suggested showcase media: add a short terminal GIF here (bkper agent -> "Bkper Agent ready." -> one prompt). -->
 
 ---
 
@@ -855,9 +865,10 @@ deployment:
 -   `auth logout` - Remove stored credentials
 -   `auth token` - Print the current OAuth access token to stdout
 
-#### Agent Bridge (Pi passthrough)
+#### Agent
 
--   `agent -- <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
+-   `agent` - Start the interactive Bkper Agent
+-   `agent <pi-args...>` - Run Pi CLI with Bkper defaults (system prompt/resources)
 
 #### App Lifecycle
 
@@ -917,7 +928,8 @@ Bkper.setConfig({
 
 Releases are published by GitHub Actions (Trusted Publisher with OIDC), not from local machines.
 
--   Merge a PR into `main` with one release label: `release:patch`, `release:minor`, or `release:major`
--   On each `main` push, the delivery workflow checks the merged PR associated with that commit, computes the next version from the latest release tag, publishes to npm, and pushes the new tag
+-   Add one release label to a PR targeting `main`: `release:patch`, `release:minor`, or `release:major`
+-   Before merge, the PR version bump workflow updates `package.json` on the PR branch to the next version derived from the latest release tag
+-   On each `main` push, the delivery workflow checks the merged PR label, verifies `package.json` already contains the expected next version, publishes to npm, and pushes the new tag
 -   Without a release label, publish is skipped
 -   Dependabot Pi update PRs are automatically labeled `release:patch` and set to GitHub native auto-merge when repo auto-merge and required checks are enabled

package/lib/release/versioning.d.ts

@@ -0,0 +1,5 @@
+export type ReleaseLevel = 'patch' | 'minor' | 'major';
+export declare function normalizeTagVersion(versionOrTag: string): string;
+export declare function bumpVersion(currentVersion: string, level: ReleaseLevel): string;
+export declare function resolveNextVersion(latestTag: string | null, packageVersion: string, level: ReleaseLevel): string;
+//# sourceMappingURL=versioning.d.ts.map

package/lib/release/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../../src/release/versioning.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAIvD,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED,wBAAgB,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAqB/E;AAED,wBAAgB,kBAAkB,CAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,YAAY,GACpB,MAAM,CAGR"}

package/lib/release/versioning.js

@@ -0,0 +1,32 @@
+const SEMVER_PATTERN = /^(\d+)\.(\d+)\.(\d+)$/;
+export function normalizeTagVersion(versionOrTag) {
+    const normalized = versionOrTag.startsWith('v') ? versionOrTag.slice(1) : versionOrTag;
+    if (!SEMVER_PATTERN.test(normalized)) {
+        throw new Error(`Invalid semver version: ${versionOrTag}`);
+    }
+    return normalized;
+}
+export function bumpVersion(currentVersion, level) {
+    const normalized = normalizeTagVersion(currentVersion);
+    const match = normalized.match(SEMVER_PATTERN);
+    if (!match) {
+        throw new Error(`Invalid semver version: ${currentVersion}`);
+    }
+    const [, majorText, minorText, patchText] = match;
+    const major = Number(majorText);
+    const minor = Number(minorText);
+    const patch = Number(patchText);
+    switch (level) {
+        case 'major':
+            return `${major + 1}.0.0`;
+        case 'minor':
+            return `${major}.${minor + 1}.0`;
+        case 'patch':
+            return `${major}.${minor}.${patch + 1}`;
+    }
+}
+export function resolveNextVersion(latestTag, packageVersion, level) {
+    const currentVersion = latestTag ? normalizeTagVersion(latestTag) : normalizeTagVersion(packageVersion);
+    return bumpVersion(currentVersion, level);
+}
+//# sourceMappingURL=versioning.js.map

package/lib/release/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../src/release/versioning.ts"],"names":[],"mappings":"AAEA,MAAM,cAAc,GAAG,uBAAuB,CAAC;AAE/C,MAAM,UAAU,mBAAmB,CAAC,YAAoB;IACpD,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAEvF,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,2BAA2B,YAAY,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,UAAU,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,cAAsB,EAAE,KAAmB;IACnE,MAAM,UAAU,GAAG,mBAAmB,CAAC,cAAc,CAAC,CAAC;IACvD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAE/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,2BAA2B,cAAc,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAAG,KAAK,CAAC;IAClD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAEhC,QAAQ,KAAK,EAAE,CAAC;QACZ,KAAK,OAAO;YACR,OAAO,GAAG,KAAK,GAAG,CAAC,MAAM,CAAC;QAC9B,KAAK,OAAO;YACR,OAAO,GAAG,KAAK,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC;QACrC,KAAK,OAAO;YACR,OAAO,GAAG,KAAK,IAAI,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;IAChD,CAAC;AACL,CAAC;AAED,MAAM,UAAU,kBAAkB,CAC9B,SAAwB,EACxB,cAAsB,EACtB,KAAmB;IAEnB,MAAM,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAAC,cAAc,CAAC,CAAC;IACxG,OAAO,WAAW,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;AAC9C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "bkper",
-    "version": "4.11.3",
+    "version": "4.12.0",
     "description": "Command line client for Bkper",
     "bin": {
         "bkper": "./lib/cli.js"