dsh-synapse 0.4.1 → 0.4.2

package/cordis.patch.yml

@@ -1,13 +1,13 @@
-# dsh-synapse only extends the Web profile: it reuses the existing DSH server
-# rather than running a second application process.
-- insert:
-    - id: synapse
-      name: dsh-synapse
-      config:
-        # A profile can override this path in its own cordis.patch.yml.
-        dataFile: !!js dshHomePath('synapse/workspaces.json')
-        autoProjection: true
-        projectionWorkspaceTitle: DSH 任务
-        # Extra authorities the /synapse Host check accepts (host or host:port);
-        # localhost and 127.0.0.1 are always allowed.
-        trustedHosts: []
+# dsh-synapse only extends the Web profile: it reuses the existing DSH server
+# rather than running a second application process.
+- insert:
+    - id: synapse
+      name: dsh-synapse
+      config:
+        # A profile can override this path in its own cordis.patch.yml.
+        dataFile: !!js dshHomePath('synapse/workspaces.json')
+        autoProjection: true
+        projectionWorkspaceTitle: DSH 任务
+        # Extra authorities the /synapse Host check accepts (host or host:port);
+        # localhost and 127.0.0.1 are always allowed.
+        trustedHosts: []

package/deepseek-mark.svg

@@ -1,3 +1,3 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" aria-hidden="true">
-  <path fill="currentColor" d="M23.0584 4.95203C22.8129 4.83203 22.7074 5.06103 22.5639 5.17704C22.5149 5.21454 22.4734 5.26354 22.4319 5.30854C22.0734 5.69155 21.6543 5.94306 21.1073 5.91306C20.3073 5.86806 19.6243 6.11957 19.0203 6.73158C18.8918 5.97706 18.4652 5.52655 17.8162 5.23754C17.4767 5.08753 17.1332 4.93703 16.8952 4.61052C16.7292 4.37801 16.6837 4.11901 16.6007 3.8635C16.5477 3.70949 16.4952 3.55199 16.3177 3.52549C16.1252 3.49549 16.0497 3.65699 15.9742 3.792C15.6722 4.34401 15.5552 4.95203 15.5667 5.56805C15.5932 6.95359 16.1782 8.05712 17.3407 8.84215C17.4727 8.93215 17.5067 9.02215 17.4652 9.15366C17.3857 9.42416 17.2917 9.68667 17.2087 9.95718C17.1557 10.1297 17.0767 10.1677 16.8917 10.0922C16.2537 9.82568 15.7027 9.43117 15.2156 8.95465C14.3891 8.15513 13.6416 7.2726 12.7096 6.58158C12.4906 6.42007 12.2716 6.27007 12.045 6.12707C11.094 5.20354 12.1696 4.44502 12.4186 4.35501C12.6791 4.26101 12.5091 3.938 11.6675 3.942C10.826 3.9455 10.056 4.22751 9.07446 4.60302C8.93096 4.65952 8.77995 4.70052 8.62545 4.73452C7.73492 4.56552 6.80989 4.52802 5.84386 4.63702C4.02481 4.83953 2.57177 5.69955 1.50373 7.1676C0.220694 8.93215 -0.0813148 10.9372 0.288196 13.0283C0.676708 15.2323 1.80174 17.0569 3.53029 18.4834C5.32285 19.9625 7.38741 20.6875 9.74298 20.5485C11.1735 20.466 12.7661 20.2745 14.5626 18.7539C15.0156 18.9795 15.4912 19.0695 16.2797 19.137C16.8872 19.1935 17.4722 19.107 17.9252 19.013C18.6347 18.8629 18.5857 18.2059 18.3292 18.0854C16.2497 17.1169 16.7062 17.5109 16.2912 17.1919C17.3477 15.9419 18.9618 13.7198 19.4598 10.6942C19.5088 10.3602 19.5713 9.88968 19.5638 9.61917C19.5598 9.45417 19.5978 9.39016 19.7863 9.37116C20.3073 9.31116 20.8128 9.16866 21.2773 8.91315C22.6249 8.17713 23.1684 6.96809 23.2964 5.51905C23.3154 5.29754 23.2924 5.06853 23.0584 4.95203ZM11.3165 17.9954C9.30097 16.4109 8.32344 15.8894 7.91992 15.9119C7.54241 15.9344 7.61042 16.3664 7.69342 16.6479C7.78042 16.9259 7.89342 17.1174 8.05193 17.3614C8.16143 17.5229 8.23694 17.7629 7.94243 17.9434C7.29341 18.3449 6.16487 17.8084 6.11187 17.7819C4.79833 17.0084 3.7003 15.9874 2.92628 14.5908C2.17875 13.2468 1.74474 11.8047 1.67324 10.2657C1.65424 9.89418 1.76374 9.76267 2.13375 9.69517C2.62077 9.60517 3.12278 9.58617 3.6093 9.65767C5.66636 9.95818 7.41741 10.8777 8.88545 12.3348C9.72348 13.1643 10.3575 14.1558 11.0105 15.1243C11.705 16.1529 12.4521 17.1329 13.4036 17.9364C13.7396 18.2179 14.0076 18.4319 14.2641 18.5899C13.4906 18.6764 12.1996 18.6949 11.3165 17.9964V17.9954ZM12.2826 11.7817C12.2826 11.6167 12.4146 11.4852 12.5806 11.4852C12.6181 11.4852 12.6521 11.4927 12.6826 11.5037C12.7241 11.5187 12.7621 11.5412 12.7921 11.5752C12.8451 11.6277 12.8751 11.7027 12.8751 11.7817C12.8751 11.9467 12.7431 12.0782 12.5771 12.0782C12.4111 12.0782 12.2826 11.9467 12.2826 11.7817ZM15.2831 13.3208C15.0906 13.3998 14.8981 13.4673 14.7131 13.4748C14.4261 13.4898 14.1131 13.3733 13.9431 13.2308C13.6791 13.0093 13.4901 12.8853 13.4111 12.4988C13.3771 12.3338 13.3961 12.0782 13.4261 11.9317C13.4941 11.6162 13.4186 11.4137 13.1961 11.2297C13.0151 11.0797 12.7846 11.0382 12.5316 11.0382C12.4371 11.0382 12.3506 10.9967 12.2861 10.9632C12.1806 10.9107 12.0936 10.7792 12.1766 10.6177C12.2031 10.5652 12.3316 10.4377 12.3616 10.4152C12.7051 10.2197 13.1011 10.2837 13.4676 10.4302C13.8071 10.5692 14.0641 10.8242 14.4336 11.1847C14.8111 11.6202 14.8791 11.7402 15.0941 12.0672C15.2641 12.3228 15.4186 12.5853 15.5247 12.8858C15.5887 13.0733 15.5057 13.2268 15.2831 13.3208Z"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" aria-hidden="true">
+  <path fill="currentColor" d="M23.0584 4.95203C22.8129 4.83203 22.7074 5.06103 22.5639 5.17704C22.5149 5.21454 22.4734 5.26354 22.4319 5.30854C22.0734 5.69155 21.6543 5.94306 21.1073 5.91306C20.3073 5.86806 19.6243 6.11957 19.0203 6.73158C18.8918 5.97706 18.4652 5.52655 17.8162 5.23754C17.4767 5.08753 17.1332 4.93703 16.8952 4.61052C16.7292 4.37801 16.6837 4.11901 16.6007 3.8635C16.5477 3.70949 16.4952 3.55199 16.3177 3.52549C16.1252 3.49549 16.0497 3.65699 15.9742 3.792C15.6722 4.34401 15.5552 4.95203 15.5667 5.56805C15.5932 6.95359 16.1782 8.05712 17.3407 8.84215C17.4727 8.93215 17.5067 9.02215 17.4652 9.15366C17.3857 9.42416 17.2917 9.68667 17.2087 9.95718C17.1557 10.1297 17.0767 10.1677 16.8917 10.0922C16.2537 9.82568 15.7027 9.43117 15.2156 8.95465C14.3891 8.15513 13.6416 7.2726 12.7096 6.58158C12.4906 6.42007 12.2716 6.27007 12.045 6.12707C11.094 5.20354 12.1696 4.44502 12.4186 4.35501C12.6791 4.26101 12.5091 3.938 11.6675 3.942C10.826 3.9455 10.056 4.22751 9.07446 4.60302C8.93096 4.65952 8.77995 4.70052 8.62545 4.73452C7.73492 4.56552 6.80989 4.52802 5.84386 4.63702C4.02481 4.83953 2.57177 5.69955 1.50373 7.1676C0.220694 8.93215 -0.0813148 10.9372 0.288196 13.0283C0.676708 15.2323 1.80174 17.0569 3.53029 18.4834C5.32285 19.9625 7.38741 20.6875 9.74298 20.5485C11.1735 20.466 12.7661 20.2745 14.5626 18.7539C15.0156 18.9795 15.4912 19.0695 16.2797 19.137C16.8872 19.1935 17.4722 19.107 17.9252 19.013C18.6347 18.8629 18.5857 18.2059 18.3292 18.0854C16.2497 17.1169 16.7062 17.5109 16.2912 17.1919C17.3477 15.9419 18.9618 13.7198 19.4598 10.6942C19.5088 10.3602 19.5713 9.88968 19.5638 9.61917C19.5598 9.45417 19.5978 9.39016 19.7863 9.37116C20.3073 9.31116 20.8128 9.16866 21.2773 8.91315C22.6249 8.17713 23.1684 6.96809 23.2964 5.51905C23.3154 5.29754 23.2924 5.06853 23.0584 4.95203ZM11.3165 17.9954C9.30097 16.4109 8.32344 15.8894 7.91992 15.9119C7.54241 15.9344 7.61042 16.3664 7.69342 16.6479C7.78042 16.9259 7.89342 17.1174 8.05193 17.3614C8.16143 17.5229 8.23694 17.7629 7.94243 17.9434C7.29341 18.3449 6.16487 17.8084 6.11187 17.7819C4.79833 17.0084 3.7003 15.9874 2.92628 14.5908C2.17875 13.2468 1.74474 11.8047 1.67324 10.2657C1.65424 9.89418 1.76374 9.76267 2.13375 9.69517C2.62077 9.60517 3.12278 9.58617 3.6093 9.65767C5.66636 9.95818 7.41741 10.8777 8.88545 12.3348C9.72348 13.1643 10.3575 14.1558 11.0105 15.1243C11.705 16.1529 12.4521 17.1329 13.4036 17.9364C13.7396 18.2179 14.0076 18.4319 14.2641 18.5899C13.4906 18.6764 12.1996 18.6949 11.3165 17.9964V17.9954ZM12.2826 11.7817C12.2826 11.6167 12.4146 11.4852 12.5806 11.4852C12.6181 11.4852 12.6521 11.4927 12.6826 11.5037C12.7241 11.5187 12.7621 11.5412 12.7921 11.5752C12.8451 11.6277 12.8751 11.7027 12.8751 11.7817C12.8751 11.9467 12.7431 12.0782 12.5771 12.0782C12.4111 12.0782 12.2826 11.9467 12.2826 11.7817ZM15.2831 13.3208C15.0906 13.3998 14.8981 13.4673 14.7131 13.4748C14.4261 13.4898 14.1131 13.3733 13.9431 13.2308C13.6791 13.0093 13.4901 12.8853 13.4111 12.4988C13.3771 12.3338 13.3961 12.0782 13.4261 11.9317C13.4941 11.6162 13.4186 11.4137 13.1961 11.2297C13.0151 11.0797 12.7846 11.0382 12.5316 11.0382C12.4371 11.0382 12.3506 10.9967 12.2861 10.9632C12.1806 10.9107 12.0936 10.7792 12.1766 10.6177C12.2031 10.5652 12.3316 10.4377 12.3616 10.4152C12.7051 10.2197 13.1011 10.2837 13.4676 10.4302C13.8071 10.5692 14.0641 10.8242 14.4336 11.1847C14.8111 11.6202 14.8791 11.7402 15.0941 12.0672C15.2641 12.3228 15.4186 12.5853 15.5247 12.8858C15.5887 13.0733 15.5057 13.2268 15.2831 13.3208Z"/>
+</svg>

