ptbk 0.119.0-16 → 0.119.0-21

package/dist/expert/_main.md

@@ -1,91 +1,106 @@
 # Promptbook (`ptbk`)
 
-Promptbook is one npm package, `ptbk`, providing the `ptbk` command-line utility. It operates agents over a selected project directory in Git. Agents, tasks and project material are readable files; versioned `ptbk.json` holds project configuration, Git-ignored `.ptbk/` holds local runtime state, and root-level `traces/<task-id>/` holds task audit evidence, without a database.
+Promptbook is one npm package, `ptbk`, providing the `ptbk` command-line utility. It operates a Git-backed project of three Book entities: **agents**, **tasks** and **chats**. Every canonical Book starts with `AGENT <name>`, `TASK <name>` or `CHAT <name>`; all share commitment syntax. The normalized opening name content is logical identity, with no separate generated IDs or filename-based logical keys. New system-created task/chat names include readable creation date/time to prevent collisions, without mandatory timestamp grammar. `chats/` holds conversations, versioned `ptbk.json` holds defaults, ignored `.ptbk/` holds runtime state and `traces/<task-file-basename>/` holds evidence under the literal task filename without `.book` or legacy `.md`.
 
-Initialization is finite, attended technical setup. Its first new-project input is the user's intent, preserved verbatim with linked assets in `specs/_initial.md`. Init creates an ordinary Expert task referring to that specification, prepares selected harnesses and real checks, commits setup by default, and automatically starts the agenda as a background service. Project-specific content is created by the normal first task, not by a separate implementation phase inside init. The wizard returns without waiting for task completion or opening a dashboard; `ptbk dashboard` is its primary next-action hint.
+Initialization is finite attended technical setup. Its first new-project input is user intent, preserved verbatim with linked assets in `specs/_initial.md`. Init creates an ordinary Expert bootstrap referring to it, prepares selected harnesses/checks and missing core roles, commits setup by default and automatically starts the background agenda. Project content comes from that ordinary task, not an implementation phase inside init. The wizard returns without waiting for task completion or opening a dashboard; `ptbk dashboard` is its primary next-action hint.
 
-Once started, the agenda is intended to run unattended for extended periods, progressing useful authorized work rather than remaining alive but silently waiting for routine approvals. It fills missing routing through Manager, executes one task at a time, creates and processes follow-ups, and discovers useful goal-driven work when the backlog is empty. Recoverable problems are handled automatically within bounds; human involvement is exceptional and explicit. Versioned changes from authoring and execution commit by default with `PTBK: ` subjects and applicable task IDs. Explicit `--no-commit` is the exception; `ptbk run` is the finite, explicitly configured queue workflow.
+Every engine owns one concrete project directory; exclusive locking prevents two owners even across different installations. It runs with zero or many observing clients. A dashboard is a lightweight view/controller, not an engine or independent scheduler: opening/closing it never starts/stops the service. Shared lifecycle states are **`running`, `pausing`, `pause`, `stopping`**. Pause/ordinary stop drain current work without starting another task; pending requests can be cancelled or changed. Force stop is immediate, with best-effort owner cleanup when handled internally; an external hard kill has no cleanup guarantee. CLI, terminal, browser and API use the same engine operations.
 
-Functional setup and its UX are separate specification aspects. Init/add use finite wizards; init has visible step progress, Expert as a procedural visual guide and a brief success celebration. `ptbk dashboard` attaches a continuous, paneled terminal control view with recognizable agents and no overall completion. Suitable terminals default to rich presentation, with raw output available throughout. Terminal, lightweight browser SPA and independently usable API control the same process. HTTP includes protected remote tunneling by default, so a phone can use the displayed pairing QR from another network; `--no-tunnel` keeps access local. Genuine human requests remain the most prominent information without becoming routine prerequisites for progress.
+`ptbk dashboard --global` is a separate continuously refreshed host-wide table of running project engines, across installation/version boundaries and independent of current directory. It stays open with zero entries, notices later starts and attaches to a selected project dashboard without `cd` or starting a worker. There is no global engine. Ordinary project dashboard entry still reports a missing service actionably.
 
-Every task has a stable ID linking its source, Git commits and trace directory. Traces retain available harness output, event logs and enabled browser recordings. Initialization saves separate trace-commit, video-ignore and video-recording choices in `ptbk.json`; `.ptbk/` and browser sessions remain ignored independently.
+The agenda is intended to progress useful authorized work unattended for extended periods, not remain alive while silently waiting for routine approvals. It fills missing routing through Manager, executes one task at a time, processes follow-ups and discovers useful goal-driven work when no backlog remains, while respecting deliberate pause/stop intent. Recoverable problems are handled automatically within bounds; human involvement is exceptional. Versioned authoring/execution changes commit by default with `PTBK: ` subjects and applicable name correlation. Explicit `--no-commit` is the exception; `ptbk run` is a finite configured queue workflow.
+
+Functional contracts and UX are separate aspects. Init/add use finite wizards; init has visible progress, Expert as visual guide and a brief success celebration. The project dashboard has distinct panels and prominent lifecycle controls; detailed effective harness/model/thinking configuration and browser profile/diagnostics are initially collapsed, keyboard-accessible panels. Browser diagnosis/recovery is automatic by default, with safe manual recheck/retry/restart controls. Rich terminals default to pretty presentation with raw alternatives. Terminal, lightweight browser SPA and independently usable API control the same engine. HTTP includes protected remote access by default; `--no-tunnel` keeps it local.
+
+**Chatter** is an editable core agent and the default conversational entry for manually discussing/directing a project. New chat first offers Chatter (Enter) or another agent; only the latter expands all valid targets. Its initial TEAM includes the other initialized roles; it handles basic authorized actions and consults/delegates to specialists through ordinary mechanisms. Existing chats and waiting questions retain their real authors. Fixer remains an ordinary OPEN maintenance agent. Human-facing messages commit individually; internal task consultations join their task result, while conversation-scoped consultations use ordinary scoped authoring persistence.
+
+Task logical identity, source/Git provenance and evidence storage remain distinct. Trace directories exactly match source basenames, not normalized TASK names or opaque keys; evidence records declared names and source revisions to preserve history across renames. Traces retain actually available harness output, events and enabled browser recordings. Init saves separate trace-commit, video-ignore and video-recording choices; `.ptbk/` and browser sessions stay ignored independently.
 
 ## Reading this specification
 
-The [whitepaper](whitepaper.md) explains APT principles and clearly identified long-term directions. The files below define concrete target behavior, not a claim that it has already been implemented. Future capabilities in the whitepaper do not implicitly become product requirements.
+The [whitepaper](whitepaper.md) explains APT principles and clearly identified long-term directions. The files below define concrete target behavior, not a claim of implementation. Future whitepaper capabilities do not implicitly become requirements.
 
