dsh-mnemon 0.1.1 → 0.1.3

package/docs/en/interfaces.md

@@ -1,75 +1,61 @@
 # WebUI, Tools, Commands, and RPC
 
-[简体中文](../zh-CN/interfaces.md) | **English** | [Documentation Center](./README.md)
+[简体中文](../zh-CN/interfaces.md) | **English** | [Documentation hub](./README.md)
 
-## Web Workspace
+This page is an integration reference. For daily use, start with the [Sidebar and conversation UI guide](./ui-guide.md).
 
-The main Web interface follows DSH's global language and light/dark theme. The top navigation is split into three divider-separated groups: “Status” stands alone; “Runtime, Memory Spaces, Documents” cover the three storage tiers; “Distill, Recall, Entities, Content” are the read/write tools. The “Status” page opens by default.
+## User-facing entry points
 
-| Page | Purpose | Call Boundary |
-|---|---|---|
-| Status | Diagnostics for the CLI, runtime hot memory, storage scope, Memory Spaces, Documents, lifecycle, and workers | Aggregated reads |
-| Runtime | Inspect and maintain USER / MEMORY hot memory and capacity | Regular mutations are deterministic; capacity maintenance may start a worker |
-| Memory Spaces | Memory Space directory, activation switches and metadata editing, a live multi-space graph, and node inspection | Deterministic RPC reads; switches and metadata edits use write RPC |
-| Documents | Search, read, create, update, and archive Documents | Search/edit operations use the control layer; archiving starts a worker |
-| Distill | Let a memory worker select scope, deduplicate, and write; supports advanced constraints | `spawn` semantic write |
-| Recall | Direct smart / keyword / basic retrieval; optional evidence-bounded Agent answers | Direct service reads; Agent answers use a worker with no tools |
-| Entities | Frequent entities and entity-related context | Direct service reads |
-| Content | Browse active Memory Spaces without recall side effects, copy or clone content, or soft-delete it | Graph reads; deletion uses a worker |
-
-The graph synchronizes every 15 seconds and can also be refreshed manually. Natural layout, uniform reset, dragging, and keyboard adjustments affect only client-side presentation and do not modify Mnemon data.
-
-### In-Conversation Interaction
-
-The memory system surfaces inside the conversation flow through three native DSH slots, all purely additive registrations that replace no official rendering:
-
-| Slot | Presentation | Data and interaction |
-|---|---|---|
-| `tool.call.toolview` (keyed by tool name) | Every `mnemon_*` tool call renders as a memory-flavoured card row: state dot, Mnemon mark, recall/write title, and a tool-specific summary; hovering reveals “Open in Memory view” and “Inspect” | Summaries derive from the call arguments and the settled result JSON (recall/document-search hit counts, engine health for status, catalogue stats for bodies, …); expanding shows the raw arguments and result; jumps use the `mnemon:anchor` event channel to open the matching Memory view page (with a query seed) |
-| `conversation.chat.turnTail` (chain) | One “Turn memory · recalled N · wrote M · document search K” line above the turn-tail actions; expanding lists the exact tool names and offers a jump to the Status page | The read-only RPC `turn-activity` counts `mnemon_*` calls per turn from the Host's durable session log; the chain `select` declines open turns, and turns without memory activity render nothing |
-| `conversation.chat.assistant-actions` (list, id `mnemon-save`) | A “Save to memory” action beside finalized assistant replies (next to feedback); clicking opens the candidate panel | The panel extracts the message text by messageId through the read-only RPC `assistant-message` into an editable candidate; submission goes through the existing `supervise` write RPC (supervised writeback: memory subagent judgment, dedupe, Memory Space choice) and shows the subagent receipt; read-only deployments are disabled up front with a note |
+| Entry | Default | Description |
+|---|---:|---|
+| Sidebar | Yes | Dedicated Memory System workbench with Status, Runtime, Memory Spaces, and Documents |
+| Buildin | No | Original `conversation.view` tab with established visuals |
+| Turn memory | Yes | Memory-tool summary for a completed turn, with exact page links |
+| Save to memory | Yes | Action beside finalized assistant replies; confirmation invokes supervised writing |
+| `/mnemon` | — | Conversation command entry |
+| Model tools | — | Structured Root Agent read/write entry |
 
