dsh-ptc-plus 0.4.10 → 0.5.1

package/README.en.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/dsh-ptc-plus-banner-en.webp" width="100%" alt="PTC Plus: No need to start over! Update it. Keep computing!">
+  <img src="assets/dsh-ptc-plus-banner-v2-en.webp" width="100%" alt="PTC Plus: Tweak it, keep computing!">
 </p>
 
 <p align="center">
@@ -25,29 +25,25 @@ PTC Plus provides a stateful TypeScript computation environment for DSH's **PTC
 - **Avoid routine call failures**: use familiar module syntax, recover from identifiable call omissions, and receive correction suggestions for verifiable syntax errors.
 - **Reuse common capabilities**: save functions as global bindings, provide their interfaces and usage notes to the model, and use them across sessions.
 
-[Quick start](#quick-start) · [Feature overview](#feature-overview) · [Continuous computation](#continuous-computation-and-language-extensions) · [Editing and call tolerance](#code-editing-and-call-tolerance) · [Global bindings](#global-bindings-reuse-functions-across-sessions) · [Interface and settings](#interface-and-settings) · [Values and recovery](#value-transfer-and-state-recovery)
+[Quick start](#quick-start) · [Feature overview](#feature-overview) · [Continuous computation](#continuous-computation-and-language-extensions) · [Editing and tolerance](#code-editing-and-call-tolerance) · [Global bindings](#global-bindings-reuse-functions-across-sessions) · [Interface and settings](#interface-and-settings) · [Values and recovery](#value-transfer-and-state-recovery) · [Development](#development)
 
 ## Quick start
 
-Requires Node.js `^22.19.0 || >=24.0.0` and the latest available official DSH release. Install into the profile you actually use:
+Requires Node.js `^22.19.0 || >=24.0.0` and the latest available official DSH release:
 
 ```sh
 dsh plugin --profile <profile> add dsh-ptc-plus
 ```
 
-Replace `<profile>` with your profile name. Restart DSH and select **PTC mode** in the session. Continuous computation, call tolerance, and global bindings default to on. Explicitly disabled options in an existing configuration stay disabled.
+Replace `<profile>` with your profile name, restart DSH, and select **PTC mode** in the session. Continuous computation, call tolerance, and global bindings are on by default. To upgrade, run `dsh plugin --profile <profile> add dsh-ptc-plus@latest` and restart that Host; see the [installation guide](docs/installation.md) for other installation methods, Desktop, the local development launcher, and troubleshooting.
 
-Session history uses DSH's public reader, and the Host incrementally projects prompt facts. Missing read surfaces or malformed historical event arrays produce explicit diagnostics, not a claim that unavailable history was successfully recovered as an empty session.
+The plugin declares `engines.dsh: "*"` for the Host's compatibility preflight; public capability checks and packed tests against the latest official release verify compatibility.
 
-With the default interface settings, the session has a **REPL** tab; wide screens also show a green **PTC Plus** header indicator. The sparkle button beside the composer opens the global binding menu and **PTC Plus settings**. You can also open **Plugins → Installed → dsh-ptc-plus → Configure** in the sidebar to check the main switch and all plugin settings.
-
-Once installed, describe your task to the model as usual. The `run_code` and `edit_run_code` examples below show how the model uses these features. See the [installation guide](docs/installation.md) for other installation methods, Desktop, the local development launcher, upgrades, and troubleshooting.
-
-For Windows source testing, double-click `scripts\run-upstream-dsh.cmd` to fetch the official DSH default branch, reuse an isolated build cache, and load this plugin checkout. The first run installs dependencies and builds DSH; see [upstream source testing](docs/installation.md#upstream-source-development-launcher-windows).
+The session shows a **REPL** tab, and wide screens show a **PTC Plus** header indicator. The sparkle button beside the composer opens the global binding menu, the session capability workbench, and **PTC Plus settings**; **Plugins → Installed → dsh-ptc-plus → Configure** in the sidebar is the same configuration.
 
 ## Feature overview
 
-Default PTC mode starts every execution in a fresh environment: variables from the previous call are gone, and a change that depends on earlier results means resending the setup code. PTC Plus turns `run_code` into a session-bound TypeScript REPL and closes the gaps below.
+Default PTC mode starts every execution in a fresh environment: the previous call's variables are gone, and a change that depends on earlier results means resending the setup code. PTC Plus turns `run_code` into a session-bound TypeScript REPL and closes those gaps.
 
 | Scenario | Default PTC mode | With PTC Plus |
 | --- | --- | --- |
@@ -56,24 +52,20 @@ Default PTC mode starts every execution in a fresh environment: variables from t
 | Change a small part of the code | A one-line change means resending the complete source | Submit a delta through `edit_run_code`, then execute the complete revised cell |
 | Use module syntax | Static `import` and `export` are invalid inside the function body | Write them directly in a cell; the plugin adapts the module syntax |
 | Omit a call summary | Missing `run_code.description` fails validation | Supply a display summary automatically so otherwise valid code proceeds |
-| Provider rejects malformed tool JSON | The whole turn ends with a provider error | Repair or preserve a buffered tool-call tail containing only tool framing and at most one usage event; route every other buffered tail through schema rejection so the model continues |
+| Provider rejects malformed tool JSON | The whole turn ends with a provider error | A repairable call tail continues; anything else becomes a schema rejection result so the model can continue |
 | Recover a misplaced top-level tool call | Undeclared top-level calls are rejected in PTC mode | Convert the call to `run_code` when the live tool definitions uniquely identify the target and validate its arguments |
 | Locate a code error | Return the native error and stack | Map the error to the cell source; suggest an edit when a missing trailing delimiter has one verified correction |
-| Work with the current project | Relative Node paths depend on the host process directory | Resolve file paths, session module imports, and default child-process directories from the session project directory |
-| Find tools and parameters | Read through the tool interfaces already supplied to the model | List and search current capabilities in code, then inspect relevant interfaces on demand |
+| Work with the current directory | Execute in the directory resolved by the Host for the current call | Relative file operations and default child processes use the session's current directory when they run, and an in-cell `tools.working_directory({ cd })` applies to the rest of that cell; module imports keep the starting directory, and existing modules and import closures retain their source base |
+| Find tools and parameters | Read through the tool interfaces already supplied to the model | Retrieve matching interfaces in one byte-budgeted `capabilities.search` response, or list and inspect members |
 | Transfer data beyond plain JSON | JSON cannot fully represent `undefined`, BigInt, cycles, and similar values | Preserve supported special values and reference relationships for further computation and recovery |
-| Inspect computation state | No reusable session variables remain after a call | View retained names, source definitions, reuse counts, and bounded value previews in the REPL tab |
+| Inspect computation state | No reusable session variables remain after a call | View retained names, source definitions, reuse counts, and value previews in the REPL tab |
 | Reuse functions across sessions | Save the code yourself and reload it in later calls | Save TypeScript global bindings and supply their interfaces and usage notes to the model |
 | Author and test global bindings | No dedicated workbench for global bindings | Ask the model for a draft to review, or run unsaved source in the workbench |
 | Continue after a restart | No computation state spans calls, so there is nothing to recover | Recover verifiable state from session records and report what cannot be recovered |
 
-The following sections explain usage and limits. See the [runtime reference](docs/runtime-reference.md) for complete language rules, configuration fields, and diagnostics.
-
 ## Continuous computation and language extensions
 
-The model executes the following code through `run_code`. Each call's code is a **cell**.
-
-First, define the data and a calculation:
+The model executes the code below through `run_code`, and each call's code is a **cell**.
 
 ```ts
 const amounts: number[] = [12, 8, 5]
@@ -83,56 +75,35 @@ function total() {
 return total() // 25
 ```
 
-In the next call, revise the data and reuse the function:
+The next call revises the data without redefining `total`:
 
 ```ts
 const amounts = amounts.filter(value => value >= 8)
 return total() // 20
 ```
 
-There is no need to redefine `total` or invent another variable name to avoid a redeclaration error. `total()` reads the updated `amounts`.
-
-The default **stateful semantics** (`bindingUpdates: 'stateful'`) extend JavaScript/TypeScript binding rules for continued revision:
-
-- Variables, functions, classes, and import bindings in the same scope can be updated, including bindings declared with `const`. Same-name revisions also work within a single cell.
-- Existing closures read updated bindings; a previously saved function value remains the original function.
-- Blocks, functions, and loop iterations retain their separate scopes.
-- Failed initialization does not permanently reserve a name that was never successfully established. Other changes made before the failure are not rolled back.
-
-Cells support TypeScript, top-level `await` / `return`, and static `import` / `export`. To detect name overwrites instead, disable **Allow redeclarations and overrides** to select the `protected` policy. Protected runtime names such as `tools` remain unavailable for overwriting.
-
-<details>
-<summary>When static imports and local overrides take effect</summary>
-
-Static imports take effect **before the entire cell body executes**. Assignments and ordinary declarations in the body can then override them. A static import in a later cell restores the binding's live module source. Writing an import below an ordinary declaration in the same cell does not restore it at that textual position. To retrieve the current exported value at a particular step, assign it explicitly:
-
-```ts
-join = (await import('node:path')).join
-```
+The default **stateful semantics** (`bindingUpdates: 'stateful'`) extend JavaScript/TypeScript binding rules for that continued revision:
 
-This captures the function value at that moment; a static import follows its module source. See the [runtime reference](docs/runtime-reference.md#cell-semantics) for more language rules.
+- Variables, functions, classes, and import bindings in the same scope can be updated, including those declared with `const`, and same-name revisions also work inside one cell.
+- Existing closures read the updated binding, a function value saved earlier is still the original function, and blocks, functions, and loop iterations keep their separate scopes.
+- A failed initialization does not permanently reserve that name, and changes made before the failure are not rolled back.
 
-</details>
+Cells support TypeScript (including runtime `enum` and namespaces), top-level `await` / `return`, and static `import` / `export`; a static import takes effect before the whole cell body executes, and an assignment later in the body can override it. To detect name overwrites instead, disable **Allow redeclarations and overrides** and use the `protected` policy; protected runtime names such as `tools` can never be overwritten.
 
-`run_code`, edited code, and the global binding workbench follow the same language policy; the workbench's temporary state is separate from the model's session. Explicit `eval`, `Function`, `node:vm`, and independent runtimes retain their corresponding native boundaries. See the [language reference](docs/runtime-reference.md#cell-semantics) for scope, module interoperability, and historical session rules.
+`run_code`, edited code, and the global binding workbench follow the same language policy, while explicit `eval`, `Function`, `node:vm`, and independent runtimes keep their own native boundaries. Scope, module interoperability, and historical session rules are in the [language reference](docs/runtime-reference.md#cell-semantics), and complete language rules, configuration fields, and diagnostics are in the [runtime reference](docs/runtime-reference.md).
 
 ## Code editing and call tolerance
 
-### Send only the change
-
-The model can use `edit_run_code` to change the most recent editable cell in the current model turn without resending its complete source. If the second cell above has just completed and the same turn is still running, its filter can be changed to `value >= 10`:
+The model can call `tools.edit_run_code` inside a new `run_code` cell to change the most recent editable cell of the current turn without resending its source:
 
 ```js
-edit_run_code({
+const receipt = await tools.edit_run_code({
   edits: [{ old_string: 'value >= 8', new_string: 'value >= 10' }]
 })
+return receipt
 ```
 
-An edit **reruns the entire cell**; this example returns `12`. Earlier state changes are not rolled back. If the code writes files or calls external services, rerunning still requires considering duplicate effects. Edits can repair failed code or refine a successful computation.
-
-Republishing a historical result as a compacted display entry is not another execution and does not make the older cell the new edit target. A newer failed cell remains available for correction.
-
-### Recover from identifiable call problems
+An `accepted: true, scheduled: true` receipt means the edit is scheduled: the entire target cell reruns after the outer cell finishes, and the next cell reads the revised value (`12` above). Reads later in the accepting cell still see the old state, earlier state changes are not rolled back, and a rerun of code that wrote files or called external services still needs to account for duplicate effects. Each regular-expression edit requires `pattern`, `flags`, `replacement`, and `expected_matches`; pass `""` explicitly when no flags are needed.
 
 | Situation | PTC Plus behavior |
 | --- | --- |
@@ -141,122 +112,89 @@ Republishing a historical result as a compacted display entry is not another exe
 | Argument validation reports a missing `description` | Distinguish outer and nested tool arguments and provide correction guidance, saved as a complete message so session history remains loadable |
 | Code fails to parse | Identify the source position; at EOF, suggest a target-bound edit if appending one or two closing delimiters has exactly one validated correction |
 
-The first two behaviors default to on and can be disabled in settings. Syntax suggestions do not execute automatically or establish that the code matches the task's intent.
+The first two behaviors are on by default and can be disabled in settings. Syntax suggestions never execute on their own, and they say nothing about whether the code matches the task's intent. A volatile state cannot be saved as a durable checkpoint, but a rejected save leaves the current variables usable; restore does not undo external effects or change global binding configuration.
 
 ## Project files and tool capabilities
 
-### Start from the session project directory
-
-The model can use Node.js directly to read files, process data, and run programs. Relative file paths and imports in session code resolve from the recorded session project directory. Child processes use that directory when `cwd` is omitted; an explicit directory still takes precedence.
+The model can use Node.js directly to read files, process data, and run programs. Relative paths and child processes without an explicit `cwd` use the session's current directory when they run, so an in-cell `tools.working_directory({ cd })` applies to the rest of that cell and matches the Host tools. Module imports and `import.meta` keep the starting directory; loaded modules, escaped import closures, and captured `require` keep their original base, and `process.chdir` is unavailable inside a cell. File, network, and other external inputs stay usable in the live environment, but a restart is not guaranteed to recover them.
 
-For example, in a project containing `package.json`, the first call reads its dependencies:
+`capabilities.search()` finds and returns complete interfaces in one call, budgeted in bytes, with oversized entries kept complete and given an individual retrieval reference; `tree()`, `find()`, and `inspect()` remain available.
 
 ```ts
-import { readFile } from 'node:fs/promises'
-const manifest = JSON.parse(await readFile('package.json', 'utf8'))
-const deps = Object.keys(manifest.dependencies ?? {})
-return deps.length
+return capabilities.search({ query: 'read file content', budgetBytes: 8192 })
 ```
 
-The next call works directly with the loaded data:
-
-```ts
-return deps.map(dep => dep + '@' + manifest.dependencies[dep])
-```
-
-This does not reread the file: it uses `manifest` already in the session. Direct file, network, and other external inputs can remain usable in the live environment without being guaranteed recoverable after a restart.
-
-### Discover tools as needed
-
-The model can still use DSH's current native tools through `tools.*`. To discover available capabilities, `capabilities.tree()` lists the catalog, `find()` searches names and descriptions, and `inspect()` provides parameter information for selected interfaces:
-
-```ts
-const matches = await capabilities.find('read')
-return capabilities.inspect({
-  symbols: matches.slice(0, 4).map(item => item.symbol),
-  budget: 4,
-})
-```
-
-Search uses lexical matching, so short keywords such as `read` or `session` work best. A miss does not prove that a tool is unavailable. Discovery grants no additional authority; DSH still validates and schedules calls. See [capability discovery](docs/runtime-reference.md#capability-discovery).
+Search uses English/Chinese lexical matching, and a miss does not prove that a tool is unavailable. Discovery grants no additional authority, DSH still validates and schedules calls, and more usage notes are in [capability discovery](docs/runtime-reference.md#capability-discovery).
 
 ## Global bindings: reuse functions across sessions
 
-Session variables serve the current task. **Global bindings** save common TypeScript functions for multiple sessions to load. For example, after saving a binding named `textTools`, the model can call `textTools.clean(text)`.
-
-Global bindings and the sparkle shortcut default to on. Create entries manually, import `.ts` files, or ask the model to write and revise them:
+Session variables serve the current task, and **global bindings** save common TypeScript functions for multiple sessions to load: after saving `textTools`, the model can call `textTools.clean(text)`. Create entries by hand, import `.ts` files, or ask the model:
 
 ```text
 /binding new Create textTools to trim outer whitespace while preserving interior spaces
 /binding edit <id> Add line-by-line trimming
 ```
 
-`<id>` is the entry's identifier in the workbench. You can also select the binding to revise from the sparkle menu.
-
-### Author, review, and enable
-
-The model can test with in-memory examples before submitting a draft. The draft floats above the composer; expanding or collapsing it leaves the conversation in place. Opening a draft from the composer menu or original request goes directly to the large dialog. Choose **Enlarge binding draft** to review the complete source in a large dialog with independent scrolling and save/discard actions at the bottom. The header separates resize and close controls; **Shrink binding draft** returns to preview. Review its source, interface, and model instructions, then choose **Save and enable**, **Save disabled**, or **Discard draft**. Submission alone neither saves nor enables a binding. If you close the panel, the sparkle button's draft badge lets you reopen it.
-
-The sparkle menu lists and toggles entries even before the first message; these choices apply across sessions. Enabled entries appear first; the disabled group shows its count and starts collapsed. Only the binding list scrolls, keeping authoring, revision, management, and settings actions visible at the bottom. Enabled entries' interfaces and usage notes are provided to the model in new sessions. Changes during a session are delivered on its next allowed request.
-
-### Interface guidance and independent trial runs
-
-Each entry can derive its public interface from source and include purpose, input constraints, or examples. Editing only its instructions does not reset its loaded runtime state. Assignment or redeclaration in a session overrides only the corresponding name and does not rewrite the saved global entry.
+The draft the model submits floats above the composer, and in the large dialog you read the complete source, interface, and model instructions before choosing **Save and enable**, **Save disabled**, or **Discard draft**; submitting a draft neither saves nor enables it. Enabled entries' interfaces and usage notes go to the model in new sessions, and a change made during a session takes effect on its next allowed request.
 
-The workbench can run unsaved source and retain temporary variables across executions. Its computation state is separate from the model's session, making it useful for manual function checks; file and network operations still have real effects. Entries can be managed without an active PTC session. See the [global binding guide](docs/user-bindings.en.md) for source format, interface generation, storage, and the full workflow.
+The workbench runs unsaved source and keeps temporary variables between executions; its computation state is separate from the model's session, file and network operations still have real effects, and entries can be managed without an active PTC session. See the [global binding guide](docs/user-bindings.en.md) for source format, interface generation, storage, and the full workflow.
 
 ## Interface and settings
 
-The **REPL tab** lets you search retained names, inspect definitions, see reuse counts and bounded value previews, and open the global binding workbench. Previews have type and size limits; missing, incomplete, or unreadable previews are identified explicitly, and display does not invoke user getters. The green **PTC Plus** header indicator offers a quick binding list on wide screens; use the REPL tab on narrow screens.
-
-Workbench controls provide visible keyboard focus and disabled feedback, and REPL names remain readable in light and dark themes. See the [visual contract](docs/client-visual-contract.md) for browser regression checks and their coverage limits.
+The **REPL tab** lists the names kept in the session with their definitions, reuse counts, and value previews, and opens the global binding workbench. Hovering a collapsed execution card for 400 ms, or focusing it with the keyboard, shows an excerpt of its recorded source, result, and feature notices, and click, Enter/Space, or tap expands the full content and copies the code; “Preview execution content on hover” under Interface display turns this off.
 
 ![Session state and the global binding workbench in the REPL tab](assets/ptc-plus-repl-workspace-en.png)
 
-The sparkle menu beside the composer groups binding authoring, entry management, and **PTC Plus settings**. Its settings dialog and the sidebar plugin configuration page share the same configuration:
-
-| Group | What you can adjust |
-| --- | --- |
-| Plugin switch | Enable or disable PTC Plus |
-| Tool call tolerance | Missing call summaries and identifiable misplaced native-tool calls |
-| REPL syntax | Allow same-name revisions or choose name protection |
-| State and recovery | Restart recovery, contextual tips, and their frequency |
-| Tool extensions | Global bindings and their management entry, official Cordis tool integration |
-| Interface display | Enhanced tool cards, the REPL tab, and the sparkle shortcut |
-| Resource limits | Execution time, memory, and output budgets |
+The settings window and the sidebar plugin configuration page are the same configuration, grouped like this:
 
-Everyday computation features default to on. **Cordis development tools default to off** and can be enabled when inspecting or developing DSH plugins; see the [integration notes](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md). Explicitly disabled options stay disabled, and each saved binding keeps its own enabled state.
+| Functional module | Group | What you can adjust |
+| --- | --- | --- |
+| Plugin switch | PTC Plus title switch | Enable or disable PTC Plus |
+| Core workspace | REPL syntax | Allow same-name revisions or choose name protection |
+| Core workspace | State and recovery | Restart recovery, official REPL ownership, contextual tips, and their frequency |
+| Extensions and tolerance | Tool extensions | Global bindings and their management entry, official Cordis tool integration |
+| Extensions and tolerance | Tool call tolerance | Missing call summaries and identifiable misplaced native-tool calls |
+| Interface and resources | Interface display | Enhanced tool cards, the REPL tab, and the sparkle shortcut |
+| Interface and resources | Resource limits | Execution time, memory, and output budgets |
+| Experimental | Capabilities and context | Experimental capability management (off by default), independent statistics, common baseline, individual choices, and presentation budgets |
 
-Settings usually apply immediately. A worker's memory limit cannot be changed while that worker is active or a submitted cell is preparing to execute. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and full limits.
+Everyday computation features are on by default, and **Cordis development tools are off by default** so they can be enabled when inspecting or developing DSH plugins; see the [integration notes](docs/adr/0020-optional-cordis-tools-in-ptc-mode.md).
 
-The host execution provider must use TypeScript. Changing it to another language during reload withdraws the active PTC runtime and reports a diagnostic; returning to TypeScript reactivates it without changing the plugin setting.
+Capabilities and context is an experimental group, off by default. It selects availability and disclosure for Skills, tools, and MCP capabilities by category, source, or item, and it also covers Initial prompt, Prompt recovery, Output excerpts, and Usage statistics; the switch beside its title pauses the whole group while keeping every choice, and changes apply to new sessions or to a session after an explicit refresh. The sparkle menu also opens the session capability workbench, which views and adjusts the current session's capabilities by category, source, and state: edits live in one draft that you can apply to this session only or save as the global default. See the [configuration reference](docs/runtime-reference.md#configuration) for fields, defaults, and full limits.
 
-![PTC Plus settings card](assets/ptc-plus-settings-en.png)
+Before a new session starts, capability and global binding changes only update its initial configuration; no change notices are sent or queued. The first request uses the resulting configuration.
 
-## Value transfer and state recovery
+The host execution provider must use TypeScript; changing it to another language during a reload withdraws the plugin and reports a diagnostic, and switching back re-enables it.
 
-### Preserve values beyond plain JSON
+With DSH's official `executionMode: persistent-in-memory` enabled, **Prioritize the official REPL mode** under State and recovery chooses who owns the PTC session: disabled by default, so PTC Plus owns `run_code`; enabled, the official runtime owns execution and PTC Plus leaves execution, REPL state semantics, and observation to it. The setting has no effect while the official mode is off. Ownership changes take effect immediately and leaving plugin execution disposes its in-memory environment. Official in-memory state follows DSH's Agent/provider lifecycle; changing priority does not guarantee clearing it. Official-mode calls stay outside the plugin's records, so they never count as recoverable state after switching back to the plugin.
 
-Within the supported value domain, tool arguments, results, and recovery records preserve `undefined`, BigInt, `NaN`, infinities, sparse arrays, cycles, and shared references. Ordinary JSON results remain structured values; special values are displayed as readable text to the model, separately from their program values.
+![PTC Plus settings window](assets/ptc-plus-settings-en.png)
 
-This does not make every JavaScript object transferable or persistent: functions, Promises, class instances, Date, Map, and Set are outside the value-transfer domain. Keeping a function in the REPL for later calls is different from returning that function as a tool result. Reuse session variables for continued computation; see the [value-transfer specification](docs/value-wire.md) for the complete supported domain.
+## Value transfer and state recovery
 
-### Recover state with verifiable history
+Stopping a background subagent preserves the parent session's REPL state, so calls triggered by its notification can continue using the parent's variables. If the parent session itself is disposed, later calls follow the recovery rules below.
 
-Session state is not permanent memory. After a restart, runtime reset, or context compaction, only state verifiable from session records whose provenance remains in the model's context can be retained. Direct file or network inputs, damaged history, and compacted source provenance can reduce what remains available.
+Within the supported range of the plugin's graph IPC, program arguments, results, and recovery records keep `undefined`, BigInt, `NaN`, infinities, sparse arrays, cycles, and shared references, and supported values can be returned directly without writing `JSON.stringify` yourself (it drops object fields containing `undefined`, turns `NaN` and infinities into `null` and `-0` into `0`, and rejects BigInt). Functions, Promises, class instances, Date, Map, and Set are outside that range, and native `tools.*` JSON argument and result contracts do not change; see the [value contract](docs/value-wire.md).
 
-Unverifiable state is discarded with a diagnostic; if necessary, the current computation continues in an empty environment. Recovery neither redispatches recorded native-tool calls nor reverses historical external effects. See the [runtime reference](docs/runtime-reference.md) for recovery evidence and limits.
+Session state is not permanent memory: after a restart, a runtime reset, or context compaction, only state verifiable from session records whose provenance remains in the model's context is retained, and everything else is discarded with a diagnostic, continuing in an empty environment when necessary. Missing or damaged session records produce an explicit error instead of being treated as a successfully recovered empty session. Recovery neither redispatches recorded native-tool calls nor reverses historical external effects; see the [runtime reference](docs/runtime-reference.md) for its evidence and limits.
 
 ## Boundaries
 
-- **Execution permissions**: primarily designed for `danger-full-access`. Code can access Node.js and the operating system directly; the plugin adds no security sandbox. DSH continues to own native-tool permissions, approvals, cancellation, and sandbox policy.
-- **Failures and reruns**: a failed execution does not mean earlier statements had no effect. Process isolation, editing, and recovery do not guarantee that external operations are safe to repeat. Timeouts or output overflow can also release the computation environment.
-- **Errors and cost**: language adaptation and call tolerance do not guarantee that every program succeeds. Actual call counts and token usage depend on the task and model; see the [evaluation notes](docs/evaluation.md#recorded-paired-observation) for a recorded comparison and its limitations.
+- **Execution permissions**: primarily designed for `danger-full-access`. Code can reach Node.js and the operating system directly, and the plugin adds no security sandbox; native-tool permissions, approvals, cancellation, and sandbox policy stay with DSH.
+- **Failures and reruns**: a failed execution does not mean earlier statements had no effect. Process isolation, editing, and recovery do not make an external operation safe to repeat, and a timeout or an output overflow can release the computation environment.
+- **Errors and cost**: language adaptation and call tolerance do not guarantee that every program runs, and actual call counts and token usage depend on the task and model; the [evaluation notes](docs/evaluation.md#recorded-paired-observation) record one comparison and its limits.
 
 PTC Plus is a community plugin, with no affiliation with or endorsement from DeepSeek or DSH.
 
-## Further reading
+## Development
+
+Development happens in the repository root: `npm ci` installs dependencies and `npm run build` regenerates `client.cjs` and the compiler artifacts. Focused tests require an explicit selection:
+
+```sh
+npm run test:backend:focus -- --file test/<owner>.test.js --test-name-pattern="<case>"
+npm run test:client:focus -- "<test name pattern>"
+```
 
-[Installation and upgrades](docs/installation.md) · [Global bindings](docs/user-bindings.en.md) · [Runtime reference](docs/runtime-reference.md) · [Architecture and development](docs/architecture.md) · [Verification](docs/verification.md) · [All documentation](docs/README.md)
+Before delivery, pick the check through [change classification](docs/verification.md#change-classification): documentation-only changes run `npm run verify:docs`, everything else runs `npm run check`, and both are followed by the [review procedure](docs/review-procedure.md). Architecture and the data plane are in [architecture and development](docs/architecture.md), the [documentation index](docs/README.md) lists everything, and installation and publishing are covered by the [installation guide](docs/installation.md) and the [publishing procedure](docs/publishing.md).
 
 [MIT License](LICENSE)