package/docs/architecture.md

@@ -1,104 +1,127 @@
-# Architecture and runtime boundaries
-
-## Purpose
-
-`dsh-synapse` is a presentation and organization layer for DeepSeek Harness conversations. It turns existing DSH sessions, turns, and forks into a visual map without replacing the systems that own those conversations.
-
-## Web profile integration
-
-The package contributes `cordis.patch.yml`, which inserts the `dsh-synapse` service into the DSH `web` profile. It reuses the existing DSH Web server and client runtime.
-
-The plugin:
-
-- does not start a second HTTP server;
-- does not create a second model or agent runtime;
-- does not replace DSH authentication or permission checks;
-- does not support non-Web profiles unless those profiles explicitly add the plugin.
-
-## Conversation ownership
-
-DSH session logs remain the source of truth for conversation content and lifecycle. Native DSH operations own:
-
-- creating and opening sessions;
-- sending follow-up messages;
-- forking sessions;
-- archiving sessions;
-- model and tool execution;
-- permission and approval decisions.
-
-Synapse projects committed DSH events into cards and sends user actions back through the native DSH session bridge.
-
-## Canvas metadata
-
-By default, Synapse stores canvas metadata at:
-
-```text
-$DSH_HOME/synapse/workspaces.json
-```
-
-The file contains organizational state such as workspace mapping, card layout, and fork anchors. It does not replace session logs.
-
-Consequences:
-
-- deleting the file resets canvas organization but does not delete conversations;
-- uninstalling the plugin keeps the file, so reinstalling restores the canvas;
-- older schema versions migrate when loaded;
-- two processes sharing the same file can still produce last-writer-wins replacement despite locking and external-change warnings.
-
-Run one `dsh web` instance for each shared profile.
-
-## Projection model
-
-With `autoProjection` enabled, committed DSH session events are grouped by working directory and projected into the corresponding Synapse workspace.
-
-Each user question becomes a conversation card. The following assistant messages are folded into that turn, and the final assistant reply is shown as the answer. Forked sessions connect to the parent turn at the durable DSH seed boundary rather than at an arbitrary canvas coordinate.
-
-Projected card text is capped at 8000 characters. Longer messages receive a truncation marker in the card, while their complete content remains available from the conversation detail view.
-
-Projection writes are coalesced during event bursts, and live updates reuse cached Markdown and patch the active card instead of rebuilding the complete canvas. Card coordinates remain visual metadata only and never determine conversation lineage.
-
-## Tool process folding
-
-Live events pair tool calls and results by `callId` and render them inside the related assistant reply instead of as standalone conversation cards.
-
-Legacy v3 migrations did not always have durable call IDs. Those records pair each tool call with the next tool result by order during migration.
-
-## Browser-local state
-
-Some interaction state, such as dragged card positions and branch anchors, may be cached in browser local storage to keep the canvas responsive. Durable workspace metadata is still written through the Synapse service.
-
-Private-browsing restrictions or local-storage failures must not prevent DSH conversations from operating; they only reduce persistence of visual preferences.
-
-## Host validation
-
-The `/synapse` endpoint always accepts `localhost` and `127.0.0.1`. Additional LAN or proxy authorities must be listed in `trustedHosts` as a host or `host:port` value.
-
-This validation is part of the Web surface and does not replace broader network access controls.
-
-## Model and KV-cache impact
-
-Synapse reads session events only after DSH commits them. It does not add or modify:
-
-- system prompts;
-- user request content;
-- model request headers;
-- tool schemas or registries;
-- provider routing;
-- approval context.
-
-As a result, the plugin has no direct model-experience effect and does not invalidate an otherwise reusable KV-cache prefix.
-
-## Operational limitations
-
-- Only the `web` profile is supported by the bundled patch.
-- Canvas metadata and session content have different owners and backup requirements.
-- A single shared metadata file is not a multi-writer database.
-- Browser state can be cleared independently from DSH Home data.
-- Historical migrations may have less precise tool-call pairing than live projection.
-
-## Related documentation
-
-- [Chinese user guide](zh-CN/README.md)
-- [English user guide](en/README.md)
-- [Development and release guide](development.md)
-- [Project overview](../README.md)
+# Architecture and runtime boundaries
+
+## Purpose
+
+`dsh-synapse` is a presentation and organization layer for DeepSeek Harness conversations. It turns existing DSH sessions, turns, and forks into a visual map without replacing the systems that own those conversations.
+
+## Web profile integration
+
+The package contributes `cordis.patch.yml`, which inserts the `dsh-synapse` service into the DSH `web` profile. It reuses the existing DSH Web server and client runtime.
+
+The plugin:
+
+- does not start a second HTTP server;
+- does not create a second model or agent runtime;
+- does not replace DSH authentication or permission checks;
+- does not support non-Web profiles unless those profiles explicitly add the plugin.
+
+## Conversation ownership
+
+DSH session logs remain the source of truth for conversation content and lifecycle. Native DSH operations own:
+
+- creating and opening sessions;
+- sending follow-up messages;
+- forking sessions;
+- archiving sessions;
+- model and tool execution;
+- permission and approval decisions.
+
+Synapse projects committed DSH events into cards and sends user actions back through the native DSH session bridge.
+
+## Harness compatibility
+
+This revision is built and verified against DeepSeek Harness `0.1.7-rc.2`. Both halves call Harness APIs directly, so a Harness release that changes them requires a matching plugin release.
+
+Host half (`index.js`) calls:
+
+- `ctx.webServer.register({ kind, path, handler })`, the route registry of `@deepseek-ai/dsh-host-webserver`;
+- `ctx.sessions.list()`, the live `Session` objects of `@deepseek-ai/dsh-session`;
+- the untagged (global) `session/created` and `session/event` listeners;
+- `session.snapshotEvents()` for a projection replay, `session.inheritedEventCount` for the durable fork cut, and `session.header.cwd` for workspace grouping.
+
+Client half (`client.js`), through `dsh.client.inject` in `package.json`:
+
+- `sessions.list`, `sessions.binding`, `sessions.create`, `sessions.fork` from `@deepseek-ai/dsh-api-session-controller`, plus `sessions.retain`/`release` for two purposes: owning a reference across a prompt round-trip, and owning one for every *running* Session whose live reply the map mirrors, because no Harness release mints a Session scope implicitly any more and an unowned Session has no readable Chat view;
+- `workspaces.list` from `@deepseek-ai/dsh-api-workspace-controller`;
+- `uiWorkspace.openSession` from `@deepseek-ai/dsh-client-ui-workspace` for selecting a Session;
+- `uiConversation.binding(sessionId).target('chat')` from `@deepseek-ai/dsh-client-ui-conversation` for the streaming reply and the turn anchor index, because the Client builds a view snapshot only after something subscribes to its target. A Session the browser does not observe still reports its `running` flag, which the list row carries.
+
+Two Harness dependencies are worth re-checking on every upgrade:
+
+- `snapshotEvents()` is marked deprecated: Harness is moving complete session logs out of memory. Rebuilding this canvas from history needs the full sequence, so the call remains, and it needs a storage-backed successor (an asynchronous paged read) before Harness removes it.
+- The browser half must acquire its own `SessionReference` before sending a prompt; borrowing an Agent scope no longer opens one.
+
+## Canvas metadata
+
+By default, Synapse stores canvas metadata at:
+
+```text
+$DSH_HOME/synapse/workspaces.json
+```
+
+The file contains organizational state such as workspace mapping, card layout, and fork anchors. It does not replace session logs.
+
+Consequences:
+
+- deleting the file resets canvas organization but does not delete conversations;
+- uninstalling the plugin keeps the file, so reinstalling restores the canvas;
+- older schema versions migrate when loaded;
+- two processes sharing the same file can still produce last-writer-wins replacement despite locking and external-change warnings.
+
+Run one `dsh web` instance for each shared profile.
+
+## Projection model
+
+With `autoProjection` enabled, committed DSH session events are grouped by working directory and projected into the corresponding Synapse workspace.
+
+Each user question becomes a conversation card. The following assistant messages are folded into that turn, and the final assistant reply is shown as the answer. Forked sessions connect to the parent turn at the durable DSH seed boundary rather than at an arbitrary canvas coordinate.
+
+Projected card text is capped at 8000 characters. Longer messages receive a truncation marker in the card, while their complete content remains available from the conversation detail view.
+
+Projection writes are coalesced during event bursts, and live updates reuse cached Markdown and patch the active card instead of rebuilding the complete canvas. Card coordinates remain visual metadata only and never determine conversation lineage.
+
+## Tool process folding
+
+Live events pair tool calls and results by `callId` and render them inside the related assistant reply instead of as standalone conversation cards.
+
+Legacy v3 migrations did not always have durable call IDs. Those records pair each tool call with the next tool result by order during migration.
+
+## Browser-local state
+
+Some interaction state, such as dragged card positions and branch anchors, may be cached in browser local storage to keep the canvas responsive. Durable workspace metadata is still written through the Synapse service.
+
+Private-browsing restrictions or local-storage failures must not prevent DSH conversations from operating; they only reduce persistence of visual preferences.
+
+## Host validation
+
+The `/synapse` endpoint always accepts `localhost` and `127.0.0.1`. Additional LAN or proxy authorities must be listed in `trustedHosts` as a host or `host:port` value.
+
+This validation is part of the Web surface and does not replace broader network access controls.
+
+## Model and KV-cache impact
+
+Synapse reads session events only after DSH commits them. It does not add or modify:
+
+- system prompts;
+- user request content;
+- model request headers;
+- tool schemas or registries;
+- provider routing;
+- approval context.
+
+As a result, the plugin has no direct model-experience effect and does not invalidate an otherwise reusable KV-cache prefix.
+
+## Operational limitations
+
+- Only the `web` profile is supported by the bundled patch.
+- Canvas metadata and session content have different owners and backup requirements.
+- A single shared metadata file is not a multi-writer database.
+- Browser state can be cleared independently from DSH Home data.
+- Historical migrations may have less precise tool-call pairing than live projection.
+
+## Related documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Development and release guide](development.md)
+- [Project overview](../README.md)