-`turn-activity` and `assistant-message` are new read-only endpoints sharing the existing Host channel and error semantics. The rendering-extension contracts behind the in-conversation interaction and the follow-up inline memory-highlight plan are recorded in the Mnemon document “dsh-mnemon 对话内记忆交互侦察”.
+Sidebar and Buildin are live, mutually exclusive mounts that share functionality, data, and Host services. The two conversation entries can be disabled independently through `mnemon-ui` settings.
 
-## Model Tools
+## Model tools
 
-### Read-Only Tools
+### Read-only tools
 
-| Tool | Purpose | Root Agent Path |
+| Tool | Purpose | Root Agent path |
 |---|---|---|
-| `mnemon_memory_bodies` | Read the Memory Space directory and statistics | Direct service |
+| `mnemon_status` | Aggregated CLI, configuration, storage, and directory status | Direct service |
+| `mnemon_memory_bodies` | Read Memory Space directory and statistics | Direct service |
 | `mnemon_recall` | Recall from one or more active spaces | `spawn` recall worker |
-| `mnemon_related` | Traverse relationships from a known ID | `spawn` related worker; the root path always requests two hops |
-| `mnemon_status` | Aggregate CLI, configuration, and active-space status | Direct service |
-| `mnemon_document_search` | Deterministically search managed Documents | Direct Documents control layer |
+| `mnemon_related` | Traverse from a known ID | `spawn` related worker; Root defaults to two hops |
+| `mnemon_document_search` | Deterministically search managed Documents | Documents control layer |
 
-Here, “read-only” means that managed bodies and long-term semantic content are not modified. After a hit, `mnemon_document_search` still updates `lastAccessedAt` and rewrites the Document index for LRU ordering.
+“Read only” means managed bodies and durable semantics do not change. `mnemon_document_search` still updates `lastAccessedAt` for LRU ordering, so feature read-only is not disk read-only.
 
-### Tools Available When `writeEnabled=true`
+### Tools available with `writeEnabled=true`
 
-| Tool | Purpose | Root Agent Path |
+| Tool | Purpose | Root Agent path |
 |---|---|---|
-| `mnemon_runtime_memory` | `add` / `replace` / `remove` hot memory | Deterministic control layer; a worker is used when add overflows |
-| `mnemon_document_manage` | Create, update, or archive a Document | Create/update are deterministic; archive uses a worker |
-| `mnemon_remember` | Distill one insight into long-term memory | `spawn` write worker |
+| `mnemon_runtime_memory` | `add` / `replace` / `remove` hot memory | Deterministic control; add overflow may start a worker |
+| `mnemon_document_manage` | Create, update, or archive a Document | Create/update deterministic; archive uses a worker |
+| `mnemon_remember` | Retain one durable insight | `spawn` write worker |
 | `mnemon_link` | Create a typed relationship | `spawn` write worker |
-| `mnemon_forget` | Soft-delete by exact ID | `spawn` write worker |
+| `mnemon_forget` | Soft-delete an exact ID | `spawn` write worker |
 | `mnemon_memory_body_create` | Create an independent Memory Space | `spawn` write worker |
 | `mnemon_memory_body_update` | Update name, description, or active state | `spawn` write worker |
-| `mnemon_memory_body_merge` | Perform a non-destructive import merge | `spawn` write worker |
+| `mnemon_memory_body_merge` | Non-destructive import merge | `spawn` write worker |
 
-When a worker calls a tool with the same name, the call goes directly to the service layer and is not delegated again.
+When a worker invokes the same tool name, it reaches the service directly and is not delegated recursively.
 
-## Tool Admission Guidelines
+## Tool admission
 