-Keep specifications in English, concise and focused on observable behavior, important contracts and invariants. Leave internal representations, algorithms and module organization to implementation unless they are themselves necessary product constraints. Preserve useful behavior, not incidental implementation detail. Keep functional contracts separate from visual presentation, with cross-links rather than duplicating both in a single primary document.
+Keep specifications in English, concise and focused on observable behavior, important contracts and invariants. Leave internal representations, algorithms and module organization to implementation unless they are necessary product constraints. Preserve useful behavior, not incidental implementation detail. Separate functional contracts from visual presentation and cross-link instead of duplicating their full definitions.
 
-[Dictionary](dictionary.md) · [Agents](agents/_index.md) · [Book language](book-language/_index.md) · [References and lookup](book-language/references.md) · [Commitment index](book-language/commitments/_index.md)
+[Project model](concepts/project-model.md) · [Engine/project evolution](concepts/engine-and-project.md) · [Dictionary](dictionary.md) · [Agents](agents/_index.md) · [Book language](book-language/_index.md) · [References and lookup](book-language/references.md) · [Commitment index](book-language/commitments/_index.md)
 
 ## Installation and operation
 
 - [Installation](cli/installation.md): Global/local package and destination-specific dependency setup.
 - [Checks and publication on GitHub Actions](cli/releasing.md): Required hosted validation and verified releases.
 - [Engine updates](cli/updates.md): Update the invoked installation, preserve setup input and rerun.
-- [Commands](cli/cli.md): Command surface and options.
-- [Configuration](cli/configuration.md): `ptbk.json`, defaults and temporary CLI overrides.
-- [Workspace](cli/workspace.md): Project, source paths, specifications, traces and `.ptbk/`.
-- [Initialization](cli/initialization.md): Technical setup, original input preservation and automatic background start.
-- [First runnable task](cli/first-task.md): Ordinary Expert bootstrap from the initial specification, with no duplicate starter.
-- [Nested projects](cli/nested-projects.md): Explicit Git boundaries for new child projects.
-- [Finite run](cli/run.md): Execute existing work with one configuration.
+- [Commands](cli/cli.md): Command surface and options, including pause/resume, force stop and global dashboard.
+- [Configuration](cli/configuration.md): `ptbk.json`, defaults and temporary overrides.
+- [Workspace](cli/workspace.md): Project/source paths, specifications, traces, runtime and external discovery metadata.
+- [Initialization](cli/initialization.md): Technical setup, original input preservation, core agents and automatic background start.
+- [First runnable task](cli/first-task.md): Ordinary Expert bootstrap without a duplicate starter.
+- [Nested projects](cli/nested-projects.md): Explicit Git boundaries for child projects.
+- [Finite run](cli/run.md): Existing work with one configuration.
 - [Start](cli/start.md): Automatic work progression, ongoing operation and startup output.
-- [Unattended operation](cli/autonomous-operation.md): A primary product invariant: sustained authorized work, automatic recovery and exceptional human involvement.
-- [Process modes](cli/process-modes.md): Daemon/foreground placement, attached clients and one-shot lifecycle commands.
+- [Unattended operation](cli/autonomous-operation.md): Sustained authorized work, recovery and exceptional human involvement.
+- [Process modes](cli/process-modes.md): Engine placement and independent observing clients.
+- [Service lifecycle](cli/service-lifecycle.md): Four states, draining, cancellation, restart, force stop and signal semantics.
+- [Project locking](cli/locking.md): One engine per project and owner-only controlled cleanup.
 - [Startup persistence](cli/persistence.md): Recovery across operating-system restarts.
 
 ## Controls and interaction
 
-- [CLI presentation and interaction](cli/interactive-ui.md): Pretty/raw output, finite wizards, live dashboards and one-shot results.
-- [Initialization experience](cli/initialization-ui.md): Intent-first flow, step totals, the Expert guide and a finite celebratory finish.
-- [Rich terminal composer](cli/rich-input.md): Multiline input, compact pasted blocks, images and preserved attachment payloads.
-- [Help, about and version](cli/help.md): Command-scoped pretty/raw help and the actual running engine version.
-- [Shared controls](cli/controls.md): One runtime control model with equivalent client capabilities.
-- [Project status view](cli/status-view.md): Live/snapshot state, prominent requests and truthful local/remote connection information.
-- [Dashboard panel layout](cli/dashboard-layout.md): Separate attention, work, queue, activity and connection regions.
-- [Terminal dashboard](cli/terminal.md): Attach with `ptbk dashboard`, observe live state and use keyboard controls.
-- [Service API](cli/api.md): Independently usable authenticated status and control endpoints.
-- [Browser dashboard](cli/dashboard.md): Lightweight JavaScript SPA at `/`, consuming the service API.
-- [Remote access](cli/remote-access.md): Default protected tunnel, mobile pairing, opt-out and lifecycle.
-- [Tunnel provider decision](cli/tunnel-options.md): Researched alternatives and development/stable-hostname tradeoffs.
-- [User interactions](cli/user-interactions.md): Exceptional, highly visible and actionable human requests and response semantics.
-- [Channels](cli/channels.md): Terminal, CLI answers, browser app and API.
-- [Browser](cli/browser.md): One independently configured browser/profile per project, with task-linked recordings.
+- [CLI presentation and interaction](cli/interactive-ui.md): Pretty/raw output, finite wizards, live views and one-shot results.
+- [Initialization experience](cli/initialization-ui.md): Intent-first flow, step totals, Expert guide and finite celebration.
+- [Rich terminal composer](cli/rich-input.md): Multiline input, pasted blocks, images and preserved attachments.
+- [Help, about and version](cli/help.md): Scoped help and actual running version.
+- [Shared controls](cli/controls.md): One engine-owned control model across clients.
+- [Project status view](cli/status-view.md): Live/snapshot state, prominent requests and truthful connection data.
+- [Dashboard panel layout](cli/dashboard-layout.md): Attention, work, visible lifecycle controls and supporting panels.
+- [Dashboard details](cli/dashboard-details.md): Collapsible actual execution configuration and browser diagnostics/recovery UI.
+- [Terminal dashboard](cli/terminal.md): Independent project attachment and keyboard controls.
+- [Global dashboard](cli/global-dashboard.md): Host-wide registration/discovery, live table, zero-service state and project attachment.
+- [Service API](cli/api.md): Independently usable authenticated status/control operations.
+- [Browser dashboard](cli/dashboard.md): Lightweight JavaScript SPA consuming the same service API.
+- [Remote access](cli/remote-access.md): Protected tunnel, mobile pairing, opt-out and lifecycle.
+- [Tunnel provider decision](cli/tunnel-options.md): Alternatives and stable-hostname tradeoffs.
+- [Chats](cli/chats.md): Durable named conversations, author attribution and persistence boundaries.
+- [Chat UI](cli/chat-ui.md): Chatter-first entry, explicit alternatives, existing threads and unread/actionable states.
+- [Human interactions](cli/user-interactions.md): Attributed waiting chats and once-only replies.
+- [Channels](cli/channels.md): Terminal, CLI, browser and API.
+- [Browser](cli/browser.md): Four profile sources, effective-profile inspection, safe ownership and automatic/manual recovery.
 
 ## Agents and work
 
 - [Agent context](cli/agent-context.md): Effective role, task and project instructions.
