ptbk 0.119.0-8 → 0.119.0-84

package/LICENSE.md

@@ -1,5 +1,16 @@
 # 🔑 License
 
+Licensing information and proposed commercial/continuity terms are published at:
+
+- English: https://www.ptbk.io/en/licence
+- Czech: https://www.ptbk.io/cs/licence
+
+The 2 November 2026 proposal on that page is a **non-effective discussion draft**, not a new grant or a retrospective restriction. A later edit of a website cannot change rights already validly obtained to a particular distribution. Product subscriptions, hosted services and third-party component licences remain separate.
+
+The existing notice below is retained with this distribution so it remains identifiable offline. It is unchanged from the notice at revision `c8718b5aa635b67aabf861e94ee673d23de74644`; retaining it does not supply missing product-specific BUSL parameters or imply unlimited commercial self-hosting rights. Final adoption of a different licence requires an explicit versioned grant and consistent distribution metadata.
+
+## Existing distribution notice
+
 Promptbook Engine is licensed under the Business Source License 1.1 (BUSL-1.1).
 
 This license allows non-production use, personal projects, and evaluation without restrictions. 

package/README.md

@@ -1,40 +1,120 @@
-# Promptbook (`ptbk`)
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/webgptorg/promptbook/reborn/2026-10/design/readme-wordmark-dark.svg" />
+    <img src="https://raw.githubusercontent.com/webgptorg/promptbook/reborn/2026-10/design/readme-wordmark.svg" alt="Promptbook" width="570" />
+  </picture>
+</p>
 
-Promptbook operates readable agent and task Books over a Git project. This repository publishes one npm package, `ptbk`, which installs the `ptbk` command. Runtime state, requests, traces and the shared browser profile live in ignored `.ptbk/` files.
+<h1 align="center">You used to give AI tasks<br />Now it works for you</h1>
 
-Requires Node.js 22.13+ in the Node 22 line, or Node 24+, and npm 10+.
+<p align="center">
+  <a href="#quickstart"><strong>Quickstart</strong></a> ·
+  <a href="#deploy-to-your-own-server"><strong>Deploy</strong></a> ·
+  <a href="https://www.ptbk.io/en"><strong>Website</strong></a> ·
+  <a href="design/README.md"><strong>Brand</strong></a> ·
+  <a href="specs/_main.md"><strong>Specifications</strong></a> ·
+  <a href="https://www.ptbk.io/en/partnership"><strong>For partners</strong></a>
+</p>
 
-```bash
-# Global installation
+Give Promptbook an ongoing responsibility, a goal and your rules. Its agents find useful work, carry it through and ask when a decision needs you. **Your engine runs on your computer or server, with your files and your choice of models.**
+
+![The dashboard controls an independent engine. The engine coordinates agents and tasks, records file changes in Git, and uses your selected models and tools.](https://raw.githubusercontent.com/webgptorg/promptbook/reborn/2026-10/design/readme-engine.svg)
+
+| Readable files | Traceable work | Your choice of AI |
+| --- | --- | --- |
+| Agents, tasks and conversations live in your project folder. | Review changes in Git and execution evidence in task traces. | Use supported harnesses such as Codex or Claude Code; local models depend on the adapter. |
+
+**What could you hand over?** Promote each new podcast episode. Follow up with customers using their CRM history. Investigate and repair an overnight bug. These are illustrative agendas; actual work follows your configured tools, checks and permissions.
+
+## Quickstart
+
+If Node.js and npm are already installed, use the npm path below. On a clean Ubuntu VPS, use the [complete shell installation](#clean-ubuntu-vps).
+
+Requires **Node.js 22.13+ in the 22.x line, or 24+**, **npm 10+**, Git and Chrome, Chromium or Edge. Setup guides you through selecting a supported harness and signing in.
+
+```sh
 npm install --global ptbk
