ptbk 0.119.0-5 → 0.119.0-56

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,112 @@
-# Promptbook (`ptbk`)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/webgptorg/promptbook/reborn/2026-10/design/readme-wordmark.svg" alt="promptbook" width="570" />
+</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="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), Codex and Claude Code. 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.
+
+## 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/book/commitments.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Which document kinds a commitment belongs to (`both` = agents and tasks, `chat` = chats, `any` = every kind).
+ *
+ * @private Book language
+ */
+export type CommitmentScope = 'agent' | 'task' | 'both' | 'chat' | 'any';
+/**
+ * How a commitment's content is interpreted.
+ *
+ * - `declaration`: the opening type-and-name commitment (`AGENT`, `TASK`, `CHAT`); its content is the name
+ * - `instruction`: repeatable multi-line natural-language content
+ * - `control`: single-value control field (its value is the first line)
+ * - `repeatable-control`: control field that may appear several times (e.g. `TASK DONE`, `TASK DEPENDS ON`)
+ * - `flag`: marker without required content (e.g. `CLOSED`)
+ * - `historical`: former syntax kept only to diagnose and convert old sources (`ENTITY`)
+ *
+ * @private Book language
+ */
+export type CommitmentKind = 'declaration' | 'instruction' | 'control' | 'repeatable-control' | 'flag' | 'historical';
+/**
+ * Definition of one canonical commitment with its aliases.
+ *
+ * @private Book language
+ */
+export type CommitmentDefinition = {
+    /** Canonical uppercase keyword (may contain spaces). */
+    readonly keyword: string;
+    /** Alias keywords sharing the semantics. */
+    readonly aliases: readonly string[];
+    /** Document kinds accepting the commitment. */
+    readonly scope: CommitmentScope;
+    /** Content interpretation. */
+    readonly kind: CommitmentKind;
+    /** Short description used by help, Expert and diagnostics. */
+    readonly description: string;
+    /** Not a documented commitment: an unknown complete keyword preserved for round-tripping and diagnosed. */
+    readonly unknown?: boolean;
+};
+/**
+ * Values of `TASK PURPOSE` (written uppercase, so each value is part of the complete keyword).
+ *
+ * @private Book language
+ */
+export declare const TASK_PURPOSE_VALUES: readonly ["CONTENT", "SYSTEM", "UNDEFINED"];
+/**
+ * Every recognized commitment.
+ *
+ * @private Book language
+ */
+export declare const COMMITMENTS: readonly CommitmentDefinition[];
+/**
+ * Every accepted spelling, including aliases and compound withdrawals, for editors using the shared vocabulary.
+ *
+ * @private Book language
+ */
+export declare function commitmentKeywords(): string[];
+/**
+ * The commitment kind a compound withdrawal names (`DELETE RULE` → `RULE`), if any.
+ *
+ * @private Book language
+ */
+export declare function withdrawnKeyword(written: string): string | undefined;
+/**
+ * A commitment keyword found at the beginning of a line.
+ *
+ * @private Book language
+ */
+export type KeywordMatch = {
+    /** Definition of the complete keyword (a synthetic `unknown` definition for undocumented keywords). */
+    readonly definition: CommitmentDefinition;
+    /** Keyword as written (complete uppercase word sequence). */
+    readonly written: string;
+    /** Content after the keyword on the same line (trimmed). */
+    readonly content: string;
+};
+/**
+ * Recognizes a commitment at the beginning of a line by the common boundary rule.
+ *
+ * The keyword is the maximal sequence of all-uppercase words at column zero, separated by spaces, with at least three
+ * letters in total. A word containing lowercase letters, digits, punctuation or a reference begins the content; once
+ * content begins, later uppercase words belong to it. The complete keyword is looked up as a whole: an unknown keyword
+ * is never shortened to a known prefix (`TASK SOMETHING` is not `TASK`).
+ *
+ * @private Book language
+ */
+export declare function matchCommitmentKeyword(line: string): KeywordMatch | undefined;
+/**
+ * Whether a line would start a commitment (writers escape such lines in literal content).
+ *
+ * @private Book language
+ */
+export declare function startsCommitment(line: string): boolean;

package/dist/book/commitments.js