-- [Agent visual identity](agents/visual-identity.md): Coder-inspired mascot badges, stable identity and truthful activity.
-- [Harnesses](cli/harnesses.md): Complete selected setup, global installations, authentication and execution.
+- [Agent visual identity](agents/visual-identity.md): Mascot badges, name identity and truthful activity.
+- [Chatter](agents/chatter.md): Default core conversational entry, initialized TEAM and ordinary specialist delegation.
+- [Fixer](agents/fixer.md): OPEN core introspection, repair and human chats.
+- [Harnesses](cli/harnesses.md): Selected setup, global installations, authentication and execution.
 - [Harness plugins](cli/harness-plugins.md): Common setup/execution/evidence contract and featured/More presentation.
-- [Harness updates](cli/harness-updates.md): Selected setup updates and safe ongoing maintenance.
-- [TEAM consultations](cli/team.md): Cooperation within one task.
-- [Authoring and saving](cli/authoring.md): Commit add and other approved versioned changes before dispatch.
+- [Harness updates](cli/harness-updates.md): Selected setup updates and safe maintenance.
+- [TEAM consultations](cli/team.md): Bounded task- or conversation-scoped specialist advice.
+- [Authoring and saving](cli/authoring.md): Commit authorized versioned changes before dispatch.
+- [Generated names](cli/generated-names.md): Creation date/time, normalized collisions and separate filenames.
 - [Task Books](cli/task-books.md): Readable bounded work and completion stamps.
-- [Markdown tasks](cli/task-markdown.md): Supported checkmark-based task sources.
-- [Task identity](cli/task-identity.md): Stable IDs linking source, occurrences, attempts, commits and traces.
+- [Markdown tasks](cli/task-markdown.md): Checkmark-based compatibility sources.
+- [Task identity](cli/task-identity.md): Opening TASK name, collisions and historical provenance, separate from trace filenames.
 - [Task origins](cli/task-origins.md): Explicit, derived and goal-driven work.
 - [Task relationships](cli/task-relationships.md): References, subtasks and prerequisites.
-- [Eligibility](cli/eligibility.md): Ready work, automatic assignment candidates and real constraints.
-- [Goal discovery](cli/goal-discovery.md): Automatic due enquiries when no backlog remains.
+- [Eligibility](cli/eligibility.md): Ready work, assignment candidates and constraints.
+- [Goal discovery](cli/goal-discovery.md): Due enquiries when no backlog remains.
 - [Earliest start](cli/not-before.md): Time boundaries and timezone.
 - [Recurrence](cli/recurrence.md): Repeated occurrences and downtime.
 
 ## Results, safety and service workflows
 
-- [Execution](cli/execution.md): The common task lifecycle.
+- [Execution](cli/execution.md): Task lifecycle and no new claims during pause/stop draining.
 - [Checks](cli/checks.md): Real initialized validation and repair.
-- [Errors](cli/errors.md): Understandable failures, diagnostic evidence and next actions.
-- [Retries](cli/retries.md): Bounded automatic repairs, authentication and provider waiting.
+- [Errors](cli/errors.md): Understandable failures, evidence and next actions.
+- [Retries](cli/retries.md): Bounded automatic repair and provider/authentication waits.
 - [Git preflight](cli/git-preflight.md): Workspace readiness and safe initialization.
-- [Git persistence](cli/git-persistence.md): Default operation commits, task-ID correlation, trace inclusion, explicit opt-out and ownership.
-- [Git synchronization](cli/git-synchronization.md): Optional pull/push and pending sync.
-- [Recovery](cli/recovery.md): Interrupted work without duplication or data loss.
-- [Isolation](cli/isolation.md): Optional worktree execution and integration.
-- [Task traces](cli/traces.md): Per-task harness text, event logs, browser replay, Git correlation and sensitive data.
-- [Trace configuration](cli/trace-configuration.md): Independent recording and Git/video-inclusion decisions saved during init.
+- [Git persistence](cli/git-persistence.md): Operation commits, name correlation, trace inclusion and ownership.
+- [Git synchronization](cli/git-synchronization.md): Optional pull/push and pending synchronization.
+- [Recovery](cli/recovery.md): Interrupted work without duplicate effects or data loss.
+- [Isolation](cli/isolation.md): Optional worktrees and integration.
+- [Task traces](cli/traces.md): Literal task-file basenames, source/name provenance, harness evidence, video and redaction.
+- [Trace configuration](cli/trace-configuration.md): Independent recording and Git/video-inclusion choices.
 - [Planning](cli/planning.md): Read-only discussion and approved task saving.
-- [Migration](cli/migration.md): Lossless Markdown-to-Book conversion.
+- [Migration](cli/migration.md): Lossless Markdown-to-Book and legacy-header conversion.
 - [Operational quality](cli/operations.md): Cross-platform, bounded and observable operation.
-- [Acceptance scenarios](cli/acceptance.md): Representative verifiable product outcomes; topic-specific contracts add focused acceptance outcomes.
+- [Acceptance scenarios](cli/acceptance.md): Verifiable outcomes, supplemented by focused topic acceptance.

package/dist/expert/agents/_index.md

@@ -1,18 +1,16 @@
 # Agents
 
-[Main specification](../_main.md) · [Book language](../book-language/_index.md)
+[Main specification](../_main.md) · [Project model](../concepts/project-model.md)
 
-An agent is a persistent role, goal, rules and knowledge, not a permanently running model call. A task is a bounded piece of work. Many agents can belong to one project while only one project task executes at a time.
+An agent is a persistent role, goal, instructions and learned project knowledge, not a permanently running model call. Its Book starts with [AGENT](../book-language/commitments/agent.md), for example `AGENT Developer`; `Developer` supplies the name, while later commitments develop the role. Agents, tasks and chats are distinct Book entities sharing syntax and [normalized name references](../book-language/references.md). Only one project task executes at a time; ordinary chats and read-only consultations do not by themselves execute queued work.
 