-- Hot memory: explicit user preferences, stable project conventions, environment facts, and frequently useful lessons.
-- Document: designs, investigations, procedures, or handoffs with complete structure and rationale.
-- Long-term Memory Space: stable insights that explicitly need to persist across tasks or benefit from graph relationships and deep recall.
-- Skip: questions, guesses, temporary progress, completion logs, raw output, secrets, and repository facts that are easy to rediscover.
+- **Runtime**: explicit preferences, stable project conventions, environment facts, and high-frequency lessons.
+- **Documents**: designs, investigations, procedures, postmortems, or handoffs with complete structure and rationale.
+- **Memory Spaces**: stable facts, decisions, and insights that must survive across tasks or benefit from graph relationships.
+- **Skip**: questions, guesses, temporary progress, completion logs, raw output, secrets, and ordinary repository facts that are easy to rediscover.
 
-`mnemon_forget` is a destructive semantic operation. It should run only when the user explicitly requests it or when content has been verified as incorrect or obsolete.
+`mnemon_forget` is a destructive semantic action. Use it only on explicit request or after confirming that content is wrong or obsolete.
 
-## `/mnemon` Commands
+## `/mnemon` commands
 
 ```text
 /mnemon
@@ -80,18 +66,35 @@ When a worker calls a tool with the same name, the call goes directly to the ser
 /mnemon forget <exact ID>
 ```
 
-- An empty `/mnemon` is equivalent to `status`.
-- `status` is a deterministic read and does not start a model.
-- `recall`, `related`, `remember`, and `forget` use the live Agent containing the command as the worker parent.
+- Empty `/mnemon` equals `status`.
+- `status` is deterministic and starts no model.
+- `recall`, `related`, `remember`, and `forget` use the live Agent containing the command as worker parent.
 - Command recall returns at most 10 results.
-- The `forget` argument must be one exact ID containing no spaces.
-- Current command help and results are primarily in Chinese and do not yet follow the Web locale.
+- `forget` requires one exact ID without spaces.
+
+## In-conversation contracts
+
+| DSH slot | Registration | Behavior |
+|---|---|---|
+| `conversation.chat.turnTail` | chain | `turn-activity` summarizes `mnemon_*` calls from completed turns; open turns and turns without activity render nothing |
+| `conversation.chat.assistant-actions` | list, `id=mnemon-save` | `assistant-message` reads finalized text; `supervise` runs only after confirmation |
+
+Both are additive and replace no official DSH rendering. The assistant-message candidate is editable and long replies are bounded by the UI preview limit. Persistence is complete only after a memory-subagent receipt.
+
+## Workspace routing
+
+Workbench requests carry `sessionId` and an optional `workspaceId`. The Host accepts only IDs registered in `workspaceRegistry`:
 
-## RPC Channels
+- deterministic reads and manual maintenance may route to the inspected root selected by `workspaceId`;
+- Agents, tools, commands, and lifecycle hooks still route by the Agent cwd associated with `sessionId`;
+- `status.workspaceContext` returns selected / effective roots and `aligned`;
+- Agent-backed operations are rejected while misaligned.
 
-RPC is the internal bridge between the DSH Host and this plugin's Web client. It is not a promised stable external HTTP API.
+## RPC channels
 
-### Read Channel
+RPC is an internal Host-to-client bridge, not a stable external HTTP API.
+
+### Read channel
 
 ```text
 channel:   /dsh-mnemon-read
@@ -100,20 +103,17 @@ authority: trusted-host
 
 | Endpoint | Behavior |
 |---|---|
+| `status` | Aggregated service, version, lifecycle, Documents, and workspace/storage context |
+| `versions` | Check installed/latest Mnemon and dsh-mnemon versions and installation sources |
 | `runtime-memory` | Runtime snapshot |
-| `status` | Aggregated service, lifecycle, Documents, and storage-scope status |
-| `documents` | Document directory snapshot |
-| `document` | Read one Document |
-| `document-search` | Deterministic search; hits update LRU metadata |
-| `graph` | Aggregated graph of active Memory Spaces |
-| `bodies` | Memory Space directory |
-| `list` | Content list |
-| `entities` | Entity statistics or entity-related context |
-| `search` | Direct Mnemon retrieval |
-| `agent-search` | Evidence-bounded answer after direct retrieval |
-| `related` | Direct relationship traversal |
-
-### Write Channel
+| `documents` / `document` / `document-search` | Directory, body, and deterministic search |
+| `graph` / `bodies` | Active multi-space graph and Memory Space directory |
+| `list` / `entities` | Durable content list and entity aggregation |
+| `search` / `agent-search` / `related` | Direct retrieval, evidence answer, and relation traversal |
+| `turn-activities` / `turn-activity` | Session-wide or single-turn memory-tool activity |
+| `assistant-message` | Finalized assistant text by messageId |
+
+### Write channel
 
 ```text
 channel:   /dsh-mnemon-write
