bkper 4.29.4 → 4.30.0

package/lib/docs/apps/event-handlers.md

@@ -6,11 +6,11 @@ Event handlers are the code that reacts to events in your Bkper Books. When a tr
 
 ## How it works
 
-1. You declare which events your app handles in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md)
+1. You declare which events your app handles in [`bkper.yaml`](https://bkper.com/docs/platform/apps/configuration.md)
 2. Bkper sends an HTTP POST to your webhook URL when those events fire
 3. Your handler processes the event and returns a response
 
-On the [Bkper Platform](https://bkper.com/docs/build/apps/overview.md), events are routed to `/events` on your app's single Worker — including local development via tunnels. For [self-hosted](https://bkper.com/docs/build/apps/self-hosted.md) setups, you configure the webhook URL directly.
+On the [Bkper Platform](https://bkper.com/docs/platform/apps/overview.md), events are routed to `/events` on your app's single Worker — including local development via tunnels. For [self-hosted](https://bkper.com/docs/platform/apps/self-hosted.md) setups, you configure the webhook URL directly.
 
 ## Agent identity
 
@@ -99,7 +99,7 @@ Do not read `bkper-oauth-token`, `bkper-agent-id`, or `Authorization` headers in
 
 > **Note**
 > During local development, events are routed through the Cloudflare tunnel started by `bkper app dev`. Local outbound uses your CLI credentials when the handler calls Bkper.
-For [self-hosted](https://bkper.com/docs/build/apps/self-hosted.md) setups, the event auth headers are sent to both `webhookUrl` and `webhookUrlDev` and must be handled directly by your infrastructure.
+For [self-hosted](https://bkper.com/docs/platform/apps/self-hosted.md) setups, the event auth headers are sent to both `webhookUrl` and `webhookUrlDev` and must be handled directly by your infrastructure.
 
 ## Event routing pattern
 
@@ -197,7 +197,7 @@ The event payload has the following structure:
 }
 ```
 
-The event payload is the same structure exposed by the [REST API](https://bkper.com/docs/build/scripts/rest-api.md). If you use TypeScript, add the [`@bkper/bkper-api-types`](https://www.npmjs.com/package/@bkper/bkper-api-types) package to your project for full type definitions.
+The event payload is the same structure exposed by the [REST API](https://bkper.com/docs/platform/scripts/rest-api.md). If you use TypeScript, add the [`@bkper/bkper-api-types`](https://www.npmjs.com/package/@bkper/bkper-api-types) package to your project for full type definitions.
 
 For update events, `data.previousAttributes` contains the fields that changed and their previous values — useful for computing diffs or reacting only to specific field changes.
 
@@ -212,7 +212,7 @@ events:
     - ACCOUNT_CREATED
 ```
 
-The complete current set of event types:
+The complete API set of event types is listed below. `COMMENT_CREATED` and `COMMENT_DELETED` remain in the API for compatibility with historical Events; Comments are not available in the current Bkper PWA.
 
 | Event | Description |
 | --- | --- |

package/lib/docs/apps/first-app.md

@@ -4,7 +4,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
 
 ## Prerequisites
 
-[Development Setup](https://bkper.com/docs/build/getting-started/setup.md) — the CLI installed and authenticated.
+[Development Setup](https://bkper.com/docs/platform/getting-started/setup.md) — the CLI installed and authenticated.
 
 ## Walkthrough
 
@@ -15,7 +15,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
     cd my-app
     ```
 
-    `bkper app init my-app` creates `./my-app` and uses `my-app` as the app id. The CLI sets your package name, URLs, and event-handler loop guards automatically. See [App Configuration](https://bkper.com/docs/build/apps/configuration.md) for the full `bkper.yaml` reference.
+    `bkper app init my-app` creates `./my-app` and uses `my-app` as the app id. The CLI sets your package name, URLs, and event-handler loop guards automatically. See [App Configuration](https://bkper.com/docs/platform/apps/configuration.md) for the full `bkper.yaml` reference.
 
 2. **Install and start developing**
 
@@ -24,7 +24,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
     npm run dev
     ```
 
-    This runs the Vite client dev server and the local Worker runtime with automatic event tunneling. See [Development Experience](https://bkper.com/docs/build/apps/development.md) for details.
+    This runs the Vite client dev server and the local Worker runtime with automatic event tunneling. See [Development Experience](https://bkper.com/docs/platform/apps/development.md) for details.
 
 3. **Open the app**
 
@@ -32,7 +32,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
 
 4. **Trigger an event**
 
-    Go to any Bkper book and check a transaction. The event handler creates a 20% draft using the original from and to Accounts. It does not affect balances unless posted. See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for the full event model.
+    Go to any Bkper book and check a transaction. The event handler creates a 20% draft using the original from and to Accounts. It does not affect balances unless posted. See [Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md) for the full event model.
 
 5. **Make a change**
 
@@ -40,7 +40,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
 
 6. **Customize your listing**
 
-    Update `bkper.yaml` with your app's description and owner details. Replace the placeholder logos in `client/public/images/`. See [App Listing](https://bkper.com/docs/build/apps/app-listing.md) for publishing details.
+    Update `bkper.yaml` with your app's description and owner details. Replace the placeholder logos in `client/public/images/`. See [App Listing](https://bkper.com/docs/platform/apps/app-listing.md) for publishing details.
 
 7. **Update the README**
 
@@ -56,7 +56,7 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
     bkper app sync
     ```
 
-    For an eligible standalone app without an external remote, sync creates private Bkper-managed source and configures it as `origin`. Authorized teammates and coding agents can then clone the same codebase with `bkper app clone my-app`. See [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) for access rules and other source workflows.
+    Stored Git source is required before an app can sync or deploy. For this standalone app without an external remote, sync creates the recommended private Bkper-managed source and configures it as `origin`. Authorized teammates and coding agents can then clone the same codebase with `bkper app clone my-app`. See [Shared App Source](https://bkper.com/docs/platform/apps/shared-app-source.md) for access rules and external source workflows.
 
 9. **Check and deploy**
 
@@ -65,12 +65,12 @@ This tutorial walks you through building and deploying a Bkper app from scratch.
     npm run deploy
     ```
 
-    Deployment is explicit: syncing or pushing source does not deploy the app. Your app is live at `https://my-app.bkper.app`. See [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) for preview environments, secrets, and KV.
+    Deployment is explicit: syncing or pushing source does not deploy the app. Your app is live at `https://my-app.bkper.app`. See [Building & Deploying](https://bkper.com/docs/platform/apps/deploying.md) for preview environments, secrets, and KV.
 
 ## Next steps
 
-- [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) — Clone and improve one private app codebase together
-- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand the single Worker client/server structure
-- [App Configuration](https://bkper.com/docs/build/apps/configuration.md) — Full `bkper.yaml` reference
-- [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) — All event types and patterns
-- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) — Preview environments and secrets
+- [Shared App Source](https://bkper.com/docs/platform/apps/shared-app-source.md) — Clone and improve one private app codebase together
+- [App Architecture](https://bkper.com/docs/platform/apps/architecture.md) — Understand the single Worker client/server structure
+- [App Configuration](https://bkper.com/docs/platform/apps/configuration.md) — Full `bkper.yaml` reference
+- [Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md) — All event types and patterns
+- [Building & Deploying](https://bkper.com/docs/platform/apps/deploying.md) — Preview environments and secrets

package/lib/docs/apps/overview.md

@@ -20,20 +20,20 @@ The same Worker can expose app-defined `/api/*` routes. Treat those routes as th
 
 When an app needs model inference, use Bkper AI by default. An authenticated app API route or event establishes the user and app identity, then platform outbound supplies authorization and usage attribution for the Worker's Bkper AI requests. The app does not need provider credentials.
 
-See [Add Bkper AI to an App](https://bkper.com/docs/build/apps/ai.md) for live model discovery, strict structured output, validation, and the client-to-Worker authentication flow.
+See [Add Bkper AI to an App](https://bkper.com/docs/platform/apps/ai.md) for live model discovery, strict structured output, validation, and the client-to-Worker authentication flow.
 
 ### Authentication
 
 OAuth is pre-configured. No client IDs, no redirect URIs, no consent screens to build.
 
-- **Web client** — Use `@bkper/web-auth`: `auth.getAccessToken()`. See [App Architecture → Client authentication](https://bkper.com/docs/build/apps/architecture.md#client-authentication).
-- **Server API routes** — Send `Authorization: Bearer <token>` to `/api/*`; dispatch validates it and platform outbound injects auth for server-side Bkper API calls. See [App Architecture → Server API authentication](https://bkper.com/docs/build/apps/architecture.md#server-api-authentication).
-- **Event handlers** — Handle `/events` in the same Worker and call Bkper with server-side `new Bkper()`; dispatch/outbound handle auth and agent identity. See [Event Handlers → Authentication](https://bkper.com/docs/build/apps/event-handlers.md#authentication).
-- **Local development** — The Vite auth middleware uses your CLI credentials. See [Development Experience → Local development authentication](https://bkper.com/docs/build/apps/development.md#local-development-authentication).
+- **Web client** — Use `@bkper/web-auth`: `auth.getAccessToken()`. See [App Architecture → Client authentication](https://bkper.com/docs/platform/apps/architecture.md#client-authentication).
+- **Server API routes** — Send `Authorization: Bearer <token>` to `/api/*`; dispatch validates it and platform outbound injects auth for server-side Bkper API calls. See [App Architecture → Server API authentication](https://bkper.com/docs/platform/apps/architecture.md#server-api-authentication).
+- **Event handlers** — Handle `/events` in the same Worker and call Bkper with server-side `new Bkper()`; dispatch/outbound handle auth and agent identity. See [Event Handlers → Authentication](https://bkper.com/docs/platform/apps/event-handlers.md#authentication).
+- **Local development** — The Vite auth middleware uses your CLI credentials. See [Development Experience → Local development authentication](https://bkper.com/docs/platform/apps/development.md#local-development-authentication).
 
 ### Services
 
-Declare the services you need in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md) and the platform provisions them:
+Declare the services you need in [`bkper.yaml`](https://bkper.com/docs/platform/apps/configuration.md) and the platform provisions them:
 
 - **KV storage** — Key-value storage for caching and state. Access via `c.env.KV` in your handlers.
 - **Secrets** — Securely stored environment variables. Set via `bkper app secrets put`, access via `c.env.SECRET_NAME`.
@@ -54,7 +54,7 @@ Bkper can host one private codebase for your app. Authorized teammates and codin
 
 Source synchronization remains separate from deployment. A Git push stores source but never builds or deploys the app.
 
-See [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) for the collaboration workflow, access rules, and external Git options.
+See [Shared App Source](https://bkper.com/docs/platform/apps/shared-app-source.md) for the collaboration workflow, access rules, and external Git options.
 
 ### Deployment
 
@@ -101,6 +101,6 @@ This gives you a working app with a client UI, server API routes, and `/events`
 
 ## Next steps
 
-- [Your First App](https://bkper.com/docs/build/apps/first-app.md) — Build and deploy a complete platform app
-- [Shared App Source](https://bkper.com/docs/build/apps/shared-app-source.md) — Collaborate from one private codebase
-- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand how platform apps are structured
+- [Your First App](https://bkper.com/docs/platform/apps/first-app.md) — Build and deploy a complete platform app
+- [Shared App Source](https://bkper.com/docs/platform/apps/shared-app-source.md) — Collaborate from one private codebase
+- [App Architecture](https://bkper.com/docs/platform/apps/architecture.md) — Understand how platform apps are structured

package/lib/docs/apps/quality.md

@@ -66,7 +66,7 @@ Keep the security boundary simple and explicit:
 - Access only the Book data needed for the operation.
 - Make event handling safe to retry and prevent event loops.
 
-See [App Security](https://bkper.com/docs/build/apps/security.md) and [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md) for implementation details.
+See [App Security](https://bkper.com/docs/platform/apps/security.md) and [Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md) for implementation details.
 
 ## Verification
 
@@ -81,7 +81,7 @@ App reviews should report concrete findings with file locations and suggested fi
 
 ## Next Steps
 
-- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Client, server, API, and event structure.
-- [App Security](https://bkper.com/docs/build/apps/security.md) — Authentication and authorization boundaries.
-- [Context Menu](https://bkper.com/docs/build/apps/context-menu.md) — Embedded Book context and open modes.
-- [Development Experience](https://bkper.com/docs/build/apps/development.md) — Local development and deterministic checks.
+- [App Architecture](https://bkper.com/docs/platform/apps/architecture.md) — Client, server, API, and event structure.
+- [App Security](https://bkper.com/docs/platform/apps/security.md) — Authentication and authorization boundaries.
+- [Context Menu](https://bkper.com/docs/platform/apps/context-menu.md) — Embedded Book context and open modes.
+- [Development Experience](https://bkper.com/docs/platform/apps/development.md) — Local development and deterministic checks.

package/lib/docs/apps/security.md

@@ -8,7 +8,7 @@ Authentication identifies the Bkper user making a request. The platform handles
 
 Authorization determines whether that user may perform a specific operation.
 
-See [App Architecture](https://bkper.com/docs/build/apps/architecture.md) for the client and server authentication flow.
+See [App Architecture](https://bkper.com/docs/platform/apps/architecture.md) for the client and server authentication flow.
 
 ## Authorize app operations
 
@@ -68,7 +68,7 @@ if (!isInstalled) {
 
 ## Next Steps
 
-- [App Quality Guidelines](https://bkper.com/docs/build/apps/quality.md) — Review cross-cutting app quality and security expectations.
-- [App Architecture](https://bkper.com/docs/build/apps/architecture.md) — Understand client and server authentication flows.
-- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md#setting-secrets) — Store production and preview secrets.
-- [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md#authentication) — Understand authentication for platform and self-hosted events.
+- [App Quality Guidelines](https://bkper.com/docs/platform/apps/quality.md) — Review cross-cutting app quality and security expectations.
+- [App Architecture](https://bkper.com/docs/platform/apps/architecture.md) — Understand client and server authentication flows.
+- [Building & Deploying](https://bkper.com/docs/platform/apps/deploying.md#setting-secrets) — Store production and preview secrets.
+- [Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md#authentication) — Understand authentication for platform and self-hosted events.

package/lib/docs/apps/self-hosted.md

@@ -1,6 +1,6 @@
 # Bkper Self-Hosted Webhooks
 
-The [Bkper Platform](https://bkper.com/docs/build/apps/overview.md) handles hosting, authentication, and deployment for you. However, you can host event handlers on your own infrastructure if you have specific requirements — existing cloud setup, compliance constraints, or legacy apps.
+The [Bkper Platform](https://bkper.com/docs/platform/apps/overview.md) handles hosting, authentication, and deployment for you. However, you can host event handlers on your own infrastructure if you have specific requirements — existing cloud setup, compliance constraints, or legacy apps.
 
 > **Tip**
 > Use the Bkper Platform unless you have a specific reason to self-host. It eliminates the need to manage authentication, secrets, hosting, and deployment yourself.
@@ -8,7 +8,7 @@ The [Bkper Platform](https://bkper.com/docs/build/apps/overview.md) handles host
 
 A Bkper event handler running on [Google Cloud Functions](https://cloud.google.com/functions/) receives authenticated calls from the `bkper-hrd@appspot.gserviceaccount.com` service account. You need to grant this service account the [Cloud Functions Invoker IAM role](https://cloud.google.com/functions/docs/securing/managing-access-iam) (`roles/cloudfunctions.invoker`).
 
-Set the production endpoint in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md):
+Set the production endpoint in [`bkper.yaml`](https://bkper.com/docs/platform/apps/configuration.md):
 
 ```yaml
 webhookUrl: https://us-central1-my-project.cloudfunctions.net/events
@@ -32,7 +32,7 @@ The function response must follow the standard format:
 { result?: any, error?: any }
 ```
 
-See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md#response-format) for details on response handling.
+See [Event Handlers](https://bkper.com/docs/platform/apps/event-handlers.md#response-format) for details on response handling.
 
 ### Considerations
 
@@ -46,7 +46,7 @@ See [Event Handlers](https://bkper.com/docs/build/apps/event-handlers.md#respons
 
 You can host event handlers on any infrastructure — other cloud providers, containers, on-premise servers.
 
-Configure the same `webhookUrl` property in [`bkper.yaml`](https://bkper.com/docs/build/apps/configuration.md):
+Configure the same `webhookUrl` property in [`bkper.yaml`](https://bkper.com/docs/platform/apps/configuration.md):
 
 ```yaml
 webhookUrl: https://my-server.example.com/bkper/events

package/lib/docs/apps/shared-app-source.md

@@ -2,7 +2,7 @@
 
 Bkper-managed app source gives your team and coding agents one shared private codebase for a Bkper app. Authorized app developers can clone the same repository, improve it locally, and continue from one shared history without setting up a separate Git host.
 
-Shared app source supports development collaboration. It does not automatically build or deploy your app.
+Every app sync and deployment requires clean, committed source stored in a durable Git remote. Bkper-managed source is the recommended default for development collaboration. It does not automatically build or deploy your app.
 
 ## Who can access the source
 
@@ -66,7 +66,7 @@ Keep agent instructions such as `AGENTS.md` in the repository so every teammate
 
 ## Source synchronization is not deployment
 
-Source storage and app deployment are separate operations:
+Source storage and app deployment are separate operations. Apps without a Git repository cannot sync or deploy; the CLI provides the initialization and managed-sync steps needed to establish source safely.
 
 | Action             | What it does with source                                                       | Does it deploy? |
 | ------------------ | ------------------------------------------------------------------------------ | --------------- |
@@ -75,19 +75,24 @@ Source storage and app deployment are separate operations:
 | `npm run build`    | Creates local build output in `dist/`.                                         | No              |
 | `bkper app deploy` | Pushes and verifies the managed commit, then uploads the existing local build. | Yes             |
 
-An ordinary Git push never deploys. `bkper app deploy` also does not run a build, so build locally before deploying the result you intend to release.
+An ordinary Git push never deploys. `bkper app deploy` also does not run a build, so build locally before deploying the result you intend to release. The CLI verifies the stored source commit but does not prove that the local `dist/` output was built from it.
 
-Managed sync and deploy require a clean, committed working tree and use fast-forward safety checks. The CLI does not automatically commit, merge, rebase, force-push, reset, or discard files.
+Managed sync and deploy require a clean, committed working tree and use fast-forward safety checks. External sync and deploy require the current branch to track an upstream containing the current clean commit. The CLI does not automatically commit, merge, rebase, force-push, reset, discard files, choose an external remote, or push to an external provider.
 
 ## External Git and monorepos
 
 Bkper-managed source is optional. Existing workflows remain external when:
 
-- the app already has a GitHub, GitLab, or other provider remote;
-- `bkper.yaml` is inside a monorepo rather than at the repository root; or
-- the app is otherwise not rooted in a standalone Git repository.
+- the app already has a GitHub, GitLab, or other provider remote; or
+- `bkper.yaml` is inside a monorepo rather than at the repository root.
 
-Clone those apps from their external provider. `bkper app clone` is for Bkper-managed source only.
+The current branch must have a configured upstream containing the commit being synced or deployed. If no upstream is configured, choose the intended provider remote and store the branch explicitly:
+
+```bash
+git push --set-upstream <remote> <branch>
+```
+
+The CLI fetches and verifies the upstream without pushing or changing the working tree. Clone external apps from their provider. `bkper app clone` is for Bkper-managed source only.
 
 Moving an existing standalone app from an external provider is intentional: the CLI never removes or renames an existing remote. Before changing remotes, make sure every branch and tag you want to preserve is available locally and the current `main` branch is clean and committed. Removing all external remotes and running `bkper app sync` then activates managed source for an eligible app.
 
@@ -95,7 +100,7 @@ The `repoUrl` field in `bkper.yaml` is app-listing metadata. It does not select
 
 ## Next steps
 
-- [Your First App](https://bkper.com/docs/build/apps/first-app.md) — Scaffold an app and establish its shared source
-- [Building & Deploying](https://bkper.com/docs/build/apps/deploying.md) — Build, sync, preview, and deploy explicitly
-- [CLI](https://bkper.com/docs/build/tools/cli.md) — Install the CLI and review its app-development workflows
+- [Your First App](https://bkper.com/docs/platform/apps/first-app.md) — Scaffold an app and establish its shared source
+- [Building & Deploying](https://bkper.com/docs/platform/apps/deploying.md) — Build, sync, preview, and deploy explicitly
+- [CLI](https://bkper.com/docs/platform/tools/cli.md) — Install the CLI and review its app-development workflows
 - [Coding Agents](https://bkper.com/docs/ai/coding-agents.md) — Give coding agents the Bkper and project context they need

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

@@ -9,14 +9,16 @@ Build, deploy, and manage Bkper apps using the `bkper` CLI.
 
 ## Source control modes
 
-Bkper selects source mode without changing the local-build deployment model:
+Every App sync and deployment requires an attached, clean, committed Git source stored in a durable remote. Bkper-managed private Git is the recommended default:
 
 - **Managed source:** `bkper app sync` activates private Bkper-managed Git for a new or existing App when `bkper.yaml` is at the root of a standalone Git repository, the current clean committed branch is `main`, and no Git remote exists. Bkper configures the managed repository as `origin`. New Apps initially upload `main`; existing Apps atomically upload all local branches and tags.
-- **External source:** an App keeps direct sync/deploy behavior when it has an external Git remote, is nested in a monorepo, or is not rooted at `bkper.yaml`. The CLI never changes an existing external remote.
+- **External source:** an App keeps its provider when it has an external Git remote or is nested in a monorepo. Its current branch must track an upstream branch containing the current commit. The CLI fetches and verifies that upstream before sync or deploy, but never chooses a remote or pushes external source.
 
-To opt out, keep a GitHub, GitLab, or other provider remote configured. Managed mode is sticky after activation; adding another remote later does not change it, and Artifacts remains `origin`. The App listing `repoUrl` metadata does not select source mode.
+Apps without a Git repository cannot sync or deploy. The CLI returns the exact initialization, review, commit, and managed-sync steps so a user or coding agent can establish source safely. To use GitHub, GitLab, or another provider instead, configure the intended branch upstream and push it before syncing.
 
-Source and deployment remain separate. `git push` stores source only and **never deploys**. `bkper app sync` pushes managed source before syncing local metadata. `bkper app deploy` pushes managed source, verifies that the exact commit exists in the linked repository, and then uploads the existing local `dist/server` and optional `dist/client` output. Builds remain local and explicit; Bkper does not claim reproducible remote CI or prove that the local bundle was built from the declared commit. Source linkage is best-effort provenance for already-authorized developers.
+Managed mode is sticky after activation; adding another remote later does not change it, and Artifacts remains `origin`. The App listing `repoUrl` metadata does not select source mode.
+
+Source and deployment remain separate. `git push` stores source only and **never deploys**. `bkper app sync` pushes managed source or verifies external source before syncing local metadata. `bkper app deploy` pushes and verifies managed source, or verifies that the external upstream contains the current commit, before uploading the existing local `dist/server` and optional `dist/client` output. Builds remain local and explicit; Bkper does not prove that the local bundle was built from the verified commit.
 
 CLI-managed pushes are clean-tree and fast-forward-only. The CLI never commits, merges, rebases, force-pushes, resets, or discards files. Authorized developers may use ordinary Git commands, including an intentional force-push, but a push still never deploys.
 
@@ -113,7 +115,7 @@ npm run build
 bkper app deploy
 ```
 
-For a managed App, sync and deploy safely push the current committed branch. For an external App, both commands preserve direct local metadata and bundle upload behavior without changing remotes.
+For a managed App, sync and deploy safely push the current committed branch. For an external App, both commands require a configured upstream containing the current clean commit and preserve direct local metadata and bundle upload behavior without changing remotes.
 
 Verify:
 
@@ -191,8 +193,9 @@ bkper app get <appId> --json
 # Deploy to preview environment (URL: https://{appId}-preview.bkper.app)
 bkper app deploy --preview
 
-# Check deployment status
+# Check deployment status from the current app or by ID
 bkper app status
+bkper app status <appId>
 ```
 
 > **Note:** `bkper app dev` runs one local Worker runtime — Miniflare, file watching, and an optional Cloudflare tunnel to `/events` when the app subscribes to events. Miniflare is loaded from the app project's `devDependencies` so each app can keep its local Workers simulator aligned with its own code. 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`. Open the printed `Open app` URL in your browser; the `Worker/API` URL is for `/api`, `/health`, `/openapi.json`, and events. If your Vite server uses a port other than `5173`, pass that port with `--cp, --client-port` so the local `ASSETS` binding can reach it. If needed, install Miniflare in the app root with `bun add -d miniflare` or `npm install -D miniflare`.
@@ -220,13 +223,13 @@ If Git authentication fails:
 
 The helper command is intentionally `bkper app git-credential <appId> [operation]`. It is internal Git plumbing, not a root `git` command or an `app git` group.
 
-## Managed Git preflight recovery
+## Source preflight recovery
 
-Managed sync and deploy require `bkper.yaml` at the Git root, an attached branch, committed `HEAD`, and a clean tree. Ignored build output such as `dist/` is allowed.
+Every sync and deploy requires an attached branch, committed `HEAD`, a clean tree, and durable source storage. Managed source additionally requires `bkper.yaml` at the Git root. Ignored build output such as `dist/` is allowed.
 
 | Failure | Safe recovery |
 | --- | --- |
-| No Git repository | For a standalone App, run `git init -b main`, review files, commit, and retry. An eligible new or existing App activates managed source on sync when no remote exists. |
+| No Git repository | From the App root, run `git init -b main`, review `.gitignore` and all source files, commit, then run `bkper app sync` to activate the recommended managed source. |
 | `bkper.yaml` below Git root | Keep the monorepo/external workflow; managed monorepos are not supported. |
 | No commits | Review, then run `git add .` and `git commit -m "Initial app"`. |
 | Detached `HEAD` | Attach a branch with `git switch -c <branch>`; use `main` for first activation. |
@@ -234,6 +237,8 @@ Managed sync and deploy require `bkper.yaml` at the Git root, an attached branch
 | Staged changes | Inspect `git diff --cached`; commit them or intentionally unstage them before retrying. |
 | Modified tracked files | Inspect `git diff`; commit or intentionally restore them before retrying. |
 | Non-ignored untracked files | Inspect `git status`; commit, ignore, or intentionally remove them before retrying. |
+| External branch has no upstream | Choose the intended provider remote and run `git push --set-upstream <remote> <branch>`, then retry. The CLI never guesses or pushes an external remote. |
+| Current commit is not upstream | Push the current branch to its configured upstream, then retry. |
 | Missing or incorrect managed `origin` | Inspect `git remote -v`; compare with a fresh managed clone. Do not overwrite an external remote. |
 | Authentication or expired credential | Run `bkper auth login` if needed, then retry the Git operation for a new five-minute token. |
 | Remote branch ahead or divergent | Run `git fetch origin <branch>` and inspect `git log --oneline --left-right HEAD...origin/<branch>`; merge or rebase by your own choice, then push and retry. The CLI never force-resolves divergence. |
@@ -549,11 +554,11 @@ Inside the interactive agent:
 -   `app clone <appId> [path]` - Clone a Bkper-managed App source repository. Does not install dependencies; run `bun install` explicitly afterward. External-source Apps must be cloned from their provider instead.
 -   `app git-credential <appId> [operation]` - Internal noninteractive Git credential helper for managed Artifacts source. Generated repository config pins the App ID and exact remote URL/path; Git appends `get`, `store`, or `erase`. Never persists tokens.
 -   `app list` - List all apps you have access to
--   `app sync` - Sync [bkper.yaml][bkper.yaml reference] configuration. For an eligible standalone repository with no remote, activate managed source for a new or existing App; existing migrations atomically upload all local branches and tags. If already managed, cleanly fast-forward-push the current committed branch first.
+-   `app sync` - Verify that source is clean, committed, and stored before syncing [bkper.yaml][bkper.yaml reference]. For an eligible standalone repository with no remote, activate managed source for a new or existing App; existing migrations atomically upload all local branches and tags. For external source, verify that the configured upstream contains the current commit.
 -   `app build` - Build the server Worker bundle for deployment
--   `app deploy` - For managed Apps, cleanly fast-forward-push and verify the current commit, then explicitly deploy the existing local build. External Apps keep direct upload behavior.
+-   `app deploy` - Require stored source, then explicitly deploy the existing local build. Managed Apps safely push and Platform-verifies the current commit. External Apps keep direct upload behavior after the CLI verifies that their upstream contains the current commit.
     -   `-p, --preview` - Deploy to preview environment
--   `app status` - Show deployment status
+-   `app status [appId]` - Show deployment status. When `appId` is omitted, the app id is read from local app config.
 -   `app logs [appId]` - View recent app logs. When `appId` is omitted, the app id is read from local app config.
     -   `--since <time>` - ISO8601 or relative lower bound (e.g. `5m`, `1h`, `15d`)
     -   `--until <time>` - ISO8601 or relative upper bound

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

@@ -147,6 +147,6 @@ Collections can also serve as references for automations (Bots or Apps) that wor
 
 ## Events
 
-Every action in a Book — posting a transaction, editing an account, adding a comment — 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_ (a bot, 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.

package/lib/docs/sdk/bkper-api-types.md

@@ -190,6 +190,8 @@ More information at the [Bkper Developer Documentation](https://bkper.com/docs/#
 - `startedTrial?`: `boolean` — True if the user has started the trial period
 - `totalTransactionsThisMonth?`: `number` — User-level total transactions this month
 - `totalTransactionsThisYear?`: `number` — User-level total transactions this year
+- `transactionsAverage?`: `number` — Authoritative rounded-up rolling monthly average of posted transactions for the current plan
+- `transactionsCapacity?`: `number` — Confirmed average monthly transaction capacity for the current plan
 
 ### Book
 

package/lib/docs/sdk/bkper-js.md

@@ -509,6 +509,8 @@ The Billing information includes the plan, the admin email, and the billing port
 - `getPortalUrl(returnUrl: string)` → `Promise<string | undefined>` — Gets the URL to redirect the User to the billing portal.
 - `getTotalTransactionsThisMonth()` → `number | undefined` — Gets the number of total transactions this month for the User's billing account.
 - `getTotalTransactionsThisYear()` → `number | undefined` — Gets the number of total transactions this year for the User's billing account.
+- `getTransactionsAverage()` → `number | undefined` — Gets the authoritative rolling monthly average of posted transactions.
+- `getTransactionsCapacity()` → `number | undefined` — Gets the confirmed average monthly transaction capacity.
 - `hasStartedTrial()` → `boolean | undefined` — Tells if the User has started the trial period.
 - `isEnabled()` → `boolean | undefined` — Tells if billing is enabled for the User.
 - `isPlanOverdue()` → `boolean | undefined` — Tells if the User's current plan payment is overdue.

package/package.json

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