-Project agents normally live as editable Books under `agents/`. References can also resolve Books elsewhere in the project and, last, in Git-ignored dependencies. Core agents are editable Books that the engine ensures exist under `agents/.core/`. Non-agents are special references supplied by the engine, not project files.
+- [Core agents](core-agents.md): Minimal editable required roles Adam, Manager, Teacher, Fixer and Chatter.
+- [Chatter](chatter.md): Default human-facing project entry, with specialist TEAM consultation and ordinary task creation.
+- [Non-agents](non-agents.md) and [Expert](expert.md): Engine-defined references/behavior, not project-owned Books.
+- [Fixer](fixer.md): Ongoing introspection/repair through ordinary tasks, chats and learning.
+- [Manager](manager.md): Automatic task assignment.
+- [Teacher](teacher.md) and [learning](learning.md): Ordinary open/closed learning.
+- [References](../book-language/references.md): One ordered resolver across all entity kinds.
+- [Visual identity](visual-identity.md) and [consistency](consistency.md): Stable presentation and guarded execution.
 
-- [References](../book-language/references.md): Equivalent @/brace syntax, normalization and four-tier lookup.
-- [Core agents](core-agents.md): Adam, Manager and Teacher.
-- [Non-agents](non-agents.md): Void/Null, User and Expert.
-- [Manager](manager.md): Automatic assignment.
-- [Teacher](teacher.md) and [learning](learning.md): Controlled improvements after work.
-- [Expert](expert.md): Knowledge of the running Promptbook engine.
-- [Visual identity](visual-identity.md): Automatic stable avatars and truthful activity across interfaces.
-- [Consistency](consistency.md): Reserved identities and recursion safeguards.
-
-The first nonempty line of a Book is the agent's name. The normalized name resolves uniquely at the highest matching tier; file organization affects lookup priority, not the declared identity. [FROM](../book-language/commitments/from.md) supplies inheritance; [TEAM](../book-language/commitments/team.md) describes whom to consult and when. They are different relationships.
+Project agents normally live under `agents/`; required core Books are initialized under `agents/.core/`. Location never replaces AGENT. A core is technically an ordinary project agent required by the engine, not a privilege or special learning mechanism. Non-agents Void/Null, User and Expert come from the running engine. Chatter's promoted default [chat picker](../cli/chat-ui.md) is a UI entry policy, not a new agent category or automatic scheduler. See [engine/project evolution](../concepts/engine-and-project.md).

package/dist/expert/agents/chatter.md

@@ -0,0 +1,31 @@
+# Chatter: the default human-facing project agent
+
+[Agents](_index.md) · [Core agents](core-agents.md) · [Chat entry](../cli/chat-ui.md) · [TEAM](../cli/team.md)
+
+**Chatter** is the user's ordinary conversational entry point when they want to inspect, discuss or manually direct a project without knowing which specialist to choose. It is a project-owned core agent, not the engine, the automatic scheduler or a replacement for Manager and specialist execution. The user's main conversation stays with Chatter while appropriate teammates advise or perform the actual specialist work.
+
+## Initialization and ownership
+
+Materialize a missing `agents/.core/chatter.book` with `AGENT Chatter` during ordinary initialization/readiness setup. Use a small editable boilerplate, normal Adam inheritance and ordinary default OPEN learning. It has the same Book, routing, harness, TEAM, Git and authority rules as other project agents, with no privileged hidden execution mechanism.
+
+At creation, include TEAM access to all other agents materialized/selected for that initialization, including the other core roles and specialists; Chatter must not consult itself. It can also consult the built-in Expert for engine-specific questions. Keep these relationships readable and editable. Users may add other teammates or change policy later. Reinitialization or engine upgrade adds a missing Chatter without resetting any existing customized core/specialist Book or rewriting an existing Chatter's team.
+
+Core hiding still applies to ordinary automatic discovery, but new human-chat entry explicitly promotes Chatter as its first/default choice. This does not make Chatter a non-agent or grant it broader access.
+
+## Conversation and delegation
+
+Chatter answers project questions, clarifies intent, explains status, performs authorized basic scoped actions and proposes or creates ordinary named tasks. For specialist topics it consults appropriate teammates rather than pretending to have performed their work itself. TEAM advice is attributed and bounded. Work requiring task execution goes through the normal queue, ownership, checks and persistence; opening a chat or asking a read-only question does not create a task or start an engine.
+
+A specialist consultation in an existing task retains that task's trace and result-commit scope. A consultation serving a conversation without an executing task is a linked two-agent exchange under [chat/TEAM rules](../cli/team.md), not a fabricated task or a human group chat. Chatter remains the human-facing speaker; do not silently switch the user's selected agent. It distinguishes requested, queued, running and completed work and cannot report a proposal as implemented.
+
+Normal approval, scope, account, browser, learning and secret-handling rules still apply. Chatter does not bypass a paused/stopping scheduler, commit unrelated edits or take over another task's ownership. Its user messages follow the same per-message persistence contract as every other human-facing chat.
+
+## Entry-point contract
+
+For a new chat without an explicit target, first offer exactly two choices: **Chat with Chatter** (initially focused/default) and **Choose another agent**. Enter immediately proceeds with Chatter, without a second specialist picker. The second choice opens the complete available target-agent list, including hidden/core roles and Expert, subject to normal resolution and valid-speaker rules. User, Void and Null are not targets. An explicit target bypasses the picker; a noninteractive new-chat request with no target uses Chatter without prompting.
+
+This applies to `ptbk chat`, the dashboard new-chat shortcut and browser/API entry. Existing chats and agent-authored waiting conversations retain their original participants; opening Fixer's question does not redirect it to Chatter. If Chatter is missing or invalid, give an actionable setup/repair diagnostic rather than silently choosing another agent, overwriting a file or initializing a project just by opening a picker.
+
+## Acceptance outcomes
+
+Initialize a project and verify one editable Chatter with all other initialized teammates. Enter through direct chat, terminal shortcut and browser: Enter chooses Chatter; the second option reveals every valid alternative; explicit selection is respected. Ask about status without creating work, consult a specialist with attribution, then create authorized linked tasks through the ordinary queue. Reinit preserves customization and adds only missing roles. Reopen another agent's waiting chat and verify that its identity, messages and required answer remain unchanged.

package/dist/expert/agents/consistency.md

@@ -1,16 +1,11 @@
-# Agent and automatic-work consistency
+# Agent and project consistency
 
-[Agents](_index.md)
+[Agents](_index.md) · [Shared resolution](../book-language/references.md)
 