@@ -123,29 +123,44 @@ authority: loopback
 | Endpoint | Behavior |
 |---|---|
 | `runtime-memory` | Hot-memory mutation |
-| `supervise` | Submit a Tab candidate to a memory worker |
+| `supervise` | Submit a candidate to the memory worker |
 | `document` | create / update / archive |
-| `remember` | Semantic write with optional advanced constraints |
-| `link` | Create a relationship |
-| `forget` | Soft-delete |
-| `body-create` | Create a Memory Space |
-| `body-update` | Update metadata or active state |
+| `remember` / `link` / `forget` | Durable semantic write, relation, and soft deletion |
+| `body-create` / `body-update` / `body-delete` | Create, edit, or physically delete a confirmed Memory Space |
+| `version-update` | Update a named component with Host-fixed commands and arguments |
+
+With `writeEnabled=false`, the channel remains registered but mutations are rejected at the Host boundary.
+
+### Backup channel
+
+```text
+channel:   /dsh-mnemon-pack
+authority: loopback
+```
+
+| Endpoint | Behavior |
+|---|---|
+| `target` | Effective root and scope |
+| `export` | Export a complete ZIP with manifest and SHA-256 checksums |
+| `inspect` | Parse and verify an import ZIP, returning component and occupancy preview |
+| `import` | Safely merge into the effective root; rejected in read-only mode |
 
-The entire write channel is not registered when `writeEnabled=false`.
+Backups contain private memory, so the entire channel is loopback-only.
 
-### Settings Channel
+### Settings channel
 
 ```text
 channel:   /dsh-mnemon-settings
 authority: loopback
+namespaces: mnemon, mnemon-ui
 endpoints: get, mutate
 ```
 
-Mutations use the settings revision to prevent overwriting concurrent edits.
+Mutations use settings revisions to prevent overwriting concurrent edits. `mnemon` owns Host/storage settings; `mnemon-ui` owns `turnBar` and `saveAction`.
 
-## npm Exports
+## npm exports
 
-The root package exposes Host-side composition and core classes:
+The root package exposes Host composition and core classes:
 
 ```text
 apply
@@ -159,13 +174,8 @@ MnemonSubagentCoordinator
 MnemonLifecycle
 ```
 
-`dsh-mnemon/client` provides `apply` and `inject` for the DSH client bundle. `MnemonClient` and the RPC endpoints are currently internal implementations and should not be treated as a stable public SDK.
-
-## Internationalization Scope
+`dsh-mnemon/client` exports `apply` and `inject` for the DSH client bundle. Client implementation classes and RPC endpoints are internal and should not be treated as a stable public SDK.
 
-The Web dictionaries keep Chinese and English keys in one-to-one correspondence. Brand names, tool names, and configuration keys are not translated. Surfaces that are not yet fully internationalized include:
+## Internationalization
 
-- `/mnemon` command output;
-- model-tool card titles;
-- some Host validation and diagnostic errors;
-- default names and descriptions written during legacy Store compatibility discovery.
+The main Sidebar / Buildin workbench, settings, and conversation entries support Chinese and English and follow DSH locale live. Brand names, tool names, and configuration keys are not translated. `/mnemon` commands, model-tool cards, some Host errors, and compatibility metadata remain partially untranslated.

package/docs/en/operations.md

@@ -1,10 +1,10 @@
 # Operations, Security, and Troubleshooting
 