package/docs/development.md

@@ -1,137 +1,138 @@
-# Development and release guide
-
-This document covers local validation, package inspection, GitHub Actions, and npm release automation for maintainers.
-
-## Requirements
-
-- Node.js `>= 22.19.0`
-- pnpm through Corepack
-- A checkout of this repository
-
-## Local workflow
-
-Install with the lockfile:
-
-```powershell
-corepack pnpm install --frozen-lockfile
-```
-
-Validate JavaScript syntax:
-
-```powershell
-corepack pnpm run build
-```
-
-Run the full test suite:
-
-```powershell
-corepack pnpm test
-```
-
-Inspect the package archive:
-
-```powershell
-corepack pnpm pack
-npm pack --dry-run --json
-```
-
-The package has no generated build output. `build` runs `node --check` over `index.js`, `client.js`, and `app.js`.
-
-## GitHub Actions
-
-Three workflows live under `.github/workflows/`.
-
-### Pull request tests
-
-`pr-tests.yml` runs for pull requests targeting `main` when they are opened, reopened, updated, or marked ready for review.
-
-The workflow:
-
-1. Checks out the pull request revision.
-2. Installs pnpm 10 and Node.js 22.19.0.
-3. Runs `pnpm install --frozen-lockfile`.
-4. Runs `pnpm run build`.
-5. Runs `pnpm test`.
-
-A per-PR concurrency group cancels obsolete runs after a newer commit arrives.
-
-### Main branch tests
-
-`main-tests.yml` runs for every push to `main`, including direct commits and merged pull requests. It executes the same frozen installation, build validation, and full test suite.
-
-### npm publishing
-
-`npm-publish.yml` runs for pushed tags matching the broad GitHub pattern `v*.*.*`. The job then validates the tag strictly before publishing.
-
-Accepted forms include:
-
-```text
-v0.4.0
-v0.4.0-rc1
-v0.4.0-rc.2
-```
-
-The tag without the leading `v` must exactly equal `package.json.version`. A mismatch fails before installation or publication.
-
-| Version | Git tag | npm dist-tag |
-|---|---|---|
-| `0.4.0-rc1` | `v0.4.0-rc1` | `next` |
-| `0.4.0` | `v0.4.0` | `latest` |
-
-Every release tag reruns installation, build validation, and the complete test suite before calling `pnpm publish`.
-
-## Configure npm authentication
-
-Create a GitHub Actions repository secret named `NPM_TOKEN` in the repository where the tag workflow will run:
-
-```powershell
-gh secret set NPM_TOKEN --repo OWNER/dsh-synapse
-```
-
-The token's npm account must have permission to create or publish the public, unscoped `dsh-synapse` package. The workflow passes the secret to the publish step as `NODE_AUTH_TOKEN`; pull request and ordinary test workflows never receive it.
-
-## Release checklist
-
-1. Confirm the full test suite passes on `main`.
-2. Update `package.json.version` to the intended release version.
-3. Commit and merge the version change.
-4. Create a matching tag on that commit.
-5. Push the tag.
-6. Confirm the **Publish to npm** workflow passes.
-7. Verify the npm dist-tag:
-   - prerelease versions use `next`
-   - stable versions use `latest`
-
-Example stable release:
-
-```powershell
-# package.json already contains 0.4.0
-git tag v0.4.0
-git push origin v0.4.0
-```
-
-Example prerelease:
-
-```powershell
-# package.json already contains 0.4.0-rc1
-git tag v0.4.0-rc1
-git push origin v0.4.0-rc1
-```
-
-## Publication failure conditions
-
-The publish job stops without publishing when:
-
-- the tag is not a supported version form;
-- the tag and `package.json.version` differ;
-- frozen installation fails;
-- syntax validation or tests fail;
-- `NPM_TOKEN` is missing, expired, or lacks package permissions;
-- npm rejects the package name or an already-published version.
-
-## Documentation
-
-- [Chinese user guide](zh-CN/README.md)
-- [English user guide](en/README.md)
-- [Architecture and runtime boundaries](architecture.md)
-- [Project overview](../README.md)
+# Development and release guide
+
+This document covers local validation, package inspection, GitHub Actions, and npm release automation for maintainers.
+
+## Requirements
+
+- Node.js `>= 22.19.0`
+- DeepSeek Harness `>= 0.1.7-rc.2` for integration runs; the test suite itself installs no Harness
+- pnpm through Corepack
+- A checkout of this repository
+
+## Local workflow
+
+Install with the lockfile:
+
+```powershell
+corepack pnpm install --frozen-lockfile
+```
+
+Validate JavaScript syntax:
+
+```powershell
+corepack pnpm run build
+```
+
+Run the full test suite:
+
+```powershell
+corepack pnpm test
+```
+
+Inspect the package archive:
+
+```powershell
+corepack pnpm pack
+npm pack --dry-run --json
+```
+
+The package has no generated build output. `build` runs `node --check` over `index.js`, `client.js`, and `app.js`.
+
+## GitHub Actions
+
+Three workflows live under `.github/workflows/`.
+
+### Pull request tests
+
+`pr-tests.yml` runs for pull requests targeting `main` when they are opened, reopened, updated, or marked ready for review.
+
+The workflow:
+
+1. Checks out the pull request revision.
+2. Installs pnpm 10 and Node.js 22.19.0.
+3. Runs `pnpm install --frozen-lockfile`.
+4. Runs `pnpm run build`.
+5. Runs `pnpm test`.
+
+A per-PR concurrency group cancels obsolete runs after a newer commit arrives.
+
+### Main branch tests
+
+`main-tests.yml` runs for every push to `main`, including direct commits and merged pull requests. It executes the same frozen installation, build validation, and full test suite.
+
+### npm publishing
+
+`npm-publish.yml` runs for pushed tags matching the broad GitHub pattern `v*.*.*`. The job then validates the tag strictly before publishing.
+
+Accepted forms include:
+
+```text
+v0.4.0
+v0.4.0-rc1
+v0.4.0-rc.2
+```
+
+The tag without the leading `v` must exactly equal `package.json.version`. A mismatch fails before installation or publication.
+
+| Version | Git tag | npm dist-tag |
+|---|---|---|
+| `0.4.0-rc1` | `v0.4.0-rc1` | `next` |
+| `0.4.0` | `v0.4.0` | `latest` |
+
+Every release tag reruns installation, build validation, and the complete test suite before calling `pnpm publish`.
+
+## Configure npm authentication
+
+Create a GitHub Actions repository secret named `NPM_TOKEN` in the repository where the tag workflow will run:
+
+```powershell
+gh secret set NPM_TOKEN --repo OWNER/dsh-synapse
+```
+
+The token's npm account must have permission to create or publish the public, unscoped `dsh-synapse` package. The workflow passes the secret to the publish step as `NODE_AUTH_TOKEN`; pull request and ordinary test workflows never receive it.
+
+## Release checklist
+
+1. Confirm the full test suite passes on `main`.
+2. Update `package.json.version` to the intended release version.
+3. Commit and merge the version change.
+4. Create a matching tag on that commit.
+5. Push the tag.
+6. Confirm the **Publish to npm** workflow passes.
+7. Verify the npm dist-tag:
+   - prerelease versions use `next`
+   - stable versions use `latest`
+
+Example stable release:
+
+```powershell
+# package.json already contains 0.4.0
+git tag v0.4.0
+git push origin v0.4.0
+```
+
+Example prerelease:
+
+```powershell
+# package.json already contains 0.4.0-rc1
+git tag v0.4.0-rc1
+git push origin v0.4.0-rc1
+```
+
+## Publication failure conditions
+
+The publish job stops without publishing when:
+
+- the tag is not a supported version form;
+- the tag and `package.json.version` differ;
+- frozen installation fails;
+- syntax validation or tests fail;
+- `NPM_TOKEN` is missing, expired, or lacks package permissions;
+- npm rejects the package name or an already-published version.
+
+## Documentation
+
+- [Chinese user guide](zh-CN/README.md)
+- [English user guide](en/README.md)
+- [Architecture and runtime boundaries](architecture.md)
+- [Project overview](../README.md)