-Validate the following before execution, and again when relevant definitions change:
+Check relevant definitions when the project changes and before work that depends on them. A normalized-name collision within or across Book kinds is **not normally fatal**: use deterministic first-wins resolution, report the effective definition and shadowed sources, and let [Fixer](fixer.md) propose or safely apply remediation. A wrong-kind match in a type-constrained commitment is a real reference error; missing and malformed definitions cannot be guessed away. Reserved built-in non-agent names cannot be replaced by project Books.
 
-- Agent references use the [shared normalization and ordered resolution](../book-language/references.md). At the first matching tier, a normalized name must identify one definition. Same-tier collisions are errors; a higher-tier definition may shadow lower-tier copies. Project agents cannot replace reserved non-agent names Void, Null, `0`, User or Expert.
-- Required core agents exist; create only missing defaults. Report malformed or conflicting existing definitions with their source locations. Core Books are distinct from engine-supplied non-agents.
-- Inheritance and textual inclusion terminate. An agent without FROM inherits Adam; every chain must reach an explicit empty or engine-defined foundation rather than cycle. Adam may inherit a custom ancestor, provided the full chain terminates. It need not directly inherit Void.
-- User cannot be an inheritance parent. Teacher's own Book must end in CLOSED. Report an open Teacher as unsafe configuration, explaining the self-teaching loop; do not run that loop.
+Initialize only missing required core agents. Do not silently erase customized or learned core content. Report invalid syntax with source context. Agent inheritance must terminate; FROM cycles and User as a parent are errors. TEAM cycles/reciprocal consultations are permitted but actual consultations are bounded. Teacher must remain CLOSED; Fixer may be OPEN and learns normally.
 
-TEAM references may be reciprocal or cyclic. That is valid and does not create an inheritance error, but actual consultations have bounded depth, count, time and cancellation.
+Manager assignment, teaching, Fixer maintenance and goal discovery use regular tasks and the same project ownership constraints. Prevent recursive manager assignment, teacher self-teaching, Fixer issue spam and unbounded model or commit loops. Dependency cycles block affected tasks, not the whole supervisor.
 
-Manager assignment, teaching and goal discovery are ordinary generated tasks, yet the engine must prevent automatic-work recursion and duplicate generation. Core dispatch cannot require an infinite chain of dispatch tasks; teaching cannot recursively teach Teacher; empty results cannot cause a busy loop. Cyclic task dependencies block the affected work with an explanation.
-
-Malformed configuration must never be repaired by erasing custom source. Resolving a Book in ignored/dependency content neither makes it an ordinary discovery candidate nor authorizes modifying the package. A running supervisor exposes the problem and remains controllable. See [recovery](../cli/recovery.md), [TEAM](../cli/team.md) and [goal discovery](../cli/goal-discovery.md).
+Ignored/dependency Book discovery does not grant authority to change third-party packages. A running service stays inspectable when any of these problems blocks work. See [recovery](../cli/recovery.md) and [task relationships](../cli/task-relationships.md).

package/dist/expert/agents/core-agents.md

@@ -1,13 +1,15 @@
-# Core agents and hidden definitions
+# Core agents and minimal project-owned defaults
 
-[Agents](_index.md)
+[Agents](_index.md) · [Engine and project evolution](../concepts/engine-and-project.md)
 
-The engine expects three editable core agents: **Adam**, **Manager** and **Teacher**, materialized as `agents/.core/adam.book`, `manager.book` and `teacher.book`.
+The engine expects five editable project roles: **Adam, Manager, Teacher, Fixer and Chatter**, materialized only if missing under `agents/.core/` as `adam.book`, `manager.book`, `teacher.book`, `fixer.book` and `chatter.book`. Their opening commitments are `AGENT <role name>`; core names do not acquire task/chat date-time decoration. A core has ordinary Book, routing, TEAM, learning, Git and runtime behavior. Being required does not grant a special inference mechanism or extra authority.
 
-On initialization and execution setup, create each missing definition from the installed engine's defaults. An incomplete core directory is repaired individually, not replaced wholesale. Existing customized files must not be overwritten, including when the package is updated. An invalid existing definition needs a diagnostic, not silent replacement.
+Initialize each missing role individually with a small comprehensible boilerplate, not an embedded encyclopedia. Existing Books belong to the project: never reset, replace or bulk-regenerate them during reinit/upgrade, including learned/customized versions. Adding a required Chatter preserves all previously present roles. Invalid/colliding sources are diagnosed through the normal resolver and repaired only by authorized work, not silently overwritten.
 
-Adam supplies the default inherited foundation. Its supplied definition ends inheritance with `FROM Void`. Manager inherits Adam by the usual default. Teacher is supplied with `FROM Expert` and ends with `CLOSED`; its parent can be customized, but its closure requirement remains.
+Initial policies: Adam is the common inheritance foundation (`FROM @Void`, initially CLOSED); Manager inherits Adam; Teacher inherits Expert and must remain CLOSED against recursive teaching; Fixer may consult Expert through TEAM and is OPEN. Chatter uses ordinary Adam inheritance/default OPEN learning and focuses on user conversation. These are individual Book policies, not restrictions imposed on every core agent.
 
-Any hidden directory inside `agents/`, not only `.core/`, contains supporting definitions rather than ordinary automatic task candidates. They remain discoverable for inheritance, imports, TEAM and explicit/internal assignments. Adam normally provides shared instructions, Manager handles assignment tasks and Teacher handles learning tasks. Hidden placement is not an access-control boundary.
+At Chatter creation, its readable TEAM relationships include all other initialized/selected agents, both core and specialist, and access to Expert for engine questions. Do not include itself. Users can customize or extend that team later; initializing a missing role does not rewrite existing teams. See [Chatter](chatter.md).
 
-See [inheritance](../book-language/inheritance.md), [non-agents](non-agents.md) and [consistency](consistency.md).
+Core definitions are hidden from ordinary default agent inventories and goal discovery, while remaining explicitly selectable, assignable and referenceable. **New human-chat entry is an explicit exception:** promote Chatter as the default first choice and offer Choose another agent to open the full valid target list, including other cores and Expert. This does not make all core agents ordinary goal-discovery candidates. Hidden status is not access control.
+
+Expert is a comprehensive version-matched engine-defined non-agent, never a project core file. See [Fixer](fixer.md), [Chatter](chatter.md), [Teacher](teacher.md), [inheritance](../book-language/inheritance.md) and [non-agents](non-agents.md).

package/dist/expert/agents/expert.md

@@ -6,6 +6,6 @@ Expert understands Promptbook, Book syntax, agents, tasks, project operation and
 
 Expert is never materialized into `agents/.core/`. Updating or selecting another engine may change Expert while preserving the project's own definitions. The engine must make the relevant introspective context available without requiring the user to maintain or copy it into every project. Do not expose credentials as introspection.
 