-[简体中文](../zh-CN/operations.md) | **English** | [Documentation Center](./README.md)
+[简体中文](../zh-CN/operations.md) | **English** | [Documentation hub](./README.md)
 
-## Health Checks
+## Health checks
 
-Check the binary first, then the plugin's aggregated status:
+Check the binary, then open **Status** in the workbench:
 
 ```sh
 command -v mnemon
@@ -15,141 +15,152 @@ mnemon --version
 /mnemon status
 ```
 
-`mnemon status` opens the effective Store, so the upstream CLI may initialize default data or run migrations. It is not a completely side-effect-free read probe. The plugin's Status page also checks active Memory Spaces, Documents, lifecycle state, and subagent counts.
+[![Status with component versions, three-tier data, and effective directories](../assets/screenshots/status-overview.png)](../assets/screenshots/status-overview.png)
 
-## Security Boundaries
+Status shows Mnemon / dsh-mnemon versions, Runtime, Memory Spaces, Documents, and effective directories. `mnemon status` opens the effective Store and may initialize data or run upstream migrations, so it is not a completely side-effect-free probe.
 
-### Process
+## Version checks and updates
 
-- `spawn(command, args, { shell: false })`; shell commands are never concatenated.
-- stdout + stderr have a combined default limit of 2 MiB.
-- Every CLI call is governed by `timeoutMs` and an AbortSignal.
-- On timeout or cancellation, the process first receives `SIGTERM`, then `SIGKILL` if it has not exited after 1.5 seconds.
-- CLI calls within one `MnemonRunner` are serialized to avoid SQLite lock conflicts from concurrent migrations in the same process.
+**Check versions** on Status opens the version panel:
 
-The serial queue does not replace coordination across DSH processes. When multiple Hosts access the same Mnemon Store concurrently, they still rely on Mnemon/SQLite's own concurrency semantics.
+[![Check and update Mnemon CLI and dsh-mnemon](../assets/screenshots/version-check.png)](../assets/screenshots/version-check.png)
 
-### Files
+- **Mnemon CLI**: installed from `mnemon --version`; latest from Mnemon GitHub Releases.
+- **dsh-mnemon**: installed from the running package; latest from the npm registry.
 
-- Runtime and Documents both use an in-process queue and a cross-instance lock file.
-- Lock acquisition waits up to 5 seconds by default; a lock is considered stale only after 30 seconds.
-- Writes use temporary files and rename.
-- Runtime uses a revision to prevent stale compaction from overwriting concurrent changes.
-- Document archiving uses a numeric revision to prevent moving active source text that has since been updated.
-- `sourcePaths` cannot escape the initiating session's workspace or point into the managed Documents directory.
+Checking is read-only and never installs automatically. Update appears only when a newer version exists and the source is safely recognized. Mnemon supports Homebrew Cask / Formula and `go install`; dsh-mnemon supports npm installations managed by pnpm in the owning DSH Profile. `link:` / `file:` development builds and unrecognized manual installs show guidance only.
 
-### Web
+The Host fixes update commands and arguments. The browser cannot supply either; shell is disabled and execution/output are bounded. After an update, the UI rechecks both components and refreshes Status automatically. Mnemon applies on the next CLI call. Restart `dsh web` after updating dsh-mnemon.
 
-- Read RPC: `trusted-host`.
-- Memory write RPC: `loopback`.
-- Settings RPC: `loopback`.
-- The WebUI neither reads SQLite directly nor starts processes.
+## Backup and recovery
 
-### Model
+### Recommended: Settings ZIP
 
-- Workers use a persona, a tool allowlist, structured output, and `maxDepth: 1`.
-- User queries, candidate content, Document bodies, and historical memories are all treated as untrusted data.
-- The evidence-answer worker has no Mnemon tools and can use only the hits supplied by the Host.
+**Settings → Memory System → Backup and migration** operates on the **currently effective root**:
 