@@ -0,0 +1,147 @@
+/**
+ * Values of `TASK PURPOSE` (written uppercase, so each value is part of the complete keyword).
+ *
+ * @private Book language
+ */
+export const TASK_PURPOSE_VALUES = ['CONTENT', 'SYSTEM', 'UNDEFINED'];
+/**
+ * Every recognized commitment.
+ *
+ * @private Book language
+ */
+export const COMMITMENTS = [
+    { keyword: 'AGENT', aliases: [], scope: 'agent', kind: 'declaration', description: 'Opening declaration of an agent: `AGENT <name>`.' },
+    { keyword: 'TASK', aliases: [], scope: 'task', kind: 'declaration', description: 'Opening declaration of a task: `TASK <name>`.' },
+    { keyword: 'CHAT', aliases: [], scope: 'chat', kind: 'declaration', description: 'Opening declaration of a chat: `CHAT <name>`.' },
+    { keyword: 'ENTITY', aliases: ['ENTITY AGENT', 'ENTITY TASK', 'ENTITY CHAT'], scope: 'any', kind: 'historical', description: 'Former kind declaration after a plain name line; convert with `ptbk migrate`.' },
+    { keyword: 'LINK', aliases: ['LINKS'], scope: 'any', kind: 'repeatable-control', description: 'Directed reference to another agent, task or chat (no scheduling or authority).' },
+    { keyword: 'CHAT MEMBER', aliases: [], scope: 'chat', kind: 'repeatable-control', description: 'Participant of a chat (`@User` and one or more agents, the first being the main agent; or the two agents of a consultation). A joining agent is appended before its first message.' },
+    { keyword: 'CHAT MESSAGE', aliases: [], scope: 'chat', kind: 'instruction', description: 'One durable message: `CHAT MESSAGE <sender> <timestamp> [progress|final]` followed by its text.' },
+    { keyword: 'CHAT TITLE', aliases: [], scope: 'chat', kind: 'repeatable-control', description: 'Evolving human-facing topic title (the latest wins); never renames the chat, whose `CHAT` name stays its identity.' },
+    { keyword: 'CHAT STATUS', aliases: [], scope: 'chat', kind: 'repeatable-control', description: '`open`, `waiting-for-user` or `resolved`, appended at each actual transition (the last valid one wins; without one a chat is open).' },
+    { keyword: 'PERSONA', aliases: ['PERSONAE'], scope: 'agent', kind: 'instruction', description: 'Role and identity of the agent.' },
+    { keyword: 'GOAL', aliases: ['GOALS'], scope: 'both', kind: 'instruction', description: "An agent's lasting objective (also used for goal discovery), or a task's bounded work and intended result." },
+    { keyword: 'RULE', aliases: ['RULES'], scope: 'both', kind: 'instruction', description: 'Behavioral constraint (task rules apply only to that task).' },
+    { keyword: 'KNOWLEDGE', aliases: [], scope: 'agent', kind: 'instruction', description: 'Inline knowledge or a reference to relevant material.' },
+    { keyword: 'STYLE', aliases: ['STYLES'], scope: 'agent', kind: 'instruction', description: 'Style of communication or output.' },
+    { keyword: 'LANGUAGE', aliases: ['LANGUAGES'], scope: 'agent', kind: 'instruction', description: 'Language(s) of responses.' },
+    { keyword: 'WRITING SAMPLE', aliases: [], scope: 'agent', kind: 'instruction', description: 'Example of the desired writing style.' },
+    { keyword: 'WRITING RULES', aliases: ['WRITING RULE'], scope: 'agent', kind: 'instruction', description: 'Specific writing conventions.' },
+    { keyword: 'SAMPLE', aliases: ['EXAMPLE'], scope: 'agent', kind: 'instruction', description: 'Representative interaction or output.' },
+    { keyword: 'FORMAT', aliases: ['FORMATS'], scope: 'agent', kind: 'instruction', description: 'Requested output format.' },
+    { keyword: 'TEMPLATE', aliases: ['TEMPLATES'], scope: 'agent', kind: 'instruction', description: 'Reusable response/output pattern.' },
+    { keyword: 'FROM', aliases: [], scope: 'agent', kind: 'control', description: 'Single inheritance parent (default Adam).' },
+    { keyword: 'IMPORT', aliases: ['IMPORTS'], scope: 'agent', kind: 'repeatable-control', description: 'In-place inclusion of another agent\'s instructions.' },
+    {
+        keyword: 'MODEL',
+        aliases: ['MODELS'],
+        scope: 'any',
+        kind: 'instruction',
+        description: 'Allowed execution combinations (`harness=… model=… thinking=… provider=… origin=… runtime=…`; fields on one line apply together, lines are alternatives) of an agent, task or chat, independent of the tool/account.',
+    },
+    { keyword: 'ACTION', aliases: ['ACTIONS'], scope: 'agent', kind: 'instruction', description: 'Actions/tools the role intends to use.' },
+    { keyword: 'TEAM', aliases: [], scope: 'agent', kind: 'instruction', description: 'Whom the agent may consult and when.' },
+    { keyword: 'OPEN', aliases: [], scope: 'agent', kind: 'instruction', description: 'Permits learning, optionally with natural-language limits.' },
+    { keyword: 'CLOSED', aliases: [], scope: 'agent', kind: 'flag', description: 'Prohibits automatic learning changes.' },
+    { keyword: 'NOTE', aliases: ['NOTES', 'COMMENT', 'NONCE', 'TODO'], scope: 'any', kind: 'instruction', description: 'Non-executable commentary.' },
+    { keyword: 'DELETE', aliases: ['CANCEL', 'DISCARD', 'REMOVE'], scope: 'agent', kind: 'instruction', description: 'Withdraws an identified earlier commitment.' },
+    { keyword: 'DICTIONARY', aliases: [], scope: 'agent', kind: 'instruction', description: 'Terminology for the role\'s work.' },
+    { keyword: 'TASK ID', aliases: [], scope: 'task', kind: 'control', description: 'Legacy historical metadata; never identity (the task name is).' },
+    { keyword: 'TASK AGENT', aliases: [], scope: 'task', kind: 'control', description: 'Responsible agent.' },
+    { keyword: 'TASK HARNESS', aliases: [], scope: 'task', kind: 'control', description: 'Former harness requirement, replaced by `MODEL harness=…` (honored and diagnosed until converted).' },
+    { keyword: 'TASK MODEL', aliases: [], scope: 'task', kind: 'control', description: 'Former model requirement, replaced by `MODEL model=…` (honored and diagnosed until converted).' },
+    { keyword: 'TASK THINKING LEVEL', aliases: [], scope: 'task', kind: 'control', description: 'Former thinking requirement, replaced by `MODEL thinking=…` (honored and diagnosed until converted).' },
+    { keyword: 'TASK PRIORITY', aliases: [], scope: 'task', kind: 'control', description: 'Nonnegative number or textual importance; higher first.' },
+    { keyword: 'TASK AFTER', aliases: [], scope: 'task', kind: 'control', description: 'Inclusive earliest permitted start.' },
+    { keyword: 'TASK DUE DATE', aliases: [], scope: 'task', kind: 'control', description: 'Desired completion deadline (not a start condition).' },
+    { keyword: 'TASK DONE', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Completion stamp with explicit timezone (historical after a later `TASK REOPEN`).' },
+    { keyword: 'TASK STATUS', aliases: [], scope: 'task', kind: 'control', description: 'Appended transition: `todo`, `not-ready`, `failed`, `cancelled` or `retired`; the last valid one is effective.' },
+    { keyword: 'TASK CHANGE', aliases: [], scope: 'task', kind: 'instruction', description: 'Chronological amendment `TASK CHANGE <timestamp> <task|occurrence|future> [<chat reference>]`; the lines below state the requested change, and later typed controls belong to it.' },
+    { keyword: 'TASK REOPEN', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Reopens the same work `TASK REOPEN <timestamp> [<chat reference>]`, keeping earlier completions as history.' },
+    { keyword: 'TASK REPEAT', aliases: [], scope: 'task', kind: 'control', description: 'Positive fixed recurrence interval.' },
+    { keyword: 'TASK DEPENDS ON', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Prerequisite task references.' },
+    { keyword: 'TASK PARENT', aliases: [], scope: 'task', kind: 'control', description: 'Parent task reference (no implied ordering).' },
+    { keyword: 'TASK RUNNER', aliases: [], scope: 'task', kind: 'repeatable-control', description: 'Opaque any-of routing selectors from Markdown.' },
+    { keyword: 'TASK NOTE', aliases: [], scope: 'task', kind: 'instruction', description: 'Explanatory task metadata.' },
+    { keyword: 'TASK ORIGIN', aliases: [], scope: 'task', kind: 'control', description: 'Provenance of the task.' },
+    {
+        keyword: 'TASK PURPOSE',
+        // The uppercase values join the keyword under the boundary rule, so each complete spelling is an alias.
+        aliases: TASK_PURPOSE_VALUES.map((value) => `TASK PURPOSE ${value}`),
+        scope: 'task',
+        kind: 'repeatable-control',
+        description: 'Project-relative purpose `TASK PURPOSE CONTENT|SYSTEM|UNDEFINED`, appended at each actual change (earlier values stay in the Book; the last valid one is effective). Presentation only: no priority, permission or executor.',
+    },
+];
+/**
+ * Lookup from every accepted keyword spelling to its definition.
+ */
+const KEYWORD_LOOKUP = new Map([
+    ...COMMITMENTS.flatMap((definition) => [definition.keyword, ...definition.aliases].map((keyword) => [keyword, definition])),
+    // `DELETE RULE …` is one complete keyword: the withdrawal names the kind of the commitment it withdraws.
+    ...COMMITMENTS.filter((definition) => definition.kind === 'instruction' && definition.keyword !== 'DELETE').flatMap((target) => ['DELETE', 'CANCEL', 'DISCARD', 'REMOVE'].flatMap((withdraw) => [target.keyword, ...target.aliases].map((keyword) => [`${withdraw} ${keyword}`, COMMITMENTS.find((definition) => definition.keyword === 'DELETE')]))),
+]);
+/**
+ * Every accepted spelling, including aliases and compound withdrawals, for editors using the shared vocabulary.
+ *
+ * @private Book language
+ */
+export function commitmentKeywords() {
+    return [...KEYWORD_LOOKUP.keys()];
+}
+/**
+ * The commitment kind a compound withdrawal names (`DELETE RULE` → `RULE`), if any.
+ *
+ * @private Book language
+ */
+export function withdrawnKeyword(written) {
+    const [, ...rest] = written.trim().split(/\s+/);
+    if (!rest.length)
+        return undefined;
+    const target = KEYWORD_LOOKUP.get(rest.join(' '));
+    return target && target.keyword !== 'DELETE' ? target.keyword : undefined;
+}
+/**
+ * One all-uppercase word of a commitment keyword (letters only; digits, punctuation or lowercase begin content).
+ */
+const KEYWORD_WORD = /^\p{Lu}[\p{Lu}\p{M}]*$/u;
+/**
+ * Fewest letters a complete keyword needs (so `A`, `I` or `AI` starting prose never begin a commitment).
+ */
+const MIN_KEYWORD_LETTERS = 3;
+/**
+ * Recognizes a commitment at the beginning of a line by the common boundary rule.
+ *
+ * The keyword is the maximal sequence of all-uppercase words at column zero, separated by spaces, with at least three
+ * letters in total. A word containing lowercase letters, digits, punctuation or a reference begins the content; once
+ * content begins, later uppercase words belong to it. The complete keyword is looked up as a whole: an unknown keyword
+ * is never shortened to a known prefix (`TASK SOMETHING` is not `TASK`).
+ *
+ * @private Book language
+ */
+export function matchCommitmentKeyword(line) {
+    if (!/^\p{Lu}/u.test(line))
+        return undefined;
+    const words = [];
+    let offset = 0;
+    for (const word of line.matchAll(/\S+/g)) {
+        if (!KEYWORD_WORD.test(word[0]))
+            break;
+        words.push(word[0]);
+        offset = word.index + word[0].length;
+    }
+    const keyword = words.join(' ');
+    if (keyword.replace(/\s/g, '').length < MIN_KEYWORD_LETTERS)
+        return undefined;
+    const definition = KEYWORD_LOOKUP.get(keyword) ?? { keyword, aliases: [], scope: 'any', kind: 'instruction', description: 'Unknown commitment (preserved without effect).', unknown: true };
+    return { definition, written: line.slice(0, offset), content: line.slice(offset).trim() };
+}
+/**
+ * Whether a line would start a commitment (writers escape such lines in literal content).
+ *
+ * @private Book language
+ */
+export function startsCommitment(line) {
+    return matchCommitmentKeyword(line) !== undefined;
+}
+//# sourceMappingURL=commitments.js.map

package/dist/book/commitments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitments.js","sourceRoot":"","sources":["../../src/book/commitments.ts"],"names":[],"mappings":"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"}

package/dist/book/convert.d.ts

@@ -0,0 +1,36 @@
+import { type EntityKind } from './parse.js';
+/**
+ * Conventional folder of a source, the documented context former syntax relied on for its kind.
+ *
+ * @private Book conversion
+ */
+export type LegacyLocation = 'agents' | 'tasks' | 'chats' | undefined;
+/**
+ * Outcome of converting one source.
+ *
+ * @private Book conversion
+ */
+export type BookConversion = {
+    readonly kind: 'unchanged';
+} | {
+    readonly kind: 'converted';
+    readonly entity: EntityKind;
+    readonly name: string;
+    readonly content: string;
+    readonly notes: readonly string[];
+} | {
+    readonly kind: 'blocked';
+    readonly reason: string;
+};
+/**
+ * Converts a Book in former syntax into the canonical form, preserving its name, content, links and history.
+ *
+ * Former syntax: a plain name line (kind from `ENTITY` or, as documented then, the conventional folder), `ENTITY`
+ * lines, a `TASK <name>` header followed by an introduction, and text after one-line controls. Descriptive text without
+ * an owner moves under GOAL (tasks), PERSONA (agents, where it was part of the role) or NOTE (chats); lines the new
+ * boundary rule would read as commitments are escaped literally. The name is kept exactly (no new date); an ambiguous
+ * kind or a name that cannot follow a keyword blocks the conversion instead of guessing.
+ *
+ * @private Book conversion
+ */
+export declare function convertLegacyBook(source: string, location: LegacyLocation): BookConversion;

package/dist/book/convert.js

@@ -0,0 +1,156 @@
+import { COMMITMENTS, matchCommitmentKeyword } from './commitments.js';
+import { fenceMarker, parseBook } from './parse.js';
+import { DECLARATION_KEYWORD, declarationName, renderCommitment } from './write.js';
+/**
+ * Keyword spellings the former parser recognized, longest first (it matched known keywords as prefixes).
+ */
+const FORMER_KEYWORDS = COMMITMENTS.filter((definition) => definition.kind !== 'declaration' || definition.keyword === 'TASK')
+    .flatMap((definition) => [definition.keyword, ...definition.aliases])
+    .sort((a, b) => b.length - a.length);
+/**
+ * How the former parser read a line: a known keyword followed by whitespace or the end of the line.
+ */
+function formerMatch(line) {
+    for (const keyword of FORMER_KEYWORDS) {
+        if (!line.startsWith(keyword))
+            continue;
+        const rest = line.slice(keyword.length);
+        if (rest !== '' && !/^\s/.test(rest))
+            continue;
+        return { keyword, content: rest.trim() };
+    }
+    return undefined;
+}
+/**
+ * Canonical keyword of a known spelling (alias resolved).
+ */
+function canonicalKeyword(written) {
+    return COMMITMENTS.find((definition) => definition.keyword === written || definition.aliases.includes(written))?.keyword ?? written;
+}
+/**
+ * Commitment that receives descriptive text without an owner in former syntax.
+ */
+const DESCRIPTION_KEYWORD = { task: 'GOAL', agent: 'PERSONA', chat: 'NOTE' };
+/**
+ * Converts a Book in former syntax into the canonical form, preserving its name, content, links and history.
+ *
+ * Former syntax: a plain name line (kind from `ENTITY` or, as documented then, the conventional folder), `ENTITY`
+ * lines, a `TASK <name>` header followed by an introduction, and text after one-line controls. Descriptive text without
+ * an owner moves under GOAL (tasks), PERSONA (agents, where it was part of the role) or NOTE (chats); lines the new
+ * boundary rule would read as commitments are escaped literally. The name is kept exactly (no new date); an ambiguous
+ * kind or a name that cannot follow a keyword blocks the conversion instead of guessing.
+ *
+ * @private Book conversion
+ */
+export function convertLegacyBook(source, location) {
+    const document = parseBook(source);
+    if (document.kind === 'empty')
+        return { kind: 'unchanged' };
+    const legacy = document.legacy;
+    const formerTaskHeader = !document.declaredKind && /^TASK\s/.test(document.lines[document.headerLine] ?? '');
+    if (!legacy && !formerTaskHeader)
+        return { kind: 'unchanged' };
+    if (legacy?.uppercaseName)
+        return { kind: 'blocked', reason: `the name "${document.name}" starts with an all-uppercase word, which cannot follow a declaration keyword; choose a representable spelling (e.g. "${declarationName(document.name)}") and edit the first line explicitly` };
+    // Kind: the canonical declaration, else ENTITY, else the documented folder convention.
+    const header = document.lines[document.headerLine];
+    const former = formerMatch(header);
+    let entity = document.declaredKind ?? (former?.keyword === 'TASK' ? 'task' : undefined);
+    if (legacy?.entity === 'conflict' || legacy?.entity === 'unsupported')
+        return { kind: 'blocked', reason: 'its ENTITY declarations are contradictory or unsupported; state the kind explicitly' };
+    if (legacy?.entity) {
+        if (entity && entity !== legacy.entity)
+            return { kind: 'blocked', reason: `its header declares a ${entity} but ENTITY says ${legacy.entity}` };
+        entity = legacy.entity;
+    }
+    const folderKind = location === 'agents' ? 'agent' : location === 'tasks' ? 'task' : location === 'chats' ? 'chat' : undefined;
+    if (!entity)
+        entity = folderKind;
+    if (!entity)
+        return { kind: 'blocked', reason: 'its kind is unknown (no ENTITY and not in agents/, tasks/ or chats/); start it with AGENT, TASK or CHAT explicitly' };
+    if (folderKind && legacy?.entity && folderKind !== legacy.entity)
+        return { kind: 'blocked', reason: `it declares a ${legacy.entity} but lies in ${location}/; move it or state the kind explicitly` };
+    const name = former?.keyword === 'TASK' && !document.declaredKind ? former.content : document.name;
+    if (!name)
+        return { kind: 'blocked', reason: 'it has no name' };
+    if (declarationName(name) !== name.replace(/\s+/g, ' ').trim())
+        return { kind: 'blocked', reason: `the name "${name}" needs an explicit spelling decision` };
+    // Re-read the body as the former parser did: only known keywords started commitments.
+    const notes = [];
+    const loose = [];
+    const body = [];
+    let fence;
+    let section;
+    let introduction = true;
+    const escapeContent = (line, message) => {
+        // Former message bodies already used the backslash escape; other content did not.
+        if (!message && line.startsWith('\\'))
+            return `\\${line}`;
+        if (!message && fenceMarker(line) === undefined && matchCommitmentKeyword(line))
+            return `\\${line}`;
+        if (message && !line.startsWith('\\') && matchCommitmentKeyword(line))
+            return `\\${line}`;
+        return line;
+    };
+    for (let index = document.headerLine + 1; index < document.lines.length; index++) {
+        const line = document.lines[index];
+        const marker = fenceMarker(line);
+        const match = fence || marker ? undefined : formerMatch(line);
+        if (fence) {
+            if (marker && marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker)
+                fence = undefined;
+        }
+        else if (marker)
+            fence = marker;
+        if (match) {
+            introduction = false;
+            const keyword = canonicalKeyword(match.keyword);
+            const definition = COMMITMENTS.find((item) => item.keyword === keyword);
+            const single = definition.kind === 'control' || definition.kind === 'repeatable-control' || definition.kind === 'flag' || definition.kind === 'historical';
+            section = { keyword, single, message: keyword === 'CHAT MESSAGE' };
+            if (keyword === 'ENTITY') {
+                notes.push('removed the redundant ENTITY declaration');
+                continue;
+            }
+            if (keyword === 'TASK') {
+                // A later legacy `TASK …` line never declared anything; keep its text as content.
+                loose.push(match.content);
+                continue;
+            }
+            const reread = matchCommitmentKeyword(line);
+            if (reread && !reread.definition.unknown && reread.definition.keyword === keyword && reread.content === match.content)
+                body.push(line);
+            else
+                body.push(...renderCommitment(match.keyword, match.content));
+            continue;
+        }
+        if (introduction || section?.single) {
+            if (line.trim() || loose.length)
+                loose.push(fence || marker ? line : line);
+            continue;
+        }
+        body.push(fence || marker ? line : escapeContent(line, Boolean(section?.message)));
+    }
+    while (loose.length && !loose[loose.length - 1].trim())
+        loose.pop();
+    const description = loose.join('\n').trim();
+    const lines = [`${DECLARATION_KEYWORD[entity]} ${name.replace(/\s+/g, ' ').trim()}`];
+    if (description) {
+        lines.push(...renderCommitment(DESCRIPTION_KEYWORD[entity], description));
+        notes.push(`moved descriptive text under ${DESCRIPTION_KEYWORD[entity]}`);
+    }
+    while (body.length && !body[0].trim())
+        body.shift();
+    if (body.length && entity !== 'chat' && description)
+        lines.push('');
+    lines.push(...body);
+    while (lines.length && !lines[lines.length - 1].trim())
+        lines.pop();
+    const content = `${lines.join(document.newline)}${document.newline}`;
+    const check = parseBook(content);
+    if (check.kind !== entity || check.name !== name.replace(/\s+/g, ' ').trim()) {
+        return { kind: 'blocked', reason: `the converted Book would not read back as the same ${entity} (${check.diagnostics.map((diagnostic) => diagnostic.message).join(' ')})` };
+    }
+    return { kind: 'converted', entity, name: check.name, content, notes };
+}
+//# sourceMappingURL=convert.js.map