-Expert is usable both through `FROM Expert` and `TEAM ... @Expert`. A project can define `Modified Expert` with `FROM Expert` and let Teacher inherit that local specialization. A programmer can consult Expert without any Expert file existing in the project.
+Expert is usable both through `FROM @Expert` and `TEAM ... @Expert`. A project can define `Modified Expert` with `FROM @Expert` and let Teacher inherit that local specialization through `FROM {Modified Expert}`. A programmer can consult Expert without any Expert file existing in the project.
 
-[Initialization](../cli/initialization.md) explicitly assigns the first project-creation task to Expert. [Teacher](teacher.md) inherits Expert by default. Expert's internal implementation may use Book and shared agent mechanisms, but those are not project-owned source or requirements on its implementation.
+[Initialization](../cli/initialization.md) explicitly assigns the first project-creation task to Expert. [Teacher](teacher.md) inherits Expert by default. Expert may internally have a comprehensive Book-like definition embedded in or generated by the engine; no project file or internal encoding is required. Its size is not constrained by the deliberately minimal core-agent boilerplates. This separation lets engine expertise evolve while project agents retain their learning. See [engine/project evolution](../concepts/engine-and-project.md).

package/dist/expert/agents/fixer.md

@@ -0,0 +1,24 @@
+# Fixer: project self-maintenance
+
+[Agents](_index.md) · [Core agents](core-agents.md) · [Learning](learning.md)
+
+**Fixer is an ordinary editable, default-OPEN core agent**, initialized as a small `agents/.core/fixer.book`. Its job is to **introspect the particular running project** and improve its health over time: detect malformed Book syntax, normalized-name collisions and shadowing, unresolved references, problematic configuration, recurring failures, broken workflows or maintenance opportunities. It can inspect available logs, traces, actual diagnostics and project context, without inventing evidence or exposing secrets.
+
+A deliberately minimal initial example (not a special runtime implementation):
+
+```book
+Fixer
+ENTITY AGENT
+FROM @Adam
+GOAL Keep this Promptbook project healthy by finding and safely fixing real problems.
+TEAM Consult @Expert for current Promptbook syntax and capabilities.
+OPEN Learn verified project-specific repair practices and preferences.
+```
+
+Fixer has `TEAM` access to the built-in **Expert** for current Promptbook syntax, runtime capabilities and version-specific knowledge. Expert is general and engine-owned; Fixer applies that knowledge to the project's own state and retains learned project-specific practices. An engine upgrade refreshes Expert but does not reset Fixer's accumulated local Book.
+
+Run Fixer's checks opportunistically and at a bounded, persisted cadence, including after relevant diagnostic changes; do not invent a continuous busy polling loop, new permanent privileged service or thousands of repetitive notifications. The work is ordinary scheduled/derived tasks in the project's **single-task** agenda. Diagnose issues with their source, impact and confidence; ordinary low-risk repairs within existing authority can be done and checked automatically. A risky, ambiguous or human-dependent correction is handled through a **chat initiated by Fixer to @User** with a specific explanation, options when useful and links to affected entities/tasks. Do not silently rewrite ambiguous definitions or unrelated project files.
+
+Fixer is not an exceptional learning architecture: it uses precisely the same OPEN/CLOSED and Teacher mechanism as other agents. Corrections and user replies can become teaching evidence in an ordinary task, and authorized useful learning is committed to Fixer's own project Book. This can prevent recurrence of previously explained problems without promising perfect automatic deduplication. Suppress redundant still-unanswered conversations about the *same* condition; an already pending answer is not a reason to send it again.
+
+No extra dashboard category is needed for Fixer. Its tasks, ordinary results, diagnostics and chats use the existing agenda and conversation presentation. If no work is justified, it may record or report a bounded no-op; it must not manufacture changes merely to justify its existence.

package/dist/expert/agents/learning.md

@@ -6,7 +6,7 @@ Learning improves a maintained agent definition; it does not require training mo
 
 When an open project/core agent completes a task, create a follow-up task assigned to Teacher. Save it with the original task's result and completion in that same commit. The learning task identifies the agent and completed work, and follows that work in the shared queue. It is neither an invisible background edit nor a second kind of runner.
 
-Teacher reviews the evidence actually available: outputs, checks, actions, mistakes, corrections and diagnostic/reasoning material exposed by the harness. Unavailable private reasoning must not be invented. Persist useful learning in the allowed parts of the agent's Book, with the teaching task's own checked completion commit.
+Teacher reviews the evidence actually available: task outputs, checks, actions, mistakes, chat exchanges and human corrections linked to the agent, plus diagnostic/reasoning material exposed by the harness. When a committed human↔agent chat contains a substantive correction, explicit preference or verified project-specific guidance relevant to an **open** participating agent, schedule an ordinary Teacher learning task even when no execution task was created by that chat. Associate it with the chat and source agent, deduplicate against unresolved equivalent teaching work and respect OPEN limits; do not learn blindly from arbitrary or untrusted chat content. A chat alone is never a hidden, uncommitted mutation of the agent. Unavailable private reasoning must not be invented. Persist useful learning in the allowed parts of the agent's Book, with the teaching task's own checked completion commit.
 
 A closed agent receives no automatic teaching changes. Recheck the current learning policy before applying an update; closing an agent also protects it from an already queued learning task. OPEN does not authorize changing its own limits, expanding tool permissions or weakening project safeguards. An inherited instruction's origin must remain distinguishable from the local definition being taught.
 

package/dist/expert/agents/non-agents.md

@@ -6,10 +6,12 @@ Non-agents exist as engine-defined references without project files. They must n
 
 | Reference | FROM | TEAM |
 | --- | --- | --- |
-| Void, alias Null (also `0`) | Ends inheritance; supplies no instructions. | Valid no-op; no consultation or error. |
-| User | Invalid; inheritance must fail with a clear diagnostic. | Consults the user through the general request mechanism. |
-| Expert | Supplies Promptbook expertise from the running engine. | Consults that runtime's Promptbook expert. |
+| `@Void`, alias `@Null` (also the legacy `0`) | Ends inheritance; supplies no instructions. | Valid no-op; no consultation or error. |
+| `@User` | Invalid; inheritance must fail with a clear diagnostic. | Starts or continues a durable human-facing chat for the required question or action. |
+| `@Expert` | Supplies Promptbook expertise from the running engine. | Consults that runtime's Promptbook expert. |
 