-These boundaries are not a secret scanner. There is currently no deterministic credential/secret detection. Do not submit keys, tokens, private keys, or raw sensitive logs to hot memory, Documents, or Memory Spaces.
+- **Export ZIP** includes Runtime, Documents, and every Memory Space.
+- **Import ZIP** previews, validates, then merges into the effective root.
+- Packs include `manifest.json`, SHA-256 inventory, and component summaries.
+- Export/import hold component locks; a Memory Space with an uncheckpointed WAL is rejected.
+- Import checks paths, counts, compressed/expanded limits, JSON schemas, Document hashes, registry consistency, and SQLite headers.
+- Merge is staged before replacing component directories; commit failure restores pre-import directories.
 
-### Security reporting
+The UI offers safe merge, not “overwrite everything”:
+
+- Runtime deduplicates by target and content.
+- Identical Document ID + hash is skipped; conflicting content receives a new ID.
+- Identical Memory Space ID + database is skipped; conflicting content receives a new ID.
+
+Import is governed by `writeEnabled` and is rejected in read-only deployments. A ZIP contains private memory—encrypt it, restrict access, and rehearse recovery.
 
-Report vulnerabilities privately through the channels in [SECURITY.md](../../SECURITY.md) (GitHub Security Advisories or maintainer email) — do not open a public issue. Typical in-scope issues include data loss, path traversal, lock/revision-check bypasses, subagent isolation breaks, and injection via memory content rendered by the WebUI.
+### Recovery rehearsal
 
-## Backup
+1. Select an isolated `custom` directory and save.
+2. Confirm **Current directory ZIP** points to that root.
+3. Select the backup, review its preview, then import.
+4. Check Runtime, Documents, Memory Spaces, and directories on Status.
+5. Run one focused direct recall and read one Document.
+6. Only after verification decide whether to switch a production scope.
 
-All three tiers share `storageRoot`. A consistent backup should cover the entire root, not just `mnemon.db`:
+Never restore directly into the only production root without another backup.
+
+### Filesystem snapshot
+
+To preserve reserved `state` or take an offline complete snapshot, stop every DSH / Mnemon process using the root and copy:
 
 ```text
 <storageRoot>/runtime
 <storageRoot>/documents
 <storageRoot>/data
-<storageRoot>/state    # when present
+<storageRoot>/state    # when present; outside the built-in Pack's three data components
 ```
 
-Recommended procedure:
+Generate an inventory or checksums and rehearse recovery in isolation. A normal directory copy while writers are running is not a consistent snapshot.
 
-1. Stop the DSH Host and any other process writing to the same root.
-2. Record the current plugin, DSH, and `mnemon --version` versions.
-3. Copy the entire root to a new timestamped directory.
-4. Generate a file inventory or checksums for the backup.
-5. Complete a recovery rehearsal in an isolated path before relying on the backup.
+## Changing storage scope
 
-The project currently has no built-in consistent snapshot, export, or recovery command. Copying while the system is running may capture an inconsistent state across files.
+Saving `global` / `workspace` / `custom` initializes a new runtime graph before switching atomically. The page reloads automatically, but **data is not migrated**:
 
-## Recovery
+```text
+old scope -- save --> new empty or existing root
 
-1. Stop every DSH/Mnemon process using the target root.
-2. Preserve a second copy of the existing root; do not overwrite the only copy of the data.
-3. Restore the complete backup to a new directory.
-4. First point `storageScope=custom` at the new directory.
-5. Start the system and inspect the Runtime projections, Document index, Memory Space directory, and recall.
-6. After verification, decide whether to replace the original root.
+no automatic copy
+no automatic merge
+no automatic delete
+```
 
-If `USER.md` / `MEMORY.md` is damaged, the control layer can repair it from a valid `memories.json`. There is no general automatic repair flow for damaged JSON, the Document index, or SQLite.
+Recommended migration: export from the old scope → switch and confirm the new root → import → verify. In Workspace mode, confirm both inspection and execution targets.
 
-## Changing Storage Scope
+## Security boundaries
 
-The plugin does not migrate data automatically:
+### Process
 
