dsh-mnemon 0.1.0

package/docs/en/assets/project-architecture.svg

@@ -0,0 +1,182 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1040" viewBox="0 0 1600 1040" role="img" aria-labelledby="title description" lang="en">
+  <title id="title">dsh-mnemon runtime architecture</title>
+  <desc id="description">DSH Web, the root Agent, and tools and commands enter the dsh-mnemon control and supervision layer, which connects to Runtime Memory, Project Documents, and long-term Mnemon Memory Spaces.</desc>
+  <style>
+    text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Inter, Arial, sans-serif; fill: #172033; }
+    .canvas { fill: #f7f9fc; }
+    .section { fill: #f0f3f8; stroke: #d7deea; stroke-width: 1.5; }
+    .card { fill: #ffffff; stroke: #d7deea; stroke-width: 1.5; filter: url(#shadow); }
+    .card-hot { fill: #fff3df; stroke: #c66a09; }
+    .card-doc { fill: #e8f1ff; stroke: #2563be; }
+    .card-long { fill: #e2f7ef; stroke: #087c5b; }
+    .title { font-size: 34px; font-weight: 720; letter-spacing: -0.6px; }
+    .subtitle { font-size: 17px; fill: #647086; }
+    .section-title { font-size: 17px; font-weight: 700; fill: #6558d9; letter-spacing: 0.4px; }
+    .node-title { font-size: 21px; font-weight: 700; }
+    .node-copy { font-size: 15px; fill: #647086; }
+    .node-code { font-family: "SFMono-Regular", Consolas, monospace; font-size: 14px; fill: #647086; }
+    .store-title { font-size: 23px; font-weight: 740; }
+    .store-copy { font-size: 15px; fill: #647086; }
+    .pill { fill: #f0f3f8; stroke: #d7deea; }
+    .pill-text { font-size: 13px; font-weight: 650; fill: #647086; }
+    .flow { fill: none; stroke: #aeb9ca; stroke-width: 2.5; marker-end: url(#arrow); }
+    .flow-hot { stroke: #c66a09; marker-end: url(#arrow-hot); }
+    .flow-doc { stroke: #2563be; marker-end: url(#arrow-doc); }
+    .flow-long { stroke: #087c5b; marker-end: url(#arrow-long); }
+    .flow-supervised { stroke: #6558d9; stroke-dasharray: 8 7; marker-end: url(#arrow-accent); }
+    .flow-label { font-size: 13px; font-weight: 650; fill: #647086; }
+    .legend { font-size: 13px; fill: #647086; }
+    .legend-line, .bus-line { marker-end: none; }
+    .bar-hot { fill: #c66a09; }
+    .bar-doc { fill: #2563be; }
+    .bar-long { fill: #087c5b; }
+  </style>
+  <defs>
+    <filter id="shadow" x="-10%" y="-20%" width="120%" height="150%">
+      <feDropShadow dx="0" dy="7" stdDeviation="10" flood-color="#21314d" flood-opacity="0.08"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#aeb9ca"/>
+    </marker>
+    <marker id="arrow-hot" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#c66a09"/>
+    </marker>
+    <marker id="arrow-doc" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#2563be"/>
+    </marker>
+    <marker id="arrow-long" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#087c5b"/>
+    </marker>
+    <marker id="arrow-accent" viewBox="0 0 10 10" refX="8.5" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#6558d9"/>
+    </marker>
+  </defs>
+
+  <rect class="canvas" width="1600" height="1040" rx="24"/>
+  <text class="title" x="64" y="58">dsh-mnemon runtime architecture</text>
+  <text class="subtitle" x="64" y="87">DSH supervises and orchestrates · Mnemon provides deterministic durable storage · all three tiers stay local</text>
+  <rect class="section" x="48" y="300" width="1504" height="394" rx="24"/>
+
+  <g aria-label="DSH interaction surfaces">
+    <rect class="card" x="64" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="88" y="146" width="96" height="27" rx="13.5"/>
+    <text class="pill-text" x="136" y="165" text-anchor="middle">DSH WEB</text>
+    <text class="node-title" x="88" y="204">Memory workspace and settings</text>
+    <text class="node-copy" x="88" y="231">Eight pages · Chinese/English · global theme</text>
+
+    <rect class="card" x="585" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="609" y="146" width="112" height="27" rx="13.5"/>
+    <text class="pill-text" x="665" y="165" text-anchor="middle">ROOT AGENT</text>
+    <text class="node-title" x="609" y="204">Current task and main context</text>
+    <text class="node-copy" x="609" y="231">Current instructions and live facts stay authoritative</text>
+
+    <rect class="card" x="1106" y="124" width="430" height="126" rx="18"/>
+    <rect class="pill" x="1130" y="146" width="142" height="27" rx="13.5"/>
+    <text class="pill-text" x="1201" y="165" text-anchor="middle">TOOLS · COMMANDS</text>
+    <text class="node-title" x="1130" y="204">Model tools and /mnemon</text>
+    <text class="node-copy" x="1130" y="231">Explicit recall, distill, links, status, maintenance</text>
+  </g>
+
+  <g aria-hidden="true">
+    <path class="flow" d="M279 250 V281 H1298 V350"/>
+    <path class="flow flow-supervised" d="M800 250 V350"/>
+    <path class="flow" d="M1321 250 V292 H800 V350"/>
+    <text class="flow-label" x="1042" y="276">typed RPC</text>
+    <text class="flow-label" x="815" y="302">tool calls</text>
+  </g>
+
+  <text class="section-title" x="80" y="337">DSH HOST · DSH-MNEMON CONTROL AND SUPERVISION LAYER</text>
+
+  <g aria-hidden="true">
+    <path class="flow bus-line" d="M300 476 V498"/>
+    <path class="flow flow-supervised bus-line" d="M800 476 V498"/>
+    <path class="flow bus-line" d="M1300 476 V498"/>
+    <path class="flow bus-line" d="M245 498 H1300"/>
+    <path class="flow" d="M245 498 V520"/>
+    <path class="flow" d="M615 498 V520"/>
+    <path class="flow" d="M985 498 V520"/>
+    <path class="flow" d="M990 630 H1190"/>
+  </g>
+
+  <g aria-label="Supervision and permission components">
+    <rect class="card" x="100" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="126" y="390">Prompt and lifecycle</text>
+    <text class="node-copy" x="126" y="420">Hot-context injection · short cues · activity score</text>
+    <text class="node-code" x="126" y="448">pre-step · turn/end · idle review</text>
+
+    <rect class="card" x="600" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="626" y="390">Subagent Coordinator</text>
+    <text class="node-copy" x="626" y="420">isolated spawn · completed-checkpoint fork</text>
+    <text class="node-code" x="626" y="448">persona · allowlist · schema · depth=1</text>
+
+    <rect class="card" x="1100" y="350" width="400" height="126" rx="17"/>
+    <text class="node-title" x="1126" y="390">RPC and permission boundary</text>
+    <text class="node-copy" x="1126" y="420">trusted-host reads · loopback writes</text>
+    <text class="node-code" x="1126" y="448">read · write · settings channels</text>
+  </g>
+
+  <g aria-label="Deterministic control components">
+    <rect class="card" x="80" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="104" y="559">Runtime Memory</text>
+    <text class="node-copy" x="104" y="587">JSON authority · Markdown projections</text>
+    <text class="node-code" x="104" y="612">lock · revision · UTF-8</text>
+
+    <rect class="card" x="450" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="474" y="559">Documents</text>
+    <text class="node-copy" x="474" y="587">index · search · active / archived</text>
+    <text class="node-code" x="474" y="612">path boundary · LRU · SHA-256</text>
+
+    <rect class="card" x="820" y="520" width="330" height="110" rx="16"/>
+    <text class="node-title" x="844" y="559">Mnemon Service</text>
+    <text class="node-copy" x="844" y="587">space routing · recall · links · graph</text>
+    <text class="node-code" x="844" y="612">active read · targeted write</text>
+
+    <rect class="card" x="1190" y="520" width="280" height="110" rx="16"/>
+    <text class="node-title" x="1214" y="559">CLI Runner</text>
+    <text class="node-copy" x="1214" y="587">argument arrays · no shell</text>
+    <text class="node-code" x="1214" y="612">serialized · timeout</text>
+  </g>
+
+  <g aria-hidden="true">
+    <path class="flow flow-hot" d="M245 630 V760"/>
+    <path class="flow flow-doc" d="M615 630 V724 H800 V760"/>
+    <path class="flow flow-long" d="M1330 630 V724 H1310 V760"/>
+    <text class="flow-label" x="262" y="718">every-turn projection</text>
+    <text class="flow-label" x="632" y="714">managed Markdown</text>
+    <text class="flow-label" x="1344" y="713">local CLI</text>
+  </g>
+
+  <g aria-label="Three local storage tiers">
+    <rect class="card card-hot" x="64" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-hot" x="88" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="116" y="809">Runtime hot memory</text>
+    <text class="node-code" x="116" y="834">&lt;storageRoot&gt;/runtime</text>
+    <text class="store-copy" x="88" y="870">memories.json is the only authority</text>
+    <text class="store-copy" x="88" y="898">USER.md 4 KiB · MEMORY.md 10 KiB</text>
+    <text class="store-copy" x="88" y="926">compact context enters every root turn</text>
+
+    <rect class="card card-doc" x="580" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-doc" x="604" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="632" y="809">Project Documents</text>
+    <text class="node-code" x="632" y="834">&lt;storageRoot&gt;/documents</text>
+    <text class="store-copy" x="604" y="870">index.json · active/ · archived/</text>
+    <text class="store-copy" x="604" y="898">complete Markdown narrative and provenance</text>
+    <text class="store-copy" x="604" y="926">cold-reference first, then move the original</text>
+
+    <rect class="card card-long" x="1096" y="760" width="440" height="194" rx="20"/>
+    <rect class="bar-long" x="1120" y="784" width="9" height="48" rx="4.5"/>
+    <text class="store-title" x="1148" y="809">Mnemon Memory Spaces</text>
+    <text class="node-code" x="1148" y="834">&lt;storageRoot&gt;/data/&lt;space-id&gt;/mnemon.db</text>
+    <text class="store-copy" x="1120" y="870">isolated SQLite Stores · active read boundary</text>
+    <text class="store-copy" x="1120" y="898">temporal · semantic · causal · entity</text>
+    <text class="store-copy" x="1120" y="926">cross-session, on-demand, attributed evidence</text>
+  </g>
+
+  <g aria-label="Legend">
+    <line x1="70" y1="996" x2="112" y2="996" class="flow legend-line"/>
+    <text class="legend" x="124" y="1001">deterministic data / control path</text>
+    <line x1="390" y1="996" x2="432" y2="996" class="flow flow-supervised legend-line"/>
+    <text class="legend" x="444" y="1001">LLM-supervised path</text>
+    <text class="legend" x="1532" y="1001" text-anchor="end">all persistent data stays under the selected storageRoot</text>
+  </g>
+</svg>

package/docs/en/configuration.md

@@ -0,0 +1,204 @@
+# Configuration Reference
+
+[简体中文](../zh-CN/configuration.md) | **English** | [Documentation Center](./README.md)
+
+## Configuration Location and Activation
+
+The plugin registers the `mnemon` namespace with the DSH settings service. User configuration is stored in:
+
+```text
+$DSH_HOME/settings.yaml
+```
+
+The default is commonly `~/.dsh/settings.yaml`. All current settings are marked as taking effect on `restart`; restart the DSH Host after saving them.
+
+The Web settings card edits only `storageScope` and `dataDir`. Other advanced settings must be changed directly in YAML.
+
+## Complete Example
+
+```yaml
+mnemon:
+  storageScope: global # global | workspace | custom
+  # dataDir: ~/mnemon-data       # required for custom
+  # cliPath: /opt/homebrew/bin/mnemon
+  # store: legacy-store          # compatibility discovery hint, not a regular routing target
+  timeoutMs: 10000
+  defaultRecallLimit: 10
+  routingGuidance: true
+  lifecycleEnabled: true
+  recallMode: guided
+  writebackMode: guided
+  idleReviewMs: 30000
+  tabEnabled: true
+  writeEnabled: true
+```
+
+## Options
+
+| Setting | Default | Range | Implementation Semantics |
+|---|---:|---|---|
+| `storageScope` | `global` | `global` / `workspace` / `custom` | Controls the root for Runtime, Documents, Memory Spaces, and reserved state as one unit |
+| `dataDir` | unset | absolute path, `~`, or `~/...` | Required for `custom`; legacy configurations that set only this option automatically resolve to `custom` |
+| `cliPath` | auto-discovered | executable path | Explicitly selects the Mnemon CLI |
+| `store` | unset | `[A-Za-z0-9][A-Za-z0-9_-]*` | Compatibility discovery/preference hint for legacy Stores; semantic operations are routed through Memory Spaces |
+| `timeoutMs` | `10000` | 100–120000 ms | Hard timeout for a single CLI call |
+| `defaultRecallLimit` | `10` | 1–50 | Default recall count for the service and UI; individual entry points may impose a lower limit |
+| `routingGuidance` | `true` | boolean | Whether to register an additional tiered-routing system section |
+| `lifecycleEnabled` | `true` | boolean | Whether to enable the pre-step cue and score-based background review |
+| `recallMode` | `guided` | `guided` / `off` | Whether to inject an on-demand recall cue; does not remove explicit recall |
+| `writebackMode` | `guided` | `guided` / `off` | Whether to inject the hot-memory cue and enable score-based background review; does not remove explicit writes |
+| `idleReviewMs` | `30000` | 5000–600000 ms | Required continuous idle time after the threshold is reached |
+| `tabEnabled` | `true` | boolean | Currently gates only Host Mnemon data RPC; the client Tab is still registered—see the limitation below |
+| `writeEnabled` | `true` | boolean | Whether to expose semantic write tools, write RPC, and write commands |
+
+## Storage Scopes
+
+### `global`
+
+```text
+MNEMON_DATA_DIR when non-empty
+  otherwise ~/.mnemon
+```
+
+Suitable for users who want Runtime, Documents, and Memory Spaces shared across multiple workspaces.
+
+### `workspace`
+
+```text
+resolve(process.cwd(), ".mnemon")
+```
+
+Here, cwd is the DSH Host process launch directory. It is not the current browser-page directory and does not necessarily match the cwd recorded for every session. Start DSH from the target project directory.
+
+### `custom`
+
+```yaml
+mnemon:
+  storageScope: custom
+  dataDir: /absolute/path/to/mnemon-data
+```
+
+`~` and `~/...` are also allowed. Relative paths are rejected.
+
+## CLI Discovery Precedence
+
+```text
+config.cliPath
+  -> executable MNEMON_CLI_PATH
+  -> each PATH directory
+  -> ~/.local/bin/mnemon
+  -> /opt/homebrew/bin/mnemon
+  -> /usr/local/bin/mnemon
+  -> /usr/bin/mnemon
+```
+
+An explicit `cliPath` is accepted as configured; if it is not executable, actual calls return a launch error.
+
+## Compatibility Store Hint Precedence
+
+```text
+config.store
+  -> MNEMON_STORE
+  -> <storageRoot>/active
+  -> default
+```
+
+After the Memory Space directory has been established, long-term semantic operations use explicit Memory Space IDs and do not rely on the global active Store for routing.
+
+## Provider Requirements
+
+Regular workers prefer `spawn`. If no provider has that name, another provider with all of the following capabilities can be selected:
+
+```text
+outputSchema = true
+toolFilter   = true
+persona      = true
+depthLimit   = true
+```
+
+Background review has no fallback: a compatible provider named `fork` must exist and must have:
+
+```text
+inheritsParentContext = true
+```
+
+A missing `fork` does not block deterministic state or regular UI reads, but a subagent failure is recorded when the review threshold is reached.
+
+## Read-Only Configuration
+
+```yaml
+mnemon:
+  writeEnabled: false
+```
+
+Effects:
+
+- Model write tools are not registered;
+- `/dsh-mnemon-write` RPC is not registered;
+- `/mnemon remember` and `/mnemon forget` are rejected;
+- semantic mutations through `MnemonService` are rejected.
+
+This is feature-level read-only behavior, not a read-only filesystem mode: the Runtime controller may still initialize or repair projections, Document search updates LRU access times, and Mnemon read commands may trigger upstream database migrations. Do not treat `writeEnabled=false` as a safety guarantee for read-only mounts.
+
+## Switch Interactions
+
+```text
+writeEnabled=false
+  -> overrides all explicit semantic writes
+
+writebackMode=off
+  -> no write cue, no scored review
+  -> explicit writes remain when writeEnabled=true
+
+recallMode=off
+  -> no recall cue
+  -> explicit recall remains
+
+lifecycleEnabled=false
+  -> no lifecycle cues or review
+  -> UI, commands, and explicit tools remain
+
+routingGuidance=false
+  -> removes only mnemon:routing
+  -> runtime-memory prompt section remains
+```
+
+## Current `tabEnabled` Limitation
+
+When `tabEnabled=false`, the Host does not register Mnemon read/write RPC, but the Web client still registers its conversation view slot unconditionally. The current result is therefore “the Tab entry may still appear while its data interface is unavailable,” not complete Tab removal. This is an implementation gap; do not rely on the setting to uninstall the UI.
+
+## Profile Patch Overrides
+
+The bundled `cordis.patch.yml` provides the default config row. A DSH profile configuration with the same ID may replace that row as a whole. When customizing a patch, retain every key that must remain enabled instead of assuming a deep merge.
+
+## Common Configurations
+
+Workspace isolation:
+
+```yaml
+mnemon:
+  storageScope: workspace
+```
+
+A custom data volume and a longer CLI timeout:
+
+```yaml
+mnemon:
+  storageScope: custom
+  dataDir: /Volumes/AgentData/mnemon
+  timeoutMs: 30000
+```
+
+Keep explicit tools while disabling lifecycle behavior:
+
+```yaml
+mnemon:
+  lifecycleEnabled: false
+```
+
+Disable only background writeback decisions:
+
+```yaml
+mnemon:
+  writebackMode: off
+```

package/docs/en/development.md

@@ -0,0 +1,178 @@
+# Development and Verification
+
+[简体中文](../zh-CN/development.md) | **English** | [Documentation Center](./README.md)
+
+## Environment
+
+The repository does not declare minimum Node, pnpm, DSH, or Mnemon versions in `package.json`. Use the current DSH development environment and verify compatibility through the full validation chain whenever dependencies are upgraded.
+
+Install dependencies:
+
+```sh
+pnpm install
+```
+
+## Standard Commands
+
+```sh
+pnpm run typecheck  # tsc --noEmit
+pnpm test           # vitest run
+pnpm run build      # declarations + host/client bundles
+pnpm run verify     # typecheck + test + build
+```
+
+## Directory Structure
+
+```text
+src/
++-- index.ts                  # Host composition root
++-- config.ts                 # settings schema
++-- process.ts / runner.ts    # local CLI execution
++-- service.ts                # durable-memory facade
++-- memory-bodies.ts          # Memory Space registry
++-- runtime-memory.ts         # hot-memory authority
++-- documents.ts              # managed Documents
++-- subagent.ts               # bounded workers
++-- lifecycle.ts              # root-Agent hooks
++-- review-activity.ts        # activity score
++-- tools.ts / commands.ts    # model and human interfaces
++-- rpc.ts / settings.ts      # Web bridges
++-- storage-scope.ts          # storage inventory
++-- client/                   # React workspace and locales
+tests/                        # Vitest suites
+lib/                          # committed build artifacts
+docs/zh-CN/                   # Chinese documentation
+docs/en/                      # English mirror
+cordis.patch.yml              # DSH profile bundle patch
+```
+
+## Build Artifacts
+
+```text
+tsc -p tsconfig.build.json
+  -> lib/types/*              declarations, maps, intermediate ESM
+
+tsdown host bundle
+  -> lib/index.js             Node ES2024 ESM
+
+tsdown client bundle
+  -> lib/client.js            DSH browser module wrapper
+  -> lib/client.js.map
+
+lightningcss plugin
+  -> CSS Modules compiled and injected as scoped <style>
+```
+
+The Host keeps `cordis` and `schemastery` external. The client keeps React, ReactDOM, the JSX runtime, and Cordis external; all other dependencies are included in the bundle.
+
+`lib/` is part of the publishing input. After modifying `src/`, rebuild and inspect the generated diff. Do not edit `lib/` manually.
+
+## Test Layers
+
+The existing Vitest suites cover:
+
+- configuration parsing, CLI discovery, and process serialization;
+- Memory Space discovery, activation, routing, and merge;
+- recall-payload compatibility and graph parsing;
+- Runtime JSON/Markdown consistency, locks, capacity, UTF-8, and revisions;
+- Document paths, frontmatter, search, LRU, archiving, and conflicts;
+- worker tool isolation, the schema subset, and structured receipts;
+- lifecycle cues, scoring, idle debounce, cancellation, and watermark retention;
+- RPC authority, read-only behavior, and settings revisions;
+- the Web workspace, bilingual copy, and key interactions.
+
+These are primarily integration tests using temporary directories, fake runners, and a mock Host. They are not equivalent to automated end-to-end tests of the real DSH + Mnemon WebUI.
+
+## Real WebUI Verification
+
+Use an isolated environment before release to avoid contaminating personal memory:
+
+```text
+temporary DSH_HOME
+temporary MNEMON_DATA_DIR or custom storageScope
+temporary workspace
+independent Web port
+local link installation
+```
+
+Recommended scenarios:
+
+1. Empty root: the UI reports no errors and can create the first Memory Space.
+2. Regular conversation: only a short cue appears; recall and writes are not forced.
+3. Historical question: the Agent independently recalls and returns the correct space provenance.
+4. Explicit distillation: the worker deduplicates, selects a scope, and writes content that can be recalled again.
+5. Multiple spaces: reads cover only active spaces; writing to an inactive space activates it automatically afterward.
+6. Runtime: USER / MEMORY add, replace, remove, and projection consistency.
+7. Documents: create, retrieve, update, manually archive, and leave original project files unchanged.
+8. Score-based review: light tasks do not trigger it; after reaching the threshold it waits for idle; a new turn can cancel it while preserving the watermark.
+9. Read-only: write tools, write commands, and write RPC are rejected while reads remain available.
+10. Status and browser console: no unhandled errors or warnings.
+
+Capacity limits, CLI timeouts, revision conflicts, and Host restarts should be verified in a dedicated fault-injection environment.
+
+## Modifying Subagent Schemas
+
+DSH structured output supports only a compact JSON Schema subset:
+
+```text
+type, oneOf, properties, required, additionalProperties,
+items, enum, const, and annotation keywords
+```
+
+Do not add unsupported keywords such as `maxItems`. `assertDshOutputSchema()` recursively rejects unknown schema keys before starting a worker; result-count and similar limits are enforced by both the persona and the Host parser.
+
+## Modifying Storage Formats
+
+Runtime, Documents, and the Memory Space registry each have a version field or fixed structure. Changes require:
+
+1. Define how the old format is parsed;
+2. add a migration or rejection path;
+3. preserve temporary-file and atomic-rename behavior;
+4. add tests for concurrency and damaged inputs;
+5. update the Chinese and English storage, operations, and Roadmap documents;
+6. verify upgrade and rollback against a copied data root.
+
+There is currently no formal schema-migration framework, so persistent formats must not change silently.
+
+## Maintaining Documentation Internationalization
+
+`docs/zh-CN` and `docs/en` should contain matching filenames with the same section responsibilities. When changing defaults, workflows, or limitations:
+
+- update both languages;
+- keep commands, configuration keys, paths, and code symbols exactly the same;
+- cross-link corresponding language pages with relative paths;
+- prefer accessible SVGs with no scripts or external resources for architecture overviews; keep directory trees, commands, formulas, and short protocols as copyable `text` / ASCII;
+- keep only summaries in the root READMEs and place details on one authoritative docs page.
+
+When the Web locale changes, the Chinese key set remains the type source of truth. The English dictionary must satisfy `Record<MnemonKey, string>` and preserve the same placeholders.
+
+## Release Checklist
+
+```text
+[ ] pnpm run verify
+[ ] review source and generated lib diffs
+[ ] validate package file list includes README.en.md and docs
+[ ] install the built/local bundle into an isolated Web profile
+[ ] run real Mnemon CLI and WebUI smoke tests
+[ ] verify Chinese and English workspaces
+[ ] verify global/workspace/custom paths as applicable
+[ ] record tested DSH and Mnemon versions
+[ ] back up any data root used for upgrade testing
+```
+
+`package.json.files` currently publishes `lib`, the patch, both root READMEs, the public bilingual docs, and the License; the historical research ledger is excluded from the installed package.
+
+## Publishing to npm
+
+After publication, `dsh plugin --profile web add dsh-mnemon` resolves by registry name — the same path as dsh-better-sidebar. Steps:
+
+```sh
+npm pack --dry-run                 # inspect the tarball file list (cordis.patch.yml, lib, docs)
+pnpm publish --access public       # prepublishOnly runs pnpm run verify first
+```
+
+Credential convention: write NPM_TOKEN only to the user-level `~/.npmrc` (`npm config set "//registry.npmjs.org/:_authToken" "${NPM_TOKEN}" --userconfig ~/.npmrc`) and remove it after publishing. Do **not** commit the credential line to the repository `.npmrc`: pnpm 11 deliberately ignores unexpanded environment-variable credentials in project-level `.npmrc` (with a warning), and that file travels with the repo.
+
+2FA note: when the npm account has publish-level two-factor authentication, an interactive `pnpm publish --access public` prompts for the OTP; scripted/CI publishing needs a Classic **Automation** token or a Granular token allowed to bypass 2FA (a plain token from `npm login` cannot publish and fails with 403 Two-factor authentication required).
+
+Before publishing, check that `package.json` `repository`/`homepage`/`bugs` point at `omdsh-dev/dsh-mnemon` (npm page consistent with GitHub) and that the version has been bumped.