-Void and User are special semantics, not ordinary model-backed roles. Expert does behave like a knowledgeable agent, but its definition and runtime context belong to the engine. It may internally share Book mechanisms; no internal representation is prescribed.
+The brace forms `{Void}`, `{Null}`, `{User}` and `{Expert}` are the same references. These built-ins are checked before any project file, as the first tier of [resolution](../book-language/references.md#ordered-resolution).
+
+Void and User are special semantics, not ordinary model-backed roles. In particular, User is not a selectable conversational agent chatting with itself. Expert does behave like a knowledgeable agent, but its definition and runtime context belong to the engine. It may internally share Book mechanisms; no internal representation is prescribed.
 
 See [Expert](expert.md), [references](../book-language/references.md) and [user requests](../cli/user-interactions.md).

package/dist/expert/agents/teacher.md

@@ -2,7 +2,7 @@
 
 [Agents](_index.md)
 
-Teacher is an editable core agent supplied with `FROM Expert` and an explicit final `CLOSED`. The user may customize its teaching instructions or parent, including inheriting a local specialization of Expert. It must remain closed to automatic learning.
+Teacher is an editable core agent supplied with `FROM @Expert` and an explicit final `CLOSED`. The user may customize its teaching instructions or parent, including inheriting a local specialization of Expert. It must remain closed to automatic learning.
 
 Teacher executes ordinary learning tasks that improve an eligible agent from completed work. It receives the original assignment, result, available execution evidence, current agent definition and that agent's learning permission. It changes only what that permission allows and must not turn an inference or missing evidence into a learned fact.
 

package/dist/expert/agents/visual-identity.md

@@ -2,7 +2,7 @@
 
 [Agents](_index.md) · [Project status view](../cli/status-view.md)
 
-Every agent has a recognizable visual identity without requiring the user to choose an image or add visual metadata before work can start. Provide it automatically for ordinary project agents, core agents such as Manager/Teacher and the engine-supplied Expert. The default works locally and offline, without an image-generation/model call, external avatar service or extra setup.
+Every agent has a recognizable visual identity without requiring the user to choose an image or add visual metadata before work can start. Provide it automatically for ordinary project agents, core agents such as Manager, Teacher and Fixer and the engine-supplied Expert. The default works locally and offline, without an image-generation/model call, external avatar service or extra setup.
 
 ## Visual direction: Promptbook Coder badges
 
@@ -20,12 +20,12 @@ Inheritance does not give every descendant Adam's appearance. Do not introduce a
 
 ## Placement and activity
 
-Show badges in agent/queue views, current-task status, attributed messages and results, including the live dashboard and status snapshot. The [current-work panel](../cli/dashboard-layout.md) makes it immediately clear who is doing what. User requests identify the human as User rather than another autonomous worker; Void/Null never appears to be doing work.
+Show badges in agent/queue views, current-task status, attributed messages and results, including the live dashboard and status snapshot. The [current-work panel](../cli/dashboard-layout.md) makes it immediately clear who is doing what. Agent-authored user-facing chat messages identify the agent speaker, while the human speaker is User rather than another autonomous worker; Void/Null never appears to be doing work.
 
 Identity and observed activity are distinct. Use readable labels and restrained expressions for working, idle, waiting for the user/provider, paused, blocked/failed and completed work. Manager assignment and goal enquiries show their actual responsible agents. A quiet blink is decorative, not proof of progress; work gestures reflect actual work and cannot simulate tool calls, checks or completion. No hardcoded alternating coding/painting scenes may pretend the runtime is performing those actions.
 
-Working motion changes or stops while waiting; snapshots are still frames of the observed state. Respect reduced motion, keep layout stable and do not imply parallel independent tasks. A completed task is not a permanently completed agent. Avatars never obscure details, errors or controls, and pending human requests remain the highest visual priority. Repainting cannot steal input or change execution, routing or permissions.
+Working motion changes or stops while waiting; snapshots are still frames of the observed state. Respect reduced motion, keep layout stable and do not imply parallel independent tasks. A completed task is not a permanently completed agent. Avatars never obscure details, errors or controls, and chats awaiting human replies remain the highest visual priority. Repainting cannot steal input or change execution, routing or permissions.
 
 ## Acceptance outcomes
 
-Compare the current-agent area with the Coder reference: it is an expressive, polished terminal-style mascot badge, not merely a colored initial or random geometric icon. Several agents remain distinguishable without color. Reconnect, move a Book and edit its rules: appearance remains stable. Equivalent references show one identity. Switching from Manager to its selected agent changes the badge, name and actual activity together. Waiting cannot look like active execution; requests remain more prominent. Raw, narrow and reduced-motion modes preserve names, state and controls.
+Compare the current-agent area with the Coder reference: it is an expressive, polished terminal-style mascot badge, not merely a colored initial or random geometric icon. Several agents remain distinguishable without color. Reconnect, move a Book and edit its rules: appearance remains stable. Equivalent references show one identity. Switching from Manager to its selected agent changes the badge, name and actual activity together. Waiting cannot look like active execution; waiting-for-user chats remain more prominent. Raw, narrow and reduced-motion modes preserve names, state and controls.

package/dist/expert/book-language/_index.md

@@ -1,14 +1,15 @@
 # Book language
 
-[Main specification](../_main.md)
+[Main specification](../_main.md) · [Project model](../concepts/project-model.md)
 
-Book is a human-readable language of natural text and commitments. It describes both a persistent agent (who works and why) and a bounded task (what work to do).
+Book is one human-readable language for **agents, tasks and chats**, each in one `.book` source. Its three syntactic building blocks are **commitment keywords**, their **content**, and **references** within nonliteral content. Every canonical Book starts with a type-and-name commitment: `AGENT <name>`, `TASK <name>` or `CHAT <name>`. The name is the commitment's content, not a separate unprefixed header or a filename.
 
-An agent starts with its name on the first nonempty line. A task starts with `TASK <title>` on that line. The two document kinds share notation, not identity, default inheritance or runtime purpose.
+The same syntax and parser apply to every entity kind. The first commitment establishes what is being defined; subsequent commitments build up that entity's instructions, work or conversation. Entity-specific validation and engine behavior are separate from parsing. The commitment vocabulary and supported entity kinds may grow without introducing another document grammar.
 
-- [Syntax](syntax.md): Source structure, text, literal content and commitment boundaries.
-- [References](references.md): Normalized agent names and stable task references.
-- [Inheritance](inheritance.md): FROM, implicit Adam and termination.
-- [Commitments](commitments/_index.md): One file per canonical commitment, with aliases in that same file.
+- [Syntax](syntax.md): Commitment-first documents, uppercase boundaries, content and diagnostics.
+- [References](references.md): One normalized name resolver and graph links across all three kinds.
+- [Inheritance](inheritance.md): Agent-only FROM, implicit Adam and termination.
+- [Commitments](commitments/_index.md): One document per canonical commitment.
+- [Generated names](../cli/generated-names.md): Preventive task/chat naming, separate from language validity and filenames.
 
-[Agents](../agents/_index.md) describes role categories and learning. [Task Books](../cli/task-books.md) describes execution-facing task semantics. The language specifies observable meaning and readable source, not parser classes or an internal representation.
+[Agents](../agents/_index.md), [Task Books](../cli/task-books.md) and [Chats](../cli/chats.md) define distinct semantics; common syntax does not make a chat executable or a task inheritable. Plain name headers and `ENTITY` belong to [explicit legacy conversion](../cli/migration.md), not canonical authoring or folder-based type inference.

package/dist/expert/book-language/commitments/_index.md

@@ -2,7 +2,25 @@
 
 [Book language](../_index.md)
 
-Each canonical commitment has one specification file. Listed aliases share its semantics and file; keywords containing spaces remain a single commitment.
+Each canonical commitment has one specification file. Listed aliases share its semantics and file; keywords containing spaces remain a single commitment. All kinds use the same [uppercase boundary and content rules](../syntax.md); semantic validation does not introduce another grammar.
+
+## Foundational type-and-name commitments
+
+Exactly one of these starts a Book. Its content is the entity's name; subsequent commitments develop that same entity.
+
+- [AGENT](agent.md)
+- [TASK](task.md)
+- [CHAT](chat.md)
+
+## Shared links
+
+- [LINK](link.md)
+
+## Chat commitments
+
+- [CHAT MEMBER](chat-member.md)
+- [CHAT MESSAGE](chat-message.md)
+- [CHAT STATUS](chat-status.md)
 
 ## Agent and shared instructions
 
@@ -30,8 +48,6 @@ Each canonical commitment has one specification file. Listed aliases share its s
 
 ## Task commitments
 
-- [TASK](task.md)
-- [TASK ID](task-id.md)
 - [TASK AGENT](task-agent.md)
 - [TASK HARNESS](task-harness.md)
 - [TASK MODEL](task-model.md)
@@ -47,3 +63,7 @@ Each canonical commitment has one specification file. Listed aliases share its s
 - [TASK RUNNER](task-runner.md)
 - [TASK NOTE](task-note.md)
 - [TASK ORIGIN](task-origin.md)
+
+## Historical syntax
+
+[Former ENTITY declaration](entity.md) documents conversion of existing sources only. It is not a canonical commitment or an alternative to the opening AGENT, TASK or CHAT.

package/dist/expert/book-language/commitments/agent.md

@@ -0,0 +1,11 @@
+# AGENT
+
+[Commitments](_index.md) · [Syntax](../syntax.md) · [Agents](../../agents/_index.md)
+
+**Document:** Agent; required first commitment, exactly once.
+
+`AGENT <name>` declares an agent whose nonempty, single-line display name is `<name>`. For example, `AGENT Frontend Developer` names the agent `Frontend Developer`. Normalize the name content only, not the keyword or filename. Use the same commitment/content boundary as every other line; there is no special bare-name parser.
+
+Subsequent commitments build the agent's role, goals, rules, knowledge, relationships and learning policy. Agent inheritance and OPEN/CLOSED retain their existing semantics. Core project agents use this same declaration; engine-provided non-agents still require no project file.
+
+Agent names do not receive the automatic task/chat date-time decoration. Folder placement cannot replace this declaration. Additional AGENT, TASK or CHAT root declarations in the same source are invalid. See [references](../references.md).

package/dist/expert/book-language/commitments/chat-member.md

@@ -0,0 +1,7 @@
+# CHAT MEMBER
+
+[Commitments](_index.md) · [Chats](../../cli/chats.md)
+
+**Document:** Chat.
+
+`CHAT MEMBER @User` or `CHAT MEMBER @Developer` declares a participant. A normal human-facing chat has exactly User and one chosen agent (including Expert where meaningful); a task-scoped TEAM consultation has two participating agents. Multiple agents with a human are reserved for future support. Void/Null are not speakers and User cannot have a chat with itself. A participant is resolved by the common name resolver.

package/dist/expert/book-language/commitments/chat-message.md

@@ -0,0 +1,11 @@
+# CHAT MESSAGE
+
+[Commitments](_index.md) · [Chats](../../cli/chats.md)
+
+**Document:** Chat.
+
+A repeated `CHAT MESSAGE <sender-reference> <timestamp>` commitment begins a durable message by a declared participant. It is one multiword commitment in the common grammar, not a new CHAT declaration or another entity. Its natural-language body continues until the next commitment/message, preserving source order, attachments and text.
+
+A stored message **must be lossless**: literal quoting/escaping of supplied text that resembles Book controls or fences is required so pasted AGENT, TASK, CHAT, RULE, CHAT MESSAGE, brace references or links never become structural or executable commitments solely by being quoted in a message. Preserve arbitrary text without changing the original message or letting it rename/retype its containing Book.
+
+A message timestamp identifies a turn's time, **not** an entity ID or part of the chat's declared name; duplicate timestamps may exist. Appending a message never refreshes the name's creation date/time. A message may ask for a human answer or report an answer, as expressed through chat attention state. In ordinary human-facing chats each newly accepted user/agent message is its own Git operation and commit; task-internal agent consultations join the parent task's result commit.

package/dist/expert/book-language/commitments/chat-status.md

@@ -0,0 +1,7 @@
+# CHAT STATUS
+
+[Commitments](_index.md) · [Chats](../../cli/chats.md)
+
+**Document:** Chat.
+
+`CHAT STATUS open|waiting-for-user|resolved` describes the conversation's durable action state. `waiting-for-user` requires a concrete unanswered agent message, decision or human-only action; it is not inferred merely from who spoke last. Appending an actual answer updates the state in that message's atomic save/commit. Read/unread presentation per local viewer is separate from durable action state; reading never answers or approves a request.

package/dist/expert/book-language/commitments/chat.md

@@ -0,0 +1,11 @@
+# CHAT
+
+[Commitments](_index.md) · [Syntax](../syntax.md) · [Chats](../../cli/chats.md)
+
+**Document:** Chat; required first commitment, exactly once.
+
+`CHAT <name>` declares a conversation whose nonempty, single-line display name is `<name>`. Normalize the name content only, excluding CHAT. The declaration identifies the conversation independently of its path, participants or linked tasks; it does not create an executable task or a separate chat ID.
+
+Subsequent CHAT MEMBER, CHAT MESSAGE, CHAT STATUS and applicable shared commitments build that conversation using the common Book syntax. A new message extends the same Book without another CHAT declaration. References use the full persisted chat name.
+
+New system-created threads include readable creation date/time under [generated-name policy](../../cli/generated-names.md), including threads started through CLI/UI and agent-originated conversations. Dates are ordinary name text, not mandatory chat syntax or message timestamps. Reopening, replying or recovering retains the existing name. Additional root declarations are invalid.