-```text
-old scope -- change setting + save --> new empty or existing scope
+- CLI uses `spawn(command, args, { shell: false })`.
+- stdout + stderr are capped at 2 MiB by default.
+- Calls use `timeoutMs` and AbortSignal; cancellation sends `SIGTERM`, then `SIGKILL` after 1.5 seconds.
+- One Runner serializes calls; separate DSH processes still rely on Mnemon / SQLite concurrency.
 
-no implicit copy
-no implicit merge
-no implicit delete
-```
+### Files
 
-When migration is required, stop writes and copy the complete root. Two roots cannot be merged by overwriting directories because JSON indexes, the registry, and multiple databases may conflict. Design an explicit merge procedure against backups instead.
+- Runtime, Documents, and Pack operations use in-process queues or component locks.
+- Lock wait defaults to 5 seconds; stale threshold is 30 seconds.
+- Writes use temporary files, staging, and rename.
+- Runtime revisions block stale compaction; Document revisions block movement of updated originals.
+- `sourcePaths` cannot escape the initiating workspace or point into managed Documents.
 
-## Troubleshooting
+### Web and model
 
-| Symptom | Check and Resolution |
-|---|---|
-| Mnemon is unavailable | Run `command -v mnemon` and `mnemon --version`; set `MNEMON_CLI_PATH` or `cliPath`, then restart |
-| Status is healthy but recall is empty | Check that a Memory Space is active, inspect the current `storageScope` and DSH launch cwd, and make sure the query is focused enough |
-| `memoryBodyId is required...` | The active count is not exactly 1; have the worker or caller select a target explicitly |
-| `memory body is not active for reading` | Activate the target in Overview; writing to an inactive space is allowed, but reading is not |
-| Subagent provider error | Regular tasks require the full isolation capabilities; background review additionally requires `fork + inheritsParentContext` |
-| Settings have no effect after saving | Check the UI error; all options should apply live after a successful Save |
-| Custom directory is rejected | Use an absolute path, `~`, or `~/...` |
-| Document has no workspace | The session must correspond to a live root Agent and include cwd in its session header |
-| Source path is rejected | The path must stay within the session workspace and must not reference the managed Documents directory |
-| Runtime replace exceeds capacity | Shorten the replacement or organize it explicitly first; current automatic maintenance handles only add overflow |
-| CLI timeout | Increase `timeoutMs`; status and graph exports for large Stores may take longer than 10 seconds |
-| Lock timeout | Check whether another instance is writing; do not delete a lock that still belongs to a live process |
-| Invalid JSON / unexpected viz | The CLI output protocol may be incompatible; validate the version against an isolated root and do not continue writing production data |
-| A remote page can read but not write | Write RPC enforces loopback by design |
-| `tabEnabled=false` still shows the Tab | The setting currently stops only Host data RPC and does not remove the client slot |
-| Local link does not reflect source | Run `pnpm run build`, then restart the DSH profile |
+- Read RPC is `trusted-host`; write, settings, and backup RPC are `loopback`.
+- The WebUI neither reads SQLite directly, starts processes, nor supplies arbitrary update commands.
+- Workers use persona, tool allowlists, structured output, and `maxDepth: 1`.
+- Queries, candidates, Document bodies, and historical memory are treated as untrusted data.
 
-## Known Limitations
+These boundaries are not a secret scanner. There is no deterministic credential detection; never submit keys, tokens, private keys, or raw sensitive logs.
 
-### Feature Read-Only Is Not Disk Read-Only
+### Security reporting
+
+Report vulnerabilities privately through [SECURITY.md](../../SECURITY.md), not a public issue. Data loss, path traversal, lock/revision bypasses, subagent-isolation breaks, and injection through rendered memory are in scope.
 
-`writeEnabled=false` disables semantic mutations, but startup may still create or repair Runtime files, Document search updates `lastAccessedAt`, and Mnemon reads may trigger upstream migrations. Do not assume it can operate without writes on a genuinely read-only filesystem.
+## Troubleshooting
 