-ptbk init --path ./project
+mkdir my-agenda
+cd my-agenda
+ptbk init
+```
+
+### Clean Ubuntu VPS
 
-# Project-local installation
-npm install --save-dev ptbk
-npx ptbk init
+On **Ubuntu 24.04 x86-64 with systemd**, run this in an interactive SSH terminal as root or an administrator with sudo:
+
+```sh
+curl -fsSL https://www.ptbk.io/install.sh | bash
 ```
 
-Initialization creates missing core agents, task templates, `ptbk.json` and project conventions, preserving customized files. Its wizard offers destination-local installation of the exact running version and selected global harness setup, reusing native login. Unattended setup requires `--installation local|global` or `--no-install`; `--non-interactive` disables prompts. Setup commits only safe generated artifacts; `--no-commit` defers persistence, and edits overlapping user work remain pending review. Configure meaningful project checks before starting work.
-
-```bash
-ptbk add "Implement the new behavior and its acceptance checks" --commit
-ptbk list
-ptbk run --dry-run
-ptbk start                     # background agenda, localhost dashboard, reboot persistence
-ptbk dashboard                 # attach terminal controls to the existing service
-ptbk show                      # inspect the same process and pending requests
-ptbk answer REQUEST_ID "Reply"
-ptbk stop                      # intentional stop also disables automatic restart
+You do not need Node.js, npm or Git installed first. The script uses the [shared server installer](deploy/ubuntu/install.sh), adds the prerequisites and published engine, then opens ordinary `ptbk init` as the `promptbook` user. [Inspect the entry script](https://github.com/webgptorg/ptbk-landing-page-aldaron/blob/main/public/install.sh) · [VPS guide](deploy/README.md#an-existing-vps-including-digitalocean-or-hetzner).
+
+Describe the work in the initializer. It prepares the project and starts the engine in the background.
+
+```sh
+ptbk dashboard     # open the controls; closing them leaves the engine running
+ptbk chat          # talk to your agents, in a separate terminal
+ptbk stop          # finish the current task, then stop
+ptbk start         # resume the agenda
 ```
 
-`start` discovers available authenticated harnesses, uses Manager for missing assignments, and executes one task at a time. It requires reported outcome evidence and passing project checks before committing implementation, dated task completion and learning follow-ups together. It watches future work and materializes goal enquiries when no unfinished backlog remains. Failures retain work and expose recovery diagnostics.
+The engine machine must stay available. By default, persistent project services return at OS startup: an agenda that was running can continue after checks; one you paused or stopped returns paused until you resume it. Its browser dashboard and API are available only on that computer through a loopback address, with no pairing step. [Local API access](specs/cli/api.md) · [Startup behavior](specs/cli/persistence.md)
+
+Agents explicitly call you with `+@User` when they need a response. Viewing that message clears its shared attention indicator while the question keeps waiting. In a project terminal dashboard or `ptbk chat`, **Ctrl+N** toggles **Sounds & notifications (experimental)** for the project's open clients. Effects start Off, follow your last-used client and suppress attention alerts during the ten seconds after input. Native delivery depends on OS permissions; exact terminal activation is available through a verified Kitty notification connection. [Attention and notifications](specs/cli/notifications.md)
+
+A background engine [updates itself](specs/cli/updates.md) when it has no other work: stable minor and patch releases of its major version, or a running prerelease to its stable release. It never installs a version your `ptbk.json` `updates` pin or range excludes, or one that needs a newer Node.js than your host runs, and you can switch it off on the dashboard's System page. Release signing and rollout delays are still being agreed with the platform, so your host access and backups still matter.
+
+**Windows:** download the EXE from [GitHub Releases](https://github.com/webgptorg/promptbook/releases), or follow the [installation guide](https://www.ptbk.io/en/open-source). The installer offers the local desktop client (selected by default). Open the app to set up your project and choose AI tools. The desktop uses the same engine and initializer as the CLI, with an embedded CLI terminal; closing a window leaves your engines running. CLI-only installation remains available.
+
+**macOS:** download the matching DMG from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). Choose `arm64` for Apple Silicon or `x64` for Intel, then drag Promptbook into Applications. Node.js, npm and the matching engine are included. Project setup uses Git from your Mac, such as Git from the Xcode Command Line Tools. See the [desktop installation guide](apps/desktop/README.md#macos-installation) for signing and login details.
+
+**Android preview:** download the ARM64 APK from [GitHub Releases](https://github.com/webgptorg/promptbook/releases). It includes the local engine, Node.js, Git and Gemini CLI. The app runs the engine in an Android foreground service and opens the project dashboard. See the [Android installation guide](apps/android/README.md) for setup and signing details.
+
+## Deploy to your own server
+
+**A clean Ubuntu 24.04 LTS x86-64 server** with systemd, outbound HTTPS and root or sudo access over SSH needs no preinstalled Node.js, npm, Git, Chrome or AI harness: use the [one-command installation](#clean-ubuntu-vps). It prepares the server through the [shared installer](deploy/ubuntu/install.sh) and opens `ptbk init` as a dedicated non-sudo `promptbook` user. Sign-in to Codex or Claude Code is finished on your phone or computer; see the [server guide](deploy/README.md#finish-setup-over-ssh).
+
+[![Set up a DigitalOcean Droplet](deploy/digitalocean/button.svg)](deploy/README.md#digitalocean)
+
+**DigitalOcean:** create an Ubuntu Droplet with your SSH key and paste the prepared startup script. It prepares the server with persistent project storage and private dashboard access; then the same command over SSH continues into setup. [Open the DigitalOcean setup guide](deploy/README.md#digitalocean). The guide includes the required script-copy step; this is not a published Marketplace one-click image.
+
+[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fwebgptorg%2Fpromptbook%2Freborn%2F2026-10%2Fdeploy%2Fazure%2Fazuredeploy.json)
+
+Create a **paid Ubuntu VPS in your own Azure account**, with a persistent disk, SSH restricted to your client IP, Node.js, Git, Chrome and the published engine. Review the provider's costs before confirming. Then connect over SSH and run the same command to continue into `ptbk init` and sign in to your chosen AI harness; the button prepares the server, while your agenda still needs setup.
+
+On every path the engine runs as a dedicated user, keeps its dashboard private and can resume at boot after initialization. [All installation options](https://www.ptbk.io/en/open-source).
+
+**[AWS EC2 setup](deploy/README.md#aws):** upload the prepared CloudFormation template to create a persistent Ubuntu server with the same installer. All providers require paid resources; after server preparation, the same command over SSH continues into attended `ptbk init` and AI sign-in.
+
+## Built around your project
+
+**Agent → Project → Task.** Agents keep the goals and rules; the project holds context; tasks record concrete work. This is the [APT Framework](specs/whitepaper.md).
+
+Agent definitions are ordinary editable text:
+
+```book
+AGENT Product caretaker
+
+GOAL Keep the product reliable and easy to maintain.
+RULE Run the project's checks before reporting a fix.
+RULE Ask before publishing outside the agreed release policy.
+OPEN Learn better methods; the GOAL and both RULEs stay as written.
+```
+
+Edit these files with [Book language support for VS Code](https://marketplace.visualstudio.com/items?itemName=promptbook.book-extension), [built and released with the engine](extensions/vscode/README.md).
+
+`OPEN` with its limits, or `CLOSED`, is an [anchor](specs/concepts/anchoring.md): a user-fixed rule whose meaning the agents cannot change themselves, even while their methods evolve. You can still change it. Anchors limit what agents may rewrite; they do not make every AI output correct.
+
+Set real project checks in `ptbk.json`; the initializer's placeholder is informational. Git tracks file changes, not every external action. External models and services receive the inputs you authorize.
+
+## App, engine and support
 
-Lifecycle commands report once and return; `start --raw` still launches a daemon. Use `dashboard` to attach terminal controls, or `start --foreground` to own execution in the current terminal (`--raw` gives plain foreground events). Q/Ctrl+C leaves an attached dashboard while its service continues. `--no-persist`, `--no-server`, `--no-qr` and `--port` customize startup. `run` executes a finite queue with one configuration; for example `ptbk run --harness openai-codex --check "npm run check" --limit 1`. Harness availability, account policy and capability checks happen before inference; unsupported installed provider features produce an actionable diagnostic.
+This repository is the **self-hosted engine**. The upcoming **Promptbook app** adds convenient remote control through an end-to-end encrypted relay connection, separate from the engine's local dashboard. [Register interest](https://www.ptbk.io/en) or [deploy Promptbook for your clients](https://www.ptbk.io/en/partnership).
 
-Suitable terminals default to rich presentation; `--raw` or redirected output gives plain results without prompts or QR codes. `ptbk add` guides and confirms task creation. Use `ptbk init --help`, `ptbk init help` or `ptbk help init` for the same command-specific offline reference.
+The [first-App specification](specs/app/integration.md) focuses on App-started VPS setup, project chat and native start/pause/stop controls. It also defines later extensions without claiming they are shipped.
 
-Global installation, local `npx ptbk`, or a project script such as `"ptbk": "ptbk"` work outside this repository. Each process loads its own installed runtime/version and pins that installation for restart. See [runtime usage](docs/runtime.md), [compatibility and verification](docs/compatibility.md), and [the specification](https://github.com/webgptorg/promptbook/blob/main/specs/_main.md).
+[Command reference](specs/cli/cli.md) · [Book language](specs/book-language/_index.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
 
-For development, use `npm ci` and `npm run check`. Checks validate types, deterministic integration fixtures and real tarball installations in disposable external projects. CI runs on Linux, macOS and Windows with Node 22 and 24.
+A star, a reproducible issue or a contribution helps us build Promptbook. See the **[engine licence and proposed commercial terms](https://www.ptbk.io/en/licence)** ([česky](https://www.ptbk.io/cs/licence)). The proposed terms are not yet effective; the [notice accompanying this distribution](LICENSE.md) and any agreement actually accepted govern your rights.
 
-For releases, run `npm version patch`, `npm version minor`, or `npm version prerelease` on a clean named branch after committing your work. Basic `preversion` checks run locally; `postversion` atomically pushes the version commit and exact `vVERSION` tag. GitHub Actions checks and publishes only `ptbk` with npm provenance, then verifies the public registry and installed CLI. Configure npm trusted publishing once as described in [releasing](docs/releasing.md).
+Pre-Reborn: [legacy version 0.114.0-51](https://github.com/webgptorg/promptbook/tree/7ab4af6862d81a7e8b2a1ce8522f79bb2cd37231).

package/dist/app/api/engine-api.d.ts

@@ -0,0 +1,117 @@
+import type { OnboardingSession } from '../../onboarding/session.js';
+import type { Agenda } from '../../engine/agenda.js';
+import { type ContractProblem } from '../../vendor/app-platform.js';
+import type { AppSecurityFacts } from '../connection.js';
+import type { AccessStore, Actor } from '../web/access.js';
+/**
+ * Capabilities this engine advertises in `GET /engine` (every route of each works). The core API needs none.
+ *
+ * @private App engine API
+ */
+export declare const ADVERTISED_CAPABILITIES: readonly {
+    readonly id: string;
+    readonly version: number;
+}[];
+/**
+ * What the engine API needs from the running engine.
+ *
+ * @private App engine API
+ */
+export type EngineApiDeps = {
+    readonly agenda?: Agenda;
+    readonly onboarding?: OnboardingSession;
+    readonly projectRoot: string;
+    /** The App data directory, where the API keeps its state beside the Books. */
+    readonly stateDirectory: string;
+    readonly engineId: () => string | undefined;
+    readonly hostname: () => string | undefined;
+    readonly dashboardUrl: () => string | undefined;
+    readonly security: () => AppSecurityFacts | undefined;
+    /** `GET /security` → `ui`: the served engine UI (a verified bundle, or the engine's own page) and its last check. */
+    readonly ui: () => Record<string, unknown>;
+    readonly log?: (text: string, level: 'info' | 'warning' | 'error') => void;
+};
+/**
+ * A contract ID for an engine name: the name itself when it fits the opaque ID pattern, else a readable prefix and a
+ * digest.
+ *
+ * @private App engine API
+ */
+export declare function opaqueIdOf(name: string): string;
+/**
+ * The Reborn engine API (`@ptbk/engine-api` v1) over the project's own domain operations: agents are the project's
+ * Books (with their origin), chats are its `CHAT` threads with real authors, and members, passkeys and sessions are
+ * the gateway's. Every request is validated with the route's strict schemas, authorized by permission (denials change
+ * nothing), held to step-up where the route asks for it, and answered with exactly the route's response schema.
+ *
+ * @private App engine API
+ */
+export declare class EngineApi {
+    private readonly deps;
+    private readonly startedAt;
+    private readonly agentNames;
+    private stateOpening?;
+    constructor(deps: EngineApiDeps);
+    /** Project operations exist only after the regular service takes ownership. */
+    private get agenda();
+    /** The capabilities available at this stage of the engine's lifecycle. */
+    private get capabilities();
+    /** Serves one `/api/v1/...` request of a signed-in member. */
+    handle(request: Request, actor: Actor, access: AccessStore): Promise<Response>;
+    /** The API state, opened on first use (a failed open is retried by the next request). */
+    private state;
+    /** Validates, authorizes and runs one operation. */
+    private dispatch;
+    /** A domain error as a contract problem (never with internal details). */
+    private problemOf;
+    /** The project's agents (content, core and the engine's own) as API agents. */
+    private agents;
+    /** One API agent from its engine view and Book. */
+    private agentOf;
+    /** One agent by ID. */
+    private agent;
+    /** An agent's activity as the contract's status. */
+    private agentStatus;
+    /** A chat participant from an engine reference. */
+    private participant;
+    /** A chat's members, the User first. */
+    private members;
+    /** When a chat's Book was created and last changed. */
+    private chatTimes;
+    /** A chat summary as the contract's `Chat` (questions from the detail when given, else the unseen pings). */
+    private chat;
+    /** A participant reference without its display name. */
+    private authorRef;
+    /** One chat by name with its detail. */
+    private chatByName;
+    /** One stored message as the contract's `Message`. */
+    private message;
+    /** A thread's entries, oldest first: every member joins before writing, and a reply in progress streams last. */
+    private entries;
+    /** The 1-based position of a message ID of a chat, if it is one. */
+    private position;
+    /** A reply as deterministic deltas, then exactly one `completed` or `failed`. */
+    private replyStream;
+    /** What the event stream compares between changes. */
+    private eventDigest;
+    /** Live changes as `agent.status`, `agent.changed` and `chat.changed` events until the client leaves. */
+    private eventStream;
+    /** The members list entry of the contract. */
+    private member;
+    /** A passkey as the contract lists it. */
+    private passkey;
+    /** A session as the contract lists it. */
+    private session;
+    /** The engine settings the API exposes. */
+    private settings;
+    /** The security overview: versions, update state, certificate, relays, hostnames, the last heartbeat. */
+    private security;
+    /** The handlers by route ID. */
+    private readonly handlers;
+}
+/**
+ * Problems are plain objects; this keeps the type importable for handlers elsewhere.
+ *
+ * @private App engine API
+ */
+export type EngineApiProblem = ContractProblem;