-### Shared Scope of Documents
+| Symptom | Check and resolution |
+|---|---|
+| Mnemon unavailable | Run `command -v mnemon`, `mnemon --version`; set `MNEMON_CLI_PATH` or `cliPath`, then restart |
+| Memory System missing from sidebar | Check `tabEnabled=true`, `displayMode=sidebar`; Buildin is in the conversation area; for a local link run `pnpm run build`, then restart |
+| Status healthy but recall empty | Check active spaces, storage scope, inspected root, effective session root, and query focus |
+| Header reports misalignment | The workbench is inspecting another workspace; align or keep deliberate read-only inspection; Agent-backed actions are rejected |
+| Saved settings appear unchanged | Inspect the save error; success applies live and reloads automatically without refresh |
+| Custom directory rejected | Use an absolute path, `~`, or `~/...` |
+| `memoryBodyId is required...` | Active count is not exactly one; select a target explicitly |
+| `memory body is not active for reading` | Activate it in Overview; inactive writes are allowed, reads are not |
+| Provider error | Semantic work needs full isolation capabilities; background review additionally needs `fork + inheritsParentContext` |
+| Runtime replace exceeds capacity | Shorten it or organize first; automatic maintenance handles add overflow only |
+| Document source path rejected | Keep it inside the session workspace and outside managed Documents |
+| CLI timeout | Increase `timeoutMs`; large Stores may need more than 10 seconds for status or graph |
+| Lock timeout | Check other writers; never delete a lock owned by a live process |
+| ZIP export reports WAL busy | Wait for Memory Space writes to settle; do not bypass the uncheckpointed-WAL guard |
+| ZIP import checksum/schema failure | The backup is damaged or incompatible; preserve the current root and never unzip over it manually |
+| No Update button | Already current, remote check failed, or the source is link/manual; follow panel guidance |
+| Remote page reads but cannot write | Write, settings, and backup RPC enforce loopback by design |
 
-`global` and `custom` may cause multiple workspaces to share one Document index; records do not have a separate workspace-ownership field. `sourcePaths` are validated against the initiating session's cwd only when written.
+## Known limitations
 
-### Cold-Reference Paths
+### Feature read-only is not disk read-only
 
-The current archive-worker prompt uses `.mnemon/documents/archived/<filename>` as its planned reference. Under global/custom scope, the actual file is at `<storageRoot>/documents/archived/<filename>`. When locating the original, use `documents/index.json` or the `relativePath` shown in the UI as the source of truth. This path-expression difference remains to be fixed.
+`writeEnabled=false` disables semantic mutation and Pack import, but startup may initialize/repair Runtime, Document search updates `lastAccessedAt`, and Mnemon reads may migrate a database.
 
-### Cross-System Transactions
+### Shared Documents scope
 
-“Index first, move second” protects the active source text but is not a rollback-capable distributed transaction across Mnemon SQLite and the filesystem. If a revision conflict occurs after indexing succeeds, the index may retain a duplicate reference; the plugin chooses to preserve data instead of rolling back a completed long-term write.
+`global` and `custom` can share one Document index across workspaces; records have no independent workspace-ownership field. `sourcePaths` are checked against the initiating cwd only when written.
 
-### Background Watermarks
+### Cross-system transactions
 
-Scores, the latest checkpoint, and retry state are not persisted. Restarting the Host clears activity that has not yet been processed. Failure backoff, circuit breaking, and a manual retry entry point are not yet implemented either.
+Cold-index-first protects active content but is not a rollback-capable distributed transaction across Mnemon SQLite and the filesystem. A revision conflict after indexing may leave a duplicate reference; the system preserves data.
 
-### Version Matrix
+### Background watermark
 
-The project does not yet declare a formal DSH/Mnemon support matrix or schema-migration policy. Back up first and validate against an isolated root before upgrading.
+Activity score, latest checkpoint, and retry state are not persisted. Host restart clears unprocessed activity. Failure backoff, circuit breaking, and manual retry are not implemented yet.
 
-### Internationalization
+### Versions and internationalization
 
-The main Web workspace is bilingual in Chinese and English, but commands, tool cards, compatibility default metadata, and some error messages are not yet fully internationalized.
+There is no formal fixed DSH / Mnemon support matrix. The main Web interface is bilingual, while commands, tool cards, compatibility metadata, and some errors remain partially untranslated.